X-Git-Url: https://git.gag.com/?a=blobdiff_plain;f=man%2Famanda-changers.7;h=05b0712cb7b9e8bc4aa9a2fb6a58d302519ae2ad;hb=HEAD;hp=503089e049808cc5d9d6df295ad8a5e9dd238e35;hpb=fd48f3e498442f0cbff5f3606c7c403d0566150e;p=debian%2Famanda diff --git a/man/amanda-changers.7 b/man/amanda-changers.7 index 503089e..05b0712 100644 --- a/man/amanda-changers.7 +++ b/man/amanda-changers.7 @@ -1,13 +1,22 @@ '\" t .\" Title: amanda-changers .\" Author: Dustin J. Mitchell -.\" Generator: DocBook XSL Stylesheets vsnapshot_8273 -.\" Date: 06/01/2010 +.\" Generator: DocBook XSL Stylesheets v1.76.1 +.\" Date: 01/10/2013 .\" Manual: Miscellanea -.\" Source: Amanda 3.1.0 +.\" Source: Amanda 3.3.3 .\" Language: English .\" -.TH "AMANDA\-CHANGERS" "7" "06/01/2010" "Amanda 3\&.1\&.0" "Miscellanea" +.TH "AMANDA\-CHANGERS" "7" "01/10/2013" "Amanda 3\&.3\&.3" "Miscellanea" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- @@ -30,7 +39,7 @@ overview of the API, and does not address details that are only of concern to de 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 chg\-compat\&. .PP -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\&. +The Changer API strives to treat all changers identically, so that Amanda\*(Aqs 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\&. .SH "SPECIFYING CHANGERS" .PP Changer specifications are strings like @@ -68,7 +77,7 @@ define changer hp\-robot { tapedev "chg\-robot:/dev/sg1" property "tape\-device" "0=tape:/dev/nst0" property append "tape\-device" "1=tape:/dev/nst1" - device_property "BLOCK_SIZE" "512k" + device\-property "BLOCK_SIZE" "512k" } # \&.\&.\&. tapedev "hp\-robot" @@ -82,7 +91,7 @@ example, above\&. .PP Devices, too, can take properties to control their behavior (see \fBamanda-devices\fR(7))\&. Device properties can come from four places: implicit device properties (from tapetype parameters), global device properties (from global -\fIdevice_property\fR +\fIdevice\-property\fR parameters), properties in device definitions, and properties in changer definitions\&. Properties are applied in this order, with later properties taking priority\&. .PP There are only three implicit properties: @@ -103,9 +112,51 @@ Global device properties always apply\&. If the changer specifies a device by al .SH "CHANGER DRIVERS" .PP 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\&. +.SS "chg\-aggregate:changer (new)" +.nf +define changer robot0 { + tpchanger "chg\-robot:/dev/sg0" + property "tape\-device" "0=tape:/dev/rmt/0" "1=tape:/dev/rmt/1" +} +define changer robot1 { + tpchanger "chg\-robot:/dev/sg1" + property "tape\-device" "0=tape:/dev/rmt/2" "1=tape:/dev/rmt/3" +} +define changer single { + tpchanger "chg\-single:/dev/rmt/4" +} +define changer aggregate { + tpchanger "chg\-aggregate:{robot0,robot1,single}" + property "state\-filename" "/etc/amanda/CONF/aggregate\&.state" + +} +tpchanger "aggregate" +.fi +.PP +This changer driver allow to use two or more changers or standalone drive in sequence\&. +.SS "Properties" +.PP +LOCK\-TIMEOUT +.RS 4 + +The time in seconds amanda wait to lock the statefile (default:1000) +.RE +.PP +STATE_FILENAME +.RS 4 + +The name of the state file (default: "$CONFIG_DIR/$changer_name\&.state"\&. +.RE .SS "chg\-disk:VTAPEROOT (new)" .nf -tpchanger "chg\-disk:/u01/vtapes" +tpchanger "chg\-disk:/var/mnt/vtapes" +property "num\-slot" "10" +property "auto\-create\-slot" "yes" +property "removable" "yes" +property "mount" "yes" +property "umount" "yes" +property "umount\-lockfile" "/etc/amanda/conf/vtapes\-lock" +property "umount\-idle" "1" .fi .PP This changer driver replaces the old @@ -118,6 +169,59 @@ The current slot can be accessed using the device name file:VTAPEROOT\&. This is useful for the \fBamrestore\fR(8) command line\&. +.SS "Properties" +.PP +AUTO\-CREATE\-SLOT +.RS 4 + +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\&. +.RE +.PP +LOCK\-TIMEOUT +.RS 4 + +The time in seconds amanda wait to lock the statefile (default:1000) +.RE +.PP +MOUNT +.RS 4 + +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\&. +.RE +.PP +NUM\-SLOT +.RS 4 + +The minimum number of slots in the changer, where the first slot is slot1\&. If additional slot directories exist, they will also be used\&. +.RE +.PP +REMOVABLE +.RS 4 + +If this property is true, then the changer will verify that the changer +directory (e\&.g\&., /var/mnt/vtapes) is on a different +filesystem from its parent directory (e\&.g\&., /var/mnt)\&. +This is useful for removable disks, as it will prevent Amanda from creating +slot directories when the removable disk is not mounted\&. +.RE +.PP +UMOUNT +.RS 4 + +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\&. +.RE +.PP +UMOUNT\-LOCKFILE +.RS 4 + +If UMOUNT is set, it require a lockfile outside of the mount point to prevent race\&. +.RE +.PP +UMOUNT\-IDLE +.RS 4 + +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\&. +.RE .SS "chg\-disk (old)" .nf tapedev "file:/u01/vtapes" @@ -148,6 +252,13 @@ setting\&. It is useful when all volumes for a configuration have different devi \fIchangerfile\fR must exist; it is used to save the state file\&. .PP +The child devices are specified using the same syntax as for the RAIT device (see +\fBamanda-changers\fR(7))\&. The range specification can be especially useful here: +.sp +.nf +tpchanger "chg\-multi:s3:mycompany\-backups/tape\-{001\&.\&.100}" +.fi +.PP This changer is not fast\-search capable\&. .SS "Properties" .PP @@ -156,6 +267,12 @@ FIRST\-SLOT This property gives the number of the first slot\&. The default value is "1"\&. .RE +.PP +LOCK\-TIMEOUT +.RS 4 + +The time in seconds amanda wait to lock the statefile (default:1000) +.RE .SS "Special Operations" .PP A number of special operations are available for @@ -210,15 +327,15 @@ The configuration file has simple lines with a parameter and its value separated .PP multieject .RS 4 -If this is 1, use an \'mt -offline\' command to change to the next tape, or multiple such commands for +If this is 1, use an \*(Aqmt +offline\*(Aq command to change to the next tape, or multiple such commands for skipping several tapes at a time\&. .RE .PP needeject .RS 4 This option is incompatible with -\'multieject\'\&. This should be 1 for changers accessed through several virtual +\*(Aqmultieject\*(Aq\&. This should be 1 for changers accessed through several virtual tape devices, when the changer needs the current tape to be ejected before changing to another device\&. .RE @@ -227,14 +344,14 @@ gravity .RS 4 Set this to 1 if the changer/stacker is unable to loop back to the first tape after unloading the -last one, or if you don\'t want amanda to go through the tape stack looking for +last one, or if you don\*(Aqt want amanda to go through the tape stack looking for the exact tape it wants instead of using the first acceptable one\&. .RE .PP slot X .RS 4 The configuration file should list -as many \'slot X\' statements as the number of slots supported by the changer or +as many \*(Aqslot X\*(Aq statements as the number of slots supported by the changer or the number of separate tape drives used\&. .RE .PP @@ -252,7 +369,7 @@ resend_mail=900 # resend mail every __ seconds timeout_mail=604800 # time out after this many seconds (default 7 days) request="[type]" # How to request a new tape (default "tty_email") request="tty" # Use the tty to ask the user to change tape\&. - # Can\'t be use by cron + # Can\*(Aqt be use by cron request="email" # Send an email to ask the user to change tape\&. request="tty_email" # Use the tty if it exist or send an email\&. .fi @@ -261,12 +378,12 @@ This changer is not fast\-search capable\&. .SS "chg\-zd\-mtx (old)" .nf tpchanger "chg\-zd\-mtx" -changerdev "/dev/sg0" # used with \'mtx \-f\' +changerdev "/dev/sg0" # used with \*(Aqmtx \-f\*(Aq changerfile "chg\-zd\-mtx\&.conf" tapedev "tape:/dev/nst0" .fi .PP -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 +This script interfaces with a tape drive using the Zubkoff/Dandelion version of mtx\&. That\*(Aqs the version that takes a device specifier with the \fB\-f\fR option and has subcommands like \fBstatus\fR\&. The configuration file parameters are (as listed in the script itself): @@ -277,12 +394,12 @@ lastslot=? #### Last storage slot (element) cleanslot=\-1 #### Slot with cleaner tape \-\- default is "\-1" #### Set negative to indicate no cleaner available driveslot=0 #### Drive slot number\&. Defaults to 0 - #### Use the \'Data Transfer Element\' you want -autoclean=0 #### Set to \'1\' or greater to enable + #### Use the \*(AqData Transfer Element\*(Aq you want +autoclean=0 #### Set to \*(Aq1\*(Aq or greater to enable autocleancount=99 #### Number of access before a clean\&. havereader=0 #### If you have a barcode reader, set to 1\&. offline_before_unload=0 #### Does your robot require an - #### \'mt offline\' before mtx unload? + #### \*(Aqmt offline\*(Aq before mtx unload? poll_drive_ready=NN #### Time (seconds) between tests to see if #### the tape drive has gone ready (default: 3)\&. max_drive_wait=NN #### Maximum time (seconds) to wait for the @@ -299,7 +416,7 @@ is true\&. .SS "chg\-rait:{CHILD1,CHILD2,\&.\&.}" .nf define changer vtape { - tpcanger "chg\-disk:/path/to/vtape" + tpchanger "chg\-disk:/path/to/vtape" } define changer robot { tpchanger "chg\-robot:/dev/sg0" @@ -354,7 +471,7 @@ define changer robot { tpchanger "robot" .fi .PP -This changer drives a robotic tape library using the operating system\'s +This changer drives a robotic tape library using the operating system\*(Aqs \fBmtx\fR command\&. It replaces the ancient \fBchg\-zd\-mtx\fR @@ -370,7 +487,7 @@ parameter can be used to specify a filename at which it should store its state\& .PP With a barcode reader present, it is possible for \fBchg\-robot\fR -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 +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\*(Aqs state is inaccurate, use the \fBamtape\fR(8) subcommand \fBupdate\fR\&. @@ -381,7 +498,7 @@ the changer when tapes are added to or removed from the library\&. .PP There is a shell script in the contrib/ -directory of Amanda\'s source distribution which can help you convert a +directory of Amanda\*(Aqs source distribution which can help you convert a \fBchg\-zd\-mtx\fR configuration into a \fBchg\-robot\fR @@ -480,7 +597,7 @@ returns incorrect barcodes, for example due to a malfunction in the barcode read .PP LOAD\-POLL .RS 4 -This property specifies the timing of Amanda\'s polling for the tape drive to be ready after loading a new tape\&. See "Timing", below\&. +This property specifies the timing of Amanda\*(Aqs polling for the tape drive to be ready after loading a new tape\&. See "Timing", below\&. .sp 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 .sp @@ -506,10 +623,16 @@ The default value is \fB"0s poll 3s until 2m"\fR\&. .RE .PP +LOCK\-TIMEOUT +.RS 4 + +The time in seconds amanda wait to lock the statefile (default:1000) +.RE +.PP MTX .RS 4 -The path to the \'mtx\' binary\&. The default value is defined at compile time\&. +The path to the \*(Aqmtx\*(Aq binary\&. The default value is defined at compile time\&. .RE .PP STATUS\-INTERVAL @@ -619,6 +742,22 @@ NDMP\-USERNAME The username for the NDMP server\&. .RE +.PP +VERBOSE +.RS 4 + +If true, enables the NDMJOB library\*(Aqs verbose (packet\-level) debugging\&. +.RE +.SS "chg\-single:DEVICE" +.nf +tpchanger "chg\-single:tape:/dev/nst0" +.fi +.PP +This changer is for use with standalone drive, it can work with any device\&. The device (\fBtape:/dev/nst0\fR) must be set in the tpchanger definition\&. +.PP +The +\fBchg\-single\fR +changer has no property\&. .SS "Unmaintained Changers" .PP Amanda has many other changer scripts and programs beyond those described here (see the