This repository has been archived by the owner on Mar 19, 2021. It is now read-only.
/
restore.tex
1454 lines (1223 loc) · 59.1 KB
/
restore.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
%%
%%
\chapter{The Restore Command}
\label{RestoreChapter}
\index[general]{Console!Command!Restore}
\index[general]{Restore}
\section{General}
Below, we will discuss restoring files with the Console {\bf restore} command,
which is the recommended way of doing restoring files. It is not possible
to restore files by automatically starting a job as you do with Backup,
Verify, ... jobs. However, in addition to the console restore command,
there is a standalone program named {\bf bextract}, which also permits
restoring files. For more information on this program, please see the
\ilink{Bareos Utility Programs}{bextract} chapter of this manual. We
don't particularly recommend the {\bf bextract} program because it
lacks many of the features of the normal Bareos restore, such as the
ability to restore Win32 files to Unix systems, and the ability to
restore access control lists (ACL). As a consequence, we recommend,
wherever possible to use Bareos itself for restores as described below.
You may also want to look at the {\bf bls} program in the same chapter,
which allows you to list the contents of your Volumes. Finally, if you
have an old Volume that is no longer in the catalog, you can restore the
catalog entries using the program named {\bf bscan}, documented in the same
\ilink{Bareos Utility Programs}{bscan} chapter.
In general, to restore a file or a set of files, you must run a {\bf restore}
job. That is a job with {\bf Type = Restore}. As a consequence, you will need
a predefined {\bf restore} job in your {\bf bareos-dir.conf} (Director's
config) file. The exact parameters (Client, FileSet, ...) that you define are
not important as you can either modify them manually before running the job or
if you use the {\bf restore} command, explained below, Bareos will
automatically set them for you. In fact, you can no longer simply run a restore
job. You must use the restore command.
Since Bareos is a network backup program, you must be aware that when you
restore files, it is up to you to ensure that you or Bareos have selected the
correct Client and the correct hard disk location for restoring those files.
{\bf Bareos} will quite willingly backup client A, and restore it by sending
the files to a different directory on client B. Normally, you will want to
avoid this, but assuming the operating systems are not too different in their
file structures, this should work perfectly well, if so desired.
By default, Bareos will restore data to the same Client that was backed
up, and those data will be restored not to the original places but to
{\bf /tmp/bareos-restores}. This is configured in the default restore
command ressource in bareos-dir.conf. You may modify any of these defaults when the
restore command prompts you to run the job by selecting the {\bf mod}
option.
\section{The Restore Command}
\label{Example1}
Since Bareos maintains a catalog of your files and on which Volumes (disk or
tape), they are stored, it can do most of the bookkeeping work, allowing you
simply to specify what kind of restore you want (current, before a particular
date), and what files to restore. Bareos will then do the rest.
This is accomplished using the {\bf restore} command in the Console. First you
select the kind of restore you want, then the JobIds are selected,
the File records for those Jobs are placed in an internal Bareos directory
tree, and the restore enters a file selection mode that allows you to
interactively walk up and down the file tree selecting individual files to be
restored. This mode is somewhat similar to the standard Unix {\bf restore}
program's interactive file selection mode.
If a Job's file records have been pruned from the catalog, the {\bf restore}
command will be unable to find any files to restore. Bareos will ask if you
want to restore all of them or if you want to use a regular expression to
restore only a selection while reading media.
See \ilink{FileRegex option}{FileRegex} and below for more details on this.
Within the Console program, after entering the {\bf restore} command, you are
presented with the following selection prompt:
\begin{bconsole}{*}{restore}{}{}
First you select one or more JobIds that contain files
to be restored. You will be presented several methods
of specifying the JobIds. Then you will be allowed to
select which files from those JobIds are to be restored.
To select the JobIds, you have the following choices:
1: List last 20 Jobs run
2: List Jobs where a given File is saved
3: Enter list of comma separated JobIds to select
4: Enter SQL list command
5: Select the most recent backup for a client
6: Select backup for a client before a specified time
7: Enter a list of files to restore
8: Enter a list of files to restore before a specified time
9: Find the JobIds of the most recent backup for a client
10: Find the JobIds for a backup for a client before a specified time
11: Enter a list of directories to restore for found JobIds
12: Select full restore to a specified Job date
13: Cancel
Select item: (1-13):
\end{bconsole}
There are a lot of options, and as a point of reference, most people will
want to select item 5 (the most recent backup for a client). The details
of the above options are:
\begin{itemize}
\item Item 1 will list the last 20 jobs run. If you find the Job you want,
you can then select item 3 and enter its JobId(s).
\item Item 2 will list all the Jobs where a specified file is saved. If you
find the Job you want, you can then select item 3 and enter the JobId.
\item Item 3 allows you the enter a list of comma separated JobIds whose
files will be put into the directory tree. You may then select which
files from those JobIds to restore. Normally, you would use this option
if you have a particular version of a file that you want to restore and
you know its JobId. The most common options (5 and 6) will not select
a job that did not terminate normally, so if you know a file is
backed up by a Job that failed (possibly because of a system crash), you
can access it through this option by specifying the JobId.
\item Item 4 allows you to enter any arbitrary SQL command. This is
probably the most primitive way of finding the desired JobIds, but at
the same time, the most flexible. Once you have found the JobId(s), you
can select item 3 and enter them.
\item Item 5 will automatically select the most recent Full backup and all
subsequent incremental and differential backups for a specified Client.
These are the Jobs and Files which, if reloaded, will restore your
system to the most current saved state. It automatically enters the
JobIds found into the directory tree in an optimal way such that only
the most recent copy of any particular file found in the set of Jobs
will be restored. This is probably the most convenient of all the above
options to use if you wish to restore a selected Client to its most
recent state.
There are two important things to note. First, this automatic selection
will never select a job that failed (terminated with an error status).
If you have such a job and want to recover one or more files from it,
you will need to explicitly enter the JobId in item 3, then choose the
files to restore.
If some of the Jobs that are needed to do the restore have had their
File records pruned, the restore will be incomplete. Bareos currently
does not correctly detect this condition. You can however, check for
this by looking carefully at the list of Jobs that Bareos selects and
prints. If you find Jobs with the JobFiles column set to zero, when
files should have been backed up, then you should expect problems.
If all the File records have been pruned, Bareos will realize that there
are no file records in any of the JobIds chosen and will inform you. It
will then propose doing a full restore (non-selective) of those JobIds.
This is possible because Bareos still knows where the beginning of the
Job data is on the Volumes, even if it does not know where particular
files are located or what their names are.
\item Item 6 allows you to specify a date and time, after which Bareos will
automatically select the most recent Full backup and all subsequent
incremental and differential backups that started before the specified date
and time.
\item Item 7 allows you to specify one or more filenames (complete path
required) to be restored. Each filename is entered one at a time or if you
prefix a filename with the less-than symbol ({\textless}) Bareos will read that
file and assume it is a list of filenames to be restored. If you
prefix the filename with a question mark (?), then the filename will
be interpreted as an SQL table name, and Bareos will include the rows
of that table in the list to be restored. The table must contain the
JobId in the first column and the FileIndex in the second column.
This table feature is intended for external programs that want to build
their own list of files to be restored.
The filename entry mode is terminated by entering a blank line.
\item Item 8 allows you to specify a date and time before entering the
filenames. See Item 7 above for more details.
\item Item 9 allows you find the JobIds of the most recent backup for
a client. This is much like option 5 (it uses the same code), but
those JobIds are retained internally as if you had entered them
manually. You may then select item 11 (see below) to restore one
or more directories.
\item Item 10 is the same as item 9, except that it allows you to enter
a before date (as with item 6). These JobIds will then be retained
internally.
\index[general]{Restore Directories}
\item Item 11 allows you to enter a list of JobIds from which you can
select directories to be restored. The list of JobIds can have been
previously created by using either item 9 or 10 on the menu. You
may then enter a full path to a directory name or a filename preceded
by a less than sign ({\textless}). The filename should contain a list
of directories to be restored. All files in those directories will
be restored, but if the directory contains subdirectories, nothing
will be restored in the subdirectory unless you explicitly enter its
name.
\item Item 12 is a full restore to a specified job date.
\item Item 13 allows you to cancel the restore command.
\end{itemize}
As an example, suppose that we select item 5 (restore to most recent state).
If you have not specified a client=xxx on the command line, it
it will then ask for the desired Client, which on my system, will print all
the Clients found in the database as follows:
\begin{bconsole}{Select item: (1-13):}{5}{restore: select client}{}
Defined clients:
1: Rufus
2: Matou
3: Polymatou
4: Minimatou
5: Minou
6: MatouVerify
7: PmatouVerify
8: RufusVerify
9: Watchdog
Select Client (File daemon) resource (1-9):
\end{bconsole}
The listed clients are only examples, yours will look differently.
If you have only one Client, it will be automatically selected.
In this example, I enter 1 for
{\bf Rufus} to select the Client.
Then Bareos needs to know what FileSet is
to be restored, so it prompts with:
\footnotesize
\begin{verbatim}
The defined FileSet resources are:
1: Full Set
2: Other Files
Select FileSet resource (1-2):
\end{verbatim}
\normalsize
If you have only one FileSet defined for the Client, it will be selected
automatically. I choose item 1, which is my full backup. Normally, you
will only have a single FileSet for each Job, and if your machines are
similar (all Linux) you may only have one FileSet for all your Clients.
At this point, Bareos has all the information it needs to find the most
recent set of backups. It will then query the database, which may take a bit
of time, and it will come up with something like the following. Note, some of
the columns are truncated here for presentation:
\footnotesize
\begin{verbatim}
+-------+------+----------+-------------+-------------+------+-------+------------+
| JobId | Levl | JobFiles | StartTime | VolumeName | File | SesId |VolSesTime |
+-------+------+----------+-------------+-------------+------+-------+------------+
| 1,792 | F | 128,374 | 08-03 01:58 | DLT-19Jul02 | 67 | 18 | 1028042998 |
| 1,792 | F | 128,374 | 08-03 01:58 | DLT-04Aug02 | 0 | 18 | 1028042998 |
| 1,797 | I | 254 | 08-04 13:53 | DLT-04Aug02 | 5 | 23 | 1028042998 |
| 1,798 | I | 15 | 08-05 01:05 | DLT-04Aug02 | 6 | 24 | 1028042998 |
+-------+------+----------+-------------+-------------+------+-------+------------+
You have selected the following JobId: 1792,1792,1797
Building directory tree for JobId 1792 ...
Building directory tree for JobId 1797 ...
Building directory tree for JobId 1798 ...
cwd is: /
$
\end{verbatim}
\normalsize
Depending on the number of {\bf JobFiles} for each JobId, the {\bf Building
directory tree ..."} can take a bit of time. If you notice ath all the
JobFiles are zero, your Files have probably been pruned and you will not be
able to select any individual files -- it will be restore everything or
nothing.
In our example, Bareos found four Jobs that comprise the most recent backup of
the specified Client and FileSet. Two of the Jobs have the same JobId because
that Job wrote on two different Volumes. The third Job was an incremental
backup to the previous Full backup, and it only saved 254 Files compared to
128,374 for the Full backup. The fourth Job was also an incremental backup
that saved 15 files.
Next Bareos entered those Jobs into the directory tree, with no files marked
to be restored as a default, tells you how many files are in the tree, and
tells you that the current working directory ({\bf cwd}) is /. Finally, Bareos
prompts with the dollar sign (\$) to indicate that you may enter commands to
move around the directory tree and to select files.
If you want all the files to automatically be marked when the directory
tree is built, you could have entered the command {\bf restore all}, or
at the \$ prompt, you can simply enter {\bf mark *}.
Instead of choosing item 5 on the first menu (Select the most recent backup
for a client), if we had chosen item 3 (Enter list of JobIds to select) and we
had entered the JobIds {\bf 1792,1797,1798} we would have arrived at the same
point.
One point to note, if you are manually entering JobIds, is that you must enter
them in the order they were run (generally in increasing JobId order). If you
enter them out of order and the same file was saved in two or more of the
Jobs, you may end up with an old version of that file (i.e. not the most
recent).
Directly entering the JobIds can also permit you to recover data from
a Job that wrote files to tape but that terminated with an error status.
While in file selection mode, you can enter {\bf help} or a question mark (?)
to produce a summary of the available commands:
\footnotesize
\begin{verbatim}
Command Description
======= ===========
cd change current directory
count count marked files in and below the cd
dir long list current directory, wildcards allowed
done leave file selection mode
estimate estimate restore size
exit same as done command
find find files, wildcards allowed
help print help
ls list current directory, wildcards allowed
lsmark list the marked files in and below the cd
mark mark dir/file to be restored recursively in dirs
markdir mark directory name to be restored (no files)
pwd print current working directory
unmark unmark dir/file to be restored recursively in dir
unmarkdir unmark directory name only no recursion
quit quit and do not do restore
? print help
\end{verbatim}
\normalsize
As a default no files have been selected for restore (unless you
added {\bf all} to the command line. If you want to restore
everything, at this point, you should enter {\bf mark *}, and then {\bf done}
and Bareos will write the bootstrap records to a file and request your
approval to start a restore job.
If you do not enter the above mentioned {\bf mark *} command, you will start
with an empty state. Now you can simply start looking at the tree and {\bf
mark} particular files or directories you want restored. It is easy to make
a mistake in specifying a file to mark or unmark, and Bareos's error handling
is not perfect, so please check your work by using the {\bf ls} or {\bf dir}
commands to see what files are actually selected. Any selected file has its
name preceded by an asterisk.
To check what is marked or not marked, enter the {\bf count} command, which
displays:
\footnotesize
\begin{verbatim}
128401 total files. 128401 marked to be restored.
\end{verbatim}
\normalsize
Each of the above commands will be described in more detail in the next
section. We continue with the above example, having accepted to restore all
files as Bareos set by default. On entering the {\bf done} command, Bareos
prints:
\footnotesize
\begin{verbatim}
Run Restore job
JobName: RestoreFiles
Bootstrap: /var/lib/bareos/client1.restore.3.bsr
Where: /tmp/bareos-restores
Replace: Always
FileSet: Full Set
Backup Client: client1
Restore Client: client1
Format: Native
Storage: File
When: 2013-06-28 13:30:08
Catalog: MyCatalog
Priority: 10
Plugin Options: *None*
OK to run? (yes/mod/no):
\end{verbatim}
\normalsize
Please examine each of the items very carefully to make sure that they are
correct. In particular, look at {\bf Where}, which tells you where in the
directory structure the files will be restored, and {\bf Client}, which
tells you which client will receive the files. Note that by default the
Client which will receive the files is the Client that was backed up.
These items will not always be completed with the correct values depending
on which of the restore options you chose. You can change any of these
default items by entering {\bf mod} and responding to the prompts.
The above assumes that you have defined a {\bf Restore} Job resource in your
Director's configuration file. Normally, you will only need one Restore Job
resource definition because by its nature, restoring is a manual operation,
and using the Console interface, you will be able to modify the Restore Job to
do what you want.
An example Restore Job resource definition is given below.
Returning to the above example, you should verify that the Client name is
correct before running the Job. However, you may want to modify some of the
parameters of the restore job. For example, in addition to checking the Client
it is wise to check that the Storage device chosen by Bareos is indeed
correct. Although the {\bf FileSet} is shown, it will be ignored in restore.
The restore will choose the files to be restored either by reading the {\bf
Bootstrap} file, or if not specified, it will restore all files associated
with the specified backup {\bf JobId} (i.e. the JobId of the Job that
originally backed up the files).
Finally before running the job, please note that the default location for
restoring files is {\bf not} their original locations, but rather the directory
{\bf /tmp/bareos-restores}. You can change this default by modifying your {\bf
bareos-dir.conf} file, or you can modify it using the {\bf mod} option. If you
want to restore the files to their original location, you must have {\bf
Where} set to nothing or to the root, i.e. {\bf /}.
If you now enter {\bf yes}, Bareos will run the restore Job.
\subsection{Restore a pruned job using a pattern}
\TODO{fix example and move to troubleshooting}
During a restore, if all File records are pruned from the catalog
for a Job, normally Bareos can restore only all files saved. That
is there is no way using the catalog to select individual files.
With this new feature, Bareos will ask if you want to specify a Regex
expression for extracting only a part of the full backup.
\begin{verbatim}
Building directory tree for JobId(s) 1,3 ...
There were no files inserted into the tree, so file selection
is not possible.Most likely your retention policy pruned the files
Do you want to restore all the files? (yes|no): no
Regexp matching files to restore? (empty to abort): /tmp/regress/(bin|tests)/
Bootstrap records written to /tmp/regress/working/zog4-dir.restore.1.bsr
\end{verbatim}
See also \ilink{FileRegex bsr option}{FileRegex} for more information.
\section{Selecting Files by Filename}
\index[general]{Selecting Files by Filename}
\index[general]{Filename!Selecting Files by}
If you have a small number of files to restore, and you know the filenames,
you can either put the list of filenames in a file to be read by Bareos, or
you can enter the names one at a time. The filenames must include the full
path and filename. No wild cards are used.
To enter the files, after the {\bf restore}, you select item number 7 from the
prompt list:
\begin{bconsole}{*}{restore}{restore list of files}{7}
First you select one or more JobIds that contain files
to be restored. You will be presented several methods
of specifying the JobIds. Then you will be allowed to
select which files from those JobIds are to be restored.
To select the JobIds, you have the following choices:
1: List last 20 Jobs run
2: List Jobs where a given File is saved
3: Enter list of comma separated JobIds to select
4: Enter SQL list command
5: Select the most recent backup for a client
6: Select backup for a client before a specified time
7: Enter a list of files to restore
8: Enter a list of files to restore before a specified time
9: Find the JobIds of the most recent backup for a client
10: Find the JobIds for a backup for a client before a specified time
11: Enter a list of directories to restore for found JobIds
12: Select full restore to a specified Job date
13: Cancel
Select item: (1-13): 7
\end{bconsole}
which then prompts you for the client name:
\footnotesize
\begin{verbatim}
Defined Clients:
1: client1
2: Tibs
3: Rufus
Select the Client (1-3): 3
\end{verbatim}
\normalsize
Of course, your client list will be different, and if you have only one
client, it will be automatically selected. And finally, Bareos requests you to
enter a filename:
\footnotesize
\begin{verbatim}
Enter filename:
\end{verbatim}
\normalsize
At this point, you can enter the full path and filename
\footnotesize
\begin{verbatim}
Enter filename: /etc/resolv.conf
Enter filename:
\end{verbatim}
\normalsize
as you can see, it took the filename. If Bareos cannot find a copy of the
file, it prints the following:
\footnotesize
\begin{verbatim}
Enter filename: junk filename
No database record found for: junk filename
Enter filename:
\end{verbatim}
\normalsize
If you want Bareos to read the filenames from a file, you simply precede the
filename with a less-than symbol ({\textless}).
It is possible to automate the selection by file by putting your list of files
in say {\bf /tmp/file-list}, then using the following command:
\footnotesize
\begin{verbatim}
restore client=client1 file=</tmp/file-list
\end{verbatim}
\normalsize
If in modifying the parameters for the Run Restore job, you find that Bareos
asks you to enter a Job number, this is because you have not yet specified
either a Job number or a Bootstrap file. Simply entering zero will allow you
to continue and to select another option to be modified.
\label{Replace}
\section{Replace Options}
When restoring, you have the option to specify a Replace option. This
directive determines the action to be taken when restoring a file or
directory that already exists. This directive can be set by selecting
the {\bf mod} option. You will be given a list of parameters to choose
from. Full details on this option can be found in the Job Resource section
of the Director documentation.
\section{Command Line Arguments}
\label{CommandArguments}
If all the above sounds complicated, you will probably agree that it really
isn't after trying it a few times. It is possible to do everything that was
shown above, with the exception of selecting the FileSet, by using command
line arguments with a single command by entering:
\footnotesize
\begin{verbatim}
restore client=Rufus select current all done yes
\end{verbatim}
\normalsize
The {\bf client=Rufus} specification will automatically select Rufus as the
client, the {\bf current} tells Bareos that you want to restore the system to
the most current state possible, and the {\bf yes} suppresses the final {\bf
yes/mod/no} prompt and simply runs the restore.
The full list of possible command line arguments are:
\begin{itemize}
\item {\bf all} -- select all Files to be restored.
\item {\bf select} -- use the tree selection method.
\item {\bf done} -- do not prompt the user in tree mode.
\item {\bf current} -- automatically select the most current set of backups
for the specified client.
\item {\bf client=xxxx} -- initially specifies the client from which the
backup was made and the client to which the restore will be make. See also
"restoreclient" keyword.
\item {\bf restoreclient=xxxx} -- if the keyword is specified, then the
restore is written to that client.
\item {\bf jobid=nnn} -- specify a JobId or comma separated list of JobIds to
be restored.
\item {\bf before=YYYY-MM-DD HH:MM:SS} -- specify a date and time to which
the system should be restored. Only Jobs started before the specified
date/time will be selected, and as is the case for {\bf current} Bareos will
automatically find the most recent prior Full save and all Differential and
Incremental saves run before the date you specify. Note, this command is not
too user friendly in that you must specify the date/time exactly as shown.
\item {\bf file=filename} -- specify a filename to be restored. You must
specify the full path and filename. Prefixing the entry with a less-than
sign
({\textless}) will cause Bareos to assume that the filename is on your system and
contains a list of files to be restored. Bareos will thus read the list from
that file. Multiple file=xxx specifications may be specified on the command
line.
\item {\bf jobid=nnn} -- specify a JobId to be restored.
\item {\bf pool=pool-name} -- specify a Pool name to be used for selection of
Volumes when specifying options 5 and 6 (restore current system, and restore
current system before given date). This permits you to have several Pools,
possibly one offsite, and to select the Pool to be used for restoring.
\item {\bf where=/tmp/bareos-restore} -- restore files in {\bf where} directory.
\item {\bf yes} -- automatically run the restore without prompting for
modifications (most useful in batch scripts).
\item {\bf strip\_prefix=/prod} -- remove a part of the filename when restoring.
\item {\bf add\_prefix=/test} -- add a prefix to all files when restoring (like
where) (can't be used with {\bf where=}).
\item {\bf add\_suffix=.old} -- add a suffix to all your files.
\item {\bf regexwhere=!a.pdf!a.bkp.pdf!} -- do complex filename manipulation
like with sed unix command. Will overwrite other filename manipulation.
\item {\bf restorejob=jobname} -- Pre-chooses a restore job. Bareos can be
configured with multiple restore jobs ("Type = Restore" in the job
definition). This allows the specification of different restore properties,
including a set of RunScripts. When more than one job of this type is
configured, during restore, Bareos will ask for a user selection
interactively, or use the given restorejob.
\end{itemize}
\label{restorefilerelocation}
\section{Using File Relocation}
\index[general]{Using File Relocation}
\label{filerelocation}
\subsection{Introduction}
The \textbf{where=} option is simple, but not very powerful. With file
relocation, Bareos can restore a file to the same directory, but with a
different name, or in an other directory without recreating the full path.
You can also do filename and path manipulations,
such as adding a suffix to all your files, renaming files
or directories, etc. Theses options will overwrite {\bf where=} option.
For example, many users use OS snapshot features so that file
\texttt{/home/eric/mbox} will be backed up from the directory
\texttt{/.snap/home/eric/mbox}, which can complicate restores. If you use
\textbf{where=/tmp}, the file will be restored to
\texttt{/tmp/.snap/home/eric/mbox} and you will have to move the file to
\texttt{/home/eric/mbox.bkp} by hand.
However, case, you could use the
\textbf{strip\_prefix=/.snap} and \textbf{add\_suffix=.bkp} options and
Bareos will restore the file to its original location -- that is
\texttt{/home/eric/mbox}.
To use this feature, there are command line options as described in
the \ilink{restore section}{restorefilerelocation} of this manual;
you can modify your restore job before running it; or you can
add options to your restore job in as described in
\ilink{bareos-dir.conf}{confaddprefix}.
\begin{verbatim}
Parameters to modify:
1: Level
2: Storage
...
10: File Relocation
...
Select parameter to modify (1-12):
This will replace your current Where value
1: Strip prefix
2: Add prefix
3: Add file suffix
4: Enter a regexp
5: Test filename manipulation
6: Use this ?
Select parameter to modify (1-6):
\end{verbatim}
\subsection{RegexWhere Format}
\label{useregexwhere}
The format is very close to that used by sed or Perl (\texttt{s/replace this/by
that/}) operator. A valid regexwhere expression has three fields :
\begin{itemize}
\item a search expression (with optional submatch)
\item a replacement expression (with optionnal back references \$1 to \$9)
\item a set of search options (only case-insensitive ``i'' at this time)
\end{itemize}
Each field is delimited by a separator specified by the user as the first
character of the expression. The separator can be one of the following:
\begin{verbatim}
<separator-keyword> = / ! ; % : , ~ # = &
\end{verbatim}
You can use several expressions separated by a commas.
\subsection*{Examples}
\begin{tabular}{|c|c|c|l|}
\hline
Orignal filename & New filename & RegexWhere & Comments \\
\hline
\hline
\texttt{c:/system.ini} & \texttt{c:/system.old.ini} & \texttt{/.ini\$/.old.ini/} & \$ matches end of name\\
\hline
\texttt{/prod/u01/pdata/} & \texttt{/rect/u01/rdata} & \texttt{/prod/rect/,/pdata/rdata/} & uses two regexp\\
\hline
\texttt{/prod/u01/pdata/} & \texttt{/rect/u01/rdata} & \texttt{!/prod/!/rect/!,/pdata/rdata/} & use \texttt{!} as separator\\
\hline
\texttt{C:/WINNT} & \texttt{d:/WINNT} & \texttt{/c:/d:/i} & case insensitive pattern match \\
\hline
\end{tabular}
%\subsubsection{Using group}
%
%Like with Perl or Sed, you can make submatch with \texttt{()},
%
%\subsubsection*{Examples}
%\subsubsection{Options}
%
% i Do case-insensitive pattern matching.
\section{Restoring Directory Attributes}
\index[general]{Attributes!Restoring Directory}
\index[general]{Restoring Directory Attributes}
Depending how you do the restore, you may or may not get the directory entries
back to their original state. Here are a few of the problems you can
encounter, and for same machine restores, how to avoid them.
\begin{itemize}
\item You backed up on one machine and are restoring to another that is
either a different OS or doesn't have the same users/groups defined. Bareos
does the best it can in these situations. Note, Bareos has saved the
user/groups in numeric form, which means on a different machine, they
may map to different user/group names.
\item You are restoring into a directory that is already created and has
file creation restrictions. Bareos tries to reset everything but
without walking up the full chain of directories and modifying them all
during the restore, which Bareos does and will not do, getting
permissions back correctly in this situation depends to a large extent
on your OS.
\item You are doing a recursive restore of a directory tree. In this case
Bareos will restore a file before restoring the file's parent directory
entry. In the process of restoring the file Bareos will create the
parent directory with open permissions and ownership of the file being
restored. Then when Bareos tries to restore the parent directory Bareos
sees that it already exists (Similar to the previous situation). If you
had set the Restore job's "Replace" property to "never" then Bareos will
not change the directory's permissions and ownerships to match what it
backed up, you should also notice that the actual number of files
restored is less then the expected number. If you had set the Restore
job's "Replace" property to "always" then Bareos will change the
Directory's ownership and permissions to match what it backed up, also
the actual number of files restored should be equal to the expected
number.
\item You selected one or more files in a directory, but did not select the
directory entry to be restored. In that case, if the directory is not
on disk Bareos simply creates the directory with some default attributes
which may not be the same as the original. If you do not select a
directory and all its contents to be restored, you can still select
items within the directory to be restored by individually marking those
files, but in that case, you should individually use the "markdir"
command to select all higher level directory entries (one at a time) to
be restored if you want the directory entries properly restored.
\end{itemize}
\section{Restoring on Windows}
\label{Windows}
\index[general]{Restoring on Windows}
\index[general]{Windows!Restoring on}
If you are restoring on Windows systems, Bareos will restore the files
with the original ownerships and permissions as would be expected. This is
also true if you are restoring those files to an alternate directory (using
the Where option in restore). However, if the alternate directory does not
already exist, the Bareos File daemon (Client) will try to create it. In
some cases, it may not create the directories, and if it does since the
File daemon runs under the SYSTEM account, the directory will be created
with SYSTEM ownership and permissions. In this case, you may have problems
accessing the newly restored files.
To avoid this problem, you should create any alternate directory before
doing the restore. Bareos will not change the ownership and permissions of
the directory if it is already created as long as it is not one of the
directories being restored (i.e. written to tape).
The default restore location is {\bf /tmp/bareos-restores/} and if you are
restoring from drive {\bf E:}, the default will be
{\bf /tmp/bareos-restores/e/}, so you should ensure that this directory
exists before doing the restore, or use the {\bf mod} option to
select a different {\bf where} directory that does exist.
Some users have experienced problems restoring files that participate in
the Active Directory. They also report that changing the userid under which
Bareos (bareos-fd.exe) runs, from SYSTEM to a Domain Admin userid, resolves
the problem.
\section{Restoring Files Can Be Slow}
\index[general]{Slow!Restoring Files Can Be}
\index[general]{Restoring Files Can Be Slow}
\TODO{move to subsection.}
Restoring files is generally {\bf much} slower than backing them up for several
reasons. The first is that during a backup the tape is normally already
positioned and Bareos only needs to write. On the other hand, because restoring
files is done so rarely, Bareos keeps only the start file and block on the
tape for the whole job rather than on a file by file basis which would use
quite a lot of space in the catalog.
Bareos will forward space to the correct file mark on the tape for the Job,
then forward space to the correct block, and finally sequentially read each
record until it gets to the correct one(s) for the file or files you want to
restore. Once the desired files are restored, Bareos will stop reading the
tape.
Finally, instead of just reading a file for backup, during the restore, Bareos
must create the file, and the operating system must allocate disk space for
the file as Bareos is restoring it.
For all the above reasons the restore process is generally much slower than
backing up (sometimes it takes three times as long).
\section{Problems Restoring Files}
\index[general]{Files!Problems Restoring}
\index[general]{Problems Restoring Files}
\TODO{move to appendix/troubleshooting}
The most frequent problems users have restoring files are error messages such
as:
\footnotesize
\begin{verbatim}
04-Jan 00:33 z217-sd: RestoreFiles.2005-01-04_00.31.04 Error:
block.c:868 Volume data error at 20:0! Short block of 512 bytes on
device /dev/tape discarded.
\end{verbatim}
\normalsize
or
\footnotesize
\begin{verbatim}
04-Jan 00:33 z217-sd: RestoreFiles.2005-01-04_00.31.04 Error:
block.c:264 Volume data error at 20:0! Wanted ID: "BB02", got ".".
Buffer discarded.
\end{verbatim}
\normalsize
Both these kinds of messages indicate that you were probably running your tape
drive in fixed block mode rather than variable block mode. Fixed block mode
will work with any program that reads tapes sequentially such as tar, but
Bareos repositions the tape on a block basis when restoring files because this
will speed up the restore by orders of magnitude when only a few files are being
restored. There are several ways that you can attempt to recover from this
unfortunate situation.
Try the following things, each separately, and reset your Device resource to
what it is now after each individual test:
\begin{enumerate}
\item Set "Block Positioning = no" in your Device resource and try the
restore. This is a new directive and untested.
\item Set "Minimum Block Size = 512" and "Maximum Block Size = 512" and
try the restore. If you are able to determine the block size your drive
was previously using, you should try that size if 512 does not work.
This is a really horrible solution, and it is not at all recommended
to continue backing up your data without correcting this condition.
Please see the Tape Testing chapter for more on this.
\item Try editing the restore.bsr file at the Run xxx yes/mod/no prompt
before starting the restore job and remove all the VolBlock statements.
These are what causes Bareos to reposition the tape, and where problems
occur if you have a fixed block size set for your drive. The VolFile
commands also cause repositioning, but this will work regardless of the
block size.
\item Use bextract to extract the files you want -- it reads the Volume
sequentially if you use the include list feature, or if you use a .bsr
file, but remove all the VolBlock statements after the .bsr file is
created (at the Run yes/mod/no) prompt but before you start the restore.
\end{enumerate}
\section{Restore Errors}
\index[general]{Errors!Restore}
\index[general]{Restore Errors}
There are a number of reasons why there may be restore errors or
warning messages. Some of the more common ones are:
\begin{description}
\item [file count mismatch]
This can occur for the following reasons:
\begin{itemize}
\item You requested Bareos not to overwrite existing or newer
files.
\item A Bareos miscount of files/directories. This is an
on-going problem due to the complications of directories,
soft/hard link, and such. Simply check that all the files you
wanted were actually restored.
\end{itemize}
\item [file size error]
When Bareos restores files, it checks that the size of the
restored file is the same as the file status data it saved
when starting the backup of the file. If the sizes do not
agree, Bareos will print an error message. This size mismatch
most often occurs because the file was being written as Bareos
backed up the file. In this case, the size that Bareos
restored will be greater than the status size. This often
happens with log files.
If the restored size is smaller, then you should be concerned
about a possible tape error and check the Bareos output as
well as your system logs.
\end{description}
\section{Example Restore Job Resource}
\index[general]{Resource!Example Restore Job}
\footnotesize
\begin{verbatim}
Job {
Name = "RestoreFiles"
Type = Restore
Client = Any-client
FileSet = "Any-FileSet"
Storage = Any-storage
Where = /tmp/bareos-restores
Messages = Standard
Pool = Default
}
\end{verbatim}
\normalsize
If {\bf Where} is not specified, the default location for restoring files will
be their original locations.
\label{Selection}
\section{File Selection Commands}
\index[general]{Console!File Selection}
\index[general]{File Selection Commands}
After you have selected the Jobs to be restored and Bareos has created the
in-memory directory tree, you will enter file selection mode as indicated by
the dollar sign ({\bf \$}) prompt. While in this mode, you may use the
commands listed above. The basic idea is to move up and down the in memory
directory structure with the {\bf cd} command much as you normally do on the
system. Once you are in a directory, you may select the files that you want
restored. As a default no files are marked to be restored. If you wish to
start with all files, simply enter: {\bf cd /} and {\bf mark *}. Otherwise
proceed to select the files you wish to restore by marking them with the {\bf
mark} command. The available commands are:
\begin{description}
\item [cd]
The {\bf cd} command changes the current directory to the argument specified.
It operates much like the Unix {\bf cd} command. Wildcard specifications are
not permitted.
Note, on Windows systems, the various drives (c:, d:, ...) are treated like a
directory within the file tree while in the file selection mode. As a
consequence, you must do a {\bf cd c:} or possibly in some cases a {\bf cd
C:} (note upper case) to get down to the first directory.
\item [dir]
\index[dir]{dir}
The {\bf dir} command is similar to the {\bf ls} command, except that it
prints it in long format (all details). This command can be a bit slower
than the {\bf ls} command because it must access the catalog database for
the detailed information for each file.
\item [estimate]
\index[dir]{estimate}
The {\bf estimate} command prints a summary of the total files in the tree,
how many are marked to be restored, and an estimate of the number of bytes
to be restored. This can be useful if you are short on disk space on the
machine where the files will be restored.
\item [find]
\index[dir]{find}
The {\bf find} command accepts one or more arguments and displays all files
in the tree that match that argument. The argument may have wildcards. It is
somewhat similar to the Unix command {\bf find / -name arg}.
\item [ls]
The {\bf ls} command produces a listing of all the files contained in the
current directory much like the Unix {\bf ls} command. You may specify an
argument containing wildcards, in which case only those files will be
listed.
Any file that is marked to be restored will have its name preceded by an
asterisk ({\bf *}). Directory names will be terminated with a forward slash