Debut de autochangers.tex.

[bacula/docs] / docs / manual-fr / autochangers.tex

%%
%%

\section*{Support des librairies}
\label{_ChapterStart18}
\index[general]{Support!Librairies}
\index[general]{Autochanger Support }
\addcontentsline{toc}{section}{Support des librairies}

\subsection*{G\'en\'eralit\'es sur les librairies}
\index[general]{G\'en\'eralit\'es!Librairies}
\index[general]{G\'en\'eralit\'es sur les librairies}
\addcontentsline{toc}{subsection}{G\'en\'eralit\'es sur les librairies}

Bacula supporte les librairies pour les op\'erations de lecture et \'ecriture. 
Plusieurs conditions sont requises pour que Bacula puisse utiliser une librairie. 
Celles-ci sont expliqu\'ees en d\'etail ci-dessous.
Mais voyons d'abord la liste de ces conditions :

\begin{itemize}
\item Un script charg\'e de piloter la librairie en accord avec les commandes 
   envoy\'ees par Bacula est requis. Nous fournissons un tel script pr\'evu pour fonctionner 
   avec le programme {\bf mtx} disponible dans les paquets {\bf depkgs}.
\item Chaque volume \`a utiliser doit \^etre d\'efini dans le catalogue et avoir 
  un num\'ero de slot (NDT : emplacement dans la librairie) assign\'e, de sorte 
  que Bacula puisse savoir o\`u se trouve le volume dans la librairie. Cet 
  enregistrement se fait la plupart du temps gr\^ace \`a la commande {\bf label}. 
  Voyez ci-dessous pour plus de d\'etails. Vous devez \'etiqueter manuellement 
  vos cartouches avant de pouvoir les utiliser.
\item Vous devez avoir modifi\'e le fichier de configuration de votre Storage 
  Daemon afin que la ressource Device identifie votre p\'eriph\'erique en tant 
  que librairie. Quelques autres param\`etres doivent \^etre d\'efinis.
\item Si vous n'ex\'ecutez pas le Storage Daemon en tant que root, vous devez 
  vous assurer qu'il d\'etient les droits requis pour acc\'eder au lecteur et au 
  bras robotis\'e de la librairie.
\item Vous devez placer la directive {\bf Autochanger = yes} dans la 
  ressource Storage de votre fichier bacula-dir.conf, de sorte que vous soyez 
  interrog\'e au sujet du slot \`a chaque \'etiquetage de cartouche.
\end{itemize}

Dans les versions ult\'erieures \`a 1.37, la nouvelle directive 
\ilink{Autochanger resource}{AutochangerRes} permet de grouper les ressources 
Device pour cr\'eer des librairies avec plusieurs lecteurs. Si vous avez une 
librairie, vous devez utiliser cette ressource.

Bacula utilise son propre script {\bf mtx-changer} pour interagir avec un 
programme qui effectue r\'eellement les changement de cartouches. Ainsi, 
{\bf mtx-changer} peut \^etre adapt\'e pour fonctionner avec n'importe quel 
programme de prise en chgarge de librairie. La version actuelle de 
{\bf mtx-changer} fonctionne avec le programme {\bf mtx} . Cependant, 
des utilisateurs de FreeBSD ont r\'ealis\'e un script, disponible dans 
le r\'epertoire {\bf examples/autochangers}, qui permet \`a Bacula de fonctionner 
avec le programme {\bf chio}.

Bacula supporte aussi les librairies \'equip\'ees de lecteurs de codes barres. 
Ce support inclut deux commandes de la console Bacula : {\bf label barcodes} 
et {\bf update slots}. Pour plus de d\'etails au sujet de ces commandes, 
voyez la section "Support des lecteurs de codes barres" plus loin.

Le support des librairies dans Bacula n'inclue pas, pour le moment, la gestion 
du nettoyage des lecteurs, ni celle des bacs de cartouches ou des silos. 
Cependant, sous certaines conditions, vous pouvez parvenir \`a le faire 
fonctionner avec des stackers (tels que gravity feed et apparent\'es). 
(NDT : le dernier paragraphe n'est pas clair. Voici la vo :
Current Bacula autochanger support does not include cleaning, stackers, or
silos.  However, under certain conditions, you may be able to make Bacula
work with stackers (gravity feed and such).)

Le support des librairies \`a plusieurs lecteurs requiert la ressource 
\ilink{Autochanger resource}{AutochangerRes}, qui est aussi recommand\'ee 
pour les librairies \`a un seul lecteur.

En principe, si {\bf mtx} fonctionne correctement avec votre librairie, ce 
n'est qu'une question d'avaptation du script {\bf mtx-changer} pour que 
Bacula s'interface correctement avec la librairie. Vous pouvez trouver une 
liste des librairies support\'ees par  {\bf mtx}  en suivant le lien suivant : 
\elink{http://mtx.badtux.net/compatibility.php}{http://mtx.badtux.net/compatibility.php}.
Le sit officiel du projet  {\bf mtx} se trouve ici : 
\elink{http://mtx.badtux.net/}{http://mtx.badtux.net/}.

Si vous avez des difficult\'es, veuillez utiliser la commande  {\bf auto} du 
programme  {\bf btape} pour tester le fonctionnement de votre librairie 
avec Bacula. Lorsque Bacula fonctionne, souvenez vous que pour beaucoup de 
distributions (par exemple FreeBSD, Debian,...), le Storage Daemon est 
ex\'ecut\'e en tant que {\bf bacula.tape}  plut\^ot que {\bf root.root}, aussi 
vous devrez vous assurer que le Storage Daemon dispose de droits suffisants pour 
acc\'eder \`a la librairie.

\label{SCSI devices}
\subsection*{D\'eterminer vos p\'eriph\'eriques SCSI}
\index[general]{D\'eterminer!p\'eriph\'eriques SCSI}
\index[general]{D\'eterminer vos p\'eriph\'eriques SCSI}
\index[general]{P\'eriph\'eriques}
\index[general]{p\'eriph\'eriques!SCSI}
\addcontentsline{toc}{subsection}{D\'eterminer vos p\'eriph\'eriques SCSI}

Sous Linux, vous pouvez lire le fichier /proc/scsi/scsi :

\footnotesize
\begin{verbatim}
cat /proc/scsi/scsi
\end{verbatim}
\normalsize

pour conna\^itre vos p\'eriph\'eriques SCSI. Vous pouvez aussi examiner les fichiers 
/proc/scsi/sg/device_hdr et /proc/scsi/sg/devices :

footnotesize
\begin{verbatim}
cat /proc/scsi/sg/device_hdr /proc/scsi/sg/devices
\end{verbatim}
\normalsize

pour d\'eterminer comment sp\'ecifier leur nom de p\'eriph\'erique ({\bf /dev/sg0} 
pour le premier, {\bf /dev/sg1} pour le second, ...) au niveau de 
la directive {\bf Changer Device}

Sous FreeBSD, vous disposez de la commande :

\footnotesize
\begin{verbatim}
camcontrol devlist
\end{verbatim}
\normalsize

pour afficher la liste des p\'eriph\'eriques SCSI ainsi que le {\bf /dev/passn} 
que vous utiliserez pour renseigner la directive {\bf Changer Device} 

Assurez-vous que votre Storage Daemon dispose bien des privil\`eges requis 
pour acc\'eder \`a ce p\'eriph\'erique.

L'astuce suivante, destin\'ee aux utilisateurs de FreeBSD, provient de 
Danny Butroyd. Au red\'emarrage, Bacula n'aura PLUS les permissions 
requises pour contr\^oler le p\'eriph\'erique /dev/pass0. Pour vous 
affanchir de cette difficult\'e, \'editez le fichier /etc/devfs.conf  et 
ajoutez lui ceci :

\footnotesize
\begin{verbatim}
own     pass0   root:bacula
perm    pass0   0666
own     nsa0.0  root:bacula
perm    nsa0.0    0666
\end{verbatim}
\normalsize

Nous avons ainsi donn\'e au groupe Bacula la permission d'\'ecrire 
sur le p\'eriph\'erique nsa0.0. Pour activer ces modifications, ex\'ecutez : 
/etc/rc.d/devfs restart

Vous n'aurez plus \`a modifier les permissions sur ces p\'eriph\'eriques 
pour que Bacula continue d'utiliser la librairie apr\`es un red\'emarrage.

\label{scripts}

\subsection*{Exemples de scripts}
\index[general]{Scripts!Exemples }
\index[general]{Exemples de scripts }
\addcontentsline{toc}{subsection}{Exemples de scripts}

Veuillez lire les sections ci-dessous pour bien comprendre comment 
les librairies fonctionnent avec Bacula. Bien que nous fournissions 
un script {\bf mtx-changer} par d\'efaut, il se peut que votre librairie 
n\'ecessite quelques am\'enagements de ce script. Si vous voulez voir des 
exemples de fichiers de configuration et de scripts, jetez un oeil 
au r\'epertoire \lt{}bacula-src\gt{}/examples/devices} o\`u vous 
trouverez un exemple de ressource Device Bacula : {\bf HP-autoloader.conf} 
ainsi que plusieurs scripts {\bf mtx-changer} modifi\'es pour fonctionner 
avec diverses librairies.

\label{Slots}

\subsection*{Slots}
\index[general]{Slots }
\addcontentsline{toc}{subsection}{Slots}

Pour utiliser convenablement une librairie, Bacula doit savoir quel volume 
se trouve dans quel {\bf slot} de la librairie. LE slots sont les 
emplacements o\`u sont rang\'ees les cartouches lorsqu'elles ne sont pas dans un 
lecteur. Bacula num\'erote ces slots de un jusqu'au nombre de cartouches 
contenues dans la librairie.

Bacula n'utilisera pas automatiquement une cartouche pr\'esente dans la librairie 
si elle ne porte pas d'\'etiquette (label) Bacula et si son num\'ero de slot n'est pas 
r\'ef\'erenc\'e dans le catalogue. Vous devez, \`a l'aide de la console, assigner un 
slot \`a chaque cartouche pr\'esente dans la librairie. Cette information est 
conserv\'ee dans le catalogue avec les autres donn\'ees relatives au volume. 
Si le slot n'est pas pr\'ecis\'e, ou s'il est \'egal \`a z\'ero, alors Bacula ne tentera 
pas d'utiliser la librairie, m\^eme si tous les enregistrements de configuration 
sont pr\'esents. De m\^eme, la commande {\bf mount} de la console Bacula ne 
provoque pas non plus l'utilisation de la librairie, mais se contente d'ordonner 
\`a Bacula de lire toute cartouche \'eventuellement pr\'esente dans le lecteur.

Vous pouvez contr\^oler le num\'ero de slot et le drapeau InChanger avec la commande :

\begin{verbatim}
list Volumes
\end{verbatim}

dans la console.

\label{mult}
\subsection*{Lecteurs multiples}
\index[general]{Lecteurs!Multiples }
\index[general]{Lecteurs ultiples}
\addcontentsline{toc}{subsection}{Lecteurs multiple}

Certaines librairies comportent plusieurs p\'eriph\'eriques de lecture/\'ectriture 
(lecteurs). La nouvelle \ilink{ressource Autochanger}{AutochangerRes} 
apparue avec la version 1.37 vous permet de grouper des ressources Devices 
(repr\'esentant chacune un lecteur). Le Director est toujours en mesure 
d'adresser directement un lecteur, mais ce faisant, il outrepasse 
le fonctionnement propre aux groupements de lecteurs. Il est pr\'ef\'erable 
que la Ressource Storage du Director d\'efinisse une ressource 
Autochanger, permettant ainsi au Storage Daemon de s'assurer qu'un seul 
lecteur \`a la fois utilise le script mtx-changer, et que deux lecteurs ne tentent 
pas de lire le m\^eme volume.

Les librairies \`a lecteurs multiples n\'ecessitent d'utiliser la directive 
{\bf Drive Index} dans la ressource Device du Storage Daemon. Les 
lecteurs sont num\'erot\'es \`a partir de z\'ero, ce qui constitue la valeur par 
d\'efaut. Pour utiliser un deuxi\`eme lecteur dans une librairie, vous devez 
d\'efinir une seconde ressource Device et lui attribuer le Drive Index 1. 
En g\'en\'eral, le second p\'eriph\'erique aura le m\^eme {\bf Changer Device} 
(canal de contr\^ole) que le premier, mais une {\bf Archive Device} diff\'erente. 

\label{ConfigRecords}
\subsection*{Directives de la ressource Device}
\index[general]{Directives!ressource Device}
\index[general]{Directives de la ressource Device}
\addcontentsline{toc}{subsection}{Directives de la ressource Device}

La configuration des librairies s'effectue dans Bacula au niveau de le ressource 
Device du Storage Daemon. Quatre directives permettent de d\'efinir l'usage de 
la librairie par Bacula : {\bf Autochanger}, {\bf Changer Device},
{\bf Changer Command} et {\bf Maximum Changer Wait 

Ces quatre directives sont d\'ecrites en d\'etail ci-dessous. Notez cependant 
que les directives {\bf Changer Device} et {\bf Changer Command} ne sont pas 
requises dans la ressource Device si elles figurent dans la ressource 
{\bf Autochanger}.

\begin{description}

\item [Autochanger = {\it Yes|No} ]
   \index[sd]{Autochanger}
   La directive {\bf Autochanger} stipule que le p\'eriph\'erique ainsi d\'efini est, ou 
   n'est pas, une librairie. La valeur par d\'efaut est {\bf no}.

\item [Changer Device = \lt{}device-name\gt{}]
   \index[sd]{Changer Device}
   En plus du nom d'Archive Device, vous devez sp\'ecifier un nom de 
   librairie {\bf Changer Device}, ceci parce que la plupart des librairies 
   sont control\'ees via un pseudo-fichier diff\'erent de celui utilis\'e pour 
   lire et \'ecrire sur les cartouches. Par exemple, sur les syst\`emes Linux, 
   on utilise g\'en\'eralement l'interface SCSI g\'en\'erique pour contr\^oler le bras 
   de la librairie, soit {\bf Changer Device = /dev/sg0} et l'interface SCSI 
   standard pour lire et \'ecrire sur les bandes, soit {\bf Archive Device = /dev/nst0}.
   Notez que certaines librairies \'evolu\'ees localiseront le bras sur 
   {\bf /dev/sg1}. De telles librairies ont souvent plusieurs lecteurs et un 
   nombre important de cartouches.

   Sur FreeBSD, on sp\'ecifiera typiquement {\bf Changer Device = /dev/pass0} ou 
   {\bf Changer Device = /dev/passn}.

   Sur Solaris, ce sera {\bf Changer Device = /dev/rdsk}.

   Assurez vous que votre Storage Daemon poss\`ede les permissions d'acc\'eder \`a 
   ce p\'eriph\'erique.

\item [Changer Command = \lt{}command\gt{}]
   \index[sd]{Changer Command  }
   Cette directive est utilis\'ee pour sp\'ecifier le programme externe \`a appeler 
   et les arguments \`a lui fournir. La commande est suppos\'ee \^etre un programme 
   ou un script shell standard qui peut \^etre ex\'ecut\'e par le syst\`eme. cette 
   commande est invoqu\'ee chaque fois que Bacula manipule le bras de la librairie. 
   Les substitutions suivantes sont effectu\'ees dans la ligne {\bf command} 
   avant qu'elle ne soit envoy\'ee au syst\`eme d'exploitation pour ex\'ecution.

\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

Voici un exemple d'utilisation de {\bf mtx} avec le script {\bf mtx-changer} :

\footnotesize
\begin{verbatim}
Changer Command = "/etc/bacula/mtx-changer %c %o %S %a %d"
\end{verbatim}
\normalsize

O\`u vous devrez adapter le chemin {\bf /etc/bacula} pour qu'il co\''incide \`a 
la r\'ealit\'e de votre installation. Les d\'etails des trois commandes (loaded, 
load, unload) utilis\'ees par Bacula ainsi que la sortie qui en est attendue 
sont donn\'es dans la section {\bf Interface entre Bacula et les librairies} 
ci-dessous.

\item [Maximum Changer Wait = \lt{}time\gt{}]
   \index[sd]{Maximum Changer Wait}
   Cet enregistrement sert \`a d\'efinir le d\'elai maximal durant lequel Bacula 
   attendra la r\'eponse d'une librairie \`a une commande (par exemple, load). 
   La valeur par d\'efaut est 120 secondes. Si votre librairie est lente, vous 
   pouvez avoir int\'er\^et \`a allonger ce d\'elai.
   
   Au del\`a de ce d\'elai, le programme de chargement est tu\'e et Bacula 
   sollicite l'intervention d'un op\'erateur.

\item [Drive Index = \lt{}number\gt{}]
   \index[sd]{Drive Index}
   Cette directive vous permet d'indiquer \`a Bacula d'utiliser le second 
   lecteur et les \'eventuels suivants dans une librairie qui en contient 
   plusieurs. Etant donn\'e que les lecteurs sont num\'erot\'es \`a partir de 
   z\'ero, le second est d\'efini par :

\footnotesize
\begin{verbatim}
Device Index = 1
\end{verbatim}
\normalsize

Pour utiliser le second lecteur, vous devez avoir une seconde d\'efinition 
de ressource Device dans le fichier bacula-sd.conf. Voyez la section 
concernant les lecteurs multiples plus haut dans ce chapitre pour plus 
de plus amples informations.
\end{description}

De plus, pour un fonctionnement correct de la librairie, vous devez d\'efinir 
une ressource Autochanger.
\input{autochangerres}

\label{example}
\subsection*{Un exemple de fichier de configuration}
\index[general]{exemple fichier configuration}
\index[general]{fichier!exemple configuration}
\addcontentsline{toc}{subsection}{Un exemple de fichier de configuration}

Les deux ressource suivantes impl\'ementent une librairie :

\footnotesize
\begin{verbatim}
Autochanger {
  Name = "Autochanger"
  Device = DDS-4
  Changer Device = /dev/sg0
  Changer Command = "/etc/bacula/mtx-changer %c %o %S %a %d"
}

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. 

\subsection*{A Multi-drive Example Configuration File}
\index[general]{Multi-drive Example Configuration File }
\addcontentsline{toc}{subsection}{A Multi-drive Example Configuration File}

The following resources implement a multi-drive autochanger: 

\footnotesize
\begin{verbatim}
Autochanger {
  Name = "Autochanger"
  Device = Drive-1, Drive-2
  Changer Device = /dev/sg0
  Changer Command = "/etc/bacula/mtx-changer %c %o %S %a %d"
}

Device {
  Name = Drive-1
  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-2
  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}, the {\bf Changer Device}, and
the path to the {\bf Changer Command} to correspond to the values used on your
system. 

\label{SpecifyingSlots}
\subsection*{Specifying Slots When Labeling}
\index[general]{Specifying Slots When Labeling }
\index[general]{Labeling!Specifying Slots When }
\addcontentsline{toc}{subsection}{Specifying Slots When Labeling}

If you add an {\bf Autochanger = yes} record to the Storage resource in your
Director's configuration file, the Bacula 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, Bacula 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. 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,
Bacula 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, Bacula 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: 

Please note that Volumes must be pre-labeled to be automatically used in
the autochanger during a backup.  If you do not have a barcode reader, this
is done manually (or via a script).

\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.

\label{Magazines}
\subsection*{Dealing with Multiple Magazines}
\index[general]{Dealing with Multiple Magazines }
\index[general]{Magazines!Dealing with Multiple }
\addcontentsline{toc}{subsection}{Dealing with Multiple Magazines}

If you have several magazines or if you insert or remove cartridges from a
magazine, you should notify Bacula of this. By doing so, Bacula 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 Bacula is simple. Every time, you change a magazine, or add or
remove a cartridge from the magazine, simply do 

\footnotesize
\begin{verbatim}
unmount
(remove magazine)
(insert new magazine)
update slots
mount
\end{verbatim}
\normalsize

in the Console program. This will cause Bacula 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. Bacula 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 Bacula'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 Bacula 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}

\label{simulating}
\subsection*{Simulating Barcodes in your Autochanger}
\index[general]{Autochanger!Simulating Barcodes in your }
\index[general]{Simulating Barcodes in your Autochanger }
\addcontentsline{toc}{subsection}{Simulating Barcodes in your Autochanger}

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/bacula/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/bacula/changer.volumes} file.
There is no need to stop and start Bacula 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 Bacula to be an autochanger with barcodes. 
\label{updateslots}

\subsection*{The Full Form of the Update Slots Command}
\index[general]{Full Form of the Update Slots Command }
\index[general]{Command!Full Form of the Update Slots }
\addcontentsline{toc}{subsection}{Full Form of the Update Slots Command}

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 Bacula 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 or have
not modified the mtx-changer script as described above, the above command will
not find any Volume names so will do nothing. 
\label{FreeBSD}

\subsection*{FreeBSD Issues}
\index[general]{Issues!FreeBSD }
\index[general]{FreeBSD Issues }
\addcontentsline{toc}{subsection}{FreeBSD Issues}

If you are having problems on FreeBSD when Bacula tries to select a tape, and
the message is {\bf Device not configured}, this is because FreeBSD has made
the tape device {\bf /dev/nsa1} disappear when there is no tape mounted in the
autochanger slot. As a consequence, Bacula is unable to open the device. The
solution to the problem is to make sure that some tape is loaded into the tape
drive before starting Bacula. This problem is corrected in Bacula versions
1.32f-5 and later. 

Please see the 
\ilink{ Tape Testing}{FreeBSDTapes} chapter of this manual for
{\bf important} information concerning your tape drive before doing the
autochanger testing. 
\label{AutochangerTesting}

\subsection*{Testing the Autochanger and Adapting Your mtx-changer Script}
\index[general]{Testing the Autochanger and Adapting Your mtx-changer Script }
\index[general]{Script!Testing the Autochanger and Adapting Your mtx-changer }
\addcontentsline{toc}{subsection}{Testing the Autochanger and Adapting Your
mtx-changer Script}

Before attempting to use the autochanger with Bacula, it is preferable to
"hand-test" that the changer works. To do so, we suggest you do the
following commands (assuming that the {\bf mtx-changer} script is installed in
{\bf /etc/bacula/mtx-changer}): 

\begin{description}

\item [Make sure Bacula is not running.]

\item [/etc/bacula/mtx-changer \ /dev/sg0 \ list \ 0 \ /dev/nst0 \ 0]
\index[sd]{mtx-changer list}

This command should print:  

\footnotesize
\begin{verbatim}
   1:
   2:
   3:
   ...
   
\end{verbatim}
\normalsize

or one number per line for each slot that is  occupied in your changer, and
the number should be  terminated by a colon ({\bf :}). If your changer has 
barcodes, the barcode will follow the colon.  If an error message is printed,
you must resolve the  problem (e.g. try a different SCSI control device name
if {\bf /dev/sg0}  is incorrect. For example, on FreeBSD systems, the
autochanger  SCSI control device is generally {\bf /dev/pass2}.  

\item [/etc/bacula/mtx-changer \ /dev/sg0 \ slots \ 0 \ /dev/nst0 \ 0]
\index[sd]{mtx-changer slots}

This command should return the number of slots in your autochanger.  

\item [/etc/bacula/mtx-changer \ /dev/sg0 \ unload \ ]
\index[sd]{mtx-changer unload}

   If a tape is loaded, this should cause  it to be unloaded.  

\item [/etc/bacula/mtx-changer \ /dev/sg0 \ load \ 3 \ /dev/nst0 \ 0 ]
\index[sd]{mtx-changer load}

Assuming you have a tape in slot 3,  it will be loaded into the read slot (0).
 

\item [/etc/bacula/mtx-changer \ /dev/sg0 \ loaded \ 0 \ /dev/nst0 \ 0]
\index[sd]{mtx-changer loaded}

It should print "3"  

\item [/etc/bacula/mtx-changer \ /dev/sg0 \ unload]
\end{description}

Once all the above commands work correctly, assuming that you have the right
{\bf Changer Command} in your configuration, Bacula should be able to operate
the changer. The only remaining area of problems will be if your autoloader
needs some time to get the tape loaded after issuing the command. After the
{\bf mtx-changer} script returns, Bacula will immediately rewind and read the
tape. If Bacula gets rewind I/O errors after a tape change, you will probably
need to insert a {\bf sleep 20} after the {\bf mtx} command, but be careful to
exit the script with a zero status by adding {\bf exit 0} after any additional
commands you add to the script. This is because Bacula checks the return
status of the script, which should be zero if all went well. 

You can test whether or not you need a {\bf sleep} by putting the following
commands into a file and running it as a script: 

\footnotesize
\begin{verbatim}
#!/bin/sh
/etc/bacula/mtx-changer /dev/sg0 unload
/etc/bacula/mtx-changer /dev/sg0 load 3
mt -f /dev/st0 rewind
mt -f /dev/st0 weof
\end{verbatim}
\normalsize

If the above script runs, you probably have no timing problems. If it does not
run, start by putting a {\bf sleep 30} or possibly a {\bf sleep 60} in the 
script just after the mtx-changer load command. If that works, then you should
move the sleep into the actual {\bf mtx-changer} script so that it will be
effective when Bacula runs. 

A second problem that comes up with a small number of autochangers is that
they need to have the cartridge ejected before it can be removed. If this is
the case, the {\bf load 3} will never succeed regardless of how long you wait.
If this seems to be your problem, you can insert an eject just after the
unload so that the script looks like: 

\footnotesize
\begin{verbatim}
#!/bin/sh
/etc/bacula/mtx-changer /dev/sg0 unload
mt -f /dev/st0 offline
/etc/bacula/mtx-changer /dev/sg0 load 3
mt -f /dev/st0 rewind
mt -f /dev/st0 weof
\end{verbatim}
\normalsize

Obviously, if you need the {\bf offline} command, you should move it into the
mtx-changer script ensuring that you save the status of the {\bf mtx} command
or always force an {\bf exit 0} from the script, because Bacula checks the
return status of the script. 

As noted earlier, there are several scripts in {\bf
\lt{}bacula-source\gt{}/examples/devices} that implement the above features,
so they may be a help to you in getting your script to work. 

If Bacula complains "Rewind error on /dev/nst0. ERR=Input/output error." you
most likely need more sleep time in your {\bf mtx-changer} before returning to
Bacula after a load command has been completed.

\label{using}

\subsection*{Using the Autochanger}
\index[general]{Using the Autochanger }
\index[general]{Autochanger!Using the }
\addcontentsline{toc}{subsection}{Using the Autochanger}

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 Bacula access those tapes? 

One strategy is to prelabel each of the tapes. Do so by starting Bacula, then
with the Console program, enter the {\bf label} command: 

\footnotesize
\begin{verbatim}
./console
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=bacula
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 Bacula 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 Bacula will unload the volume (just labeled TestVolume1)
before loading the next volume to be labeled. 

Once all your Volumes are labeled, Bacula 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=bacula
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

\label{Barcodes}

\subsection*{Barcode Support}
\index[general]{Support!Barcode }
\index[general]{Barcode Support }
\addcontentsline{toc}{subsection}{Barcode Support}

Bacula provides barcode support with two Console commands, {\bf label
barcodes} and {\bf update slots}.

The {\bf label barcodes} will cause Bacula 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 Bacula with the
current magazine in case you have changed magazines or in case you have moved
cassettes from one slot to another.

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 Bacula from attempting to write on the Volume.

\label{interface}

\subsection*{Bacula Autochanger Interface}
\index[general]{Interface!Bacula Autochanger }
\index[general]{Bacula Autochanger Interface }
\addcontentsline{toc}{subsection}{Bacula Autochanger Interface}

Bacula calls the autochanger script that you specify on the {\bf Changer
Device} statement. Normally this script will be the {\bf mtx-changer} script
that we can provide, but it can in fact be any program. The only requirements
are that the "commands" that Bacula uses 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

Bacula checks the exit status of the program called, and if it is zero, the
data is accepted. If the exit status is non-zero, Bacula ignores any
information returned and treats the drive as if it is not an autochanger.