| 1 |
\chapter{The Bootstrap File} |
| 2 |
\label{blb:BootstrapChapter} |
| 3 |
\index[general]{File!Bootstrap } |
| 4 |
\index[general]{Bootstrap File } |
| 5 |
|
| 6 |
The information in this chapter is provided so that you may either create your |
| 7 |
own bootstrap files, or so that you can edit a bootstrap file produced by |
| 8 |
\textbf{\bacula{}}. However, normally the bootstrap file will be automatically created |
| 9 |
for you during the |
| 10 |
\bxlink{\bacula{} Console}{blb:ConsoleChapter}{console}{chapter} of the \bconsoleman{}, or |
| 11 |
by using a |
| 12 |
\bilink{Write Bootstrap}{blb:writebootstrap} record in your Backup |
| 13 |
Jobs, and thus you will never need to know the details of this file. |
| 14 |
|
| 15 |
The \textbf{bootstrap} file contains \acs{ASCII} information that permits precise |
| 16 |
specification of what files should be restored, what volume they are on, |
| 17 |
and where they are on the volume. It is a relatively compact |
| 18 |
form of specifying the information, is human readable, and can be edited with |
| 19 |
any text editor. |
| 20 |
|
| 21 |
\section{Bootstrap File Format} |
| 22 |
\index[general]{Format!Bootstrap} |
| 23 |
\index[general]{Bootstrap File Format } |
| 24 |
|
| 25 |
The general format of a \textbf{bootstrap} file is: |
| 26 |
|
| 27 |
\textbf{\bbracket{keyword}= \bbracket{value}} |
| 28 |
|
| 29 |
Where each \textbf{keyword} and the \textbf{value} specify which files to restore. |
| 30 |
More precisely the \textbf{keyword} and their \textbf{values} serve to limit which |
| 31 |
files will be restored and thus act as a filter. The absence of a keyword |
| 32 |
means that all records will be accepted. |
| 33 |
|
| 34 |
Blank lines and lines beginning with a pound sign (\#) in the bootstrap file |
| 35 |
are ignored. |
| 36 |
|
| 37 |
There are keywords which permit filtering by Volume, Client, Job, FileIndex, |
| 38 |
Session Id, Session Time, \ldots{} |
| 39 |
|
| 40 |
The more keywords that are specified, the more selective the specification of |
| 41 |
which files to restore will be. In fact, each keyword is \textbf{AND}ed with |
| 42 |
other keywords that may be present. |
| 43 |
|
| 44 |
For example, |
| 45 |
|
| 46 |
\begin{bVerbatim} |
| 47 |
Volume = Test-001 |
| 48 |
VolSessionId = 1 |
| 49 |
VolSessionTime = 108927638 |
| 50 |
\end{bVerbatim} |
| 51 |
|
| 52 |
directs the Storage daemon (or the \btool{bextract} program) to restore only |
| 53 |
those files on Volume Test-001 \textbf{AND} having VolumeSessionId equal to one |
| 54 |
\textbf{AND} having VolumeSession time equal to 108927638. |
| 55 |
|
| 56 |
The full set of permitted keywords presented in the order in which they are |
| 57 |
matched against the Volume records are: |
| 58 |
|
| 59 |
\begin{bdescription} |
| 60 |
|
| 61 |
\item [Volume] |
| 62 |
\index[general]{Volume } |
| 63 |
The value field specifies what Volume the following commands apply to. |
| 64 |
Each Volume specification becomes the current Volume, to which all the |
| 65 |
following commands apply until a new current Volume (if any) is |
| 66 |
specified. If the Volume name contains spaces, it should be enclosed in |
| 67 |
quotes. At lease one Volume specification is required. |
| 68 |
|
| 69 |
\item [Count] |
| 70 |
\index[general]{Count} |
| 71 |
The value is the total number of files that will be restored for this Volume. |
| 72 |
This allows the Storage daemon to know when to stop reading the Volume. |
| 73 |
This value is optional. |
| 74 |
|
| 75 |
\item [VolFile] |
| 76 |
\index[general]{VolFile} |
| 77 |
The value is a file number, a list of file numbers, or a range of file |
| 78 |
numbers to match on the current Volume. The file number represents the |
| 79 |
physical file on the Volume where the data is stored. For a tape |
| 80 |
volume, this record is used to position to the correct starting file, |
| 81 |
and once the tape is past the last specified file, reading will stop. |
| 82 |
|
| 83 |
\item [VolBlock] |
| 84 |
\index[general]{VolBlock} |
| 85 |
The value is a block number, a list of block numbers, or a range of |
| 86 |
block numbers to match on the current Volume. The block number |
| 87 |
represents the physical block within the file on the Volume where the |
| 88 |
data is stored. |
| 89 |
|
| 90 |
|
| 91 |
\item [VolSessionTime] |
| 92 |
\index[general]{VolSessionTime } |
| 93 |
The value specifies a Volume Session Time to be matched from the current |
| 94 |
volume. |
| 95 |
|
| 96 |
\item [VolSessionId] |
| 97 |
\index[general]{VolSessionId } |
| 98 |
The value specifies a VolSessionId, a list of volume session ids, or a |
| 99 |
range of volume session ids to be matched from the current Volume. Each |
| 100 |
VolSessionId and VolSessionTime pair corresponds to a unique Job that is |
| 101 |
backed up on the Volume. |
| 102 |
|
| 103 |
\item [JobId] |
| 104 |
\index[general]{JobId } |
| 105 |
The value specifies a JobId, list of JobIds, or range of JobIds to be |
| 106 |
selected from the current Volume. Note, the JobId may not be unique if you |
| 107 |
have multiple Directors, or if you have reinitialized your database. The |
| 108 |
JobId filter works only if you do not run multiple simultaneous jobs. |
| 109 |
This value is optional and not used by \bacula{} to restore files. |
| 110 |
|
| 111 |
\item [Job] |
| 112 |
\index[general]{Job } |
| 113 |
The value specifies a Job name or list of Job names to be matched on the |
| 114 |
current Volume. The Job corresponds to a unique VolSessionId and |
| 115 |
VolSessionTime pair. However, the Job is perhaps a bit more readable by |
| 116 |
humans. Standard regular expressions (wildcards) may be used to match Job |
| 117 |
names. The Job filter works only if you do not run multiple simultaneous |
| 118 |
jobs. |
| 119 |
This value is optional and not used by \bacula{} to restore files. |
| 120 |
|
| 121 |
\item [Client] |
| 122 |
\index[general]{Client } |
| 123 |
The value specifies a Client name or list of Clients to will be matched on |
| 124 |
the current Volume. Standard regular expressions (wildcards) may be used to |
| 125 |
match Client names. The Client filter works only if you do not run multiple |
| 126 |
simultaneous jobs. |
| 127 |
This value is optional and not used by \bacula{} to restore files. |
| 128 |
|
| 129 |
\item [FileIndex] |
| 130 |
\index[general]{FileIndex} |
| 131 |
The value specifies a FileIndex, list of FileIndexes, or range of FileIndexes |
| 132 |
to be selected from the current Volume. Each file (data) stored on a Volume |
| 133 |
within a Session has a unique FileIndex. For each Session, the first file |
| 134 |
written is assigned FileIndex equal to one and incremented for each file |
| 135 |
backed up. |
| 136 |
|
| 137 |
This for a given Volume, the triple VolSessionId, VolSessionTime, and |
| 138 |
FileIndex uniquely identifies a file stored on the Volume. Multiple copies of |
| 139 |
the same file may be stored on the same Volume, but for each file, the triple |
| 140 |
VolSessionId, VolSessionTime, and FileIndex will be unique. This triple is |
| 141 |
stored in the Catalog database for each file. |
| 142 |
|
| 143 |
To restore a particular file, this value (or a range of FileIndexes) is |
| 144 |
required. |
| 145 |
|
| 146 |
\phantomsection |
| 147 |
\item [FileRegex]\label{blb:FileRegex} |
| 148 |
\index[general]{FileRegex} |
| 149 |
The value is a regular expression. When specified, only matching |
| 150 |
filenames will be restored. |
| 151 |
|
| 152 |
\begin{bVerbatim} |
| 153 |
FileRegex=^/etc/passwd(.old)? |
| 154 |
\end{bVerbatim} |
| 155 |
|
| 156 |
\item [Slot] |
| 157 |
\index[general]{Slot } |
| 158 |
The value specifies the autochanger slot. There may be only a single |
| 159 |
\textbf{Slot} specification for each Volume. |
| 160 |
|
| 161 |
\item [Stream] |
| 162 |
\index[general]{Stream } |
| 163 |
The value specifies a Stream, a list of Streams, or a range of Streams to be |
| 164 |
selected from the current Volume. Unless you really know what you are doing |
| 165 |
(the internals of \textbf{\bacula{}}), you should avoid this specification. |
| 166 |
This value is optional and not used by \bacula{} to restore files. |
| 167 |
|
| 168 |
\item [*JobType] |
| 169 |
\index[general]{*JobType } |
| 170 |
Not yet implemented. |
| 171 |
|
| 172 |
\item [*JobLevel] |
| 173 |
\index[general]{*JobLevel } |
| 174 |
Not yet implemented. |
| 175 |
\end{bdescription} |
| 176 |
|
| 177 |
The \textbf{Volume} record is a bit special in that it must be the first record. |
| 178 |
The other keyword records may appear in any order and any number following a |
| 179 |
Volume record. |
| 180 |
|
| 181 |
Multiple Volume records may be specified in the same bootstrap file, but each |
| 182 |
one starts a new set of filter criteria for the Volume. |
| 183 |
|
| 184 |
In processing the bootstrap file within the current Volume, each filter |
| 185 |
specified by a keyword is \textbf{AND}ed with the next. Thus, |
| 186 |
|
| 187 |
\begin{bVerbatim} |
| 188 |
Volume = Test-01 |
| 189 |
Client = "My machine" |
| 190 |
FileIndex = 1 |
| 191 |
\end{bVerbatim} |
| 192 |
|
| 193 |
will match records on Volume \textbf{Test-01} \textbf{AND} Client records for |
| 194 |
\textbf{My machine} \textbf{AND} FileIndex equal to \textbf{one}. |
| 195 |
|
| 196 |
Multiple occurrences of the same record are \textbf{OR}ed together. Thus, |
| 197 |
|
| 198 |
\begin{bVerbatim} |
| 199 |
Volume = Test-01 |
| 200 |
Client = "My machine" |
| 201 |
Client = "Backup machine" |
| 202 |
FileIndex = 1 |
| 203 |
\end{bVerbatim} |
| 204 |
|
| 205 |
will match records on Volume \textbf{Test-01} \textbf{AND} (Client records for |
| 206 |
\textbf{My machine} \textbf{OR} \textbf{Backup machine}) \textbf{AND} FileIndex equal to |
| 207 |
\textbf{one}. |
| 208 |
|
| 209 |
For integer values, you may supply a range or a list, and for all other values |
| 210 |
except Volumes, you may specify a list. A list is equivalent to multiple |
| 211 |
records of the same keyword. For example, |
| 212 |
|
| 213 |
\begin{bVerbatim} |
| 214 |
Volume = Test-01 |
| 215 |
Client = "My machine", "Backup machine" |
| 216 |
FileIndex = 1-20, 35 |
| 217 |
\end{bVerbatim} |
| 218 |
|
| 219 |
will match records on Volume \textbf{Test-01} \textbf{AND} \textbf{(}Client records for |
| 220 |
\textbf{My machine} \textbf{OR} \textbf{Backup machine}\textbf{)} \textbf{AND} |
| 221 |
\textbf{(}FileIndex 1 \textbf{OR} 2 \textbf{OR} 3 \ldots{} \textbf{OR} 20 \textbf{OR} 35\textbf{)}. |
| 222 |
|
| 223 |
As previously mentioned above, there may be multiple Volume records in the |
| 224 |
same bootstrap file. Each new Volume definition begins a new set of filter |
| 225 |
conditions that apply to that Volume and will be \textbf{OR}ed with any other |
| 226 |
Volume definitions. |
| 227 |
|
| 228 |
As an example, suppose we query for the current set of tapes to restore all |
| 229 |
files on Client \textbf{Rufus} using the \bcommandname{query} command in the console |
| 230 |
program: |
| 231 |
|
| 232 |
\begin{bVerbatim} |
| 233 |
Using default Catalog name=MySQL DB=bacula |
| 234 |
*query |
| 235 |
Available queries: |
| 236 |
1: List Job totals: |
| 237 |
2: List where a file is saved: |
| 238 |
3: List where the most recent copies of a file are saved: |
| 239 |
4: List total files/bytes by Job: |
| 240 |
5: List total files/bytes by Volume: |
| 241 |
6: List last 10 Full Backups for a Client: |
| 242 |
7: List Volumes used by selected JobId: |
| 243 |
8: List Volumes to Restore All Files: |
| 244 |
Choose a query (1-8): 8 |
| 245 |
Enter Client Name: Rufus |
| 246 |
+-------+------------------+------------+-----------+----------+------------+ |
| 247 |
| JobId | StartTime | VolumeName | StartFile | VolSesId | VolSesTime | |
| 248 |
+-------+------------------+------------+-----------+----------+------------+ |
| 249 |
| 154 | 2002-05-30 12:08 | test-02 | 0 | 1 | 1022753312 | |
| 250 |
| 202 | 2002-06-15 10:16 | test-02 | 0 | 2 | 1024128917 | |
| 251 |
| 203 | 2002-06-15 11:12 | test-02 | 3 | 1 | 1024132350 | |
| 252 |
| 204 | 2002-06-18 08:11 | test-02 | 4 | 1 | 1024380678 | |
| 253 |
+-------+------------------+------------+-----------+----------+------------+ |
| 254 |
\end{bVerbatim} |
| 255 |
|
| 256 |
The output shows us that there are four Jobs that must be restored. The first |
| 257 |
one is a Full backup, and the following three are all Incremental backups. |
| 258 |
|
| 259 |
The following bootstrap file will restore those files: |
| 260 |
|
| 261 |
\begin{bVerbatim} |
| 262 |
Volume=test-02 |
| 263 |
VolSessionId=1 |
| 264 |
VolSessionTime=1022753312 |
| 265 |
Volume=test-02 |
| 266 |
VolSessionId=2 |
| 267 |
VolSessionTime=1024128917 |
| 268 |
Volume=test-02 |
| 269 |
VolSessionId=1 |
| 270 |
VolSessionTime=1024132350 |
| 271 |
Volume=test-02 |
| 272 |
VolSessionId=1 |
| 273 |
VolSessionTime=1024380678 |
| 274 |
\end{bVerbatim} |
| 275 |
|
| 276 |
As a final example, assume that the initial Full save spanned two Volumes. The |
| 277 |
output from \bcommandname{query} might look like: |
| 278 |
|
| 279 |
\begin{bVerbatim} |
| 280 |
+-------+------------------+------------+-----------+----------+------------+ |
| 281 |
| JobId | StartTime | VolumeName | StartFile | VolSesId | VolSesTime | |
| 282 |
+-------+------------------+------------+-----------+----------+------------+ |
| 283 |
| 242 | 2002-06-25 16:50 | File0003 | 0 | 1 | 1025016612 | |
| 284 |
| 242 | 2002-06-25 16:50 | File0004 | 0 | 1 | 1025016612 | |
| 285 |
| 243 | 2002-06-25 16:52 | File0005 | 0 | 2 | 1025016612 | |
| 286 |
| 246 | 2002-06-25 19:19 | File0006 | 0 | 2 | 1025025494 | |
| 287 |
+-------+------------------+------------+-----------+----------+------------+ |
| 288 |
\end{bVerbatim} |
| 289 |
|
| 290 |
and the following bootstrap file would restore those files: |
| 291 |
|
| 292 |
\begin{bVerbatim} |
| 293 |
Volume=File0003 |
| 294 |
VolSessionId=1 |
| 295 |
VolSessionTime=1025016612 |
| 296 |
Volume=File0004 |
| 297 |
VolSessionId=1 |
| 298 |
VolSessionTime=1025016612 |
| 299 |
Volume=File0005 |
| 300 |
VolSessionId=2 |
| 301 |
VolSessionTime=1025016612 |
| 302 |
Volume=File0006 |
| 303 |
VolSessionId=2 |
| 304 |
VolSessionTime=1025025494 |
| 305 |
\end{bVerbatim} |
| 306 |
|
| 307 |
\section{Automatic Generation of Bootstrap Files} |
| 308 |
\index[general]{Files!Automatic Generation of Bootstrap } |
| 309 |
\index[general]{Automatic Generation of Bootstrap Files } |
| 310 |
|
| 311 |
One thing that is probably worth knowing: the bootstrap files that are |
| 312 |
generated automatically at the end of the job are not as optimized as those |
| 313 |
generated by the \bcommandname{restore} command. This is because during Incremental and |
| 314 |
Differential jobs, the records pertaining to the files written for the |
| 315 |
Job are appended to the end of the bootstrap file. |
| 316 |
As consequence, all the files saved to an Incremental or Differential job will be |
| 317 |
restored first by the Full save, then by any Incremental or Differential |
| 318 |
saves. |
| 319 |
|
| 320 |
When the bootstrap file is generated for the \bcommandname{restore} command, only one copy |
| 321 |
(the most recent) of each file is restored. |
| 322 |
|
| 323 |
So if you have spare cycles on your machine, you could optimize the bootstrap |
| 324 |
files by doing the following: |
| 325 |
|
| 326 |
\begin{bVerbatim} |
| 327 |
./bconsole |
| 328 |
restore client=xxx select all |
| 329 |
done |
| 330 |
no |
| 331 |
quit |
| 332 |
Backup bootstrap file. |
| 333 |
\end{bVerbatim} |
| 334 |
|
| 335 |
The above will not work if you have multiple FileSets because that will be an |
| 336 |
extra prompt. However, the \bcommandname{restore client=xxx select all} builds the |
| 337 |
in-memory tree, selecting everything and creates the bootstrap file. |
| 338 |
|
| 339 |
The \textbf{no} answers the \textbf{Do you want to run this (yes/mod/no)} question. |
| 340 |
|
| 341 |
\label{blb:bscanBootstrap} |
| 342 |
\section{Bootstrap for bscan} |
| 343 |
\index[general]{bscan} |
| 344 |
\index[general]{bscan!bootstrap} |
| 345 |
\index[general]{bscan bootstrap} |
| 346 |
If you have a very large number of Volumes to scan with \btool{bscan}, |
| 347 |
you may exceed the command line limit (511 characters). I that case, |
| 348 |
you can create a simple bootstrap file that consists of only the |
| 349 |
volume names. An example might be: |
| 350 |
|
| 351 |
\begin{bVerbatim} |
| 352 |
Volume="Vol001" |
| 353 |
Volume="Vol002" |
| 354 |
Volume="Vol003" |
| 355 |
Volume="Vol004" |
| 356 |
Volume="Vol005" |
| 357 |
\end{bVerbatim} |
| 358 |
|
| 359 |
|
| 360 |
\section{A Final Bootstrap Example} |
| 361 |
\index[general]{Bootstrap Example} |
| 362 |
\index[general]{Example!Bootstrap} |
| 363 |
|
| 364 |
If you want to extract or copy a single Job, you can do it by selecting by |
| 365 |
JobId (code not tested) or better yet, if you know the VolSessionTime and the |
| 366 |
VolSessionId (printed on Job report and in Catalog), specifying this is by far |
| 367 |
the best. Using the VolSessionTime and VolSessionId is the way \bacula{} does |
| 368 |
restores. A bsr file might look like the following: |
| 369 |
|
| 370 |
\begin{bVerbatim} |
| 371 |
Volume="Vol001" |
| 372 |
VolSessionId=10 |
| 373 |
VolSessionTime=1080847820 |
| 374 |
\end{bVerbatim} |
| 375 |
|
| 376 |
If you know how many files are backed up (on the job report), you can |
| 377 |
enormously speed up the selection by adding (let's assume there are 157 |
| 378 |
files): |
| 379 |
|
| 380 |
\begin{bVerbatim} |
| 381 |
FileIndex=1-157 |
| 382 |
Count=157 |
| 383 |
\end{bVerbatim} |
| 384 |
|
| 385 |
Finally, if you know the File number where the Job starts, you can also cause |
| 386 |
\btool{bcopy} to forward space to the right file without reading every record: |
| 387 |
|
| 388 |
\begin{bVerbatim} |
| 389 |
VolFile=20 |
| 390 |
\end{bVerbatim} |
| 391 |
|
| 392 |
There is nothing magic or complicated about a BSR file. Parsing it and |
| 393 |
properly applying it within \bacula{} *is* magic, but you don't need to worry |
| 394 |
about that. |
| 395 |
|
| 396 |
If you want to see a \textbf{real} bsr file, simply fire up the \bcommandname{restore} command |
| 397 |
in the console program, select something, then answer no when it prompts to |
| 398 |
run the job. Then look at the file \bfilename{restore.bsr} in your working |
| 399 |
directory. |