1AMANDA-DEVICES(7)                 Miscellanea                AMANDA-DEVICES(7)
2
3
4

NAME

6       amanda-devices - Configuring and Using Amanda Devices
7

DESCRIPTION

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
13       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
17       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

SPECIFYING DEVICES

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
29       Devices are described in amanda.conf(5) with "device" sections, e.g.,
30
31       define device top_drive {
32           tapedev "tape:/dev/nst0"
33           device_property "BLOCK_SIZE" "131072"
34       }
35       A device defininition creates a device "alias", in this case named
36       top_drive, which can then be named in the global tapedev parameter:
37
38       tapedev "top_drive"
39
40       The global tapedev parameter can also specify a literal device name.
41       For example,
42
43       tapedev "file:/amdisks"
44       is equivalent to
45
46       tapedev "default"
47       define device default {
48           tapedev "file:/amdisks"
49       }
50       Device properties specified outside of any device definition apply to
51       all devices. This syntax is provided mainly for backward compatibility,
52       and for simple Amanda configurations. Note that there is no way to
53       provide properties specific to a device without defining a device
54       alias.
55
56       See amanda.conf(5) for more information on Amanda configuration.
57

DEVICES

59       This section lists the device drivers included with Amanda, and basic
60       instructions for using them. For complete How-To information, consult
61       the Amanda wiki at http://wiki.zmanda.com.
62
63   Null Device
64       tapedev "null:"
65
66       The null device driver only supports writing, and discards all data. It
67       is generally only useful for testing purposes.
68
69   RAIT Device
70       tapedev "rait:tape:/dev/rmt/tps0d{4,5,6}n"
71
72       The RAIT device driver mirrors or stripes data over multiple "child"
73       devices. The child devices are specified using a shell-like syntax,
74       where alternatives are enclosed in braces and separated by commas.
75
76       With two child devices, the RAIT device driver mirrors data such that
77       the two devices contain identical data and can be used singly for
78       recovery. With more than two devices, the RAIT device "stripes" data
79       across all but one device and writes a parity block to the final
80       device, usable for data recovery in the event of a device or volume
81       failure. The RAIT device scales its blocksize as necessary to match the
82       number of children that will be used to store data.
83
84       When a child device is known to have failed, the RAIT device should be
85       reconfigured to replace that device with the text "ERROR", e.g.,
86
87       tapedev "rait:{tape:/dev/st0,ERROR,tape:/dev/st2}"
88       This will cause the RAIT device to start up in degraded mode,
89       reconstructing the data from the missing device.
90
91       Like ordinary RAID drivers, the RAIT device driver can automatically
92       enter degraded mode when one of its child devices fails. However, the
93       RAIT device cannot automatically recover from any write error nor write
94       any data in degraded mode. When reading, certain errors may be fatal
95       (rather than causing degraded mode). And in any case, labels on all
96       volumes must initially match (labeled or otherwise). If you have lost
97       one volume from a set, explicitly start the device in degraded mode as
98       described above.
99
100   Child Device Block Sizes
101       The RAIT device driver requires that all of its child devices use the
102       same block size. If no block sizes are specified, the driver selects
103       the block size closest to 32k that is within the MIN_BLOCK_SIZE -
104       MAX_BLOCK_SIZE range of all child devices, and calculates its own
105       blocksize according to the formula rait_blocksize = child_blocksize *
106       (num_children - 1). If a block size is specified for the RAIT device,
107       then it calculates its child block sizes according to the formula
108       child_blocksize = rait_blocksize / (num_children - 1). Either way, it
109       sets the BLOCK_SIZE property of each child device accordingly.
110
111   S3 Device
112       tapedev "s3:foocorp-backups/DailySet1-"
113       device_property "S3_ACCESS_KEY" "MYACCESSKEY"
114       device_property "S3_SECRET_KEY" "MYSECRETKEY"
115
116       The S3 device driver uploads data to the Amazon S3 "storage cloud". Its
117       device name is a slash-sparated combination of bucket name and prefix:
118       "s3:BUCKET/PREFIX". Since buckets must be unique across all Amazon S3
119       users, and since the number of buckets allowed to each user is limited,
120       the driver can store multiple Amanda volumes in a single S3 bucket,
121       distinguished by prefix. The prefix and slash can be omitted if they
122       are not needed: "s3:BUCKET".
123
124       The access and secret keys used to authenticate to Amazon S3 are
125       provided as properties.
126
127       The S3 device driver stores each block in a distinct S3 object. Due to
128       high HTTP overhead for each request, use of larger than normal block
129       sizes (> 1 megabyte) is reccomended with the S3 device.
130
131       You can control where your data is physically stored by Amazon S3 using
132       a location constraint. Setting this affects can affect both billing and
133       legal concerns, so you are encouraged to consult Amazon´s documentation
134       for details.
135
136       To control location constraints, set the S3_BUCKET_LOCATION property.
137       Currently, there are two valid settings: "" (any location) and "EU"
138       (Europe). If the S3_BUCKET_LOCATION is set, Amanda will check to make
139       sure that the setting agrees with the constraint currently on the
140       bucket.
141
142   Tape Device
143       tapedev "tape:/dev/nst0"
144
145       The tape device driver interacts with a tape drive. The device uses the
146       operating system´s built-in tape support, which is generally similar to
147       that available via the command-line utilities dd(1) and mt(1).
148
149       The tape device name should specify a path to the operating system´s
150       device file.
151
152   VFS Device
153       tapedev "file:/path/to/vtape"
154
155       The VFS device driver stores data on a UNIX filesystem. Note that
156       although one typically uses the VFS device driver to store data on hard
157       disks, the driver does not interface with any hardware on a block
158       level.
159
160       The device name specifies a path to a directory which must exist and
161       contain a "data/" subdirectory. Each tape file is stored as a distinct
162       file in this directory, the name of which reflects the Amanda header in
163       the tape file. Block boundaries are not maintained: the driver supports
164       reads of arbitrary size, regardless of the blocksize used to write the
165       data.
166

