From 3f2ba8e2fe1f29c0954da7ae68542b181cf67527 Mon Sep 17 00:00:00 2001 From: Kern Sibbald Date: Sat, 3 Jun 2017 15:55:01 +0200 Subject: [PATCH] Improve Autochanger documentation --- docs/manuals/en/main/autochangerres.tex | 73 +++++++++--- docs/manuals/en/main/autochangers.tex | 142 +++++++----------------- docs/manuals/en/main/storedconf.tex | 16 ++- 3 files changed, 114 insertions(+), 117 deletions(-) diff --git a/docs/manuals/en/main/autochangerres.tex b/docs/manuals/en/main/autochangerres.tex index 98563c77..bd0cb9fb 100644 --- a/docs/manuals/en/main/autochangerres.tex +++ b/docs/manuals/en/main/autochangerres.tex @@ -33,22 +33,65 @@ will not work for Autochangers. device names on a single line separated by commas, and/or you may specify multiple Device directives. This directive is required. -\item [Changer Device = {\it name-string}] - \index[sd]{Changer Device} - The specified {\bf name-string} gives the system file name of the autochanger - device name. If specified in this resource, the Changer Device name - is not needed in the Device resource. If it is specified in the Device - resource (see above), it will take precedence over one specified in - the Autochanger resource. - -\item [Changer Command = {\it name-string}] +\item [Changer Device = \lt{}device-name\gt{}] + \index[sd]{Changer Device } + In addition to the Archive Device name, you may 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 = \lt{}command\gt{}] \index[sd]{Changer Command } - The {\bf name-string} specifies an external program to be called that will - automatically change volumes as required by {\bf Bacula}. Most frequently, - you will specify the Bacula supplied {\bf mtx-changer} script as follows. - If it is specified here, it need not be specified in the Device - resource. If it is also specified in the Device resource, it will take - precedence over the one specified in the Autochanger resource. + 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 Bacula 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 Bacula distribution) is: + +\footnotesize +\begin{verbatim} +Changer Command = "/etc/bacula/mtx-changer %c %o %S %a %d" +\end{verbatim} +\normalsize + +Where you will need to adapt the {\bf /etc/bacula} to be the actual path on +your system where the mtx-changer script resides. Details of the three +commands currently used by Bacula (loaded, load, unload) as well as the +output expected by Bacula are give in the {\bf Bacula Autochanger Interface} +section below. \end{description} diff --git a/docs/manuals/en/main/autochangers.tex b/docs/manuals/en/main/autochangers.tex index 6bfdc10f..bdef231b 100644 --- a/docs/manuals/en/main/autochangers.tex +++ b/docs/manuals/en/main/autochangers.tex @@ -37,9 +37,9 @@ which is explained in more detail after this list: slot number when you label Volumes. \end{itemize} -In version 1.37 and later, there is a new \ilink{Autochanger resource}{AutochangerRes} that permits you to group Device resources thus -creating a multi-drive autochanger. If you have an autochanger, -you {\bf must} use this new resource. +The \ilink{Autochanger resource}{AutochangerRes} permits you to group +Device resources thus creating a multi-drive autochanger. If you have an +autochanger, you {\bf must} use this resource. Bacula uses its own {\bf mtx-changer} script to interface with a program that actually does the tape changing. Thus in principle, {\bf mtx-changer} @@ -61,9 +61,8 @@ However, if you are very careful to setup Bacula to access the Volumes in the autochanger sequentially, you may be able to make Bacula work with stackers (gravity feed and such). -Support for multi-drive -autochangers requires the \ilink{Autochanger resource}{AutochangerRes} -introduced in version 1.37. This resource is also recommended for single +Support for multi-drive autochangers requires the \ilink{Autochanger +resource}{AutochangerRes}. This resource is also recommended for single drive autochangers. In principle, if {\bf mtx} will operate your changer correctly, then it is @@ -74,15 +73,6 @@ supported by {\bf mtx} at the following link: The home page for the {\bf mtx} project can be found at: \elink{http://mtx.opensource-sw.net/}{http://mtx.opensource-sw.net/}. -Note, we have feedback from some users that there are certain -incompatibilities between the Linux kernel and mtx. For example between -kernel 2.6.18-8.1.8.el5 of CentOS and RedHat and version 1.3.10 and 1.3.11 -of mtx. This was fixed by upgrading to a version 2.6.22 kernel. - -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 Bacula. When Bacula is running, please remember that for many distributions (e.g. FreeBSD, @@ -98,6 +88,8 @@ 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. + + \label{SCSI devices} \section{Knowing What SCSI Devices You Have} \index[general]{Have!Knowing What SCSI Devices You } @@ -229,16 +221,14 @@ in the Console program. \index[general]{Devices!Multiple} \index[general]{Multiple Devices} -Some autochangers have more than one read/write device (drive). The -new \ilink{Autochanger resource}{AutochangerRes} introduced in version -1.37 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 +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. +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 @@ -252,25 +242,26 @@ Device}. As a default, Bacula jobs will prefer to write to a Volume that is already mounted. If you have a multiple drive autochanger and you want Bacula 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} +time. An alternative is to define a {\bf Maximum Concurrent Jobs} in +the {\bf Device} resource to limit the number of simultaneous backups to +a particular drive. +\smallskip +You may also 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. +the Storage daemon to maximize the use of drives. However, we do not +particularly recommend setting Prefer Mounted Volumes to no, because it +seems to increase the number of drive conflicts that can lead to dead-lock +situations. \label{ConfigRecords} \section{Device Configuration Records} -\index[general]{Records!Device Configuration } -\index[general]{Device Configuration Records } - -Configuration of autochangers within Bacula 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 Bacula uses -the autochanger. +\index[general]{Records!Device Configuration} +\index[general]{Device Configuration Records} -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. +Configuration of autochangers within Bacula is normally done in the +{\bf Autochanger} resource (see below). However, first we discuss +setting up the {\bf Device} resource for use with an autochanger. \begin{description} @@ -279,65 +270,6 @@ if they are present in the {\bf Autochanger} resource. The {\bf Autochanger} record specifies that the current device is or is not an autochanger. The default is {\bf no}. -\item [Changer Device = \lt{}device-name\gt{}] - \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 = \lt{}command\gt{}] - \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 Bacula 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 Bacula distribution) is: - -\footnotesize -\begin{verbatim} -Changer Command = "/etc/bacula/mtx-changer %c %o %S %a %d" -\end{verbatim} -\normalsize - -Where you will need to adapt the {\bf /etc/bacula} to be the actual path on -your system where the mtx-changer script resides. Details of the three -commands currently used by Bacula (loaded, load, unload) as well as the -output expected by Bacula are give in the {\bf Bacula Autochanger Interface} -section below. \item [Maximum Changer Wait = \lt{}time\gt{}] \index[sd]{Maximum Changer Wait } @@ -362,9 +294,22 @@ Device Index = 1 \end{verbatim} \normalsize +\smallskip To use the second drive, you need a second Device resource definition in the Bacula configuration file. See the Multiple Drive section above in this chapter for more information. + +\smallskip +In addtion to the above Directives there are two others that may +appear in a {\bf Device} resource. They are {\bf Changer Device} and +{\bf Changer Command}. These were originally used for single drive +autochanger prior to the implementation of the {\bf Autochanger} directive. +With the implementation of the Autochanger directive, these two Directives +should be specified only in the Autochanger resource. For historical +reasons they may be specified in a {\bf Device} resource. For more +details of these two directives see the {\bf Autochanger} documentation +below. + \end{description} In addition, for proper functioning of the Autochanger, you must @@ -679,8 +624,7 @@ 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. +drive before starting Bacula. Please see the \borgxrlink{Tape Testing}{FreeBSDTapes}{problems}{chapter} of the \problemsman{} for {\bf important} information concerning your tape drive before doing the @@ -865,7 +809,7 @@ with the Console program, enter the {\bf label} command: \begin{verbatim} ./bconsole Connecting to Director rufus:8101 -1000 OK: rufus-dir Version: 1.26 (4 October 2002) +1000 OK: rufus-dir Version: 7.9.1 (29 May 2017) *label \end{verbatim} \normalsize diff --git a/docs/manuals/en/main/storedconf.tex b/docs/manuals/en/main/storedconf.tex index 69ae1880..23b3fded 100644 --- a/docs/manuals/en/main/storedconf.tex +++ b/docs/manuals/en/main/storedconf.tex @@ -420,6 +420,10 @@ Device { \item [Changer Device = {\it name-string}] \index[sd]{Changer Device} \index[sd]{Directive!Changer Device} + Note: Eventhough this directive may be specified in the Device resource, + it is normally specified only in the {\bf Autochanger} resource. It + is listed here for historical reasons. + \smallskip The specified {\bf name-string} must be the {\bf generic SCSI} device name of the autochanger that corresponds to the normal read/write {\bf Archive Device} specified in the Device resource. This @@ -437,6 +441,10 @@ Device { \item [Changer Command = {\it name-string}] \index[sd]{Changer Command} \index[sd]{Directive!Changer Command} + Note: Eventhough this directive may be specified in the Device resource, + it is normally specified only in the {\bf Autochanger} resource. It + is listed here for historical reasons. + \smallskip The {\bf name-string} specifies an external program to be called that will automatically change volumes as required by {\bf Bacula}. Normally, this directive will be specified only in the {\bf AutoChanger} resource, @@ -500,6 +508,8 @@ bacula-sd Alert: TapeAlert[32]: Interface: Problem with SCSI interface \item [Drive Index = {\it number}] \index[sd]{Drive Index} \index[sd]{Directive!Drive Index} + This directive is only used for a Device that is part of an + Autochanger. The {\bf Drive Index} that you specify is passed to the {\bf mtx-changer} script and is thus passed to the {\bf mtx} program. By default, the Drive Index is zero, so if you have only one drive in your @@ -1141,9 +1151,9 @@ Similar consideration should be given to all other Command parameters. \end{description} %% This pulls in the Autochanger resource from another file. -\label{AutochangerRes} -\label{AutochangerResource1} -\input{autochangerres} +%%\label{AutochangerRes} +%%\label{AutochangerResource1} +%%\input{autochangerres} \section{Capabilities} \index[general]{Capabilities} -- 2.39.5