2 .\" Title: amanda-devices
3 .\" Author: Ian Turner <ian@zmanda.com>
4 .\" Generator: DocBook XSL Stylesheets vsnapshot_8273 <http://docbook.sf.net/>
6 .\" Manual: Miscellanea
7 .\" Source: Amanda 2.6.1p1
10 .TH "AMANDA\-DEVICES" "7" "04/10/2009" "Amanda 2\&.6\&.1p1" "Miscellanea"
11 .\" -----------------------------------------------------------------
12 .\" * set default formatting
13 .\" -----------------------------------------------------------------
14 .\" disable hyphenation
16 .\" disable justification (adjust text to left margin only)
18 .\" -----------------------------------------------------------------
19 .\" * MAIN CONTENT STARTS HERE *
20 .\" -----------------------------------------------------------------
22 amanda-devices \- Configuring and Using Amanda Devices
25 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\&.
29 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\&.
31 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\&.
32 .SH "SPECIFYING DEVICES"
34 Device names take the form
35 \fITYPE:NODE\fR, where
37 selects a device driver, and
39 provides further information to that driver\&. The syntax for each device driver is given in the corresponding section below\&.
41 Devices are described in
43 with "device" sections, e\&.g\&.,
46 define device top_drive {
47 tapedev "tape:/dev/nst0"
48 device_property "BLOCK_SIZE" "131072"
51 A device defininition creates a device "alias", in this case named
52 \fItop_drive\fR, which can then be named in the global
62 parameter can also specify a literal device name\&. For example,
65 tapedev "file:/amdisks"
71 define device default {
72 tapedev "file:/amdisks"
75 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\&.
79 for more information on Amanda configuration\&.
82 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\&.
88 The null device driver only supports writing, and discards all data\&. It is generally only useful for testing purposes\&.
91 tapedev "rait:tape:/dev/rmt/tps0d{4,5,6}n"
94 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\&.
96 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\&.
98 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\&.,
101 tapedev "rait:{tape:/dev/st0,ERROR,tape:/dev/st2}"
103 This will cause the RAIT device to start up in degraded mode, reconstructing the data from the missing device\&.
105 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\&.
106 .SS "Child Device Block Sizes"
108 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
109 \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
110 \fIchild_blocksize = rait_blocksize / (num_children \- 1)\fR\&. Either way, it sets the BLOCK_SIZE property of each child device accordingly\&.
113 tapedev "s3:foocorp\-backups/DailySet1\-"
114 device_property "S3_ACCESS_KEY" "MYACCESSKEY"
115 device_property "S3_SECRET_KEY" "MYSECRETKEY"
118 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"\&.
120 The access and secret keys used to authenticate to Amazon S3 are provided as properties\&.
122 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\&.
124 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\&.
126 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\&.
129 tapedev "tape:/dev/nst0"
132 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)\&.
134 The tape device name should specify a path to the operating system\'s device file\&.
137 tapedev "file:/path/to/vtape"
140 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\&.
142 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\&.
147 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\&.
149 Properties are specified in
152 \fIdevice\-property\fR
153 parameter\&. The syntax looks like this:
156 device_property "FROBNICATOR_PATH" "/var/frobd/state"
157 device_property "BYTES_PER_FORTNIGHT" "128k"
158 device_property "USE_QUBITS" "no"
161 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
162 \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\&.
164 Some properties are set based on other configuration values, such as tapetype parameters\&. These special cases are detailed under the appropriate property, below\&.
166 The order in which device properties are set is as follows:
176 Tapetype parameters (including length, blocksize, and readblocksize) are translated into device properties and set accordingly\&.
187 Device properties from any device_property configuration parameters are set, in the order they appear in the configuration file\&.
190 Properties described as read\-only are not accessible to users\&. They are listed here for completeness\&.
191 .SS "COMMON PROPERTIES"
193 Note that some of these properties are currently unused, and present only for future expansion\&. Not all devices implement all of these properties\&.
198 (read\-only) This boolean property indicates whether this device supports appending data to volumes\&.
204 (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\&.
210 (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\&.
216 (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\&.
222 (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\&.
228 (read\-only) This property indicates the level of concurrent access that this device supports\&.
234 (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\&.
240 (read\-only) This property gives the maximum block size this device can support\&. See BLOCK SIZES, below\&.
246 (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\&.
252 (read\-write) This property gives the minimum block size this device can support\&. See BLOCK SIZES, below\&.
258 (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\&.
264 (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\&.
270 (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\&.
276 (read\-write) If this boolean property is set, then the device will produce verbose debugging output\&. This property is not recognized by all devices\&.
280 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\&.
282 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\&.
284 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\&.
290 .nr an-no-space-flag 1
298 The RAIT device does not support flexible block sizes, as its parity algorithm requires that all child devices have the same, fixed block size\&.
301 .SS "DRIVER\-SPECIFIC PROPERTIES"
307 (read\-write) This property gives the Amazon S3 access key used to access the service\&.
313 (read\-write) Location constraint for buckets on Amazon S3\&.
314 Currently, it can be set to "", for no constraint (i\&.e\&. store data in the US),
315 or "EU" (i\&.e\&. store data in the EU)\&.
316 See Amazon\'s documentation for details and latest information
322 (read\-write) This property gives the Amazon S3 secret key used to access the service\&.
328 (read\-write) Whether or not to use SSL/TLS to secure communications with Amazon S3\&.
334 (read\-write) This property specifies the user token for Amanda Enterprise Edition customers\&.
337 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:
340 device_property "S3_ACCESS_KEY" "27D3B8C6C4E7AA423C2B37C72A0D22C8"
341 device_property "S3_SECRET_KEY" "agphc2Q7Zmxragphc2RmO2xragpzZGY7a2xqCgr"
346 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\&.
351 (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\&.
357 (read\-write) This boolean property specifies whether the device
358 driver may execute the MTBSF operation (backward seek file)\&.
364 (read\-write) This boolean property specifies whether the device
365 driver should execute an MTBSF (backward seek file) operation after
366 MTEOM (seek to end of recorded data) in order to append\&.
372 (read\-write) This boolean property specifies whether the device
373 driver may use the MTBSR operation (backward seek record)\&.
379 (read\-write) This boolean property specifies whether the device
380 driver may use the MTEOM command (seek to end of recorded data)\&.
386 (read\-write) This integer property gives the number of filemarks that should be written at EOD\&. It is usually 1 or 2\&.
392 (read\-write) This boolean property specifies whether the device driver may use the MTFSF operation (forward seek file)\&.
398 (read\-write) This boolean property specifies whether the device driver may use the MTFSR operation (forward seek record)\&.
404 (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\&.
409 \fBamanda.conf\fR(5),
412 \fBIan Turner\fR <\&ian@zmanda\&.com\&>
414 Zmanda, Inc\&. (http://www\&.zmanda\&.com)
417 \fBDustin J\&. Mitchell\fR <\&dustin@zmanda\&.com\&>
419 Zmanda, Inc\&. (http://www\&.zmanda\&.com)
projects / debian / amanda / blob