3 \chapter{The Restore Command}
5 \index[general]{Command!Console Restore}
6 \index[general]{Console Restore Command}
9 \index[general]{General }
11 Below, we will discuss restoring files with the Console {\bf restore} command,
12 which is the recommended way of doing restoring files. It is not possible
13 to restore files by automatically starting a job as you do with Backup,
14 Verify, ... jobs. However, in addition to the console restore command,
15 there is a standalone program named {\bf bextract}, which also permits
16 restoring files. For more information on this program, please see the
17 \ilink{Bacula Utility Programs}{bextract} chapter of this manual. We
18 don't particularly recommend the {\bf bextract} program because it
19 lacks many of the features of the normal Bacula restore, such as the
20 ability to restore Win32 files to Unix systems, and the ability to
21 restore access control lists (ACL). As a consequence, we recommend,
22 wherever possible to use Bacula itself for restores as described below.
24 You may also want to look at the {\bf bls} program in the same chapter,
25 which allows you to list the contents of your Volumes. Finally, if you
26 have an old Volume that is no longer in the catalog, you can restore the
27 catalog entries using the program named {\bf bscan}, documented in the same
28 \ilink{Bacula Utility Programs}{bscan} chapter.
30 In general, to restore a file or a set of files, you must run a {\bf restore}
31 job. That is a job with {\bf Type = Restore}. As a consequence, you will need
32 a predefined {\bf restore} job in your {\bf bacula-dir.conf} (Director's
33 config) file. The exact parameters (Client, FileSet, ...) that you define are
34 not important as you can either modify them manually before running the job or
35 if you use the {\bf restore} command, explained below, Bacula will
36 automatically set them for you. In fact, you can no longer simply run a restore
37 job. You must use the restore command.
39 Since Bacula is a network backup program, you must be aware that when you
40 restore files, it is up to you to ensure that you or Bacula have selected the
41 correct Client and the correct hard disk location for restoring those files.
42 {\bf Bacula} will quite willingly backup client A, and restore it by sending
43 the files to a different directory on client B. Normally, you will want to
44 avoid this, but assuming the operating systems are not too different in their
45 file structures, this should work perfectly well, if so desired.
46 By default, Bacula will restore data to the same Client that was backed
47 up, and those data will be restored not to the original places but to
48 {\bf /tmp/bacula-restores}. You may modify any of these defaults when the
49 restore command prompts you to run the job by selecting the {\bf mod}
53 \section{The Restore Command}
54 \index[general]{Command!Restore}
55 \index[general]{Restore Command}
57 Since Bacula maintains a catalog of your files and on which Volumes (disk or
58 tape), they are stored, it can do most of the bookkeeping work, allowing you
59 simply to specify what kind of restore you want (current, before a particular
60 date), and what files to restore. Bacula will then do the rest.
62 This is accomplished using the {\bf restore} command in the Console. First you
63 select the kind of restore you want, then the JobIds are selected,
64 the File records for those Jobs are placed in an internal Bacula directory
65 tree, and the restore enters a file selection mode that allows you to
66 interactively walk up and down the file tree selecting individual files to be
67 restored. This mode is somewhat similar to the standard Unix {\bf restore}
68 program's interactive file selection mode.
70 If a Job's file records have been pruned from the catalog, the {\bf restore}
71 command will be unable to find any files to restore. Bacula will ask if you
72 want to restore all of them or if you want to use a regular expression to
73 restore only a selection while reading media. See \ilink{FileRegex
74 option}{FileRegex} and below for more details on this.
76 Within the Console program, after entering the {\bf restore} command, you are
77 presented with the following selection prompt:
81 First you select one or more JobIds that contain files
82 to be restored. You will be presented several methods
83 of specifying the JobIds. Then you will be allowed to
84 select which files from those JobIds are to be restored.
85 To select the JobIds, you have the following choices:
86 1: List last 20 Jobs run
87 2: List Jobs where a given File is saved
88 3: Enter list of comma separated JobIds to select
89 4: Enter SQL list command
90 5: Select the most recent backup for a client
91 6: Select backup for a client before a specified time
92 7: Enter a list of files to restore
93 8: Enter a list of files to restore before a specified time
94 9: Find the JobIds of the most recent backup for a client
95 10: Find the JobIds for a backup for a client before a specified time
96 11: Enter a list of directories to restore for found JobIds
102 There are a lot of options, and as a point of reference, most people will
103 want to slect item 5 (the most recent backup for a client). The details
104 of the above options are:
107 \item Item 1 will list the last 20 jobs run. If you find the Job you want,
108 you can then select item 3 and enter its JobId(s).
110 \item Item 2 will list all the Jobs where a specified file is saved. If you
111 find the Job you want, you can then select item 3 and enter the JobId.
113 \item Item 3 allows you the enter a list of comma separated JobIds whose
114 files will be put into the directory tree. You may then select which
115 files from those JobIds to restore. Normally, you would use this option
116 if you have a particular version of a file that you want to restore and
117 you know its JobId. The most common options (5 and 6) will not select
118 a job that did not terminate normally, so if you know a file is
119 backed up by a Job that failed (possibly because of a system crash), you
120 can access it through this option by specifying the JobId.
122 \item Item 4 allows you to enter any arbitrary SQL command. This is
123 probably the most primitive way of finding the desired JobIds, but at
124 the same time, the most flexible. Once you have found the JobId(s), you
125 can select item 3 and enter them.
127 \item Item 5 will automatically select the most recent Full backup and all
128 subsequent incremental and differential backups for a specified Client.
129 These are the Jobs and Files which, if reloaded, will restore your
130 system to the most current saved state. It automatically enters the
131 JobIds found into the directory tree in an optimal way such that only
132 the most recent copy of any particular file found in the set of Jobs
133 will be restored. This is probably the most convenient of all the above
134 options to use if you wish to restore a selected Client to its most
137 There are two important things to note. First, this automatic selection
138 will never select a job that failed (terminated with an error status).
139 If you have such a job and want to recover one or more files from it,
140 you will need to explicitly enter the JobId in item 3, then choose the
143 If some of the Jobs that are needed to do the restore have had their
144 File records pruned, the restore will be incomplete. Bacula currently
145 does not correctly detect this condition. You can however, check for
146 this by looking carefully at the list of Jobs that Bacula selects and
147 prints. If you find Jobs with the JobFiles column set to zero, when
148 files should have been backed up, then you should expect problems.
150 If all the File records have been pruned, Bacula will realize that there
151 are no file records in any of the JobIds chosen and will inform you. It
152 will then propose doing a full restore (non-selective) of those JobIds.
153 This is possible because Bacula still knows where the beginning of the
154 Job data is on the Volumes, even if it does not know where particular
155 files are located or what their names are.
157 \item Item 6 allows you to specify a date and time, after which Bacula will
158 automatically select the most recent Full backup and all subsequent
159 incremental and differential backups that started before the specified date
162 \item Item 7 allows you to specify one or more filenames (complete path
163 required) to be restored. Each filename is entered one at a time or if you
164 prefix a filename with the less-than symbol (\lt{}) Bacula will read that
165 file and assume it is a list of filenames to be restored. If you
166 prefix the filename with a question mark (?), then the filename will
167 be interpreted as an SQL table name, and Bacula will include the rows
168 of that table in the list to be restored. The table must contain the
169 JobId in the first column and the FileIndex in the second column.
170 This table feature is intended for external programs that want to build
171 their own list of files to be restored.
172 The filename entry mode is terminated by entering a blank line.
174 \item Item 8 allows you to specify a date and time before entering the
175 filenames. See Item 7 above for more details.
177 \item Item 9 allows you find the JobIds of the most recent backup for
178 a client. This is much like option 5 (it uses the same code), but
179 those JobIds are retained internally as if you had entered them
180 manually. You may then select item 11 (see below) to restore one
183 \item Item 10 is the same as item 9, except that it allows you to enter
184 a before date (as with item 6). These JobIds will then be retained
187 \index[general]{Restore Directories}
188 \item Item 11 allows you to enter a list of JobIds from which you can
189 select directories to be restored. The list of JobIds can have been
190 previously created by using either item 9 or 10 on the menu. You
191 may then enter a full path to a directory name or a filename preceded
192 by a less than sign (\lt{}). The filename should contain a list
193 of directories to be restored. All files in those directories will
194 be restored, but if the directory contains subdirectories, nothing
195 will be restored in the subdirectory unless you explicitly enter its
198 \item Item 12 allows you to cancel the restore command.
201 As an example, suppose that we select item 5 (restore to most recent state).
202 If you have not specified a client=xxx on the command line, it
203 it will then ask for the desired Client, which on my system, will print all
204 the Clients found in the database as follows:
218 Select Client (File daemon) resource (1-9):
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 {\bf Rufus} to select the Client. Then Bacula needs to know what FileSet is
225 to be restored, so it prompts with:
229 The defined FileSet resources are:
232 Select FileSet resource (1-2):
236 If you have only one FileSet defined for the Client, it will be selected
237 automatically. I choose item 1, which is my full backup. Normally, you
238 will only have a single FileSet for each Job, and if your machines are
239 similar (all Linux) you may only have one FileSet for all your Clients.
241 At this point, {\bf Bacula} has all the information it needs to find the most
242 recent set of backups. It will then query the database, which may take a bit
243 of time, and it will come up with something like the following. Note, some of
244 the columns are truncated here for presentation:
248 +-------+------+----------+-------------+-------------+------+-------+------------+
249 | JobId | Levl | JobFiles | StartTime | VolumeName | File | SesId |VolSesTime |
250 +-------+------+----------+-------------+-------------+------+-------+------------+
251 | 1,792 | F | 128,374 | 08-03 01:58 | DLT-19Jul02 | 67 | 18 | 1028042998 |
252 | 1,792 | F | 128,374 | 08-03 01:58 | DLT-04Aug02 | 0 | 18 | 1028042998 |
253 | 1,797 | I | 254 | 08-04 13:53 | DLT-04Aug02 | 5 | 23 | 1028042998 |
254 | 1,798 | I | 15 | 08-05 01:05 | DLT-04Aug02 | 6 | 24 | 1028042998 |
255 +-------+------+----------+-------------+-------------+------+-------+------------+
256 You have selected the following JobId: 1792,1792,1797
257 Building directory tree for JobId 1792 ...
258 Building directory tree for JobId 1797 ...
259 Building directory tree for JobId 1798 ...
265 Depending on the number of {\bf JobFiles} for each JobId, the {\bf Building
266 directory tree ..."} can take a bit of time. If you notice ath all the
267 JobFiles are zero, your Files have probably been pruned and you will not be
268 able to select any individual files -- it will be restore everything or
271 In our example, Bacula found four Jobs that comprise the most recent backup of
272 the specified Client and FileSet. Two of the Jobs have the same JobId because
273 that Job wrote on two different Volumes. The third Job was an incremental
274 backup to the previous Full backup, and it only saved 254 Files compared to
275 128,374 for the Full backup. The fourth Job was also an incremental backup
278 Next Bacula entered those Jobs into the directory tree, with no files marked
279 to be restored as a default, tells you how many files are in the tree, and
280 tells you that the current working directory ({\bf cwd}) is /. Finally, Bacula
281 prompts with the dollar sign (\$) to indicate that you may enter commands to
282 move around the directory tree and to select files.
284 If you want all the files to automatically be marked when the directory
285 tree is built, you could have entered the command {\bf restore all}, or
286 at the \$ prompt, you can simply enter {\bf mark *}.
288 Instead of choosing item 5 on the first menu (Select the most recent backup
289 for a client), if we had chosen item 3 (Enter list of JobIds to select) and we
290 had entered the JobIds {\bf 1792,1797,1798} we would have arrived at the same
293 One point to note, if you are manually entering JobIds, is that you must enter
294 them in the order they were run (generally in increasing JobId order). If you
295 enter them out of order and the same file was saved in two or more of the
296 Jobs, you may end up with an old version of that file (i.e. not the most
299 Directly entering the JobIds can also permit you to recover data from
300 a Job that wrote files to tape but that terminated with an error status.
302 While in file selection mode, you can enter {\bf help} or a question mark (?)
303 to produce a summary of the available commands:
309 cd change current directory
310 count count marked files in and below the cd
311 dir long list current directory, wildcards allowed
312 done leave file selection mode
313 estimate estimate restore size
314 exit same as done command
315 find find files, wildcards allowed
317 ls list current directory, wildcards allowed
318 lsmark list the marked files in and below the cd
319 mark mark dir/file to be restored recursively in dirs
320 markdir mark directory name to be restored (no files)
321 pwd print current working directory
322 unmark unmark dir/file to be restored recursively in dir
323 unmarkdir unmark directory name only no recursion
324 quit quit and do not do restore
329 As a default no files have been selected for restore (unless you
330 added {\bf all} to the command line. If you want to restore
331 everything, at this point, you should enter {\bf mark *}, and then {\bf done}
332 and {\bf Bacula} will write the bootstrap records to a file and request your
333 approval to start a restore job.
335 If you do not enter the above mentioned {\bf mark *} command, you will start
336 with an empty slate. Now you can simply start looking at the tree and {\bf
337 mark} particular files or directories you want restored. It is easy to make
338 a mistake in specifying a file to mark or unmark, and Bacula's error handling
339 is not perfect, so please check your work by using the {\bf ls} or {\bf dir}
340 commands to see what files are actually selected. Any selected file has its
341 name preceded by an asterisk.
343 To check what is marked or not marked, enter the {\bf count} command, which
348 128401 total files. 128401 marked to be restored.
353 Each of the above commands will be described in more detail in the next
354 section. We continue with the above example, having accepted to restore all
355 files as Bacula set by default. On entering the {\bf done} command, Bacula
360 Bootstrap records written to /home/kern/bacula/working/restore.bsr
361 The job will require the following
362 Volume(s) Storage(s) SD Device(s)
363 ===========================================================================
365 DLT-19Jul02 Tape DLT8000
366 DLT-04Aug02 Tape DLT8000
368 128401 files selected to restore.
370 JobName: kernsrestore
371 Bootstrap: /home/kern/bacula/working/restore.bsr
372 Where: /tmp/bacula-restores
377 When: 2006-12-11 18:20:33
380 OK to run? (yes/mod/no):
385 Please examine each of the items very carefully to make sure that they are
386 correct. In particular, look at {\bf Where}, which tells you where in the
387 directory structure the files will be restored, and {\bf Client}, which
388 tells you which client will receive the files. Note that by default the
389 Client which will receive the files is the Client that was backed up.
390 These items will not always be completed with the correct values depending
391 on which of the restore options you chose. You can change any of these
392 default items by entering {\bf mod} and responding to the prompts.
394 The above assumes that you have defined a {\bf Restore} Job resource in your
395 Director's configuration file. Normally, you will only need one Restore Job
396 resource definition because by its nature, restoring is a manual operation,
397 and using the Console interface, you will be able to modify the Restore Job to
400 An example Restore Job resource definition is given below.
402 Returning to the above example, you should verify that the Client name is
403 correct before running the Job. However, you may want to modify some of the
404 parameters of the restore job. For example, in addition to checking the Client
405 it is wise to check that the Storage device chosen by Bacula is indeed
406 correct. Although the {\bf FileSet} is shown, it will be ignored in restore.
407 The restore will choose the files to be restored either by reading the {\bf
408 Bootstrap} file, or if not specified, it will restore all files associated
409 with the specified backup {\bf JobId} (i.e. the JobId of the Job that
410 originally backed up the files).
412 Finally before running the job, please note that the default location for
413 restoring files is {\bf not} their original locations, but rather the directory
414 {\bf /tmp/bacula-restores}. You can change this default by modifying your {\bf
415 bacula-dir.conf} file, or you can modify it using the {\bf mod} option. If you
416 want to restore the files to their original location, you must have {\bf
417 Where} set to nothing or to the root, i.e. {\bf /}.
419 If you now enter {\bf yes}, Bacula will run the restore Job. The Storage
420 daemon will first request Volume {\bf DLT-19Jul02} and after the appropriate
421 files have been restored from that volume, it will request Volume {\bf
424 \subsection{Restore a pruned job using a pattern}
425 During a restore, if all File records are pruned from the catalog
426 for a Job, normally Bacula can restore only all files saved. That
427 is there is no way using the catalog to select individual files.
428 With this new feature, Bacula will ask if you want to specify a Regex
429 expression for extracting only a part of the full backup.
432 Building directory tree for JobId(s) 1,3 ...
433 There were no files inserted into the tree, so file selection
434 is not possible.Most likely your retention policy pruned the files
436 Do you want to restore all the files? (yes|no): no
438 Regexp matching files to restore? (empty to abort): /tmp/regress/(bin|tests)/
439 Bootstrap records written to /tmp/regress/working/zog4-dir.restore.1.bsr
442 See also \ilink{FileRegex bsr option}{FileRegex} for more information.
444 \section{Selecting Files by Filename}
445 \index[general]{Selecting Files by Filename }
446 \index[general]{Filename!Selecting Files by }
448 If you have a small number of files to restore, and you know the filenames,
449 you can either put the list of filenames in a file to be read by Bacula, or
450 you can enter the names one at a time. The filenames must include the full
451 path and filename. No wild cards are used.
453 To enter the files, after the {\bf restore}, you select item number 7 from the
458 To select the JobIds, you have the following choices:
459 1: List last 20 Jobs run
460 2: List Jobs where a given File is saved
461 3: Enter list of comma separated JobIds to select
462 4: Enter SQL list command
463 5: Select the most recent backup for a client
464 6: Select backup for a client before a specified time
465 7: Enter a list of files to restore
466 8: Enter a list of files to restore before a specified time
467 9: Find the JobIds of the most recent backup for a client
468 10: Find the JobIds for a backup for a client before a specified time
469 11: Enter a list of directories to restore for found JobIds
475 which then prompts you for the client name:
483 Select the Client (1-3): 3
487 Of course, your client list will be different, and if you have only one
488 client, it will be automatically selected. And finally, Bacula requests you to
497 At this point, you can enter the full path and filename
501 Enter filename: /home/kern/bacula/k/Makefile.in
506 as you can see, it took the filename. If Bacula cannot find a copy of the
507 file, it prints the following:
511 Enter filename: junk filename
512 No database record found for: junk filename
517 If you want Bacula to read the filenames from a file, you simply precede the
518 filename with a less-than symbol (\lt{}). When you have entered all the
519 filenames, you enter a blank line, and Bacula will write the bootstrap file,
520 tells you what tapes will be used, and proposes a Restore job to be run:
525 Automatically selected Storage: DDS-4
526 Bootstrap records written to /home/kern/bacula/working/restore.bsr
527 The restore job will require the following Volumes:
530 1 file selected to restore.
532 JobName: kernsrestore
533 Bootstrap: /home/kern/bacula/working/restore.bsr
534 Where: /tmp/bacula-restores
539 When: 2003-09-11 10:20:53
541 OK to run? (yes/mod/no):
545 It is possible to automate the selection by file by putting your list of files
546 in say {\bf /tmp/file-list}, then using the following command:
550 restore client=Rufus file=</tmp/file-list
554 If in modifying the parameters for the Run Restore job, you find that Bacula
555 asks you to enter a Job number, this is because you have not yet specified
556 either a Job number or a Bootstrap file. Simply entering zero will allow you
557 to continue and to select another option to be modified.
561 \section{Replace Options}
563 When restoring, you have the option to specify a Replace option. This
564 directive determines the action to be taken when restoring a file or
565 directory that already exists. This directive can be set by selecting
566 the {\bf mod} option. You will be given a list of parameters to choose
567 from. Full details on this option can be found in the Job Resource section
568 of the Director documentation.
570 \label{CommandArguments}
572 \section{Command Line Arguments}
573 \index[general]{Arguments!Command Line }
574 \index[general]{Command Line Arguments }
576 If all the above sounds complicated, you will probably agree that it really
577 isn't after trying it a few times. It is possible to do everything that was
578 shown above, with the exception of selecting the FileSet, by using command
579 line arguments with a single command by entering:
583 restore client=Rufus select current all done yes
587 The {\bf client=Rufus} specification will automatically select Rufus as the
588 client, the {\bf current} tells Bacula that you want to restore the system to
589 the most current state possible, and the {\bf yes} suppresses the final {\bf
590 yes/mod/no} prompt and simply runs the restore.
592 The full list of possible command line arguments are:
595 \item {\bf all} -- select all Files to be restored.
596 \item {\bf select} -- use the tree selection method.
597 \item {\bf done} -- do not prompt the user in tree mode.
598 \item {\bf current} -- automatically select the most current set of backups
599 for the specified client.
600 \item {\bf client=xxxx} -- initially specifies the client from which the
601 backup was made and the client to which the restore will be make. See also
602 "restoreclient" keyword.
603 \item {\bf restoreclient=xxxx} -- if the keyword is specified, then the
604 restore is written to that client.
605 \item {\bf jobid=nnn} -- specify a JobId or comma separated list of JobIds to
607 \item {\bf before=YYYY-MM-DD HH:MM:SS} -- specify a date and time to which
608 the system should be restored. Only Jobs started before the specified
609 date/time will be selected, and as is the case for {\bf current} Bacula will
610 automatically find the most recent prior Full save and all Differential and
611 Incremental saves run before the date you specify. Note, this command is not
612 too user friendly in that you must specify the date/time exactly as shown.
613 \item {\bf file=filename} -- specify a filename to be restored. You must
614 specify the full path and filename. Prefixing the entry with a less-than
616 (\lt{}) will cause Bacula to assume that the filename is on your system and
617 contains a list of files to be restored. Bacula will thus read the list from
618 that file. Multiple file=xxx specifications may be specified on the command
620 \item {\bf jobid=nnn} -- specify a JobId to be restored.
621 \item {\bf pool=pool-name} -- specify a Pool name to be used for selection of
622 Volumes when specifying options 5 and 6 (restore current system, and restore
623 current system before given date). This permits you to have several Pools,
624 possibly one offsite, and to select the Pool to be used for restoring.
625 \item {\bf where=/tmp/bacula-restore} -- restore files in {\bf where} directory.
626 \item {\bf yes} -- automatically run the restore without prompting for
627 modifications (most useful in batch scripts).
628 \item {\bf strip\_prefix=/prod} -- remove a part of the filename when restoring.
629 \item {\bf add\_prefix=/test} -- add a prefix to all files when restoring (like
630 where) (can't be used with {\bf where=}).
631 \item {\bf add\_suffix=.old} -- add a suffix to all your files.
632 \item {\bf regexwhere=!a.pdf!a.bkp.pdf!} -- do complex filename manipulation
633 like with sed unix command. Will overwrite other filename manipulation.
634 \item {\bf restorejob=jobname} -- Pre-chooses a restore job. Bacula can be
635 configured with multiple restore jobs ("Type = Restore" in the job
636 definition). This allows the specification of different restore properties,
637 including a set of RunScripts. When more than one job of this type is
638 configured, during restore, Bacula will ask for a user selection
639 interactively, or use the given restorejob.
642 \label{restorefilerelocation}
643 \section{Using File Relocation}
644 \index[general]{Using File Relocation}
645 \label{filerelocation}
647 \subsection{Introduction}
649 The \textbf{where=} option is simple, but not very powerful. With file
650 relocation, Bacula can restore a file to the same directory, but with a
651 different name, or in an other directory without recreating the full path.
653 You can also do filename and path manipulations, implemented in Bacula
654 2.1.8 or later, such as adding a suffix to all your files, renaming files
655 or directories, etc. Theses options will overwrite {\bf where=} option.
658 For example, many users use OS snapshot features so that file
659 \texttt{/home/eric/mbox} will be backed up from the directory
660 \texttt{/.snap/home/eric/mbox}, which can complicate restores. If you use
661 \textbf{where=/tmp}, the file will be restored to
662 \texttt{/tmp/.snap/home/eric/mbox} and you will have to move the file to
663 \texttt{/home/eric/mbox.bkp} by hand.
665 However, case, you could use the
666 \textbf{strip\_prefix=/.snap} and \textbf{add\_suffix=.bkp} options and
667 Bacula will restore the file to its original location -- that is
668 \texttt{/home/eric/mbox}.
670 To use this feature, there are command line options as described in
671 the \ilink{restore section}{restorefilerelocation} of this manual;
672 you can modify your restore job before running it; or you can
673 add options to your restore job in as described in
674 \ilink{bacula-dir.conf}{confaddprefix}.
677 Parameters to modify:
683 Select parameter to modify (1-12):
686 This will replace your current Where value
691 5: Test filename manipulation
693 Select parameter to modify (1-6):
697 \subsection{RegexWhere Format}
699 The format is very close to that used by sed or Perl (\texttt{s/replace this/by
700 that/}) operator. A valid regexwhere expression has three fields :
702 \item a search expression (with optionnal submatch)
703 \item a replacement expression (with optionnal back references \$1 to \$9)
704 \item a set of search options (only case-insensitive ``i'' at this time)
707 Each field is delimited by a separator specified by the user as the first
708 character of the expression. The separator can be one of the following:
710 <separator-keyword> = / ! ; % : , ~ # = &
713 You can use several expressions separated by a commas.
715 \subsection*{Examples}
717 \begin{tabular}{|c|c|c|l|}
719 Orignal filename & New filename & RegexWhere & Comments \\
722 \texttt{c:/system.ini} & \texttt{c:/system.old.ini} & \texttt{/.ini\$/.old.ini/} & \$ matches end of name\\
724 \texttt{/prod/u01/pdata/} & \texttt{/rect/u01/rdata} & \texttt{/prod/rect/,/pdata/rdata/} & uses two regexp\\
726 \texttt{/prod/u01/pdata/} & \texttt{/rect/u01/rdata} & \texttt{!/prod/!/rect/!,/pdata/rdata/} & use \texttt{!} as separator\\
728 \texttt{C:/WINNT} & \texttt{d:/WINNT} & \texttt{/c:/d:/i} & case insensitive pattern match \\
733 %\subsubsection{Using group}
735 %Like with Perl or Sed, you can make submatch with \texttt{()},
737 %\subsubsection*{Examples}
740 %\subsubsection{Options}
742 % i Do case-insensitive pattern matching.
744 \section{Restoring Directory Attributes}
745 \index[general]{Attributes!Restoring Directory }
746 \index[general]{Restoring Directory Attributes }
748 Depending how you do the restore, you may or may not get the directory entries
749 back to their original state. Here are a few of the problems you can
750 encounter, and for same machine restores, how to avoid them.
753 \item You backed up on one machine and are restoring to another that is
754 either a different OS or doesn't have the same users/groups defined. Bacula
755 does the best it can in these situations. Note, Bacula has saved the
756 user/groups in numeric form, which means on a different machine, they
757 may map to different user/group names.
759 \item You are restoring into a directory that is already created and has
760 file creation restrictions. Bacula tries to reset everything but
761 without walking up the full chain of directories and modifying them all
762 during the restore, which Bacula does and will not do, getting
763 permissions back correctly in this situation depends to a large extent
766 \item You are doing a recursive restore of a directory tree. In this case
767 Bacula will restore a file before restoring the file's parent directory
768 entry. In the process of restoring the file Bacula will create the
769 parent directory with open permissions and ownership of the file being
770 restored. Then when Bacula tries to restore the parent directory Bacula
771 sees that it already exists (Similar to the previous situation). If you
772 had set the Restore job's "Replace" property to "never" then Bacula will
773 not change the directory's permissions and ownerships to match what it
774 backed up, you should also notice that the actual number of files
775 restored is less then the expected number. If you had set the Restore
776 job's "Replace" property to "always" then Bacula will change the
777 Directory's ownership and permissions to match what it backed up, also
778 the actual number of files restored should be equal to the expected
781 \item You selected one or more files in a directory, but did not select the
782 directory entry to be restored. In that case, if the directory is not
783 on disk Bacula simply creates the directory with some default attributes
784 which may not be the same as the original. If you do not select a
785 directory and all its contents to be restored, you can still select
786 items within the directory to be restored by individually marking those
787 files, but in that case, you should individually use the "markdir"
788 command to select all higher level directory entries (one at a time) to
789 be restored if you want the directory entries properly restored.
791 \item The {\bf bextract} program does not restore access control lists
792 (ACLs) to Unix machines.
796 \section{Restoring on Windows}
797 \index[general]{Restoring on Windows }
798 \index[general]{Windows!Restoring on }
800 If you are restoring on WinNT/2K/XP systems, Bacula will restore the files
801 with the original ownerships and permissions as would be expected. This is
802 also true if you are restoring those files to an alternate directory (using
803 the Where option in restore). However, if the alternate directory does not
804 already exist, the Bacula File daemon (Client) will try to create it. In
805 some cases, it may not create the directories, and if it does since the
806 File daemon runs under the SYSTEM account, the directory will be created
807 with SYSTEM ownership and permissions. In this case, you may have problems
808 accessing the newly restored files.
810 To avoid this problem, you should create any alternate directory before
811 doing the restore. Bacula will not change the ownership and permissions of
812 the directory if it is already created as long as it is not one of the
813 directories being restored (i.e. written to tape).
815 The default restore location is {\bf /tmp/bacula-restores/} and if you are
816 restoring from drive {\bf E:}, the default will be
817 {\bf /tmp/bacula-restores/e/}, so you should ensure that this directory
818 exists before doing the restore, or use the {\bf mod} option to
819 select a different {\bf where} directory that does exist.
821 Some users have experienced problems restoring files that participate in
822 the Active Directory. They also report that changing the userid under which
823 Bacula (bacula-fd.exe) runs, from SYSTEM to a Domain Admin userid, resolves
827 \section{Restoring Files Can Be Slow}
828 \index[general]{Slow!Restoring Files Can Be }
829 \index[general]{Restoring Files Can Be Slow }
831 Restoring files is generally {\bf much} slower than backing them up for several
832 reasons. The first is that during a backup the tape is normally already
833 positioned and Bacula only needs to write. On the other hand, because restoring
834 files is done so rarely, Bacula keeps only the start file and block on the
835 tape for the whole job rather than on a file by file basis which would use
836 quite a lot of space in the catalog.
838 Bacula will forward space to the correct file mark on the tape for the Job,
839 then forward space to the correct block, and finally sequentially read each
840 record until it gets to the correct one(s) for the file or files you want to
841 restore. Once the desired files are restored, Bacula will stop reading the
844 Finally, instead of just reading a file for backup, during the restore, Bacula
845 must create the file, and the operating system must allocate disk space for
846 the file as Bacula is restoring it.
848 For all the above reasons the restore process is generally much slower than
849 backing up (sometimes it takes three times as long).
851 \section{Problems Restoring Files}
852 \index[general]{Files!Problems Restoring }
853 \index[general]{Problems Restoring Files }
855 The most frequent problems users have restoring files are error messages such
860 04-Jan 00:33 z217-sd: RestoreFiles.2005-01-04_00.31.04 Error:
861 block.c:868 Volume data error at 20:0! Short block of 512 bytes on
862 device /dev/tape discarded.
870 04-Jan 00:33 z217-sd: RestoreFiles.2005-01-04_00.31.04 Error:
871 block.c:264 Volume data error at 20:0! Wanted ID: "BB02", got ".".
876 Both these kinds of messages indicate that you were probably running your tape
877 drive in fixed block mode rather than variable block mode. Fixed block mode
878 will work with any program that reads tapes sequentially such as tar, but
879 Bacula repositions the tape on a block basis when restoring files because this
880 will speed up the restore by orders of magnitude when only a few files are being
881 restored. There are several ways that you can attempt to recover from this
882 unfortunate situation.
884 Try the following things, each separately, and reset your Device resource to
885 what it is now after each individual test:
888 \item Set "Block Positioning = no" in your Device resource and try the
889 restore. This is a new directive and untested.
891 \item Set "Minimum Block Size = 512" and "Maximum Block Size = 512" and
892 try the restore. If you are able to determine the block size your drive
893 was previously using, you should try that size if 512 does not work.
894 This is a really horrible solution, and it is not at all recommended
895 to continue backing up your data without correcting this condition.
896 Please see the Tape Testing chapter for more on this.
898 \item Try editing the restore.bsr file at the Run xxx yes/mod/no prompt
899 before starting the restore job and remove all the VolBlock statements.
900 These are what causes Bacula to reposition the tape, and where problems
901 occur if you have a fixed block size set for your drive. The VolFile
902 commands also cause repositioning, but this will work regardless of the
905 \item Use bextract to extract the files you want -- it reads the Volume
906 sequentially if you use the include list feature, or if you use a .bsr
907 file, but remove all the VolBlock statements after the .bsr file is
908 created (at the Run yes/mod/no) prompt but before you start the restore.
911 \section{Restore Errors}
912 \index[general]{Errors!Restore}
913 \index[general]{Restore Errors}
915 There are a number of reasons why there may be restore errors or
916 warning messages. Some of the more common ones are:
920 \item [file count mismatch]
921 This can occur for the following reasons:
923 \item You requested Bacula not to overwrite existing or newer
925 \item A Bacula miscount of files/directories. This is an
926 on-going problem due to the complications of directories,
927 soft/hard link, and such. Simply check that all the files you
928 wanted were actually restored.
931 \item [file size error]
932 When Bacula restores files, it checks that the size of the
933 restored file is the same as the file status data it saved
934 when starting the backup of the file. If the sizes do not
935 agree, Bacula will print an error message. This size mismatch
936 most often occurs because the file was being written as Bacula
937 backed up the file. In this case, the size that Bacula
938 restored will be greater than the status size. This often
939 happens with log files.
941 If the restored size is smaller, then you should be concerned
942 about a possible tape error and check the Bacula output as
943 well as your system logs.
948 \section{Example Restore Job Resource}
949 \index[general]{Example Restore Job Resource }
950 \index[general]{Resource!Example Restore Job }
955 Name = "RestoreFiles"
958 FileSet = "Any-FileSet"
959 Storage = Any-storage
960 Where = /tmp/bacula-restores
967 If {\bf Where} is not specified, the default location for restoring files will
968 be their original locations.
971 \section{File Selection Commands}
972 \index[general]{Commands!File Selection }
973 \index[general]{File Selection Commands }
975 After you have selected the Jobs to be restored and Bacula has created the
976 in-memory directory tree, you will enter file selection mode as indicated by
977 the dollar sign ({\bf \$}) prompt. While in this mode, you may use the
978 commands listed above. The basic idea is to move up and down the in memory
979 directory structure with the {\bf cd} command much as you normally do on the
980 system. Once you are in a directory, you may select the files that you want
981 restored. As a default no files are marked to be restored. If you wish to
982 start with all files, simply enter: {\bf cd /} and {\bf mark *}. Otherwise
983 proceed to select the files you wish to restore by marking them with the {\bf
984 mark} command. The available commands are:
989 The {\bf cd} command changes the current directory to the argument specified.
990 It operates much like the Unix {\bf cd} command. Wildcard specifications are
993 Note, on Windows systems, the various drives (c:, d:, ...) are treated like a
994 directory within the file tree while in the file selection mode. As a
995 consequence, you must do a {\bf cd c:} or possibly in some cases a {\bf cd
996 C:} (note upper case) to get down to the first directory.
1000 The {\bf dir} command is similar to the {\bf ls} command, except that it
1001 prints it in long format (all details). This command can be a bit slower
1002 than the {\bf ls} command because it must access the catalog database for
1003 the detailed information for each file.
1006 \index[dir]{estimate }
1007 The {\bf estimate} command prints a summary of the total files in the tree,
1008 how many are marked to be restored, and an estimate of the number of bytes
1009 to be restored. This can be useful if you are short on disk space on the
1010 machine where the files will be restored.
1014 The {\bf find} command accepts one or more arguments and displays all files
1015 in the tree that match that argument. The argument may have wildcards. It is
1016 somewhat similar to the Unix command {\bf find / -name arg}.
1019 The {\bf ls} command produces a listing of all the files contained in the
1020 current directory much like the Unix {\bf ls} command. You may specify an
1021 argument containing wildcards, in which case only those files will be
1024 Any file that is marked to be restored will have its name preceded by an
1025 asterisk ({\bf *}). Directory names will be terminated with a forward slash
1026 ({\bf /}) to distinguish them from filenames.
1030 The {\bf lsmark} command is the same as the {\bf ls} except that it will
1031 print only those files marked for extraction. The other distinction is that
1032 it will recursively descend into any directory selected.
1036 The {\bf mark} command allows you to mark files to be restored. It takes a
1037 single argument which is the filename or directory name in the current
1038 directory to be marked for extraction. The argument may be a wildcard
1039 specification, in which case all files that match in the current directory
1040 are marked to be restored. If the argument matches a directory rather than a
1041 file, then the directory and all the files contained in that directory
1042 (recursively) are marked to be restored. Any marked file will have its name
1043 preceded with an asterisk ({\bf *}) in the output produced by the {\bf ls}
1045 {\bf dir} commands. Note, supplying a full path on the mark command does not
1046 work as expected to select a file or directory in the current directory.
1047 Also, the {\bf mark} command works on the current and lower directories but
1048 does not touch higher level directories.
1050 After executing the {\bf mark} command, it will print a brief summary:
1059 If no files were marked, or:
1068 if some files are marked.
1071 \index[dir]{unmark }
1072 The {\bf unmark} is identical to the {\bf mark} command, except that it
1073 unmarks the specified file or files so that they will not be restored. Note:
1074 the {\bf unmark} command works from the current directory, so it does not
1075 unmark any files at a higher level. First do a {\bf cd /} before the {\bf
1076 unmark *} command if you want to unmark everything.
1080 The {\bf pwd} command prints the current working directory. It accepts no
1085 The {\bf count} command prints the total files in the directory tree and the
1086 number of files marked to be restored.
1090 This command terminates file selection mode.
1094 This command terminates file selection mode (the same as done).
1098 This command terminates the file selection and does not run the restore
1104 This command prints a summary of the commands available.
1107 This command is the same as the {\bf help} command.
1110 If your filename contains some weird caracters, you can use \texttt{?},
1111 \texttt{*} or \textbackslash{}\textbackslash{}. For example, if your filename
1112 contains a \textbackslash{}, you can use
1113 \textbackslash{}\textbackslash{}\textbackslash{}\textbackslash{}.
1116 * mark weird_file\\\\with-backslash
1119 \label{database_restore}
1120 \section{Restoring When Things Go Wrong}
1121 \index[general]{Restoring When Things Go Wrong }
1122 \index[general]{Restoring Your Database}
1123 \index[general]{Database!Restoring}
1125 This and the following sections will try to present a few of the kinds of
1126 problems that can come up making restoring more difficult. We will try to
1127 provide a few ideas how to get out of these problem situations.
1128 In addition to what is presented here, there is more specific information
1129 on restoring a \ilink{Client}{restore_client} and your
1130 \ilink{Server}{restore_server} in the \ilink{Disaster Recovery Using
1131 Bacula}{RescueChapter} chapter of this manual.
1135 My database is broken.
1137 For SQLite, use the vacuum command to try to fix the database. For either
1138 MySQL or PostgreSQL, see the vendor's documentation. They have specific tools
1139 that check and repair databases, see the \ilink{database
1140 repair}{DatabaseRepair} sections of this manual for links to vendor
1143 Assuming the above does not resolve the problem, you will need to restore
1144 or rebuild your catalog. Note, if it is a matter of some
1145 inconsistencies in the Bacula tables rather than a broken database, then
1146 running \ilink{dbcheck}{dbcheck} might help, but you will need to ensure
1147 that your database indexes are properly setup. Please see
1148 the \ilink{Database Performance Issues}{DatabasePerformance} sections
1149 of this manual for more details.
1152 How do I restore my catalog?
1153 \item[Solution with a Catalog backup]
1154 If you have backed up your database nightly (as you should) and you
1155 have made a bootstrap file, you can immediately load back your
1156 database (or the ASCII SQL output). Make a copy of your current
1157 database, then re-initialize it, by running the following scripts:
1159 ./drop_bacula_tables
1160 ./make_bacula_tables
1162 After re-initializing the database, you should be able to run
1163 Bacula. If you now try to use the restore command, it will not
1164 work because the database will be empty. However, you can manually
1165 run a restore job and specify your bootstrap file. You do so
1166 by entering the {bf run} command in the console and selecting the
1167 restore job. If you are using the default bacula-dir.conf, this
1168 Job will be named {\bf RestoreFiles}. Most likely it will prompt
1169 you with something such as:
1174 JobName: RestoreFiles
1175 Bootstrap: /home/kern/bacula/working/restore.bsr
1176 Where: /tmp/bacula-restores
1181 When: 2005-07-10 17:33:40
1184 OK to run? (yes/mod/no):
1188 A number of the items will be different in your case. What you want to
1189 do is: to use the mod option to change the Bootstrap to point to your
1190 saved bootstrap file; and to make sure all the other items such as
1191 Client, Storage, Catalog, and Where are correct. The FileSet is not
1192 used when you specify a bootstrap file. Once you have set all the
1193 correct values, run the Job and it will restore the backup of your
1194 database, which is most likely an ASCII dump.
1196 You will then need to follow the instructions for your
1197 database type to recreate the database from the ASCII backup file.
1198 See the \ilink {Catalog Maintenance}{CatMaintenanceChapter} chapter of
1199 this manual for examples of the command needed to restore a
1200 database from an ASCII dump (they are shown in the Compacting Your
1201 XXX Database sections).
1203 Also, please note that after you restore your database from an ASCII
1204 backup, you do NOT want to do a {\bf make\_bacula\_tables} command, or
1205 you will probably erase your newly restored database tables.
1208 \item[Solution with a Job listing]
1209 If you did save your database but did not make a bootstrap file, then
1210 recovering the database is more difficult. You will probably need to
1211 use bextract to extract the backup copy. First you should locate the
1212 listing of the job report from the last catalog backup. It has
1213 important information that will allow you to quickly find your database
1214 file. For example, in the job report for the CatalogBackup shown below,
1215 the critical items are the Volume name(s), the Volume Session Id and the
1216 Volume Session Time. If you know those, you can easily restore your
1221 22-Apr 10:22 HeadMan: Start Backup JobId 7510,
1222 Job=CatalogBackup.2005-04-22_01.10.0
1223 22-Apr 10:23 HeadMan: Bacula 1.37.14 (21Apr05): 22-Apr-2005 10:23:06
1225 Job: CatalogBackup.2005-04-22_01.10.00
1228 FileSet: "CatalogFile" 2003-04-10 01:24:01
1231 Start time: 22-Apr-2005 10:21:00
1232 End time: 22-Apr-2005 10:23:06
1235 FD Bytes Written: 210,739,395
1236 SD Bytes Written: 210,739,521
1238 Software Compression: None
1239 Volume name(s): DLT-22Apr05
1240 Volume Session Id: 11
1241 Volume Session Time: 1114075126
1242 Last Volume Bytes: 1,428,240,465
1243 Non-fatal FD errors: 0
1245 FD termination status: OK
1246 SD termination status: OK
1247 Termination: Backup OK
1251 From the above information, you can manually create a bootstrap file,
1252 and then follow the instructions given above for restoring your database.
1253 A reconstructed bootstrap file for the above backup Job would look
1258 Volume="DLT-22Apr05"
1260 VolSessionTime=1114075126
1265 Where we have inserted the Volume name, Volume Session Id, and Volume
1266 Session Time that correspond to the values in the job report. We've also
1267 used a FileIndex of one, which will always be the case providing that
1268 there was only one file backed up in the job.
1270 The disadvantage of this bootstrap file compared to what is created when
1271 you ask for one to be written, is that there is no File and Block
1272 specified, so the restore code must search all data in the Volume to find
1273 the requested file. A fully specified bootstrap file would have the File
1274 and Blocks specified as follows:
1278 Volume="DLT-22Apr05"
1280 VolSessionTime=1114075126
1287 Once you have restored the ASCII dump of the database,
1288 you will then to follow the instructions for your
1289 database type to recreate the database from the ASCII backup file.
1290 See the \ilink {Catalog Maintenance}{CatMaintenanceChapter} chapter of
1291 this manual for examples of the command needed to restore a
1292 database from an ASCII dump (they are shown in the Compacting Your
1293 XXX Database sections).
1295 Also, please note that after you restore your database from an ASCII
1296 backup, you do NOT want to do a {\bf make\_bacula\_tables} command, or
1297 you will probably erase your newly restored database tables.
1299 \item [Solution without a Job Listing]
1300 If you do not have a job listing, then it is a bit more difficult.
1301 Either you use the \ilink{bscan}{bscan} program to scan the contents
1302 of your tape into a database, which can be very time consuming
1303 depending on the size of the tape, or you can use the \ilink{bls}{bls}
1304 program to list everything on the tape, and reconstruct a bootstrap
1305 file from the bls listing for the file or files you want following
1306 the instructions given above.
1308 There is a specific example of how to use {\bf bls} below.
1311 I try to restore the last known good full backup by specifying
1312 item 3 on the restore menu then the JobId to restore. Bacula
1320 and restores nothing.
1323 Most likely the File records were pruned from the database either due
1324 to the File Retention period expiring or by explicitly purging the
1325 Job. By using the "llist jobid=nn" command, you can obtain all the
1326 important information about the job:
1332 Job: save.2005-12-05_18.27.33
1340 SchedTime: 2005-12-05 18:27:32
1341 StartTime: 2005-12-05 18:27:35
1342 EndTime: 2005-12-05 18:27:37
1343 JobTDate: 1133803657
1345 VolSessionTime: 1133803624
1352 FileSet.FileSet: BackupSet
1356 Then you can find the Volume(s) used by doing:
1361 select VolumeName from JobMedia,Media where JobId=1 and JobMedia.MediaId=Media.MediaId;
1365 Finally, you can create a bootstrap file as described in the previous
1366 problem above using this information.
1368 If you are using Bacula version 1.38.0 or greater, when you select
1369 item 3 from the menu and enter the JobId, it will ask you if
1370 you would like to restore all the files in the job, and it will
1371 collect the above information and write the bootstrap file for
1375 You don't have a bootstrap file, and you don't have the Job report for
1376 the backup of your database, but you did backup the database, and you
1377 know the Volume to which it was backed up.
1380 Either bscan the tape (see below for bscanning), or better use {\bf bls}
1381 to find where it is on the tape, then use {\bf bextract} to
1382 restore the database. For example,
1387 ./bls -j -V DLT-22Apr05 /dev/nst0
1390 Might produce the following output:
1393 bls: butil.c:258 Using device: "/dev/nst0" for reading.
1394 21-Jul 18:34 bls: Ready to read from volume "DLT-22Apr05" on device "DLTDrive"
1396 Volume Record: File:blk=0:0 SessId=11 SessTime=1114075126 JobId=0 DataLen=164
1398 Begin Job Session Record: File:blk=118:0 SessId=11 SessTime=1114075126
1400 Job=CatalogBackup.2005-04-22_01.10.0 Date=22-Apr-2005 10:21:00 Level=F Type=B
1401 End Job Session Record: File:blk=118:4053 SessId=11 SessTime=1114075126
1403 Date=22-Apr-2005 10:23:06 Level=F Type=B Files=1 Bytes=210,739,395 Errors=0
1406 21-Jul 18:34 bls: End of Volume at file 201 on device "DLTDrive" (/dev/nst0),
1407 Volume "DLT-22Apr05"
1408 21-Jul 18:34 bls: End of all volumes.
1411 Of course, there will be many more records printed, but we have indicated
1412 the essential lines of output. From the information on the Begin Job and End
1413 Job Session Records, you can reconstruct a bootstrap file such as the one
1417 How can I find where a file is stored.
1419 Normally, it is not necessary, you just use the {\bf restore} command to
1420 restore the most recently saved version (menu option 5), or a version
1421 saved before a given date (menu option 8). If you know the JobId of the
1422 job in which it was saved, you can use menu option 3 to enter that JobId.
1424 If you would like to know the JobId where a file was saved, select
1425 restore menu option 2.
1427 You can also use the {\bf query} command to find information such as:
1432 1: List up to 20 places where a File is saved regardless of the
1434 2: List where the most recent copies of a file are saved
1435 3: List last 20 Full Backups for a Client
1436 4: List all backups for a Client after a specified time
1437 5: List all backups for a Client
1438 6: List Volume Attributes for a selected Volume
1439 7: List Volumes used by selected JobId
1440 8: List Volumes to Restore All Files
1441 9: List Pool Attributes for a selected Pool
1442 10: List total files/bytes by Job
1443 11: List total files/bytes by Volume
1444 12: List Files for a selected JobId
1445 13: List Jobs stored on a selected MediaId
1446 14: List Jobs stored for a given Volume name
1447 15: List Volumes Bacula thinks are in changer
1448 16: List Volumes likely to need replacement from age or errors
1449 Choose a query (1-16):
1454 I didn't backup my database. What do I do now?
1456 This is probably the worst of all cases, and you will probably have
1457 to re-create your database from scratch and then bscan in all your
1458 Volumes, which is a very long, painful, and inexact process.
1460 There are basically three steps to take:
1463 \item Ensure that your SQL server is running (MySQL or PostgreSQL)
1464 and that the Bacula database (normally bacula) exists. See the
1465 \ilink{Installation}{CreateDatabase} chapter of the manual.
1466 \item Ensure that the Bacula databases are created. This is also
1467 described at the above link.
1468 \item Start and stop the Bacula Director using the propriate
1469 bacula-dir.conf file so that it can create the Client and
1470 Storage records which are not stored on the Volumes. Without these
1471 records, scanning is unable to connect the Job records to the proper
1475 When the above is complete, you can begin bscanning your Volumes. Please
1476 see the \ilink{bscan}{bscan} section of the Volume Utility Tools of this
1477 chapter for more details.