X-Git-Url: https://git.gag.com/?a=blobdiff_plain;f=man%2Famanda-devices.7;h=f92917663a2f939e943c5b96a4f75c8eb56dba7f;hb=d28952249e392eb31bc8eecc53f6c477f30c617b;hp=e1f7f33e827dd98ef53305ae98f193b515217f97;hpb=96f35b20267e8b1a1c846d476f27fcd330e0b018;p=debian%2Famanda diff --git a/man/amanda-devices.7 b/man/amanda-devices.7 index e1f7f33..f929176 100644 --- a/man/amanda-devices.7 +++ b/man/amanda-devices.7 @@ -1,13 +1,22 @@ '\" t .\" Title: amanda-devices .\" Author: Ian Turner -.\" Generator: DocBook XSL Stylesheets vsnapshot_8273 -.\" Date: 11/05/2009 +.\" Generator: DocBook XSL Stylesheets v1.76.1 +.\" Date: 01/10/2013 .\" Manual: Miscellanea -.\" Source: Amanda 2.6.1p2 +.\" Source: Amanda 3.3.3 .\" Language: English .\" -.TH "AMANDA\-DEVICES" "7" "11/05/2009" "Amanda 2\&.6\&.1p2" "Miscellanea" +.TH "AMANDA\-DEVICES" "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 .\" ----------------------------------------------------------------- @@ -38,19 +47,21 @@ selects a device driver, and \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 @@ -72,79 +83,40 @@ define device default { 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 @@ -153,13 +125,18 @@ with the 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 @@ -184,7 +161,7 @@ Tapetype parameters (including length, blocksize, and readblocksize) are transla .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\&. @@ -210,6 +187,12 @@ CANONICAL_NAME (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 @@ -228,10 +211,16 @@ CONCURRENCY (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 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\-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\-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 @@ -258,22 +247,35 @@ MAX_VOLUME_USAGE (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 @@ -281,7 +283,7 @@ Amanda writes device data in blocks\&. On most devices the block boundaries are .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 .\} @@ -298,8 +300,191 @@ Most devices are flexible enough to read a volume using a different block size t 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 .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 @@ -311,44 +496,137 @@ S3_BUCKET_LOCATION .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 @@ -407,18 +685,159 @@ FSR NONBLOCKING_OPEN .RS 4 - (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\&. Witout it, Linux wait for a few seconds if no tape are loaded\&. Solaris have strange error it is set to "yes"\&. + (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 .PP -READ_BUFFER_SIZE +READ_BLOCK_SIZE .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) 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 -.SH "SEE ALSO" +.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 -\fBamanda.conf\fR(5), +(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\&>