'\" t
.\" Title: amanda-devices
.\" Author: Ian Turner <ian@zmanda.com>
-.\" Generator: DocBook XSL Stylesheets vsnapshot_8273 <http://docbook.sf.net/>
-.\" Date: 10/18/2010
+.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
+.\" Date: 02/21/2012
.\" Manual: Miscellanea
-.\" Source: Amanda 3.2.0
+.\" Source: Amanda 3.3.1
.\" Language: English
.\"
-.TH "AMANDA\-DEVICES" "7" "10/18/2010" "Amanda 3\&.2\&.0" "Miscellanea"
+.TH "AMANDA\-DEVICES" "7" "02/21/2012" "Amanda 3\&.3\&.1" "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
.\" -----------------------------------------------------------------
.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
COMMENT
.RS 4
- (read\-write) This string property is entirely for the user\'s convenience\&. It is supported by all devices, but no device interprets its value in any way\&.
+ (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
(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
.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_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\&.
+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
.\}
.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\&.
+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\'t 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\'s default value (equivalent to "*") is used\&. The bucket location has both billing and legal concerns, so you are encouraged to consult Amazon\'s documentation for details\&.
+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 .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\'s servers\&.
+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\&.
writing long enough to bring the average below this value\&.
.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) Set to yes if it is an openstack storage device\&.
+.RE
+.PP
S3_ACCESS_KEY
.RS 4
(read\-write) Location constraint for buckets on Amazon S3\&.
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/AmazonS3/latest/index.html?LocationSelection.html for the most up\-to\-date list\&.
+(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
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
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
VERBOSE
.RS 4
- (read\-write) If true, verbose data about each HTTP transaction is sent to the debug log\&.
+(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\'s built\-in tape support, which is generally similar to that available via the command\-line utilities dd(1) and mt(1)\&.
+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\'s device file\&.
+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"
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
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_BLOCK_SIZE
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\'s free space to detect a full filesystem before an
+ 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\&.