This repository has been archived by the owner on Mar 19, 2021. It is now read-only.
/
autochangers.tex
1074 lines (876 loc) · 40.5 KB
/
autochangers.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{Autochanger Support}
\label{AutochangersChapter}
\index[general]{Support!Autochanger}
\index[general]{Autochanger Support}
Bareos provides autochanger support for reading and writing tapes. In
order to work with an autochanger, Bareos requires a number of things, each of
which is explained in more detail after this list:
\begin{itemize}
\item A script that actually controls the autochanger according to commands
sent by Bareos. Bareos contains the script \command{mtx-changer}, that utilize the command \command{mtx}.
It's config file is normally located at \path|/etc/bareos/mtx-changer.conf|
\item That each Volume (tape) to be used must be defined in the Catalog and
have a Slot number assigned to it so that Bareos knows where the Volume is
in the autochanger. This is generally done with the {\bf label} command, but
can also done after the tape is labeled using the {\bf update slots}
command. See below for more details. You must pre-label the tapes manually
before using them.
\item Modifications to your Storage daemon's Device configuration resource to
identify that the device is a changer, as well as a few other parameters.
\item You should also modify your Storage resource definition in the
Director's configuration file so that you are automatically prompted for the
Slot when labeling a Volume.
\item You need to ensure that your Storage daemon
has access permissions to both the tape drive and the control device.
On Linux, the system user \user{bareos} is added to the groups \group{disk} and \group{tape},
so that it should have the permission to access the library.
\item You need to have {\bf Autochanger = yes} in your Storage resource
in your \path|bareos-dir.conf| file so that you will be prompted for the
slot number when you label Volumes.
\end{itemize}
Bareos uses its own \command{mtx-changer} script to interface with a program
that actually does the tape changing. Thus in principle, {\bf mtx-changer}
can be adapted to function with any autochanger program, or you can
call any other script or program. The current
version of {\bf mtx-changer} works with the \command{mtx} program.
FreeBSD users might need to adapt this script to use \command{chio}.
For more details, refer to the \ilink{Testing Autochanger}{AutochangerTesting} chapter.
Bareos also supports autochangers with barcode
readers. This support includes two Console commands: \bcommand{label barcodes}
and \bcommand{update slots}. For more details on these commands, see the chapter about \ilink{Barcode Support}{Barcodes}.
Current Bareos autochanger support does not include cleaning, stackers, or
silos. Stackers and silos are not supported because Bareos expects to
be able to access the Slots randomly.
However, if you are very careful to setup Bareos to access the Volumes
in the autochanger sequentially, you may be able to make Bareos
work with stackers (gravity feed and such).
In principle, if {\bf mtx} will operate your changer correctly, then it is
just a question of adapting the {\bf mtx-changer} script (or selecting one
already adapted) for proper interfacing.
% link does not exists any more:
%You can find a list of autochangers
%supported by {\bf mtx} at the following link:
%\elink{http://mtx.opensource-sw.net/compatibility.php}
%{http://mtx.opensource-sw.net/compatibility.php}.
%In addition, apparently certain versions of mtx, for example, version
%1.3.11 limit the number of slots to a maximum of 64. The solution was to
%use version 1.3.10.
If you are having troubles, please use the {\bf auto} command in the {\bf
btape} program to test the functioning of your autochanger with Bareos.
Please remember, that on most distributions, the Storage daemon
runs as user \user{bareos} and not as \user{root}.
You will need to ensure that the Storage daemon has sufficient
permissions to access the autochanger.
Some users have reported that the the Storage daemon blocks under certain
circumstances in trying to mount a volume on a drive that has a different
volume loaded. As best we can determine, this is simply a matter of
waiting a bit. The drive was previously in use writing a Volume, and
sometimes the drive will remain BLOCKED for a good deal of time (up to 7
minutes on a slow drive) waiting for the cassette to rewind and to unload
before the drive can be used with a different Volume.
\section{Knowing What SCSI Devices You Have}
\label{SCSI devices}
\index[general]{SCSI devices}
\index[general]{Devices!SCSI}
\index[general]{Devices!Detecting}
\subsection{Linux}
Under Linux, you can
\footnotesize
\begin{verbatim}
cat /proc/scsi/scsi
\end{verbatim}
\normalsize
to see what SCSI devices you have available. You can also:
\footnotesize
\begin{verbatim}
cat /proc/scsi/sg/device_hdr /proc/scsi/sg/devices
\end{verbatim}
\normalsize
to find out how to specify their control address ({\bf /dev/sg0} for the
first, {\bf /dev/sg1} for the second, ...) on the {\bf Changer Device = }
Bareos directive.
You can also use the excellent {\bf lsscsi} tool.
\footnotesize
\begin{verbatim}
$ lsscsi -g
[1:0:2:0] tape SEAGATE ULTRIUM06242-XXX 1619 /dev/st0 /dev/sg9
[1:0:14:0] mediumx STK L180 0315 /dev/sch0 /dev/sg10
[2:0:3:0] tape HP Ultrium 3-SCSI G24S /dev/st1 /dev/sg11
[3:0:0:0] enclosu HP A6255A HP04 - /dev/sg3
[3:0:1:0] disk HP 36.4G ST336753FC HP00 /dev/sdd /dev/sg4
\end{verbatim}
\normalsize
% missing link:
%For more detailed information on what SCSI devices you have please see
%the \ilink{Linux SCSI Tricks}{SCSITricks} section of the Tape Testing
%chapter of this manual.
\subsection{FreeBSD}
Under FreeBSD, use the following command to list the SCSI devices as well as the {\bf /dev/passn} that you will use on
the Bareos {\bf Changer Device = } directive:
\footnotesize
\begin{verbatim}
camcontrol devlist
\end{verbatim}
\normalsize
Please check that your Storage daemon has permission to access this
device.
The following tip for FreeBSD users comes from Danny Butroyd:
on reboot Bareos will NOT have permission to
control the device /dev/pass0 (assuming this is your changer device).
To get around this just edit the /etc/devfs.conf file and add the
following to the bottom:
\footnotesize
\begin{verbatim}
own pass0 root:bareos
perm pass0 0666
own nsa0.0 root:bareos
perm nsa0.0 0666
\end{verbatim}
\normalsize
This gives the bareos group permission to write to the nsa0.0 device
too just to be on the safe side. To bring these changes into effect
just run:-
/etc/rc.d/devfs restart
Basically this will stop you having to manually change permissions on these
devices to make Bareos work when operating the AutoChanger after a reboot.
% example directory does not exist:
% \label{scripts}
% \section{Example Scripts}
% \index[general]{Scripts!Example}
% \index[general]{Example Scripts}
%
% Please read the sections below so that you understand how autochangers work
% with Bareos. Although we supply a default {\bf mtx-changer} script, your
% autochanger may require some additional changes. If you want to see examples
% of configuration files and scripts, please look in the {\bf
% {\textless}bareos-src{\textgreater}/examples/devices} directory where you will find an
% example {\bf HP-autoloader.conf} Bareos Device resource, and several {\bf
% mtx-changer} scripts that have been modified to work with different
% autochangers.
\section{Slots}
\index[general]{Slots}
\label{Slots}
To properly address autochangers, Bareos must know which Volume is in each
{\bf slot} of the autochanger. Slots are where the changer cartridges reside
when not loaded into the drive. Bareos numbers these slots from one to the
number of cartridges contained in the autochanger.
Bareos will not automatically use a Volume in your autochanger unless it is
labeled and the slot number is stored in the catalog and the Volume is marked
as InChanger. This is because it must know where each volume is to
be able to load the volume.
For each Volume in your
changer, you will, using the Console program, assign a slot. This information
is kept in {\bf Bareos's} catalog database along with the other data for the
volume. If no slot is given, or the slot is set to zero, Bareos will not
attempt to use the autochanger even if all the necessary configuration records
are present. When doing a {\bf mount} command on an autochanger, you must
specify which slot you want mounted. If the drive is loaded with a tape
from another slot, it will unload it and load the correct tape, but
normally, no tape will be loaded because an {\bf unmount} command causes
Bareos to unload the tape in the drive.
You can check if the Slot number and InChanger flag are set by doing a:
\begin{verbatim}
list Volumes
\end{verbatim}
in the Console program.
\label{mult}
\section{Multiple Devices}
\index[general]{Devices!Multiple}
\index[general]{Multiple Devices}
Some autochangers have more than one read/write device (drive). The
\ilink{Autochanger resource}{AutochangerRes} permits you to group Device resources, where each device
represents a drive. The Director may still reference the Devices (drives)
directly, but doing so, bypasses the proper functioning of the
drives together. Instead, the Director (in the Storage resource)
should reference the Autochanger resource name. Doing so permits
the Storage daemon to ensure that only one drive uses the mtx-changer
script at a time, and also that two drives don't reference the
same Volume.
Multi-drive requires the use of the {\bf
Drive Index} directive in the Device resource of the Storage daemon's
configuration file. Drive numbers or the Device Index are numbered beginning
at zero, which is the default. To use the second Drive in an autochanger, you
need to define a second Device resource and set the Drive Index to 1 for
that device. In general, the second device will have the same {\bf Changer
Device} (control channel) as the first drive, but a different {\bf Archive
Device}.
As a default, Bareos jobs will prefer to write to a Volume that is
already mounted. If you have a multiple drive autochanger and you want
Bareos to write to more than one Volume in the same Pool at the same
time, you will need to set \ilink{Prefer Mounted Volumes} {PreferMountedVolumes}
in the Directors Job resource to {\bf no}. This will cause
the Storage daemon to maximize the use of drives.
\label{ConfigRecords}
\section{Device Configuration Records}
\index[general]{Records!Device Configuration}
\index[general]{Device Configuration Records}
Configuration of autochangers within Bareos is done in the Device resource of
the Storage daemon. Four records: {\bf Autochanger}, {\bf Changer Device},
{\bf Changer Command}, and {\bf Maximum Changer Wait} control how Bareos uses
the autochanger.
These four records, permitted in {\bf Device} resources, are described in
detail below. Note, however, that the {\bf Changer Device} and the
{\bf Changer Command} directives are not needed in the Device resource
if they are present in the {\bf Autochanger} resource.
\begin{description}
\xdirective{sd}{Autochanger}{yes {\textbar} no}{}{no}{}{%
The \configdirective{Autochanger} record specifies if the current device belongs to an
autochanger ressource.
}
\item [Changer Device = {\textless}device-name{\textgreater}]
\index[sd]{Changer Device}
In addition to the Archive Device name, you must specify a {\bf Changer
Device} name. This is because most autochangers are controlled through a
different device than is used for reading and writing the cartridges. For
example, on Linux, one normally uses the generic SCSI interface for
controlling the autochanger, but the standard SCSI interface for reading and
writing the tapes. On Linux, for the {\bf Archive Device = /dev/nst0}, you
would typically have {\bf Changer Device = /dev/sg0}. Note, some of the more
advanced autochangers will locate the changer device on {\bf /dev/sg1}. Such
devices typically have several drives and a large number of tapes.
On FreeBSD systems, the changer device will typically be on {\bf /dev/pass0}
through {\bf /dev/passN}.
On Solaris, the changer device will typically be some file under {\bf
/dev/rdsk}.
Please ensure that your Storage daemon has permission to access this
device.
\item [Changer Command = {\textless}command{\textgreater}]
\index[sd]{Changer Command}
This record is used to specify the external program to call and what
arguments to pass to it. The command is assumed to be a standard program or
shell script that can be executed by the operating system. This command is
invoked each time that Bareos wishes to manipulate the autochanger. The
following substitutions are made in the {\bf command} before it is sent to
the operating system for execution:
\footnotesize
\begin{verbatim}
%% = %
%a = archive device name
%c = changer device name
%d = changer drive index base 0
%f = Client's name
%j = Job name
%o = command (loaded, load, or unload)
%s = Slot base 0
%S = Slot base 1
%v = Volume name
\end{verbatim}
\normalsize
An actual example for using {\bf mtx} with the {\bf mtx-changer} script (part
of the Bareos distribution) is:
\footnotesize
\begin{verbatim}
Changer Command = "/usr/lib/bareos/scripts/mtx-changer %c %o %S %a %d"
\end{verbatim}
\normalsize
Details of the three
commands currently used by Bareos (loaded, load, unload) as well as the
output expected by Bareos are given in the \ilink{Bareos Autochanger Interface}{autochanger-interface} section.
\item [Maximum Changer Wait = {\textless}time{\textgreater}]
\index[sd]{Maximum Changer Wait}
This record is used to define the maximum amount of time that Bareos
will wait for an autoloader to respond to a command (e.g. load). The
default is set to 120 seconds. If you have a slow autoloader you may
want to set it longer.
If the autoloader program fails to respond in this time, it will be killed
and Bareos will request operator intervention.
\item [Drive Index = {\textless}number{\textgreater}]
\index[sd]{Drive Index}
This record allows you to tell Bareos to use the second or subsequent
drive in an autochanger with multiple drives. Since the drives are
numbered from zero, the second drive is defined by
\footnotesize
\begin{verbatim}
Device Index = 1
\end{verbatim}
\normalsize
To use the second drive, you need a second Device resource definition in the
Bareos configuration file. See the Multiple Drive section above in this
chapter for more information.
\end{description}
In addition, for proper functioning of the Autochanger, you must
define an Autochanger resource.
\label{example}
\section{An Example Configuration File}
\index[general]{Example Configuration File}
\index[general]{File!Example Configuration}
The following two resources implement an autochanger:
\footnotesize
\begin{verbatim}
Autochanger {
Name = Autochanger
Device = DDS-4
Changer Command = "/usr/lib/bareos/scripts/mtx-changer %c %o %S %a %d"
Changer Device = /dev/sg0
}
Device {
Name = DDS-4
Media Type = DDS-4
Archive Device = /dev/nst0 # Normal archive device
Autochanger = yes
LabelMedia = no;
AutomaticMount = yes;
AlwaysOpen = yes;
}
\end{verbatim}
\normalsize
where you will adapt the {\bf Archive Device}, the {\bf Changer Device}, and
the path to the {\bf Changer Command} to correspond to the values used on your
system.
\section{A Multi-drive Example Configuration File}
\index[general]{Multi-drive Example Configuration File}
The following resources implement a multi-drive autochanger:
\footnotesize
\begin{verbatim}
Autochanger {
Name = Autochanger
Device = Drive-0
Device = Drive-1
Changer Command = "/usr/lib/bareos/scripts/mtx-changer %c %o %S %a %d"
Changer Device = /dev/sg0
}
Device {
Name = Drive-0
Drive Index = 0
Media Type = DDS-4
Archive Device = /dev/nst0 # Normal archive device
Autochanger = yes
LabelMedia = no;
AutomaticMount = yes;
AlwaysOpen = yes;
}
Device {
Name = Drive-1
Drive Index = 1
Media Type = DDS-4
Archive Device = /dev/nst1 # Normal archive device
Autochanger = yes
LabelMedia = no;
AutomaticMount = yes;
AlwaysOpen = yes;
}
\end{verbatim}
\normalsize
where you will adapt the {\bf Archive Device} and the {\bf Changer Device} to correspond to the values used on your
system.
\section{Specifying Slots When Labeling}
\index[general]{Specifying Slots When Labeling}
\index[general]{Labeling!Specifying Slots When}
\label{SpecifyingSlots}
If you add an {\bf Autochanger = yes} record to the Storage resource in your
Director's configuration file, the Bareos Console will automatically prompt
you for the slot number when the Volume is in the changer when
you {\bf add} or {\bf label} tapes for that Storage device. If your
{\bf mtx-changer} script is properly installed, Bareos will automatically
load the correct tape during the label command.
You must also set
{\bf Autochanger = yes} in the Storage daemon's Device resource
as we have described above in order for the autochanger to be used.
%\TODO{check: why not in the example?}
Please see the
\ilink{Storage Resource}{Autochanger1} in the Director's chapter
and the
\ilink{Device Resource}{Autochanger} in the Storage daemon
chapter for more details on these records.
Thus all stages of dealing with tapes can be totally automated. It is also
possible to set or change the Slot using the {\bf update} command in the
Console and selecting {\bf Volume Parameters} to update.
Even though all the above configuration statements are specified and correct,
Bareos will attempt to access the autochanger only if a {\bf slot} is non-zero
in the catalog Volume record (with the Volume name).
If your autochanger has barcode labels, you can label all the Volumes in
your autochanger one after another by using the {\bf label barcodes} command.
For each tape in the changer containing a barcode, Bareos will mount the tape
and then label it with the same name as the barcode. An appropriate Media
record will also be created in the catalog. Any barcode that begins with the
same characters as specified on the "CleaningPrefix=xxx" command, will be
treated as a cleaning tape, and will not be labeled.
For example with:
\footnotesize
\begin{verbatim}
Pool {
Name ...
Cleaning Prefix = "CLN"
}
\end{verbatim}
\normalsize
Any slot containing a barcode of CLNxxxx will be treated as a cleaning tape
and will not be mounted.
\section{Changing Cartridges}
\index[general]{Changing Cartridges}
If you wish to insert or remove cartridges in your autochanger or
you manually run the {\bf mtx} program, you must first tell Bareos
to release the autochanger by doing:
\footnotesize
\begin{verbatim}
unmount
(change cartridges and/or run mtx)
mount
\end{verbatim}
\normalsize
If you do not do the unmount before making such a change, Bareos
will become completely confused about what is in the autochanger
and may stop function because it expects to have exclusive use
of the autochanger while it has the drive mounted.
\label{Magazines}
\section{Dealing with Multiple Magazines}
\index[general]{Magazines!Dealing with Multiple}
If you have several magazines or if you insert or remove cartridges from a
magazine, you should notify Bareos of this. By doing so, Bareos will as
a preference, use Volumes that it knows to be in the autochanger before
accessing Volumes that are not in the autochanger. This prevents unneeded
operator intervention.
If your autochanger has barcodes (machine readable tape labels), the task of
informing Bareos is simple. Every time, you change a magazine, or add or
remove a cartridge from the magazine, simply use following commands in the Console program:
\footnotesize
\begin{verbatim}
unmount
(remove magazine)
(insert new magazine)
update slots
mount
\end{verbatim}
\normalsize
This will cause Bareos to request the autochanger to
return the current Volume names in the magazine. This will be done without
actually accessing or reading the Volumes because the barcode reader does this
during inventory when the autochanger is first turned on. Bareos will ensure
that any Volumes that are currently marked as being in the magazine are marked
as no longer in the magazine, and the new list of Volumes will be marked as
being in the magazine. In addition, the Slot numbers of the Volumes will be
corrected in Bareos's catalog if they are incorrect (added or moved).
If you do not have a barcode reader on your autochanger, you have several
alternatives.
\begin{enumerate}
\item You can manually set the Slot and InChanger flag using the {\bf update
volume} command in the Console (quite painful).
\item You can issue a
\footnotesize
\begin{verbatim}
update slots scan
\end{verbatim}
\normalsize
command that will cause Bareos to read the label on each of the cartridges in
the magazine in turn and update the information (Slot, InChanger flag) in the
catalog. This is quite effective but does take time to load each cartridge
into the drive in turn and read the Volume label.
%\item You can modify the mtx-changer script so that it simulates an
% autochanger with barcodes. See below for more details.
\end{enumerate}
\hide{
% unwanted, commented out
\section{Simulating Barcodes in your Autochanger}
\index[general]{Autochanger!Simulating Barcodes in your}
\index[general]{Simulating Barcodes in your Autochanger}
\label{simulating}
You can simulate barcodes in your autochanger by making the {\bf mtx-changer}
script return the same information that an autochanger with barcodes would do.
This is done by commenting out the one and only line in the {\bf list)} case,
which is:
\footnotesize
\begin{verbatim}
${MTX} -f $ctl status | grep " *Storage Element [0-9]*:.*Full" | awk "{print \$3 \$4}" | sed "s/Full *\(:VolumeTag=\)*//"
\end{verbatim}
\normalsize
at approximately line 99 by putting a \# in column one of that line, or by
simply deleting it. Then in its place add a new line that prints the contents
of a file. For example:
\footnotesize
\begin{verbatim}
cat /etc/bareos/changer.volumes
\end{verbatim}
\normalsize
Be sure to include a full path to the file, which can have any name. The
contents of the file must be of the following format:
\footnotesize
\begin{verbatim}
1:Volume1
2:Volume2
3:Volume3
...
\end{verbatim}
\normalsize
Where the 1, 2, 3 are the slot numbers and Volume1, Volume2, ... are the
Volume names in those slots. You can have multiple files that represent the
Volumes in different magazines, and when you change magazines, simply copy the
contents of the correct file into your {\bf /etc/bareos/changer.volumes} file.
There is no need to stop and start Bareos when you change magazines, simply
put the correct data in the file, then run the {\bf update slots} command, and
your autochanger will appear to Bareos to be an autochanger with barcodes.
}
\section{Update Slots Command}
\index[general]{Console!Command!update slots}
\label{updateslots}
If you change only one cartridge in the magazine, you may not want to scan all
Volumes, so the {\bf update slots} command (as well as the {\bf update slots
scan} command) has the additional form:
\footnotesize
\begin{verbatim}
update slots=n1,n2,n3-n4, ...
\end{verbatim}
\normalsize
where the keyword {\bf scan} can be appended or not. The n1,n2, ... represent
Slot numbers to be updated and the form n3-n4 represents a range of Slot
numbers to be updated (e.g. 4-7 will update Slots 4,5,6, and 7).
This form is particularly useful if you want to do a scan (time expensive) and
restrict the update to one or two slots.
For example, the command:
\footnotesize
\begin{verbatim}
update slots=1,6 scan
\end{verbatim}
\normalsize
will cause Bareos to load the Volume in Slot 1, read its Volume label and
update the Catalog. It will do the same for the Volume in Slot 6. The command:
\footnotesize
\begin{verbatim}
update slots=1-3,6
\end{verbatim}
\normalsize
will read the barcoded Volume names for slots 1,2,3 and 6 and make the
appropriate updates in the Catalog. If you don't have a barcode reader the above command will
not find any Volume names so will do nothing.
\section{Using the Autochanger}
\index[general]{Autochanger!Using the}
\label{using}
Let's assume that you have properly defined the necessary Storage daemon
Device records, and you have added the {\bf Autochanger = yes} record to the
Storage resource in your Director's configuration file.
Now you fill your autochanger with say six blank tapes.
What do you do to make Bareos access those tapes?
One strategy is to prelabel each of the tapes. Do so by starting Bareos, then
with the Console program, enter the {\bf label} command:
\footnotesize
\begin{verbatim}
./bconsole
Connecting to Director rufus:8101
1000 OK: rufus-dir Version: 1.26 (4 October 2002)
*label
\end{verbatim}
\normalsize
it will then print something like:
\footnotesize
\begin{verbatim}
Using default Catalog name=BackupDB DB=bareos
The defined Storage resources are:
1: Autochanger
2: File
Select Storage resource (1-2): 1
\end{verbatim}
\normalsize
I select the autochanger (1), and it prints:
\footnotesize
\begin{verbatim}
Enter new Volume name: TestVolume1
Enter slot (0 for none): 1
\end{verbatim}
\normalsize
where I entered {\bf TestVolume1} for the tape name, and slot {\bf 1} for the
slot. It then asks:
\footnotesize
\begin{verbatim}
Defined Pools:
1: Default
2: File
Select the Pool (1-2): 1
\end{verbatim}
\normalsize
I select the Default pool. This will be automatically done if you only have a
single pool, then Bareos will proceed to unload any loaded volume, load the
volume in slot 1 and label it. In this example, nothing was in the drive, so
it printed:
\footnotesize
\begin{verbatim}
Connecting to Storage daemon Autochanger at localhost:9103 ...
Sending label command ...
3903 Issuing autochanger "load slot 1" command.
3000 OK label. Volume=TestVolume1 Device=/dev/nst0
Media record for Volume=TestVolume1 successfully created.
Requesting mount Autochanger ...
3001 Device /dev/nst0 is mounted with Volume TestVolume1
You have messages.
*
\end{verbatim}
\normalsize
You may then proceed to label the other volumes. The messages will change
slightly because Bareos will unload the volume (just labeled TestVolume1)
before loading the next volume to be labeled.
Once all your Volumes are labeled, Bareos will automatically load them as they
are needed.
To "see" how you have labeled your Volumes, simply enter the {\bf list
volumes} command from the Console program, which should print something like
the following:
\footnotesize
\begin{verbatim}
*{\bf list volumes}
Using default Catalog name=BackupDB DB=bareos
Defined Pools:
1: Default
2: File
Select the Pool (1-2): 1
+-------+----------+--------+---------+-------+--------+----------+-------+------+
| MedId | VolName | MedTyp | VolStat | Bites | LstWrt | VolReten | Recyc | Slot |
+-------+----------+--------+---------+-------+--------+----------+-------+------+
| 1 | TestVol1 | DDS-4 | Append | 0 | 0 | 30672000 | 0 | 1 |
| 2 | TestVol2 | DDS-4 | Append | 0 | 0 | 30672000 | 0 | 2 |
| 3 | TestVol3 | DDS-4 | Append | 0 | 0 | 30672000 | 0 | 3 |
| ... |
+-------+----------+--------+---------+-------+--------+----------+-------+------+
\end{verbatim}
\normalsize
\section{Barcode Support}
\index[general]{Support!Barcode}
\index[general]{Barcode Support}
\label{Barcodes}
Bareos provides barcode support with two Console commands, {\bf label
barcodes} and {\bf update slots}.
The {\bf label barcodes} will cause Bareos to read the barcodes of all the
cassettes that are currently installed in the magazine (cassette holder) using
the {\bf mtx-changer} {\bf list} command. Each cassette is mounted in turn and
labeled with the same Volume name as the barcode.
The {\bf update slots} command will first obtain the list of cassettes and
their barcodes from {\bf mtx-changer}. Then it will find each volume in turn
in the catalog database corresponding to the barcodes and set its Slot to
correspond to the value just read. If the Volume is not in the catalog, then
nothing will be done. This command is useful for synchronizing Bareos with the
current magazine in case you have changed magazines or in case you have moved
cassettes from one slot to another. If the autochanger is empty, nothing will
be done.
The {\bf Cleaning Prefix} statement can be used in the Pool resource to define
a Volume name prefix, which if it matches that of the Volume (barcode) will
cause that Volume to be marked with a VolStatus of {\bf Cleaning}. This will
prevent Bareos from attempting to write on the Volume.
\section{Use bconsole to display Autochanger content}
The {\bf status slots storage=xxx} command displays autochanger content.
\footnotesize
\begin{verbatim}
Slot | Volume Name | Status | Type | Pool | Loaded |
------+-----------------+----------+-------------------+----------------+---------|
1 | 00001 | Append | DiskChangerMedia | Default | 0 |
2 | 00002 | Append | DiskChangerMedia | Default | 0 |
3*| 00003 | Append | DiskChangerMedia | Scratch | 0 |
4 | | | | | 0 |
\end{verbatim}
\normalsize
If you see a {\bf *} near the slot number, you have to run {\bf update slots}
command to synchronize autochanger content with your catalog.
\section{Bareos Autochanger Interface}
\index[general]{Interface!Autochanger}
\index[general]{Autochanger Interface}
\label{autochanger-interface}
Bareos calls the autochanger script that you specify on the {\bf Changer
Command} statement. Normally this script will be the {\bf mtx-changer} script
that we provide, but it can in fact be any program. The only requirement
for the script is that it must understand the commands that
Bareos uses, which are {\bf loaded}, {\bf load}, {\bf
unload}, {\bf list}, and {\bf slots}. In addition,
each of those commands must return the information in the precise format as
specified below:
\footnotesize
\begin{verbatim}
- Currently the changer commands used are:
loaded -- returns number of the slot that is loaded, base 1,
in the drive or 0 if the drive is empty.
load -- loads a specified slot (note, some autochangers
require a 30 second pause after this command) into
the drive.
unload -- unloads the device (returns cassette to its slot).
list -- returns one line for each cassette in the autochanger
in the format <slot>:<barcode>. Where
the {\bf slot} is the non-zero integer representing
the slot number, and {\bf barcode} is the barcode
associated with the cassette if it exists and if you
autoloader supports barcodes. Otherwise the barcode
field is blank.
slots -- returns total number of slots in the autochanger.
\end{verbatim}
\normalsize
Bareos checks the exit status of the program called, and if it is zero, the
data is accepted. If the exit status is non-zero, Bareos will print an
error message and request the tape be manually mounted on the drive.
\section{Tapespeed and blocksizes}
\index[general]{speedtuning!tapedrives}
\index[general]{tuning!tape}
\index[general]{blocksize!tapedrives}
\index[general]{tape speed}
\index[general]{block sizes}
\label{Tapespeed and blocksizes}
\label{setblocksizes}
The tape speed tuning whitepaper (\elink{http://www.bareos.org/en/Whitepapers/articles/Speed\_Tuning\_of\_Tape\_Drives.html}{http://www.bareos.org/en/Whitepapers/articles/Speed\_Tuning\_of\_Tape\_Drives.html})
shows that the two parameters
\configdirective{maximum file size} and \configdirective{maximum block size} of the device
have siginificant influence on the tape speed.
While it is no problem to change the \configdirective{maximum file size} parameter,
unfortunately it is not possible to change the \configdirective{maximum block size}
parameter, because the previously written tapes would become unreadable
in the new setup. It would require that the \configdirective{maximum block size} parameter
is switched back to the old value to be able to read the old volumes, but
of course then the new volumes would be unreadable.
Why is that the case?
The problem is that Bareos writes the label block (header) in the same block
size that is configured in the \configdirective{maximum block size} parameter in the device.
Per default, this value is 63k, so usually a tape written by Bareos looks like this:
\begin{verbatim}
|------------------
|label block (63k)|
|------------------
|data block 1(63k)|
|data block 2(63k)|
|... |
|data block n(63k)|
-------------------
\end{verbatim}
Setting the maximum block size to e.g. 512k, would lead to the following:
\begin{verbatim}
|------------------
|label block (512k)|
|------------------
|data block 1(512k)|
|data block 2(512k)|
|... |
|data block n(512k)|
--------------------
\end{verbatim}
As you can see, every block is written with the maximum block size, also the label block.
The problem that arises here is that reading a block header with a wrong block size causes
a read error which is interpreted as an non-existent label by Bareos.
This is a potential source of data loss, because in normal operation, Bareos refuses to
relabel an already labeled volume to be sure to not overwrite data that is still needed.
If Bareos cannot read the volume label, this security mechanism does not work and you might
label tapes already labeled accidentially.
To solve this problem, the block size handling was changed in Bareos \sinceVersion{sd}{Maximum Block Size}{14.2} in the following way:
\begin{itemize}
\item The tape label block is always written in the standard 63k (64512) Blocksize.
\item The following blocks are then written in the block size configured in the {\bf maximum block size} directive.
\item To be able to change the block size in an existing environment, it is now
possible to set the \configdirective{maximum block size} and \configdirective{minimum block size} in the
pool ressource. This setting is automatically promoted to each medium in
that pool as usual (i.e. when a medium is labeled for that pool or if a volume is transferred to that pool from the scratch pool).
When a volume is mounted, the volume's block size is
used to write and read the data blocks that follow the header block.
\end{itemize}
The following picture shows the result:
\begin{verbatim}
|--------------------------------|
|label block (label block size) |
|--------------------------------|
|data block 1(maximum block size)|
|data block 2(maximum block size)|
|... |
|data block n(maximum block size)|
---------------------------------|
\end{verbatim}
We have a label block with a certain size (63k per default to be compatible to old installations),
and the following data blocks are written with another blocksize.
This approach has the following advantages:
\begin{itemize}
\item If nothing is configured, existing installations keep on working without problems.
\item If you want to switch an existing installation that uses the default
blocksize and move to a new (usually bigger) block size, you can do that
easily by creating a new pool, where \configdirective{maximum block size} is set to the new
value that you wish to use in the future:
\end{itemize}
\begin{bconfig}{Pool Ressource: setting Maximum Block Size}
Pool {
Name = LTO-4-1M
Pool Type = Backup
Recycle = yes # Bareos can automatically recycle Volumes
AutoPrune = yes # Prune expired volumes
Volume Retention = 1 Month # How long should the Full Backups be kept? (#06)
Maximum Block Size = 1048576
Recycle Pool = Scratch
}
\end{bconfig}
Now configure your backups that they will write into the newly defined pool in the
future, and your backups will be written with the new blocksize.
Your existing tapes can be automatically transferred to the new pool when they expire
via the \ilink{Scratch Pool}{TheScratchPool} mechanism. When a tape in your old pool expires, it is
transferred to the scratch pool if you set
{\bf Recycle Pool = Scratch}. When your new pool needs a new volume, it will get it
from the scratch pool and apply the new pool's properties to that tape which also
include \configdirective{maximum block size} and \configdirective{minimum block size}.
This way you can smoothly switch your tapes to a new block size while you can still
restore the data on your old tapes at any time.
\subsection*{Possible Problems}
There is only one case where the new block handling will cause problems, and this
is if you have used bigger block sizes already in your setup. As we now defined the
label block to always be 63k, all labels will not be readable.
To also solve this problem, the directive \configdirective{label block size} can be used to define
a different label block size. That way, everything should work smoothly as all label
blocks will be readable again.
\subsection*{How can I find out which blocksize was used when the tape was written?}
At least on Linux, you can see if Bareos tries to read the blocks with the
wrong block size. In that case, you get a kernel message like the following in
your system's messages:
\begin{verbatim}
[542132.410170] st1: Failed to read 1048576 byte block with 64512 byte transfer.
\end{verbatim}
Here, the block was written with 1M block size but we only read 64k.
\subsection*{Direct access to Volumes with with non-default blocksizes}
\label{direct-access-to-volumes-with-non-default-blocksizes}
\index[general]{bls!block size}
\index[general]{bextract!block size}
\index[general]{Command!bls!block size}