1 .\" Title: amanda-devices
2 .\" Author: Ian Turner <ian@zmanda.com>
3 .\" Generator: DocBook XSL Stylesheets v1.74.0 <http://docbook.sf.net/>
5 .\" Manual: Miscellanea
6 .\" Source: Amanda 2.6.1
9 .TH "AMANDA\-DEVICES" "7" "01/22/2009" "Amanda 2\&.6\&.1" "Miscellanea"
10 .\" -----------------------------------------------------------------
11 .\" * (re)Define some macros
12 .\" -----------------------------------------------------------------
13 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
14 .\" toupper - uppercase a string (locale-aware)
15 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
17 .tr aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ
19 .tr aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz
21 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
22 .\" SH-xref - format a cross-reference to an SH section
23 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
32 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
33 .\" SH - level-one heading that works better for non-TTY output
34 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
36 .\" put an extra blank line of space above the head in non-TTY output
43 .nr an-prevailing-indent \\n[IN]
47 .HTML-TAG ".NH \\n[an-level]"
49 .nr an-no-space-flag 1
51 \." make the size of the head bigger
56 .\" if n (TTY output), use uppercase
61 .\" if not n (not TTY), use normal case (not uppercase)
65 .\" if not n (not TTY), put a border/line under subheading
70 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
71 .\" SS - level-two heading that works better for non-TTY output
72 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
77 .nr an-prevailing-indent \\n[IN]
82 .nr an-no-space-flag 1
85 \." make the size of the head bigger
91 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
92 .\" BB/BE - put background/screen (filled box) around block of text
93 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
106 .if "\\$2"adjust-for-leading-newline" \{\
114 .nr BW \\n(.lu-\\n(.i
117 .ie "\\$2"adjust-for-leading-newline" \{\
118 \M[\\$1]\h'1n'\v'+.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
121 \M[\\$1]\h'1n'\v'-.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
132 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
133 .\" BM/EM - put colored marker in margin next to block of text
134 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
151 \M[\\$1]\D'P -.75n 0 0 \\n(BHu -(\\n[.i]u - \\n(INu - .75n) 0 0 -\\n(BHu'\M[]
159 .\" -----------------------------------------------------------------
160 .\" * set default formatting
161 .\" -----------------------------------------------------------------
162 .\" disable hyphenation
164 .\" disable justification (adjust text to left margin only)
166 .\" -----------------------------------------------------------------
167 .\" * MAIN CONTENT STARTS HERE *
168 .\" -----------------------------------------------------------------
170 amanda-devices \- Configuring and Using Amanda Devices
173 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\&.
177 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\&.
179 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\&.
180 .SH "SPECIFYING DEVICES"
182 Device names take the form
183 \fITYPE:NODE\fR, where
185 selects a device driver, and
187 provides further information to that driver\&. The syntax for each device driver is given in the corresponding section below\&.
189 Devices are described in
191 with "device" sections, e\&.g\&.,
194 define device top_drive {
195 tapedev "tape:/dev/nst0"
196 device_property "BLOCK_SIZE" "131072"
199 A device defininition creates a device "alias", in this case named
200 \fItop_drive\fR, which can then be named in the global
210 parameter can also specify a literal device name\&. For example,
213 tapedev "file:/amdisks"
219 define device default {
220 tapedev "file:/amdisks"
223 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\&.
227 for more information on Amanda configuration\&.
230 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\&.
236 The null device driver only supports writing, and discards all data\&. It is generally only useful for testing purposes\&.
239 tapedev "rait:tape:/dev/rmt/tps0d{4,5,6}n"
242 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\&.
244 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\&.
246 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\&.,
249 tapedev "rait:{tape:/dev/st0,ERROR,tape:/dev/st2}"
251 This will cause the RAIT device to start up in degraded mode, reconstructing the data from the missing device\&.
253 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\&.
254 .SS "Child Device Block Sizes"
256 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
257 \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
258 \fIchild_blocksize = rait_blocksize / (num_children \- 1)\fR\&. Either way, it sets the BLOCK_SIZE property of each child device accordingly\&.
261 tapedev "s3:foocorp\-backups/DailySet1\-"
262 device_property "S3_ACCESS_KEY" "MYACCESSKEY"
263 device_property "S3_SECRET_KEY" "MYSECRETKEY"
266 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"\&.
268 The access and secret keys used to authenticate to Amazon S3 are provided as properties\&.
270 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\&.
272 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\&.
274 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\&.
277 tapedev "tape:/dev/nst0"
280 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)\&.
282 The tape device name should specify a path to the operating system\'s device file\&.
285 tapedev "file:/path/to/vtape"
288 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\&.
290 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\&.
295 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\&.
297 Properties are specified in
300 \fIdevice\-property\fR
301 parameter\&. The syntax looks like this:
304 device_property "FROBNICATOR_PATH" "/var/frobd/state"
305 device_property "BYTES_PER_FORTNIGHT" "128k"
306 device_property "USE_QUBITS" "no"
309 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
310 \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\&.
312 Some properties are set based on other configuration values, such as tapetype parameters\&. These special cases are detailed under the appropriate property, below\&.
314 The order in which device properties are set is as follows:
324 Tapetype parameters (including length, blocksize, and readblocksize) are translated into device properties and set accordingly\&.
335 Device properties from any device_property configuration parameters are set, in the order they appear in the configuration file\&.
338 Properties described as read\-only are not accessible to users\&. They are listed here for completeness\&.
339 .SS "COMMON PROPERTIES"
341 Note that some of these properties are currently unused, and present only for future expansion\&. Not all devices implement all of these properties\&.
346 (read\-only) This boolean property indicates whether this device supports appending data to volumes\&.
352 (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\&.
358 (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\&.
364 (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\&.
370 (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\&.
376 (read\-only) This property indicates the level of concurrent access that this device supports\&.
382 (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\&.
388 (read\-only) This property gives the maximum block size this device can support\&. See BLOCK SIZES, below\&.
394 (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\&.
400 (read\-write) This property gives the minimum block size this device can support\&. See BLOCK SIZES, below\&.
406 (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\&.
412 (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\&.
418 (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\&.
424 (read\-write) If this boolean property is set, then the device will produce verbose debugging output\&. This property is not recognized by all devices\&.
428 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\&.
430 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\&.
432 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\&.
439 .nr an-no-space-flag 1
447 The RAIT device does not support flexible block sizes, as its parity algorithm requires that all child devices have the same, fixed block size\&.
451 .SS "DRIVER\-SPECIFIC PROPERTIES"
457 (read\-write) This property gives the Amazon S3 access key used to access the service\&.
463 (read\-write) Location constraint for buckets on Amazon S3\&.
464 Currently, it can be set to "", for no constraint (i\&.e\&. store data in the US),
465 or "EU" (i\&.e\&. store data in the EU)\&.
466 See Amazon\'s documentation for details and latest information
472 (read\-write) This property gives the Amazon S3 secret key used to access the service\&.
478 (read\-write) Whether or not to use SSL/TLS to secure communications with Amazon S3\&.
484 (read\-write) This property specifies the user token for Amanda Enterprise Edition customers\&.
487 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:
490 device_property "S3_ACCESS_KEY" "27D3B8C6C4E7AA423C2B37C72A0D22C8"
491 device_property "S3_SECRET_KEY" "agphc2Q7Zmxragphc2RmO2xragpzZGY7a2xqCgr"
496 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\&.
501 (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\&.
507 (read\-write) This boolean property specifies whether the device
508 driver may execute the MTBSF operation (backward seek file)\&.
514 (read\-write) This boolean property specifies whether the device
515 driver should execute an MTBSF (backward seek file) operation after
516 MTEOM (seek to end of recorded data) in order to append\&.
522 (read\-write) This boolean property specifies whether the device
523 driver may use the MTBSR operation (backward seek record)\&.
529 (read\-write) This boolean property specifies whether the device
530 driver may use the MTEOM command (seek to end of recorded data)\&.
536 (read\-write) This integer property gives the number of filemarks that should be written at EOD\&. It is usually 1 or 2\&.
542 (read\-write) This boolean property specifies whether the device driver may use the MTFSF operation (forward seek file)\&.
548 (read\-write) This boolean property specifies whether the device driver may use the MTFSR operation (forward seek record)\&.
554 (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\&.
559 \fBamanda.conf\fR(5),
562 \fBIan Turner\fR <\&ian@zmanda\&.com\&>
564 Zmanda, Inc\&. (\FChttp://www\&.zmanda\&.com\F[])
567 \fBDustin J\&. Mitchell\fR <\&dustin@zmanda\&.com\&>
569 Zmanda, Inc\&. (\FChttp://www\&.zmanda\&.com\F[])
projects / debian / amanda / blob