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: 06/02/2011
   6 .\"    Manual: Miscellanea
   7 .\"    Source: Amanda 3.3.0
   8 .\"  Language: English
   9 .\"
  10 .TH "AMANDA\-CHANGERS" "7" "06/02/2011" "Amanda 3\&.3\&.0" "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\&. At this point, all Amanda programs use the new Changer API directly, although 1\&.0 changer scripts are still fully supported via
  31 chg\-compat\&.
  32 .PP
  33 The Changer API strives to treat all changers identically, so that Amanda\'s behavior is independent of the changer in use\&. However, some parts of Amanda operate differently depending on whether a changer can efficiently search for a volume with a given label\&. This distinction is really only apparent with tape libraries: those with barcode readers can quickly find a desired tape, while those without may fall back to an inefficient scan of each volume\&. The capability to perform quick searches is called "fast\-search", and each changer is annotated below to indicate its support\&.
  34 .SH "SPECIFYING CHANGERS"
  35 .PP
  36 Changer specifications are strings like
  37 chg\-disk:/my/vtapes\&. The
  38 chg\-
  39 prefix serves to differentiate changers from devices (see
  40 \fBamanda-devices\fR(7))\&. The next portion (disk, in this case) identifies the particular changer driver to use, and everything that follows the
  41 :
  42 is interpreted by the driver\&. Note that the
  43 :
  44 character is required, even when nothing follows it\&. This is an easy way to distinguish new changer specifications from old\&.
  45 .PP
  46 A name which does not match this pattern, but which matches an old changer script (e\&.g\&.,
  47 chg\-zd\-mtx), invokes the backward\-compatibility changer driver as e\&.g\&.,
  48 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\&.,
  49 chg\-single:tape:/dev/rmt/0\&.
  50 .PP
  51 Changers which require additional parameters can also be described in
  52 \fBamanda.conf\fR(5)
  53 with "changer" sections\&. Such a changer defininition creates a changer "alias", in this case named
  54 \fIhp\-robot\fR, which can then be named where an application expects a changer \- for example, the target of the
  55 \fBamvault\fR
  56 command or in a global
  57 \fBtpchanger\fR
  58 parameter\&.
  59 .SS "CONFIGURATION"
  60 .PP
  61 The preferred method of specifying configuration for a changer is as a "changer" section in
  62 \fBamanda.conf\fR(5)\&. The
  63 \fItapedev\fR
  64 parameter then indicates, by name, the changer that will be used by default by most Amanda programs\&. For example:
  65 .sp
  66 .nf
  67 define changer hp\-robot {
  68     tapedev "chg\-robot:/dev/sg1"
  69     property "tape\-device" "0=tape:/dev/nst0"
  70     property append "tape\-device" "1=tape:/dev/nst1"
  71     device\-property "BLOCK_SIZE" "512k"
  72 }
  73 # \&.\&.\&.
  74 tapedev "hp\-robot"
  75 .fi
  76 .PP
  77 Several changer drivers accept
  78 \fIchanger properties\fR
  79 which control the behavior of the changer\&. These properties must be specified in a changer definition, as in the
  80 \fIhp\-robot\fR
  81 example, above\&.
  82 .PP
  83 Devices, too, can take properties to control their behavior (see
  84 \fBamanda-devices\fR(7))\&. Device properties can come from four places: implicit device properties (from tapetype parameters), global device properties (from global
  85 \fIdevice\-property\fR
  86 parameters), properties in device definitions, and properties in changer definitions\&. Properties are applied in this order, with later properties taking priority\&.
  87 .PP
  88 There are only three implicit properties:
  89 \fIMAX_VOLUME_USAGE\fR
  90 is set based on the tapetype
  91 \fIlength\fR
  92 parameter,
  93 \fIREAD_BLOCK_SIZE\fR
  94 is set if
  95 \fIreadblocksize\fR
  96 is set, and
  97 \fIBLOCK_SIZE\fR
  98 is set based on the
  99 \fIblocksize\fR
 100 parameter\&.
 101 .PP
 102 Global device properties always apply\&. If the changer specifies a device by alias, then device properties from the definition apply\&. If the changer is specified by an alias, then properties from that definition applied\&.
 103 .SH "CHANGER DRIVERS"
 104 .PP
 105 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\&.
 106 .SS "chg\-aggregate:changer (new)"
 107 .nf
 108 define changer robot0 {
 109   tpchanger "chg\-robot:/dev/sg0"
 110   property "tape\-device" "0=tape:/dev/rmt/0" "1=tape:/dev/rmt/1"
 111 }
 112 define changer robot1 {
 113   tpchanger "chg\-robot:/dev/sg1"
 114   property "tape\-device" "0=tape:/dev/rmt/2" "1=tape:/dev/rmt/3"
 115 }
 116 define changer single {
 117   tpchanger "chg\-single:/dev/rmt/4"
 118 }
 119 define changer aggregate {
 120   tpchanger "chg\-aggregate:{robot0,robot1,single}"
 121   property "state\-filename" "/etc/amanda/CONF/aggregate\&.state"
 122
 123 }
 124 tpchanger "aggregate"
 125 .fi
 126 .PP
 127 This changer driver allow to use two or more changers or standalone drive in sequence\&.
 128 .SS "chg\-disk:VTAPEROOT (new)"
 129 .nf
 130 tpchanger "chg\-disk:/var/mnt/vtapes"
 131 property "num\-slot" "10"
 132 property "auto\-create\-slot" "yes"
 133 property "removable" "yes"
 134 property "mount" "yes"
 135 property "umount" "yes"
 136 property "umount\-lockfile" "/etc/amanda/conf/vtapes\-lock"
 137 property "umount\-idle" "1"
 138 .fi
 139 .PP
 140 This changer driver replaces the old
 141 \fBchg\-disk\fR, supporting parallel access to vtapes stored in directories named
 142 slotN
 143 in the directory specified after
 144 chg\-disk:\&. It does so by creating numbered "drives" so that simultaneous processes can access distinct slots\&. This changer is fast\-search capable\&.
 145 .PP
 146 The current slot can be accessed using the device name
 147 file:VTAPEROOT\&. This is useful for the
 148 \fBamrestore\fR(8)
 149 command line\&.
 150 .SS "Properties"
 151 .PP
 152 AUTO\-CREATE\-SLOT
 153 .RS 4
 154
 155 If a slotN directory in the range 1 to NUM\-SLOT does not already exist, and this property is true, then the changer will create the directory\&.
 156 .RE
 157 .PP
 158 MOUNT
 159 .RS 4
 160
 161 If this property is true, the changer try to mount the removable disk if nothing is mounted\&. The system must be configured to allow the amanda user to mount it\&.
 162 .RE
 163 .PP
 164 NUM\-SLOT
 165 .RS 4
 166
 167 The minimum number of slots in the changer, where the first slot is slot1\&.  If additional slot directories exist, they will also be used\&.
 168 .RE
 169 .PP
 170 REMOVABLE
 171 .RS 4
 172
 173 If this property is true, then the changer will verify that the changer
 174 directory (e\&.g\&., /var/mnt/vtapes) is on a different
 175 filesystem from its parent directory (e\&.g\&., /var/mnt)\&.
 176 This is useful for removable disks, as it will prevent Amanda from creating
 177 slot directories when the removable disk is not mounted\&.
 178 .RE
 179 .PP
 180 UMOUNT
 181 .RS 4
 182
 183 If this property is true, the changer try to umount the removable disk when it exit\&. The system must be configured to allow the amanda user to umount it\&.
 184 .RE
 185 .PP
 186 UMOUNT\-LOCKFILE
 187 .RS 4
 188
 189 If UMOUNT is set, it require a lockfile outside of the mount point to prevent race\&.
 190 .RE
 191 .PP
 192 UMOUNT\-IDLE
 193 .RS 4
 194
 195 If set, the changer try to umount the removable disk when it is not in use\&. The umount\-idle value is a delay in second to wait before doing the umount\&. A value >= 1 is required to prevent useless mount/umount\&.
 196 .RE
 197 .SS "chg\-disk (old)"
 198 .nf
 199 tapedev "file:/u01/vtapes"
 200 tpchanger "chg\-disk"
 201 changerfile "chg\-disk\&.conf"     # optional file
 202 .fi
 203 .PP
 204 This changer script supports sequential access to vtapes stored in directories named
 205 slotN
 206 in the directory specified by the
 207 \fItapedev\fR
 208 parameter\&. The configuration file parameter is:
 209 .sp
 210 .nf
 211 LASTSLOT=number    # The number of slots, default to tapecycle setting\&.
 212 .fi
 213 .PP
 214 This changer is not fast\-search capable\&.
 215 .SS "chg\-multi:DEVICE\-LIST"
 216 .nf
 217 tpchanger "chg\-multi:{/dev/nst0,/dev/nst1,/dev/nst2}"
 218 changerfile "chg\-multi\-state"
 219 .fi
 220 .PP
 221 This script simply round\-robins a number of distinct device names, as specified in the
 222 \fItpchanger\fR
 223 setting\&. It is useful when all volumes for a configuration have different device names \-\- for example, if you have many standalone drive\&. The
 224 \fIchangerfile\fR
 225 must exist; it is used to save the state file\&.
 226 .PP
 227 The child devices are specified using the same syntax as for the RAIT device (see
 228 \fBamanda-changers\fR(7))\&. The range specification can be especially useful here:
 229 .sp
 230 .nf
 231 tpchanger "chg\-multi:s3:mycompany\-backups/tape\-{001\&.\&.100}"
 232 .fi
 233 .PP
 234 This changer is not fast\-search capable\&.
 235 .SS "Properties"
 236 .PP
 237 FIRST\-SLOT
 238 .RS 4
 239
 240 This property gives the number of the first slot\&. The default value is "1"\&.
 241 .RE
 242 .SS "Special Operations"
 243 .PP
 244 A number of special operations are available for
 245 \fBchg\-multi\fR
 246 via
 247 \fBamtape\fR(8)
 248 subcommands\&.
 249 .PP
 250 The
 251 \fBreset\fR
 252 subcommand will change the current slot to the first available slot, but does not erase any stored state maintained by the changer\&.
 253 .PP
 254 The
 255 \fBeject\fR
 256 subcommand will eject the volume in the given drive
 257 .PP
 258 The
 259 \fBclean\fR
 260 subcommand is not yet implemented\&.
 261 .PP
 262 The
 263 \fBupdate\fR
 264 subcommand instructs the changer to update its state database\&. Given no arguments, the changer will scan all available slots, loading each tape and reading its label\&. Especially for large libraries, this can take a long time\&. If only a few slots have changed, they can be listed on the command line:
 265 .sp
 266 .nf
 267 amtape CONFIG update 1\-3,9
 268 .fi
 269 In this case, the changer will only scan the stated slots\&. Finally, the changer will not scan at all if it is given the tape label for the slot:
 270 .sp
 271 .nf
 272 amtape CONFIG update 2=DailySet\-028
 273 .fi
 274 In this case, the changer updates its state to indicate that
 275 DailySet\-028
 276 is in slot 2, without trying to load the tape\&.
 277 .sp
 278 .nf
 279 amtape CONFIG update 1\-3,9=
 280 .fi
 281 In this case, the changer marks the stated slots as an unknown state\&.
 282 .SS "chg\-multi (old)"
 283 .nf
 284 tpchanger "chg\-multi"
 285 changerfile "chg\-multi\-state"
 286 .fi
 287 .PP
 288 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
 289 \fIchangerfile\fR
 290 need not exist; it is used as a prefix for filenames of state files\&.
 291 .PP
 292 The configuration file has simple lines with a parameter and its value separated by a space\&. The # character introduces a comment\&. The configuration parameters are:
 293 .PP
 294 multieject
 295 .RS 4
 296 If this is 1, use an \'mt
 297 offline\' command to change to the next tape, or multiple such commands for
 298 skipping several tapes at a time\&.
 299 .RE
 300 .PP
 301 needeject
 302 .RS 4
 303 This option is incompatible with
 304 \'multieject\'\&. This should be 1 for changers accessed through several virtual
 305 tape devices, when the changer needs the current tape to be ejected before
 306 changing to another device\&.
 307 .RE
 308 .PP
 309 gravity
 310 .RS 4
 311 Set this to 1 if the
 312 changer/stacker is unable to loop back to the first tape after unloading the
 313 last one, or if you don\'t want amanda to go through the tape stack looking for
 314 the exact tape it wants instead of using the first acceptable one\&.
 315 .RE
 316 .PP
 317 slot X
 318 .RS 4
 319 The configuration file should list
 320 as many \'slot X\' statements as the number of slots supported by the changer or
 321 the number of separate tape drives used\&.
 322 .RE
 323 .PP
 324 This changer is not fast\-search capable\&.
 325 .SS "chg\-manual"
 326 .nf
 327 tpchanger "chg\-manual"
 328 changerfile "chg\-manual\&.conf"
 329 .fi
 330 .PP
 331 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):
 332 .sp
 333 .nf
 334 resend_mail=900       # resend mail every __ seconds
 335 timeout_mail=604800   # time out after this many seconds (default 7 days)
 336 request="[type]"      # How to request a new tape (default "tty_email")
 337   request="tty"       # Use the tty to ask the user to change tape\&.
 338                       # Can\'t be use by cron
 339   request="email"     # Send an email to ask the user to change tape\&.
 340   request="tty_email" # Use the tty if it exist or send an email\&.
 341 .fi
 342 .PP
 343 This changer is not fast\-search capable\&.
 344 .SS "chg\-zd\-mtx (old)"
 345 .nf
 346 tpchanger "chg\-zd\-mtx"
 347 changerdev "/dev/sg0"         # used with \'mtx \-f\'
 348 changerfile "chg\-zd\-mtx\&.conf"
 349 tapedev "tape:/dev/nst0"
 350 .fi
 351 .PP
 352 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
 353 \fB\-f\fR
 354 option and has subcommands like
 355 \fBstatus\fR\&. The configuration file parameters are (as listed in the script itself):
 356 .sp
 357 .nf
 358 firstslot=?                 #### First storage slot (element)
 359 lastslot=?                  #### Last storage slot (element)
 360 cleanslot=\-1                #### Slot with cleaner tape \-\- default is "\-1"
 361                             #### Set negative to indicate no cleaner available
 362 driveslot=0                 #### Drive slot number\&.  Defaults to 0
 363                             #### Use the \'Data Transfer Element\' you want
 364 autoclean=0                 #### Set to \'1\' or greater to enable
 365 autocleancount=99           #### Number of access before a clean\&.
 366 havereader=0                #### If you have a barcode reader, set to 1\&.
 367 offline_before_unload=0     #### Does your robot require an
 368                             #### \'mt offline\' before mtx unload?
 369 poll_drive_ready=NN         #### Time (seconds) between tests to see if
 370                             #### the tape drive has gone ready (default: 3)\&.
 371 max_drive_wait=NN           #### Maximum time (seconds) to wait for the
 372                             #### tape drive to become ready (default: 120)\&.
 373 initial_poll_delay=NN       #### initial delay after load before polling for
 374                             #### readiness
 375 slotinfofile=FILENAME       #### record slot information to this file, in
 376                             #### the line\-based format "SLOT LABEL\en"
 377 .fi
 378 .PP
 379 This changer is fast\-search capable if and only if
 380 \fBhavereader\fR
 381 is true\&.
 382 .SS "chg\-rait:{CHILD1,CHILD2,\&.\&.}"
 383 .nf
 384 define changer vtape {
 385     tpcanger "chg\-disk:/path/to/vtape"
 386 }
 387 define changer robot {
 388     tpchanger "chg\-robot:/dev/sg0"
 389     tapedev "tape:/dev/nst0"
 390 }
 391 tpchanger "chg\-rait:{vtape,robot}"
 392 .fi
 393 .PP
 394 This changer script constructs RAIT devices out of the devices provided by several "sub\-changers"\&. The sub\-changers are specified using the same shell\-like syntax as the RAIT device (see
 395 \fBamanda-devices\fR(7))\&.
 396 .PP
 397 Chg\-rait does not require that all of the child changers have the same slot names: compound slot names are created by combining the slot names supplied by the child changers using the same shell\-like syntax\&. For example, if the child changers return slots "top", "strange", and "3", then the RAIT changer will return "{top,strange,3}"\&. This makes it possible to, for example, mirror data on tapes in slots 1\-10 to tapes in slots 11\-20 of the same robot, using two
 398 \fBchg\-zd\-mtx\fR
 399 child changers (and, naturally, two tape drives)\&. In this arrangement, the first slot would be named
 400 {1,11}\&.
 401 .PP
 402 As a convenience to the user, the RAIT changer will also accept un\-braced slot names, and supply the same name to each child changer\&. Thus with a 4\-device RAIT changer, "17" is equivalent to "{17,17,17,17}"\&.
 403 .PP
 404 Drive names are parsed in a similar fashion, for operations that take drive names (clean and eject)\&.
 405 .PP
 406 This changer is fast\-search capable only if all of its child changers are fast\-search capable\&.
 407 .if n \{\
 408 .sp
 409 .\}
 410 .RS 4
 411 .it 1 an-trap
 412 .nr an-no-space-flag 1
 413 .nr an-break-flag 1
 414 .br
 415 .ps +1
 416 \fBNote\fR
 417 .ps -1
 418 .br
 419 The old chg\-rait script is no longer supported nor shipped with Amanda, although the old script will continue to function via \fBchg\-compat\fR, giving users time to upgrade their configuration\&.
 420 .sp .5v
 421 .RE
 422 .SS "chg\-null:"
 423 .nf
 424 tpchanger "chg\-null:"
 425 .fi
 426 .PP
 427 This changer always provides the device "null:"\&. It is sometimes useful in conjunction with
 428 \fBchg\-rait:\fR\&.
 429 .SS "chg\-robot:DEVICE"
 430 .nf
 431 define changer robot {
 432     tpchanger "chg\-robot:/dev/sg0"
 433     property "tape\-device" "0=tape:/dev/rmt/0" "1=tape:/dev/rmt/1"
 434     property "eject\-before\-unload" "yes"
 435     property "use\-slots" "1\-5,11\-20"
 436 }
 437 tpchanger "robot"
 438 .fi
 439 .PP
 440 This changer drives a robotic tape library using the operating system\'s
 441 \fBmtx\fR
 442 command\&. It replaces the ancient
 443 \fBchg\-zd\-mtx\fR
 444 script\&. The changer uses all of the information available to operate as efficiently as possible\&. Even without a barcode reader, the changer can usually load a tape immediately, without resorting to a sequential scan of many tapes\&. It is capable of sharing state across multiple Amanda configurations, avoiding conflicts and optimally tracking the contents of the library\&.
 445 .PP
 446 This changer does not accept a
 447 \fBchangerdev\fR
 448 parameter, but the
 449 \fBchangerfile\fR
 450 parameter can be used to specify a filename at which it should store its state\&. Ordinarily, this state is stored in a file named after the changer device under
 451 \fI$localstatedir/amanda\fR, e\&.g\&.,
 452 \fB/var/amanda/chg\-robot\-dev\-sg0\fR\&. There should be a single such statefile for each distinct tape library attached to the Amanda server, even if multiple Amanda configurations reference that library\&.
 453 .PP
 454 With a barcode reader present, it is possible for
 455 \fBchg\-robot\fR
 456 to track the state of the library reliably, even recognizing tapes that are removed and later re\-inserted (by remembering their barcodes)\&. Without barcodes, the changer can still remember the slot in which it last saw the tape with a particular label, although this information can become stale if the tapes are rearranged by an operator\&. In any case, the changer will never "hunt" for a tape by repeatedly loading slots and checking labels\&. If the changer\'s state is inaccurate, use the
 457 \fBamtape\fR(8)
 458 subcommand
 459 \fBupdate\fR\&.
 460 .PP
 461 This changer is fast\-search capable even without a barcode reader\&. For such libraries, it is the responsibility of the operator to
 462 \fBupdate\fR
 463 the changer when tapes are added to or removed from the library\&.
 464 .PP
 465 There is a shell script in the
 466 contrib/
 467 directory of Amanda\'s source distribution which can help you convert a
 468 \fBchg\-zd\-mtx\fR
 469 configuration into a
 470 \fBchg\-robot\fR
 471 configuration\&. Just give it your Amanda configuration name:
 472 .sp
 473 .nf
 474   sh contrib/convert\-zd\-mtx\-to\-robot\&.sh $config
 475 .fi
 476 The script can be downloaded at
 477 http://github\&.com/zmanda/amanda/raw/master/contrib/convert\-zd\-mtx\-to\-robot\&.sh
 478 .SS "Special Operations"
 479 .PP
 480 A number of special operations are available for
 481 \fBchg\-robot\fR
 482 via
 483 \fBamtape\fR(8)
 484 subcommands\&.
 485 .PP
 486 The
 487 \fBreset\fR
 488 subcommand will change the current slot to the first available slot, but does not erase any stored state maintained by the changer\&.
 489 .PP
 490 The
 491 \fBeject\fR
 492 subcommand will unload the volume in the given drive, ejecting first if the changer properties dictate\&. Note that, despite the subcommand name, the changer attempts to avoid the state where a volume has been ejected from the drive but not unloaded back to a storage slot\&.
 493 .PP
 494 The
 495 \fBclean\fR
 496 subcommand is not yet implemented\&.
 497 .PP
 498 The
 499 \fBupdate\fR
 500 subcommand instructs the changer to update its state database\&. Given no arguments, the changer will scan all available slots, loading each tape and reading its label\&. Especially for large libraries, this can take a long time\&. If only a few slots have changed, they can be listed on the command line:
 501 .sp
 502 .nf
 503 amtape CONFIG update 1\-3,9
 504 .fi
 505 In this case, the changer will only scan the stated slots\&. Finally, the changer will not scan at all if it is given the tape label for the slot:
 506 .sp
 507 .nf
 508 amtape CONFIG update 2=DailySet\-028
 509 .fi
 510 In this case, the changer updates its state to indicate that
 511 DailySet\-028
 512 is in slot 2, without trying to load the tape\&.
 513 .sp
 514 .nf
 515 amtape CONFIG update 1\-3,9=
 516 .fi
 517 In this case, the changer marks the stated slots as an unknown state\&.
 518 .SS "Properties"
 519 .PP
 520 DRIVE\-CHOICE
 521 .RS 4
 522
 523 This property controls the algorithm used to select a drive in which to load a
 524 tape\&.  If set to the default ("lru"), the changer attempts to use the least
 525 recently used drive, resulting in a round\-robin behavior\&.  The "firstavail"
 526 algorithm selects the first available drive, thus preferring the first drive
 527 specified via the TAPE\-DEVICE property\&.
 528 .RE
 529 .PP
 530 EJECT\-BEFORE\-UNLOAD
 531 .RS 4
 532
 533 Set this boolean property to true if the library requires an
 534 \fBoffline\fR operation be performed on the tape drive before it
 535 can be unloaded\&.  If set, then \fBmt\fR will be invoked to
 536 perform this operation\&.  Most libraries do not require this workaround\&.
 537 .RE
 538 .PP
 539 EJECT\-DELAY
 540 .RS 4
 541
 542 This is the time between ejecting a tape and unloading the volume to a storage slot, and
 543 defaults to 0 seconds\&.  It is only used if EJECT\-BEFORE\-UNLOAD is true\&.  See "Timing", below\&.
 544 .RE
 545 .PP
 546 FAST\-SEARCH
 547 .RS 4
 548
 549 This boolean property indicates whether the changer advertises the ability to find
 550 volumes without sequential scanning\&.  The traditional taperscan algorithm alters its
 551 behavior based on this flag, so it is sometimes necessary to adjust it, although the
 552 changer will always search for a desired tape using the most efficient means
 553 available\&.  The default value is true\&.
 554 .RE
 555 .PP
 556 IGNORE\-BARCODES
 557 .RS 4
 558
 559 If this boolean property is true, then chg\-robot will ignore any barcode information
 560 that the library provides\&.  This property is probably only useful when the library
 561 returns incorrect barcodes, for example due to a malfunction in the barcode reader\&.
 562 .RE
 563 .PP
 564 LOAD\-POLL
 565 .RS 4
 566 This property specifies the timing of Amanda\'s polling for the tape drive to be ready after loading a new tape\&. See "Timing", below\&.
 567 .sp
 568 The script "polls" by trying to open the tape device repeatedly until no error is encountered\&. The property specifies the time to wait before the first poll (D), the frequency at which to poll and retry on errors (P); and the time after which it should give up (U)\&. The format is
 569 .sp
 570 .nf
 571 "D [poll P [until U]]"
 572 .fi
 573 For a simple delay with no polling, use e\&.g\&.,
 574 .sp
 575 .nf
 576 property "load\-poll" "13s"
 577 .fi
 578 To delay and then poll, use e\&.g\&.,
 579 .sp
 580 .nf
 581 property "load\-poll" "13s poll 5s"
 582 .fi
 583 and to add a maximum total time, use e\&.g\&.,
 584 .sp
 585 .nf
 586 property "load\-poll" "0s poll 5s until 2m"
 587 .fi
 588 The default value is
 589 \fB"0s poll 3s until 2m"\fR\&.
 590 .RE
 591 .PP
 592 MTX
 593 .RS 4
 594
 595 The path to the \'mtx\' binary\&.  The default value is defined at compile time\&.
 596 .RE
 597 .PP
 598 STATUS\-INTERVAL
 599 .RS 4
 600
 601 This is the minimum time between invocations of \fBmtx status\fR
 602 to determine the state of the changer library\&.  The default value, 2 seconds,
 603 avoids back\-to\-back status invocations but ensures that the metadata is up to
 604 date\&.  For operating systems or libraries where the \fBmtx
 605 status\fR takes a considerable time to complete, this value should be
 606 increased\&.  See "Timing", below\&.
 607 .RE
 608 .PP
 609 TAPE\-DEVICE
 610 .RS 4
 611
 612 This property describes the correspondance of drive numbers in the library to
 613 Amanda devices, in the format \fIDRIVE=DEVICE\fR\&.  The property
 614 can be specified multiple times to describe multiple devices\&.  The device will
 615 usually be a tape device name starting with \fBtape:\fR, but may
 616 also refer to a device alias (see \fBamanda-devices\fR(7))\&. As
 617 a shortcut, if the \fBtapedev\fR parameter is specified in the
 618 changer definition, then it is assumed to be the device name for drive 0\&.
 619 .RE
 620 .PP
 621 UNLOAD\-DELAY
 622 .RS 4
 623
 624 This specifies the minimum time between an unload operation any any subsequent
 625 operation\&.  The default value is 0 seconds\&.  See "Timing", below\&.
 626 .RE
 627 .PP
 628 USE\-SLOTS
 629 .RS 4
 630
 631 This property, if specifies, enumerates the slots to which this changer should
 632 limit itself\&.  The slots are specified as a comma\-separated list of ranges,
 633 e\&.g\&., "1\-5,11\-15,19,22"\&.  The property can be specified more than once, and
 634 the resulting sets will be combined\&.  The changer will refuse to load tapes
 635 not found in these slots, except for import/export purposes\&.
 636 .RE
 637 .SS "Timing"
 638 .PP
 639 Tape libraries are fickle, and in many cases will report that an operation is complete when it is still in progress\&. Chg\-robot takes several timing\-related properties to accomodate such behavior\&.
 640 .PP
 641 A typical sequence of operations performed during a load are: get library status, eject a tape, unload the tape back to a storage slot, load a new tape, and read the label on that tape to ensure the drive is ready\&.
 642 .PP
 643 On most systems, the library status check is nearly instantaneous \-\- the changer library provides its cached state to the host without initiating any robot motion\&. In order to keep its metadata up\-to\-date, chg\-robot runs this command very frequently, but this frequency can be reduced (at the cost of potentially stale metadata) by setting the STATUS\-INTERVAL property to a larger value\&.
 644 .PP
 645 Some tape libraries do not integrate the eject operation (performed by the embedded tape drive) with the unload operation (performed by the library robot), and can actually cause physical damage by attempting to remove the tape before the ejection is complete\&. For such changers, set the EJECT\-DELAY property to allow enough time for the eject to complete\&.
 646 .PP
 647 Once a tape is unloaded, if the library needs time to "quiesce" before processing another command, add that time to the UNLOAD\-DELAY parameter\&. No other operations will be performed on the library until this delay has elapsed\&.
 648 .PP
 649 Once a tape has been loaded, chg\-robot waits until the drive is ready before allowing Amanda to use the volume, as described for LOAD\-POLL, above\&.
 650 .PP
 651 Each of the times specified in these properties may be given as integers with the optional suffix
 652 \fBs\fR
 653 for seconds (the default) or
 654 \fBm\fR
 655 for minutes\&.
 656 .SS "chg\-ndmp:HOST[:PORT]@SCSIDEV"
 657 .nf
 658     tpchanger "chg\-ndmp:filer\&.company\&.com@/dev/sg0"
 659     property        "tape\-device" "0=ndmp:filer\&.company\&.com@/dev/rtape0"
 660     property append "tape\-device" "1=ndmp:filer\&.company\&.com@/dev/rtape1"
 661     property "use\-slots" "1\-12"
 662     property "ndmp\-auth" "text"
 663     property "ndmp\-username" "luke"
 664     property "ndmp\-password" "leia"
 665 .fi
 666 .PP
 667 This changer is very similar to
 668 \fBchg\-robot\fR, but controls a tape changer on an NDMP server instead of a local device\&. The
 669 \fBHOST\fR
 670 in the
 671 \fBtpchanger\fR
 672 should be the hostname of the NDMP server\&. The
 673 \fBPORT\fR
 674 is optional\&. The
 675 \fBSCSIDEV\fR
 676 should specify the SCSI device on the NDMP server which controls the changer\&. The format of this parameter is implementation\-specific\&.
 677 .PP
 678 The appropriate authentication properties will be automatically set on any devices created by this changer\&.
 679 .SS "Properties"
 680 .PP
 681 This changer supports all of the properties supported by
 682 \fBchg\-robot\fR, although the value of
 683 \fBMTX\fR
 684 is ignored\&. The following properties are also recognized:
 685 .PP
 686 NDMP_AUTH
 687 .RS 4
 688
 689 Authentication method to use to connect to the NDMP server\&.  One of
 690 "md5" (default), "text", "none" (for an empty authentication attempt) or "void" (for
 691 no authentication attempt at all)\&.
 692 .RE
 693 .PP
 694 NDMP\-PASSWORD
 695 .RS 4
 696
 697 The password for the NDMP server\&.
 698 .RE
 699 .PP
 700 NDMP\-USERNAME
 701 .RS 4
 702
 703 The username for the NDMP server\&.
 704 .RE
 705 .PP
 706 VERBOSE
 707 .RS 4
 708
 709 If true, enables the NDMJOB library\'s verbose (packet\-level) debugging\&.
 710 .RE
 711 .SS "Unmaintained Changers"
 712 .PP
 713 Amanda has many other changer scripts and programs beyond those described here (see the
 714 changer\-src/
 715 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\&.
 716 .SH "SEE ALSO"
 717 .PP
 718 \fBamanda\fR(8),
 719 \fBamanda.conf\fR(5),
 720 \fBamanda-devices\fR(7)
 721 .PP
 722 The Amanda Wiki:
 723 : http://wiki.zmanda.com/
 724 .SH "AUTHOR"
 725 .PP
 726 \fBDustin J\&. Mitchell\fR <\&dustin@zmanda\&.com\&>
 727 .RS 4
 728 Zmanda, Inc\&. (http://www\&.zmanda\&.com)
 729 .RE