
#include "bacula_template.inc" title="Console Restore Command" num=8

<h1>The Bacula Console Restore Command</h1>

<h2>General</h2>
Below, we will discuss restoring files with the Console
<b>Restore</b> command, which is the recommended way of doing it.
However, there is a standalone program named <b>bextract</b>,
which also permits restoring files.  For more information on this
program, please see the <a href="progs.html#bextract">Bacula
Utility Programs</a> chapter of this manual.  You will also
want to look at the <b>bls</b> 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 <b>bscan</b>, documented in the same
<a href="progs.html#bextract">Bacula Utility
Programs</a> chapter.
<p>
In general, to restore a file or a set of files, you must run a
<b>restore</b> job.  That is a job with <b>Type = Restore</b>.
As a consequence, you will need a predefined <b>restore</b> job
in your <b>bacula-dir.conf</b> (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
<b>restore</b> command, explained below, they will be automatically set
for you.
<p>
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.
<b>Bacula</b> 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.

<a name="Example"></a>
<h2>The Restore Command</h2>
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.
<p>
This is accomplished using the <b>restore</b> 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 <b>restore</b> program's
interactive file selection mode.
<p>Within the Console program, after entering the <b>restore</b>
command, you are presented with the following selection prompt:
     <pre>
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): 
     </pre>
     <ul><li>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). </li>          
     <li>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. </li>
     <li>Item 3 allows you the enter a list of comma separated JobIds whose
         files will be put into the directory tree. </li> 
     <li>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.</li>
     <li>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.</li>
     <li>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.</li>
     <li>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 (&lt;) 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.
     <li>Item 8 allows you to specify a date and time before
         entering the filenames. See Item 7 above for more
         details.</li>
     <li>Item 9 allows you to cancel the restore command.</li>
     </ul>
<p>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:
     <pre>
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):
     </pre>
     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 <b>Rufus</b> to select the Client.  Then
     Bacula needs to know what FileSet is to be restored, so it
     prompts with:
     <pre>
The defined FileSet resources are:
     1: Full Set
     2: Kerns Files
Select FileSet resource (1-2): 
     </pre>
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.
<p>At this point,
<b>Bacula</b> 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:
<font size=-2>
<pre>
+-------+------+----------+-------------+-------------+------+-------+------------+
| 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: /
$
</pre>
</font>

Depending on the number of <b>JobFiles</b> for each JobId, the 
<b>Building directory tree ..."</b> can take a bit of time.
<p>
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.

<p>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 (<b>cwd</b>) 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. 
<p>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
<b>1792,1797,1798</b> we would have arrived at the same point.
<p>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).

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

     <pre>
  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
     </pre>

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

<p>If you do not enter the above mentioned <b>mark *</b> command, you
will start with an empty slate.  Now 
you can simply start looking at the tree and <b>mark</b> 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 <b>ls</b> or <b>dir</b> commands to see what files are actually
selected.  Any selected file has its name preceded by an asterisk.

<p>To check what is marked or not marked, enter the <b>count</b> command,
which displays:

     <pre>
128401 total files. 128401 marked to be restored.
     </pre>

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
<b>done</b> command, Bacula prints:
     <pre>
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): 
    </pre>
Please examine each of the items very carefully to make sure
that they are correct. In particular, look at <b>Where</b>,
which tells you where in the directory structure the files
will be restored, and <b>Client</b>, 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.             
<p>

The above assumes that you have defined a <b>Restore</b> 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.
<p>An example Restore Job resource definition is given below.

<p>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 <b>FileSet</b> is shown, it will be ignored in
restore. The restore will choose the files to be restored either
by reading the <b>Bootstrap</b> file, or if not specified, it
will restore all files associated with the specified 
backup <b>JobId</b> (i.e. the JobId of the Job that      
originally backed up the files).

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

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

<h2>Selecting Files by Filename</h2>
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.  
<p>
To enter the files, after the <b>restore</b>, you
select item number 7 from the prompt list:
<pre>
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
</pre>
which then prompts you with for the client name:
<pre>
Defined Clients:
     1: Timmy
     2: Tibs
     3: Rufus
Select the Client (1-3): 3
</pre>
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:
<pre>
Enter filename:
</pre>
At this point, you can enter the full path and filename
<pre>
Enter filename: /home/kern/bacula/k/Makefile.in
Enter filename: 
</pre>
as you can see, it took the filename.  If Bacula
cannot find a copy of the file, it prints the 
following:
<pre>
Enter filename: junk filename
No database record found for: junk filename
Enter filename: 
</pre>
If you want Bacula to read the filenames from a file,
you simply precede the filename with a less-than symbol
(&lt;). 
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:
<pre>
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): 
</pre>
It is possible to automate the selection by file by putting
your list of files in say <b>/tmp/file-list</b>, then
using the following command:
<pre>
restore client=Rufus file=&lt;/tmp/file-list
</pre>

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.

<a name="CommandArguments"></a>
<h2>Command Line Arguments</h2>
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:

