Next: Catalog Maintenance Up: Bacula User's Guide Previous: Bacula Console Contents Index
Subsections

- General
- The Restore Command
- Selecting Files by Filename
- Command Line Arguments
- Restoring Directory Attributes
- Restoring on Windows
- Restoring Files Can Be Slow
- Problems Restoring Files
- Example Restore Job Resource
- File Selection Commands

#
The Bacula Console Restore Command

## General

Below, we will discuss restoring files with the Console Restore command, which is the recommended way of doing it. However, there is a standalone program named bextract, which also permits restoring files. For more information on this program, please see the Bacula Utility Programs chapter of this manual. You will also want to look at the bls program in the same chapter, which allows you to list the contents of your Volumes. Finally, if you have an old Volume that is no longer in the catalog, you can restore the catalog entries using the program named bscan, documented in the same Bacula Utility Programs chapter.

In general, to restore a file or a set of files, you must run a restore job. That is a job with Type = Restore. As a consequence, you will need a predefined restore job in your bacula-dir.conf (Director's config) file. The exact parameters (Client, FileSet, ...) that you define are not important as you can either modify them manually before running the job or if you use the restore command, explained below, they will be automatically set for you.

Since Bacula is a network backup program, you must be aware that when you restore files, it is up to you to ensure that you or Bacula have selected the correct Client and the correct hard disk location for restoring those files. Bacula will quite willingly backup client A, and restore it by sending the files to a different directory on client B. Normally, you will want to avoid this, but assuming the operating systems are not too different in their file structures, this should work perfectly well, if so desired.

## The Restore Command

Since Bacula maintains a catalog of your files and on which Volumes (disk or tape), they are stored, it can do most of the bookkeeping work, allowing you simply to specify what kind of restore you want (current, before a particular date), and what files to restore. Bacula will then do the rest.

This is accomplished using the restore command in the Console. First you select the kind of restore you want, then Bacula Once the JobIds are selected, the File records for those Jobs are placed in an internal Bacula directory tree, and the restore enters a file selection mode that allows you to interactively walk up and down the file tree selecting individual files to be restored. This mode is somewhat similar to the standard Unix restore program's interactive file selection mode.

Within the Console program, after entering the restore command, you are presented with the following selection prompt:

    First you select one or more JobIds that contain files
    to be restored. You will be presented several methods
    of specifying the JobIds. Then you will be allowed to
    select which files from those JobIds are to be restored.
    To select the JobIds, you have the following choices:
         1: List last 20 Jobs run
         2: List Jobs where a given File is saved
         3: Enter list of JobIds to select
         4: Enter SQL list command
         5: Select the most recent backup for a client
         6: Select backup for a client before a specified time
         7: Enter a list of files to restore
         8: Enter a list of files to restore before a specified time
         9: Cancel
    Select item:  (1-9):

- Item 1 will list the last 20 jobs run. If you find the Job you want, you can then select item 3 and enter its JobId(s).
- Item 2 will list all the Jobs where a specified file is saved. If you find the Job you want, you can then select item 3 and enter the JobId.
- Item 3 allows you the enter a list of comma separated JobIds whose files will be put into the directory tree.
- Item 4 allows you to enter any arbitrary SQL command. This is probably the most primitive way of finding the desired JobIds, but at the same time, the most flexible. Once you have found the JobId(s), you can select item 3 and enter them.
- Item 5 will automatically select the most recent Full backup and all subsequent incremental and differential backups for a specified Client. These are the Jobs and Files which if reloaded will restore your system to the most current saved state. It automatically enters the JobIds found into the directory tree. This is probably the most convenient of all the above options to use if you wish to restore a selected Client to its most recent state.
- Item 6 allows you to specify a date and time then Bacula will automatically select the most recent Full backup and all subsequent incremental and differential backups that started before the specified date and time.
- Item 7 allows you to specify one or more filenames (complete path required) to be restored. Each filename is entered one at a time or if you prefix a filename with the less-than symbol (<) Bacula will read that file and assume it is a list of filenames to be restored. The filename entry mode is terminated by entering a blank line.
- Item 8 allows you to specify a date and time before entering the filenames. See Item 7 above for more details.
- Item 9 allows you to cancel the restore command.

As an example, suppose that we select item 5 (restore to most recent state). It will then ask for the desired Client, which on my system, will print all the Clients found in the database as follows:

    Defined clients:
         1: Rufus
         2: Matou
         3: Polymatou
         4: Minimatou
         5: Minou
         6: MatouVerify
         7: PmatouVerify
         8: RufusVerify
         9: Watchdog
    Select Client (File daemon) resource (1-9):

You will probably have fare fewer Clients than this example, and if you have only one Client, it will be automatically selected, but in this case, I enter Rufus to select the Client. Then Bacula needs to know what FileSet is to be restored, so it prompts with:

    The defined FileSet resources are:
         1: Full Set
         2: Kerns Files
    Select FileSet resource (1-2):

I choose item 1, which is my full backup. Normally, you will only have a single FileSet for each Job, and if your machines are similar (all Linux) you may only have one FileSet for all your Clients.

At this point, Bacula has all the information it needs to find the most recent set of backups. It will then query the database, which may take a bit of time, and it will come up with something like the following. Note, some of the columns are truncated here for presentation:

    +-------+------+----------+-------------+-------------+------+-------+------------+
    | JobId | Levl | JobFiles | StartTime   | VolumeName  | File | SesId | VolSesTime |
    +-------+------+----------+-------------+-------------+------+-------+------------+
    | 1,792 | F    |  128,374 | 08-03 01:58 | DLT-19Jul02 |   67 |    18 | 1028042998 |
    | 1,792 | F    |  128,374 | 08-03 01:58 | DLT-04Aug02 |    0 |    18 | 1028042998 |
    | 1,797 | I    |      254 | 08-04 13:53 | DLT-04Aug02 |    5 |    23 | 1028042998 |
    | 1,798 | I    |       15 | 08-05 01:05 | DLT-04Aug02 |    6 |    24 | 1028042998 |
    +-------+------+----------+-------------+-------------+------+-------+------------+
    You have selected the following JobId: 1792,1792,1797
    Building directory tree for JobId 1792 ...
    Building directory tree for JobId 1797 ...
    Building directory tree for JobId 1798 ...
    cwd is: /
    $

Depending on the number of JobFiles for each JobId, the Building directory tree ...`` can take a bit of time.

In our example, Bacula found four Jobs that comprise the most recent backup of the specified Client and FileSet. Two of the Jobs have the same JobId because that Job wrote on two different Volumes. The third Job was an incremental backup to the previous Full backup, and it only saved 254 Files compared to 128,374 for the Full backup. The fourth Job was also an incremental backup that saved 15 files.

Next Bacula entered those Jobs into the directory tree, with no files marked to be restored as a default, tells you how many files are in the tree, and tells you what the current working directory (cwd) is /. Finally, Bacula prompts with the dollar sign ($) to indicate that you may enter commands to move around the directory tree and to select files.

Instead of choosing item 5 on the first menu (Select the most recent backup for a client), if we had chosen item 3 (Enter list of JobIds to select) and we had entered the JobIds 1792,1797,1798 we would have arrived at the same point.

One point to note if you are manually entering JobIds is that you must enter them in the order they were run (generally in increasing JobId order). If you enter them out of order and the same file was saved in two or more of the Jobs, you may end up with an old version of that file (i.e. not the most recent).

While in file selection mode, you can enter help or a question mark (?) to produce a summary of the available commands:

      Command    Description
      =======    ===========
      cd         change current directory
      count      count marked files in and below the cd
      dir        list current directory
      done       leave file selection mode
      estimate   estimate restore size
      exit       exit = done
      find       find files -- wildcards allowed
      help       print help
      ls         list current directory -- wildcards allowed
      lsmark     list the marked files in and below the cd
      mark       mark file to be restored
      markdir    mark directory entry to be restored -- nonrecursive
      pwd        print current working directory
      unmark     unmark file to be restored
      unmarkdir  unmark directory -- no recursion
      quit       quit
      ?          print help

As a default no files have been selected for restore. If you want to restore everything, at this point, you should enter mark *, and then done and Bacula will write the bootstrap records to a file and request your approval to start a restore job.

If you do not enter the above mentioned mark * command, you will start with an empty slate. Now you can simply start looking at the tree and mark particular files or directories if you want restored. It is easy to make a mistake in specifying a file to mark or unmark, and Bacula's error handling is not perfect, so please check your work by using the ls or dir commands to see what files are actually selected. Any selected file has its name preceded by an asterisk.

To check what is marked or not marked, enter the count command, which displays:

    128401 total files. 128401 marked to be restored.

Each of the above commands will be described in more detail in the next section. We continue with the above example, having accepted to restore all files as Bacula set by default. On entering the done command, Bacula prints:

    Bootstrap records written to /home/kern/bacula/working/restore.bsr
    The restore job will require the following Volumes:

       DLT-19Jul02
       DLT-04Aug02
    128401 files selected to restore.
    Run Restore job
    JobName:    kernsrestore
    Bootstrap:  /home/kern/bacula/working/restore.bsr
    Where:      /tmp/bacula-restores
    Replace:    always
    FileSet:    Kerns Files
    Client:     Rufus
    Storage:    SDT-10000
    JobId:      *None*
    OK to run? (yes/mod/no):

Please examine each of the items very carefully to make sure that they are correct. In particular, look at Where, which tells you where in the directory structure the files will be restored, and Client, which tells you which client will receive the files. These items will not always be completed with the correct values depending on which of the restore options you chose.

The above assumes that you have defined a Restore Job resource in your Director's configuration file. Normally, you will only need one Restore Job resource definition because by its nature, restoring is a manual operation, and using the Console interface, you will be able to modify the Restore Job to do what you want.

An example Restore Job resource definition is given below.

Returning to the above example, you should verify that the Client name is correct before running the Job. However, you may want to modify some of the parameters of the restore job. For example, in addition to checking the Client it is wise to check that the Storage device chosen by Bacula is indeed correct. Although the FileSet is shown, it will be ignored in restore. The restore will choose the files to be restored either by reading the Bootstrap file, or if not specified, it will restore all files associated with the specified backup JobId (i.e. the JobId of the Job that originally backed up the files).

Finally before running the job, please note that the default location for restoring files is not their original locations, rather the directory /tmp/bacula-restores. You can change this default by modifying your bacula-dir.conf file, or you can modify it using the mod option. If you want to restore the files to their original location, you must have Where set to nothing or to the root, i.e. /.

If you now enter yes, Bacula will run the restore Job. The Storage daemon will first request Volume DLT-19Jul02 and after the appropriate files have been restored from that volume, it will request Volume DLT-04Aug02.

## Selecting Files by Filename

If you have a small number of files to restore, and you know the filenames, you can either put the list of filenames in a file to be read by Bacula, or you can enter the names one at a time. The filenames must include the full path and filename. No wild cards are used.

To enter the files, after the restore, you select item number 7 from the prompt list:

    To select the JobIds, you have the following choices:
         1: List last 20 Jobs run
         2: List Jobs where a given File is saved
         3: Enter list of JobIds to select
         4: Enter SQL list command
         5: Select the most recent backup for a client
         6: Select backup for a client before a specified time
         7: Enter a list of files to restore
         8: Enter a list of files to restore before a specified time
         9: Cancel
    Select item:  (1-9): 7

which then prompts you with for the client name:

    Defined Clients:
         1: Timmy
         2: Tibs
         3: Rufus
    Select the Client (1-3): 3

Of course, your client list will be different, and if you have only one client, it will be automatically selected. And finally, Bacula requests you to enter a filename:

    Enter filename:

At this point, you can enter the full path and filename

    Enter filename: /home/kern/bacula/k/Makefile.in
    Enter filename:

as you can see, it took the filename. If Bacula cannot find a copy of the file, it prints the following:

    Enter filename: junk filename
    No database record found for: junk filename
    Enter filename:

If you want Bacula to read the filenames from a file, you simply precede the filename with a less-than symbol (<). When you have entered all the filenames, you enter a blank line, and Bacula will write the bootstrap file, tell you what tapes will be used, and propose a Restore job to be run:

    Enter filename:
    Automatically selected Storage: DDS-4
    Bootstrap records written to /home/kern/bacula/working/restore.bsr
    The restore job will require the following Volumes:

       test1
    1 file selected to restore.
    Run Restore job
    JobName:    kernsrestore
    Bootstrap:  /home/kern/bacula/working/restore.bsr
    Where:      /tmp/bacula-restores
    Replace:    always
    FileSet:    Kerns Files
    Client:     Rufus
    Storage:    DDS-4
    When:       2003-09-11 10:20:53
    Priority:   10
    OK to run? (yes/mod/no):

It is possible to automate the selection by file by putting your list of files in say /tmp/file-list, then using the following command:

    restore client=Rufus file=</tmp/file-list

If in modifying the parameters for the Run Restore job, you find that Bacula asks you to enter a Job number, this is because you have no yet specified either a Job number or a Bootstrap file. Simply entering zero will allow you to continue and to select another option to be modified.

## Command Line Arguments

If all the above sounds complicated, you will probably agree that it really isn't after trying it a few times. It is possible to do everything that was shown above, with the exception of selecting the FileSet, by using command line arguments with a single command by entering:

    restore client=Rufus select current all done yes

The client=Rufus specification will automatically select Rufus as the client, the current tells Bacula that you want to restore the system to the most current state possible, and the yes suppresses the final yes/mod/no prompt and simply runs the restore.

The full list of possible command line arguments are:

- all - select all Files to be restored.
- select - use the tree selection method.
- done - do not prompt the user in tree mode.
- current - automatically select the most current set of backups for the specified client.
- client=xxxx - select the specified client.
- jobid=nnn - specify a JobId or comma separated list of JobIds to be restored.
- before=YYYY-MM-DD HH:MM:SS - specify a date and time to which the system should be restored. Only Jobs started before the specified date/time will be selected, and as is the case for current Bacula will automatically find the most recent prior Full save and all Differential and Incremental saves run before the date you specify. Note, this command is not too user friendly in that you must specify the date/time exactly as shown.
- file=filename - specify a filename to be restored. You must specify the full path and filename. Prefixing the entry with a less-than sign (<) will cause Bacula to assume that the filename is on your system and contains a list of files to be restored. Bacula will thus read the list from that file. Multiple file=xxx specifications may be specified on the command line.
- jobid=nnn - specify a JobId to be restored.
- pool=pool-name - specify a Pool name to be used for selection of Volumes when specifying options 5 and 6 (restore current system, and restore current system before given date). This permits you to have several Pools, possibly one offsite, and to select the Pool to be used for restoring.
- yes - automatically run the restore without prompting for modifications (most useful in batch scripts).

## Restoring Directory Attributes

Depending how you do the restore, you may or may not get the directory entries back to their original state. Here are a few of the problems you can encounter, and for same machine restores, how to avoid them.

- You backed up on one machine and are restoring to another that is either a different OS or doesn't have the same users/groups defined. Bacula does the best it can in these situations.
- You are restoring into a directory that is already created and has file creation restrictions. Bacula tries to reset everything but without walking up the full chain of directories and modifying them all during the restore, which Bacula does and will not do, getting permissions back correctly in this situation depends to a large extent on your OS.
- You selected one or more files in a directory, but did not select the directory entry to be restored. In that case, if the directory is not on disk Bacula simply creates the directory with some default attributes which may not be the same as the original. If you do not select a directory and all its contents to be restored, you can still select items within the directory to be restored by individually marking those files, but in that case, you should individually use the ''markdir`` command to select all higher level directory entries (one at a time) to be restored if you want the directory entries properly restored.

## Restoring on Windows

If you are restoring on WinNT/2K/XP systems, Bacula will restore the files with the original ownerships and permissions as would be expected. This is also true if you are restoring those files to an alternate directory (using the Where option in restore). However, if the alternate directory does not already exist, the Bacula File daemon (Client) will create it, and since the File daemon runs under the SYSTEM account, the directory will be created with SYSTEM ownership and permissions. In this case, you may have problems accessing the newly restored files.

To avoid this problem, you can create the alternate directory before doing the restore. Bacula will not change the ownership and permissions of the directory if it is already created as long as it is not one of the directories being restored (i.e. written to tape).

## Restoring Files Can Be Slow

Restoring files is generally much slower than backing it up for several reasons. The first is that during a backup the tape is normally already positioned and Bacula need only write. On the other hand, because restoring files is done so rarely, Bacula keeps only the he start file and block on the tape for the whole job rather than on a file by file basis which would use quite a lot of space in the catalog.

Bacula versions 1.31a and older would seek to the first file on the first tape, then sequentially search the tape for the specified files. If you were doing a full restore, this is OK, but if you want to restore one or two files, the process could be quite long.

This deficiency has been corrected in version 1.32. The consequence is that Bacula will forward space to the correct file mark on the tape for the Job, then forward space to the correct block, and finally sequentially read each record until it gets to the correct one(s) for the file or files you want to restore. Once the desired files are restored, Bacula will stop reading the tape. For restoring a small number of files, version 1.32 and greater are hundreds of times faster than previous versions.

Finally, instead of just reading a file for backup, during the restore, Bacula must create the file, and the operating system must allocate disk space for the file as Bacula is restoring it.

For all the above reasons the restore process is generally much slower than backing up.

## Problems Restoring Files

The most frequent problems users have restoring files are error messages such as:

    04-Jan 00:33 z217-sd: RestoreFiles.2005-01-04_00.31.04 Error:
    block.c:868 Volume data error at 20:0! Short block of 512 bytes on
    device /dev/tape discarded.

or

    04-Jan 00:33 z217-sd: RestoreFiles.2005-01-04_00.31.04 Error:
    block.c:264 Volume data error at 20:0! Wanted ID: "BB02", got ".".
    Buffer discarded.

Both these kinds of messages indicate that you were probably running your tape drive in fixed block mode rather than variable block mode. Fixed block mode will work with any program that reads tapes sequentially such as tar, but Bacula repositions the tape on a block basis when restoring files because this will speed up the restore by orders of magnitude when only a few files are restore. There are several ways that you can attempt to recover from this unfortunate situation.

Try the following things each separately, and reset your Device resource to what it is now after each individual test:

1. Set ''Block Positioning = no`` in your Device resource and try the restore. This is a new directive and untested.
2. Set ''Minimum Block Size = 512`` and ''Maximum Block Size = 512`` and try the restore. Again send me the full job report output. If you are able to determine the block size your drive was previously using, you should try that size if 512 does not work.
3. Try editing the restore.bsr file at the Run xxx yes/mod/no prompt before starting the restore job and remove all the VolBlock statements. These are what causes Bacula to reposition the tape, and where problems occur if you have a fixed block size set for your drive. The VolFile commands also cause repositioning, but this will work regardless of the block size.
4. Use bextract to extract the files you want - it reads the Volume sequentially if you use the include list feature, or if you use a .bsr file, but remove all the VolBlock statements after the .bsr file is created (at the Run yes/mod/no) prompt but before you start the restore.

## Example Restore Job Resource

    Job {
      Name = "RestoreFiles"
      Type = Restore
      Client = Any-client
      FileSet = "Any-FileSet"
      Storage = Any-storage
      Where = /tmp/bacula-restores
      Messages = Standard
      Pool = Default
    }

If Where is not specified, the default location for restoring files will be their original locations.

## File Selection Commands

After you have selected the Jobs to be restored and Bacula has created the in-memory directory tree, you will enter file selection mode as indicated by the dollar sign ($) prompt. While in this mode, you may use the commands listed above. The basic idea is to move up and down the in memory directory structure with the cd command much as you normally do on the system. Once you are in a directory, you may select the files that you want restored. As a default no files are marked to be restored. If you wish to start with all files, simply enter: cd / and mark *. Otherwise proceed to select the files you wish to restore by marking them with the mark command. The available commands are:

cd
  The cd command changes the current directory to the argument specified. It operates much like the Unix cd command. Wildcard specifications are not permitted.

  Note, on Windows systems, the various drives (c:, d:, ...) are treated like a directory within the file tree while in the file selection mode. As a consequence, you must do a cd c: or possibly in some cases a cd C: (note upper case) to get down to the first directory.

dir
  The dir command is similar to the ls command, except that it prints it in long format (all details). This command can be a bit slower than the ls command because it must access the catalog database for the detailed information for each file.

estimate
  The estimate command prints a summary of the total files in the tree, how many are marked to be restored, and an estimate of the number of bytes to be restored. This can be useful if you are short on disk space on the machine where the files will be restored.

find
  The find command accepts one or more arguments and displays all files in the tree that match that argument. The argument may have wildcards. It is somewhat similar to the Unix command find / -name arg.

ls
  The ls command produces a listing of all the files contained in the current directory much like the Unix ls command. You may specify an argument containing wildcards, in which case only those files will be listed. Any file that is marked to be restored will have its name preceded by an asterisk (*). Directory names will be terminated with a forward slash (/) to distinguish them from filenames.

lsmark
  The lsmark command is the same as the ls except that it will print only those files marked for extraction. The other distinction is that it will recursively descend into any directory selected.

mark
  The mark command allows you to mark files to be restored. It takes a single argument which is the filename or directory name in the current directory to be marked for extraction. The argument may be a wildcard specification, in which case all files that match in the current directory are marked to be restored. If the argument matches a directory rather than a file, then the directory and all files contained in that directory (recursively) are marked to be restored. Any marked file will have its name preceded with an asterisk (*) in the output produced by the ls or dir commands. Note, supplying a full path on the mark command does not work as expected to select a file or directory in the current directory. Also, the mark command works on the current and lower directories but does not touch higher level directories.

  After executing the mark command, it will print a brief summary:

          No files marked.

  If no files were marked, or:

          nn files marked.

  if some files are marked.

unmark
  The unmark is identical to the mark command, except that it unmarks the specified file or files so that they will not be restored. Note: the unmark command works from the current directory, so it does not unmark any files at a higher level. First do a cd / before the unmark * command if you want to unmark everything.

pwd
  The pwd command prints the current working directory. It accepts no arguments.

count
  The count command prints the total files in the directory tree and the number of files marked to be restored.

done
  This command terminates file selection mode.

exit
  This command terminates file selection mode (the same as done).

quit
  This command terminates the file selection and does not run the restore job.

help
  This command prints a summary of the commands available.

?
  This command is the same as the help command.

Next: Catalog Maintenance Up: Bacula User's Guide Previous: Bacula Console Contents Index