--- /dev/null
+%%
+%%
+
+\chapter{The Bootstrap File}
+\label{BootstrapChapter}
+\index[general]{File!Bootstrap }
+\index[general]{Bootstrap File }
+
+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 {\bf
+Bacula}. However, normally the bootstrap file will be automatically created
+for you during the
+\ilink{restore\_command}{_ConsoleChapter} command in the Console program, or
+by using a
+\ilink{ Write Bootstrap}{writebootstrap} record in your Backup
+Jobs, and thus you will never need to know the details of this file.
+
+The {\bf bootstrap} file contains ASCII information that permits precise
+specification of what files should be restored, what volume they are on,
+and where they are on the volume. It is a relatively compact
+form of specifying the information, is human readable, and can be edited with
+any text editor.
+
+\section{Bootstrap File Format}
+\index[general]{Format!Bootstrap}
+\index[general]{Bootstrap File Format }
+
+The general format of a {\bf bootstrap} file is:
+
+{\bf \lt{}keyword\gt{}= \lt{}value\gt{}}
+
+Where each {\bf keyword} and the {\bf value} specify which files to restore.
+More precisely the {\bf keyword} and their {\bf values} 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.
+
+Blank lines and lines beginning with a pound sign (\#) in the bootstrap file
+are ignored.
+
+There are keywords which permit filtering by Volume, Client, Job, FileIndex,
+Session Id, Session Time, ...
+
+The more keywords that are specified, the more selective the specification of
+which files to restore will be. In fact, each keyword is {\bf AND}ed with
+other keywords that may be present.
+
+For example,
+
+\footnotesize
+\begin{verbatim}
+Volume = Test-001
+VolSessionId = 1
+VolSessionTime = 108927638
+\end{verbatim}
+\normalsize
+
+directs the Storage daemon (or the {\bf bextract} program) to restore only
+those files on Volume Test-001 {\bf AND} having VolumeSessionId equal to one
+{\bf AND} having VolumeSession time equal to 108927638.
+
+The full set of permitted keywords presented in the order in which they are
+matched against the Volume records are:
+
+\begin{description}
+
+\item [Volume]
+ \index[general]{Volume }
+ 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. At lease one Volume specification is required.
+
+\item [Count]
+ \index[general]{Count}
+ 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.
+ This value is optional.
+
+\item [VolFile]
+ \index[general]{VolFile}
+ The value is a file number, a list of file numbers, or a range of file
+ 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.
+
+\item [VolBlock]
+ \index[general]{VolBlock}
+ The value is a block number, a list of block numbers, or a range of
+ block numbers to match on the current Volume. The block number
+ represents the physical block within the file on the Volume where the
+ data is stored.
+
+
+\item [VolSessionTime]
+ \index[general]{VolSessionTime }
+ The value specifies a Volume Session Time to be matched from the current
+ volume.
+
+\item [VolSessionId]
+ \index[general]{VolSessionId }
+ 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.
+
+\item [JobId]
+ \index[general]{JobId }
+ 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.
+ This value is optional and not used by Bacula to restore files.
+
+\item [Job]
+ \index[general]{Job }
+ 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.
+ This value is optional and not used by Bacula to restore files.
+
+\item [Client]
+ \index[general]{Client }
+ 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.
+ This value is optional and not used by Bacula to restore files.
+
+\item [FileIndex]
+ \index[general]{FileIndex}
+ 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.
+
+ 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.
+
+ To restore a particular file, this value (or a range of FileIndexes) is
+ required.
+
+\item [FileRegex]
+ \index[general]{FileRegex}
+ The value is a regular expression. When specified, only matching
+ filenames will be restored.
+
+\begin{verbatim}
+ FileRegex=^/etc/passwd(.old)?
+\end{verbatim}
+
+\item [Slot]
+ \index[general]{Slot }
+ The value specifies the autochanger slot. There may be only a single {\bf
+ Slot} specification for each Volume.
+
+\item [Stream]
+ \index[general]{Stream }
+ 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 {\bf Bacula}), you should avoid this specification.
+ This value is optional and not used by Bacula to restore files.
+
+\item [*JobType]
+ \index[general]{*JobType }
+ Not yet implemented.
+
+\item [*JobLevel]
+ \index[general]{*JobLevel }
+ Not yet implemented.
+\end{description}
+
+The {\bf Volume} 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.
+
+Multiple Volume records may be specified in the same bootstrap file, but each
+one starts a new set of filter criteria for the Volume.
+
+In processing the bootstrap file within the current Volume, each filter
+specified by a keyword is {\bf AND}ed with the next. Thus,
+
+\footnotesize
+\begin{verbatim}
+Volume = Test-01
+Client = "My machine"
+FileIndex = 1
+\end{verbatim}
+\normalsize
+
+will match records on Volume {\bf Test-01} {\bf AND} Client records for {\bf
+My machine} {\bf AND} FileIndex equal to {\bf one}.
+
+Multiple occurrences of the same record are {\bf OR}ed together. Thus,
+
+\footnotesize
+\begin{verbatim}
+Volume = Test-01
+Client = "My machine"
+Client = "Backup machine"
+FileIndex = 1
+\end{verbatim}
+\normalsize
+
+will match records on Volume {\bf Test-01} {\bf AND} (Client records for {\bf
+My machine} {\bf OR} {\bf Backup machine}) {\bf AND} FileIndex equal to {\bf
+one}.
+
+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,
+
+\footnotesize
+\begin{verbatim}
+Volume = Test-01
+Client = "My machine", "Backup machine"
+FileIndex = 1-20, 35
+\end{verbatim}
+\normalsize
+
+will match records on Volume {\bf Test-01} {\bf AND} {\bf (}Client records for
+{\bf My machine} {\bf OR} {\bf Backup machine}{\bf )} {\bf AND} {\bf
+(}FileIndex 1 {\bf OR} 2 {\bf OR} 3 ... {\bf OR} 20 {\bf OR} 35{\bf )}.
+
+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 {\bf OR}ed with any other
+Volume definitions.
+
+As an example, suppose we query for the current set of tapes to restore all
+files on Client {\bf Rufus} using the {\bf query} command in the console
+program:
+
+\footnotesize
+\begin{verbatim}
+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 |
++-------+------------------+------------+-----------+----------+------------+
+\end{verbatim}
+\normalsize
+
+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.
+
+The following bootstrap file will restore those files:
+
+\footnotesize
+\begin{verbatim}
+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
+\end{verbatim}
+\normalsize
+
+As a final example, assume that the initial Full save spanned two Volumes. The
+output from {\bf query} might look like:
+
+\footnotesize
+\begin{verbatim}
++-------+------------------+------------+-----------+----------+------------+
+| 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 |
++-------+------------------+------------+-----------+----------+------------+
+\end{verbatim}
+\normalsize
+
+and the following bootstrap file would restore those files:
+
+\footnotesize
+\begin{verbatim}
+Volume=File0003
+VolSessionId=1
+VolSessionTime=1025016612
+Volume=File0004
+VolSessionId=1
+VolSessionTime=1025016612
+Volume=File0005
+VolSessionId=2
+VolSessionTime=1025016612
+Volume=File0006
+VolSessionId=2
+VolSessionTime=1025025494
+\end{verbatim}
+\normalsize
+
+\section{Automatic Generation of Bootstrap Files}
+\index[general]{Files!Automatic Generation of Bootstrap }
+\index[general]{Automatic Generation of Bootstrap Files }
+
+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 during Incremental and
+Differential jobs, the records pertaining to the files written for the
+Job are appended to the end of the bootstrap file.
+As 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.
+
+When the bootstrap file is generated for the restore command, only one copy
+(the most recent) of each file is restored.
+
+So if you have spare cycles on your machine, you could optimize the bootstrap
+files by doing the following:
+
+\footnotesize
+\begin{verbatim}
+ ./bconsole
+ restore client=xxx select all
+ done
+ no
+ quit
+ Backup bootstrap file.
+\end{verbatim}
+\normalsize
+
+The above will not work if you have multiple FileSets because that will be an
+extra prompt. However, the {\bf restore client=xxx select all} builds the
+in-memory tree, selecting everything and creates the bootstrap file.
+
+The {\bf no} answers the {\bf Do you want to run this (yes/mod/no)} question.
+
+\label{bscanBootstrap}
+\section{Bootstrap for bscan}
+\index[general]{bscan}
+\index[general]{bscan!bootstrap}
+\index[general]{bscan bootstrap}
+If you have a very large number of Volumes to scan with {\bf bscan},
+you may exceed the command line limit (511 characters). I that case,
+you can create a simple bootstrap file that consists of only the
+volume names. An example might be:
+
+\footnotesize
+\begin{verbatim}
+Volume="Vol001"
+Volume="Vol002"
+Volume="Vol003"
+Volume="Vol004"
+Volume="Vol005"
+\end{verbatim}
+\normalsize
+
+
+\section{A Final Bootstrap Example}
+\index[general]{Bootstrap Example}
+\index[general]{Example!Bootstrap}
+
+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:
+
+\footnotesize
+\begin{verbatim}
+Volume="Vol001"
+VolSessionId=10
+VolSessionTime=1080847820
+\end{verbatim}
+\normalsize
+
+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):
+
+\footnotesize
+\begin{verbatim}
+FileIndex=1-157
+Count=157
+\end{verbatim}
+\normalsize
+
+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:
+
+\footnotesize
+\begin{verbatim}
+VolFile=20
+\end{verbatim}
+\normalsize
+
+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.
+
+If you want to see a *real* bsr file, simply fire up the {\bf restore} command
+in the console program, select something, then answer no when it prompts to
+run the job. Then look at the file {\bf restore.bsr} in your working
+directory.
projects / bacula / docs / blobdiff