<pre>
restore client=Rufus select current all done yes
</pre>
The <b>client=Rufus</b> specification will automatically select Rufus
as the client, the <b>current</b> tells Bacula that you want to restore
the system to the most current state possible, and the <b>yes</b> suppresses
the final <b>yes/mod/no</b> prompt and simply runs the restore.
<p>The full list of possible command line arguments are:
<ul>
  <li><b>all</b> -- select all Files to be restored.</li>
  <li><b>select</b> -- use the tree selection method.</li>
  <li><b>done</b> -- do not prompt the user in tree mode.</li>
  <li><b>current</b> -- automatically select the most current set of
         backups for the specified client.</li>
  <li><b>client=xxxx</b> -- select the specified client.</li>
  <li><b>jobid=nnn</b> -- specify a JobId or comma separated list of
         JobIds to be restored.</li>
  <li><b>before=YYYY-MM-DD HH:MM:SS</b> -- 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 <b>current</b> 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. </li>
   <li><b>file=filename</b> -- specify a filename to be restored. You
         must specify the full path and filename. Prefixing the entry   
         with a less-than sign (&lt;) 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. </li>
   <li><b>jobid=nnn</b> -- specify a JobId to be restored. </li>
   <li><b>pool=pool-name</b> -- 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.</li>
   <li><b>yes</b> -- automatically run the restore without prompting
         for modifications (most useful in batch scripts).</li>
</ul>


<a name="Windows"></a>
<h2>Restoring on Windows</h2>
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.

<p>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).

<h2>Restoring Files Can Be Slow</h2>
Restoring files is generally <b>much</b> 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.  
<p>
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.
<p>
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.
<p>
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.
<p>
For all the above reasons the restore process is generally
much slower than backing up. 


<h2>Example Restore Job Resource</h2>
<pre>
Job {
  Name = "RestoreFiles"
  Type = Restore
  Client = Any-client 
  FileSet = "Any-FileSet" 
  Storage = Any-storage
  Where = /tmp/bacula-restores
  Messages = Standard
  Pool = Default
}
</pre>
If <b>Where</b> is not specified, the default location for restoring
files will be their original locations.

<a name="Selection"></a>
<h2>File Selection Commands</h2>
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 (<b>$</b>) 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 <b>cd</b> 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: <b>cd /</b>
and <b>mark *</b>. Otherwise proceed to select the files you wish to restore by marking them
with the <b>mark</b> command. The available commands are:

<dl>
  <dt>cd</dt><dd>The <b>cd</b> command changes the current directory to
    the argument specified. It operates much like the Unix <b>cd</b> command.
    Wildcard specifications are not permitted.
    <p>
    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 <b>cd c:</b> or
    possibly in some cases a <b>cd C:</b> (note upper case) 
    to get down to the first directory.
  </dd>
  <dt>dir</dt><dd>The <b>dir</b> command is similar to the <b>ls</b> command,
    except that it prints it in long format (all details). This command 
    can be a bit slower than the <b>ls</b> command because it must access
    the catalog database for the detailed information for each file.
  </dd>
  <dt>estimate</dt><dd>The <b>estimate</b> 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.
    </dd>
  <dt>find</dt><dd>The <b>find</b> 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
     <b>find / -name arg</b>.
  </dd>
  <dt>ls</dt><dd>The <b>ls</b> command produces a listing of all the files
    contained in the current directory much like the Unix <b>ls</b> 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 (<b>*</b>).  Directory names
    will be terminated with a forward slash (<b>/</b>) to distinguish them
    from filenames.
  </dd>
  <dt>lsmark</dt><dd>The <b>lsmark</b> command is the same as the 
   <b>ls</b> except that it will print only those files marked for
   extraction. The other distinction is that it will recursively
   descend into any directory selected. </dd>
  <dt>mark</dt><dd>The <b>mark</b> 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 (<b>*</b>) in the output produced by the
    <b>ls</b> or <b>dir</b> 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 <b>mark</b> command works
    on the current and lower directories but does not touch higher level
    directories.
    <p>
    After executing the <b>mark</b> command, it will print a brief summary:
    <pre>
    No files marked.
    </pre>
    If no files were marked, or:
    <pre>
    nn files marked.
    </pre>
    if some files are marked.

  </dd>
  <dt>unmark</dt><dd>The <b>unmark</b> is identical to the <b>mark</b>
    command, except that it unmarks the specified file or files so that
    they will not be restored. Note: the <b>unmark</b> command works from 
    the current directory, so it does not unmark any files at a higher
    level. First do a <b>cd /</b> before the <b>unmark *</b> command if
    you want to unmark everything.
  </dd>
  <dt>pwd</dt><dd>The <b>pwd</b> command prints the current working 
    directory. It accepts no arguments.
  </dd>
  <dt>count</dt><dd>The <b>count</b> command prints the total files in the
    directory tree and the number of files marked to be restored.
  </dd>
  <dt>done</dt><dd>This command terminates file selection mode.
  </dd>
  <dt>exit</dt><dd>This command terminates file selection mode (the same as
     done).
  </dd>
  <dt>quit</dt><dd>This command terminates the file selection and does
      not run the restore job.</dd>
  <dt>help</dt><dd>This command prints a summary of the commands available.
  </dd>
  <dt>?</dt><dd>This command is the same as the <b>help</b> command.
  </dd>
</dl>

<page_prev name="Critical Items Before Going Production" url="critical.html">
<page_next name="Maintaining Your Catalog" url="catmaintenance.html">
