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 are described in amanda.conf(5) with "device" sections, e.g.,
30 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 tapedev "top_drive"
39 The global tapedev parameter can also specify a literal device name.
41 For example,
42 tapedev "file:/amdisks"
44 is equivalent to
45 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 See amanda.conf(5) for more information on Amanda configuration.
57
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 Null Device
64 tapedev "null:"
65 The null device driver only supports writing, and discards all data. It
67 is generally only useful for testing purposes.
68 RAIT Device
70 tapedev "rait:tape:/dev/rmt/tps0d{4,5,6}n"
71 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 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 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 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 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 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 S3 Device
112 tapedev "s3:foocorp-backups/DailySet1-"
113 device_property "S3_ACCESS_KEY" "MYACCESSKEY"
114 device_property "S3_SECRET_KEY" "MYSECRETKEY"
115 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 The access and secret keys used to authenticate to Amazon S3 are
125 provided as properties.
126 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 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 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 Tape Device
143 tapedev "tape:/dev/nst0"
144 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 The tape device name should specify a path to the operating system´s
150 device file.
151 VFS Device
153 tapedev "file:/path/to/vtape"
154 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 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
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 Properties are specified in amanda.conf with the device-property
176 parameter. The syntax looks like this:
177 device_property "FROBNICATOR_PATH" "/var/frobd/state"
179 device_property "BYTES_PER_FORTNIGHT" "128k"
180 device_property "USE_QUBITS" "no"
181 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 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 The order in which device properties are set is as follows:
195 1. Tapetype parameters (including length, blocksize, and
197 readblocksize) are translated into device properties and set
198 accordingly.
199 2. Device properties from any device_property configuration parameters
201 are set, in the order they appear in the configuration file.
202 Properties described as read-only are not accessible to users. They are
204 listed here for completeness.
205 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 APPENDABLE
212 (read-only) This boolean property indicates whether this device
214 supports appending data to volumes.
215 BLOCK_SIZE
217 (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 CANONICAL_NAME
224 (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 COMPRESSION
230 (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 COMPRESSION_RATE
237 (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 CONCURRENCY
243 (read-only) This property indicates the level of concurrent access
245 that this device supports.
246 FREE_SPACE
248 (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 MAX_BLOCK_SIZE
255 (read-only) This property gives the maximum block size this device
257 can support. See BLOCK SIZES, below.
258 MEDIUM_ACCESS_TYPE
260 (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 MIN_BLOCK_SIZE
267 (read-write) This property gives the minimum block size this
269 device can support. See BLOCK SIZES, below.
270 MAX_VOLUME_USAGE
272 (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 PARTIAL_DELETION
280 (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 STREAMING
286 (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 VERBOSE
293 (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 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 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 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 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 DRIVER-SPECIFIC PROPERTIES
332 S3 Device
333 S3_ACCESS_KEY
334 (read-write) This property gives the Amazon S3 access key used to
336 access the service.
337 S3_BUCKET_LOCATION
339 (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 S3_SECRET_KEY
346 (read-write) This property gives the Amazon S3 secret key used to
348 access the service.
349 S3_SSL
351 (read-write) Whether or not to use SSL/TLS to secure
353 communications with Amazon S3.
354 S3_USER_TOKEN
356 (read-write) This property specifies the user token for Amanda
358 Enterprise Edition customers.
359 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 device_property "S3_ACCESS_KEY" "27D3B8C6C4E7AA423C2B37C72A0D22C8"
365 device_property "S3_SECRET_KEY" "agphc2Q7Zmxragphc2RmO2xragpzZGY7a2xqCgr"
366 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 BROKEN_GMT_ONLINE
376 (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 BSF
382 (read-write) This boolean property specifies whether the device
384 driver may execute the MTBSF operation (backward seek file).
385 BSF_AFTER_EOM
387 (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 BSR
394 (read-write) This boolean property specifies whether the device
396 driver may use the MTBSR operation (backward seek record).
397 EOM
399 (read-write) This boolean property specifies whether the device
401 driver may use the MTEOM command (seek to end of recorded data).
402 FINAL_FILEMARKS
404 (read-write) This integer property gives the number of filemarks
406 that should be written at EOD. It is usually 1 or 2.
407 FSF
409 (read-write) This boolean property specifies whether the device
411 driver may use the MTFSF operation (forward seek file).
412 FSF_AFTER_FILEMARK
414 (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 FSR
420 (read-write) This boolean property specifies whether the device
422 driver may use the MTFSR operation (forward seek record).
423 NONBLOCKING_OPEN
425 (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 READ_BUFFER_SIZE
433 (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
443 amanda.conf(5),
444
446 Ian Turner <ian@zmanda.com>
447 Zmanda, Inc. (http://www.zmanda.com)
448 Dustin J. Mitchell <dustin@zmanda.com>
450 Zmanda, Inc. (http://www.zmanda.com)
451Amanda 2.6.1p2 11/05/2009 AMANDA-DEVICES(7)