4 \chapter{The Bootstrap File}
5 \label{BootstrapChapter}
6 \index[general]{File!Bootstrap }
7 \index[general]{Bootstrap File }
9 The information in this chapter is provided so that you may either create your
10 own bootstrap files, or so that you can edit a bootstrap file produced by {\bf
11 Bacula}. However, normally the bootstrap file will be automatically created
13 \ilink{restore\_command}{_ConsoleChapter} command in the Console program, or
15 \ilink{ Write Bootstrap}{writebootstrap} record in your Backup
16 Jobs, and thus you will never need to know the details of this file.
18 The {\bf bootstrap} file contains ASCII information that permits precise
19 specification of what files should be restored, what volume they are on,
20 and where they are on the volume. It is a relatively compact
21 form of specifying the information, is human readable, and can be edited with
24 \section{Bootstrap File Format}
25 \index[general]{Format!Bootstrap}
26 \index[general]{Bootstrap File Format }
28 The general format of a {\bf bootstrap} file is:
30 {\bf \lt{}keyword\gt{}= \lt{}value\gt{}}
32 Where each {\bf keyword} and the {\bf value} specify which files to restore.
33 More precisely the {\bf keyword} and their {\bf values} serve to limit which
34 files will be restored and thus act as a filter. The absence of a keyword
35 means that all records will be accepted.
37 Blank lines and lines beginning with a pound sign (\#) in the bootstrap file
40 There are keywords which permit filtering by Volume, Client, Job, FileIndex,
41 Session Id, Session Time, ...
43 The more keywords that are specified, the more selective the specification of
44 which files to restore will be. In fact, each keyword is {\bf AND}ed with
45 other keywords that may be present.
53 VolSessionTime = 108927638
57 directs the Storage daemon (or the {\bf bextract} program) to restore only
58 those files on Volume Test-001 {\bf AND} having VolumeSessionId equal to one
59 {\bf AND} having VolumeSession time equal to 108927638.
61 The full set of permitted keywords presented in the order in which they are
62 matched against the Volume records are:
67 \index[general]{Volume }
68 The value field specifies what Volume the following commands apply to.
69 Each Volume specification becomes the current Volume, to which all the
70 following commands apply until a new current Volume (if any) is
71 specified. If the Volume name contains spaces, it should be enclosed in
72 quotes. At lease one Volume specification is required.
75 \index[general]{Count}
76 The value is the total number of files that will be restored for this Volume.
77 This allows the Storage daemon to know when to stop reading the Volume.
78 This value is optional.
81 \index[general]{VolFile}
82 The value is a file number, a list of file numbers, or a range of file
83 numbers to match on the current Volume. The file number represents the
84 physical file on the Volume where the data is stored. For a tape
85 volume, this record is used to position to the correct starting file,
86 and once the tape is past the last specified file, reading will stop.
89 \index[general]{VolBlock}
90 The value is a block number, a list of block numbers, or a range of
91 block numbers to match on the current Volume. The block number
92 represents the physical block within the file on the Volume where the
96 \item [VolSessionTime]
97 \index[general]{VolSessionTime }
98 The value specifies a Volume Session Time to be matched from the current
102 \index[general]{VolSessionId }
103 The value specifies a VolSessionId, a list of volume session ids, or a
104 range of volume session ids to be matched from the current Volume. Each
105 VolSessionId and VolSessionTime pair corresponds to a unique Job that is
106 backed up on the Volume.
109 \index[general]{JobId }
110 The value specifies a JobId, list of JobIds, or range of JobIds to be
111 selected from the current Volume. Note, the JobId may not be unique if you
112 have multiple Directors, or if you have reinitialized your database. The
113 JobId filter works only if you do not run multiple simultaneous jobs.
114 This value is optional and not used by Bacula to restore files.
117 \index[general]{Job }
118 The value specifies a Job name or list of Job names to be matched on the
119 current Volume. The Job corresponds to a unique VolSessionId and
120 VolSessionTime pair. However, the Job is perhaps a bit more readable by
121 humans. Standard regular expressions (wildcards) may be used to match Job
122 names. The Job filter works only if you do not run multiple simultaneous
124 This value is optional and not used by Bacula to restore files.
127 \index[general]{Client }
128 The value specifies a Client name or list of Clients to will be matched on
129 the current Volume. Standard regular expressions (wildcards) may be used to
130 match Client names. The Client filter works only if you do not run multiple
132 This value is optional and not used by Bacula to restore files.
135 \index[general]{FileIndex}
136 The value specifies a FileIndex, list of FileIndexes, or range of FileIndexes
137 to be selected from the current Volume. Each file (data) stored on a Volume
138 within a Session has a unique FileIndex. For each Session, the first file
139 written is assigned FileIndex equal to one and incremented for each file
142 This for a given Volume, the triple VolSessionId, VolSessionTime, and
143 FileIndex uniquely identifies a file stored on the Volume. Multiple copies of
144 the same file may be stored on the same Volume, but for each file, the triple
145 VolSessionId, VolSessionTime, and FileIndex will be unique. This triple is
146 stored in the Catalog database for each file.
148 To restore a particular file, this value (or a range of FileIndexes) is
152 \item [FileRegex]\label{FileRegex}
153 \index[general]{FileRegex}
154 The value is a regular expression. When specified, only matching
155 filenames will be restored.
158 FileRegex=^/etc/passwd(.old)?
162 \index[general]{Slot }
163 The value specifies the autochanger slot. There may be only a single {\bf
164 Slot} specification for each Volume.
167 \index[general]{Stream }
168 The value specifies a Stream, a list of Streams, or a range of Streams to be
169 selected from the current Volume. Unless you really know what you are doing
170 (the internals of {\bf Bacula}), you should avoid this specification.
171 This value is optional and not used by Bacula to restore files.
174 \index[general]{*JobType }
178 \index[general]{*JobLevel }
182 The {\bf Volume} record is a bit special in that it must be the first record.
183 The other keyword records may appear in any order and any number following a
186 Multiple Volume records may be specified in the same bootstrap file, but each
187 one starts a new set of filter criteria for the Volume.
189 In processing the bootstrap file within the current Volume, each filter
190 specified by a keyword is {\bf AND}ed with the next. Thus,
195 Client = "My machine"
200 will match records on Volume {\bf Test-01} {\bf AND} Client records for {\bf
201 My machine} {\bf AND} FileIndex equal to {\bf one}.
203 Multiple occurrences of the same record are {\bf OR}ed together. Thus,
208 Client = "My machine"
209 Client = "Backup machine"
214 will match records on Volume {\bf Test-01} {\bf AND} (Client records for {\bf
215 My machine} {\bf OR} {\bf Backup machine}) {\bf AND} FileIndex equal to {\bf
218 For integer values, you may supply a range or a list, and for all other values
219 except Volumes, you may specify a list. A list is equivalent to multiple
220 records of the same keyword. For example,
225 Client = "My machine", "Backup machine"
230 will match records on Volume {\bf Test-01} {\bf AND} {\bf (}Client records for
231 {\bf My machine} {\bf OR} {\bf Backup machine}{\bf )} {\bf AND} {\bf
232 (}FileIndex 1 {\bf OR} 2 {\bf OR} 3 ... {\bf OR} 20 {\bf OR} 35{\bf )}.
234 As previously mentioned above, there may be multiple Volume records in the
235 same bootstrap file. Each new Volume definition begins a new set of filter
236 conditions that apply to that Volume and will be {\bf OR}ed with any other
239 As an example, suppose we query for the current set of tapes to restore all
240 files on Client {\bf Rufus} using the {\bf query} command in the console
245 Using default Catalog name=MySQL DB=bacula
249 2: List where a file is saved:
250 3: List where the most recent copies of a file are saved:
251 4: List total files/bytes by Job:
252 5: List total files/bytes by Volume:
253 6: List last 10 Full Backups for a Client:
254 7: List Volumes used by selected JobId:
255 8: List Volumes to Restore All Files:
256 Choose a query (1-8): 8
257 Enter Client Name: Rufus
258 +-------+------------------+------------+-----------+----------+------------+
259 | JobId | StartTime | VolumeName | StartFile | VolSesId | VolSesTime |
260 +-------+------------------+------------+-----------+----------+------------+
261 | 154 | 2002-05-30 12:08 | test-02 | 0 | 1 | 1022753312 |
262 | 202 | 2002-06-15 10:16 | test-02 | 0 | 2 | 1024128917 |
263 | 203 | 2002-06-15 11:12 | test-02 | 3 | 1 | 1024132350 |
264 | 204 | 2002-06-18 08:11 | test-02 | 4 | 1 | 1024380678 |
265 +-------+------------------+------------+-----------+----------+------------+
269 The output shows us that there are four Jobs that must be restored. The first
270 one is a Full backup, and the following three are all Incremental backups.
272 The following bootstrap file will restore those files:
278 VolSessionTime=1022753312
281 VolSessionTime=1024128917
284 VolSessionTime=1024132350
287 VolSessionTime=1024380678
291 As a final example, assume that the initial Full save spanned two Volumes. The
292 output from {\bf query} might look like:
296 +-------+------------------+------------+-----------+----------+------------+
297 | JobId | StartTime | VolumeName | StartFile | VolSesId | VolSesTime |
298 +-------+------------------+------------+-----------+----------+------------+
299 | 242 | 2002-06-25 16:50 | File0003 | 0 | 1 | 1025016612 |
300 | 242 | 2002-06-25 16:50 | File0004 | 0 | 1 | 1025016612 |
301 | 243 | 2002-06-25 16:52 | File0005 | 0 | 2 | 1025016612 |
302 | 246 | 2002-06-25 19:19 | File0006 | 0 | 2 | 1025025494 |
303 +-------+------------------+------------+-----------+----------+------------+
307 and the following bootstrap file would restore those files:
313 VolSessionTime=1025016612
316 VolSessionTime=1025016612
319 VolSessionTime=1025016612
322 VolSessionTime=1025025494
326 \section{Automatic Generation of Bootstrap Files}
327 \index[general]{Files!Automatic Generation of Bootstrap }
328 \index[general]{Automatic Generation of Bootstrap Files }
330 One thing that is probably worth knowing: the bootstrap files that are
331 generated automatically at the end of the job are not as optimized as those
332 generated by the restore command. This is because during Incremental and
333 Differential jobs, the records pertaining to the files written for the
334 Job are appended to the end of the bootstrap file.
335 As consequence, all the files saved to an Incremental or Differential job will be
336 restored first by the Full save, then by any Incremental or Differential
339 When the bootstrap file is generated for the restore command, only one copy
340 (the most recent) of each file is restored.
342 So if you have spare cycles on your machine, you could optimize the bootstrap
343 files by doing the following:
348 restore client=xxx select all
352 Backup bootstrap file.
356 The above will not work if you have multiple FileSets because that will be an
357 extra prompt. However, the {\bf restore client=xxx select all} builds the
358 in-memory tree, selecting everything and creates the bootstrap file.
360 The {\bf no} answers the {\bf Do you want to run this (yes/mod/no)} question.
362 \label{bscanBootstrap}
363 \section{Bootstrap for bscan}
364 \index[general]{bscan}
365 \index[general]{bscan!bootstrap}
366 \index[general]{bscan bootstrap}
367 If you have a very large number of Volumes to scan with {\bf bscan},
368 you may exceed the command line limit (511 characters). I that case,
369 you can create a simple bootstrap file that consists of only the
370 volume names. An example might be:
383 \section{A Final Bootstrap Example}
384 \index[general]{Bootstrap Example}
385 \index[general]{Example!Bootstrap}
387 If you want to extract or copy a single Job, you can do it by selecting by
388 JobId (code not tested) or better yet, if you know the VolSessionTime and the
389 VolSessionId (printed on Job report and in Catalog), specifying this is by far
390 the best. Using the VolSessionTime and VolSessionId is the way Bacula does
391 restores. A bsr file might look like the following:
397 VolSessionTime=1080847820
401 If you know how many files are backed up (on the job report), you can
402 enormously speed up the selection by adding (let's assume there are 157
412 Finally, if you know the File number where the Job starts, you can also cause
413 bcopy to forward space to the right file without reading every record:
421 There is nothing magic or complicated about a BSR file. Parsing it and
422 properly applying it within Bacula *is* magic, but you don't need to worry
425 If you want to see a *real* bsr file, simply fire up the {\bf restore} command
426 in the console program, select something, then answer no when it prompts to
427 run the job. Then look at the file {\bf restore.bsr} in your working