Debian Codegraph @

manuals/en/main/autochangers.tex

raw
1 \chapter{Autochanger Support}
2 \label{blb:AutochangersChapter}
3 \index[general]{Support!Autochanger}
4 \index[general]{Autochanger Support}
5
6 \bacula{} provides autochanger support for reading and writing tapes. In
7 order to work with an autochanger, \bacula{} requires a number of things, each of
8 which is explained in more detail after this list:
9
10 \begin{bitemize}
11 \item A script that actually controls the autochanger according to commands
12 sent by \bacula{}. We furnish such a script that works with \mtx{} found in
13 the \textbf{depkgs} distribution.
14
15 \item That each Volume (tape) to be used must be defined in the Catalog and
16 have a Slot number assigned to it so that \bacula{} knows where the Volume is
17 in the autochanger. This is generally done with the \bcommandname{label} command, but
18 can also done after the tape is labeled using the \bcommandname{update slots}
19 command. See below for more details. You must pre-label the tapes manually
20 before using them.
21
22 \item Modifications to your Storage daemon's Device configuration resource to
23 identify that the device is a changer, as well as a few other parameters.
24
25 \item You should also modify your Storage resource definition in the
26 Director's configuration file so that you are automatically prompted for the
27 Slot when labeling a Volume.
28
29 \item You need to ensure that your Storage daemon (if not running as root)
30 has access permissions to both the tape drive and the control device.
31
32 \item You need to have \textbf{Autochanger = yes} in your Storage resource
33 in your \bfilename{bacula-dir.conf} file so that you will be prompted for the
34 slot number when you label Volumes.
35 \end{bitemize}
36
37 In version 1.37 and later, there is a new \bilink{Autochanger resource}{blb:AutochangerRes}
38 that permits you to group Device resources thus
39 creating a multi-drive autochanger. If you have an autochanger,
40 you \textbf{must} use this new resource.
41
42 \bacula{} uses its own \mtxchanger{} script to interface with a program
43 that actually does the tape changing. Thus in principle, \mtxchanger{}
44 can be adapted to function with any autochanger program, or you can
45 call any other script or program. The current
46 version of \mtxchanger{} works with the \mtx{} program. However,
47 FreeBSD users have provided a script in the \textbf{\bdirectoryname{examples/autochangers}}
48 directory that allows \bacula{} to use the \btool{chio} program.
49
50 \bacula{} also supports autochangers with barcode
51 readers. This support includes two Console commands: \bcommandname{label barcodes}
52 and \bcommandname{update slots}. For more details on these commands, see the ``Barcode
53 Support'' section below.
54
55 Current \bacula{} autochanger support does not include cleaning, stackers, or
56 silos. Stackers and silos are not supported because \bacula{} expects to
57 be able to access the slots randomly.
58 However, if you are very careful to setup \bacula{} to access the Volumes
59 in the autochanger sequentially, you may be able to make \bacula{}
60 work with stackers (gravity feed and such).
61
62 Support for multi-drive
63 autochangers requires the \bilink{Autochanger resource}{blb:AutochangerRes}
64 introduced in version 1.37. This resource is also recommended for single
65 drive autochangers.
66
67 In principle, if \mtx{} will operate your changer correctly, then it is
68 just a question of adapting the \mtxchanger{} script (or selecting one
69 already adapted) for proper interfacing.
70 %You can find a list of autochangers
71 %supported by \mtx{} at the following link:
72 %\bref{http://mtx.opensource-sw.net/compatibility.php}{mtx.opensource-sw.net/compatibility.php}.
73 %The home page for the \mtx{} project can be found at:
74 %\bref{http://mtx.opensource-sw.net/}{mtx.opensource-sw.net/}.
75
76 Note, we have feedback from some users that there are certain
77 incompatibilities between the Linux kernel and \mtx{}. For example between
78 kernel 2.6.18-8.1.8.el5 of CentOS and RedHat and version 1.3.10 and 1.3.11
79 of \mtx{}. This was fixed by upgrading to a version 2.6.22 kernel.
80
81 In addition, apparently certain versions of \mtx{}, for example, version
82 1.3.11 limit the number of slots to a maximum of 64. The solution was to
83 use version 1.3.10.
84
85 If you are having troubles, please use the \bcommandname{auto} command in the \btool{btape}
86 program to test the functioning of your autochanger with \bacula{}. When
87 \bacula{} is running, please remember that for many distributions (e.g. FreeBSD,
88 Debian, \ldots{}) the Storage daemon runs as \textbf{bacula.tape} rather than \textbf{root.root},
89 so you will need to ensure that the Storage daemon has sufficient
90 permissions to access the autochanger.
91
92 Some users have reported that the the Storage daemon blocks under certain
93 circumstances in trying to mount a volume on a drive that has a different
94 volume loaded. As best we can determine, this is simply a matter of
95 waiting a bit. The drive was previously in use writing a Volume, and
96 sometimes the drive will remain \texttt{BLOCKED} for a good deal of time (up to 7
97 minutes on a slow drive) waiting for the cassette to rewind and to unload
98 before the drive can be used with a different Volume.
99
100 \label{blb:SCSI devices}
101 \section{Knowing What \acs{SCSI} Devices You Have}
102 \index[general]{Have!Knowing What \acs{SCSI} Devices You}
103 \index[general]{Knowing What \acs{SCSI} Devices You Have}
104 \index[general]{SCSI devices}
105 \index[general]{devices!SCSI}
106
107 Under Linux, you can
108
109 \begin{bVerbatim}
110 cat /proc/scsi/scsi
111 \end{bVerbatim}
112
113 to see what \acs{SCSI} devices you have available. You can also:
114
115 \begin{bVerbatim}
116 cat /proc/scsi/sg/device_hdr /proc/scsi/sg/devices
117 \end{bVerbatim}
118
119 to find out how to specify their control address (\bfilename{/dev/sg0} for the
120 first, \bfilename{/dev/sg1} for the second, \ldots{}) on the \textbf{\bdirectivename{Changer Device =}}
121 \bacula{} directive.
122
123 You can also use the excellent \btool{lsscsi} tool.
124 \begin{bVerbatim}
125 $ lsscsi -g
126 [1:0:2:0] tape SEAGATE ULTRIUM06242-XXX 1619 /dev/st0 /dev/sg9
127 [1:0:14:0] mediumx STK L180 0315 /dev/sch0 /dev/sg10
128 [2:0:3:0] tape HP Ultrium 3-SCSI G24S /dev/st1 /dev/sg11
129 [3:0:0:0] enclosu HP A6255A HP04 - /dev/sg3
130 [3:0:1:0] disk HP 36.4G ST336753FC HP00 /dev/sdd /dev/sg4
131 \end{bVerbatim}
132
133 For more detailed information on what \acs{SCSI} devices you have please see
134 the \bxlink{Linux \acs{SCSI} Tricks}{blb:SCSITricks}{problems}{section} of the
135 \bxlink{Tape Testing}{blb:TapeTestingChapter}{problems}{chapter} of the
136 \bproblemman{}.
137
138 Under FreeBSD, you can use:
139
140 \begin{bVerbatim}
141 camcontrol devlist
142 \end{bVerbatim}
143
144 To list the \acs{SCSI} devices as well as the \bfilename{/dev/passn} that you will use on
145 the \bacula{} \bdirectivename{Changer Device =} directive.
146
147 Please check that your Storage daemon has permission to access this
148 device.
149
150 The following tip for FreeBSD users comes from Danny Butroyd:
151 on reboot \bacula{} will NOT have permission to
152 control the device \bfilename{/dev/pass0} (assuming this is your changer device).
153 To get around this just edit the \bfilename{/etc/devfs.conf} file and add the
154 following to the bottom:
155
156 \begin{bVerbatim}
157 own pass0 root:bacula
158 perm pass0 0666
159 own nsa0.0 root:bacula
160 perm nsa0.0 0666
161 \end{bVerbatim}
162
163 This gives the bacula group permission to write to the \bfilename{nsa0.0} device
164 too just to be on the safe side. To bring these changes into effect
165 just run:
166
167 \begin{bVerbatim}
168 /etc/rc.d/devfs restart
169 \end{bVerbatim}
170
171 Basically this will stop you having to manually change permissions on these
172 devices to make \bacula{} work when operating the AutoChanger after a reboot.
173
174 \label{blb:scripts}
175 \section{Example Scripts}
176 \index[general]{Scripts!Example}
177 \index[general]{Example Scripts}
178
179 Please read the sections below so that you understand how autochangers work
180 with \bacula{}. Although we supply a default \mtxchanger{} script, your
181 autochanger may require some additional changes. If you want to see examples
182 of configuration files and scripts, please look in the \bdirectoryname{\bbracket{bacula-src}/examples/devices}
183 directory where you will find an example \bfilename{HP-autoloader.conf}
184 \bacula{} Device resource, and several \mtxchanger{} scripts that have been modified to work with different
185 autochangers.
186
187 \label{blb:Slots}
188
189 \section{Slots}
190 \index[general]{Slots}
191
192 To properly address autochangers, \bacula{} must know which Volume is in each
193 \textbf{slot} of the autochanger. Slots are where the changer cartridges reside
194 when not loaded into the drive. \bacula{} numbers these slots from one to the
195 number of cartridges contained in the autochanger.
196
197 \bacula{} will not automatically use a Volume in your autochanger unless it is
198 labeled and the slot number is stored in the catalog and the Volume is marked
199 as InChanger. This is because it must know where each volume is (slot) to
200 be able to load the volume.
201
202 For each Volume in your
203 changer, you will, using the Console program, assign a slot. This information
204 is kept in \textbf{\bacula{}'s} catalog database along with the other data for the
205 volume. If no slot is given, or the slot is set to zero, \bacula{} will not
206 attempt to use the autochanger even if all the necessary configuration records
207 are present. When doing a \bcommandname{mount} command on an autochanger, you must
208 specify which slot you want mounted. If the drive is loaded with a tape
209 from another slot, it will unload it and load the correct tape, but
210 normally, no tape will be loaded because an \bcommandname{unmount} command causes
211 \bacula{} to unload the tape in the drive.
212
213
214 You can check if the Slot number and InChanger flag are set by doing a:
215 \begin{bVerbatim}
216 list Volumes
217 \end{bVerbatim}
218
219 in the Console program.
220
221 \label{blb:mult}
222 \section{Multiple Devices}
223 \index[general]{Devices!Multiple}
224 \index[general]{Multiple Devices}
225
226 Some autochangers have more than one read/write device (drive). The
227 new \bilink{Autochanger resource}{blb:AutochangerRes} introduced in version
228 1.37 permits you to group Device resources, where each device
229 represents a drive. The Director may still reference the Devices (drives)
230 directly, but doing so, bypasses the proper functioning of the
231 drives together. Instead, the Director (in the Storage resource)
232 should reference the Autochanger resource name. Doing so permits
233 the Storage daemon to ensure that only one drive uses the \mtxchanger{}
234 script at a time, and also that two drives don't reference the
235 same Volume.
236
237 Multi-drive requires the use of the \textbf{\bdirectivename{Drive Index}} directive in
238 the \bresourcename{Device} resource of the Storage daemon's
239 configuration file. Drive numbers or the Device Index are numbered beginning
240 at zero (\bdefaultvalue{0}), which is the default. To use the second Drive in an autochanger, you
241 need to define a second \bresourcename{Device} resource and set the \bdirectivename{Drive Index} to 1 for
242 that device. In general, the second device will have the same \textbf{\bdirectivename{Changer Device}}
243 (control channel) as the first drive, but a different \textbf{\bdirectivename{Archive Device}}.
244
245 As a default, \bacula{} jobs will prefer to write to a Volume that is
246 already mounted. If you have a multiple drive autochanger and you want
247 \bacula{} to write to more than one Volume in the same Pool at the same
248 time, you will need to set \bilink{Prefer Mounted Volumes}{blb:PreferMountedVolumes}
249 in the Directors Job resource to \textbf{no}. This will cause
250 the Storage daemon to maximize the use of drives.
251
252
253 \label{blb:ConfigRecords}
254 \section{Device Configuration Records}
255 \index[general]{Records!Device Configuration}
256 \index[general]{Device Configuration Records}
257
258 Configuration of autochangers within \bacula{} is done in the Device resource of
259 the Storage daemon. Four records: \textbf{\bdirectivename{Autochanger}}, \textbf{\bdirectivename{Changer Device}},
260 \textbf{\bdirectivename{Changer Command}}, and \textbf{\bdirectivename{Maximum Changer Wait}} control how \bacula{} uses
261 the autochanger.
262
263 These four records, permitted in \textbf{\bresourcename{Device}} resources, are described in
264 detail below. Note, however, that the \textbf{\bdirectivename{Changer Device}} and the
265 \textbf{\bdirectivename{Changer Command}} directives are not needed in the \bresourcename{Device} resource
266 if they are present in the \textbf{\bresourcename{Autochanger}} resource.
267
268 \begin{bdescription}
269
270 \item [Autochanger = \byesorno{} ]
271 \index[sd]{Autochanger}
272 The \textbf{Autochanger} record specifies that the current device is or is not
273 an autochanger. The default is \bdefaultvalue{no}.
274
275 \item [Changer Device = \bbracket{device-name}]
276 \index[sd]{Changer Device}
277 In addition to the Archive Device name, you must specify a \textbf{\bdirectivename{Changer Device}} name.
278 This is because most autochangers are controlled through a
279 different device than is used for reading and writing the cartridges. For
280 example, on Linux, one normally uses the generic \acs{SCSI} interface for
281 controlling the autochanger, but the standard \acs{SCSI} interface for reading and
282 writing the tapes. On Linux, for the \textbf{Archive Device = \bfilename{/dev/nst0}}, you
283 would typically have \textbf{Changer Device = \bfilename{/dev/sg0}}. Note, some of the more
284 advanced autochangers will locate the changer device on \bfilename{/dev/sg1}. Such
285 devices typically have several drives and a large number of tapes.
286
287 On FreeBSD systems, the changer device will typically be on \bfilename{/dev/pass0}
288 through \bfilename{/dev/passn}.
289
290 On Solaris, the changer device will typically be some file under \textbf{\bfilename{/dev/rdsk}}.
291
292 Please ensure that your Storage daemon has permission to access this device.
293
294 \item [Changer Command = \bbracket{command}]
295 \index[sd]{Changer Command}
296 This record is used to specify the external program to call and what
297 arguments to pass to it. The command is assumed to be a standard program or
298 shell script that can be executed by the operating system. This command is
299 invoked each time that \bacula{} wishes to manipulate the autochanger. The
300 following substitutions are made in the \textbf{command} before it is sent to
301 the operating system for execution:
302
303
304 \begin{bVerbatim}
305 %% = %
306 %a = archive device name
307 %c = changer device name
308 %d = changer drive index base 0
309 %f = Client's name
310 %j = Job name
311 %o = command (loaded, load, or unload)
312 %s = Slot base 0
313 %S = Slot base 1
314 %v = Volume name
315 \end{bVerbatim}
316
317 An actual example for using \mtx{} with the \mtxchanger{} script (part
318 of the \bacula{} distribution) is:
319
320 \begin{bVerbatim}
321 Changer Command = "/opt/bacula/scripts/mtx-changer %c %o %S %a %d"
322 \end{bVerbatim}
323
324 Where you will need to adapt the \bdirectoryname{/opt/bacula} to be the actual path on
325 your system where the \mtxchanger{} script resides. Details of the three
326 commands currently used by \bacula{} (\bcommandname{loaded}, \bcommandname{load}, \bcommandname{unload}) as well as the
327 output expected by \bacula{} are give in the \textbf{\bacula{} Autochanger Interface}
328 section below.
329
330 \item [Maximum Changer Wait = \bbracket{time}]
331 \index[sd]{Maximum Changer Wait}
332 This record is used to define the maximum amount of time that \bacula{}
333 will wait for an autoloader to respond to a command (e.g. \bcommandname{load}). The
334 default is set to \bdefaultvalue{120} seconds. If you have a slow autoloader you may
335 want to set it longer.
336
337 If the autoloader program fails to respond in this time, it will be killed
338 and \bacula{} will request operator intervention.
339
340 \item [Drive Index = \bbracket{number}]
341 \index[sd]{Drive Index}
342 This record allows you to tell \bacula{} to use the second or subsequent
343 drive in an autochanger with multiple drives. Since the drives are
344 numbered from zero, the second drive is defined by
345
346 \begin{bVerbatim}
347 Drive Index = 1
348 \end{bVerbatim}
349
350 To use the second drive, you need a second Device resource definition in the
351 \bacula{} configuration file. See the \bilink{Multiple Drive}{blb:mult} section above in this
352 chapter for more information.
353 \end{bdescription}
354
355 In addition, for proper functioning of the Autochanger, you must
356 define an \bresourcename{Autochanger} resource.
357 \input{autochangerres}
358
359 \label{blb:example}
360 \section{An Example Configuration File}
361 \index[general]{Example Configuration File}
362 \index[general]{File!Example Configuration}
363
364 The following two resources implement an autochanger:
365
366 \begin{bVerbatim}
367 Autochanger {
368 Name = "Autochanger"
369 Device = DDS-4
370 Changer Device = /dev/sg0
371 Changer Command = "/opt/bacula/scripts/mtx-changer %c %o %S %a %d"
372 }
373
374 Device {
375 Name = DDS-4
376 Media Type = DDS-4
377 Archive Device = /dev/nst0 # Normal archive device
378 Autochanger = yes
379 LabelMedia = no
380 AutomaticMount = yes
381 AlwaysOpen = yes
382 }
383 \end{bVerbatim}
384
385 where you will adapt the \textbf{\bdirectivename{Archive Device}}, the \textbf{\bdirectivename{Changer Device}}, and
386 the path to the \textbf{\bdirectivename{Changer Command}} to correspond to the values used on your
387 system.
388
389 \section{A Multi-drive Example Configuration File}
390 \index[general]{Multi-drive Example Configuration File}
391
392 The following resources implement a multi-drive autochanger:
393
394 \begin{bVerbatim}
395 Autochanger {
396 Name = "Autochanger"
397 Device = Drive-1,Drive-2
398 Changer Device = /dev/sg0
399 Changer Command = "/opt/bacula/scripts/mtx-changer %c %o %S %a %d"
400 }
401
402 Device {
403 Name = Drive-1
404 Drive Index = 0
405 Media Type = DDS-4
406 Archive Device = /dev/nst0 # Normal archive device
407 Autochanger = yes
408 LabelMedia = no
409 AutomaticMount = yes
410 AlwaysOpen = yes
411 }
412
413 Device {
414 Name = Drive-2
415 Drive Index = 1
416 Media Type = DDS-4
417 Archive Device = /dev/nst1 # Normal archive device
418 Autochanger = yes
419 LabelMedia = no
420 AutomaticMount = yes
421 AlwaysOpen = yes
422 }
423 \end{bVerbatim}
424
425 where you will adapt the \textbf{\bdirectivename{Archive Device}}, the \textbf{\bdirectivename{Changer Device}}, and
426 the path to the \textbf{\bdirectivename{Changer Command}} to correspond to the values used on your
427 system.
428
429 \label{blb:SpecifyingSlots}
430 \section{Specifying Slots When Labeling}
431 \index[general]{Specifying Slots When Labeling}
432 \index[general]{Labeling!Specifying Slots When}
433
434 If you add an \textbf{\bdirectivename{Autochanger = yes}} record to the Storage resource in your
435 Director's configuration file, the \bacula{} Console will automatically prompt
436 you for the slot number when the Volume is in the changer when
437 you \bcommandname{add} or \bcommandname{label} tapes for that Storage device. If your
438 \mtxchanger{} script is properly installed, \bacula{} will automatically
439 load the correct tape during the \bcommandname{label} command.
440
441 You must also set
442 \textbf{\bdirectivename{Autochanger = yes}} in the Storage daemon's Device resource
443 as we have described above in
444 order for the autochanger to be used. Please see the
445 \bilink{Storage Resource}{blb:Autochanger1} in the Director's chapter
446 and the
447 \bilink{Device Resource}{blb:Autochanger} in the Storage daemon
448 chapter for more details on these records.
449
450 Thus all stages of dealing with tapes can be totally automated. It is also
451 possible to set or change the Slot using the \bcommandname{update} command in the
452 Console and selecting \textbf{Volume Parameters} to update.
453
454 Even though all the above configuration statements are specified and correct,
455 \bacula{} will attempt to access the autochanger only if a \textbf{slot} is non-zero
456 in the catalog Volume record (with the Volume name).
457
458 If your autochanger has barcode labels, you can label all the Volumes in
459 your autochanger one after another by using the \bcommandname{label barcodes} command.
460 For each tape in the changer containing a barcode, \bacula{} will mount the tape
461 and then label it with the same name as the barcode. An appropriate Media
462 record will also be created in the catalog. Any barcode that begins with the
463 same characters as specified on the ``\bdirectivename{CleaningPrefix=xxx} command, will be
464 treated as a cleaning tape, and will not be labeled.
465
466 For example with
467 \begin{bVerbatim}
468 Pool {
469 Name ...
470 Cleaning Prefix = "CLN"
471 }
472 \end{bVerbatim}
473 any slot containing a barcode of \texttt{CLNxxxx} will be treated as a cleaning tape
474 and will not be mounted.
475
476 Please note that Volumes must be pre-labeled to be automatically used in
477 the autochanger during a backup. If you do not have a barcode reader, this
478 is done manually (or via a script).
479
480 \section{Changing Cartridges}
481 \index[general]{Changing Cartridges}
482 If you wish to insert or remove cartridges in your autochanger or
483 you manually run the \mtx{} program, you must first tell \bacula{}
484 to release the autochanger by doing:
485
486 \begin{bVerbatim}
487 unmount
488 \end{bVerbatim}
489 Change cartridges and/or run \mtx{}
490 \begin{bVerbatim}
491 mount
492 \end{bVerbatim}
493
494 If you do not do the \bcommandname{unmount} before making such a change, \bacula{}
495 will become completely confused about what is in the autochanger
496 and may stop function because it expects to have exclusive use
497 of the autochanger while it has the drive mounted.
498
499
500 \label{blb:Magazines}
501 \section{Dealing with Multiple Magazines}
502 \index[general]{Dealing with Multiple Magazines}
503 \index[general]{Magazines!Dealing with Multiple}
504
505 If you have several magazines or if you insert or remove cartridges from a
506 magazine, you should notify \bacula{} of this. By doing so, \bacula{} will as
507 a preference, use Volumes that it knows to be in the autochanger before
508 accessing Volumes that are not in the autochanger. This prevents unneeded
509 operator intervention.
510
511 If your autochanger has barcodes (machine readable tape labels), the task of
512 informing \bacula{} is simple. Every time, you change a magazine, or add or
513 remove a cartridge from the magazine, simply do
514
515 \begin{bVerbatim}
516 unmount
517 \end{bVerbatim}
518 Remove magazine
519
520 Insert new magazine
521 \begin{bVerbatim}
522 update slots
523 mount
524 \end{bVerbatim}
525
526 in the Console program. This will cause \bacula{} to request the autochanger to
527 return the current Volume names in the magazine. This will be done without
528 actually accessing or reading the Volumes because the barcode reader does this
529 during inventory when the autochanger is first turned on. \bacula{} will ensure
530 that any Volumes that are currently marked as being in the magazine are marked
531 as no longer in the magazine, and the new list of Volumes will be marked as
532 being in the magazine. In addition, the Slot numbers of the Volumes will be
533 corrected in \bacula{}'s catalog if they are incorrect (added or moved).
534
535 If you do not have a barcode reader on your autochanger, you have several
536 alternatives.
537
538 \begin{benumerate}
539 \item You can manually set the Slot and InChanger flag using the
540 \bcommandname{update volume} command in the Console (quite painful).
541
542 \item You can issue a
543
544 \begin{bVerbatim}
545 update slots scan
546 \end{bVerbatim}
547
548 command that will cause \bacula{} to read the label on each of the cartridges in
549 the magazine in turn and update the information (Slot, InChanger flag) in the
550 catalog. This is quite effective but does take time to load each cartridge
551 into the drive in turn and read the Volume label.
552
553 \item You can modify the \mtxchanger{} script so that it simulates an
554 autochanger with barcodes. See below for more details.
555 \end{benumerate}
556
557 \label{blb:simulating}
558 \section{Simulating Barcodes in your Autochanger}
559 \index[general]{Autochanger!Simulating Barcodes in your}
560 \index[general]{Simulating Barcodes in your Autochanger}
561
562 You can simulate barcodes in your autochanger by making the \mtxchanger{}
563 script return the same information that an autochanger with barcodes would do.
564 This is done by commenting out the one and only line in the \textbf{list)} case,
565 which is:
566
567 \begin{bVerbatim}
568 ${MTX} -f $ctl status | grep " *Storage Element [0-9]*:.*Full" | awk "{print \$3 \$4}"
569 | sed "s/Full *\(:VolumeTag=\)*//"
570 \end{bVerbatim}
571
572 at approximately line 99 by putting a \# in column one of that line, or by
573 simply deleting it. Then in its place add a new line that prints the contents
574 of a file. For example:
575
576 \begin{bVerbatim}
577 cat /etc/bacula/changer.volumes
578 \end{bVerbatim}
579
580 Be sure to include a full path to the file, which can have any name. The
581 contents of the file must be of the following format:
582
583 \begin{bVerbatim}
584 1:Volume1
585 2:Volume2
586 3:Volume3
587 ...
588 \end{bVerbatim}
589
590 Where the 1, 2, 3 are the slot numbers and Volume1, Volume2, \ldots{} are the
591 Volume names in those slots. You can have multiple files that represent the
592 Volumes in different magazines, and when you change magazines, simply copy the
593 contents of the correct file into your \bfilename{/etc/bacula/changer.volumes} file.
594 There is no need to stop and start \bacula{} when you change magazines, simply
595 put the correct data in the file, then run the \bcommandname{update slots} command, and
596 your autochanger will appear to \bacula{} to be an autochanger with barcodes.
597 \label{blb:updateslots}
598
599 \section{The Full Form of the Update Slots Command}
600 \index[general]{Full Form of the Update Slots Command}
601 \index[general]{Command!Full Form of the Update Slots}
602
603 If you change only one cartridge in the magazine, you may not want to scan all
604 Volumes, so the \bcommandname{update slots} command (as well as the
605 \bcommandname{update slots scan} command) has the additional form:
606
607 \begin{bVerbatim}
608 update slots=n1,n2,n3-n4, ...
609 \end{bVerbatim}
610
611 where the keyword \textbf{scan} can be appended or not. The n1,n2, \ldots{} represent
612 Slot numbers to be updated and the form n3-n4 represents a range of Slot
613 numbers to be updated (e.g. 4-7 will update Slots 4,5,6, and 7).
614
615 This form is particularly useful if you want to do a scan (time expensive) and
616 restrict the update to one or two slots.
617
618 For example, the command:
619
620 \begin{bVerbatim}
621 update slots=1,6 scan
622 \end{bVerbatim}
623
624 will cause \bacula{} to load the Volume in Slot 1, read its Volume label and
625 update the Catalog. It will do the same for the Volume in Slot 6. The command:
626
627
628 \begin{bVerbatim}
629 update slots=1-3,6
630 \end{bVerbatim}
631
632 will read the barcoded Volume names for slots 1,2,3 and 6 and make the
633 appropriate updates in the Catalog. If you don't have a barcode reader or have
634 not modified the \mtxchanger{} script as described above, the above command will
635 not find any Volume names so will do nothing.
636 \label{blb:FreeBSD}
637
638 \section{FreeBSD Issues}
639 \index[general]{Issues!FreeBSD}
640 \index[general]{FreeBSD Issues}
641
642 If you are having problems on FreeBSD when \bacula{} tries to select a tape, and
643 the message is \textbf{Device not configured}, this is because FreeBSD has made
644 the tape device \bfilename{/dev/nsa1} disappear when there is no tape mounted in the
645 autochanger slot. As a consequence, \bacula{} is unable to open the device. The
646 solution to the problem is to make sure that some tape is loaded into the tape
647 drive before starting \bacula{}. This problem is corrected in \bacula{} versions
648 1.32f-5 and later.
649
650 Please see the
651 \bxlink{Tape Testing}{blb:FreeBSDTapes}{problems}{chapter} of the \bproblemman{} for
652 \textbf{important} information concerning your tape drive before doing the
653 autochanger testing.
654 \label{blb:AutochangerTesting}
655
656 \section{Testing Autochanger and Adapting mtx-changer script}
657 \index[general]{Testing the Autochanger}
658 \index[general]{Adapting Your mtx-changer script}
659
660
661 Before attempting to use the autochanger with \bacula{}, it is preferable to
662 ``hand-test'' that the changer works. To do so, we suggest you do the
663 following commands (assuming that the \mtxchanger{} script is installed in
664 \bfilename{/opt/bacula/scripts/mtx-changer}):
665
666 \begin{bdescription}
667
668 \item [Make sure \bacula{} is not running.]
669
670 \item [/opt/bacula/scripts/mtx-changer \ /dev/sg0 \ list \ 0 \ /dev/nst0 \ 0]
671 \index[sd]{mtx-changer list}
672
673 This command should print:
674
675 \begin{bVerbatim}
676 1:
677 2:
678 3:
679 ...
680 \end{bVerbatim}
681
682 or one number per line for each slot that is occupied in your changer, and
683 the number should be terminated by a colon (\textbf{:}). If your changer has
684 barcodes, the barcode will follow the colon. If an error message is printed,
685 you must resolve the problem (e.g. try a different \acs{SCSI} control device name
686 if \bfilename{/dev/sg0} is incorrect). For example, on FreeBSD systems, the
687 autochanger \acs{SCSI} control device is generally \bfilename{/dev/pass2}.
688
689 \item [/opt/bacula/scripts/mtx-changer \ /dev/sg0 \ listall \ 0 \ /dev/nst0 \ 0]
690 \index[sd]{mtx-changer listall}
691
692 This command should print:
693
694 \begin{bVerbatim}
695 Drive content: D:Drive num:F:Slot loaded:Volume Name
696 D:0:F:2:vol2 or D:Drive num:E
697 D:1:F:42:vol42
698 D:3:E
699
700 Slot content:
701 S:1:F:vol1 S:Slot num:F:Volume Name
702 S:2:E or S:Slot num:E
703 S:3:F:vol4
704
705 Import/Export tray slots:
706 I:10:F:vol10 I:Slot num:F:Volume Name
707 I:11:E or I:Slot num:E
708 I:12:F:vol40
709 \end{bVerbatim}
710
711 \item [/opt/bacula/scripts/mtx-changer \ /dev/sg0 \ transfer \ 1 \ 2]
712 \index[sd]{mtx-changer listall}
713
714 This command should transfer a volume from source (1) to destination (2)
715
716 \item [/opt/bacula/scripts/mtx-changer \ /dev/sg0 \ slots ]
717 \index[sd]{mtx-changer slots}
718
719 This command should return the number of slots in your autochanger.
720
721 \item [/opt/bacula/scripts/mtx-changer \ /dev/sg0 \ unload \ 1 \ /dev/nst0 \ 0 ]
722 \index[sd]{mtx-changer unload}
723
724 If a tape is loaded from slot 1, this should cause it to be unloaded.
725
726 \item [/opt/bacula/scripts/mtx-changer \ /dev/sg0 \ load \ 3 \ /dev/nst0 \ 0 ]
727 \index[sd]{mtx-changer load}
728
729 Assuming you have a tape in slot 3, it will be loaded into drive (0).
730
731
732 \item [/opt/bacula/scripts/mtx-changer \ /dev/sg0 \ loaded \ 0 \ /dev/nst0 \ 0]
733 \index[sd]{mtx-changer loaded}
734
735 It should print ``3''
736 Note, we have used an ``illegal'' slot number 0. In this case, it is simply
737 ignored because the slot number is not used. However, it must be specified
738 because the drive parameter at the end of the command is needed to select
739 the correct drive.
740
741 \item [/opt/bacula/scripts/mtx-changer \ /dev/sg0 \ unload \ 3 /dev/nst0 \ 0]
742
743 will unload the tape into slot 3.
744
745 \end{bdescription}
746
747 Once all the above commands work correctly, assuming that you have the right
748 \textbf{\bdirectivename{Changer Command}} in your configuration, \bacula{} should be able to operate
749 the changer. The only remaining area of problems will be if your autoloader
750 needs some time to get the tape loaded after issuing the command. After the
751 \mtxchanger{} script returns, \bacula{} will immediately rewind and read the
752 tape. If \bacula{} gets rewind I/O errors after a tape change, you will probably
753 need to insert a \textbf{sleep 20} after the \mtx{} command, but be careful to
754 exit the script with a zero status by adding \textbf{exit 0} after any additional
755 commands you add to the script. This is because \bacula{} checks the return
756 status of the script, which should be zero if all went well.
757
758 You can test whether or not you need a \textbf{sleep} by putting the following
759 commands into a file and running it as a script:
760
761 \begin{bVerbatim}
762 #!/bin/sh
763 /opt/bacula/scripts/mtx-changer /dev/sg0 unload 1 /dev/nst0 0
764 /opt/bacula/scripts/mtx-changer /dev/sg0 load 3 /dev/nst0 0
765 mt -f /dev/st0 rewind
766 mt -f /dev/st0 weof
767 \end{bVerbatim}
768
769 If the above script runs, you probably have no timing problems. If it does not
770 run, start by putting a \textbf{sleep 30} or possibly a \textbf{sleep 60} in the
771 script just after the \mtxchanger{} load command. If that works, then you should
772 move the sleep into the actual \mtxchanger{} script so that it will be
773 effective when \bacula{} runs.
774
775 A second problem that comes up with a small number of autochangers is that
776 they need to have the cartridge ejected before it can be removed. If this is
777 the case, the \textbf{load 3} will never succeed regardless of how long you wait.
778 If this seems to be your problem, you can insert an eject just after the
779 unload so that the script looks like:
780
781 \begin{bVerbatim}
782 #!/bin/sh
783 /opt/bacula/scripts/mtx-changer /dev/sg0 unload 1 /dev/nst0 0
784 mt -f /dev/st0 offline
785 /opt/bacula/scripts/mtx-changer /dev/sg0 load 3 /dev/nst0 0
786 mt -f /dev/st0 rewind
787 mt -f /dev/st0 weof
788 \end{bVerbatim}
789
790 Obviously, if you need the \bcommandname{offline} command, you should move it into the
791 \mtxchanger{} script ensuring that you save the status of the \mtx{} command
792 or always force an \textbf{exit 0} from the script, because \bacula{} checks the
793 return status of the script.
794
795 As noted earlier, there are several scripts in \textbf{\bdirectoryname{\bbracket{bacula-source}/examples/devices}}
796 that implement the above features,
797 so they may be a help to you in getting your script to work.
798
799 If \bacula{} complains ``Rewind error on \bfilename{/dev/nst0}. ERR=Input/output error.'' you
800 most likely need more sleep time in your \mtxchanger{} before returning to
801 \bacula{} after a load command has been completed.
802
803 \label{blb:using}
804
805 \section{Using the Autochanger}
806 \index[general]{Using the Autochanger}
807 \index[general]{Autochanger!Using the}
808
809 Let's assume that you have properly defined the necessary Storage daemon
810 Device records, and you have added the \textbf{\bdirectivename{Autochanger = yes}} record to the
811 Storage resource in your Director's configuration file.
812
813 Now you fill your autochanger with say six blank tapes.
814
815 What do you do to make \bacula{} access those tapes?
816
817 One strategy is to prelabel each of the tapes. Do so by starting \bacula{}, then
818 with the Console program, enter the \bcommandname{label} command:
819
820 \begin{bVerbatim}
821 ./bconsole
822 Connecting to Director rufus:9101
823 1000 OK: rufus-dir Version: 1.26 (4 October 2002)
824 *label
825 \end{bVerbatim}
826
827 it will then print something like:
828
829 \begin{bVerbatim}
830 Using default Catalog name=BackupDB DB=bacula
831 The defined Storage resources are:
832 1: Autochanger
833 2: File
834 Select Storage resource (1-2): 1
835 \end{bVerbatim}
836
837 I select the autochanger (1), and it prints:
838
839 \begin{bVerbatim}
840 Enter new Volume name: TestVolume1
841 Enter slot (0 for none): 1
842 \end{bVerbatim}
843
844 where I entered \textbf{TestVolume1} for the tape name, and slot \textbf{1} for the
845 slot. It then asks:
846
847 \begin{bVerbatim}
848 Defined Pools:
849 1: Default
850 2: File
851 Select the Pool (1-2): 1
852 \end{bVerbatim}
853
854 I select the Default pool. This will be automatically done if you only have a
855 single pool, then \bacula{} will proceed to unload any loaded volume, load the
856 volume in slot 1 and label it. In this example, nothing was in the drive, so
857 it printed:
858
859 \begin{bVerbatim}
860 Connecting to Storage daemon Autochanger at localhost:9103 ...
861 Sending label command ...
862 3903 Issuing autochanger "load slot 1" command.
863 3000 OK label. Volume=TestVolume1 Device=/dev/nst0
864 Media record for Volume=TestVolume1 successfully created.
865 Requesting mount Autochanger ...
866 3001 Device /dev/nst0 is mounted with Volume TestVolume1
867 You have messages.
868 *
869 \end{bVerbatim}
870
871 You may then proceed to label the other volumes. The messages will change
872 slightly because \bacula{} will unload the volume (just labeled TestVolume1)
873 before loading the next volume to be labeled.
874
875 Once all your Volumes are labeled, \bacula{} will automatically load them as they
876 are needed.
877
878 To ``see'' how you have labeled your Volumes, simply enter the \bcommandname{list volumes} command from the Console program, which should print something like
879 the following:
880
881 \begin{bVerbatim}
882 * list volumes
883 Using default Catalog name=BackupDB DB=bacula
884 Defined Pools:
885 1: Default
886 2: File
887 Select the Pool (1-2): 1
888 +-------+----------+--------+---------+-------+--------+----------+-------+------+
889 | MedId | VolName | MedTyp | VolStat | Bites | LstWrt | VolReten | Recyc | Slot |
890 +-------+----------+--------+---------+-------+--------+----------+-------+------+
891 | 1 | TestVol1 | DDS-4 | Append | 0 | 0 | 30672000 | 0 | 1 |
892 | 2 | TestVol2 | DDS-4 | Append | 0 | 0 | 30672000 | 0 | 2 |
893 | 3 | TestVol3 | DDS-4 | Append | 0 | 0 | 30672000 | 0 | 3 |
894 | ... |
895 +-------+----------+--------+---------+-------+--------+----------+-------+------+
896 \end{bVerbatim}
897
898 \label{blb:Barcodes}
899
900 \section{Barcode Support}
901 \index[general]{Support!Barcode}
902 \index[general]{Barcode Support}
903
904 \bacula{} provides barcode support with two Console commands, \bcommandname{label barcodes}
905 and \bcommandname{update slots}.
906
907 The \bcommandname{label barcodes} will cause \bacula{} to read the barcodes of all the
908 cassettes that are currently installed in the magazine (cassette holder) using
909 the \mtxchanger{} \textbf{list} command. Each cassette is mounted in turn and
910 labeled with the same Volume name as the barcode.
911
912 The \bcommandname{update slots} command will first obtain the list of cassettes and
913 their barcodes from \mtxchanger{}. Then it will find each volume in turn
914 in the catalog database corresponding to the barcodes and set its slot to
915 correspond to the value just read. If the Volume is not in the catalog, then
916 nothing will be done. This command is useful for synchronizing \bacula{} with the
917 current magazine in case you have changed magazines or in case you have moved
918 cassettes from one slot to another. If the autochanger is empty, nothing will
919 be done.
920
921 The \textbf{\bdirectivename{Cleaning Prefix}} statement can be used in the Pool resource to define
922 a Volume name prefix, which if it matches that of the Volume (barcode) will
923 cause that Volume to be marked with a VolStatus of \textbf{Cleaning}. This will
924 prevent \bacula{} from attempting to write on the Volume.
925
926 \section{Use bconsole to display Autochanger content}
927
928 The \bcommandname{status slots storage=xxx} command displays autochanger content.
929
930 \begin{bVerbatim}
931 Slot | Volume Name | Status | Type | Pool | Loaded |
932 ------+-----------------+----------+-------------------+----------------+---------|
933 1 | 00001 | Append | DiskChangerMedia | Default | 0 |
934 2 | 00002 | Append | DiskChangerMedia | Default | 0 |
935 3*| 00003 | Append | DiskChangerMedia | Scratch | 0 |
936 4 | | | | | 0 |
937 \end{bVerbatim}
938
939 If you see a \textbf{*} near the slot number, you have to run \bcommandname{update slots}
940 command to synchronize autochanger content with your catalog.
941
942 \label{blb:interface}
943
944 \section{\bacula{} Autochanger Interface}
945 \index[general]{Interface!\bacula{} Autochanger}
946 \index[general]{\bacula{} Autochanger Interface}
947
948 \bacula{} calls the autochanger script that you specify on the \textbf{\bdirectivename{Changer Command}}
949 statement. Normally this script will be the \mtxchanger{} script
950 that we provide, but it can in fact be any program. The only requirement
951 for the script is that it must understand the commands that
952 \bacula{} uses, which are \textbf{loaded}, \textbf{load},
953 \textbf{unload}, \textbf{list}, and \textbf{slots}. In addition,
954 each of those commands must return the information in the precise format as
955 specified below:
956
957 Currently the changer commands used are:
958 \begin{bdescription}
959 \item [loaded] returns number of the slot that is loaded, base 1,
960 in the drive or 0 if the drive is empty.
961 \item [load] loads a specified slot (note, some autochangers
962 require a 30 second pause after this command) into
963 the drive.
964 \item [unload] unloads the device (returns cassette to its slot).
965 \item [list] returns one line for each cassette in the autochanger
966 in the format \bbracket{slot}:\bbracket{barcode}. Where
967 the \bbracket{slot} is the non-zero integer representing
968 the slot number, and \bbracket{barcode} is the barcode
969 associated with the cassette if it exists and if you
970 autoloader supports barcodes. Otherwise the barcode
971 field is blank.
972 \item [slots] returns total number of slots in the autochanger.
973 \end{bdescription}
974
975 \bacula{} checks the exit status of the program called, and if it is zero, the
976 data is accepted. If the exit status is non-zero, \bacula{} will print an
977 error message and request the tape be manually mounted on the drive.