1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
5 <!-- entities files to use -->
6 <!ENTITY % global_entities SYSTEM '../entities/global.entities'>
10 <refentry id='amanda-changers.7'>
13 <refentrytitle>amanda-changers</refentrytitle>
14 <manvolnum>7</manvolnum>
20 <refname>amanda-changers</refname>
21 <refpurpose>Configuring and Using Amanda Changers</refpurpose>
26 <!-- body begins here -->
28 <refsect1><title>DESCRIPTION</title>
30 <para>Amanda uses changers to arbitrate access to devices
31 (<citerefentry><refentrytitle>amanda-devices</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
32 and data volumes. Changers provide an abstraction of tape robots, but are used
33 to manage non-tape media, too. Amanda communicates with changers through the
34 Changer API. This manpage contains a <emphasis>user-level</emphasis> overview
35 of the API, and does not address details that are only of concern to
36 developers. For that purpose, consult the Amanda source code and
37 http://wiki.zmanda.com.</para>
41 <refsect1><title>TRANSITION</title>
43 <para>The Amanda Changer API is in transition from version 1.0 - driven by
44 shell scripts invoked for each changer operation - to version 2.0, composed of
45 perl objects that can manage parallel access to multiple devices and other
46 complexity. When this transition is complete, Amanda devices will, in general,
47 be specified via a changer, which will provide the necessary device specifier
48 to access a requested volume. In the interim, support for the "new" changer
49 syntax is limited to the experimental
50 <citerefentry><refentrytitle>amvault</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
54 <refsect1><title>SPECIFYING CHANGERS</title>
56 <para>Changer specifications are strings like
57 <computeroutput>chg-disk:/my/vtapes</computeroutput>. The
58 <computeroutput>chg-</computeroutput> prefix serves to differentiate changers
60 <citerefentry><refentrytitle>amanda-devices</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
61 The next portion (<computeroutput>disk</computeroutput>, in this case)
62 identifies the particular changer driver to use, and everything that follows
63 the <computeroutput>:</computeroutput> is interpreted by the driver.</para>
65 <para>A name which does not match this pattern, but which matches an old
66 changer script (e.g., <computeroutput>chg-zd-mtx</computeroutput>), invokes the
67 backward-compatibility changer driver as
68 <computeroutput>chg-compat:chg-zd-mtx</computeroutput>. If the name does not
69 match an old changer, then it is treated as an Amanda device, and is wrapped by
70 the single-device changer, e.g.,
71 <computeroutput>chg-single:tape:/dev/rmt/0</computeroutput>.</para>
73 <para>Changers which require additional parameters can also be described in &amconf; with "changer" sections, for example,
75 define changer hp-robot {
76 tapedev "chg-robot:/dev/sg1"
77 property "drives" "0=/dev/nst0;1=/dev/nst0"
78 property "slots" "1-10"
82 (note that "chg-robot" is not yet implemented, so this is hypothetical). A
83 changer defininition creates a changer "alias", in this case named
84 <emphasis>hp-robot</emphasis>, which can then be named where an application
85 expects a changer - for example, the target of the <command>amvault</command> command.</para>
88 <refsect1><title>CHANGER DRIVERS</title>
90 <para>This section lists the changer drivers included with Amanda, and basic instructions for using them. For complete How-To information, consult the Amanda wiki at http://wiki.zmanda.com.</para>
92 <refsect2><title>chg-disk (new)</title>
94 tpchanger "chg-disk:/u01/vtapes"
97 <para>This changer driver replaces the old <command>chg-disk</command>,
98 supporting parallel access to vtapes stored in directories named
99 <computeroutput>slotN</computeroutput> in the directory specified after
100 <computeroutput>chg-disk:</computeroutput>. It does so by creating numbered
101 "drives" so that simultaneous processes can access distinct slots.</para>
105 <refsect2><title>chg-disk (old)</title>
107 tapedev "file:/u01/vtapes"
111 <para>This changer script supports sequential access to vtapes stored in
112 directories named <computeroutput>slotN</computeroutput> in the directory
113 specified by the <emphasis>tapedev</emphasis> parameter.</para>
117 <refsect2><title>chg-multi</title>
119 tpchanger "chg-multi"
120 changerfile "chg-multi-state"
123 <para>This script simply round-robins a number of distinct device names, as
124 specified in its configuration file. It is useful when all volumes for a
125 configuration have different device names -- for example, with S3 devices.
126 The <emphasis>changerfile</emphasis> need not exist; it is used as a prefix
127 for filenames of state files.
132 <refsect2><title>chg-manual</title>
134 tpchanger "chg-manual"
135 changerfile "chg-manual.conf"
138 <para>This script simply provides distinct device names in a round-robin
139 fashion, as specified in its configuration file. It is useful when all volumes
140 for a configuration have different device names -- for example, with S3
141 devices. The configuration file parameters are (as listed in the script):
143 resend_mail=900 # resend mail every __ seconds
144 timeout_mail=604800 # time out after this many seconds (default 7 days)
145 request="[type]" # How to request a new tape (default "tty_email")
146 request="tty" # Use the tty to ask the user to change tape.
147 # Can't be use by cron
148 request="email" # Send an email to ask the user to change tape.
149 request="tty_email" # Use the tty if it exist or send an email.
155 <refsect2><title>chg-zd-mtx</title>
157 tpchanger "chg-zd-mtx"
158 changerdev "/dev/sg0" # used with 'mtx -f'
159 changerfile "chg-zd-mtx.conf"
160 tapedev "tape:/dev/nst0"
163 <para>This script interfaces with a tape drive using the Zubkoff/Dandelion
164 version of mtx. That's the version that takes a device specifier with the
165 <command>-f</command> option and has subcommands like
166 <command>status</command>. The configuration file parameters are (as listed in
169 firstslot=? #### First storage slot (element)
170 lastslot=? #### Last storage slot (element)
171 cleanslot=-1 #### Slot with cleaner tape -- default is "-1"
172 #### Set negative to indicate no cleaner available
173 driveslot=0 #### Drive slot number. Defaults to 0
174 #### Use the 'Data Transfer Element' you want
175 autoclean=0 #### Set to '1' or greater to enable
176 autocleancount=99 #### Number of access before a clean.
177 havereader=0 #### If you have a barcode reader, set to 1.
178 offline_before_unload=0 #### Does your robot require an
179 #### 'mt offline' before mtx unload?
180 poll_drive_ready=NN #### Time (seconds) between tests to see if
181 #### the tape drive has gone ready (default: 3).
182 max_drive_wait=NN #### Maximum time (seconds) to wait for the
183 #### tape drive to become ready (default: 120).
184 initial_poll_delay=NN #### initial delay after load before polling for
186 slotinfofile=FILENAME #### record slot information to this file, in
187 #### the line-based format "SLOT LABEL\n"
193 <refsect2><title>chg-rait</title>
196 changerfile "chg-rait.conf"
199 <para>This changer script constructs RAIT devices out of the devices provided by several "sub-changers". The configuration file specifies <computeroutput>nchangers</computeroutput>, the number of
200 subchangers, and then provides <computeroutput>tpchanger</computeroutput>, <computeroutput>changerdev_N</computeroutput>, <computeroutput>changerfile_N</computeroutput>, and <computeroutput>tpchanger_N</computeroutput> for each sub-changer, 1 through N.</para>
204 <refsect2><title>chg-null</title>
209 <para>This changer always provides the device "null:". It is sometimes useful in conjunction with <command>chg-rait</command>.</para>
213 <refsect2><title>Unmaintained Changers</title>
215 <para>Amanda has many other changer scripts and programs beyond those described
216 here (see the <computeroutput>changer-src/</computeroutput> in the source
217 directory), but most of these scripts are unmaintained and undocumented, and
218 will be removed when the new changer API is fully implemented.</para>
224 <refsect1><title>SEE ALSO</title>
226 <citerefentry><refentrytitle>amanda</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
227 <citerefentry><refentrytitle>amanda.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
228 <citerefentry><refentrytitle>amanda-devices</refentrytitle><manvolnum>7</manvolnum></citerefentry>,