Provided by: amanda-common_2.6.1p1-2_i386 bug

NAME

       amanda-devices - Configuring and Using Amanda Devices

DESCRIPTION

       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.

       This is a user-level 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.

       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.

SPECIFYING DEVICES

       Device names take the form TYPE:NODE, where TYPE selects a device
       driver, and NODE provides further information to that driver. The
       syntax for each device driver is given in the corresponding section
       below.

       Devices are described in amanda.conf(5) with "device" sections, e.g.,

       define device top_drive {
           tapedev "tape:/dev/nst0"
           device_property "BLOCK_SIZE" "131072"
       }
       A device defininition creates a device "alias", in this case named
       top_drive, which can then be named in the global tapedev parameter:

       tapedev "top_drive"

       The global tapedev parameter can also specify a literal device name.
       For example,

       tapedev "file:/amdisks"
       is equivalent to

       tapedev "default"
       define device default {
           tapedev "file:/amdisks"
       }
       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.

       See amanda.conf(5) for more information on Amanda configuration.

DEVICES

       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.

   Null Device
       tapedev "null:"

       The null device driver only supports writing, and discards all data. It
       is generally only useful for testing purposes.

   RAIT Device
       tapedev "rait:tape:/dev/rmt/tps0d{4,5,6}n"

       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.

       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.

       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.,

       tapedev "rait:{tape:/dev/st0,ERROR,tape:/dev/st2}"
       This will cause the RAIT device to start up in degraded mode,
       reconstructing the data from the missing device.

       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.

   Child Device Block Sizes
       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 rait_blocksize = child_blocksize *
       (num_children - 1). If a block size is specified for the RAIT device,
       then it calculates its child block sizes according to the formula
       child_blocksize = rait_blocksize / (num_children - 1). Either way, it
       sets the BLOCK_SIZE property of each child device accordingly.

   S3 Device
       tapedev "s3:foocorp-backups/DailySet1-"
       device_property "S3_ACCESS_KEY" "MYACCESSKEY"
       device_property "S3_SECRET_KEY" "MYSECRETKEY"

       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".

       The access and secret keys used to authenticate to Amazon S3 are
       provided as properties.

       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.

       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.

       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.

   Tape Device
       tapedev "tape:/dev/nst0"

       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 name should specify a path to the operating system´s
       device file.

   VFS Device
       tapedev "file:/path/to/vtape"

       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.

       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.

PROPERTIES

       Device drivers use properties 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.

       Properties are specified in amanda.conf with the device-property
       parameter. The syntax looks like this:

       device_property "FROBNICATOR_PATH" "/var/frobd/state"
       device_property "BYTES_PER_FORTNIGHT" "128k"
       device_property "USE_QUBITS" "no"

       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 amanda.conf(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.

       Some properties are set based on other configuration values, such as
       tapetype parameters. These special cases are detailed under the
       appropriate property, below.

       The order in which device properties are set is as follows:

        1. Tapetype parameters (including length, blocksize, and
           readblocksize) are translated into device properties and set
           accordingly.

        2. Device properties from any device_property configuration parameters
           are set, in the order they appear in the configuration file.

       Properties described as read-only are not accessible to users. They are
       listed here for completeness.

   COMMON PROPERTIES
       Note that some of these properties are currently unused, and present
       only for future expansion. Not all devices implement all of these
       properties.

       APPENDABLE

            (read-only) This boolean property indicates whether this device
           supports appending data to volumes.

       BLOCK_SIZE

            (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 blocksize sets this
           property.

       CANONICAL_NAME

            (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.

       COMPRESSION

            (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.

       COMPRESSION_RATE

            (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.

       CONCURRENCY

            (read-only) This property indicates the level of concurrent access
           that this device supports.

       FREE_SPACE

            (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.

       MAX_BLOCK_SIZE

            (read-only) This property gives the maximum block size this device
           can support.  See BLOCK SIZES, below.

       MEDIUM_ACCESS_TYPE

            (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.

       MIN_BLOCK_SIZE

            (read-write) This property gives the minimum block size this
           device can support.  See BLOCK SIZES, below.

       MAX_VOLUME_USAGE

            (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 length sets this
           property.

       PARTIAL_DELETION

            (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.

       STREAMING

            (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.

       VERBOSE

            (read-write) If this boolean property is set, then the device will
           produce verbose debugging output.  This property is not recognized
           by all devices.

   BLOCK SIZES
       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.

       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.

       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.

           Note
           The RAIT device does not support flexible block sizes, as its
           parity algorithm requires that all child devices have the same,
           fixed block size.

   DRIVER-SPECIFIC PROPERTIES
   S3 Device
       S3_ACCESS_KEY

            (read-write) This property gives the Amazon S3 access key used to
           access the service.

       S3_BUCKET_LOCATION

            (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

       S3_SECRET_KEY

            (read-write) This property gives the Amazon S3 secret key used to
           access the service.

       S3_SSL

            (read-write) Whether or not to use SSL/TLS to secure
           communications with Amazon S3.

       S3_USER_TOKEN

            (read-write) This property specifies the user token for Amanda
           Enterprise Edition customers.

       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:

       device_property "S3_ACCESS_KEY" "27D3B8C6C4E7AA423C2B37C72A0D22C8"
       device_property "S3_SECRET_KEY" "agphc2Q7Zmxragphc2RmO2xragpzZGY7a2xqCgr"

   Tape Device
       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.

       BROKEN_GMT_ONLINE

            (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.

       BSF

            (read-write) This boolean property specifies whether the device
            driver may execute the MTBSF operation (backward seek file).

       BSF_AFTER_EOM

            (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.

       BSR

            (read-write) This boolean property specifies whether the device
            driver may use the MTBSR operation (backward seek record).

       EOM

            (read-write) This boolean property specifies whether the device
            driver may use the MTEOM command (seek to end of recorded data).

       FINAL_FILEMARKS

            (read-write) This integer property gives the number of filemarks
           that should be written at EOD.  It is usually 1 or 2.

       FSF

            (read-write) This boolean property specifies whether the device
           driver may use the MTFSF operation (forward seek file).

       FSR

            (read-write) This boolean property specifies whether the device
           driver may use the MTFSR operation (forward seek record).

       READ_BUFFER_SIZE

            (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
           READBLOCKSIZE sets this property.  See BLOCK SIZES, above.

SEE ALSO

       amanda.conf(5),

AUTHORS

       Ian Turner <ian@zmanda.com>
           Zmanda, Inc. (http://www.zmanda.com)

       Dustin J. Mitchell <dustin@zmanda.com>
           Zmanda, Inc. (http://www.zmanda.com)