
#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. There is also a
program named <b>bscan</b> documented in the same
<a href="progs.html#bextract">Bacula Utility
Programs</a> chapter that permits restoring a catalog
database from tapes.
<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
should have 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 <b>Bacula</b> is a network backup program, you must 
be aware that when you restore files, it is up to you to
ensure that you or <b>Bacula</b> have selected the correct
Client and the correct 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.

<h2>The Restore Command</h2>
   The restore command in the Console program allows you to first select one
     or more Jobs (JobIds) to be restored using various methods,
     explained below. Once the JobIds are selected, the File records
     for those Jobs are placed in an internal <b>Bacula</b> 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: Cancel
Select item:  (1-6): 
     </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 cancel the restore command.</li>
     </ul>
     <p>As an example, suppose that we select item 5. It will then ask
     for the desired Client, which on my system, will print the
     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>
     I enter <b>Rufus</b>, and <b>Bacula</b> needs to know what FileSet
     is to be restored, so it prompts with:
     <pre>
The defined FileSet resources are:
     1: Full Set      i7/6gj+3j/QTsV+Ukx/xsB
     2: Kerns Files   qi@s8kuw7/SRvM@Vxm/vaN
Select FileSet resource (1-2): 
     </pre>
     To which, I choose item 1, which is my full backup. Note, the items
     that follow your FileSet names are an MD5 signature of the contents
     of the FileSet. In fact, the FileSet ID will change each time you
     edit the FileSet definition. As a consequence, it is possible to have
     two &quot;Full Set&quot; entries above, but each one will have a different
     MD5 signature. You are urged to change your FileSet name every time you
     change the contents to avoid any confusion of the name.
     <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:
     <pre>
     <font size=-2>
+-------+------+----------+------------------+-------------+---------+----------+------------+
| JobId | Levl | JobFiles | StartTime        | VolumeName  | StrtFil | VolSesId | VolSesTime |
+-------+------+----------+------------------+-------------+---------+----------+------------+
| 1,792 | F    |  128,374 | 2002-08-03 01:58 | DLT-19Jul02 |      67 |       18 | 1028042998 |
| 1,792 | F    |  128,374 | 2002-08-03 01:58 | DLT-04Aug02 |       0 |       18 | 1028042998 |
| 1,797 | I    |      254 | 2002-08-04 13:53 | DLT-04Aug02 |       5 |       23 | 1028042998 |
| 1,798 | I    |       15 | 2002-08-05 01:05 | DLT-04Aug02 |       6 |       24 | 1028042998 |
+-------+------+----------+------------------+-------------+---------+----------+------------+
</font>
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>
     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,  <b>Bacula</b> found four Jobs that comprise the most
     recent backup of the specified Client and FileSet. Two of the Jobs have the
     same JobId because it 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 <b>Bacula</b> entered those Jobs into the directory tree,
     and as a default marks all files to be restored, tells you how many files
     are in the tree then
     tells you that the current working directory (<b>cwd</b>) is /.
     Finally, <b>Bacula</b> 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>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
  =======    ===========
  mark       mark file for restoration
  unmark     unmark file for restoration
  cd         change current directory
  pwd        print current working directory
  ls         list current directory
  dir        list current directory
  count      count marked files
  find       find files
  done       leave file selection mode
  exit       exit = done
  help       print help
  ?          print help
     </pre>

     As a default <b>Bacula</b> has selected all the files in the directory
     tree. If you want to do a full restore, simply enter <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 instead, you wish to start with an empty slate (i.e. no jobs
     marked for restoration), simply enter <b>unmark *</b>.  Otherwise,
     you can simply start looking at the tree and <b>unmark</b> particular
     files or directories if you do not want them restored. 

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

     <pre>
128401 total files. 128401 marked for restoration.
     </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 <b>Bacula</b> set by default. On entering the
     <b>done</b> command, <b>Bacula</b> 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 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 <b>Bacula</b> 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 is 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>, <b>Bacula</b> 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>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.

<h2>File Selection Commands</h2>
After you have selected the Jobs to be restored and <b>Bacula</b> 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 select the
files that you want restored. As a default all files are marked for
restoration. If you wish to start with no files, simply enter: <b>unmark *</b>.
Then proceed to select the files you wish to restore by marking them
with the <b>mark</b> command. The available commands are:

<dl>
  <dt>mark</dt><dd>The <b>mark</b> command allows you to mark files
    for restoration. It takes a single argument which is the filename
    to be marked. The argument may be a wildcard specification, in which
    case all files that match in the current directory are marked for
    restoration. If the argument matches a directory rather than a file,
    then the directory and all files contained in that directory (recursively)
    are marked for restoration. 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.
  </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.
  </dd>
  <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.
  </dd>
  <dt>pwd</dt><dd>The <b>pwd</b> command prints the current working 
    directory. It accepts no arguments.
  </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 for restoration will
    have its name preceded by an asterisk (<b>*</b>).  Directories names
    will be terminated with a forward slash (<b>/</b>) to distinguish them
    from filenames.
  </dd>
  <dt>dir</dt><dd>The <b>dir</b> command is the 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>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>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>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>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="The Console Program" url="console.html">
<page_next name="Disaster Recovery Using Bacula" url="rescue.html">
