
#include "bacula_template.inc" title="Bootstrap Files" num=22

<h1>The Bootstrap File</h1>
The information in this chapter is provided so that you may    
either create your own bootstrap files, or so that you can
edit a bootstrap file produced by <b>Bacula</b>. However, normally
the bootstrap file will be
automatically created for you during the 
<a href="restore.html"><b>restore</b></a> command
in the Console program, or by using a <a href="dirdconf.html#writebootstrap">
<b>Write Bootstrap</b></a>
record in your Backup Jobs, and thus you will never need to know
the details of this file.
<p>
The <b>bootstrap</b> file contains ASCII information that permits
precise specification of what files should be restored. It is a
relatively compact form of specifying the information, is
human readable, and can be edited with any text editor.

<h2>File Format</h2>
The general format of a <b>bootstrap</b> file is:
<p><b>&lt;keyword&gt = &lt;value&gt;</b>
<p>Where each <b>keyword</b> and the <b>value</b> specify
which files to restore. More precisely
the <b>keyword</b> and their <b>values</b> serve
to limit which files will be restored and thus act as
a filter. The absence of a keyword means that all
records will be accepted.
<p>Blank lines and lines beginning with a pound sign (#) in
the bootstrap file are ignored.
<p>There are keywords which permit filtering by Volume,
Client, Job, FileIndex, Session Id, Session Time, ...
<p>The more keywords that are specified, the more 
selective the specification of which files to
restore will be.
In fact, each keyword is <b>AND</b>ed with
other keywords that may be present.
<p>
For example,
<pre>
Volume = Test-001
VolSessionId = 1
VolSessionTime = 108927638
</pre>
directs the Storage daemon (or the <b>bextract</b> program)
to restore only those files on Volume Test-001 <b>AND</b>
having VolumeSessionId equal to one <b>AND</b> having VolumeSession time
equal to 108927638.
<p>
The full set of permitted keywords presented in the order in which
they are matched against the Volume records are:
<dl>
  <dt>Volume</dt><dd>The value field specifies what Volume the
      following commands apply to.
      Each Volume specification becomes the current
      Volume, to which all the following commands apply until
      a new current Volume (if any) is specified. If the Volume name
      contains spaces, it should be enclosed in quotes. </dd>
  <dt>Count</dt><dd>The value is the total number of files that
      will be restored for this Volume. This allows the Storage  
      daemon to know when to stop reading the Volume.</dd>
  <dt>VolFile</dt><dd>The value is a file number, a list of file numbers,
      or a range of file numbers numbers to match on the current Volume.
      The file number represents the physical file on the Volume where
      the data is stored.  For a tape volume, this record is used
      to position to the correct starting file, and once the tape is
      past the last specified file, reading will stop.       </dd>
  <dt>VolBlock</dt><dd> The value is a block number, a list of block numbers,
      or a range of block numbers numbers to match on the current Volume.
      The block number represents the physical block on the Volume where
      the data is stored.  This record is currently not used.</dd>
  <dt>VolSessionTime</dt><dd>The value specifies a Volume Session Time to
      be matched from the current volume.
      </dd>
  <dt>VolSessionId</dt><dd>The value specifies a VolSessionId, a list of
      volume session ids, or a range of volume session ids to be matched
      from the current Volume. Each VolSessionId and VolSessionTime pair corresponds
      to a unique Job that is backed up on the Volume.
      </dd>
  <dt>JobId</dt><dd>The value specifies a JobId, list of JobIds, or range of JobIds 
      to be selected from the current Volume. Note, the JobId may not be
      unique if you have multiple Directors, or if you have reinitialized your
      database. The JobId filter works only if you do not run
      multiple simultaneous jobs. 
      </dd>
  <dt>Job</dt><dd>The value specifies a Job name or list of Job names to
      be matched on the current Volume. The Job corresponds to a unique
      VolSessionId and VolSessionTime pair. However, the Job is perhaps a
      bit more readable by humans. Standard regular expressions (wildcards)
      may be used to match Job names.  The Job filter works only if you do
      not run multiple simultaneous jobs.
      </dd>
  <dt>Client</dt><dd>The value specifies a Client name or list of Clients to
      will be matched on the current Volume. Standard regular expressions
      (wildcards) may be used to match Client names. The Client filter works
      only if you do not run multiple simultaneous jobs.
      </dd>
  <dt>FileIndex</dt><dd>The value specifies a FileIndex, list of FileIndexes,
      or range of FileIndexes to be selected from the current Volume.
      Each file (data) stored on a Volume within a Session has a unique
      FileIndex. For each Session, the first file written is assigned
      FileIndex equal to one and incremented for each file backed up.
      <p>This for a given Volume, the triple VolSessionId, VolSessionTime,
      and FileIndex uniquely identifies a file stored on the Volume. Multiple
      copies of the same file may be stored on the same Volume, but for
      each file, the triple VolSessionId, VolSessionTime, and FileIndex
      will be unique. This triple is stored in the Catalog database for
      each file.
      </dd>
  <dt>Slot</dt><dd>The value specifies the autochanger slot. There may
     be only a single <b>Slot</b> specification for each Volume.</dd>
  <dt>Stream</dt><dd>The value specifies a Stream, a list of Streams,
     or a range of Streams to be selected from the current Volume.
     Unless you really know what you are doing (the internals of
     <b>Bacula</b>, you should avoid this specification.</dd>

  <dt>*JobType</dt><dd>Not yet implemented.
      </dd>
  <dt>*JobLevel</dt><dd>Not yet implemented.
      </dd>
</dl>

<p>The <b>Volume</b> record is a bit special in that it must be the 
first record. The other keyword records may appear in any order and any
number following a Volume record.
<p>Multiple Volume records may be specified in the same bootstrap file,
but each one starts a new set of filter criteria for the Volume.
<p>
In processing the bootstrap file within the current Volume,
each filter specified by a keyword is <b>AND</b>ed with the next.
Thus,

<pre>
Volume = Test-01
Client = "My machine"
FileIndex = 1
</pre>
will match records on Volume <b>Test-01</b> <b>AND</b> Client records
for <b>My machine</b> <b>AND</b> FileIndex equal to <b>one</b>.
<p>Multiple occurrences of the same record are <b>OR</b>ed together.
Thus,
<pre>
Volume = Test-01
Client = "My machine"
Client = "Backup machine"
FileIndex = 1
</pre>
will match records on Volume <b>Test-01</b> <b>AND</b> (Client records
for <b>My machine</b> <b>OR</b> <b>Backup machine</b>) <b>AND</b>
FileIndex equal to <b>one</b>.
<p>
For integer values, you may supply a range or a list, and for all 
other values except Volumes, you may specify a list. A list is 
equivalent to multiple records of the same keyword.
For example,
<pre>
Volume = Test-01
Client = "My machine", "Backup machine"
FileIndex = 1-20, 35
</pre>
will match records on Volume <b>Test-01</b> <b>AND</b> <b>(</b>Client records
for <b>My machine</b> <b>OR</b> <b>Backup machine</b><b>)</b> <b>AND</b>
<b>(</b>FileIndex 1 <b>OR</b> 2 <b>OR</b> 3 ... 
<b>OR</b> 20 <b>OR</b> 35<b>)</b>.
<p>
As previously mentioned above, there may be multiple Volume records in
the same bootstrap file. Each new Volume definition begins a new set
of filter conditions that apply to that Volume and will be <b>OR</b>ed
with any other Volume definitions.
<p>As an example, suppose we query for the current set of tapes
to restore all files on Client <b>Rufus</b> using the <b>query</b>
command in the console program:
<pre>
Using default Catalog name=MySQL DB=bacula
*query
Available queries:
     1: List Job totals:
     2: List where a file is saved:
     3: List where the most recent copies of a file are saved:
     4: List total files/bytes by Job:
     5: List total files/bytes by Volume:
     6: List last 10 Full Backups for a Client:
     7: List Volumes used by selected JobId:
     8: List Volumes to Restore All Files:
Choose a query (1-8): 8

Enter Client Name: Rufus
+-------+------------------+------------+-----------+----------+------------+
| JobId | StartTime        | VolumeName | StartFile | VolSesId | VolSesTime |
+-------+------------------+------------+-----------+----------+------------+
| 154   | 2002-05-30 12:08 | test-02    | 0         | 1        | 1022753312 |
| 202   | 2002-06-15 10:16 | test-02    | 0         | 2        | 1024128917 |
| 203   | 2002-06-15 11:12 | test-02    | 3         | 1        | 1024132350 |
| 204   | 2002-06-18 08:11 | test-02    | 4         | 1        | 1024380678 |
+-------+------------------+------------+-----------+----------+------------+
</pre>
The output shows us that there are four Jobs that must be restored.
The first one is a Full backup, and the following three are all Incremental
backups.
<p>The following bootstrap file will restore those files:
<pre>
Volume=test-02
VolSessionId=1
VolSessionTime=1022753312
Volume=test-02
VolSessionId=2
VolSessionTime=1024128917
Volume=test-02
VolSessionId=1
VolSessionTime=1024132350
Volume=test-02
VolSessionId=1
VolSessionTime=1024380678
</pre>

<p>
As a final example, assume that the initial Full save spanned two Volumes.
The output from <b>query</b> might look like:
<pre>
+-------+------------------+------------+-----------+----------+------------+
| JobId | StartTime        | VolumeName | StartFile | VolSesId | VolSesTime |
+-------+------------------+------------+-----------+----------+------------+
| 242   | 2002-06-25 16:50 | File0003   | 0         | 1        | 1025016612 |
| 242   | 2002-06-25 16:50 | File0004   | 0         | 1        | 1025016612 |
| 243   | 2002-06-25 16:52 | File0005   | 0         | 2        | 1025016612 |
| 246   | 2002-06-25 19:19 | File0006   | 0         | 2        | 1025025494 |
+-------+------------------+------------+-----------+----------+------------+
</pre>
and the following bootstrap file would restore those files:
<pre>
Volume=File0003
VolSessionId=1
VolSessionTime=1025016612
Volume=File0004
VolSessionId=1
VolSessionTime=1025016612
Volume=File0005
VolSessionId=2
VolSessionTime=1025016612
Volume=File0006
VolSessionId=2
VolSessionTime=1025025494
</pre>
    
<h2>Automatic Generation of Bootstrap Files</h2>
One thing that is probably worth knowing: the bootstrap
files that are generated automatically at the end of the
job are not as optimized as those generated by the
restore command.  This is because the ones created at the
end of the file, contain all files written to the Volume
for that job. As a consequence, all the files saved to
an Incremental or Differential job will be restored first
by the Full save, then by any Incremental or Differential
saves.
<p>
When the bootstrap file is generated for the restore
command, only one copy (the most recent) of each file
is restored.
<p>
So if you have spare cycles on your machine, you could
optimize the bootstrap files by doing the following:
<pre>
   ./console
   restore client=xxx select all
   no
   quit

   Backup bootstrap file.
</pre>
The above will not work if you have multiple FileSets
because that will be an extra prompt. However, the
<b>restore client=xxx select all</b>
builds the in-memory tree, selecting everything
and creates the bootstrap file.
<p>
The <b>no</b> answers the <b>Do you want to run this (yes/mod/no)</b>
question.

<h2>A Final Example</h2>
If you want to extract or copy a single Job, you can do it
by selecting by JobId (code not tested) or better yet, 
if you know the VolSessionTime and the VolSessionId 
(printed on Job report and in Catalog), specifying this is by far the best.
Using the VolSessionTime and VolSessionId is the way Bacula does restores.
A bsr file might look like the following:
<pre>
Volume="Vol001"
VolSessionId=10
VolSessionTime=1080847820
</pre>
If you know how many files are backed up (on the job report), 
you can enormously speed up the selection by adding 
(let's assume there are 157 files):
<pre>
FileIndex=1-157
Count=157
</pre>
Finally, if you know the File number where the Job starts, 
you can also cause bcopy to forward space to the right file 
without reading every record:
<pre>
VolFile=20
</pre>
There is nothing magic or complicated about a BSR file. 
Parsing it and properly applying it within Bacula *is* magic, 
but you don't need to worry about that.
<p>
If you want to see a *real* bsr file, simply fire up 
the <b>restore</b> command in the console program,
select something, then answer no when it prompts to run the job. 
Then look at the file <b>restore.bsr</b> in your working directory.

<page_prev name="Using Bacula to Improve Your System Security" url="verify.html">
<page_next name="Installing and Configuring MySQL" url="mysql.html">
