Debian Codegraph @

manuals/en/main/bootstrap.tex

raw
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.