git.gag.com Git - debian/amanda/blob - man/amanda-changers.7

   1 '\" t
   2 .\"     Title: amanda-changers
   3 .\"    Author: Dustin J. Mitchell <dustin@zmanda.com>
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot_8273 <http://docbook.sf.net/>
   5 .\"      Date: 11/05/2009
   6 .\"    Manual: Miscellanea
   7 .\"    Source: Amanda 2.6.1p2
   8 .\"  Language: English
   9 .\"
  10 .TH "AMANDA\-CHANGERS" "7" "11/05/2009" "Amanda 2\&.6\&.1p2" "Miscellanea"
  11 .\" -----------------------------------------------------------------
  12 .\" * set default formatting
  13 .\" -----------------------------------------------------------------
  14 .\" disable hyphenation
  15 .nh
  16 .\" disable justification (adjust text to left margin only)
  17 .ad l
  18 .\" -----------------------------------------------------------------
  19 .\" * MAIN CONTENT STARTS HERE *
  20 .\" -----------------------------------------------------------------
  21 .SH "NAME"
  22 amanda-changers \- Configuring and Using Amanda Changers
  23 .SH "DESCRIPTION"
  24 .PP
  25 Amanda uses changers to arbitrate access to devices (\fBamanda-devices\fR(7)) and data volumes\&. Changers provide an abstraction of tape robots, but are used to manage non\-tape media, too\&. Amanda communicates with changers through the Changer API\&. This manpage contains a
  26 \fIuser\-level\fR
  27 overview of the API, and does not address details that are only of concern to developers\&. For that purpose, consult the Amanda source code and http://wiki\&.zmanda\&.com\&.
  28 .SH "TRANSITION"
  29 .PP
  30 The Amanda Changer API is in transition from version 1\&.0 \- driven by shell scripts invoked for each changer operation \- to version 2\&.0, composed of perl objects that can manage parallel access to multiple devices and other complexity\&. When this transition is complete, Amanda devices will, in general, be specified via a changer, which will provide the necessary device specifier to access a requested volume\&. In the interim, support for the "new" changer syntax is limited to the experimental
  31 \fBamvault\fR(8)\&.
  32 .SH "SPECIFYING CHANGERS"
  33 .PP
  34 Changer specifications are strings like
  35 chg\-disk:/my/vtapes\&. The
  36 chg\-
  37 prefix serves to differentiate changers from devices (see
  38 \fBamanda-devices\fR(7))\&. The next portion (disk, in this case) identifies the particular changer driver to use, and everything that follows the
  39 :
  40 is interpreted by the driver\&.
  41 .PP
  42 A name which does not match this pattern, but which matches an old changer script (e\&.g\&.,
  43 chg\-zd\-mtx), invokes the backward\-compatibility changer driver as
  44 chg\-compat:chg\-zd\-mtx\&. If the name does not match an old changer, then it is treated as an Amanda device, and is wrapped by the single\-device changer, e\&.g\&.,
  45 chg\-single:tape:/dev/rmt/0\&.
  46 .PP
  47 Changers which require additional parameters can also be described in
  48 \fBamanda.conf\fR(5)
  49 with "changer" sections, for example,
  50 .sp
  51 .nf
  52 define changer hp\-robot {
  53     tapedev "chg\-robot:/dev/sg1"
  54     property "drives" "0=/dev/nst0;1=/dev/nst0"
  55     property "slots" "1\-10"
  56 }
  57 .fi
  58 (note that "chg\-robot" is not yet implemented, so this is hypothetical)\&. A changer defininition creates a changer "alias", in this case named
  59 \fIhp\-robot\fR, which can then be named where an application expects a changer \- for example, the target of the
  60 \fBamvault\fR
  61 command\&.
  62 .SH "CHANGER DRIVERS"
  63 .PP
  64 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\&.
  65 .SS "chg\-disk (new)"
  66 .nf
  67 tpchanger "chg\-disk:/u01/vtapes"
  68 .fi
  69 .PP
  70 This changer driver replaces the old
  71 \fBchg\-disk\fR, supporting parallel access to vtapes stored in directories named
  72 slotN
  73 in the directory specified after
  74 chg\-disk:\&. It does so by creating numbered "drives" so that simultaneous processes can access distinct slots\&.
  75 .SS "chg\-disk (old)"
  76 .nf
  77 tapedev "file:/u01/vtapes"
  78 tpchanger "chg\-disk"
  79 .fi
  80 .PP
  81 This changer script supports sequential access to vtapes stored in directories named
  82 slotN
  83 in the directory specified by the
  84 \fItapedev\fR
  85 parameter\&.
  86 .SS "chg\-multi"
  87 .nf
  88 tpchanger "chg\-multi"
  89 changerfile "chg\-multi\-state"
  90 .fi
  91 .PP
  92 This script simply round\-robins a number of distinct device names, as specified in its configuration file\&. It is useful when all volumes for a configuration have different device names \-\- for example, with S3 devices\&. The
  93 \fIchangerfile\fR
  94 need not exist; it is used as a prefix for filenames of state files\&.
  95 .SS "chg\-manual"
  96 .nf
  97 tpchanger "chg\-manual"
  98 changerfile "chg\-manual\&.conf"
  99 .fi
 100 .PP
 101 This script simply provides distinct device names in a round\-robin fashion, as specified in its configuration file\&. It is useful when all volumes for a configuration have different device names \-\- for example, with S3 devices\&. The configuration file parameters are (as listed in the script):
 102 .sp
 103 .nf
 104 resend_mail=900       # resend mail every __ seconds
 105 timeout_mail=604800   # time out after this many seconds (default 7 days)
 106 request="[type]"      # How to request a new tape (default "tty_email")
 107   request="tty"       # Use the tty to ask the user to change tape\&.
 108                       # Can\'t be use by cron
 109   request="email"     # Send an email to ask the user to change tape\&.
 110   request="tty_email" # Use the tty if it exist or send an email\&.
 111 .fi
 112 .SS "chg\-zd\-mtx"
 113 .nf
 114 tpchanger "chg\-zd\-mtx"
 115 changerdev "/dev/sg0"         # used with \'mtx \-f\'
 116 changerfile "chg\-zd\-mtx\&.conf"
 117 tapedev "tape:/dev/nst0"
 118 .fi
 119 .PP
 120 This script interfaces with a tape drive using the Zubkoff/Dandelion version of mtx\&. That\'s the version that takes a device specifier with the
 121 \fB\-f\fR
 122 option and has subcommands like
 123 \fBstatus\fR\&. The configuration file parameters are (as listed in the script itself):
 124 .sp
 125 .nf
 126 firstslot=?                 #### First storage slot (element)
 127 lastslot=?                  #### Last storage slot (element)
 128 cleanslot=\-1                #### Slot with cleaner tape \-\- default is "\-1"
 129                             #### Set negative to indicate no cleaner available
 130 driveslot=0                 #### Drive slot number\&.  Defaults to 0
 131                             #### Use the \'Data Transfer Element\' you want
 132 autoclean=0                 #### Set to \'1\' or greater to enable
 133 autocleancount=99           #### Number of access before a clean\&.
 134 havereader=0                #### If you have a barcode reader, set to 1\&.
 135 offline_before_unload=0     #### Does your robot require an
 136                             #### \'mt offline\' before mtx unload?
 137 poll_drive_ready=NN         #### Time (seconds) between tests to see if
 138                             #### the tape drive has gone ready (default: 3)\&.
 139 max_drive_wait=NN           #### Maximum time (seconds) to wait for the
 140                             #### tape drive to become ready (default: 120)\&.
 141 initial_poll_delay=NN       #### initial delay after load before polling for
 142                             #### readiness
 143 slotinfofile=FILENAME       #### record slot information to this file, in
 144                             #### the line\-based format "SLOT LABEL\en"
 145 .fi
 146 .SS "chg\-rait"
 147 .nf
 148 tpchanger "chg\-rait"
 149 changerfile "chg\-rait\&.conf"
 150 .fi
 151 .PP
 152 This changer script constructs RAIT devices out of the devices provided by several "sub\-changers"\&. The configuration file specifies
 153 nchangers, the number of subchangers, and then provides
 154 tpchanger,
 155 changerdev_N,
 156 changerfile_N, and
 157 tpchanger_N
 158 for each sub\-changer, 1 through N\&.
 159 .SS "chg\-null"
 160 .nf
 161 tpchanger "chg\-null"
 162 .fi
 163 .PP
 164 This changer always provides the device "null:"\&. It is sometimes useful in conjunction with
 165 \fBchg\-rait\fR\&.
 166 .SS "Unmaintained Changers"
 167 .PP
 168 Amanda has many other changer scripts and programs beyond those described here (see the
 169 changer\-src/
 170 in the source directory), but most of these scripts are unmaintained and undocumented, and will be removed when the new changer API is fully implemented\&.
 171 .SH "SEE ALSO"
 172 .PP
 173
 174 \fBamanda\fR(8),
 175 \fBamanda.conf\fR(5),
 176 \fBamanda-devices\fR(7),
 177 .SH "AUTHOR"
 178 .PP
 179 \fBDustin J\&. Mitchell\fR <\&dustin@zmanda\&.com\&>
 180 .RS 4
 181 Zmanda, Inc\&. (http://www\&.zmanda\&.com)
 182 .RE