'\" t .\" Title: amanda-devices .\" Author: Ian Turner .\" Generator: DocBook XSL Stylesheets vsnapshot_8273 .\" Date: 04/10/2009 .\" Manual: Miscellanea .\" Source: Amanda 2.6.1p1 .\" Language: English .\" .TH "AMANDA\-DEVICES" "7" "04/10/2009" "Amanda 2\&.6\&.1p1" "Miscellanea" .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" amanda-devices \- Configuring and Using Amanda Devices .SH "DESCRIPTION" .PP The Device API specifies a generic interface between Amanda and storage devices such as tapes or disks\&. This manual page describes the device drivers included with Amanda\&. .PP This is a \fIuser\-level\fR description of the API, and does not address details that are only of concern to developers\&. For that purpose, consult the Amanda source code and http://wiki\&.zmanda\&.com\&. .PP The term "device driver" describes the software that can communicate with some kind of backend storage, e\&.g\&., a tape driver\&. A "device" is the storage element itself, usually a piece of hardware\&. When discussing a device and its driver as a unit, the term "device" is sometimes also used to refer to the combination of device and driver\&. .SH "SPECIFYING DEVICES" .PP Device names take the form \fITYPE:NODE\fR, where \fITYPE\fR 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 \fBamanda.conf\fR(5) with "device" sections, e\&.g\&., .sp .nf define device top_drive { tapedev "tape:/dev/nst0" device_property "BLOCK_SIZE" "131072" } .fi A device defininition creates a device "alias", in this case named \fItop_drive\fR, which can then be named in the global \fItapedev\fR parameter: .sp .nf tapedev "top_drive" .fi .PP The global \fItapedev\fR parameter can also specify a literal device name\&. For example, .sp .nf tapedev "file:/amdisks" .fi is equivalent to .sp .nf tapedev "default" define device default { tapedev "file:/amdisks" } .fi 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.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\&., .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\&. .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\&. .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\&. .PP Properties are specified in \fIamanda\&.conf\fR with the \fIdevice\-property\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" .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\&. .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 The order in which device properties are set is as follows: .sp .RS 4 .ie n \{\ \h'-04' 1.\h'+01'\c .\} .el \{\ .sp -1 .IP " 1." 4.2 .\} Tapetype parameters (including length, blocksize, and readblocksize) are translated into device properties and set accordingly\&. .RE .sp .RS 4 .ie n \{\ \h'-04' 2.\h'+01'\c .\} .el \{\ .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\&. .RE .PP Properties described as read\-only are not accessible to users\&. They are listed here for completeness\&. .SS "COMMON PROPERTIES" .PP Note that some of these properties are currently unused, and present only for future expansion\&. Not all devices implement all of these properties\&. .PP APPENDABLE .RS 4 (read\-only) This boolean property indicates whether this device supports appending data to volumes\&. .RE .PP BLOCK_SIZE .RS 4 (read\-write) This property gives the block size, in bytes, that will be used to write to the device\&. The usual suffixes ("kbytes", etc\&.) are allowed\&. The tapetype parameter \fIblocksize\fR sets this property\&. .RE .PP CANONICAL_NAME .RS 4 (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 COMPRESSION .RS 4 (read\-write) This boolean property represents the compression status of the device, and can be used to enable and disable such compression\&. This applies mostly to tape devices, although many tape devices do not support setting compression from software\&. .RE .PP COMPRESSION_RATE .RS 4 (read\-only) This property gives the compression rate, as a decimal ratio\&. It may be a measured value over some unspecified period or a simple estimate\&. .RE .PP CONCURRENCY .RS 4 (read\-only) This property indicates the level of concurrent access that this device supports\&. .RE .PP FREE_SPACE .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\&. .RE .PP MAX_BLOCK_SIZE .RS 4 (read\-only) This property gives the maximum block size this device can support\&. See BLOCK SIZES, below\&. .RE .PP MEDIUM_ACCESS_TYPE .RS 4 (read\-only) This property gives the type of the media in the device: read only, WORM (Write Once, Read Many), read/write, or write only\&. Write\-only devices do not support recovery, but the data are not necessarily thrown out\&. .RE .PP MIN_BLOCK_SIZE .RS 4 (read\-write) This property gives the minimum block size this device can support\&. See BLOCK SIZES, below\&. .RE .PP MAX_VOLUME_USAGE .RS 4 (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 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\&. .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\&. .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\&. .RE .SS "BLOCK SIZES" .PP Amanda writes device data in blocks\&. On most devices the block boundaries are embedded in the media along with the data itself, so subsequent reads must use the same block sizes\&. On tape devices, the block size is dictated by the capabilities of the hardware \-\- buffer sizes, physical format, and so on\&. .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\&. .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 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 "S3 Device" .PP S3_ACCESS_KEY .RS 4 (read\-write) This property gives the Amazon S3 access key used to access the service\&. .RE .PP 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 .RE .PP S3_SECRET_KEY .RS 4 (read\-write) This property gives the Amazon S3 secret key used to access the service\&. .RE .PP S3_SSL .RS 4 (read\-write) Whether or not to use SSL/TLS to secure communications with Amazon S3\&. .RE .PP S3_USER_TOKEN .RS 4 (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 .nf device_property "S3_ACCESS_KEY" "27D3B8C6C4E7AA423C2B37C72A0D22C8" device_property "S3_SECRET_KEY" "agphc2Q7Zmxragphc2RmO2xragpzZGY7a2xqCgr" .fi .SS "Tape Device" .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\&. .RE .PP BSF .RS 4 (read\-write) This boolean property specifies whether the device driver may execute the MTBSF operation (backward seek file)\&. .RE .PP BSF_AFTER_EOM .RS 4 (read\-write) This boolean property specifies whether the device driver should execute an MTBSF (backward seek file) operation after MTEOM (seek to end of recorded data) in order to append\&. .RE .PP BSR .RS 4 (read\-write) This boolean property specifies whether the device driver may use the MTBSR operation (backward seek record)\&. .RE .PP EOM .RS 4 (read\-write) This boolean property specifies whether the device driver may use the MTEOM command (seek to end of recorded data)\&. .RE .PP FINAL_FILEMARKS .RS 4 (read\-write) This integer property gives the number of filemarks that should be written at EOD\&. It is usually 1 or 2\&. .RE .PP FSF .RS 4 (read\-write) This boolean property specifies whether the device driver may use the MTFSF operation (forward seek file)\&. .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 .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\&. .RE .SH "SEE ALSO" .PP \fBamanda.conf\fR(5), .SH "AUTHORS" .PP \fBIan Turner\fR <\&ian@zmanda\&.com\&> .RS 4 Zmanda, Inc\&. (http://www\&.zmanda\&.com) .RE .PP \fBDustin J\&. Mitchell\fR <\&dustin@zmanda\&.com\&> .RS 4 Zmanda, Inc\&. (http://www\&.zmanda\&.com) .RE