1AMANDA-DEVICES(7) Miscellanea AMANDA-DEVICES(7)
2
6 amanda-devices - Configuring and Using Amanda Devices
7
9 The Device API specifies a generic interface between Amanda and storage
10 devices such as tapes or disks. This manual page describes the device
11 drivers included with Amanda.
12 This is a user-level description of the API, and does not address
14 details that are only of concern to developers. For that purpose,
15 consult the Amanda source code and http://wiki.zmanda.com.
16 The term "device driver" describes the software that can communicate
18 with some kind of backend storage, e.g., a tape driver. A "device" is
19 the storage element itself, usually a piece of hardware. When
20 discussing a device and its driver as a unit, the term "device" is
21 sometimes also used to refer to the combination of device and driver.
22
24 Device names take the form TYPE:NODE, where TYPE selects a device
25 driver, and NODE provides further information to that driver. The
26 syntax for each device driver is given in the corresponding section
27 below.
28 Devices can be described in amanda.conf(5) with "device" sections,
30 e.g.,
31 define device top_drive {
33 tapedev "tape:/dev/nst0"
34 device_property "BLOCK_SIZE" "131072"
35 }
36 Such a device defininition creates a device "alias", in this case named
37 top_drive, which can then be named in the global tapedev or tpchanger
38 parameter:
39 tapedev "top_drive"
41 The global tapedev parameter can also specify a literal device name.
43 For example,
44 tapedev "file:/amdisks"
46 is equivalent to
47 tapedev "default"
49 define device default {
50 tapedev "file:/amdisks"
51 }
52 Note that, in both cases, the specified devices are actually accessed
53 through the chg-single changer driver; see amanda-changers(7) for more
54 information.
55 Device properties specified outside of any device definition apply to
57 all devices. This syntax is provided mainly for backward compatibility,
58 and for simple Amanda configurations. Note that there is no way to
59 provide properties specific to a device without defining a device
60 alias.
61 See amanda-changers(7) for details on how devices are configured, and
63 in particular on how device properties are specified. See
64 amanda.conf(5) for more information on Amanda configuration in general.
65 Note
67 There is no way to reset a device property to its default value.
68
70 Device drivers use properties as a generic means to interact with other
71 parts of Amanda. Some properties are set by the device driver and used
72 by Amanda to determine how its devices should be used. Other properties
73 can be set by Amanda or by the user to influence the driver´s behavior.
74 Properties are set for a particular device, so that if you have two
75 tape devices, they will not share property values.
76 Properties are specified in amanda.conf with the device-property
78 parameter. The syntax looks like this:
79 device_property "FROBNICATOR_PATH" "/var/frobd/state"
81 device_property "BYTES_PER_FORTNIGHT" "128k"
82 device_property "USE_QUBITS" "no"
83 Both the property name and the property value are always quoted.
85 Property names, like Amanda configuration parameters, are not
86 case-sensitive, and - (dash) and _ (underscore) may be used
87 interchangeably. String values are given as simple strings, like
88 FROBNICATOR_PATH in the example above. Integer values can be specified
89 with any of the suffixes given in the "VALUE SUFFIXES" section of
90 amanda.conf(5), like BYTES_PER_FORTNIGHT, above. Boolean values can be
91 specified using the same names as in amanda.conf(5), like USE_QUBITS,
92 above. Some properties have special formats, as described below.
93 Some properties are set based on other configuration values, such as
95 tapetype parameters. These special cases are detailed under the
96 appropriate property, below.
97 The order in which device properties are set is as follows:
99 1. Tapetype parameters (including length, blocksize, and
101 readblocksize) are translated into device properties and set
102 accordingly.
103 2. Device properties from any device_property configuration parameters
105 are set, in the order they appear in the configuration file.
106 Properties described as read-only are not accessible to users. They are
108 listed here for completeness.
109 COMMON PROPERTIES
111 Note that some of these properties are currently unused, and present
112 only for future expansion. Not all devices implement all of these
113 properties.
114 APPENDABLE
116 (read-only) This boolean property indicates whether this device
118 supports appending data to volumes.
119 BLOCK_SIZE
121 (read-write) This property gives the block size, in bytes, that
123 will be used to write to the device. The usual suffixes ("kbytes",
124 etc.) are allowed. The tapetype parameter blocksize sets this
125 property.
126 CANONICAL_NAME
128 (read-only) This property contains the full canonical name for
130 this device. This name may not be the same as the user-supplied
131 name, but is a valid name by which to access this device.
132 COMMENT
134 (read-write) This string property is entirely for the user´s
136 convenience. It is supported by all devices, but no device
137 interprets its value in any way.
138 COMPRESSION
140 (read-write) This boolean property represents the compression
142 status of the device, and can be used to enable and disable such
143 compression. This applies mostly to tape devices, although many
144 tape devices do not support setting compression from software.
145 COMPRESSION_RATE
147 (read-only) This property gives the compression rate, as a decimal
149 ratio. It may be a measured value over some unspecified period or
150 a simple estimate.
151 CONCURRENCY
153 (read-only) This property indicates the level of concurrent access
155 that this device supports.
156 FREE_SPACE
158 (read-only) This property gives the amount of free space available
160 on the current volume, if known. This is often an estimate; for
161 example, tape devices can only estimate the amount of tape left on
162 a spool.
163 FULL_DELETION
165 (read-only) This property indicates whether the device supports
167 erasing the entire volume. Aside from S3 and VFS, most devices
168 cannot support this feature.
169 MAX_BLOCK_SIZE
171 (read-only) This property gives the maximum block size this device
173 can support. See BLOCK SIZES, below.
174 MEDIUM_ACCESS_TYPE
176 (read-only) This property gives the type of the media in the
178 device: read only, WORM (Write Once, Read Many), read/write, or
179 write only. Write-only devices do not support recovery, but the
180 data are not necessarily thrown out.
181 MIN_BLOCK_SIZE
183 (read-write) This property gives the minimum block size this
185 device can support. See BLOCK SIZES, below.
186 MAX_VOLUME_USAGE
188 (read-write) On devices that support it, this property will limit
190 the total amount of data written to a volume; attempts to write
191 beyond this point will cause the device to simulate "out of space."
192 Zero means no limit. The tapetype parameter length sets this
193 property.
194 PARTIAL_DELETION
196 (read-only) This property indicates whether the device supports
198 deletion of specific files. Aside from linear tapes and S3, most
199 devices can support this feature. It is currently unused by
200 Amanda.
201 STREAMING
203 (read-only) This property gives the streaming requirement for this
205 device. For example, tape drives often require a steady supply of
206 data to avoid shoe-shining, while disk devices have no such
207 requirement.
208 VERBOSE
210 (read-write) If this boolean property is set, then the device will
212 produce verbose debugging output. This property is not recognized
213 by most devices.
214 BLOCK SIZES
216 Amanda writes device data in blocks. On most devices the block
217 boundaries are embedded in the media along with the data itself, so
218 subsequent reads must use the same block sizes. On tape devices, the
219 block size is dictated by the capabilities of the hardware -- buffer
220 sizes, physical format, and so on.
221 Amanda has historically supported a single, fixed block size -- usually
223 32k. The Device API adds the ability to specify a block size at
224 runtime, using the BLOCK_SIZE property. Devices provide MIN_BLOCK_SIZE
225 and MAX_BLOCK_SIZE as a guide to the range of acceptable block sizes.
226 Note that this does not imply that all sizes in the range
227 MIN_BLOCK_SIZE - MAX_BLOCK_SIZE are available -- the device may require
228 that block sizes are even multiples of some power of two, for example.
229 Consult the documentation for your hardware and operating system for
230 more information.
231 Most devices are flexible enough to read a volume using a different
233 block size than that with which it was written. This can be useful when
234 handling old volumes written with a smaller blocksize, or volumes of
235 unknown blocksize. Unfortunately, some tape devices do not detect
236 oversized blocks correctly, and may lose data if the configured block
237 size is smaller than the volume´s block size. The tape device driver
238 has a READ_BLOCK_SIZE property which specifies the minimum buffer size
239 that will be allocated for reads from tape. If the hardware supports
240 it, setting this property allows Amanda to correctly read from tapes
241 written with any blocksize less than or equal to READ_BLOCK_SIZE.
242 Note
244 The RAIT device does not support flexible block sizes, as its
245 parity algorithm requires that all child devices have the same,
246 fixed block size.
247
249 This section lists the device drivers included with Amanda, and basic
250 instructions for using them. For complete How-To information, consult
251 the Amanda wiki at http://wiki.zmanda.com.
252 Null Device
254 tapedev "null:"
255 The null device driver only supports writing, and discards all data. It
257 is generally only useful for testing purposes.
258 RAIT Device
260 tapedev "rait:tape:/dev/rmt/tps0d{4,5,6}n"
261 The RAIT device driver mirrors or stripes data over multiple "child"
263 devices. The child devices are specified using a shell-like syntax,
264 where alternatives are enclosed in braces and separated by commas.
265 Braces and commas can be escaped with a backslash. Note that the
266 backslash itself must be escaped in most contexts. For example:
267 tapedev "rait:{commandev:foo\\,bar,bracedev:foo\\}bar}"
269 With two child devices, the RAIT device driver mirrors data such that
271 the two devices contain identical data and can be used singly for
272 recovery. With more than two devices, the RAIT device "stripes" data
273 across all but one device and writes a parity block to the final
274 device, usable for data recovery in the event of a device or volume
275 failure. The RAIT device scales its blocksize as necessary to match the
276 number of children that will be used to store data.
277 When a child device is known to have failed, the RAIT device should be
279 reconfigured to replace that device with the text "ERROR", e.g.,
280 tapedev "rait:{tape:/dev/st0,ERROR,tape:/dev/st2}"
282 This will cause the RAIT device to start up in degraded mode,
283 reconstructing the data from the missing device.
284 Like ordinary RAID drivers, the RAIT device driver can automatically
286 enter degraded mode when one of its child devices fails. However, the
287 RAIT device cannot automatically recover from any write error nor write
288 any data in degraded mode. When reading, certain errors may be fatal
289 (rather than causing degraded mode). And in any case, labels on all
290 volumes must initially match (labeled or otherwise). If you have lost
291 one volume from a set, explicitly start the device in degraded mode as
292 described above.
293 Child Device Block Sizes
295 The RAIT device driver requires that all of its child devices use the
296 same block size. If no block sizes are specified, the driver selects
297 the block size closest to 32k that is within the MIN_BLOCK_SIZE -
298 MAX_BLOCK_SIZE range of all child devices, and calculates its own
299 blocksize according to the formula rait_blocksize = child_blocksize *
300 (num_children - 1). If a block size is specified for the RAIT device,
301 then it calculates its child block sizes according to the formula
302 child_blocksize = rait_blocksize / (num_children - 1). Either way, it
303 sets the BLOCK_SIZE property of each child device accordingly.
304 S3 Device
306 tapedev "s3:foocorp-backups/DailySet1-"
307 device_property "S3_ACCESS_KEY" "MYACCESSKEY"
308 device_property "S3_SECRET_KEY" "MYSECRETKEY"
309 The S3 device driver uploads data to the Amazon S3 "storage cloud". Its
311 device name is a slash-sparated combination of bucket name and prefix:
312 "s3:BUCKET/PREFIX". Since buckets must be unique across all Amazon S3
313 users, and since the number of buckets allowed to each user is limited,
314 the driver can store multiple Amanda volumes in a single S3 bucket,
315 distinguished by prefix. The prefix and slash can be omitted if they
316 are not needed: "s3:BUCKET".
317 The access and secret keys used to authenticate to Amazon S3 are
319 provided as properties.
320 The S3 device driver stores each block in a distinct S3 object. Due to
322 high HTTP overhead for each request, use of larger than normal block
323 sizes (> 1 megabyte) is reccomended with the S3 device.
324 Amanda automatically creates a bucket when writing, if the bucket
326 doesn´t already exist. At that time, it specifies where Amazon should
327 store the data based on the S3_BUCKET_LOCATION property. Currently,
328 there are two valid settings: "*" (any location, probably US) and "EU"
329 (Europe). If this property is not set, Amazon´s default value of "*" is
330 used. The bucket location has both billing and legal concerns, so you
331 are encouraged to consult Amazon´s documentation for details.
332 Amazon does not permit changes to bucket locations, so this is a
334 permanent specification. If the bucket already exists and the property
335 is set, then Amanda checks the property against the location of the
336 bucket, and produces an error if they do not match.
337 Note
339 If a location constraint is set, the bucket name must consist only
340 of lower-case letters, numbers, dashes, and dots.
341 This driver supports the VERBOSE property, but use it carefully -- it
343 produces a great deal of output, and may cause spurious failures by
344 filling your debug log partition. Its logging is generally only useful
345 for developers chasing down a problem in communications with Amazon´s
346 servers.
347 Device-Specific Properties
349 In addition to the common properties, the S3 device supports the
350 properties listed in this section.
351 Most Amanda devices work just fine without any properties, but not the
353 S3 device. A typical S3 configuration will have an access key and
354 secret key specified:
355 device_property "S3_ACCESS_KEY" "27D3B8C6C4E7AA423C2B37C72A0D22C8"
357 device_property "S3_SECRET_KEY" "agphc2Q7Zmxragphc2RmO2xragpzZGY7a2xqCgr"
358 MAX_RECV_SPEED
360 (read-write) Maximum speed, in bytes per second, that this device
362 will receive data from S3. If the average speed exceeds this
363 value, the device will stop reading long enough to bring the
364 average below this value.
365 MAX_SEND_SPEED
367 (read-write) Maximum speed, in bytes per second, that this device
369 will send data to S3. If the average speed exceeds this value, the
370 device will stop writing long enough to bring the average below
371 this value.
372 S3_ACCESS_KEY
374 (read-write) This property gives the Amazon S3 access key used to
376 access the service.
377 S3_BUCKET_LOCATION
379 (read-write) Location constraint for buckets on Amazon S3.
381 Currently, it can be set to "", for no constraint (i.e. store data
382 in the US), or "EU" (i.e. store data in the EU). See Amazon´s
383 documentation for details and latest information
384 SSL_CA_INFO
386 (read-write) Path to CA certificate to use to verify the identity
388 of the S3 server. Only applicable when SSL/TLS is in use. The
389 certificate should be in PEM format if OpenSSL or GnuTLS is being
390 used with libcurl. Multiple certificates can be bundled together
391 simply by concatenating them. If NSS is being used, then it is the
392 directory that the database resides in. The value is passed to
393 curl_easy_setopt(3) as CURLOPT_CAINFO.
394 S3_SECRET_KEY
396 (read-write) This property gives the Amazon S3 secret key used to
398 access the service.
399 S3_STORAGE_CLASS
401 (read-write) Storage class for new objects, currently one of
403 "STANDARD" (the default) or "REDUCED_REDUNDANCY" (cheaper, but less
404 redundant). See :
405 http://docs.amazonwebservices.com/AmazonS3/latest/dev/index.html?DataDurability.html
406 for the most up-to-date list.
407 S3_SSL
409 (read-write) Whether or not to use SSL/TLS to secure
411 communications with Amazon S3.
412 S3_USER_TOKEN
414 (read-write) This property specifies the user token for Amanda
416 Enterprise Edition customers.
417 VERBOSE
419 (read-write) If true, verbose data about each HTTP transaction is
421 sent to the debug log.
422 Tape Device
424 tapedev "tape:/dev/nst0"
425 The tape device driver interacts with a tape drive. The device uses the
427 operating system´s built-in tape support, which is generally similar to
428 that available via the command-line utilities dd(1) and mt(1).
429 The tape device name should specify a path to the operating system´s
431 device file.
432 Device-Specific Properties
434 Most of these properties are automatically detected, but can be
435 overridden in the configuration file if the autodetection fails. Note
436 that tape drives are required to at least support the MTREW (rewind)
437 operation; all other operations can be emulated with the MTREW and read
438 data operations.
439 BROKEN_GMT_ONLINE
441 (read-write) Set this boolean property if the system´s GMT_ONLINE
443 macro gives incorrect results. This is currently true for the
444 Linux IDE-TAPE driver.
445 BSF
447 (read-write) This boolean property specifies whether the device
449 driver may execute the MTBSF operation (backward seek file).
450 BSF_AFTER_EOM
452 (read-write) This boolean property specifies whether the device
454 driver should execute an MTBSF (backward seek file) operation
455 after
456 MTEOM (seek to end of recorded data) in order to append.
457 BSR
459 (read-write) This boolean property specifies whether the device
461 driver may use the MTBSR operation (backward seek record).
462 EOM
464 (read-write) This boolean property specifies whether the device
466 driver may use the MTEOM command (seek to end of recorded data).
467 FINAL_FILEMARKS
469 (read-write) This integer property gives the number of filemarks
471 that should be written at EOD. It is usually 1 or 2.
472 FSF
474 (read-write) This boolean property specifies whether the device
476 driver may use the MTFSF operation (forward seek file).
477 FSF_AFTER_FILEMARK
479 (read-write) This boolean property specifies whether the device
481 driver needs a FSF to go the next file after the filemark is read.
482 Default to "TRUE" on Solaris and "FALSE" on all others machines.
483 FSR
485 (read-write) This boolean property specifies whether the device
487 driver may use the MTFSR operation (forward seek record).
488 NONBLOCKING_OPEN
490 (read-write) Set this boolean property to "true" if O_NONBLOCK
492 must be used on the open call. Default to "true" on Linux and
493 "false" on all others machines. Witout it, Linux wait for a few
494 seconds if no tape are loaded. Solaris have strange error it is set
495 to "yes".
496 READ_BLOCK_SIZE
498 (read-write) This property (previously known as READ_BUFFER_SIZE)
500 specifies the block size that will be used for reads; this should
501 be large enough to contain any block that may be read from the
502 device (for example, from a tape containing variable-sized blocks),
503 and must be larger than BLOCK_SIZE. This property is most often
504 used when overwriting tapes using a new, smaller block size.
505 The tapetype parameter READBLOCKSIZE sets this property. See
506 BLOCK SIZES, above.
507 NDMP Device
509 tapedev "ndmp:my.filer.com:10000@st1"
510 device_property "NDMP_USERNAME" "jimmy"
511 device_property "NDMP_PASSWORD" "thelock"
512 This device enables Amanda to communicate with a tape service on an
514 NDMP server. The device name specifies the hostname and optionally the
515 TCP port of the NDMP server, followed by the name of the tape device on
516 the server (st1 in the example above).
517 Device-Specific Properties
519 The properties NDMP_USERNAME and NDMP_PASSWORD set the username and
520 password with which to access the NDMP server. The default for both is
521 "ndmp".
522 NDMP_AUTH
524 (read-write) Authentication method to use to connect to the NDMP
526 server. One of "md5" (default), "text", "none" (for an empty
527 authentication attempt) or "void" (for no authentication attempt at
528 all).
529 NDMP_PASSWORD
531 (read-write) Password for md5 or text authentications.
533 NDMP_USERNAME
535 (read-write) Username for md5 or text authentications.
537 VFS Device
539 tapedev "file:/path/to/vtape"
540 The VFS device driver stores data on a UNIX filesystem. Note that
542 although one typically uses the VFS device driver to store data on hard
543 disks, the driver does not interface with any hardware on a block
544 level.
545 The device name specifies a path to a directory which must exist and
547 contain a "data/" subdirectory. Each tape file is stored as a distinct
548 file in this directory, the name of which reflects the Amanda header in
549 the tape file. Block boundaries are not maintained: the driver supports
550 reads of arbitrary size, regardless of the blocksize used to write the
551 data.
552 DVD-RW Device
554 tapedev "dvdrw:/var/cache/amanda/dvd-cache:/dev/scd0"
555 device_property "DVDRW_MOUNT_POINT" "/media/dvd"
556 device_property "DVDRW_KEEP_CACHE" "false"
557 device_property "DVDRW_UNLABELLED_WHEN_UNMOUNTABLE" "true"
558 The DVD-RW device driver reads and writes optical media such as DVDs
560 and CDs. The device name must specify a cache directory for data to be
561 temporarily stored, followed by the operating system name for the
562 optical drive. The cache directory must contain a "data/" subdirectory.
563 The DVDRW_MOUNT_POINT property is required, and specifies a directory
565 where the optical media can be mounted. This directory must be
566 configured to enable non-root users to mount the optical media. On
567 Linux, that means a line similar to the following in /etc/fstab:
568 /dev/scd0 /media/dvd auto ro,user,noauto 0 0
569 Note the "user" option.
571 When writing data, the device acts as a VFS device using the given
573 cache directory. On completion of writing the tape, the cache directory
574 is written to optical media. The DVDRW_KEEP_CACHE property controls
575 whether the cache contents are immediately deleted. When reading, the
576 optical media is first mounted and read as a VFS device.
577 Attempting to mount unformatted media or media that is formatted but
579 contains no filesystem will usually result in an error. The boolean
580 DVDRW_UNLABELLED_WHEN_UNMOUNTABLE property specifies whether media that
581 cannot be mounted should be treated as an empty, unlabelled volume when
582 attempting to read the volume label. It is necessary to set this
583 property to "true" when labelling such media.
584 Device-Specific Properties
586 The properties DVDRW_GROWISOFS_COMMAND, DVDRW_MOUNT_COMMAND and
587 DVDRW_UMOUNT_COMMAND specify alternative commands for writing, mounting
588 and unmounting optical media. The default is to find the programs using
589 the PATH environment variable.
590 The DVDRW_MOUNT_POINT property is required. Other properties are
592 optional.
593 DVDRW_KEEP_CACHE
595 (read-write) Set this boolean property to "true" if the disk cache
597 directory should be kept after successfully writing tape data to
598 optical media. The default is false, which causes the cache
599 contents to be deleted immediately after a successful write
600 operation.
601 DVDRW_MOUNT_POINT
603 (read-write) This property specifies the filesystem mount point
605 for the optical media. Non-root users must be able to mount optical
606 media by invoking "mount" and specifying this mount point.
607 DVDRW_UNLABELLED_WHEN_UNMOUNTABLE
609 (read-write) Treat unmountable media as empty, unlabelled media.
611 This is necessary when attempting to label freshly formatted media.
612 DVDRW_GROWISOFS_COMMAND
614 (read-write) The command to invoke to burn the DVD.
616 DVDRW_MOUNT_COMMAND
618 (read-write) The command to invoke to mount the DVD.
620 DVDRW_UMOUNT_COMMAND
622 (read-write) The command to invoke to unmount the DVD.
624
626 amanda(8), amanda.conf(5)
627 The Amanda Wiki: : http://wiki.zmanda.com/
629
631 Ian Turner <ian@zmanda.com>
632 Zmanda, Inc. (http://www.zmanda.com)
633 Dustin J. Mitchell <dustin@zmanda.com>
635 Zmanda, Inc. (http://www.zmanda.com)
636Amanda 3.1.3 10/04/2010 AMANDA-DEVICES(7)