Imported Upstream version 3.3.0
[debian/amanda] / man / amanda-devices.7
1 '\" t
2 .\"     Title: amanda-devices
3 .\"    Author: Ian Turner <ian@zmanda.com>
4 .\" Generator: DocBook XSL Stylesheets vsnapshot_8273 <http://docbook.sf.net/>
5 .\"      Date: 06/02/2011
6 .\"    Manual: Miscellanea
7 .\"    Source: Amanda 3.3.0
8 .\"  Language: English
9 .\"
10 .TH "AMANDA\-DEVICES" "7" "06/02/2011" "Amanda 3\&.3\&.0" "Miscellanea"
11 .\" -----------------------------------------------------------------
12 .\" * set default formatting
13 .\" -----------------------------------------------------------------
14 .\" disable hyphenation
15 .nh
16 .\" disable justification (adjust text to left margin only)
17 .ad l
18 .\" -----------------------------------------------------------------
19 .\" * MAIN CONTENT STARTS HERE *
20 .\" -----------------------------------------------------------------
21 .SH "NAME"
22 amanda-devices \- Configuring and Using Amanda Devices
23 .SH "DESCRIPTION"
24 .PP
25 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\&.
26 .PP
27 This is a
28 \fIuser\-level\fR
29 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\&.
30 .PP
31 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\&.
32 .SH "SPECIFYING DEVICES"
33 .PP
34 Device names take the form
35 \fITYPE:NODE\fR, where
36 \fITYPE\fR
37 selects a device driver, and
38 \fINODE\fR
39 provides further information to that driver\&. The syntax for each device driver is given in the corresponding section below\&.
40 .PP
41 Devices can be described in
42 \fBamanda.conf\fR(5)
43 with "device" sections, e\&.g\&.,
44 .sp
45 .nf
46 define device top_drive {
47     tapedev "tape:/dev/nst0"
48     device\-property "BLOCK_SIZE" "131072"
49 }
50 .fi
51 Such a device defininition creates a device "alias", in this case named
52 \fItop_drive\fR, which can then be named in the global
53 \fItapedev\fR
54 or
55 \fItpchanger\fR
56 parameter:
57 .sp
58 .nf
59 tapedev "top_drive"
60 .fi
61 .PP
62 The global
63 \fItapedev\fR
64 parameter can also specify a literal device name\&. For example,
65 .sp
66 .nf
67 tapedev "file:/amdisks"
68 .fi
69 is equivalent to
70 .sp
71 .nf
72 tapedev "default"
73 define device default {
74     tapedev "file:/amdisks"
75 }
76 .fi
77 Note that, in both cases, the specified devices are actually accessed through the
78 \fIchg\-single\fR
79 changer driver; see
80 \fBamanda-changers\fR(7)
81 for more information\&.
82 .PP
83 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\&.
84 .PP
85 See
86 \fBamanda-changers\fR(7)
87 for details on how devices are configured, and in particular on how device properties are specified\&. See
88 \fBamanda.conf\fR(5)
89 for more information on Amanda configuration in general\&.
90 .if n \{\
91 .sp
92 .\}
93 .RS 4
94 .it 1 an-trap
95 .nr an-no-space-flag 1
96 .nr an-break-flag 1
97 .br
98 .ps +1
99 \fBNote\fR
100 .ps -1
101 .br
102 .PP
103 There is no way to reset a device property to its default value\&.
104 .sp .5v
105 .RE
106 .SH "PROPERTIES"
107 .PP
108 Device drivers use
109 \fIproperties\fR
110 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\&.
111 .PP
112 Properties are specified in
113 \fIamanda\&.conf\fR
114 with the
115 \fIdevice\-property\fR
116 parameter\&. The syntax looks like this:
117 .sp
118 .nf
119 device\-property "FROBNICATOR_PATH" "/var/frobd/state"
120 device\-property "BYTES_PER_FORTNIGHT" "128k"
121 device\-property "USE_QUBITS" "no"
122 .fi
123 .PP
124 Both the property name and the property value are always quoted\&. Property names, like Amanda configuration parameters, are not case\-sensitive, and
125 \-
126 (dash) and
127 _
128 (underscore) may be used interchangeably\&. 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
129 \fBamanda.conf\fR(5), like BYTES_PER_FORTNIGHT, above\&. Boolean values can be specified using the same names as in
130 \fBamanda.conf\fR(5), like USE_QUBITS, above\&. Some properties have special formats, as described below\&.
131 .PP
132 Some properties are set based on other configuration values, such as tapetype parameters\&. These special cases are detailed under the appropriate property, below\&.
133 .PP
134 The order in which device properties are set is as follows:
135 .sp
136 .RS 4
137 .ie n \{\
138 \h'-04' 1.\h'+01'\c
139 .\}
140 .el \{\
141 .sp -1
142 .IP "  1." 4.2
143 .\}
144 Tapetype parameters (including length, blocksize, and readblocksize) are translated into device properties and set accordingly\&.
145 .RE
146 .sp
147 .RS 4
148 .ie n \{\
149 \h'-04' 2.\h'+01'\c
150 .\}
151 .el \{\
152 .sp -1
153 .IP "  2." 4.2
154 .\}
155 Device properties from any device\-property configuration parameters are set, in the order they appear in the configuration file\&.
156 .RE
157 .PP
158 Properties described as read\-only are not accessible to users\&. They are listed here for completeness\&.
159 .SS "COMMON PROPERTIES"
160 .PP
161 Note that some of these properties are currently unused, and present only for future expansion\&. Not all devices implement all of these properties\&.
162 .PP
163 APPENDABLE
164 .RS 4
165
166  (read\-only) This boolean property indicates whether this device supports appending data to volumes\&.
167 .RE
168 .PP
169 BLOCK_SIZE
170 .RS 4
171
172  (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\&.
173 .RE
174 .PP
175 CANONICAL_NAME
176 .RS 4
177
178  (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\&.
179 .RE
180 .PP
181 COMMENT
182 .RS 4
183
184  (read\-write) This string property is entirely for the user\'s convenience\&.  It is supported by all devices, but no device interprets its value in any way\&.
185 .RE
186 .PP
187 COMPRESSION
188 .RS 4
189
190  (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\&.
191 .RE
192 .PP
193 COMPRESSION_RATE
194 .RS 4
195
196  (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\&.
197 .RE
198 .PP
199 CONCURRENCY
200 .RS 4
201
202  (read\-only) This property indicates the level of concurrent access that this device supports\&.
203 .RE
204 .PP
205 FULL_DELETION
206 .RS 4
207
208  (read\-only) This property indicates whether the device supports erasing the entire volume\&.  Aside from S3 and VFS, most devices cannot support this feature\&.
209 .RE
210 .PP
211 LEOM
212 .RS 4
213
214 (read\-write) If this property is true, then the device can detect an EOM condition before actually running out of space, allowing Amanda to forgo caching parts while writing\&.  For some devices, it is necessary to override the conservative default value of this property\&.
215 .RE
216 .PP
217 MAX_BLOCK_SIZE
218 .RS 4
219
220  (read\-only) This property gives the maximum block size this device can support\&.  See BLOCK SIZES, below\&.
221 .RE
222 .PP
223 MEDIUM_ACCESS_TYPE
224 .RS 4
225
226  (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\&.
227 .RE
228 .PP
229 MIN_BLOCK_SIZE
230 .RS 4
231
232  (read\-write) This property gives the minimum block size this device can support\&.  See BLOCK SIZES, below\&.
233 .RE
234 .PP
235 MAX_VOLUME_USAGE
236 .RS 4
237
238  (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\&.
239 .RE
240 .PP
241 ENFORCE_MAX_VOLUME_USAGE
242 .RS 4
243
244  (read\-write) If this property is false, limit set by MAX_VOLUME_USAGE property (and thus the tapetype LENGTH parameter) will not be verified while writing to device, allowing the volume to expand without limit\&. If this property is true, then MAX_VOLUME_USAGE willbe enforced, limiting the total size of the volume\&. This property is not available on all devices; see below\&.
245 .RE
246 .PP
247 PARTIAL_DELETION
248 .RS 4
249
250  (read\-only) This property indicates whether the device supports deletion of specific files\&.  Aside from linear tapes and S3, most devices can support this feature\&.  It is currently unused by Amanda\&.
251 .RE
252 .PP
253 STREAMING
254 .RS 4
255
256 (read\-only) This property gives the streaming requirement for this device\&.  For
257 example, tape drives often require a steady supply of data to avoid
258 shoe\-shining, while disk devices have no such requirement\&.  Streaming is
259 accomplished by buffering \fBdevice\-output\-buffer\-size\fR bytes of
260 data\&.  The allowed values are "none" (no streaming buffer necessary),
261 "required" (fill the buffer before starting to write), or "desired" (fill the
262 buffer before starting to write, and if the buffer becomes empty, stop writing
263 until it is completely full again)\&.
264 .RE
265 .PP
266 VERBOSE
267 .RS 4
268
269  (read\-write) If this boolean property is set, then the device will produce verbose debugging output\&.  This property is not recognized by most devices\&.
270 .RE
271 .SS "BLOCK SIZES"
272 .PP
273 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\&.
274 .PP
275 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\&.
276 .PP
277 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_BLOCK_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_BLOCK_SIZE\&.
278 .if n \{\
279 .sp
280 .\}
281 .RS 4
282 .it 1 an-trap
283 .nr an-no-space-flag 1
284 .nr an-break-flag 1
285 .br
286 .ps +1
287 \fBNote\fR
288 .ps -1
289 .br
290 .PP
291 The RAIT device does not support flexible block sizes, as its parity algorithm requires that all child devices have the same, fixed block size\&.
292 .sp .5v
293 .RE
294 .SS "LEOM DETECTION"
295 .PP
296 Some Amanda devices can detect end\-of\-medium (running out of space on the device) before it occurs\&. This early warning is referred to as logical EOM, and where it is supported Amanda can operate more efficiently, since the possibility for data loss is reduced\&.
297 .PP
298 The boolean LEOM property indicates whether or not a particular device supports LEOM detection\&. The sections below also describe the degree of support\&.
299 .SH "DEVICES"
300 .PP
301 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\&.
302 .SS "Null Device"
303 .nf
304 tapedev "null:"
305 .fi
306 .PP
307 The null device driver only supports writing, and discards all data\&. It is generally only useful for testing purposes\&.
308 .SS "RAIT Device"
309 .nf
310 tapedev "rait:tape:/dev/rmt/tps0d{4,5,6}n"
311 .fi
312 .PP
313 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\&. Braces and commas can be escaped with a backslash\&. Note that the backslash itself must be escaped in most contexts\&. For example:
314 .sp
315 .nf
316 tapedev "rait:{file:/var/amanda/vtapes,tape:/dev/nst0}"
317 tapedev "rait:{comma\-dev:foo\e\e,bar,brace\-dev:foo\e\e}bar}" # quoting
318 .fi
319 If the braces contain a numeric range separated with two dots, that range will be filled in sequentially\&. If the first number has a leading zero, then the results will be zero\-padded to the maximum length\&. For example:
320 .sp
321 .nf
322 tapedev "rait:file:/var/amanda/vtapes/drive{01\&.\&.04}"
323 .fi
324 .PP
325 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\&.
326 .PP
327 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\&.,
328 .sp
329 .nf
330 tapedev "rait:{tape:/dev/st0,ERROR,tape:/dev/st2}"
331 .fi
332 This will cause the RAIT device to start up in degraded mode, reconstructing the data from the missing device\&.
333 .PP
334 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\&.
335 .PP
336 This device can detect LEOM if and only if all of the child devices can detect LEOM\&.
337 .SS "Child Device Block Sizes"
338 .PP
339 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
340 \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
341 \fIchild_blocksize = rait_blocksize / (num_children \- 1)\fR\&. Either way, it sets the BLOCK_SIZE property of each child device accordingly\&.
342 .SS "S3 Device"
343 .nf
344 tapedev "s3:foocorp\-backups/DailySet1\-"
345 device\-property "S3_ACCESS_KEY" "MYACCESSKEY"
346 device\-property "S3_SECRET_KEY" "MYSECRETKEY"
347 .fi
348 .PP
349 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"\&.
350 .PP
351 The access and secret keys used to authenticate to Amazon S3 are provided as properties\&.
352 .PP
353 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 recommended with the S3 device\&.
354 .PP
355 Amanda automatically creates a bucket when writing, if the bucket doesn\'t already exist\&. At that time, it specifies where Amazon should store the data based on the S3_BUCKET_LOCATION property\&. If this property is not set, Amazon\'s default value (equivalent to "*") is used\&. The bucket location has both billing and legal concerns, so you are encouraged to consult Amazon\'s documentation for details\&.
356 .PP
357 Amazon does not permit changes to bucket locations, so this is a permanent specification\&. If the bucket already exists and the property is set, then Amanda checks the property against the location of the bucket, and produces an error if they do not match\&.
358 .if n \{\
359 .sp
360 .\}
361 .RS 4
362 .it 1 an-trap
363 .nr an-no-space-flag 1
364 .nr an-break-flag 1
365 .br
366 .ps +1
367 \fBNote\fR
368 .ps -1
369 .br
370 .PP
371 If a location constraint is set, the bucket name must consist only of lower\-case letters, numbers, dashes, and dots\&.
372 .sp .5v
373 .RE
374 .PP
375 This driver supports the VERBOSE property, but use it carefully \-\- it produces a great deal of output, and may cause spurious failures by filling your debug log partition\&. Its logging is generally only useful for developers chasing down a problem in communications with Amazon\'s servers\&.
376 .PP
377 Since Amazon storage is unlimited, the device never encounteres EOM, so LEOM detection is trivially enabled for this device\&.
378 .PP
379 This driver supports the ENFORCE_MAX_VOLUME_USAGE property\&. Default value is false\&. See COMMON_PROPERTIES, above\&.
380 .SS "Device-Specific Properties"
381 .PP
382 In addition to the common properties, the S3 device supports the properties listed in this section\&.
383 .PP
384 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:
385 .sp
386 .nf
387 device\-property "S3_ACCESS_KEY" "27D3B8C6C4E7AA423C2B37C72A0D22C8"
388 device\-property "S3_SECRET_KEY" "agphc2Q7Zmxragphc2RmO2xragpzZGY7a2xqCgr"
389 .fi
390 .PP
391 MAX_RECV_SPEED
392 .RS 4
393
394 (read\-write) Maximum speed, in bytes per second, that this device will receive
395 data from S3\&.  If the average speed exceeds this value, the device will stop
396 reading long enough to bring the average below this value\&.
397 .RE
398 .PP
399 MAX_SEND_SPEED
400 .RS 4
401
402 (read\-write) Maximum speed, in bytes per second, that this device will send
403 data to S3\&.  If the average speed exceeds this value, the device will stop
404 writing long enough to bring the average below this value\&.
405 .RE
406 .PP
407 NB_THREADS_BACKUP
408 .RS 4
409
410 (read\-write) The number of thread that send data to the s3 device, higher value can provide more throutput\&.
411 .RE
412 .PP
413 NB_THREADS_RECOVERY
414 .RS 4
415
416 (read\-write) The number of thread that read data from the s3 device, higher value can provide more throutput\&.
417 .RE
418 .PP
419 S3_ACCESS_KEY
420 .RS 4
421
422  (read\-write) This property gives the Amazon S3 access key used to access the service\&.
423 .RE
424 .PP
425 S3_BUCKET_LOCATION
426 .RS 4
427
428  (read\-write) Location constraint for buckets on Amazon S3\&.
429 As of this writing, it can be set to "*" (US Standard, i\&.e\&. lowest\-latency
430 choice of US East or West), "us\-west\-1" (US West, Northern California), "EU"
431 (European Union), or "ap\-southeast\-1" (Asia Pacific)\&.  See : http://docs.amazonwebservices.com/AmazonS3/latest/index.html?LocationSelection.html for the most up\-to\-date list\&.
432 .RE
433 .PP
434 SSL_CA_INFO
435 .RS 4
436
437  (read\-write) Path to CA certificate to use to verify the identity of the S3 server\&.
438 Only applicable when SSL/TLS is in use\&. The certificate should be in PEM format
439 if OpenSSL or GnuTLS is being used with libcurl\&. Multiple certificates can be
440 bundled together simply by concatenating them\&.
441 If NSS is being used, then it is the directory that the database resides in\&.
442 The value is passed to curl_easy_setopt(3) as CURLOPT_CAINFO\&.
443 .RE
444 .PP
445 S3_HOST
446 .RS 4
447
448 (read\-write) The host name to connect, in the form "hostname:port" or "ip:port", default is "s3\&.amazonaws\&.com"
449 .RE
450 .PP
451 S3_SECRET_KEY
452 .RS 4
453
454 (read\-write) This property gives the Amazon S3 secret key used to access the service\&.
455 .RE
456 .PP
457 S3_SERVICE_PATH
458 .RS 4
459
460 (read\-write) A path to add at the beginning of the URL\&.
461 .RE
462 .PP
463 S3_STORAGE_CLASS
464 .RS 4
465
466 (read\-write) Storage class for new objects, currently one of "STANDARD" (the default)
467 or "REDUCED_REDUNDANCY" (cheaper, but less redundant)\&.  See
468 : http://docs.amazonwebservices.com/AmazonS3/latest/dev/index.html?DataDurability.html
469 for the most up\-to\-date list\&.
470 .RE
471 .PP
472 S3_SSL
473 .RS 4
474
475 (read\-write) Whether or not to use SSL/TLS to secure communications with Amazon S3\&.
476 .RE
477 .PP
478 S3_SUBDOMAIN
479 .RS 4
480
481  (read\-write) Whether or not to use subdomain hostname\&.
482 .RE
483 .PP
484 S3_USER_TOKEN
485 .RS 4
486
487 (read\-write) This property specifies the user token for Amanda Enterprise Edition customers\&.
488 .RE
489 .PP
490 VERBOSE
491 .RS 4
492
493 (read\-write) If true, verbose data about each HTTP transaction is sent to the debug log\&.
494 .RE
495 .SS "S3 URL"
496
497      SSL &&  SUBDOMAIN:   https://bucket\&.host/service_path/file
498      SSL && !SUBDOMAIN:   https://host/service_path/bucket/file
499     !SSL &&  SUBDOMAIN:   http://bucket\&.host/service_path/file
500     !SSL && !SUBDOMAIN:   http://host/service_path/bucket/file
501 .SS "Tape Device"
502 .nf
503 tapedev "tape:/dev/nst0"
504 .fi
505 .PP
506 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)\&.
507 .PP
508 The tape device name should specify a path to the operating system\'s device file\&.
509 .PP
510 There is no simple way to determine whether a particular system (operating system and tape hardware) supports LEOM, so as a safe default the tape device has LEOM detection disabled\&. However, on modern hardware and common operating systems (Linux, *BSD, and Solaris, at least), LEOM support is functional\&. On these systems, enable LEOM by setting the LEOM property to "true" at the appropriate place in the Amanda configuration\&.
511 .SS "Device-Specific Properties"
512 .PP
513 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\&.
514 .PP
515 BROKEN_GMT_ONLINE
516 .RS 4
517
518  (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\&.
519 .RE
520 .PP
521 BSF
522 .RS 4
523
524  (read\-write) This boolean property specifies whether the device
525  driver may execute the MTBSF operation (backward seek file)\&.
526 .RE
527 .PP
528 BSF_AFTER_EOM
529 .RS 4
530
531  (read\-write) This boolean property specifies whether the device
532  driver should execute an MTBSF (backward seek file) operation after
533  MTEOM (seek to end of recorded data) in order to append\&.
534 .RE
535 .PP
536 BSR
537 .RS 4
538
539  (read\-write) This boolean property specifies whether the device
540  driver may use the MTBSR operation (backward seek record)\&.
541 .RE
542 .PP
543 EOM
544 .RS 4
545
546  (read\-write) This boolean property specifies whether the device
547  driver may use the MTEOM command (seek to end of recorded data)\&.
548 .RE
549 .PP
550 FINAL_FILEMARKS
551 .RS 4
552
553  (read\-write) This integer property gives the number of filemarks that should be written at EOD\&.  It is usually 1 or 2\&.
554 .RE
555 .PP
556 FSF
557 .RS 4
558
559  (read\-write) This boolean property specifies whether the device driver may use the MTFSF operation (forward seek file)\&.
560 .RE
561 .PP
562 FSF_AFTER_FILEMARK
563 .RS 4
564
565  (read\-write) This boolean property specifies whether the device driver needs a FSF to go the next file after the filemark is read\&. Default to "TRUE" on Solaris and "FALSE" on all others machines\&.
566 .RE
567 .PP
568 FSR
569 .RS 4
570
571  (read\-write) This boolean property specifies whether the device driver may use the MTFSR operation (forward seek record)\&.
572 .RE
573 .PP
574 NONBLOCKING_OPEN
575 .RS 4
576
577  (read\-write) Set this boolean property to "true" if O_NONBLOCK must be used on the open call\&. Default to "true" on Linux and "false" on all others machines\&. Witout it, Linux wait for a few seconds if no tape are loaded\&. Solaris have strange error it is set to "yes"\&.
578 .RE
579 .PP
580 READ_BLOCK_SIZE
581 .RS 4
582
583  (read\-write) This property (previously known as \fIREAD_BUFFER_SIZE\fR) specifies the block size that will be used for reads; this should be large enough to contain any block that may be read from the device (for example, from a tape containing variable\-sized blocks), and must be larger than BLOCK_SIZE\&.  This property is most often used when overwriting tapes using a new, smaller block size\&.
584  The tapetype parameter \fIREADBLOCKSIZE\fR sets this property\&.  See BLOCK SIZES, above\&.
585 .RE
586 .SS "NDMP Device"
587 .nf
588 tapedev "ndmp:my\&.filer\&.com:10000@st1"
589 device\-property "NDMP_USERNAME" "jimmy"
590 device\-property "NDMP_PASSWORD" "thelock"
591 .fi
592 .PP
593 This device enables Amanda to communicate with a tape service on an NDMP server\&. The device name specifies the hostname and optionally the TCP port of the NDMP server, followed by the name of the tape device on the server (\fBst1\fR
594 in the example above)\&.
595 .PP
596 This device supports LEOM detection\&.
597 .SS "Device-Specific Properties"
598 .PP
599 The properties
600 \fBNDMP_USERNAME\fR
601 and
602 \fBNDMP_PASSWORD\fR
603 set the username and password with which to access the NDMP server\&. The default for both is "ndmp"\&.
604 .PP
605 NDMP_AUTH
606 .RS 4
607
608 (read\-write) Authentication method to use to connect to the NDMP server\&.  One of
609 "md5" (default), "text", "none" (for an empty authentication attempt) or "void" (for
610 no authentication attempt at all)\&.
611 .RE
612 .PP
613 NDMP_PASSWORD
614 .RS 4
615
616 (read\-write) Password for md5 or text authentications\&.
617 .RE
618 .PP
619 NDMP_USERNAME
620 .RS 4
621
622 (read\-write) Username for md5 or text authentications\&.
623 .RE
624 .PP
625 READ_BLOCK_SIZE
626 .RS 4
627
628 (read\-write) This property specifies the block 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\&. See BLOCK_SIZES, above\&.
629 .RE
630 .SS "VFS Device"
631 .nf
632 tapedev "file:/path/to/vtape"
633 .fi
634 .PP
635 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\&.
636 .PP
637 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\&.
638 .PP
639 This device supports LEOM detection\&. LEOM will be indicated when the MAX_VOLUME_USAGE is nearly met, or when the filesystem is nearly out of space\&. The latter circumstance is detected by monitoring the available space on the filesystem, and this monitoring can be disabled with the MONITOR_FREE_SPACE property\&. Note that the device cannot detect other circumstances that may cause a write to fail, such as a filesystem quota\&. LEOM detection can be disabled by setting the LEOM property to false\&.
640 .PP
641 This device supports the ENFORCE_MAX_VOLUME_USAGE property\&. Default value is true\&. See COMMON PROPERTIES, above\&.
642 .SS "Device-Specific Properties"
643 .PP
644 MONITOR_FREE_SPACE
645 .RS 4
646
647          (read\-write) This property controls whether the device will monitor
648          the filesystem\'s free space to detect a full filesystem before an
649          error occurs, and defaults to true\&.  The monitoring operation works on
650          most filesystems, but if it causes problems, use this property to
651          disable it\&.
652 .RE
653 .SS "DVD\-RW Device"
654 .nf
655 tapedev "dvdrw:/var/cache/amanda/dvd\-cache:/dev/scd0"
656 device\-property "DVDRW_MOUNT_POINT" "/media/dvd"
657 device\-property "DVDRW_KEEP_CACHE" "false"
658 device\-property "DVDRW_UNLABELLED_WHEN_UNMOUNTABLE" "true"
659 .fi
660 .PP
661 The DVD\-RW device driver reads and writes optical media such as DVDs and CDs\&. The device name must specify a cache directory for data to be temporarily stored, followed by the operating system name for the optical drive\&. The cache directory must contain a "data/" subdirectory\&.
662 .PP
663 The DVDRW_MOUNT_POINT property is required, and specifies a directory where the optical media can be mounted\&. This directory must be configured to enable non\-root users to mount the optical media\&. On Linux, that means a line similar to the following in /etc/fstab:
664 .nf
665 /dev/scd0 /media/dvd auto ro,user,noauto 0 0
666 .fi
667 .PP
668 Note the "user" option\&.
669 .PP
670 When writing data, the device acts as a VFS device using the given cache directory\&. On completion of writing the tape, the cache directory is written to optical media\&. The DVDRW_KEEP_CACHE property controls whether the cache contents are immediately deleted\&. When reading, the optical media is first mounted and read as a VFS device\&.
671 .PP
672 Attempting to mount unformatted media or media that is formatted but contains no filesystem will usually result in an error\&. The boolean DVDRW_UNLABELLED_WHEN_UNMOUNTABLE property specifies whether media that cannot be mounted should be treated as an empty, unlabelled volume when attempting to read the volume label\&. It is necessary to set this property to "true" when labelling such media\&.
673 .PP
674 This device does not support LEOM detection\&.
675 .SS "Device-Specific Properties"
676 .PP
677 The properties DVDRW_GROWISOFS_COMMAND, DVDRW_MOUNT_COMMAND and DVDRW_UMOUNT_COMMAND specify alternative commands for writing, mounting and unmounting optical media\&. The default is to find the programs using the PATH environment variable\&.
678 .PP
679 The CDRW device supports all of the properties of the VFS device, as well as the properties given below\&. The DVDRW_MOUNT_POINT property is required\&. Other properties are optional\&.
680 .PP
681 DVDRW_KEEP_CACHE
682 .RS 4
683
684  (read\-write) Set this boolean property to "true" if the disk cache directory should be kept after successfully writing tape data to optical media\&. The default is false, which causes the cache contents to be deleted immediately after a successful write operation\&.
685 .RE
686 .PP
687 DVDRW_MOUNT_POINT
688 .RS 4
689
690  (read\-write) This property specifies the filesystem mount point for the optical media\&. Non\-root users must be able to mount optical media by invoking "mount" and specifying this mount point\&.
691 .RE
692 .PP
693 DVDRW_UNLABELLED_WHEN_UNMOUNTABLE
694 .RS 4
695
696  (read\-write) Treat unmountable media as empty, unlabelled media\&. This is necessary when attempting to label freshly formatted media\&.
697 .RE
698 .PP
699 DVDRW_GROWISOFS_COMMAND
700 .RS 4
701
702  (read\-write) The command to invoke to burn the DVD\&.
703 .RE
704 .PP
705 DVDRW_MOUNT_COMMAND
706 .RS 4
707
708  (read\-write) The command to invoke to mount the DVD\&.
709 .RE
710 .PP
711 DVDRW_UMOUNT_COMMAND
712 .RS 4
713
714  (read\-write) The command to invoke to unmount the DVD\&.
715 .RE
716 .SH "SEE ALSO"
717 .PP
718 \fBamanda\fR(8),
719 \fBamanda.conf\fR(5)
720 .PP
721 The Amanda Wiki:
722 : http://wiki.zmanda.com/
723 .SH "AUTHORS"
724 .PP
725 \fBIan Turner\fR <\&ian@zmanda\&.com\&>
726 .RS 4
727 Zmanda, Inc\&. (http://www\&.zmanda\&.com)
728 .RE
729 .PP
730 \fBDustin J\&. Mitchell\fR <\&dustin@zmanda\&.com\&>
731 .RS 4
732 Zmanda, Inc\&. (http://www\&.zmanda\&.com)
733 .RE