This repository has been archived by the owner on Mar 19, 2021. It is now read-only.
/
programs.tex
1575 lines (1322 loc) · 65.8 KB
/
programs.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{Bareos Programs}
\label{_UtilityChapter}
This document describes the utility programs written to aid Bareos users and
developers in dealing with Volumes external to Bareos adn to perform other useful tasks.
\section{Parameter}
\subsection{Specifying the Configuration File}
\index[general]{Specifying the Configuration File}
Each of the utilities that deal with Volumes require a valid
Storage daemon configuration file \path|bareos-sd.conf| (actually, the only part of the
configuration file that these programs need is the {\bf Device} resource
definitions). This permits the programs to find the configuration parameters
for your archive device (generally a tape drive).
Using the {\bf -c} option a custom storage daemon configuration file can be selected.
\subsection{Specifying a Device Name For a Tape}
\index[general]{Tape!Device Name}
\index[general]{Specifying a Device Name For a Tape}
Each of these programs require a {\bf device-name} where the Volume can be
found. In the case of a tape, this is the physical device name such as {\bf
/dev/nst0} or {\bf /dev/rmt/0ubn} depending on your system. For the program to
work, it must find the identical name in the Device resource of the
configuration file. See below for specifying Volume names.
Please note that if you have Bareos running and you want to use
one of these programs, you will either need to stop the Storage daemon, or
{\bf unmount} any tape drive you want to use, otherwise the drive
will {\bf busy} because Bareos is using it.
\subsection{Specifying a Device Name For a File}
\index[general]{File!Device Name}
\index[general]{Specifying a Device Name For a File}
If you are attempting to read or write an archive file rather than a tape, the
{\bf device-name} should be the full path to the archive location including
the filename. The filename (last part of the specification) will be stripped
and used as the Volume name, and the path (first part before the filename)
must have the same entry in the configuration file. So, the path is equivalent
to the archive device name, and the filename is equivalent to the volume name.
The default file storage path is \fileStoragePath.
\subsection{Specifying Volumes}
\index[general]{Volumes!Specifying}
\index[general]{Specifying Volumes}
\index[general]{Bootstrap}
Often you must specify the Volume name to the programs below.
The best method to do so is to specify a
{\bf bootstrap} file on the command line with the {\bf -b} option. As part of
the bootstrap file, you will then specify the Volume name or Volume names if
more than one volume is needed. For example, suppose you want to read tapes
{\bf tape1} and {\bf tape2}. First construct a {\bf bootstrap} file named say,
{\bf list.bsr} which contains:
\footnotesize
\begin{verbatim}
Volume=test1|test2
\end{verbatim}
\normalsize
where each Volume is separated by a vertical bar. Then simply use:
\footnotesize
\begin{verbatim}
bls -b list.bsr /dev/nst0
\end{verbatim}
\normalsize
In the case of Bareos Volumes that are on files, you may simply append volumes
as follows:
\footnotesize
\begin{verbatim}
bls /tmp/test1\|test2
\end{verbatim}
\normalsize
where the backslash (\textbackslash{}) was necessary as a shell escape to
permit entering the vertical bar (|).
And finally, if you feel that specifying a Volume name is a bit complicated
with a bootstrap file, you can use the {\bf -V} option (on all programs except
{\bf bcopy}) to specify one or more Volume names separated by the vertical bar
(|). For example,
\footnotesize
\begin{verbatim}
bls -V Vol001 /dev/nst0
\end{verbatim}
\normalsize
You may also specify an asterisk (*) to indicate that the program should
accept any volume. For example:
\footnotesize
\begin{verbatim}
bls -V* /dev/nst0
\end{verbatim}
\normalsize
\section{Bareos Daemons}
\subsection{Daemon Command Line Options}
\index[general]{Daemon!Command Line Options}
\index[general]{Command Line Options!Daemon}
Each of the three daemons (Director, File, Storage) accepts a small set of
options on the command line. In general, each of the daemons as well as the
Console program accepts the following options:
\begin{description}
\item [-c {\textless}file{\textgreater}]
Define the file to use as a configuration file. The default is the daemon
name followed by {\bf .conf} i.e. {\bf bareos-dir.conf} for the Director,
{\bf bareos-fd.conf} for the File daemon, and {\bf bareos-sd} for the Storage
daemon.
\item [-d nn]
Set the debug level to {\bf nn}. Higher levels of debug cause more
information to be displayed on STDOUT concerning what the daemon is doing.
\item [-f]
Run the daemon in the foreground. This option is needed to run the daemon
under the debugger.
\item [-g {\textless}group{\textgreater}]
Run the daemon under this group. This must be a group name, not a GID.
\item [-s]
Do not trap signals. This option is needed to run the daemon under the
debugger.
\item [-t]
Read the configuration file and print any error messages, then immediately
exit. Useful for syntax testing of new configuration files.
\item [-u {\textless}user{\textgreater}]
Run the daemon as this user. This must be a user name, not a UID.
\item [-v]
Be more verbose or more complete in printing error and informational
messages. Recommended.
\item [-?]
Print the version and list of options.
\end{description}
\subsection{bareos-dir}
\index[general]{Command!bareos-dir}
\index[dir]{Command Line Options}
Bareos Director.
\TODO{Bareos Director describe command line arguments}
\subsection{bareos-sd}
\index[general]{Command!bareos-sd}
\index[sd]{Command Line Options}
Baroes Storage Daemon
\TODO{Bareos Storage Daemon describe command line arguments}
\subsection{bareos-fd}
\index[general]{Command!bareos-fd}
\index[fd]{Command Line Options}
Baroes File Daemon
\TODO{Bareos File Daemon describe command line arguments}
\section{Interactive Programs}
\subsection{bconsole}
\index[general]{Command!bconsole}
\index[console]{Command Line Options}
Bareos console.
\TODO{Bareos console describe command line arguments}
needs config file
\subsection{bat}
\index[general]{Command!bat}
\section{Volume Utility Commands}
\index[general]{Volume Utility Tools}
\index[general]{Tools!Volume Utility}
\subsection{bls}
\label{bls}
\index[general]{bls}
\index[general]{Command!bls}
{\bf bls} can be used to do an {\bf ls} type listing of a {\bf Bareos} tape or
file. It is called:
\footnotesize
\begin{verbatim}
Usage: bls [options] <device-name>
-b <file> specify a bootstrap file
-c <file> specify a Storage configuration file
-D <director> specify a director name specified in the Storage
configuration file for the Key Encryption Key selection
-d <nn> set debug level to <nn>
-dt print timestamp in debug output
-e <file> exclude list
-i <file> include list
-j list jobs
-k list blocks
(no j or k option) list saved files
-L dump label
-p proceed inspite of errors
-v be verbose
-V specify Volume names (separated by |)
-? print this message
\end{verbatim}
\normalsize
For example, to list the contents of a tape:
\footnotesize
\begin{verbatim}
bls -V Volume-name /dev/nst0
\end{verbatim}
\normalsize
Or to list the contents of a file:
\footnotesize
\begin{verbatim}
bls /var/lib/bareos/storage/testvol
or
bls -V testvol /var/lib/bareos/storage
\end{verbatim}
\normalsize
Note that, in the case of a file, the Volume name becomes the filename, so in
the above example, you will replace the {\bf Volume-name} with the name of the volume
(file) you wrote.
Normally if no options are specified, {\bf bls} will produce the equivalent
output to the {\bf ls -l} command for each file on the tape. Using other
options listed above, it is possible to display only the Job records, only the
tape blocks, etc. For example:
\footnotesize
\begin{verbatim}
bls: butil.c:282-0 Using device: "/var/lib/bareos/storage" for reading.
12-Sep 18:30 bls JobId 0: Ready to read from volume "testvol" on device "FileStorage" (/var/lib/bareos/storage).
bls JobId 1: -rwxr-xr-x 1 root root 4614 2013-01-22 22:24:11 /usr/sbin/service
bls JobId 1: -rwxr-xr-x 1 root root 13992 2013-01-22 22:24:12 /usr/sbin/rtcwake
bls JobId 1: -rwxr-xr-x 1 root root 6243 2013-02-06 11:01:29 /usr/sbin/update-fonts-scale
bls JobId 1: -rwxr-xr-x 1 root root 43240 2013-01-22 22:24:10 /usr/sbin/grpck
bls JobId 1: -rwxr-xr-x 1 root root 16894 2013-01-22 22:24:11 /usr/sbin/update-rc.d
bls JobId 1: -rwxr-xr-x 1 root root 9480 2013-01-22 22:47:43 /usr/sbin/gss_clnt_send_err
...
bls JobId 456: -rw-r----- 1 root bareos 1008 2013-05-23 13:17:45 /etc/bareos/bareos-fd.conf
bls JobId 456: -rw-r----- 1 bareos bareos 6026 2013-04-22 12:00:33 /etc/bareos/bareos-sd.conf.dpkg-dist
bls JobId 456: drwxr-xr-x 2 root root 4096 2013-07-04 17:40:21 /etc/bareos/
12-Sep 18:30 bls JobId 0: End of Volume at file 0 on device "FileStorage" (/var/lib/bareos/storage), Volume "testvol"
12-Sep 18:30 bls JobId 0: End of all volumes.
2972 files found.
\end{verbatim}
\normalsize
\subsubsection{Show Label Information}
\index[general]{bls!Label}
Using the \parameter{-L} the label information of a Volume is shown:
\begin{commandOut}{bls, Show Volume Label}{}{bls -L /var/lib/bareos/storage/testvol}
bls: butil.c:282-0 Using device: "/var/lib/bareos/storage" for reading.
12-Sep 18:41 bls JobId 0: Ready to read from volume "testvol" on device "FileStorage" (/var/lib/bareos/storage).
Volume Label:
Id : Bareos 0.9 mortal
VerNo : 10
VolName : File002
PrevVolName :
VolFile : 0
LabelType : VOL_LABEL
LabelSize : 147
PoolName : Default
MediaType : File
PoolType : Backup
HostName : debian6
Date label written: 06-Mar-2013 17:21
\end{commandOut}
\subsubsection{Listing Jobs}
\index[general]{Listing Jobs with bls}
\index[general]{bls!Listing Jobs}
If you are listing a Volume to determine what Jobs to restore, normally the
{\bf -j} option provides you with most of what you will need as long as you
don't have multiple clients. For example:
\begin{commandOut}{bls, Listing Jobs}{}{bls /var/lib/bareos/storage/testvol -j}
bls: butil.c:282-0 Using device: "/var/lib/bareos/storage" for reading.
12-Sep 18:33 bls JobId 0: Ready to read from volume "testvol" on device "FileStorage" (/var/lib/bareos/storage).
Volume Record: File:blk=0:193 SessId=1 SessTime=1362582744 JobId=0 DataLen=158
Begin Job Session Record: File:blk=0:64705 SessId=1 SessTime=1362582744 JobId=1
Job=BackupClient1.2013-03-06_17.22.48_05 Date=06-Mar-2013 17:22:51 Level=F Type=B
End Job Session Record: File:blk=0:6499290 SessId=1 SessTime=1362582744 JobId=1
Date=06-Mar-2013 17:22:52 Level=F Type=B Files=162 Bytes=6,489,071 Errors=0 Status=T
Begin Job Session Record: File:blk=0:6563802 SessId=2 SessTime=1362582744 JobId=2
Job=BackupClient1.2013-03-06_23.05.00_02 Date=06-Mar-2013 23:05:02 Level=I Type=B
End Job Session Record: File:blk=0:18832687 SessId=2 SessTime=1362582744 JobId=2
Date=06-Mar-2013 23:05:02 Level=I Type=B Files=3 Bytes=12,323,791 Errors=0 Status=T
...
Begin Job Session Record: File:blk=0:319219736 SessId=299 SessTime=1369307832 JobId=454
Job=BackupClient1.2013-09-11_23.05.00_25 Date=11-Sep-2013 23:05:03 Level=I Type=B
End Job Session Record: File:blk=0:319219736 SessId=299 SessTime=1369307832 JobId=454
Date=11-Sep-2013 23:05:03 Level=I Type=B Files=0 Bytes=0 Errors=0 Status=T
Begin Job Session Record: File:blk=0:319284248 SessId=301 SessTime=1369307832 JobId=456
Job=BackupCatalog.2013-09-11_23.10.00_28 Date=11-Sep-2013 23:10:03 Level=F Type=B
End Job Session Record: File:blk=0:320694269 SessId=301 SessTime=1369307832 JobId=456
Date=11-Sep-2013 23:10:03 Level=F Type=B Files=12 Bytes=1,472,681 Errors=0 Status=T
12-Sep 18:32 bls JobId 0: End of Volume at file 0 on device "FileStorage" (/var/lib/bareos/storage), Volume "testvol"
12-Sep 18:32 bls JobId 0: End of all volumes.
\end{commandOut}
Adding the {\bf -v} option will display virtually all information that is
available for each record.
\subsubsection{Listing Blocks}
\index[general]{Listing Blocks with bls}
\index[general]{bls!Listing Blocks}
Normally, except for debugging purposes, you will not need to list Bareos
blocks (the "primitive" unit of Bareos data on the Volume). However, you can
do so with:
\footnotesize
\begin{verbatim}
bls -k /tmp/File002
bls: butil.c:148 Using device: /tmp
Block: 1 size=64512
Block: 2 size=64512
...
Block: 65 size=64512
Block: 66 size=19195
bls: Got EOF on device /tmp
End of File on device
\end{verbatim}
\normalsize
By adding the {\bf -v} option, you can get more information, which can be
useful in knowing what sessions were written to the volume:
\footnotesize
\begin{verbatim}
bls -k -v /tmp/File002
Date label written: 2002-10-19 at 21:16
Block: 1 blen=64512 First rec FI=VOL_LABEL SessId=1 SessTim=1035062102 Strm=0 rlen=147
Block: 2 blen=64512 First rec FI=6 SessId=1 SessTim=1035062102 Strm=DATA rlen=4087
Block: 3 blen=64512 First rec FI=12 SessId=1 SessTim=1035062102 Strm=DATA rlen=5902
Block: 4 blen=64512 First rec FI=19 SessId=1 SessTim=1035062102 Strm=DATA rlen=28382
...
Block: 65 blen=64512 First rec FI=83 SessId=1 SessTim=1035062102 Strm=DATA rlen=1873
Block: 66 blen=19195 First rec FI=83 SessId=1 SessTim=1035062102 Strm=DATA rlen=2973
bls: Got EOF on device /tmp
End of File on device
\end{verbatim}
\normalsize
Armed with the SessionId and the SessionTime, you can extract just about
anything.
If you want to know even more, add a second {\bf -v} to the command line to
get a dump of every record in every block.
\footnotesize
\begin{verbatim}
bls -k -v -v /tmp/File002
bls: block.c:79 Dump block 80f8ad0: size=64512 BlkNum=1
Hdrcksum=b1bdfd6d cksum=b1bdfd6d
bls: block.c:92 Rec: VId=1 VT=1035062102 FI=VOL_LABEL Strm=0 len=147 p=80f8b40
bls: block.c:92 Rec: VId=1 VT=1035062102 FI=SOS_LABEL Strm=-7 len=122 p=80f8be7
bls: block.c:92 Rec: VId=1 VT=1035062102 FI=1 Strm=UATTR len=86 p=80f8c75
bls: block.c:92 Rec: VId=1 VT=1035062102 FI=2 Strm=UATTR len=90 p=80f8cdf
bls: block.c:92 Rec: VId=1 VT=1035062102 FI=3 Strm=UATTR len=92 p=80f8d4d
bls: block.c:92 Rec: VId=1 VT=1035062102 FI=3 Strm=DATA len=54 p=80f8dbd
bls: block.c:92 Rec: VId=1 VT=1035062102 FI=3 Strm=MD5 len=16 p=80f8e07
bls: block.c:92 Rec: VId=1 VT=1035062102 FI=4 Strm=UATTR len=98 p=80f8e2b
bls: block.c:92 Rec: VId=1 VT=1035062102 FI=4 Strm=DATA len=16 p=80f8ea1
bls: block.c:92 Rec: VId=1 VT=1035062102 FI=4 Strm=MD5 len=16 p=80f8ec5
bls: block.c:92 Rec: VId=1 VT=1035062102 FI=5 Strm=UATTR len=96 p=80f8ee9
bls: block.c:92 Rec: VId=1 VT=1035062102 FI=5 Strm=DATA len=1783 p=80f8f5d
bls: block.c:92 Rec: VId=1 VT=1035062102 FI=5 Strm=MD5 len=16 p=80f9668
bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=UATTR len=95 p=80f968c
bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=DATA len=32768 p=80f96ff
bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=DATA len=32768 p=8101713
bls: block.c:79 Dump block 80f8ad0: size=64512 BlkNum=2
Hdrcksum=9acc1e7f cksum=9acc1e7f
bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=contDATA len=4087 p=80f8b40
bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=DATA len=31970 p=80f9b4b
bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=MD5 len=16 p=8101841
...
\end{verbatim}
\normalsize
\subsection{bextract}
\label{bextract}
\index[general]{bextract}
\index[general]{Command!bextract}
\index[general]{Disaster!Recovery!bextract}
If you find yourself using {\bf bextract}, you probably have done
something wrong. For example, if you are trying to recover a file
but are having problems, please see the \ilink{Restoring When Things Go
Wrong}{database_restore} section of the Restore chapter of this manual.
Normally, you will restore files by running a {\bf Restore} Job from the {\bf
Console} program. However, {\bf bextract} can be used to extract a single file
or a list of files from a Bareos tape or file. In fact, {\bf bextract} can be
a useful tool to restore files to an empty system assuming you are able to
boot, you have statically linked {\bf bextract} and you have an appropriate
{\bf bootstrap} file.
Please note that some of the current limitations of bextract are:
\begin{enumerate}
\item It cannot restore access control lists (ACL) that have been
backed up along with the file data.
\item It cannot restore encrypted files.
\item The command line length is relatively limited,
which means that you cannot enter a huge number of volumes. If you need to
enter more volumes than the command line supports, please use a bootstrap
file (see below).
\end{enumerate}
It is called:
\footnotesize
\begin{verbatim}
Usage: bextract <options> <bareos-archive-device-name> <directory-to-store-files>
-b <file> specify a bootstrap file
-c <file> specify a Storage configuration file
-D <director> specify a director name specified in the Storage
configuration file for the Key Encryption Key selection
-d <nn> set debug level to <nn>
-dt print timestamp in debug output
-e <file> exclude list
-i <file> include list
-p proceed inspite of I/O errors
-v verbose
-V <volumes> specify Volume names (separated by |)
-? print this message
\end{verbatim}
\normalsize
where {\bf device-name} is the Archive Device (raw device name or full
filename) of the device to be read, and {\bf directory-to-store-files} is a
path prefix to prepend to all the files restored.
NOTE: On Windows systems, if you specify a prefix of say d:/tmp, any file that
would have been restored to {\bf c:/My Documents} will be restored to {\bf
d:/tmp/My Documents}. That is, the original drive specification will be
stripped. If no prefix is specified, the file will be restored to the original
drive.
\subsubsection{Extracting with Include or Exclude Lists}
Using the {\bf -e} option, you can specify a file containing a list of files
to be excluded. Wildcards can be used in the exclusion list. This option will
normally be used in conjunction with the {\bf -i} option (see below). Both the
{\bf -e} and the {\bf -i} options may be specified at the same time as the
{\bf -b} option. The bootstrap filters will be applied first, then the include
list, then the exclude list.
Likewise, and probably more importantly, with the {\bf -i} option, you can
specify a file that contains a list (one file per line) of files and
directories to include to be restored. The list must contain the full filename
with the path. If you specify a path name only, all files and subdirectories
of that path will be restored. If you specify a line containing only the
filename (e.g. {\bf my-file.txt}) it probably will not be extracted because
you have not specified the full path.
For example, if the file {\bf include-list} contains:
\footnotesize
\begin{verbatim}
/etc/bareos
/usr/sbin
\end{verbatim}
\normalsize
Then the command:
\footnotesize
\begin{verbatim}
bextract -i include-list -V Volume /dev/nst0 /tmp
\end{verbatim}
\normalsize
will restore from the Bareos archive {\bf /dev/nst0} all files and directories
in the backup from {\bf /etc/bareos} and from {\bf /usr/sbin}. The
restored files will be placed in a file of the original name under the
directory {\bf /tmp} (i.e. /tmp/etc/bareos/... and
/tmp/usr/sbin/...).
\subsubsection{Extracting With a Bootstrap File}
The {\bf -b} option is used to specify a {\bf bootstrap} file containing the
information needed to restore precisely the files you want. Specifying a {\bf
bootstrap} file is optional but recommended because it gives you the most
control over which files will be restored. For more details on the {\bf
bootstrap} file, please see
\ilink{Restoring Files with the Bootstrap File}{BootstrapChapter}
chapter of this document. Note, you may also use a bootstrap file produced by
the {\bf restore} command. For example:
\footnotesize
\begin{verbatim}
bextract -b bootstrap-file /dev/nst0 /tmp
\end{verbatim}
\normalsize
The bootstrap file allows detailed specification of what files you want
restored (extracted). You may specify a bootstrap file and include and/or
exclude files at the same time. The bootstrap conditions will first be
applied, and then each file record seen will be compared to the include and
exclude lists.
\subsubsection{Extracting From Multiple Volumes}
If you wish to extract files that span several Volumes, you can specify the
Volume names in the bootstrap file or you may specify the Volume names on the
command line by separating them with a vertical bar. See the section above
under the {\bf bls} program entitled {\bf Listing Multiple Volumes} for more
information. The same techniques apply equally well to the {\bf bextract}
program or read the \ilink{Bootstrap}{BootstrapChapter}
chapter of this document.
\subsection{bscan}
\label{bscan}
\index[general]{bscan}
\index[general]{Command!bscan}
If you find yourself using this program, you have probably done something
wrong. For example, the best way to recover a lost or damaged Bareos
database is to reload the database by using the bootstrap file that
was written when you saved it (default Bareos-dir.conf file).
The {\bf bscan} program can be used to re-create a database (catalog)
records from the backup information written to one or more Volumes. This
is normally needed only if one or more Volumes have been pruned or purged
from your catalog so that the records on the Volume are no longer in the
catalog, or for Volumes that you have archived. Note, if you scan in
Volumes that were previously purged, you will be able to do restores from
those Volumes. However, unless you modify the Job and File retention times
for the Jobs that were added by scanning, the next time you run any backup Job
with the same name, the records will be pruned again. Since it takes a
long time to scan Volumes this can be very frustrating.
With some care, {\bf bscan} can also be used to synchronize your existing
catalog with a Volume. Although we have never seen a case of bscan
damaging a catalog, since bscan modifies your catalog, we recommend that
you do a simple ASCII backup of your database before running {\bf bscan}
just to be sure. See \ilink{Compacting Your Database}{CompactingMySQL} for
the details of making a copy of your database.
{\bf bscan} can also be useful in a disaster recovery situation, after the
loss of a hard disk, if you do not have a valid {\bf bootstrap} file for
reloading your system, or if a Volume has been recycled but not overwritten,
you can use {\bf bscan} to re-create your database, which can then be used to
{\bf restore} your system or a file to its previous state.
It is called:
\footnotesize
\begin{verbatim}
Usage: bscan [options] <Bareos-archive>
-B <driver name> specify the database driver name (default NULL) <postgresql|mysql|sqlite>
-b bootstrap specify a bootstrap file
-c <file> specify configuration file
-d <nn> set debug level to nn
-dt print timestamp in debug output
-m update media info in database
-D <director> specify a director name specified in the Storage
configuration file for the Key Encryption Key selection
-n <name> specify the database name (default Bareos)
-u <user> specify database user name (default Bareos)
-P <password> specify database password (default none)
-h <host> specify database host (default NULL)
-t <port> specify database port (default 0)
-p proceed inspite of I/O errors
-r list records
-s synchronize or store in database
-S show scan progress periodically
-v verbose
-V <Volumes> specify Volume names (separated by |)
-w <dir> specify working directory (default from conf file)
-? print this message
\end{verbatim}
\normalsize
As Bareos supports loading its database backend dynamically you need to specify
the right database driver to use using the {\bf -B} option.
If you are using MySQL or PostgreSQL, there is no need to supply a working
directory since in that case, bscan knows where the databases are. However, if
you have provided security on your database, you may need to supply either the
database name ({\bf -b} option), the user name ({\bf -u} option), and/or the
password ({\bf -p}) options.
NOTE: before {\bf bscan} can work, it needs at least a bare bones valid
database. If your database exists but some records are missing because
they were pruned, then you are all set. If your database was lost or
destroyed, then you must first ensure that you have the SQL program running
(MySQL or PostgreSQL), then you must create the Bareos database (normally
named bareos), and you must create the Bareos tables.
This is explained in the
\ilink{Installation}{CreateDatabase} chapter of the manual. Finally, before
scanning into an empty database, you must start and stop the Director with
the appropriate Bareos-dir.conf file so that it can create the Client and
Storage records which are not stored on the Volumes. Without these
records, scanning is unable to connect the Job records to the proper
client.
Forgetting for the moment the extra complications of a full rebuild of
your catalog, let's suppose that you did a backup to Volumes "Vol001"
and "Vol002", then sometime later all records of one or both those
Volumes were pruned or purged from the
database. By using {\bf bscan} you can recreate the catalog entries for
those Volumes and then use the {\bf restore} command in the Console to restore
whatever you want. A command something like:
\footnotesize
\begin{verbatim}
bscan -v -V Vol001\|Vol002 /dev/nst0
\end{verbatim}
\normalsize
will give you an idea of what is going to happen without changing
your catalog. Of course, you may need to change the path to the Storage
daemon's conf file, the Volume name, and your tape (or disk) device name. This
command must read the entire tape, so if it has a lot of data, it may take a
long time, and thus you might want to immediately use the command listed
below. Note, if you are writing to a disk file, replace the device name with
the path to the directory that contains the Volumes. This must correspond to
the Archive Device in the conf file.
Then to actually write or store the records in the catalog, add the {\bf -s}
option as follows:
\footnotesize
\begin{verbatim}
bscan -s -m -v -V Vol001\|Vol002 /dev/nst0
\end{verbatim}
\normalsize
When writing to the database, if bscan finds existing records, it will
generally either update them if something is wrong or leave them alone. Thus
if the Volumes you are scanning are all or partially in the catalog already, no
harm will be done to that existing data. Any missing data will simply be
added.
If you have multiple tapes, you should scan them with:
\footnotesize
\begin{verbatim}
bscan -s -m -v -V Vol001\|Vol002\|Vol003 /dev/nst0
\end{verbatim}
\normalsize
Since there is a limit on the command line length (511 bytes) accepted
by {\bf bscan}, if you have too many Volumes, you will need to manually
create a bootstrap file. See the \ilink{Bootstrap}{BootstrapChapter}
chapter of this manual for more details, in particular the section
entitled \ilink{Bootstrap for bscan}{bscanBootstrap}. Basically, the
.bsr file for the above example might look like:
\footnotesize
\begin{verbatim}
Volume=Vol001
Volume=Vol002
Volume=Vol003
\end{verbatim}
\normalsize
Note: {\bf bscan} does not support supplying Volume names on the
command line and at the same time in a bootstrap file. Please
use only one or the other.
You should, always try to specify the tapes in the order they are written.
If you do not, any Jobs that span a volume may not be fully or properly
restored. However, bscan can handle scanning tapes that are not sequential. Any
incomplete records at the end of the tape will simply be ignored in that
case. If you are simply repairing an existing catalog, this may be OK, but
if you are creating a new catalog from scratch, it will leave your database
in an incorrect state. If you do not specify all necessary Volumes on a
single bscan command, bscan will not be able to correctly restore the
records that span two volumes. In other words, it is much better to
specify two or three volumes on a single bscan command (or in a .bsr file)
rather than run bscan two or three times, each with a single volume.
Note, the restoration process using bscan is not identical to the original
creation of the catalog data. This is because certain data such as Client
records and other non-essential data such
as volume reads, volume mounts, etc is not stored on the Volume, and thus is
not restored by bscan. The results of bscanning are, however, perfectly valid,
and will permit restoration of any or all the files in the catalog using the
normal Bareos console commands. If you are starting with an empty catalog
and expecting bscan to reconstruct it, you may be a bit disappointed, but
at a minimum, you must ensure that your Bareos-dir.conf file is the same
as what it previously was -- that is, it must contain all the appropriate
Client resources so that they will be recreated in your new database {\bf
before} running bscan. Normally when the Director starts, it will recreate
any missing Client records in the catalog. Another problem you will have
is that even if the Volumes (Media records) are recreated in the database,
they will not have their autochanger status and slots properly set. As a
result, you will need to repair that by using the {\bf update slots}
command. There may be other considerations as well. Rather than
bscanning, you should always attempt to recover you previous catalog
backup.
\subsubsection{Using bscan to Compare a Volume to an existing Catalog}
\index[general]{Catalog!Using bscan to Compare a Volume to an existing}
If you wish to compare the contents of a Volume to an existing catalog without
changing the catalog, you can safely do so if and only if you do {\bf not}
specify either the {\bf -m} or the {\bf -s} options.
However, the comparison routines are not as good or as thorough
as they should be, so we don't particularly recommend this mode other than for
testing.
\subsubsection{Using bscan to Recreate a Catalog from a Volume}
\index[general]{Catalog!Recreate Using bscan}
\index[general]{bscan!Recreate Catalog}
This is the mode for which {\bf bscan} is most useful. You can either {\bf
bscan} into a freshly created catalog, or directly into your existing catalog
(after having made an ASCII copy as described above). Normally, you should
start with a freshly created catalog that contains no data.
Starting with a single Volume named {\bf TestVolume1}, you run a command such
as:
\footnotesize
\begin{verbatim}
bscan -V TestVolume1 -v -s -m /dev/nst0
\end{verbatim}
\normalsize
If there is more than one volume, simply append it to the first one separating
it with a vertical bar. You may need to precede the vertical bar with a
forward slash escape the shell -- e.g. {\bf
TestVolume1\textbackslash{}|TestVolume2}. The {\bf -v} option was added for
verbose output (this can be omitted if desired). The {\bf -s} option that
tells {\bf bscan} to store information in the database. The physical device
name {\bf /dev/nst0} is specified after all the options.
{\bf} For example, after having done a full backup of a directory, then two
incrementals, I reinitialized the SQLite database as described above, and
using the bootstrap.bsr file noted above, I entered the following command:
\footnotesize
\begin{verbatim}
bscan -b bootstrap.bsr -v -s /dev/nst0
\end{verbatim}
\normalsize
which produced the following output:
\footnotesize
\begin{verbatim}
bscan: bscan.c:182 Using Database: Bareos, User: bacula
bscan: bscan.c:673 Created Pool record for Pool: Default
bscan: bscan.c:271 Pool type "Backup" is OK.
bscan: bscan.c:632 Created Media record for Volume: TestVolume1
bscan: bscan.c:298 Media type "DDS-4" is OK.
bscan: bscan.c:307 VOL_LABEL: OK for Volume: TestVolume1
bscan: bscan.c:693 Created Client record for Client: Rufus
bscan: bscan.c:769 Created new JobId=1 record for original JobId=2
bscan: bscan.c:717 Created FileSet record "Users Files"
bscan: bscan.c:819 Updated Job termination record for new JobId=1
bscan: bscan.c:905 Created JobMedia record JobId 1, MediaId 1
bscan: Got EOF on device /dev/nst0
bscan: bscan.c:693 Created Client record for Client: Rufus
bscan: bscan.c:769 Created new JobId=2 record for original JobId=3
bscan: bscan.c:708 Fileset "Users Files" already exists.
bscan: bscan.c:819 Updated Job termination record for new JobId=2
bscan: bscan.c:905 Created JobMedia record JobId 2, MediaId 1
bscan: Got EOF on device /dev/nst0
bscan: bscan.c:693 Created Client record for Client: Rufus
bscan: bscan.c:769 Created new JobId=3 record for original JobId=4
bscan: bscan.c:708 Fileset "Users Files" already exists.
bscan: bscan.c:819 Updated Job termination record for new JobId=3
bscan: bscan.c:905 Created JobMedia record JobId 3, MediaId 1
bscan: Got EOF on device /dev/nst0
bscan: bscan.c:652 Updated Media record at end of Volume: TestVolume1
bscan: bscan.c:428 End of Volume. VolFiles=3 VolBlocks=57 VolBytes=10,027,437
\end{verbatim}
\normalsize
The key points to note are that {\bf bscan} prints a line when each major
record is created. Due to the volume of output, it does not print a line for
each file record unless you supply the {\bf -v} option twice or more on the
command line.
In the case of a Job record, the new JobId will not normally be the same as
the original Jobid. For example, for the first JobId above, the new JobId is
1, but the original JobId is 2. This is nothing to be concerned about as it is
the normal nature of databases. {\bf bscan} will keep everything straight.
Although {\bf bscan} claims that it created a Client record for Client: Rufus
three times, it was actually only created the first time. This is normal.
You will also notice that it read an end of file after each Job (Got EOF on
device ...). Finally the last line gives the total statistics for the bscan.
If you had added a second {\bf -v} option to the command line, Bareos would
have been even more verbose, dumping virtually all the details of each Job
record it encountered.
Now if you start Bareos and enter a {\bf list jobs} command to the console
program, you will get:
\footnotesize
\begin{verbatim}
+-------+----------+------------------+------+-----+----------+----------+---------+
| JobId | Name | StartTime | Type | Lvl | JobFiles | JobBytes | JobStat |
+-------+----------+------------------+------+-----+----------+----------+---------+
| 1 | usersave | 2002-10-07 14:59 | B | F | 84 | 4180207 | T |
| 2 | usersave | 2002-10-07 15:00 | B | I | 15 | 2170314 | T |
| 3 | usersave | 2002-10-07 15:01 | B | I | 33 | 3662184 | T |
+-------+----------+------------------+------+-----+----------+----------+---------+
\end{verbatim}
\normalsize
which corresponds virtually identically with what the database contained
before it was re-initialized and restored with bscan. All the Jobs and Files
found on the tape are restored including most of the Media record. The Volume
(Media) records restored will be marked as {\bf Full} so that they cannot be
rewritten without operator intervention.
It should be noted that {\bf bscan} cannot restore a database to the exact
condition it was in previously because a lot of the less important information
contained in the database is not saved to the tape. Nevertheless, the
reconstruction is sufficiently complete, that you can run {\bf restore}
against it and get valid results.
An interesting aspect of restoring a catalog backup using {\bf bscan} is
that the backup was made while Bareos was running and writing to a tape. At
the point the backup of the catalog is made, the tape Bareos is writing to
will have say 10 files on it, but after the catalog backup is made, there
will be 11 files on the tape Bareos is writing. This there is a difference
between what is contained in the backed up catalog and what is actually on
the tape. If after restoring a catalog, you attempt to write on the same
tape that was used to backup the catalog, Bareos will detect the difference
in the number of files registered in the catalog compared to what is on the
tape, and will mark the tape in error.
There are two solutions to this problem. The first is possibly the simplest
and is to mark the volume as Used before doing any backups. The second is
to manually correct the number of files listed in the Media record of the
catalog. This procedure is documented elsewhere in the manual and involves
using the {\bf update volume} command in {\bf bconsole}.
\subsubsection{Using bscan to Correct the Volume File Count}
\index[general]{bscan!Correct Volume File Count}
\index[general]{Volume!File Count}
If the Storage daemon crashes during a backup Job, the catalog will not be
properly updated for the Volume being used at the time of the crash. This
means that the Storage daemon will have written say 20 files on the tape, but
the catalog record for the Volume indicates only 19 files.
Bareos refuses to write on a tape that contains a different number of files
from what is in the catalog. To correct this situation, you may run a {\bf
bscan} with the {\bf -m} option (but {\bf without} the {\bf -s} option) to
update only the final Media record for the Volumes read.
\subsubsection{After bscan}
\index[general]{bscan!after}
If you use {\bf bscan} to enter the contents of the Volume into an existing
catalog, you should be aware that the records you entered may be immediately
pruned during the next job, particularly if the Volume is very old or had been
previously purged. To avoid this, after running {\bf bscan}, you can manually
set the volume status (VolStatus) to {\bf Read-Only} by using the {\bf update}
command in the catalog. This will allow you to restore from the volume without
having it immediately purged. When you have restored and backed up the data,
you can reset the VolStatus to {\bf Used} and the Volume will be purged from
the catalog.
\subsection{bcopy}
\label{bcopy}
\index[general]{bcopy}
\index[general]{Command!bcopy}
The {\bf bcopy} program can be used to copy one {\bf Bareos} archive file to
another. For example, you may copy a tape to a file, a file to a tape, a file
to a file, or a tape to a tape. For tape to tape, you will need two tape
drives. In the
process of making the copy, no record of the information written to the new
Volume is stored in the catalog. This means that the new Volume, though it
contains valid backup data, cannot be accessed directly from existing catalog
entries. If you wish to be able to use the Volume with the Console restore
command, for example, you must first bscan the new Volume into the catalog.
\footnotesize
\begin{verbatim}
Usage: bcopy [-d debug_level] <input-archive> <output-archive>
-b bootstrap specify a bootstrap file
-c <file> specify configuration file
-D <director> specify a director name specified in the Storage
configuration file for the Key Encryption Key selection
-dnn set debug level to nn
-dt print timestamp in debug output
-i specify input Volume names (separated by |)
-o specify output Volume names (separated by |)
-p proceed inspite of I/O errors
-v verbose
-w dir specify working directory (default /tmp)
-? print this message
\end{verbatim}
\normalsize
By using a {\bf bootstrap} file, you can copy parts of a Bareos archive file
to another archive.
One of the objectives of this program is to be able to recover as much data as
possible from a damaged tape. However, the current version does not yet have
this feature.
As this is a new program, any feedback on its use would be appreciated. In
addition, I only have a single tape drive, so I have never been able to test
this program with two tape drives.
\subsection{btape}
\label{btape}
\index[general]{btape}
\index[general]{Command!btape}
This program permits a number of elementary tape operations via a tty command
interface. It works only with tapes and not with other kinds of Bareos
storage media (DVD, File, ...).
The {\bf test} command, described below,
can be very useful for testing older tape drive compatibility problems.
Aside from initial testing of tape drive compatibility with {\bf Bareos},
{\bf btape} will be mostly used by developers writing new tape drivers.
{\bf btape} can be dangerous to use with existing {\bf Bareos} tapes because
it will relabel a tape or write on the tape if so requested regardless that
the tape may contain valuable data, so please be careful and use it only on
blank tapes.
To work properly, {\bf btape} needs to read the Storage daemon's configuration
file. As a default, it will look for {\bf Bareos-sd.conf} in the current
directory. If your configuration file is elsewhere, please use the {\bf -c}
option to specify where.
The physical device name must be specified on the command line, and this
same device name must be present in the Storage daemon's configuration file
read by {\bf btape}
\footnotesize
\begin{verbatim}
Usage: btape <options> <device_name>
-b <file> specify bootstrap file
-c <file> set configuration file to file
-D <director> specify a director name specified in the Storage
configuration file for the Key Encryption Key selection
-d <nn> set debug level to nn
-dt print timestamp in debug output
-p proceed inspite of I/O errors
-s turn off signals
-v be verbose
-? print this message.
\end{verbatim}
\normalsize
\subsubsection{Using btape to Verify your Tape Drive}
\index[general]{Drive!Verify using btape}
An important reason for this program is to ensure that a Storage daemon