This repository has been archived by the owner on Mar 19, 2021. It is now read-only.
/
bootstrap.tex
431 lines (354 loc) · 14.9 KB
/
bootstrap.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
%%
%%
\chapter{The Bootstrap File}
\label{BootstrapChapter}
\index[general]{File!Bootstrap}
\index[general]{Bootstrap!File}
\TODO{This chapter is going to be rewritten (by Philipp).}
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
Bareos. However, normally the bootstrap file will be automatically created
for you during the \bcommand{restore}{} in the Console program, or
by using a
\linkResourceDirective{Dir}{Job}{Write Bootstrap} 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]{Bootstrap!File Format}
The general format of a {\bf bootstrap} file is:
{\bf {\textless}keyword{\textgreater}= {\textless}value{\textgreater}}
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]{Bootstrap!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]{Bootstrap!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]{Bootstrap!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]{Bootstrap!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]{Bootstrap!VolSessionTime}
The value specifies a Volume Session Time to be matched from the current
volume.
\item [VolSessionId]
\index[general]{Bootstrap!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]{Bootstrap!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 Bareos to restore files.
\item [Job]
\index[general]{Bootstrap!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 Bareos to restore files.
\item [Client]
\index[general]{Bootstrap!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 Bareos to restore files.
\item [FileIndex]
\index[general]{Bootstrap!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]{Bootstrap!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]{Bootstrap!Slot}
The value specifies the autochanger slot. There may be only a single {\bf
Slot} specification for each Volume.
\item [Stream]
\index[general]{Bootstrap!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 Bareos), you should avoid this specification.
This value is optional and not used by Bareos 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=bareos
*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]{Bootstrap!Automatic Generation}
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.
\section{Bootstrap for bscan}
\index[general]{bscan}
\index[general]{bscan!bootstrap}
\index[general]{Bootstrap!bscan}
\index[general]{Command!bscan}
\label{bscanBootstrap}
If you have a very large number of Volumes to scan with {\bf bscan},
you may exceed the command line limit (511 characters). In 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{Bootstrap Example}
\index[general]{Example!Bootstrap}
\index[general]{Bootstrap!Example}
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 Bareos 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 Bareos *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.