PROPERTIES

168       Device drivers use properties as a generic means to interact with other
169       parts of Amanda. Some properties are set by the device driver and used
170       by Amanda to determine how its devices should be used. Other properties
171       can be set by Amanda or by the user to influence the driver´s behavior.
172       Properties are set for a particular device, so that if you have two
173       tape devices, they will not share property values.
174
175       Properties are specified in amanda.conf with the device-property
176       parameter. The syntax looks like this:
177
178       device_property "FROBNICATOR_PATH" "/var/frobd/state"
179       device_property "BYTES_PER_FORTNIGHT" "128k"
180       device_property "USE_QUBITS" "no"
181
182       Both the property name and the property value are always quoted. String
183       values are given as simple strings, like FROBNICATOR_PATH in the
184       example above. Integer values can be specified with any of the suffixes
185       given in the "VALUE SUFFIXES" section of amanda.conf(5), like
186       BYTES_PER_FORTNIGHT, above. Boolean values can be specified as any of
187       "true", "yes", "1", "0", "no", "false", like USE_QUBITS, above. Some
188       properties have special formats, as described below.
189
190       Some properties are set based on other configuration values, such as
191       tapetype parameters. These special cases are detailed under the
192       appropriate property, below.
193
194       The order in which device properties are set is as follows:
195
196        1. Tapetype parameters (including length, blocksize, and
197           readblocksize) are translated into device properties and set
198           accordingly.
199
200        2. Device properties from any device_property configuration parameters
201           are set, in the order they appear in the configuration file.
202
203       Properties described as read-only are not accessible to users. They are
204       listed here for completeness.
205
206   COMMON PROPERTIES
207       Note that some of these properties are currently unused, and present
208       only for future expansion. Not all devices implement all of these
209       properties.
210
211       APPENDABLE
212
213            (read-only) This boolean property indicates whether this device
214           supports appending data to volumes.
215
216       BLOCK_SIZE
217
218            (read-write) This property gives the block size, in bytes, that
219           will be used to write to the device.  The usual suffixes ("kbytes",
220           etc.) are allowed.  The tapetype parameter blocksize sets this
221           property.
222
223       CANONICAL_NAME
224
225            (read-only) This property contains the full canonical name for
226           this device.  This name may not be the same as the user-supplied
227           name, but is a valid name by which to access this device.
228
229       COMPRESSION
230
231            (read-write) This boolean property represents the compression
232           status of the device, and can be used to enable and disable such
233           compression.  This applies mostly to tape devices, although many
234           tape devices do not support setting compression from software.
235
236       COMPRESSION_RATE
237
238            (read-only) This property gives the compression rate, as a decimal
239           ratio.  It may be a measured value over some unspecified period or
240           a simple estimate.
241
242       CONCURRENCY
243
244            (read-only) This property indicates the level of concurrent access
245           that this device supports.
246
247       FREE_SPACE
248
249            (read-only) This property gives the amount of free space available
250           on the current volume, if known.  This is often an estimate; for
251           example, tape devices can only estimate the amount of tape left on
252           a spool.
253
254       MAX_BLOCK_SIZE
255
256            (read-only) This property gives the maximum block size this device
257           can support.  See BLOCK SIZES, below.
258
259       MEDIUM_ACCESS_TYPE
260
261            (read-only) This property gives the type of the media in the
262           device: read only, WORM (Write Once, Read Many), read/write, or
263           write only.  Write-only devices do not support recovery, but the
264           data are not necessarily thrown out.
265
266       MIN_BLOCK_SIZE
267
268            (read-write) This property gives the minimum block size this
269           device can support.  See BLOCK SIZES, below.
270
271       MAX_VOLUME_USAGE
272
273            (read-write) On devices that support it, this property will limit
274           the total amount of data written to a volume; attempts to write
275           beyond this point will cause the device to simulate "out of space."
276           Zero means no limit.  The tapetype parameter length sets this
277           property.
278
279       PARTIAL_DELETION
280
281            (read-only) This property indicates whether the device supports
282           deletion of specific files.  Aside from linear tapes, most devices
283           can support this feature.  It is currently unused by Amanda.
284
285       STREAMING
286
287            (read-only) This property gives the streaming requirement for this
288           device.  For example, tape drives often require a steady supply of
289           data to avoid shoe-shining, while disk devices have no such
290           requirement.
291
292       VERBOSE
293
294            (read-write) If this boolean property is set, then the device will
295           produce verbose debugging output.  This property is not recognized
296           by all devices.
297
298   BLOCK SIZES
299       Amanda writes device data in blocks. On most devices the block
300       boundaries are embedded in the media along with the data itself, so
301       subsequent reads must use the same block sizes. On tape devices, the
302       block size is dictated by the capabilities of the hardware -- buffer
303       sizes, physical format, and so on.
304
305       Amanda has historically supported a single, fixed block size -- usually
306       32k. The Device API adds the ability to specify a block size at
307       runtime, using the BLOCK_SIZE property. Devices provide MIN_BLOCK_SIZE
308       and MAX_BLOCK_SIZE as a guide to the range of acceptable block sizes.
309       Note that this does not imply that all sizes in the range
310       MIN_BLOCK_SIZE - MAX_BLOCK_SIZE are available -- the device may require
311       that block sizes are even multiples of some power of two, for example.
312       Consult the documentation for your hardware and operating system for
313       more information.
314
315       Most devices are flexible enough to read a volume using a different
316       block size than that with which it was written. This can be useful when
317       handling old volumes written with a smaller blocksize, or volumes of
318       unknown blocksize. Unfortunately, some tape devices do not detect
319       oversized blocks correctly, and may lose data if the configured block
320       size is smaller than the volume´s block size. The tape device driver
321       has a READ_BUFFER_SIZE property which specifies the minimum buffer size
322       that will be allocated for reads from tape. If the hardware supports
323       it, setting this property allows Amanda to correctly read from tapes
324       written with any blocksize less than or equal to READ_BUFFER SIZE.
325
326           Note
327           The RAIT device does not support flexible block sizes, as its
328           parity algorithm requires that all child devices have the same,
329           fixed block size.
330
331   DRIVER-SPECIFIC PROPERTIES
332   S3 Device
333       S3_ACCESS_KEY
334
335            (read-write) This property gives the Amazon S3 access key used to
336           access the service.
337
338       S3_BUCKET_LOCATION
339
340            (read-write) Location constraint for buckets on Amazon S3.
341           Currently, it can be set to "", for no constraint (i.e. store data
342           in the US), or "EU" (i.e. store data in the EU).  See Amazon´s
343           documentation for details and latest information
344
345       S3_SECRET_KEY
346
347            (read-write) This property gives the Amazon S3 secret key used to
348           access the service.
349
350       S3_SSL
351
352            (read-write) Whether or not to use SSL/TLS to secure
353           communications with Amazon S3.
354
355       S3_USER_TOKEN
356
357            (read-write) This property specifies the user token for Amanda
358           Enterprise Edition customers.
359
360       Most Amanda devices work just fine without any properties, but not the
361       S3 device. A typical S3 configuration will have an access key and
362       secret key specified:
363
364       device_property "S3_ACCESS_KEY" "27D3B8C6C4E7AA423C2B37C72A0D22C8"
365       device_property "S3_SECRET_KEY" "agphc2Q7Zmxragphc2RmO2xragpzZGY7a2xqCgr"
366
367
368   Tape Device
369       Most of these properties are automatically detected, but can be
370       overridden in the configuration file if the autodetection fails. Note
371       that tape drives are required to at least support the MTREW (rewind)
372       operation; all other operations can be emulated with the MTREW and read
373       data operations.
374
375       BROKEN_GMT_ONLINE
376
377            (read-write) Set this boolean property if the system´s GMT_ONLINE
378           macro gives incorrect results.  This is currently true for the
379           Linux IDE-TAPE driver.
380
381       BSF
382
383            (read-write) This boolean property specifies whether the device
384            driver may execute the MTBSF operation (backward seek file).
385
386       BSF_AFTER_EOM
387
388            (read-write) This boolean property specifies whether the device
389            driver should execute an MTBSF (backward seek file) operation
390           after
391            MTEOM (seek to end of recorded data) in order to append.
392
393       BSR
394
395            (read-write) This boolean property specifies whether the device
396            driver may use the MTBSR operation (backward seek record).
397
398       EOM
399
400            (read-write) This boolean property specifies whether the device
401            driver may use the MTEOM command (seek to end of recorded data).
402
403       FINAL_FILEMARKS
404
405            (read-write) This integer property gives the number of filemarks
406           that should be written at EOD.  It is usually 1 or 2.
407
408       FSF
409
410            (read-write) This boolean property specifies whether the device
411           driver may use the MTFSF operation (forward seek file).
412
413       FSF_AFTER_FILEMARK
414
415            (read-write) This boolean property specifies whether the device
416           driver needs a FSF to go the next file after the filemark is read.
417           Default to "TRUE" on Solaris and "FALSE" on all others machines.
418
419       FSR
420
421            (read-write) This boolean property specifies whether the device
422           driver may use the MTFSR operation (forward seek record).
423
424       NONBLOCKING_OPEN
425
426            (read-write) Set this boolean property to "true" if O_NONBLOCK
427           must be used on the open call. Default to "true" on Linux and
428           "false" on all others machines. Witout it, Linux wait for a few
429           seconds if no tape are loaded. Solaris have strange error it is set
430           to "yes".
431
432       READ_BUFFER_SIZE
433
434            (read-write) This property specifies the minimum buffer size that
435           will be used for reads; this should be large enough to contain any
436           block that may be read from the device, and must be larger than
437           BLOCK_SIZE.  This property exists for tape devices which cannot
438           determine the size of on-tape blocks, or which may discard data
439           which overflows a small buffer.  The tapetype parameter
440           READBLOCKSIZE sets this property.  See BLOCK SIZES, above.
441

SEE ALSO

443       amanda.conf(5),
444

AUTHORS

446       Ian Turner <ian@zmanda.com>
447           Zmanda, Inc. (http://www.zmanda.com)
448
449       Dustin J. Mitchell <dustin@zmanda.com>
450           Zmanda, Inc. (http://www.zmanda.com)
451
452
453
454Amanda 2.6.1p2                    11/05/2009                 AMANDA-DEVICES(7)
Impressum