Next: Bacula Copyright, Trademark, and Up: Bacula Concepts and Overview Previous: Using Bacula to Improve Contents Index
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 Bacula. However, normally the bootstrap file will be automatically created for you during the restore_command command in the Console program, or by using a Write Bootstrap record in your Backup Jobs, and thus you will never need to know the details of this file.
The 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.
The general format of a bootstrap file is:
<keyword>= <value>
Where each keyword and the value specify which files to restore. More precisely the keyword and their 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 ANDed with other keywords that may be present.
For example,
Volume = Test-001 VolSessionId = 1 VolSessionTime = 108927638
directs the Storage daemon (or the bextract program) to restore only those files on Volume Test-001 AND having VolumeSessionId equal to one 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:
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.
FileRegex=^/etc/passwd(.old)?
The 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 ANDed with the next. Thus,
Volume = Test-01 Client = "My machine" FileIndex = 1
will match records on Volume Test-01 AND Client records for My machine AND FileIndex equal to one.
Multiple occurrences of the same record are ORed together. Thus,
Volume = Test-01 Client = "My machine" Client = "Backup machine" FileIndex = 1
will match records on Volume Test-01 AND (Client records for My machine OR Backup machine) AND FileIndex equal to 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,
Volume = Test-01 Client = "My machine", "Backup machine" FileIndex = 1-20, 35
will match records on Volume Test-01 AND (Client records for My machine OR Backup machine) AND (FileIndex 1 OR 2 OR 3 ... OR 20 OR 35).
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 ORed with any other Volume definitions.
As an example, suppose we query for the current set of tapes to restore all files on Client Rufus using the query command in the console program:
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 |
+-------+------------------+------------+-----------+----------+------------+
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:
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
As a final example, assume that the initial Full save spanned two Volumes. The output from query might look like:
+-------+------------------+------------+-----------+----------+------------+ | 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 | +-------+------------------+------------+-----------+----------+------------+
and the following bootstrap file would restore those files:
Volume=File0003 VolSessionId=1 VolSessionTime=1025016612 Volume=File0004 VolSessionId=1 VolSessionTime=1025016612 Volume=File0005 VolSessionId=2 VolSessionTime=1025016612 Volume=File0006 VolSessionId=2 VolSessionTime=1025025494
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:
./bconsole restore client=xxx select all done no quit Backup bootstrap file.
The above will not work if you have multiple FileSets because that will be an extra prompt. However, the restore client=xxx select all builds the in-memory tree, selecting everything and creates the bootstrap file.
The no answers the Do you want to run this (yes/mod/no) question.
Volume="Vol001" Volume="Vol002" Volume="Vol003" Volume="Vol004" Volume="Vol005"
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:
Volume="Vol001" VolSessionId=10 VolSessionTime=1080847820
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):
FileIndex=1-157 Count=157
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:
VolFile=20
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 restore command in the console program, select something, then answer no when it prompts to run the job. Then look at the file restore.bsr in your working directory.