+'\" t
.\" Title: amanda-devices
.\" Author: Ian Turner <ian@zmanda.com>
-.\" Generator: DocBook XSL Stylesheets v1.74.0 <http://docbook.sf.net/>
-.\" Date: 01/22/2009
+.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
+.\" Date: 01/10/2013
.\" Manual: Miscellanea
-.\" Source: Amanda 2.6.1
+.\" Source: Amanda 3.3.3
.\" Language: English
.\"
-.TH "AMANDA\-DEVICES" "7" "01/22/2009" "Amanda 2\&.6\&.1" "Miscellanea"
+.TH "AMANDA\-DEVICES" "7" "01/10/2013" "Amanda 3\&.3\&.3" "Miscellanea"
.\" -----------------------------------------------------------------
-.\" * (re)Define some macros
+.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.\" toupper - uppercase a string (locale-aware)
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.de toupper
-.tr aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ
-\\$*
-.tr aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz
-..
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.\" SH-xref - format a cross-reference to an SH section
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.de SH-xref
-.ie n \{\
-.\}
-.toupper \\$*
-.el \{\
-\\$*
-.\}
-..
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.\" SH - level-one heading that works better for non-TTY output
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.de1 SH
-.\" put an extra blank line of space above the head in non-TTY output
-.if t \{\
-.sp 1
-.\}
-.sp \\n[PD]u
-.nr an-level 1
-.set-an-margin
-.nr an-prevailing-indent \\n[IN]
-.fi
-.in \\n[an-margin]u
-.ti 0
-.HTML-TAG ".NH \\n[an-level]"
-.it 1 an-trap
-.nr an-no-space-flag 1
-.nr an-break-flag 1
-\." make the size of the head bigger
-.ps +3
-.ft B
-.ne (2v + 1u)
-.ie n \{\
-.\" if n (TTY output), use uppercase
-.toupper \\$*
-.\}
-.el \{\
-.nr an-break-flag 0
-.\" if not n (not TTY), use normal case (not uppercase)
-\\$1
-.in \\n[an-margin]u
-.ti 0
-.\" if not n (not TTY), put a border/line under subheading
-.sp -.6
-\l'\n(.lu'
-.\}
-..
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.\" SS - level-two heading that works better for non-TTY output
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.de1 SS
-.sp \\n[PD]u
-.nr an-level 1
-.set-an-margin
-.nr an-prevailing-indent \\n[IN]
-.fi
-.in \\n[IN]u
-.ti \\n[SN]u
-.it 1 an-trap
-.nr an-no-space-flag 1
-.nr an-break-flag 1
-.ps \\n[PS-SS]u
-\." make the size of the head bigger
-.ps +2
-.ft B
-.ne (2v + 1u)
-.if \\n[.$] \&\\$*
-..
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.\" BB/BE - put background/screen (filled box) around block of text
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.de BB
-.if t \{\
-.sp -.5
-.br
-.in +2n
-.ll -2n
-.gcolor red
-.di BX
-.\}
-..
-.de EB
-.if t \{\
-.if "\\$2"adjust-for-leading-newline" \{\
-.sp -1
-.\}
-.br
-.di
-.in
-.ll
-.gcolor
-.nr BW \\n(.lu-\\n(.i
-.nr BH \\n(dn+.5v
-.ne \\n(BHu+.5v
-.ie "\\$2"adjust-for-leading-newline" \{\
-\M[\\$1]\h'1n'\v'+.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
-.\}
-.el \{\
-\M[\\$1]\h'1n'\v'-.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
-.\}
-.in 0
-.sp -.5v
-.nf
-.BX
-.in
-.sp .5v
-.fi
-.\}
-..
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.\" BM/EM - put colored marker in margin next to block of text
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.de BM
-.if t \{\
-.br
-.ll -2n
-.gcolor red
-.di BX
-.\}
-..
-.de EM
-.if t \{\
-.br
-.di
-.ll
-.gcolor
-.nr BH \\n(dn
-.ne \\n(BHu
-\M[\\$1]\D'P -.75n 0 0 \\n(BHu -(\\n[.i]u - \\n(INu - .75n) 0 0 -\\n(BHu'\M[]
-.in 0
-.nf
-.BX
-.in
-.fi
-.\}
-..
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
-.SH "Name"
+.SH "NAME"
amanda-devices \- Configuring and Using Amanda Devices
.SH "DESCRIPTION"
.PP
\fINODE\fR
provides further information to that driver\&. The syntax for each device driver is given in the corresponding section below\&.
.PP
-Devices are described in
+Devices can be described in
\fBamanda.conf\fR(5)
with "device" sections, e\&.g\&.,
.sp
.nf
define device top_drive {
tapedev "tape:/dev/nst0"
- device_property "BLOCK_SIZE" "131072"
+ device\-property "BLOCK_SIZE" "131072"
}
.fi
-A device defininition creates a device "alias", in this case named
+Such a device defininition creates a device "alias", in this case named
\fItop_drive\fR, which can then be named in the global
\fItapedev\fR
+or
+\fItpchanger\fR
parameter:
.sp
.nf
tapedev "file:/amdisks"
}
.fi
+Note that, in both cases, the specified devices are actually accessed through the
+\fIchg\-single\fR
+changer driver; see
+\fBamanda-changers\fR(7)
+for more information\&.
+.PP
Device properties specified outside of any device definition apply to all devices\&. This syntax is provided mainly for backward compatibility, and for simple Amanda configurations\&. Note that there is no way to provide properties specific to a device without defining a device alias\&.
.PP
See
+\fBamanda-changers\fR(7)
+for details on how devices are configured, and in particular on how device properties are specified\&. See
\fBamanda.conf\fR(5)
-for more information on Amanda configuration\&.
-.SH "DEVICES"
-.PP
-This section lists the device 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 "Null Device"
-.nf
-tapedev "null:"
-.fi
-.PP
-The null device driver only supports writing, and discards all data\&. It is generally only useful for testing purposes\&.
-.SS "RAIT Device"
-.nf
-tapedev "rait:tape:/dev/rmt/tps0d{4,5,6}n"
-.fi
-.PP
-The RAIT device driver mirrors or stripes data over multiple "child" devices\&. The child devices are specified using a shell\-like syntax, where alternatives are enclosed in braces and separated by commas\&.
-.PP
-With two child devices, the RAIT device driver mirrors data such that the two devices contain identical data and can be used singly for recovery\&. With more than two devices, the RAIT device "stripes" data across all but one device and writes a parity block to the final device, usable for data recovery in the event of a device or volume failure\&. The RAIT device scales its blocksize as necessary to match the number of children that will be used to store data\&.
-.PP
-When a child device is known to have failed, the RAIT device should be reconfigured to replace that device with the text "ERROR", e\&.g\&.,
+for more information on Amanda configuration in general\&.
+.if n \{\
.sp
-.nf
-tapedev "rait:{tape:/dev/st0,ERROR,tape:/dev/st2}"
-.fi
-This will cause the RAIT device to start up in degraded mode, reconstructing the data from the missing device\&.
-.PP
-Like ordinary RAID drivers, the RAIT device driver can automatically enter degraded mode when one of its child devices fails\&. However, the RAIT device cannot automatically recover from any write error nor write any data in degraded mode\&. When reading, certain errors may be fatal (rather than causing degraded mode)\&. And in any case, labels on all volumes must initially match (labeled or otherwise)\&. If you have lost one volume from a set, explicitly start the device in degraded mode as described above\&.
-.SS "Child Device Block Sizes"
-.PP
-The RAIT device driver requires that all of its child devices use the same block size\&. If no block sizes are specified, the driver selects the block size closest to 32k that is within the MIN_BLOCK_SIZE \- MAX_BLOCK_SIZE range of all child devices, and calculates its own blocksize according to the formula
-\fIrait_blocksize = child_blocksize * (num_children \- 1)\fR\&. If a block size is specified for the RAIT device, then it calculates its child block sizes according to the formula
-\fIchild_blocksize = rait_blocksize / (num_children \- 1)\fR\&. Either way, it sets the BLOCK_SIZE property of each child device accordingly\&.
-.SS "S3 Device"
-.nf
-tapedev "s3:foocorp\-backups/DailySet1\-"
-device_property "S3_ACCESS_KEY" "MYACCESSKEY"
-device_property "S3_SECRET_KEY" "MYSECRETKEY"
-.fi
-.PP
-The S3 device driver uploads data to the Amazon S3 "storage cloud"\&. Its device name is a slash\-sparated combination of bucket name and prefix: "s3:BUCKET/PREFIX"\&. Since buckets must be unique across all Amazon S3 users, and since the number of buckets allowed to each user is limited, the driver can store multiple Amanda volumes in a single S3 bucket, distinguished by prefix\&. The prefix and slash can be omitted if they are not needed: "s3:BUCKET"\&.
-.PP
-The access and secret keys used to authenticate to Amazon S3 are provided as properties\&.
-.PP
-The S3 device driver stores each block in a distinct S3 object\&. Due to high HTTP overhead for each request, use of larger than normal block sizes (> 1 megabyte) is reccomended with the S3 device\&.
-.PP
-You can control where your data is physically stored by Amazon S3 using a location constraint\&. Setting this affects can affect both billing and legal concerns, so you are encouraged to consult Amazon\'s documentation for details\&.
-.PP
-To control location constraints, set the S3_BUCKET_LOCATION property\&. Currently, there are two valid settings: "" (any location) and "EU" (Europe)\&. If the S3_BUCKET_LOCATION is set, Amanda will check to make sure that the setting agrees with the constraint currently on the bucket\&.
-.SS "Tape Device"
-.nf
-tapedev "tape:/dev/nst0"
-.fi
-.PP
-The tape device driver interacts with a tape drive\&. The device uses the operating system\'s built\-in tape support, which is generally similar to that available via the command\-line utilities dd(1) and mt(1)\&.
-.PP
-The tape device name should specify a path to the operating system\'s device file\&.
-.SS "VFS Device"
-.nf
-tapedev "file:/path/to/vtape"
-.fi
-.PP
-The VFS device driver stores data on a UNIX filesystem\&. Note that although one typically uses the VFS device driver to store data on hard disks, the driver does not interface with any hardware on a block level\&.
+.\}
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBNote\fR
+.ps -1
+.br
.PP
-The device name specifies a path to a directory which must exist and contain a "data/" subdirectory\&. Each tape file is stored as a distinct file in this directory, the name of which reflects the Amanda header in the tape file\&. Block boundaries are not maintained: the driver supports reads of arbitrary size, regardless of the blocksize used to write the data\&.
+There is no way to reset a device property to its default value\&.
+.sp .5v
+.RE
.SH "PROPERTIES"
.PP
Device drivers use
\fIproperties\fR
-as a generic means to interact with other parts of Amanda\&. Some properties are set by the device driver and used by Amanda to determine how its devices should be used\&. Other properties can be set by Amanda or by the user to influence the driver\'s behavior\&. Properties are set for a particular device, so that if you have two tape devices, they will not share property values\&.
+as a generic means to interact with other parts of Amanda\&. Some properties are set by the device driver and used by Amanda to determine how its devices should be used\&. Other properties can be set by Amanda or by the user to influence the driver\*(Aqs behavior\&. Properties are set for a particular device, so that if you have two tape devices, they will not share property values\&.
.PP
Properties are specified in
\fIamanda\&.conf\fR
parameter\&. The syntax looks like this:
.sp
.nf
-device_property "FROBNICATOR_PATH" "/var/frobd/state"
-device_property "BYTES_PER_FORTNIGHT" "128k"
-device_property "USE_QUBITS" "no"
+device\-property "FROBNICATOR_PATH" "/var/frobd/state"
+device\-property "BYTES_PER_FORTNIGHT" "128k"
+device\-property "USE_QUBITS" "no"
.fi
.PP
-Both the property name and the property value are always quoted\&. String values are given as simple strings, like FROBNICATOR_PATH in the example above\&. Integer values can be specified with any of the suffixes given in the "VALUE SUFFIXES" section of
-\fBamanda.conf\fR(5), like BYTES_PER_FORTNIGHT, above\&. Boolean values can be specified as any of "true", "yes", "1", "0", "no", "false", like USE_QUBITS, above\&. Some properties have special formats, as described below\&.
+Both the property name and the property value are always quoted\&. Property names, like Amanda configuration parameters, are not case\-sensitive, and
+\-
+(dash) and
+_
+(underscore) may be used interchangeably\&. String values are given as simple strings, like FROBNICATOR_PATH in the example above\&. Integer values can be specified with any of the suffixes given in the "VALUE SUFFIXES" section of
+\fBamanda.conf\fR(5), like BYTES_PER_FORTNIGHT, above\&. Boolean values can be specified using the same names as in
+\fBamanda.conf\fR(5), like USE_QUBITS, above\&. Some properties have special formats, as described below\&.
.PP
Some properties are set based on other configuration values, such as tapetype parameters\&. These special cases are detailed under the appropriate property, below\&.
.PP
.sp -1
.IP " 2." 4.2
.\}
-Device properties from any device_property configuration parameters are set, in the order they appear in the configuration file\&.
+Device properties from any device\-property configuration parameters are set, in the order they appear in the configuration file\&.
.RE
.PP
Properties described as read\-only are not accessible to users\&. They are listed here for completeness\&.
(read\-only) This property contains the full canonical name for this device\&. This name may not be the same as the user\-supplied name, but is a valid name by which to access this device\&.
.RE
.PP
+COMMENT
+.RS 4
+
+ (read\-write) This string property is entirely for the user\*(Aqs convenience\&. It is supported by all devices, but no device interprets its value in any way\&.
+.RE
+.PP
COMPRESSION
.RS 4
(read\-only) This property indicates the level of concurrent access that this device supports\&.
.RE
.PP
-FREE_SPACE
+FULL_DELETION
+.RS 4
+
+ (read\-only) This property indicates whether the device supports erasing the entire volume\&. Aside from S3 and VFS, most devices cannot support this feature\&.
+.RE
+.PP
+LEOM
.RS 4
- (read\-only) This property gives the amount of free space available on the current volume, if known\&. This is often an estimate; for example, tape devices can only estimate the amount of tape left on a spool\&.
+(read\-write) If this property is true, then the device can detect an EOM condition before actually running out of space, allowing Amanda to forgo caching parts while writing\&. For some devices, it is necessary to override the conservative default value of this property\&.
.RE
.PP
MAX_BLOCK_SIZE
(read\-write) On devices that support it, this property will limit the total amount of data written to a volume; attempts to write beyond this point will cause the device to simulate "out of space\&." Zero means no limit\&. The tapetype parameter \fIlength\fR sets this property\&.
.RE
.PP
+ENFORCE_MAX_VOLUME_USAGE
+.RS 4
+
+ (read\-write) If this property is false, limit set by MAX_VOLUME_USAGE property (and thus the tapetype LENGTH parameter) will not be verified while writing to device, allowing the volume to expand without limit\&. If this property is true, then MAX_VOLUME_USAGE willbe enforced, limiting the total size of the volume\&. This property is not available on all devices; see below\&.
+.RE
+.PP
PARTIAL_DELETION
.RS 4
- (read\-only) This property indicates whether the device supports deletion of specific files\&. Aside from linear tapes, most devices can support this feature\&. It is currently unused by Amanda\&.
+ (read\-only) This property indicates whether the device supports deletion of specific files\&. Aside from linear tapes and S3, most devices can support this feature\&. It is currently unused by Amanda\&.
.RE
.PP
STREAMING
.RS 4
- (read\-only) This property gives the streaming requirement for this device\&. For example, tape drives often require a steady supply of data to avoid shoe\-shining, while disk devices have no such requirement\&.
+(read\-only) This property gives the streaming requirement for this device\&. For
+example, tape drives often require a steady supply of data to avoid
+shoe\-shining, while disk devices have no such requirement\&. Streaming is
+accomplished by buffering \fBdevice\-output\-buffer\-size\fR bytes of
+data\&. The allowed values are "none" (no streaming buffer necessary),
+"required" (fill the buffer before starting to write), or "desired" (fill the
+buffer before starting to write, and if the buffer becomes empty, stop writing
+until it is completely full again)\&.
.RE
.PP
VERBOSE
.RS 4
- (read\-write) If this boolean property is set, then the device will produce verbose debugging output\&. This property is not recognized by all devices\&.
+ (read\-write) If this boolean property is set, then the device will produce verbose debugging output\&. This property is not recognized by most devices\&.
.RE
.SS "BLOCK SIZES"
.PP
.PP
Amanda has historically supported a single, fixed block size \-\- usually 32k\&. The Device API adds the ability to specify a block size at runtime, using the BLOCK_SIZE property\&. Devices provide MIN_BLOCK_SIZE and MAX_BLOCK_SIZE as a guide to the range of acceptable block sizes\&. Note that this does not imply that all sizes in the range MIN_BLOCK_SIZE \- MAX_BLOCK_SIZE are available \-\- the device may require that block sizes are even multiples of some power of two, for example\&. Consult the documentation for your hardware and operating system for more information\&.
.PP
-Most devices are flexible enough to read a volume using a different block size than that with which it was written\&. This can be useful when handling old volumes written with a smaller blocksize, or volumes of unknown blocksize\&. Unfortunately, some tape devices do not detect oversized blocks correctly, and may lose data if the configured block size is smaller than the volume\'s block size\&. The tape device driver has a READ_BUFFER_SIZE property which specifies the minimum buffer size that will be allocated for reads from tape\&. If the hardware supports it, setting this property allows Amanda to correctly read from tapes written with any blocksize less than or equal to READ_BUFFER SIZE\&.
+Most devices are flexible enough to read a volume using a different block size than that with which it was written\&. This can be useful when handling old volumes written with a smaller blocksize, or volumes of unknown blocksize\&. Unfortunately, some tape devices do not detect oversized blocks correctly, and may lose data if the configured block size is smaller than the volume\*(Aqs block size\&. The tape device driver has a READ_BLOCK_SIZE property which specifies the minimum buffer size that will be allocated for reads from tape\&. If the hardware supports it, setting this property allows Amanda to correctly read from tapes written with any blocksize less than or equal to READ_BLOCK_SIZE\&.
.if n \{\
.sp
.\}
.RS 4
-.BM yellow
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.PP
The RAIT device does not support flexible block sizes, as its parity algorithm requires that all child devices have the same, fixed block size\&.
.sp .5v
-.EM yellow
.RE
-.SS "DRIVER\-SPECIFIC PROPERTIES"
+.SS "LEOM DETECTION"
+.PP
+Some Amanda devices can detect end\-of\-medium (running out of space on the device) before it occurs\&. This early warning is referred to as logical EOM, and where it is supported Amanda can operate more efficiently, since the possibility for data loss is reduced\&.
+.PP
+The boolean LEOM property indicates whether or not a particular device supports LEOM detection\&. The sections below also describe the degree of support\&.
+.SH "DEVICES"
+.PP
+This section lists the device 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 "Null Device"
+.nf
+tapedev "null:"
+.fi
+.PP
+The null device driver only supports writing, and discards all data\&. It is generally only useful for testing purposes\&.
+.SS "RAIT Device"
+.nf
+tapedev "rait:tape:/dev/rmt/tps0d{4,5,6}n"
+.fi
+.PP
+The RAIT device driver mirrors or stripes data over multiple "child" devices\&. The child devices are specified using a shell\-like syntax, where alternatives are enclosed in braces and separated by commas\&. Braces and commas can be escaped with a backslash\&. Note that the backslash itself must be escaped in most contexts\&. For example:
+.sp
+.nf
+tapedev "rait:{file:/var/amanda/vtapes,tape:/dev/nst0}"
+tapedev "rait:{comma\-dev:foo\e\e,bar,brace\-dev:foo\e\e}bar}" # quoting
+.fi
+If the braces contain a numeric range separated with two dots, that range will be filled in sequentially\&. If the first number has a leading zero, then the results will be zero\-padded to the maximum length\&. For example:
+.sp
+.nf
+tapedev "rait:file:/var/amanda/vtapes/drive{01\&.\&.04}"
+.fi
+.PP
+With two child devices, the RAIT device driver mirrors data such that the two devices contain identical data and can be used singly for recovery\&. With more than two devices, the RAIT device "stripes" data across all but one device and writes a parity block to the final device, usable for data recovery in the event of a device or volume failure\&. The RAIT device scales its blocksize as necessary to match the number of children that will be used to store data\&.
+.PP
+When a child device is known to have failed, the RAIT device should be reconfigured to replace that device with the text "ERROR", e\&.g\&.,
+.sp
+.nf
+tapedev "rait:{tape:/dev/st0,ERROR,tape:/dev/st2}"
+.fi
+This will cause the RAIT device to start up in degraded mode, reconstructing the data from the missing device\&.
+.PP
+Like ordinary RAID drivers, the RAIT device driver can automatically enter degraded mode when one of its child devices fails\&. However, the RAIT device cannot automatically recover from any write error nor write any data in degraded mode\&. When reading, certain errors may be fatal (rather than causing degraded mode)\&. And in any case, labels on all volumes must initially match (labeled or otherwise)\&. If you have lost one volume from a set, explicitly start the device in degraded mode as described above\&.
+.PP
+This device can detect LEOM if and only if all of the child devices can detect LEOM\&.
+.SS "Child Device Block Sizes"
+.PP
+The RAIT device driver requires that all of its child devices use the same block size\&. If no block sizes are specified, the driver selects the block size closest to 32k that is within the MIN_BLOCK_SIZE \- MAX_BLOCK_SIZE range of all child devices, and calculates its own blocksize according to the formula
+\fIrait_blocksize = child_blocksize * (num_children \- 1)\fR\&. If a block size is specified for the RAIT device, then it calculates its child block sizes according to the formula
+\fIchild_blocksize = rait_blocksize / (num_children \- 1)\fR\&. Either way, it sets the BLOCK_SIZE property of each child device accordingly\&.
.SS "S3 Device"
+.nf
+tapedev "s3:foocorp\-backups/DailySet1\-"
+device\-property "S3_ACCESS_KEY" "MYACCESSKEY"
+device\-property "S3_SECRET_KEY" "MYSECRETKEY"
+.fi
+.PP
+The S3 device driver uploads data to the Amazon S3 "storage cloud"\&. Its device name is a slash\-sparated combination of bucket name and prefix: "s3:BUCKET/PREFIX"\&. Since buckets must be unique across all Amazon S3 users, and since the number of buckets allowed to each user is limited, the driver can store multiple Amanda volumes in a single S3 bucket, distinguished by prefix\&. The prefix and slash can be omitted if they are not needed: "s3:BUCKET"\&.
+.PP
+The access and secret keys used to authenticate to Amazon S3 are provided as properties\&.
+.PP
+The S3 device driver stores each block in a distinct S3 object\&. Due to high HTTP overhead for each request, use of larger than normal block sizes (> 1 megabyte) is recommended with the S3 device\&.
+.PP
+Amanda automatically creates a bucket when writing, if the bucket doesn\*(Aqt already exist\&. At that time, it specifies where Amazon should store the data based on the S3_BUCKET_LOCATION property\&. If this property is not set, Amazon\*(Aqs default value (equivalent to "*") is used\&. The bucket location has both billing and legal concerns, so you are encouraged to consult Amazon\*(Aqs documentation for details\&.
+.PP
+Amazon does not permit changes to bucket locations, so this is a permanent specification\&. If the bucket already exists and the property is set, then Amanda checks the property against the location of the bucket, and produces an error if they do not match\&.
+.if n \{\
+.sp
+.\}
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBNote\fR
+.ps -1
+.br
+.PP
+If a location constraint is set, the bucket name must consist only of lower\-case letters, numbers, dashes, and dots\&.
+.sp .5v
+.RE
+.PP
+This driver supports the VERBOSE property, but use it carefully \-\- it produces a great deal of output, and may cause spurious failures by filling your debug log partition\&. Its logging is generally only useful for developers chasing down a problem in communications with Amazon\*(Aqs servers\&.
+.PP
+Since Amazon storage is unlimited, the device never encounteres EOM, so LEOM detection is trivially enabled for this device\&.
+.PP
+This driver supports the ENFORCE_MAX_VOLUME_USAGE property\&. Default value is false\&. See COMMON_PROPERTIES, above\&.
+.SS "Device-Specific Properties"
+.PP
+In addition to the common properties, the S3 device supports the properties listed in this section\&.
+.PP
+Most Amanda devices work just fine without any properties, but not the S3 device\&. A typical S3 configuration will have an access key and secret key specified:
+.sp
+.nf
+device\-property "S3_ACCESS_KEY" "27D3B8C6C4E7AA423C2B37C72A0D22C8"
+device\-property "S3_SECRET_KEY" "agphc2Q7Zmxragphc2RmO2xragpzZGY7a2xqCgr"
+.fi
+.PP
+CLIENT_ID
+.RS 4
+
+(read\-write) The client_id for oauth2\&.
+.RE
+.PP
+CLIENT_SECRET
+.RS 4
+
+(read\-write) The client_secret for oauth2\&.
+.RE
+.PP
+CREATE\-BUCKET
+.RS 4
+
+(read\-write) Default: yes\&. If amanda create/delete the bucket\&.
+.RE
+.PP
+REFRESH_TOKEN
+.RS 4
+
+(read\-write) The refresh\-token for oauth2\&.
+.RE
+.PP
+MAX_RECV_SPEED
+.RS 4
+
+(read\-write) Maximum speed, in bytes per second, that this device will receive
+data from S3\&. If the average speed exceeds this value, the device will stop
+reading long enough to bring the average below this value\&.
+.RE
+.PP
+MAX_SEND_SPEED
+.RS 4
+
+(read\-write) Maximum speed, in bytes per second, that this device will send
+data to S3\&. If the average speed exceeds this value, the device will stop
+writing long enough to bring the average below this value\&.
+.RE
+.PP
+S3_MULTI_DELETE
+.RS 4
+
+(read\-write) If the server support the multi delete protocol (only Amazon S3),
+default is "YES"\&. If it fail, it revert to single delete\&.
+.RE
+.PP
+NB_THREADS_BACKUP
+.RS 4
+
+(read\-write) The number of thread that send data to the s3 device, higher value can provide more throutput\&.
+.RE
+.PP
+NB_THREADS_RECOVERY
+.RS 4
+
+(read\-write) The number of thread that read data from the s3 device, higher value can provide more throutput\&.
+.RE
+.PP
+OPENSTACK_SWIFT_API
+.RS 4
+
+ (read\-write) Deprecated, set "STORAGE_API to "SWIFT\-1\&.0"\&.
+.RE
+.PP
+PROXY
+.RS 4
+
+ (read\-write) The proxy hostname or IP in the format "host[:port]"\&.
+.RE
+.PP
+PASSWORD
+.RS 4
+
+(read\-write) The password (for swift v2)\&.
+.RE
+.PP
+PROJECT\-ID
+.RS 4
+
+(read\-write) The projectid (for google)\&.
+.RE
+.PP
+REUSE\-CONNECTION
+.RS 4
+
+(read\-write) Default: YES\&. Set it to "NO" if reusing a connection cause some bug, this is sometime the case with big block size\&.
+.RE
.PP
S3_ACCESS_KEY
.RS 4
.RS 4
(read\-write) Location constraint for buckets on Amazon S3\&.
-Currently, it can be set to "", for no constraint (i\&.e\&. store data in the US),
-or "EU" (i\&.e\&. store data in the EU)\&.
-See Amazon\'s documentation for details and latest information
+As of this writing, it can be set to "*" (US Standard, i\&.e\&. lowest\-latency
+choice of US East or West), "us\-west\-1" (US West, Northern California), "EU"
+(European Union), or "ap\-southeast\-1" (Asia Pacific)\&. See : http://docs.amazonwebservices.com/general/latest/gr/index.html?rande.html for the most up\-to\-date list\&.
+.RE
+.PP
+SSL_CA_INFO
+.RS 4
+
+ (read\-write) Path to CA certificate to use to verify the identity of the S3 server\&.
+Only applicable when SSL/TLS is in use\&. The certificate should be in PEM format
+if OpenSSL or GnuTLS is being used with libcurl\&. Multiple certificates can be
+bundled together simply by concatenating them\&.
+If NSS is being used, then it is the directory that the database resides in\&.
+The value is passed to curl_easy_setopt(3) as CURLOPT_CAINFO\&.
+.RE
+.PP
+S3_HOST
+.RS 4
+
+(read\-write) The host name to connect, in the form "hostname:port" or "ip:port", default is "s3\&.amazonaws\&.com"
.RE
.PP
S3_SECRET_KEY
.RS 4
- (read\-write) This property gives the Amazon S3 secret key used to access the service\&.
+(read\-write) This property gives the Amazon S3 secret key used to access the service\&.
+.RE
+.PP
+S3_SERVER_SIDE_ENCRYPTION
+.RS 4
+
+(read\-write) Set to the server side encryption algorithm to use\&.
+There is actually only one algorithm, it is "AES256"\&. The encryption is done
+by Amazon on their server\&. See
+: http://docs.amazonwebservices.com/AmazonS3/latest/API/index.html?RESTObjectPUT.html
+for the most up\-to\-date list\&.
+.RE
+.PP
+S3_SERVICE_PATH
+.RS 4
+
+(read\-write) A path to add at the beginning of the URL\&.
+.RE
+.PP
+S3_STORAGE_CLASS
+.RS 4
+
+(read\-write) Storage class for new objects, currently one of "STANDARD" (the default)
+or "REDUCED_REDUNDANCY" (cheaper, but less redundant)\&. See
+: http://docs.amazonwebservices.com/AmazonS3/latest/dev/index.html?DataDurability.html
+for the most up\-to\-date list\&.
.RE
.PP
S3_SSL
.RS 4
- (read\-write) Whether or not to use SSL/TLS to secure communications with Amazon S3\&.
+(read\-write) Whether or not to use SSL/TLS to secure communications with Amazon S3\&.
+.RE
+.PP
+S3_SUBDOMAIN
+.RS 4
+
+ (read\-write) Whether or not to use subdomain hostname\&.
.RE
.PP
S3_USER_TOKEN
.RS 4
- (read\-write) This property specifies the user token for Amanda Enterprise Edition customers\&.
+(read\-write) This property specifies the user token for Amanda Enterprise Edition customers\&.
.RE
.PP
-Most Amanda devices work just fine without any properties, but not the S3 device\&. A typical S3 configuration will have an access key and secret key specified:
-.sp
+STORAGE_API
+.RS 4
+
+ (read\-write) Which API to use for the cloud:
.nf
-device_property "S3_ACCESS_KEY" "27D3B8C6C4E7AA423C2B37C72A0D22C8"
-device_property "S3_SECRET_KEY" "agphc2Q7Zmxragphc2RmO2xragpzZGY7a2xqCgr"
+ S3 Amanzon S3 api
+ SWIFT\-1\&.0 Openstack swift v1\&.0
+ SWIFT\-2\&.0 Openstack swift v2\&.0
+ OAUTH2 Google
+ CASTOR Caringo CAStor
.fi
+.RE
+.PP
+TENANT_ID
+.RS 4
+
+(read\-write) The tenant_id (for swift v2)\&.
+.RE
+.PP
+TENANT_NAME
+.RS 4
+(read\-write) The tenant_name (for swift v2)\&.
+.RE
+.PP
+USERNAME
+.RS 4
+
+(read\-write) The username (for swift v2)\&.
+.RE
+.PP
+VERBOSE
+.RS 4
+
+(read\-write) If true, verbose data about each HTTP transaction is sent to the debug log\&.
+.RE
+.SS "S3 URL"
+
+ SSL && SUBDOMAIN: https://bucket\&.host/service_path/file
+ SSL && !SUBDOMAIN: https://host/service_path/bucket/file
+ !SSL && SUBDOMAIN: http://bucket\&.host/service_path/file
+ !SSL && !SUBDOMAIN: http://host/service_path/bucket/file
.SS "Tape Device"
+.nf
+tapedev "tape:/dev/nst0"
+.fi
+.PP
+The tape device driver interacts with a tape drive\&. The device uses the operating system\*(Aqs built\-in tape support, which is generally similar to that available via the command\-line utilities dd(1) and mt(1)\&.
+.PP
+The tape device name should specify a path to the operating system\*(Aqs device file\&.
+.PP
+There is no simple way to determine whether a particular system (operating system and tape hardware) supports LEOM, so as a safe default the tape device has LEOM detection disabled\&. However, on modern hardware and common operating systems (Linux, *BSD, and Solaris, at least), LEOM support is functional\&. On these systems, enable LEOM by setting the LEOM property to "true" at the appropriate place in the Amanda configuration\&.
+.SS "Device-Specific Properties"
.PP
Most of these properties are automatically detected, but can be overridden in the configuration file if the autodetection fails\&. Note that tape drives are required to at least support the MTREW (rewind) operation; all other operations can be emulated with the MTREW and read data operations\&.
.PP
BROKEN_GMT_ONLINE
.RS 4
- (read\-write) Set this boolean property if the system\'s GMT_ONLINE macro gives incorrect results\&. This is currently true for the Linux IDE\-TAPE driver\&.
+ (read\-write) Set this boolean property if the system\*(Aqs GMT_ONLINE macro gives incorrect results\&. This is currently true for the Linux IDE\-TAPE driver\&.
.RE
.PP
BSF
(read\-write) This boolean property specifies whether the device driver may use the MTFSF operation (forward seek file)\&.
.RE
.PP
+FSF_AFTER_FILEMARK
+.RS 4
+
+ (read\-write) This boolean property specifies whether the device driver needs a FSF to go the next file after the filemark is read\&. Default to "TRUE" on Solaris and "FALSE" on all others machines\&.
+.RE
+.PP
FSR
.RS 4
(read\-write) This boolean property specifies whether the device driver may use the MTFSR operation (forward seek record)\&.
.RE
.PP
-READ_BUFFER_SIZE
+NONBLOCKING_OPEN
.RS 4
- (read\-write) This property specifies the minimum buffer size that will be used for reads; this should be large enough to contain any block that may be read from the device, and must be larger than BLOCK_SIZE\&. This property exists for tape devices which cannot determine the size of on\-tape blocks, or which may discard data which overflows a small buffer\&. The tapetype parameter \fIREADBLOCKSIZE\fR sets this property\&. See BLOCK SIZES, above\&.
+ (read\-write) Set this boolean property to "true" if O_NONBLOCK must be used on the open call\&. Default to "true" on Linux and "false" on all others machines\&. Without it, Linux wait for a few seconds if no tape are loaded\&. Solaris have strange error it is set to "yes"\&.
.RE
-.SH "SEE ALSO"
.PP
+READ_BLOCK_SIZE
+.RS 4
-\fBamanda.conf\fR(5),
-.SH "Authors"
+ (read\-write) This property (previously known as \fIREAD_BUFFER_SIZE\fR) specifies the block size that will be used for reads; this should be large enough to contain any block that may be read from the device (for example, from a tape containing variable\-sized blocks), and must be larger than BLOCK_SIZE\&. This property is most often used when overwriting tapes using a new, smaller block size\&.
+ The tapetype parameter \fIREADBLOCKSIZE\fR sets this property\&. See BLOCK SIZES, above\&.
+.RE
+.SS "NDMP Device"
+.nf
+tapedev "ndmp:my\&.filer\&.com:10000@st1"
+device\-property "NDMP_USERNAME" "jimmy"
+device\-property "NDMP_PASSWORD" "thelock"
+.fi
+.PP
+This device enables Amanda to communicate with a tape service on an NDMP server\&. The device name specifies the hostname and optionally the TCP port of the NDMP server, followed by the name of the tape device on the server (\fBst1\fR
+in the example above)\&.
+.PP
+This device supports LEOM detection\&.
+.SS "Device-Specific Properties"
+.PP
+The properties
+\fBNDMP_USERNAME\fR
+and
+\fBNDMP_PASSWORD\fR
+set the username and password with which to access the NDMP server\&. The default for both is "ndmp"\&.
+.PP
+INDIRECT
+.RS 4
+
+(read\-write) Set to "yes" if the ndmp server doesn\*(Aqt allow to set a window length to 0\&.
+The default is "no"\&.
+.RE
+.PP
+NDMP_AUTH
+.RS 4
+
+(read\-write) Authentication method to use to connect to the NDMP server\&. One of
+"md5" (default), "text", "none" (for an empty authentication attempt) or "void" (for
+no authentication attempt at all)\&.
+.RE
+.PP
+NDMP_PASSWORD
+.RS 4
+
+(read\-write) Password for md5 or text authentications\&.
+.RE
+.PP
+NDMP_USERNAME
+.RS 4
+
+(read\-write) Username for md5 or text authentications\&.
+.RE
+.PP
+READ_BLOCK_SIZE
+.RS 4
+
+(read\-write) This property specifies the block size that will be used for reads; this should be large enough to contain any block that may be read from the device and must be larger than BLOCK_SIZE\&. See BLOCK_SIZES, above\&.
+.RE
+.SS "VFS Device"
+.nf
+tapedev "file:/path/to/vtape"
+.fi
+.PP
+The VFS device driver stores data on a UNIX filesystem\&. Note that although one typically uses the VFS device driver to store data on hard disks, the driver does not interface with any hardware on a block level\&.
+.PP
+The device name specifies a path to a directory which must exist and contain a "data/" subdirectory\&. Each tape file is stored as a distinct file in this directory, the name of which reflects the Amanda header in the tape file\&. Block boundaries are not maintained: the driver supports reads of arbitrary size, regardless of the blocksize used to write the data\&.
+.PP
+This device supports LEOM detection\&. LEOM will be indicated when the MAX_VOLUME_USAGE is nearly met, or when the filesystem is nearly out of space\&. The latter circumstance is detected by monitoring the available space on the filesystem, and this monitoring can be disabled with the MONITOR_FREE_SPACE property\&. Note that the device cannot detect other circumstances that may cause a write to fail, such as a filesystem quota\&. LEOM detection can be disabled by setting the LEOM property to false\&.
+.PP
+This device supports the ENFORCE_MAX_VOLUME_USAGE property\&. Default value is true\&. See COMMON PROPERTIES, above\&.
+.SS "Device-Specific Properties"
+.PP
+MONITOR_FREE_SPACE
+.RS 4
+
+ (read\-write) This property controls whether the device will monitor
+ the filesystem\*(Aqs free space to detect a full filesystem before an
+ error occurs, and defaults to true\&. The monitoring operation works on
+ most filesystems, but if it causes problems, use this property to
+ disable it\&.
+.RE
+.SS "DVD\-RW Device"
+.nf
+tapedev "dvdrw:/var/cache/amanda/dvd\-cache:/dev/scd0"
+device\-property "DVDRW_MOUNT_POINT" "/media/dvd"
+device\-property "DVDRW_KEEP_CACHE" "false"
+device\-property "DVDRW_UNLABELLED_WHEN_UNMOUNTABLE" "true"
+.fi
+.PP
+The DVD\-RW device driver reads and writes optical media such as DVDs and CDs\&. The device name must specify a cache directory for data to be temporarily stored, followed by the operating system name for the optical drive\&. The cache directory must contain a "data/" subdirectory\&.
+.PP
+The DVDRW_MOUNT_POINT property is required, and specifies a directory where the optical media can be mounted\&. This directory must be configured to enable non\-root users to mount the optical media\&. On Linux, that means a line similar to the following in /etc/fstab:
+.nf
+/dev/scd0 /media/dvd auto ro,user,noauto 0 0
+.fi
+.PP
+Note the "user" option\&.
+.PP
+When writing data, the device acts as a VFS device using the given cache directory\&. On completion of writing the tape, the cache directory is written to optical media\&. The DVDRW_KEEP_CACHE property controls whether the cache contents are immediately deleted\&. When reading, the optical media is first mounted and read as a VFS device\&.
+.PP
+Attempting to mount unformatted media or media that is formatted but contains no filesystem will usually result in an error\&. The boolean DVDRW_UNLABELLED_WHEN_UNMOUNTABLE property specifies whether media that cannot be mounted should be treated as an empty, unlabelled volume when attempting to read the volume label\&. It is necessary to set this property to "true" when labelling such media\&.
+.PP
+This device does not support LEOM detection\&.
+.SS "Device-Specific Properties"
+.PP
+The properties DVDRW_GROWISOFS_COMMAND, DVDRW_MOUNT_COMMAND and DVDRW_UMOUNT_COMMAND specify alternative commands for writing, mounting and unmounting optical media\&. The default is to find the programs using the PATH environment variable\&.
+.PP
+The CDRW device supports all of the properties of the VFS device, as well as the properties given below\&. The DVDRW_MOUNT_POINT property is required\&. Other properties are optional\&.
+.PP
+DVDRW_KEEP_CACHE
+.RS 4
+
+ (read\-write) Set this boolean property to "true" if the disk cache directory should be kept after successfully writing tape data to optical media\&. The default is false, which causes the cache contents to be deleted immediately after a successful write operation\&.
+.RE
+.PP
+DVDRW_MOUNT_POINT
+.RS 4
+
+ (read\-write) This property specifies the filesystem mount point for the optical media\&. Non\-root users must be able to mount optical media by invoking "mount" and specifying this mount point\&.
+.RE
+.PP
+DVDRW_UNLABELLED_WHEN_UNMOUNTABLE
+.RS 4
+
+ (read\-write) Treat unmountable media as empty, unlabelled media\&. This is necessary when attempting to label freshly formatted media\&.
+.RE
+.PP
+DVDRW_GROWISOFS_COMMAND
+.RS 4
+
+ (read\-write) The command to invoke to burn the DVD\&.
+.RE
+.PP
+DVDRW_MOUNT_COMMAND
+.RS 4
+
+ (read\-write) The command to invoke to mount the DVD\&.
+.RE
+.PP
+DVDRW_UMOUNT_COMMAND
+.RS 4
+
+ (read\-write) The command to invoke to unmount the DVD\&.
+.RE
+.SH "SEE ALSO"
+.PP
+\fBamanda\fR(8),
+\fBamanda.conf\fR(5)
+.PP
+The Amanda Wiki:
+: http://wiki.zmanda.com/
+.SH "AUTHORS"
.PP
\fBIan Turner\fR <\&ian@zmanda\&.com\&>
.RS 4
-Zmanda, Inc\&. (\FChttp://www\&.zmanda\&.com\F[])
+Zmanda, Inc\&. (http://www\&.zmanda\&.com)
.RE
.PP
\fBDustin J\&. Mitchell\fR <\&dustin@zmanda\&.com\&>
.RS 4
-Zmanda, Inc\&. (\FChttp://www\&.zmanda\&.com\F[])
+Zmanda, Inc\&. (http://www\&.zmanda\&.com)
.RE
projects / debian / amanda / blobdiff