X-Git-Url: https://git.gag.com/?p=debian%2Famanda;a=blobdiff_plain;f=man%2Fxml-source%2Famanda.conf.5.xml;h=179722e1c6c33fb7ba25695cc21ff92c0e3fdca2;hp=fe19c50def205d4a77771bd1247661f4c72ce18e;hb=b116e9366c7b2ea2c2eb53b0a13df4090e176235;hpb=fd48f3e498442f0cbff5f3606c7c403d0566150e
diff --git a/man/xml-source/amanda.conf.5.xml b/man/xml-source/amanda.conf.5.xml
index fe19c50..179722e 100644
--- a/man/xml-source/amanda.conf.5.xml
+++ b/man/xml-source/amanda.conf.5.xml
@@ -56,21 +56,18 @@ The remainder of the line is ignored.
and
MailTo
are treated the same. Also, the characters
-'-'
-and
-'_'
+'-' and '_'
are interchangeable in all predefined Amanda keywords:
device_property
and
device-property
-have the same meaning.
+have the same meaning. This manpage uses the dashed versions, but the
+underscored versions will be accepted for backward compatibility
Identifiers are names which are defined in the configuration itself, such
as dumptypes or interfaces. Identifiers are are case-insensitive, but
sensitive to
-'-'
-vs.
-'_'.
+'-' vs. '_'.
Identifiers should be quoted in the configuration file, although For historical
reasons, the quotes are optional.
@@ -91,7 +88,7 @@ tapetype "EXABYTE" # optional insensitive sensitive
define dumptype "dt" { # optional insensitive sensitive
"dumptype-common" # optional insensitive sensitive
- strategy noincr # prohibited insensitive insensitive
+ strategy noinc # prohibited insensitive insensitive
}
@@ -395,9 +392,25 @@ days /
Default:
15 tapes.
-Typically tapes are used by Amanda in an ordered rotation. The tapecycle parameter
-defines the size of that rotation. This parameter must be be larger than the number of tapes
-used in a dumpcycle.
+
+Specifies the number of "active" volumes - volumes that Amanda will not
+overwrite. While Amanda is always willing to write to a new volume, it refuses
+to overwrite a volume unless at least 'tapecycle -1'
+volumes have been written since.
+
+ It is considered good administrative practice to set the
+tapecycle parameter slightly lower than the actual
+number of tapes in use. This allows the administrator to more easily cope
+with damaged or misplaced tapes or schedule adjustments that call for
+slight adjustments in the rotation order.
+
+Note: Amanda is commonly misconfigured with tapecycle
+equal to the number of tapes per dumpcycle. In this
+misconfiguration, amanda may erase a full dump before a new one is
+completed. Recovery is then impossible. The
+tapecycle must be at least one tape larger than the
+number of tapes per dumpcycle.
+
The number of tapes per dumpcycle is calculated by multiplying the number of
&amdump; runs per dump cycle runspercycle (the
@@ -406,21 +419,6 @@ remap='B'>runtapes (the number of tapes used per run). Typically
tapecycle is set to two or four times the tapes
per dumpcycle.
-Amanda is commonly misconfigured with tapecycle
-equal to the number of tapes per dumpcycle. In this
-misconfiguration, amanda may erase a full dump before a new one is completed,
-the recovery is then impossible. tapecycle must be at least one tape larger
-than the number of tapes per dumpcycle.
-
-
-While Amanda is always willing to use a new tape in its rotation, it refuses to reuse a tape until at
-least 'tapecycle -1' number of other tapes have been used.
-
-
-It is considered good administrative practice to set the tapecycle parameter
-slightly lower than the actual number of tapes in rotation. This allows the administrator to more easily cope
-with damaged or misplaced tapes or schedule adjustments that call for slight adjustments in the rotation order.
-
@@ -437,22 +435,13 @@ can't read logfiles written when this option was enabled.
- label_new_tapes
+ label-new-tapes
string
- Deprecated, use autolabel option.
+ Deprecated, use autolabel option with options volume-error empty to get equivalent behavior.
Default: not set.
When set, this directive will cause Amanda to automatically write an Amanda
-tape label to any blank tape she encounters. This option is DANGEROUS
-because when set, Amanda will ERASE any non-Amanda tapes you may have, and may
-also ERASE any near-failing tapes. Use with caution.
-When using this directive, specify the template for new tape
-labels. The template should contain some number of contiguous '%'
-characters, which will be replaced with a generated number. Be sure to
-specify enough '%' characters that you do not run out of tape labels.
-Example:
-label_new_tapes "DailySet1-%%%"
-
+tape label to any blank tape she encounters.
@@ -460,9 +449,9 @@ Example:
autolabel
string
[any]
- [other_config]
- [non_amanda]
- [volume_error]
+ [other-config]
+ [non-amanda]
+ [volume-error]
[empty]
Default: not set.
@@ -477,28 +466,31 @@ specify enough '%' characters that you do not run out of tape labels.
Example:
autolabel "DailySet1-%%%" empty
+Note that many devices cannot distinguish an empty tape from an error
+condition, so it may is often necessary to include
+volume-error as an autolabel condition.
any
-equivalent to 'other_config non_amanda volume_error empty'
+equivalent to 'other-config non-amanda volume-error empty'
-other_config
+other-config
Label volumes with a valid Amanda label that do not match our
labelstr. Danger: this may erase volumes
from other Amanda configurations without warning!
-non_amanda
+non-amanda
Label volumes which do not start with data that resembles an
Amanda header. Danger: this may erase volumes from other backup applications
without warning!
-volume_error
+volume-error
Label volumes where an error occurs while trying to read the label.
Danger: this may erase arbitrary volumes due to transient errors.
@@ -542,30 +534,14 @@ option.
Default:
"null:".
-The device name, referencing the name of a "device" section in the configuration file. See
-
-for more information on device names.
+This parameter can either specify a device (explicitly or by referencing a device definition - see )
+or a tape changer (explicitly or by referencing a device definition - see ).
-If a tape changer is configured
-(see the
-tpchanger
-option), this option might not be used.
-
-If tapedev is
-null:,
-programs such as
-&amdump;
-will run normally but all images will be thrown away.
-This should only be used for debugging and testing,
-and probably only with the
-record
-option set to
-no.
- device_property string string
+ device-property string string
These options can set various device properties. See
@@ -574,7 +550,7 @@ Both strings are always quoted; the first string contains the name of
the property to set, and the second contains its value. For example, to set
a fixed block size of 128k, write:
-device_property "BLOCK_SIZE" "128k"
+device-property "BLOCK_SIZE" "128k"
@@ -595,13 +571,12 @@ the property to set, and the others contains its values.
tpchanger string
-Default: not set.
-The name of the tape changer.
-If a tape changer is not configured, this option is not used
-and should be commented out of the configuration file.
-If a tape changer is configured, choose one of the changer scripts
-(e.g. chg-scsi)
-and enter that here.
+Default: not set. The tape changer to use. In most cases, only one of
+tpchanger or tapedev is
+specified, although for backward compatibility both may be specified if
+tpchanger gives the name of an old changer script.
+See for more information on
+configuring changers.
@@ -620,7 +595,7 @@ option.
changerfile string
Default:
-"usr/adm/amanda/log/changer-status".
+"/usr/adm/amanda/log/changer-status".
A tape changer configuration parameter.
Usage depends on the particular changer defined with the
tpchanger
@@ -639,9 +614,6 @@ and should be commented out of the configuration file.
let Amanda write to more than one tape.
Note that this is an upper bound on the number of tapes,
and Amanda may use less.
-Also note that as of this release, Amanda does not support true tape overflow.
-When it reaches the end of one tape,
-the backup image Amanda was processing starts over again on the next tape.
@@ -649,7 +621,7 @@ the backup image Amanda was processing starts over again on the next tape.maxdumpsize int
Default:
-runtapes*tape_length.
+runtapes*tape-length.
Maximum number of bytes the planner will schedule for a run.
The default unit is Kbytes if it is not specified.
@@ -703,6 +675,14 @@ The algorithm used to choose which dump image to send to the taper.
+taper-parallel-write int
+
+
+Default: 1.
+Amanda can write simultaneously up to that number of volume at any given
+time. The changer must have as many drives.
+
+
labelstr string
Default:
@@ -778,7 +758,7 @@ per client instead of per disk.
- connect_tries int
+ connect-tries int
Default:
3.
@@ -787,7 +767,7 @@ How many times the server will try a connection.
- req_tries int
+ req-tries int
Default:
3.
@@ -1023,7 +1003,7 @@ Amanda maintains this file with information about the active set of tapes.
- device_output_buffer_size int
+ device-output-buffer-size int
Default:
1280k.
@@ -1040,7 +1020,7 @@ useful on fast tape drives and optical media.
Default:
20.
This option is deprecated; use
-the device_output_buffer_size directive
+the device-output-buffer-size directive
instead. tapebufs works the same way,
but the number specified is multiplied by the device blocksize prior
to use.
@@ -1068,27 +1048,29 @@ Whether an amdump run will flush the dumps from holding disk to tape.
- amrecover_do_fsf bool
+ amrecover-do-fsf bool
+Deprecated; amrecover always uses fsf, and does not invoke amrestore.
Default:
on.
Amrecover will call amrestore with the -f flag for faster positioning of the tape.
- amrecover_check_label bool
+ amrecover-check-label bool
+Deprecated; amrecover always checks the label, and does not invoke amrestore.
Default:
on.
Amrecover will call amrestore with the -l flag to check the label.
- amrecover_changer string
+ amrecover-changer string
Default: not set.
Amrecover will use the changer if you use 'settape <string>' and that string
-is the same as the amrecover_changer setting.
+is the same as the amrecover-changer setting.
@@ -1159,7 +1141,7 @@ Relative pathnames are relative to the configuration directory.
- debug_days int
+ debug-days int
Default:
3.
@@ -1168,7 +1150,7 @@ The number of days the debug files are kept.
- debug_auth int
+ debug-auth int
Default:
0.
@@ -1177,7 +1159,7 @@ Debug level of the auth module
- debug_event int
+ debug-event int
Default:
0.
@@ -1186,7 +1168,7 @@ Debug level of the event module
- debug_holding int
+ debug-holding int
Default:
0.
@@ -1195,7 +1177,7 @@ Debug level of the holdingdisk module
- debug_protocol int
+ debug-protocol int
Default:
0.
@@ -1204,7 +1186,7 @@ Debug level of the protocol module
- debug_planner int
+ debug-planner int
Default:
0.
@@ -1213,7 +1195,7 @@ Debug level of the planner process
- debug_driver int
+ debug-driver int
Default:
0.
@@ -1222,7 +1204,7 @@ Debug level of the driver process
- debug_dumper int
+ debug-dumper int
Default:
0.
@@ -1231,7 +1213,7 @@ Debug level of the dumper process
- debug_chunker int
+ debug-chunker int
Default:
0.
@@ -1240,7 +1222,7 @@ Debug level of the chunker process
- debug_taper int
+ debug-taper int
Default:
0.
@@ -1357,6 +1339,36 @@ Range is inclusive.
+
+ recovery-limit [ string | same-host ]
+
+Default: none (no limitations). This parameter limits the hosts
+ that may do remote recoveries. Hosts are identified by their authenticated
+ peer name, as described in ; if this is
+ not available and the recovery-limit parameter is present, recovery will be
+ denied. The arguments to the parameter are strings giving host match
+ expressions (see ) or the special
+ keyword same-host, which requires an exact match to the hostname of the
+ DLE being recovered. Specifying no arguments at all will disable all
+ recoveries from any host.
+
+Note that match expressions can be constructed to be
+ forgiving of e.g., fully-qualified vs. unqualified hostnames, but
+ same-host requires an exact match.
+
+The error messages that appear in amrecover are intentionally vague to
+ avoid information leakage. Consult the amindexd debug log for more details
+ on the reasons a recovery was rejected.
+
+Recovery limits can be refined on a per-DLE basis using the dumptype
+ parameter of the same name. Note that the default value will apply to any
+ dumpfiles for disks which no longer appear in the disklist; thus leaving the
+ global parameter at its default value but setting it for all DLEs is not
+ sufficient to maintain secure backups.
+
+
+
+
@@ -1490,7 +1502,7 @@ Type of authorization to perform between tape server and backup client hosts. S
- amandad_path string
+ amandad-path string
Default:
"$libexec/amandad".
@@ -1500,7 +1512,7 @@ Specify the amandad path of the client, only use with rsh/ssh authentification.
- client_username string
+ client-username string
Default:
CLIENT_LOGIN.
@@ -1510,7 +1522,7 @@ Specify the username to connect on the client, only use with rsh/ssh authentific
- client_port [ int | string ]
+ client-port [ int | string ]
Default:
"amanda".
@@ -1653,7 +1665,7 @@ to use your own compression method. (See dumptype custom-compress in example/ama
compress client custom
- Specify client_custom_compress "PROG"
+ Specify client-custom-compress "PROG"
PROG must not contain white space and it must accept -d for uncompress.
@@ -1666,7 +1678,7 @@ to use your own compression method. (See dumptype custom-compress in example/ama
compress server custom
- Specify server_custom_compress "PROG"
+ Specify server-custom-compress "PROG"
PROG must not contain white space and it must accept -d for uncompress.
@@ -1678,7 +1690,7 @@ or mt option), Amanda (software) compression shou
- client_custom_compress string
+ client-custom-compress string
Default: none.
The program to use to perform compression/decompression on the client; used with
@@ -1687,7 +1699,7 @@ or mt option), Amanda (software) compression shou
- server_custom_compress string
+ server-custom-compress string
Default: none.
The program to use to perform compression/decompression on the server; used with
@@ -1722,9 +1734,9 @@ server host as it goes from the network into the holding disk or to tape.
encrypt client
- Specify client_encrypt "PROG"
+ Specify client-encrypt "PROG"
PROG must not contain white space.
- Specify client_decrypt_option "decryption-parameter" Default: "-d"
+ Specify client-decrypt-option "decryption-parameter" Default: "-d"
decryption-parameter must not contain white space.
(See dumptype client-encrypt-nocomp in example/amanda.conf for reference)
@@ -1732,9 +1744,9 @@ server host as it goes from the network into the holding disk or to tape.
encrypt server
- Specify server_encrypt "PROG"
+ Specify server-encrypt "PROG"
PROG must not contain white space.
- Specify server_decrypt_option "decryption-parameter" Default: "-d"
+ Specify server-decrypt-option "decryption-parameter" Default: "-d"
decryption-parameter must not contain white space.
(See dumptype server-encrypt-fast in example/amanda.conf for reference)
@@ -1750,7 +1762,7 @@ client-encryption AND server-compression is not supported.
- client_encrypt string
+ client-encrypt string
Default: none.
The program to use to perform encryption/decryption on the client; used with
@@ -1759,16 +1771,16 @@ The program to use to perform encryption/decryption on the client; used with
- client_decrypt_option string
+ client-decrypt-option string
Default: -d.
-The option that can be passed to client_encrypt to make it decrypt instead.
+The option that can be passed to client-encrypt to make it decrypt instead.
Must not contain whitespace.
- server_encrypt string
+ server-encrypt string
Default: none.
The program to use to perform encryption/decryption on the server; used with
@@ -1777,10 +1789,10 @@ The program to use to perform encryption/decryption on the server; used with
- server_decrypt_option string
+ server-decrypt-option string
Default: -d.
-The option that can be passed to server_encrypt to make it decrypt instead.
+The option that can be passed to server-encrypt to make it decrypt instead.
Must not contain whitespace.
@@ -2098,7 +2110,7 @@ level 1 incrementals in this configuration; this is probably a bug.
- ssh_keys string
+ ssh-keys string
Default: not set.
The key file the ssh auth will use, it must be the private key. If this parameter is not specified, then the default ssh key will be used.
@@ -2159,23 +2171,28 @@ The value should be hh*100+mm, e.g. 6:30PM (18:30) would be entered as
- tape_splitsize int
+ allow-split bool
+
+Default: true.
+If true, then dumps with this dumptype can be split on the storage media. If false, then
+the dump will be written in a single file on the media. See "Dump Splitting Configuration"
+below.
+
+
+
+
+ tape-splitsize int
+ Deprecated. See "Dump Splitting Configuration" below.
Default: not set.
Split dump file on tape into pieces of a specified size.
-This allows dumps to be spread across multiple tapes, and can potentially
-make more efficient use of tape space.
-Note that if this value is too large (more than half the size of the
-average dump being split), substantial tape space can be wasted.
-If too small, large dumps will be split into innumerable tiny dumpfiles,
-adding to restoration complexity.
-A good rule of thumb, usually, is 1/10 of the size of your tape.
-The default unit is Kbytes if it is not specified.
+The default unit is Kbytes if it is not specified.
- split_diskbuffer string
+ split-diskbuffer string
+ Deprecated. See "Dump Splitting Configuration" below.
Default: not set.
When dumping a split dump in PORT-WRITE mode (usually meaning "no holding disk"), buffer the split chunks to a file in the directory specified by this option.
@@ -2184,20 +2201,26 @@ When dumping a split dump in PORT-WRITE mode (usually meaning "no holding disk")
- fallback_splitsize int
+ fallback-splitsize int
+ Deprecated. See "Dump Splitting Configuration" below.
Default:
10M.
-When dumping a split dump in PORT-WRITE mode, if no split_diskbuffer is
-specified (or if we somehow fail to use our split_diskbuffer), we must
-buffer split chunks in memory.
-This specifies the maximum size split chunks can be in this scenario,
+This specifies the part size used when no split-diskbuffer is specified, or when it is too small or does not exist,
and thus the maximum amount of memory consumed for in-memory splitting.
-The size of this buffer can be changed from its (very conservative) default
-to a value reflecting the amount of memory that each taper process on
-the dump server may reasonably consume.
-
-The default unit is Kbytes if it is not specified.
+The default unit is Kbytes if it is not specified.
+
+
+
+
+ recovery-limit
+ [ same-host | string ]*
+
+
+Default: global value. This parameter overrides the global
+ recovery-limit parameter for DLEs of this
+ dumptype.
+
@@ -2348,6 +2371,52 @@ tape devices.
+
+ part-size int
+
+Default: none. This is the size (in KB if no units are specified) of
+each split part written to the volume. It is reduced to
+part-cache-max-size when part caching is required.
+If this is set to zero, then no splitting will take place; in this case,
+some devices can span dumps from volume to volume, while others will cause
+the entire dump to fail if they encounter end-of-medium before the dump is
+complete. See "Dump Splitting Configuration" below.
+
+
+
+
+ part-cache-type [ none | disk | memory ]
+
+Default: none. When part caching is required, this parameter specifies
+the type of caching that will be used. The options include no caching
+(none), in which case a failed part will cause the
+entire dump to fail; on-disk caching (disk), for
+which part-cache-dir must be set properly; and
+in-memory caching (memory), which on most systems
+severely restrains the size of the part that can be written. See "Dump
+Splitting Configuration" below.
+
+
+
+
+ part-cache-dir string
+
+Default: none.
+The directory in which part-cache files can be written when caching on disk.
+See "Dump Splitting Configuration" below.
+
+
+
+
+ part-cache-max-size int
+
+Default: none.
+The maximum part size to use when caching is in effect. This is used to limit
+the part size when disk or memory space for caching is constrained. This value
+must be greater than zero.
+
+
+
speed int
@@ -2374,7 +2443,7 @@ man page for more information.
In addition to options, another
tapetype
-name may be supplie as an identifier, which makes this
+name may be supplied as an identifier, which makes this
tapetype
inherit options from another
tapetype.
@@ -2547,13 +2616,13 @@ A comment string describing this script.
- execute_where [ client | server ]
+ execute-where [ client | server ]
Default: client. Where the script must be executed, on the client or server.
- >execute_on execute_on [,execute_on]*
+ execute-on execute_on [,execute_on]*
No default. When the script must be executed, you can specify many of them:
@@ -2676,7 +2745,7 @@ script --post-recover
- property> [append] [priority] string string+
+ property [append] [priority] string string+
No default. You can set property for the script, each script have a different set of property. Both strings are quoted; the first string contains the name of
the property to set, and the others contains its values.
@@ -2697,7 +2766,7 @@ in the form of "device" sections, which look like this:
define device name {
commend "comment (optional)"
tapedev "device-specifier"
- device_property "prop-name" "prop-value"
+ device-property "prop-name" "prop-value"
...
}
@@ -2712,7 +2781,7 @@ As with most sections, the comment
parmeter is optional and only for the user's convenience.
An arbitrary number of device_property parameters can be specified.
+remap='I'>device-property parameters can be specified.
Again, see
for information on device properties.
@@ -2743,6 +2812,60 @@ device. The remaining parameters are specific to the changer type selected.
+Dump Splitting Configuration
+
+ Amanda can "split" dumps into parts while writing them to storage
+ media. This allows Amanda to recover gracefully from a failure while
+ writing a part to a volume, by simply selecting a new volume and
+ re-writing the dump from the beginning of the failed part. Parts also
+ allow Amanda to seek directly to the required data, although this
+ functionality is not yet used.
+
+ In order to support re-writing from the beginning of a failed part,
+ Amanda must have access to the contents of the part after it has been
+ partially written. If the dump is being read from holding disk, then
+ the part contents are availble there. Otherwise, the part must be
+ cached, and this can be done memory or on disk. In either of the
+ latter cases, the cache must have enough space to hold an entire
+ part.
+
+ Because it is common for a single Amanda configuration to use both
+ holding-disk (FILE-WRITE) and direct (known as PORT-WRITE) dumps, Amanda
+ allows the configuration of different split sizes for the two cases. This
+ allows, for example, for a part size appropriate to large tapes when
+ performing FILE-WRITE dumps, with a part size limited by available disk
+ or memory when performing PORT-WRITE dumps.
+
+ Selecting a proper split size is a delicate matter. If the parts are
+ too large, substantial storage space may be wasted in failed parts. If
+ too small, large dumps will be split into innumerable tiny dumpfiles,
+ adding to restoration complexity; furthermore, an excess of filemarks
+ will cause slower tape drive operation and reduce the usable space on
+ tape. A good rule of thumb is 1/10 of the size of a volume of storage
+ media.
+
+ In versions of Amanda through 3.1.*, splitting was controlled by the
+ dumptype parameters tape-splitsize,
+ split-diskbuffer, and
+ fallback-splitsize. These keywords had
+ confusing and non-intuitive interactions, and have since been
+ deprecated.
+
+ If the deprecated keywords are not present, subsequent versions
+ of Amanda use the dumptype parameter
+ allow-split to control whether a DLE can be
+ split, and the tapetype parameters
+ part-size,
+ part-cache-type,
+ part-cache-dir, and
+ part-cache-max-size. The
+ part-size specifies the "normal" part size,
+ while the part-cache-* parameters describe
+ how to behave when caching is required (on PORT-WRITE). Full
+ details on these parameters are given above.
+
+
+
,
,