Debian Codegraph @

manuals/en/main/restore.tex

raw
1 \chapter{The Restore Command}
2 \label{blb:RestoreChapter}
3 \index[general]{Command!Console Restore}
4 \index[general]{Console Restore Command}
5
6 \section{General}
7 \index[general]{General }
8
9 Below, we will discuss restoring files with the Console \bcommandname{restore} command,
10 which is the recommended way of doing restoring files. It is not possible
11 to restore files by automatically starting a job as you do with Backup,
12 Verify, \ldots{} jobs. However, in addition to the console \bcommandname{restore} command,
13 there is a standalone program named \btool{bextract}, which also permits
14 restoring files. For more information on this program, please see the
15 \bxlink{bextract}{blb:bextract}{utility}{command} in the \butilityman{}. We
16 don't particularly recommend the \btool{bextract} program because it
17 lacks many of the features of the normal \bacula{} restore, such as the
18 ability to restore Win32 files to Unix systems, and the ability to
19 restore access control lists (ACL). As a consequence, we recommend,
20 wherever possible to use \bacula{} itself for restores as described below.
21
22 You may also want to look at the \btool{bls} program in the same chapter,
23 which allows you to list the contents of your Volumes. Finally, if you
24 have an old Volume that is no longer in the catalog, you can restore the
25 catalog entries using the program named \btool{bscan}, documented in the same
26 \bxlink{bscan}{blb:bscan}{utility}{command} in the \butilityman{}.
27
28 In general, to restore a file or a set of files, you must run a \bcommandname{restore}
29 job. That is a job with \textbf{Type = Restore}. As a consequence, you will need
30 a predefined \bcommandname{restore} job in your \bfilename{bacula-dir.conf} (Director's
31 config) file. The exact parameters (Client, FileSet, \ldots{}) that you define are
32 not important as you can either modify them manually before running the job or
33 if you use the \bcommandname{restore} command, explained below, \bacula{} will
34 automatically set them for you. In fact, you can no longer simply run a restore
35 job. You must use the \bcommandname{restore} command.
36
37 Since \bacula{} is a network backup program, you must be aware that when you
38 restore files, it is up to you to ensure that you or \bacula{} have selected the
39 correct Client and the correct hard disk location for restoring those files.
40 \textbf{\bacula{}} will quite willingly backup client A, and restore it by sending
41 the files to a different directory on client B. Normally, you will want to
42 avoid this, but assuming the operating systems are not too different in their
43 file structures, this should work perfectly well, if so desired.
44 By default, \bacula{} will restore data to the same Client that was backed
45 up, and those data will be restored not to the original places but to
46 \bdirectoryname{/tmp/bacula-restores}. You may modify any of these defaults when the
47 \bcommandname{restore} command prompts you to run the job by selecting the \textbf{mod}
48 option.
49
50 \label{blb:Example1}
51 \section{The Restore Command}
52 \index[general]{Command!Restore}
53 \index[general]{Restore Command}
54
55 Since \bacula{} maintains a catalog of your files and on which Volumes (disk or
56 tape), they are stored, it can do most of the bookkeeping work, allowing you
57 simply to specify what kind of restore you want (current, before a particular
58 date), and what files to restore. \bacula{} will then do the rest.
59
60 This is accomplished using the \bcommandname{restore} command in the Console. First you
61 select the kind of restore you want, then the JobIds are selected,
62 the File records for those Jobs are placed in an internal \bacula{} directory
63 tree, and the restore enters a file selection mode that allows you to
64 interactively walk up and down the file tree selecting individual files to be
65 restored. This mode is somewhat similar to the standard Unix \bcommandname{restore}
66 program's interactive file selection mode.
67
68 If a Job's file records have been pruned from the catalog, the \bcommandname{restore}
69 command will be unable to find any files to restore. \bacula{} will ask if you
70 want to restore all of them or if you want to use a regular expression to
71 restore only a selection while reading media. See
72 \bilink{FileRegex option}{blb:FileRegex} and below for more details on this.
73
74 Within the Console program, after entering the \bcommandname{restore} command, you are
75 presented with the following selection prompt:
76
77 \begin{bVerbatim}
78 First you select one or more JobIds that contain files
79 to be restored. You will be presented several methods
80 of specifying the JobIds. Then you will be allowed to
81 select which files from those JobIds are to be restored.
82 To select the JobIds, you have the following choices:
83 1: List last 20 Jobs run
84 2: List Jobs where a given File is saved
85 3: Enter list of comma separated JobIds to select
86 4: Enter SQL list command
87 5: Select the most recent backup for a client
88 6: Select backup for a client before a specified time
89 7: Enter a list of files to restore
90 8: Enter a list of files to restore before a specified time
91 9: Find the JobIds of the most recent backup for a client
92 10: Find the JobIds for a backup for a client before a specified time
93 11: Enter a list of directories to restore for found JobIds
94 12: Select full restore to a specified Job date
95 13: Select object to restore
96 14: Cancel
97 Select item: (1-14):
98 \end{bVerbatim}
99
100 There are a lot of options, and as a point of reference, most people will
101 want to slect item 5 (the most recent backup for a client). The details
102 of the above options are:
103
104 \begin{bitemize}
105 \item Item 1 will list the last 20 jobs run. If you find the Job you want,
106 you can then select item 3 and enter its JobId(s).
107
108 \item Item 2 will list all the Jobs where a specified file is saved. If you
109 find the Job you want, you can then select item 3 and enter the JobId.
110
111 \item Item 3 allows you the enter a list of comma separated JobIds whose
112 files will be put into the directory tree. You may then select which
113 files from those JobIds to restore. Normally, you would use this option
114 if you have a particular version of a file that you want to restore and
115 you know its JobId. The most common options (5 and 6) will not select
116 a job that did not terminate normally, so if you know a file is
117 backed up by a Job that failed (possibly because of a system crash), you
118 can access it through this option by specifying the JobId.
119
120 \item Item 4 allows you to enter any arbitrary \acs{SQL} command. This is
121 probably the most primitive way of finding the desired JobIds, but at
122 the same time, the most flexible. Once you have found the JobId(s), you
123 can select item 3 and enter them.
124
125 \item Item 5 will automatically select the most recent Full backup and all
126 subsequent incremental and differential backups for a specified Client.
127 These are the Jobs and Files which, if reloaded, will restore your
128 system to the most current saved state. It automatically enters the
129 JobIds found into the directory tree in an optimal way such that only
130 the most recent copy of any particular file found in the set of Jobs
131 will be restored. This is probably the most convenient of all the above
132 options to use if you wish to restore a selected Client to its most
133 recent state.
134
135 There are two important things to note. First, this automatic selection
136 will never select a job that failed (terminated with an error status).
137 If you have such a job and want to recover one or more files from it,
138 you will need to explicitly enter the JobId in item 3, then choose the
139 files to restore.
140
141 If some of the Jobs that are needed to do the restore have had their
142 File records pruned, the restore will be incomplete. \bacula{} currently
143 does not correctly detect this condition. You can however, check for
144 this by looking carefully at the list of Jobs that \bacula{} selects and
145 prints. If you find Jobs with the JobFiles column set to zero, when
146 files should have been backed up, then you should expect problems.
147
148 If all the File records have been pruned, \bacula{} will realize that there
149 are no file records in any of the JobIds chosen and will inform you. It
150 will then propose doing a full restore (non-selective) of those JobIds.
151 This is possible because \bacula{} still knows where the beginning of the
152 Job data is on the Volumes, even if it does not know where particular
153 files are located or what their names are.
154
155 \item Item 6 allows you to specify a date and time, after which \bacula{} will
156 automatically select the most recent Full backup and all subsequent
157 incremental and differential backups that started before the specified date
158 and time.
159
160 \item Item 7 allows you to specify one or more filenames (complete path
161 required) to be restored. Each filename is entered one at a time or if you
162 prefix a filename with the less-than symbol (\lt{}) \bacula{} will read that
163 file and assume it is a list of filenames to be restored. If you
164 prefix the filename with a question mark (?), then the filename will
165 be interpreted as an SQL table name, and \bacula{} will include the rows
166 of that table in the list to be restored. The table must contain the
167 JobId in the first column and the FileIndex in the second column.
168 This table feature is intended for external programs that want to build
169 their own list of files to be restored.
170 The filename entry mode is terminated by entering a blank line.
171
172 \item Item 8 allows you to specify a date and time before entering the
173 filenames. See Item 7 above for more details.
174
175 \item Item 9 allows you find the JobIds of the most recent backup for
176 a client. This is much like option 5 (it uses the same code), but
177 those JobIds are retained internally as if you had entered them
178 manually. You may then select item 11 (see below) to restore one
179 or more directories.
180
181 \item Item 10 is the same as item 9, except that it allows you to enter
182 a before date (as with item 6). These JobIds will then be retained
183 internally.
184
185 \index[general]{Restore Directories}
186 \item Item 11 allows you to enter a list of JobIds from which you can
187 select directories to be restored. The list of JobIds can have been
188 previously created by using either item 9 or 10 on the menu. You
189 may then enter a full path to a directory name or a filename preceded
190 by a less than sign (\lt{}). The filename should contain a list
191 of directories to be restored. All files in those directories will
192 be restored, but if the directory contains subdirectories, nothing
193 will be restored in the subdirectory unless you explicitly enter its
194 name.
195
196 \item Item 12 allows you to restore choosen state of the Job.
197
198 \item Item 13 allows you to enter menu to select object to be restored.
199
200 \item Item 14 allows you to cancel the \bcommandname{restore} command.
201 \end{bitemize}
202
203 As an example, suppose that we select item 5 (restore to most recent state).
204 If you have not specified a \texttt{client=xxx} on the command line, it
205 it will then ask for the desired Client, which on my system, will print all
206 the Clients found in the database as follows:
207
208 \begin{bVerbatim}
209 Defined clients:
210 1: Rufus
211 2: Matou
212 3: Polymatou
213 4: Minimatou
214 5: Minou
215 6: MatouVerify
216 7: PmatouVerify
217 8: RufusVerify
218 9: Watchdog
219 Select Client (File daemon) resource (1-9):
220 \end{bVerbatim}
221
222 You will probably have far fewer Clients than this example, and if you have
223 only one Client, it will be automatically selected. In this case, I enter
224 \textbf{Rufus} to select the Client. Then \bacula{} needs to know what FileSet is
225 to be restored, so it prompts with:
226
227 \begin{bVerbatim}
228 The defined FileSet resources are:
229 1: Full Set
230 2: Other Files
231 Select FileSet resource (1-2):
232 \end{bVerbatim}
233
234 If you have only one FileSet defined for the Client, it will be selected
235 automatically. I choose item 1, which is my full backup. Normally, you
236 will only have a single FileSet for each Job, and if your machines are
237 similar (all Linux) you may only have one FileSet for all your Clients.
238
239 At this point, \textbf{\bacula{}} has all the information it needs to find the most
240 recent set of backups. It will then query the database, which may take a bit
241 of time, and it will come up with something like the following. Note, some of
242 the columns are truncated here for presentation:
243
244 \begin{bVerbatim}
245 +-------+------+----------+-------------+-------------+------+-------+------------+
246 | JobId | Levl | JobFiles | StartTime | VolumeName | File | SesId |VolSesTime |
247 +-------+------+----------+-------------+-------------+------+-------+------------+
248 | 1,792 | F | 128,374 | 08-03 01:58 | DLT-19Jul02 | 67 | 18 | 1028042998 |
249 | 1,792 | F | 128,374 | 08-03 01:58 | DLT-04Aug02 | 0 | 18 | 1028042998 |
250 | 1,797 | I | 254 | 08-04 13:53 | DLT-04Aug02 | 5 | 23 | 1028042998 |
251 | 1,798 | I | 15 | 08-05 01:05 | DLT-04Aug02 | 6 | 24 | 1028042998 |
252 +-------+------+----------+-------------+-------------+------+-------+------------+
253 You have selected the following JobId: 1792,1792,1797
254 Building directory tree for JobId 1792 ...
255 Building directory tree for JobId 1797 ...
256 Building directory tree for JobId 1798 ...
257 cwd is: /
258 $
259 \end{bVerbatim}
260
261 Depending on the number of \textbf{JobFiles} for each JobId, the \textbf{Building directory tree \ldots{}"}
262 can take a bit of time. If you notice ath all the
263 JobFiles are zero, your Files have probably been pruned and you will not be
264 able to select any individual files -- it will be restore everything or
265 nothing.
266
267 In our example, \bacula{} found four Jobs that comprise the most recent backup of
268 the specified Client and FileSet. Two of the Jobs have the same JobId because
269 that Job wrote on two different Volumes. The third Job was an incremental
270 backup to the previous Full backup, and it only saved 254 Files compared to
271 128,374 for the Full backup. The fourth Job was also an incremental backup
272 that saved 15 files.
273
274 Next \bacula{} entered those Jobs into the directory tree, with no files marked
275 to be restored as a default, tells you how many files are in the tree, and
276 tells you that the current working directory (\bcommandname{cwd}) is /. Finally, \bacula{}
277 prompts with the dollar sign (\$) to indicate that you may enter commands to
278 move around the directory tree and to select files.
279
280 If you want all the files to automatically be marked when the directory
281 tree is built, you could have entered the command \bcommandname{restore all}, or
282 at the \$ prompt, you can simply enter \bcommandname{mark *}.
283
284 Instead of choosing item 5 on the first menu (Select the most recent backup
285 for a client), if we had chosen item 3 (Enter list of JobIds to select) and we
286 had entered the JobIds \textbf{1792,1797,1798} we would have arrived at the same
287 point.
288
289 One point to note, if you are manually entering JobIds, is that you must enter
290 them in the order they were run (generally in increasing JobId order). If you
291 enter them out of order and the same file was saved in two or more of the
292 Jobs, you may end up with an old version of that file (i.e. not the most
293 recent).
294
295 Directly entering the JobIds can also permit you to recover data from
296 a Job that wrote files to tape but that terminated with an error status.
297
298 While in file selection mode, you can enter \bcommandname{help} or a question mark (?)
299 to produce a summary of the available commands:
300
301 \begin{bVerbatim}
302 Command Description
303 ======= ===========
304 cd change current directory
305 count count marked files in and below the cd
306 dir long list current directory, wildcards allowed
307 done leave file selection mode
308 du
309 estimate estimate restore size
310 exit same as done command
311 find find files, wildcards allowed
312 help print help
313 ls list current directory, wildcards allowed
314 lsmark list the marked files in and below the cd
315 mark mark dir/file to be restored recursively in dirs
316 markdir mark directory name to be restored (no files)
317 pwd print current working directory
318 unmark unmark dir/file to be restored recursively in dir
319 unmarkdir unmark directory name only no recursion
320 quit quit and do not do restore
321 ? print help
322 \end{bVerbatim}
323
324 As a default no files have been selected for restore (unless you
325 added \textbf{all} to the command line. If you want to restore
326 everything, at this point, you should enter \bcommandname{mark *}, and then \bcommandname{done}
327 and \textbf{\bacula{}} will write the bootstrap records to a file and request your
328 approval to start a restore job.
329
330 If you do not enter the above mentioned \bcommandname{mark *} command, you will start
331 with an empty slate. Now you can simply start looking at the tree and
332 \bcommandname{mark} particular files or directories you want restored. It is easy to make
333 a mistake in specifying a file to mark or unmark, and \bacula{}'s error handling
334 is not perfect, so please check your work by using the \bcommandname{ls} or \bcommandname{dir}
335 commands to see what files are actually selected. Any selected file has its
336 name preceded by an asterisk.
337
338 To check what is marked or not marked, enter the \bcommandname{count} command, which
339 displays:
340
341 \begin{bVerbatim}
342 128401 total files. 128401 marked to be restored.
343 \end{bVerbatim}
344
345 Each of the above commands will be described in more detail in the next
346 section. We continue with the above example, having accepted to restore all
347 files as \bacula{} set by default. On entering the \bcommandname{done} command, \bacula{}
348 prints:
349
350 \begin{bVerbatim}
351 Bootstrap records written to /home/kern/bacula/working/restore.bsr
352 The job will require the following
353 Volume(s) Storage(s) SD Device(s)
354 ===========================================================================
355
356 DLT-19Jul02 Tape DLT8000
357 DLT-04Aug02 Tape DLT8000
358
359 128401 files selected to restore.
360 Run Restore job
361 JobName: kernsrestore
362 Bootstrap: /home/kern/bacula/working/restore.bsr
363 Where: /tmp/bacula-restores
364 Replace: always
365 FileSet: Other Files
366 Client: Rufus
367 Storage: Tape
368 When: 2006-12-11 18:20:33
369 Catalog: MyCatalog
370 Priority: 10
371 OK to run? (yes/mod/no):
372 \end{bVerbatim}
373
374 Please examine each of the items very carefully to make sure that they are
375 correct. In particular, look at \textbf{Where}, which tells you where in the
376 directory structure the files will be restored, and \textbf{Client}, which
377 tells you which client will receive the files. Note that by default the
378 Client which will receive the files is the Client that was backed up.
379 These items will not always be completed with the correct values depending
380 on which of the restore options you chose. You can change any of these
381 default items by entering \textbf{mod} and responding to the prompts.
382
383 The above assumes that you have defined a \textbf{Restore} Job resource in your
384 Director's configuration file. Normally, you will only need one Restore Job
385 resource definition because by its nature, restoring is a manual operation,
386 and using the Console interface, you will be able to modify the Restore Job to
387 do what you want.
388
389 An example Restore Job resource definition is given below.
390
391 Returning to the above example, you should verify that the Client name is
392 correct before running the Job. However, you may want to modify some of the
393 parameters of the restore job. For example, in addition to checking the Client
394 it is wise to check that the Storage device chosen by \bacula{} is indeed
395 correct. Although the \textbf{FileSet} is shown, it will be ignored in restore.
396 The restore will choose the files to be restored either by reading the \textbf{Bootstrap}
397 file, or if not specified, it will restore all files associated
398 with the specified backup \textbf{JobId} (i.e. the JobId of the Job that
399 originally backed up the files).
400
401 Finally before running the job, please note that the default location for
402 restoring files is \textbf{not} their original locations, but rather the directory
403 \bdirectoryname{/tmp/bacula-restores}. You can change this default by modifying your
404 \bfilename{bacula-dir.conf} file, or you can modify it using the \textbf{mod} option. If you
405 want to restore the files to their original location, you must have \textbf{Where}
406 set to nothing or to the root, i.e. \bdirectoryname{/}.
407
408 If you now enter \textbf{yes}, \bacula{} will run the restore Job. The Storage
409 daemon will first request Volume \textbf{DLT-19Jul02} and after the appropriate
410 files have been restored from that volume, it will request Volume \textbf{DLT-04Aug02}.
411
412 \subsection{Restore a pruned job using a pattern}
413 During a restore, if all File records are pruned from the catalog
414 for a Job, normally \bacula{} can restore only all files saved. That
415 is there is no way using the catalog to select individual files.
416 With this new feature, \bacula{} will ask if you want to specify a Regex
417 expression for extracting only a part of the full backup.
418
419 \begin{bVerbatim}
420 Building directory tree for JobId(s) 1,3 ...
421 There were no files inserted into the tree, so file selection
422 is not possible.Most likely your retention policy pruned the files
423
424 Do you want to restore all the files? (yes|no): no
425
426 Regexp matching files to restore? (empty to abort): /tmp/regress/(bin|tests)/
427 Bootstrap records written to /tmp/regress/working/zog4-dir.restore.1.bsr
428 \end{bVerbatim}
429
430 See also \bilink{FileRegex bsr option}{blb:FileRegex} for more information.
431
432 \section{Selecting Files by Filename}
433 \index[general]{Selecting Files by Filename }
434 \index[general]{Filename!Selecting Files by }
435
436 If you have a small number of files to restore, and you know the filenames,
437 you can either put the list of filenames in a file to be read by \bacula{}, or
438 you can enter the names one at a time. The filenames must include the full
439 path and filename. No wild cards are used.
440
441 To enter the files, after the \bcommandname{restore}, you select item number 7 from the
442 prompt list:
443
444 \begin{bVerbatim}
445 To select the JobIds, you have the following choices:
446 1: List last 20 Jobs run
447 2: List Jobs where a given File is saved
448 3: Enter list of comma separated JobIds to select
449 4: Enter SQL list command
450 5: Select the most recent backup for a client
451 6: Select backup for a client before a specified time
452 7: Enter a list of files to restore
453 8: Enter a list of files to restore before a specified time
454 9: Find the JobIds of the most recent backup for a client
455 10: Find the JobIds for a backup for a client before a specified time
456 11: Enter a list of directories to restore for found JobIds
457 12: Cancel
458 Select item: (1-12):
459 \end{bVerbatim}
460
461 which then prompts you for the client name:
462
463 \begin{bVerbatim}
464 Defined Clients:
465 1: Timmy
466 2: Tibs
467 3: Rufus
468 Select the Client (1-3): 3
469 \end{bVerbatim}
470
471 Of course, your client list will be different, and if you have only one
472 client, it will be automatically selected. And finally, \bacula{} requests you to
473 enter a filename:
474
475 \begin{bVerbatim}
476 Enter filename:
477 \end{bVerbatim}
478
479 At this point, you can enter the full path and filename
480
481 \begin{bVerbatim}
482 Enter filename: /home/kern/bacula/k/Makefile.in
483 Enter filename:
484 \end{bVerbatim}
485
486 as you can see, it took the filename. If \bacula{} cannot find a copy of the
487 file, it prints the following:
488
489 \begin{bVerbatim}
490 Enter filename: junk filename
491 No database record found for: junk filename
492 Enter filename:
493 \end{bVerbatim}
494
495 If you want \bacula{} to read the filenames from a file, you simply precede the
496 filename with a less-than symbol (\lt{}). When you have entered all the
497 filenames, you enter a blank line, and \bacula{} will write the bootstrap file,
498 tells you what tapes will be used, and proposes a Restore job to be run:
499
500 \begin{bVerbatim}
501 Enter filename:
502 Automatically selected Storage: DDS-4
503 Bootstrap records written to /home/kern/bacula/working/restore.bsr
504 The restore job will require the following Volumes:
505
506 test1
507 1 file selected to restore.
508 Run Restore job
509 JobName: kernsrestore
510 Bootstrap: /home/kern/bacula/working/restore.bsr
511 Where: /tmp/bacula-restores
512 Replace: always
513 FileSet: Other Files
514 Client: Rufus
515 Storage: DDS-4
516 When: 2003-09-11 10:20:53
517 Priority: 10
518 OK to run? (yes/mod/no):
519 \end{bVerbatim}
520
521 It is possible to automate the selection by file by putting your list of files
522 in say \bdirectoryname{/tmp/file-list}, then using the following command:
523
524 \begin{bVerbatim}
525 restore client=Rufus file=</tmp/file-list
526 \end{bVerbatim}
527
528 If in modifying the parameters for the Run Restore job, you find that \bacula{}
529 asks you to enter a Job number, this is because you have not yet specified
530 either a Job number or a Bootstrap file. Simply entering zero will allow you
531 to continue and to select another option to be modified.
532
533 \label{blb:Replace}
534
535 \section{Replace Options}
536
537 When restoring, you have the option to specify a Replace option. This
538 directive determines the action to be taken when restoring a file or
539 directory that already exists. This directive can be set by selecting
540 the \textbf{mod} option. You will be given a list of parameters to choose
541 from. Full details on this option can be found in the Job Resource section
542 of the Director documentation.
543
544 \label{blb:CommandArguments}
545
546 \section{Command Line Arguments}
547 \index[general]{Arguments!Command Line }
548 \index[general]{Command Line Arguments }
549
550 If all the above sounds complicated, you will probably agree that it really
551 isn't after trying it a few times. It is possible to do everything that was
552 shown above, with the exception of selecting the FileSet, by using command
553 line arguments with a single command by entering:
554
555 \begin{bVerbatim}
556 restore client=Rufus select current all done yes
557 \end{bVerbatim}
558
559 The \textbf{client=Rufus} specification will automatically select Rufus as the
560 client, the \textbf{current} tells \bacula{} that you want to restore the system to
561 the most current state possible, the \textbf{all} selects all files, the \textbf{done}
562 automatically finishes the file selection process, and the \textbf{yes} suppresses the final
563 \textbf{yes/mod/no} prompt and simply runs the restore.
564
565 An example using a FileSet and a date specification:
566
567 \begin{bVerbatim}
568 restore client=Rufus fileset=Catalog before="2015-05-26 00:00:00" select all done yes
569 \end{bVerbatim}
570
571 In this second example, the \textbf{fileset} tells \bacula{} which FileSet to use so you are
572 not prompted for one, the \textbf{before} specifies a date and time to which the system should
573 be restored. Notice that the \textbf{current} argument was removed in this example because
574 it does not make sense when you are using the \textbf{before} argument to also
575 specify ``current"'' as a date and time.
576
577 Also, when using the \textbf{before} argument, be aware that the \textbf{select}
578 argument must come after it, otherise you will not get the results you expect.
579
580 If you wish to select specific files to restore rather than restoring the entire
581 backup job, omit the \textbf{all}, \textbf{done}, and \textbf{yes} parameters
582 and you will be taken to the interactive file selection prompt.
583
584 The full list of possible command line arguments is:
585 \begin{bdescription}
586 \item [all] -- select all Files to be restored.
587 \item [select] -- use the tree selection method.
588 \item [done] -- do not prompt the user in tree mode.
589 \item [current] -- automatically select the most current set of backups
590 for the specified client.
591 \item [client=xxxx] -- initially specifies the client from which the
592 backup was made and the client to which the restore will be make. See also
593 "restoreclient" keyword.
594 \item [restoreclient=xxxx] -- if the keyword is specified, then the
595 restore is written to that client.
596 \item [jobid=nnn] -- specify a JobId or comma separated list of JobIds to
597 be restored.
598 \item [before="YYYY-MM-DD HH:MM:SS"] -- specify a date and time to which
599 the system should be restored. Only Jobs started before the specified
600 date/time will be selected, and as is the case for \textbf{current} \bacula{} will
601 automatically find the most recent prior Full save and all Differential and
602 Incremental saves run before the date you specify. Note, this command is not
603 too user friendly in that you must specify the date/time exactly as shown.
604 \item [file=filename] -- specify a filename to be restored. You must
605 specify the full path and filename. Prefixing the entry with a less-than
606 sign
607 (\lt{}) will cause \bacula{} to assume that the filename is on your system and
608 contains a list of files to be restored. \bacula{} will thus read the list from
609 that file. Multiple file=xxx specifications may be specified on the command
610 line.
611 \item [directory=path] -- specify a directory to be restored. You must
612 specify the full path. Prefixing the entry with a less-than
613 sign
614 (\lt{}) will cause \bacula{} to assume that the filename is on your system and
615 contains a list of directories to be restored. \bacula{} will thus read the list from
616 that file. Multiple directory=xxx specifications may be specified on the command
617 line.
618 \item [fileset=fileset-name] -- Specify a FileSet to be restored.
619 \item [jobid=nnn] -- specify a JobId to be restored.
620 \item [pool=pool-name] -- specify a Pool name to be used for selection of
621 Volumes when specifying options 5 and 6 (restore current system, and restore
622 current system before given date). This permits you to have several Pools,
623 possibly one offsite, and to select the Pool to be used for restoring.
624 \item [where=/tmp/bacula-restores] -- restore files in \textbf{where} directory.
625 \item [yes] -- automatically run the restore without prompting for
626 modifications (most useful in batch scripts).
627
628 \item [add\_prefix=/test] -- add a prefix to all files when restoring (like
629 where) (can't be used with \textbf{where=}).
630 \item [strip\_prefix=/prod] -- remove a part of the filename when
631 restoring. We suggest to not select any file outside the "strip\_prefix"
632 and explicitly "unmark" parent directories when using strip\_prefix and
633 add\_prefix together to relocate files.
634 \item [add\_suffix=.old] -- add a suffix to all your files.
635 \item [regexwhere=!a.pdf!a.bkp.pdf!] -- do complex filename manipulation
636 like with \btool{sed} unix command. Will overwrite other filename manipulation.
637 \item [restorejob=jobname] -- Pre-chooses a restore job. \bacula{} can be
638 configured with multiple restore jobs ("Type = Restore" in the job
639 definition). This allows the specification of different restore properties,
640 including a set of RunScripts. When more than one job of this type is
641 configured, during restore, \bacula{} will ask for a user selection
642 interactively, or use the given restorejob.
643 \item [objectid=id] -- specify an Object to be restored
644 \end{bdescription}
645
646 \label{blb:restorefilerelocation}
647 \section{Using File Relocation}
648 \index[general]{Using File Relocation}
649 \label{blb:filerelocation}
650
651 \subsection{Introduction}
652
653 The \textbf{where=} option is simple, but not very powerful. With file
654 relocation, \bacula{} can restore a file to the same directory, but with a
655 different name, or in an other directory without recreating the full path.
656
657 You can also do filename and path manipulations, implemented in \bacula{}
658 2.1.8 or later, such as adding a suffix to all your files, renaming files
659 or directories, etc. Theses options will overwrite \textbf{where=} option.
660
661
662 For example, many users use OS snapshot features so that file
663 \texttt{/home/eric/mbox} will be backed up from the directory
664 \texttt{/.snap/home/eric/mbox}, which can complicate restores. If you use
665 \textbf{where=/tmp}, the file will be restored to
666 \texttt{/tmp/.snap/home/eric/mbox} and you will have to move the file to
667 \texttt{/home/eric/mbox.bkp} by hand.
668
669 However, case, you could use the
670 \textbf{strip\_prefix=/.snap} and \textbf{add\_suffix=.bkp} options and
671 \bacula{} will restore the file to its original location -- that is
672 \texttt{/home/eric/mbox}.
673
674 To use this feature, there are command line options as described in
675 the \bilink{restore section}{blb:restorefilerelocation} of this manual;
676 you can modify your restore job before running it; or you can
677 add options to your restore job in as described in
678 \bilink{bacula-dir.conf}{blb:confaddprefix}.
679
680 \begin{bVerbatim}
681 Parameters to modify:
682 1: Level
683 2: Storage
684 ...
685 10: File Relocation
686 ...
687 Select parameter to modify (1-12):
688
689
690 This will replace your current Where value
691 1: Strip prefix
692 2: Add prefix
693 3: Add file suffix
694 4: Enter a regexp
695 5: Test filename manipulation
696 6: Use this ?
697 Select parameter to modify (1-6):
698 \end{bVerbatim}
699
700
701 \subsection{RegexWhere Format}\label{useregexwhere}
702
703 The format is very close to that used by sed or Perl (\texttt{s/replace this/by
704 that/}) operator. A valid regexwhere expression has three fields :
705 \begin{bitemize}
706 \item a search expression (with optionnal submatch)
707 \item a replacement expression (with optionnal back references \$1 to \$9)
708 \item a set of search options (only case-insensitive ``i'' at this time)
709 \end{bitemize}
710
711 Each field is delimited by a separator specified by the user as the first
712 character of the expression. The separator can be one of the following:
713 \begin{bVerbatim}
714 <separator-keyword> = / ! ; % : , ~ # = &
715 \end{bVerbatim}
716
717 You can use several expressions separated by a commas.
718
719 \subsection*{Examples}
720
721 \LTXtable{\linewidth}{t-main-regexp}
722
723 %\subsubsection{Using group}
724 %
725 %Like with Perl or Sed, you can make submatch with \texttt{()},
726 %
727 %\subsubsection*{Examples}
728
729
730 %\subsubsection{Options}
731 %
732 % i Do case-insensitive pattern matching.
733
734 \section{Restoring Directory Attributes}
735 \index[general]{Attributes!Restoring Directory }
736 \index[general]{Restoring Directory Attributes }
737
738 Depending how you do the restore, you may or may not get the directory entries
739 back to their original state. Here are a few of the problems you can
740 encounter, and for same machine restores, how to avoid them.
741
742 \begin{bitemize}
743 \item You backed up on one machine and are restoring to another that is
744 either a different OS or doesn't have the same users/groups defined. \bacula{}
745 does the best it can in these situations. Note, \bacula{} has saved the
746 user/groups in numeric form, which means on a different machine, they
747 may map to different user/group names.
748
749 \item You are restoring into a directory that is already created and has
750 file creation restrictions. \bacula{} tries to reset everything but
751 without walking up the full chain of directories and modifying them all
752 during the restore, which \bacula{} does and will not do, getting
753 permissions back correctly in this situation depends to a large extent
754 on your OS.
755
756 \item You are doing a recursive restore of a directory tree. In this case
757 \bacula{} will restore a file before restoring the file's parent directory
758 entry. In the process of restoring the file \bacula{} will create the
759 parent directory with open permissions and ownership of the file being
760 restored. Then when \bacula{} tries to restore the parent directory \bacula{}
761 sees that it already exists (Similar to the previous situation). If you
762 had set the Restore job's "Replace" property to "never" then \bacula{} will
763 not change the directory's permissions and ownerships to match what it
764 backed up, you should also notice that the actual number of files
765 restored is less then the expected number. If you had set the Restore
766 job's "Replace" property to "always" then \bacula{} will change the
767 Directory's ownership and permissions to match what it backed up, also
768 the actual number of files restored should be equal to the expected
769 number.
770
771 \item You selected one or more files in a directory, but did not select the
772 directory entry to be restored. In that case, if the directory is not
773 on disk \bacula{} simply creates the directory with some default attributes
774 which may not be the same as the original. If you do not select a
775 directory and all its contents to be restored, you can still select
776 items within the directory to be restored by individually marking those
777 files, but in that case, you should individually use the \bcommandname{markdir}
778 command to select all higher level directory entries (one at a time) to
779 be restored if you want the directory entries properly restored.
780
781 \item The \btool{bextract} program does not restore access control lists
782 (ACLs) to Unix machines.
783 \end{bitemize}
784
785 \label{blb:Windows}
786 \section{Restoring on Windows}
787 \index[general]{Restoring on Windows }
788 \index[general]{Windows!Restoring on }
789
790 If you are restoring on WinNT/2K/XP systems, \bacula{} will restore the files
791 with the original ownerships and permissions as would be expected. This is
792 also true if you are restoring those files to an alternate directory (using
793 the Where option in restore). However, if the alternate directory does not
794 already exist, the \bacula{} File daemon (Client) will try to create it. In
795 some cases, it may not create the directories, and if it does since the
796 File daemon runs under the SYSTEM account, the directory will be created
797 with SYSTEM ownership and permissions. In this case, you may have problems
798 accessing the newly restored files.
799
800 To avoid this problem, you should create any alternate directory before
801 doing the restore. \bacula{} will not change the ownership and permissions of
802 the directory if it is already created as long as it is not one of the
803 directories being restored (i.e. written to tape).
804
805 The default restore location is \bdirectoryname{/tmp/bacula-restores/} and if you are
806 restoring from drive \bdirectoryname{E:}, the default will be
807 \bdirectoryname{/tmp/bacula-restores/e/}, so you should ensure that this directory
808 exists before doing the restore, or use the \textbf{mod} option to
809 select a different \textbf{where} directory that does exist.
810
811 Some users have experienced problems restoring files that participate in
812 the Active Directory. They also report that changing the userid under which
813 \bacula{} (bacula-fd.exe) runs, from SYSTEM to a Domain Admin userid, resolves
814 the problem.
815
816
817 \section{Restoring Files Can Be Slow}
818 \index[general]{Slow!Restoring Files Can Be }
819 \index[general]{Restoring Files Can Be Slow }
820
821 Restoring files is generally \textbf{much} slower than backing them up for several
822 reasons. The first is that during a backup the tape is normally already
823 positioned and \bacula{} only needs to write. On the other hand, because restoring
824 files is done so rarely, \bacula{} keeps only the start file and block on the
825 tape for the whole job rather than on a file by file basis which would use
826 quite a lot of space in the catalog.
827
828 \bacula{} will forward space to the correct file mark on the tape for the Job,
829 then forward space to the correct block, and finally sequentially read each
830 record until it gets to the correct one(s) for the file or files you want to
831 restore. Once the desired files are restored, \bacula{} will stop reading the
832 tape.
833
834 Finally, instead of just reading a file for backup, during the restore, \bacula{}
835 must create the file, and the operating system must allocate disk space for
836 the file as \bacula{} is restoring it.
837
838 For all the above reasons the restore process is generally much slower than
839 backing up (sometimes it takes three times as long).
840
841 \section{Problems Restoring Files}
842 \index[general]{Files!Problems Restoring }
843 \index[general]{Problems Restoring Files }
844
845 The most frequent problems users have restoring files are error messages such
846 as:
847
848 \begin{bVerbatim}
849 04-Jan 00:33 z217-sd: RestoreFiles.2005-01-04_00.31.04 Error:
850 block.c:868 Volume data error at 20:0! Short block of 512 bytes on
851 device /dev/tape discarded.
852 \end{bVerbatim}
853
854 or
855
856 \begin{bVerbatim}
857 04-Jan 00:33 z217-sd: RestoreFiles.2005-01-04_00.31.04 Error:
858 block.c:264 Volume data error at 20:0! Wanted ID: "BB02", got ".".
859 Buffer discarded.
860 \end{bVerbatim}
861
862 Both these kinds of messages indicate that you were probably running your tape
863 drive in fixed block mode rather than variable block mode. Fixed block mode
864 will work with any program that reads tapes sequentially such as tar, but
865 \bacula{} repositions the tape on a block basis when restoring files because this
866 will speed up the restore by orders of magnitude when only a few files are being
867 restored. There are several ways that you can attempt to recover from this
868 unfortunate situation.
869
870 Try the following things, each separately, and reset your Device resource to
871 what it is now after each individual test:
872
873 \begin{benumerate}
874 \item Set "Block Positioning = no" in your Device resource and try the
875 restore. This is a new directive and untested.
876
877 \item Set "Minimum Block Size = 512" and "Maximum Block Size = 512" and
878 try the restore. If you are able to determine the block size your drive
879 was previously using, you should try that size if 512 does not work.
880 This is a really horrible solution, and it is not at all recommended
881 to continue backing up your data without correcting this condition.
882 Please see the Tape Testing chapter for more on this.
883
884 \item Try editing the restore.bsr file at the Run xxx yes/mod/no prompt
885 before starting the restore job and remove all the VolBlock statements.
886 These are what causes \bacula{} to reposition the tape, and where problems
887 occur if you have a fixed block size set for your drive. The VolFile
888 commands also cause repositioning, but this will work regardless of the
889 block size.
890
891 \item Use bextract to extract the files you want -- it reads the Volume
892 sequentially if you use the include list feature, or if you use a .bsr
893 file, but remove all the VolBlock statements after the .bsr file is
894 created (at the Run yes/mod/no) prompt but before you start the restore.
895 \end{benumerate}
896
897 \section{Restore Errors}
898 \index[general]{Errors!Restore}
899 \index[general]{Restore Errors}
900
901 There are a number of reasons why there may be restore errors or
902 warning messages. Some of the more common ones are:
903
904 \begin{bdescription}
905
906 \item [file count mismatch]
907 This can occur for the following reasons:
908 \begin{bitemize}
909 \item You requested \bacula{} not to overwrite existing or newer
910 files.
911 \item A \bacula{} miscount of files/directories. This is an
912 on-going problem due to the complications of directories,
913 soft/hard link, and such. Simply check that all the files you
914 wanted were actually restored.
915 \end{bitemize}
916
917 \item [file size error]
918 When \bacula{} restores files, it checks that the size of the
919 restored file is the same as the file status data it saved
920 when starting the backup of the file. If the sizes do not
921 agree, \bacula{} will print an error message. This size mismatch
922 most often occurs because the file was being written as \bacula{}
923 backed up the file. In this case, the size that \bacula{}
924 restored will be greater than the status size. This often
925 happens with log files.
926
927 If the restored size is smaller, then you should be concerned
928 about a possible tape error and check the \bacula{} output as
929 well as your system logs.
930 \end{bdescription}
931
932
933
934 \section{Example Restore Job Resource}
935 \index[general]{Example Restore Job Resource }
936 \index[general]{Resource!Example Restore Job }
937
938 \begin{bVerbatim}
939 Job {
940 Name = "RestoreFiles"
941 Type = Restore
942 Client = Any-client
943 FileSet = "Any-FileSet"
944 Storage = Any-storage
945 Where = /tmp/bacula-restores
946 Messages = Standard
947 Pool = Default
948 }
949 \end{bVerbatim}
950
951 If \textbf{Where} is not specified, the default location for restoring files will
952 be their original locations.
953 \label{blb:Selection}
954
955 \section{File Selection Commands}
956 \index[general]{Commands!File Selection }
957 \index[general]{File Selection Commands }
958
959 After you have selected the Jobs to be restored and \bacula{} has created the
960 in-memory directory tree, you will enter file selection mode as indicated by
961 the dollar sign (\textbf{\$}) prompt. While in this mode, you may use the
962 commands listed above. The basic idea is to move up and down the in memory
963 directory structure with the \bcommandname{cd} command much as you normally do on the
964 system. Once you are in a directory, you may select the files that you want
965 restored. As a default no files are marked to be restored. If you wish to
966 start with all files, simply enter: \bcommandname{cd /} and \bcommandname{mark *}. Otherwise
967 proceed to select the files you wish to restore by marking them with the \bcommandname{mark}
968 command. The available commands are:
969
970 \begin{bdescription}
971
972 \item [cd]
973 The \bcommandname{cd} command changes the current directory to the argument specified.
974 It operates much like the Unix \bcommandname{cd} command. Wildcard specifications are
975 not permitted.
976
977 Note, on Windows systems, the various drives (c:, d:, \ldots{}) are treated like a
978 directory within the file tree while in the file selection mode. As a
979 consequence, you must do a \bcommandname{cd c:} or possibly in some cases a \bcommandname{cd C:} (note upper case) to get down to the first directory.
980
981 \item [dir]
982 \index[dir]{dir }
983 The \bcommandname{dir} command is similar to the \bcommandname{ls} command, except that it
984 prints it in long format (all details). This command can be a bit slower
985 than the \bcommandname{ls} command because it must access the catalog database for
986 the detailed information for each file.
987
988 \item [estimate]
989 \index[dir]{estimate }
990 The \bcommandname{estimate} command prints a summary of the total files in the tree,
991 how many are marked to be restored, and an estimate of the number of bytes
992 to be restored. This can be useful if you are short on disk space on the
993 machine where the files will be restored.
994
995 \item [find]
996 \index[dir]{find}
997 The \bcommandname{find} command accepts one or more arguments and displays all files
998 in the tree that match that argument. The argument may have wildcards. It is
999 somewhat similar to the Unix command \bcommandname{find / -name arg}.
1000
1001 \item [ls]
1002 The \bcommandname{ls} command produces a listing of all the files contained in the
1003 current directory much like the Unix \bcommandname{ls} command. You may specify an
1004 argument containing wildcards, in which case only those files will be
1005 listed.
1006
1007 Any file that is marked to be restored will have its name preceded by an
1008 asterisk (\textbf{*}). Directory names will be terminated with a forward slash
1009 (\textbf{/}) to distinguish them from filenames.
1010
1011 \item [du]
1012 The \bcommandname{du} command is similar to the \bcommandname{ls} command but it also prints size of each file directory listed.
1013 For directory it is just a sum of all files sizes in all directories below.
1014
1015 \item [lsmark]
1016 \index[fd]{lsmark}
1017 The \bcommandname{lsmark} command is the same as the \bcommandname{ls} except that it will
1018 print only those files marked for extraction. The other distinction is that
1019 it will recursively descend into any directory selected.
1020
1021 \item [mark]
1022 \index[dir]{mark}
1023 The \bcommandname{mark} command allows you to mark files to be restored. It takes a
1024 single argument which is the filename or directory name in the current
1025 directory to be marked for extraction. The argument may be a wildcard
1026 specification, in which case all files that match in the current directory
1027 are marked to be restored. If the argument matches a directory rather than a
1028 file, then the directory and all the files contained in that directory
1029 (recursively) are marked to be restored. Any marked file will have its name
1030 preceded with an asterisk (\textbf{*}) in the output produced by the \bcommandname{ls}
1031 or
1032 \bcommandname{dir} commands. Note, supplying a full path on the mark command does not
1033 work as expected to select a file or directory in the current directory.
1034 Also, the \bcommandname{mark} command works on the current and lower directories but
1035 does not touch higher level directories.
1036
1037 After executing the \bcommandname{mark} command, it will print a brief summary:
1038
1039 \begin{bVerbatim}
1040 No files marked.
1041 \end{bVerbatim}
1042
1043 If no files were marked, or:
1044
1045 \begin{bVerbatim}
1046 nn files marked.
1047 \end{bVerbatim}
1048
1049 if some files are marked.
1050
1051 \item [unmark]
1052 \index[dir]{unmark }
1053 The \bcommandname{unmark} is identical to the \bcommandname{mark} command, except that it
1054 unmarks the specified file or files so that they will not be restored. Note:
1055 the \bcommandname{unmark} command works from the current directory, so it does not
1056 unmark any files at a higher level. First do a \bcommandname{cd /} before the
1057 \bcommandname{unmark *} command if you want to unmark everything.
1058
1059 \item [pwd]
1060 \index[dir]{pwd }
1061 The \bcommandname{pwd} command prints the current working directory. It accepts no
1062 arguments.
1063
1064 \item [count]
1065 \index[dir]{count }
1066 The \bcommandname{count} command prints the total files in the directory tree and the
1067 number of files marked to be restored.
1068
1069 \item [done]
1070 \index[dir]{done }
1071 This command terminates file selection mode.
1072
1073 \item [exit]
1074 \index[fd]{exit }
1075 This command terminates file selection mode (the same as done).
1076
1077 \item [quit]
1078 \index[fd]{quit }
1079 This command terminates the file selection and does not run the restore
1080 job.
1081
1082
1083 \item [help]
1084 \index[fd]{help }
1085 This command prints a summary of the commands available.
1086
1087 \item [?]
1088 This command is the same as the \bcommandname{help} command.
1089 \end{bdescription}
1090
1091 If your filename contains some weird caracters, you can use \texttt{?},
1092 \texttt{*} or \textbackslash{}\textbackslash{}. For example, if your filename
1093 contains a \textbackslash{}, you can use
1094 \textbackslash{}\textbackslash{}\textbackslash{}\textbackslash{}.
1095
1096 \begin{bVerbatim}
1097 * mark weird_file\\\\with-backslash
1098 \end{bVerbatim}
1099
1100 \label{blb:database_restore}
1101 \section{Restoring When Things Go Wrong}
1102 \index[general]{Restoring When Things Go Wrong }
1103 \index[general]{Restoring Your Database}
1104 \index[general]{Database!Restoring}
1105
1106 This and the following sections will try to present a few of the kinds of
1107 problems that can come up making restoring more difficult. We will try to
1108 provide a few ideas how to get out of these problem situations.
1109 In addition to what is presented here, there is more specific information
1110 on restoring a \bilink{Client}{blb:restore_client} and your
1111 \bilink{Server}{blb:restore_server} in the
1112 \bilink{Disaster Recovery Using \bacula{}}{blb:RescueChapter} chapter of this manual.
1113
1114 \begin{bdescription}
1115 \item[Problem]
1116 My database is broken.
1117 \item[Solution]
1118 For either \mysql{} or \postgresql{}, see the vendor's documentation. They have specific tools
1119 that check and repair databases, see the
1120 \bilink{database repair}{blb:DatabaseRepair} sections of this manual for links to vendor
1121 information.
1122
1123 Assuming the above does not resolve the problem, you will need to restore
1124 or rebuild your catalog. Note, if it is a matter of some
1125 inconsistencies in the \bacula{} tables rather than a broken database, then
1126 running the \bxlink{dbcheck}{blb:dbcheck}{utility}{command}\footnote{\butilityman{}}
1127 might help, but you will need to ensure
1128 that your database indexes are properly setup. Please see
1129 the \bilink{Database Performance Issues}{blb:DatabasePerformance} sections
1130 of this manual for more details.
1131
1132 \item[Problem]
1133 How do I restore my catalog?
1134 \item[Solution with a Catalog backup]
1135 If you have backed up your database nightly (as you should) and you
1136 have made a bootstrap file, you can immediately load back your
1137 database (or the ASCII SQL output). Make a copy of your current
1138 database, then re-initialize it, by running the following scripts:
1139 \begin{bVerbatim}
1140 ./drop_bacula_tables
1141 ./make_bacula_tables
1142 \end{bVerbatim}
1143 After re-initializing the database, you should be able to run
1144 \bacula{}. If you now try to use the \bcommandname{restore} command, it will not
1145 work because the database will be empty. However, you can manually
1146 run a restore job and specify your bootstrap file. You do so
1147 by entering the \bcommandname{run} command in the console and selecting the
1148 restore job. If you are using the default \bfilename{bacula-dir.conf}, this
1149 Job will be named \textbf{RestoreFiles}. Most likely it will prompt
1150 you with something such as:
1151
1152 \begin{bVerbatim}
1153 Run Restore job
1154 JobName: RestoreFiles
1155 Bootstrap: /home/kern/bacula/working/restore.bsr
1156 Where: /tmp/bacula-restores
1157 Replace: always
1158 FileSet: Full Set
1159 Client: rufus-fd
1160 Storage: File
1161 When: 2005-07-10 17:33:40
1162 Catalog: MyCatalog
1163 Priority: 10
1164 OK to run? (yes/mod/no):
1165 \end{bVerbatim}
1166
1167 A number of the items will be different in your case. What you want to
1168 do is: to use the mod option to change the Bootstrap to point to your
1169 saved bootstrap file; and to make sure all the other items such as
1170 Client, Storage, Catalog, and Where are correct. The FileSet is not
1171 used when you specify a bootstrap file. Once you have set all the
1172 correct values, run the Job and it will restore the backup of your
1173 database, which is most likely an ASCII dump.
1174
1175 You will then need to follow the instructions for your
1176 database type to recreate the database from the ASCII backup file.
1177 See the \bilink{Catalog Maintenance}{blb:CatMaintenanceChapter} chapter of
1178 this manual for examples of the command needed to restore a
1179 database from an ASCII dump (they are shown in the Compacting Your
1180 XXX Database sections).
1181
1182 Also, please note that after you restore your database from an ASCII
1183 backup, you do NOT want to do a \btool{make\_bacula\_tables} command, or
1184 you will probably erase your newly restored database tables.
1185
1186
1187 \item[Solution with a Job listing]
1188 If you did save your database but did not make a bootstrap file, then
1189 recovering the database is more difficult. You will probably need to
1190 use bextract to extract the backup copy. First you should locate the
1191 listing of the job report from the last catalog backup. It has
1192 important information that will allow you to quickly find your database
1193 file. For example, in the job report for the CatalogBackup shown below,
1194 the critical items are the Volume name(s), the Volume Session Id and the
1195 Volume Session Time. If you know those, you can easily restore your
1196 Catalog.
1197
1198 \begin{bVerbatim}
1199 22-Apr 10:22 HeadMan: Start Backup JobId 7510,
1200 Job=CatalogBackup.2005-04-22_01.10.0
1201 22-Apr 10:23 HeadMan: \bacula{} 1.37.14 (21Apr05): 22-Apr-2005 10:23:06
1202 JobId: 7510
1203 Job: CatalogBackup.2005-04-22_01.10.00
1204 Backup Level: Full
1205 Client: Polymatou
1206 FileSet: "CatalogFile" 2003-04-10 01:24:01
1207 Pool: "Default"
1208 Storage: "DLTDrive"
1209 Start time: 22-Apr-2005 10:21:00
1210 End time: 22-Apr-2005 10:23:06
1211 FD Files Written: 1
1212 SD Files Written: 1
1213 FD Bytes Written: 210,739,395
1214 SD Bytes Written: 210,739,521
1215 Rate: 1672.5 KB/s
1216 Software Compression: None
1217 Volume name(s): DLT-22Apr05
1218 Volume Session Id: 11
1219 Volume Session Time: 1114075126
1220 Last Volume Bytes: 1,428,240,465
1221 Non-fatal FD errors: 0
1222 SD Errors: 0
1223 FD termination status: OK
1224 SD termination status: OK
1225 Termination: Backup OK
1226 \end{bVerbatim}
1227
1228 From the above information, you can manually create a bootstrap file,
1229 and then follow the instructions given above for restoring your database.
1230 A reconstructed bootstrap file for the above backup Job would look
1231 like the following:
1232
1233 \begin{bVerbatim}
1234 Volume="DLT-22Apr05"
1235 VolSessionId=11
1236 VolSessionTime=1114075126
1237 FileIndex=1-1
1238 \end{bVerbatim}
1239
1240 Where we have inserted the Volume name, Volume Session Id, and Volume
1241 Session Time that correspond to the values in the job report. We've also
1242 used a FileIndex of one, which will always be the case providing that
1243 there was only one file backed up in the job.
1244
1245 The disadvantage of this bootstrap file compared to what is created when
1246 you ask for one to be written, is that there is no File and Block
1247 specified, so the restore code must search all data in the Volume to find
1248 the requested file. A fully specified bootstrap file would have the File
1249 and Blocks specified as follows:
1250
1251 \begin{bVerbatim}
1252 Volume="DLT-22Apr05"
1253 VolSessionId=11
1254 VolSessionTime=1114075126
1255 VolFile=118-118
1256 VolBlock=0-4053
1257 FileIndex=1-1
1258 \end{bVerbatim}
1259
1260 Once you have restored the ASCII dump of the database,
1261 you will then to follow the instructions for your
1262 database type to recreate the database from the ASCII backup file.
1263 See the \bilink{Catalog Maintenance}{blb:CatMaintenanceChapter} chapter of
1264 this manual for examples of the command needed to restore a
1265 database from an ASCII dump (they are shown in the Compacting Your
1266 XXX Database sections).
1267
1268 Also, please note that after you restore your database from an ASCII
1269 backup, you do NOT want to do a \btool{make\_bacula\_tables} command, or
1270 you will probably erase your newly restored database tables.
1271
1272 \item [Solution without a Job Listing]
1273 If you do not have a job listing, then it is a bit more difficult.
1274 Either you use the \bxlink{bscan}{blb:bscan}{utility}{program}
1275 to scan the contents
1276 of your tape into a database, which can be very time consuming
1277 depending on the size of the tape, or you can use the \bxlink{bls}{blb:bls}{utility}{program}
1278 to list everything on the tape, and reconstruct a
1279 bootstrap file from the bls listing for the file or files you want following
1280 the instructions given above.
1281
1282 There is a specific example of how to use \btool{bls} below.
1283
1284 \item [Problem]
1285 I try to restore the last known good full backup by specifying
1286 item 3 on the restore menu then the JobId to restore. \bacula{}
1287 then reports:
1288
1289 \begin{bVerbatim}
1290 1 Job 0 Files
1291 \end{bVerbatim}
1292 and restores nothing.
1293
1294 \item[Solution]
1295 Most likely the File records were pruned from the database either due
1296 to the File Retention period expiring or by explicitly purging the
1297 Job. By using the \bcommandname{llist jobid=nn} command, you can obtain all the
1298 important information about the job:
1299
1300 \begin{bVerbatim}
1301 llist jobid=120
1302 JobId: 120
1303 Job: save.2005-12-05_18.27.33
1304 Job.Name: save
1305 PurgedFiles: 0
1306 Type: B
1307 Level: F
1308 Job.ClientId: 1
1309 Client.Name: Rufus
1310 JobStatus: T
1311 SchedTime: 2005-12-05 18:27:32
1312 StartTime: 2005-12-05 18:27:35
1313 EndTime: 2005-12-05 18:27:37
1314 JobTDate: 1133803657
1315 VolSessionId: 1
1316 VolSessionTime: 1133803624
1317 JobFiles: 236
1318 JobErrors: 0
1319 JobMissingFiles: 0
1320 Job.PoolId: 4
1321 Pool.Name: Full
1322 Job.FileSetId: 1
1323 FileSet.FileSet: BackupSet
1324 \end{bVerbatim}
1325
1326 Then you can find the Volume(s) used by doing:
1327
1328 \begin{bVerbatim}
1329 sql
1330 select VolumeName from JobMedia,Media where JobId=1 and JobMedia.MediaId=Media.MediaId;
1331 \end{bVerbatim}
1332
1333 Finally, you can create a bootstrap file as described in the previous
1334 problem above using this information.
1335
1336 If you are using \bacula{} version 1.38.0 or greater, when you select
1337 item 3 from the menu and enter the JobId, it will ask you if
1338 you would like to restore all the files in the job, and it will
1339 collect the above information and write the bootstrap file for
1340 you.
1341
1342 \item [Problem]
1343 You don't have a bootstrap file, and you don't have the Job report for
1344 the backup of your database, but you did backup the database, and you
1345 know the Volume to which it was backed up.
1346
1347 \item [Solution]
1348 Either bscan the tape (see below for bscanning), or better use \btool{bls}
1349 to find where it is on the tape, then use \btool{bextract} to
1350 restore the database. For example,
1351
1352
1353 \begin{bVerbatim}
1354 ./bls -j -V DLT-22Apr05 /dev/nst0
1355 \end{bVerbatim}
1356 Might produce the following output:
1357 \begin{bVerbatim}
1358 bls: butil.c:258 Using device: "/dev/nst0" for reading.
1359 21-Jul 18:34 bls: Ready to read from volume "DLT-22Apr05" on device "DLTDrive"
1360 (/dev/nst0).
1361 Volume Record: File:blk=0:0 SessId=11 SessTime=1114075126 JobId=0 DataLen=164
1362 ...
1363 Begin Job Session Record: File:blk=118:0 SessId=11 SessTime=1114075126
1364 JobId=7510
1365 Job=CatalogBackup.2005-04-22_01.10.0 Date=22-Apr-2005 10:21:00 Level=F Type=B
1366 End Job Session Record: File:blk=118:4053 SessId=11 SessTime=1114075126
1367 JobId=7510
1368 Date=22-Apr-2005 10:23:06 Level=F Type=B Files=1 Bytes=210,739,395 Errors=0
1369 Status=T
1370 ...
1371 21-Jul 18:34 bls: End of Volume at file 201 on device "DLTDrive" (/dev/nst0),
1372 Volume "DLT-22Apr05"
1373 21-Jul 18:34 bls: End of all volumes.
1374 \end{bVerbatim}
1375 Of course, there will be many more records printed, but we have indicated
1376 the essential lines of output. From the information on the Begin Job and End
1377 Job Session Records, you can reconstruct a bootstrap file such as the one
1378 shown above.
1379
1380 \item[Problem]
1381 How can I find where a file is stored.
1382 \item[Solution]
1383 Normally, it is not necessary, you just use the \bcommandname{restore} command to
1384 restore the most recently saved version (menu option 5), or a version
1385 saved before a given date (menu option 8). If you know the JobId of the
1386 job in which it was saved, you can use menu option 3 to enter that JobId.
1387
1388 If you would like to know the JobId where a file was saved, select
1389 restore menu option 2.
1390
1391 You can also use the \bcommandname{query} command to find information such as:
1392 \begin{bVerbatim}
1393 *query
1394 Available queries:
1395 1: List up to 20 places where a File is saved regardless of the
1396 directory
1397 2: List where the most recent copies of a file are saved
1398 3: List last 20 Full Backups for a Client
1399 4: List all backups for a Client after a specified time
1400 5: List all backups for a Client
1401 6: List Volume Attributes for a selected Volume
1402 7: List Volumes used by selected JobId
1403 8: List Volumes to Restore All Files
1404 9: List Pool Attributes for a selected Pool
1405 10: List total files/bytes by Job
1406 11: List total files/bytes by Volume
1407 12: List Files for a selected JobId
1408 13: List Jobs stored on a selected MediaId
1409 14: List Jobs stored for a given Volume name
1410 15: List Volumes \bacula{} thinks are in changer
1411 16: List Volumes likely to need replacement from age or errors
1412 Choose a query (1-16):
1413 \end{bVerbatim}
1414
1415 \item[Problem]
1416 I didn't backup my database. What do I do now?
1417 \item[Solution]
1418 This is probably the worst of all cases, and you will probably have
1419 to re-create your database from scratch and then bscan in all your
1420 Volumes, which is a very long, painful, and inexact process.
1421
1422 There are basically three steps to take:
1423
1424 \begin{benumerate}
1425 \item Ensure that your SQL server is running (\mysql{} or \postgresql{})
1426 and that the \bacula{} database (normally bacula) exists. See the
1427 \bilink{Installation}{blb:CreateDatabase} chapter of the manual.
1428 \item Ensure that the \bacula{} databases are created. This is also
1429 described at the above link.
1430 \item Start and stop the \bacula{} Director using the propriate
1431 \bfilename{bacula-dir.conf} file so that it can create the Client and
1432 Storage records which are not stored on the Volumes. Without these
1433 records, scanning is unable to connect the Job records to the proper
1434 client.
1435 \end{benumerate}
1436
1437 When the above is complete, you can begin bscanning your Volumes. Please
1438 see the \bxlink{bscan}{blb:bscan}{utility}{section} of the \butilityman{}.
1439
1440 \end{bdescription}