and
<amkeyword>MailTo</amkeyword>
are treated the same. Also, the characters
-'<amkeyword>-</amkeyword>'
-and
-'<amkeyword>_</amkeyword>'
+'<amkeyword>-</amkeyword>' and '<amkeyword>_</amkeyword>'
are interchangeable in all predefined Amanda keywords:
<amkeyword>device_property</amkeyword>
and
<amkeyword>device-property</amkeyword>
-have the same meaning.</para>
+have the same meaning. This manpage uses the dashed versions, but the
+underscored versions will be accepted for backward compatibility</para>
<para>Identifiers are names which are defined in the configuration itself, such
as dumptypes or interfaces. Identifiers are are case-insensitive, but
sensitive to
-'<amkeyword>-</amkeyword>'
-vs.
-'<amkeyword>_</amkeyword>'.
+'<amkeyword>-</amkeyword>' vs. '<amkeyword>_</amkeyword>'.
Identifiers should be quoted in the configuration file, although For historical
reasons, the quotes are optional.</para>
define dumptype "dt" { # optional insensitive sensitive
"dumptype-common" # optional insensitive sensitive
- strategy noincr # prohibited insensitive insensitive
+ strategy noinc # prohibited insensitive insensitive
}
</programlisting>
</para>
<listitem>
<para>Default:
<amdefault>15 tapes</amdefault>.
-Typically tapes are used by Amanda in an ordered rotation. The <amkeyword>tapecycle</amkeyword> parameter
-defines the size of that rotation. This parameter must be be larger than the number of tapes
-used in a dumpcycle.</para>
+
+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 '<amkeyword>tapecycle</amkeyword> -1'
+volumes have been written since.</para>
+
+<para> It is considered good administrative practice to set the
+<amkeyword>tapecycle</amkeyword> 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.</para>
+
+<para>Note: Amanda is commonly misconfigured with <amkeyword>tapecycle</amkeyword>
+equal to the number of tapes per <amkeyword>dumpcycle</amkeyword>. In this
+misconfiguration, amanda may erase a full dump before a new one is
+completed. Recovery is then impossible. The
+<amkeyword>tapecycle</amkeyword> must be at least one tape larger than the
+number of tapes per dumpcycle.</para>
+
<para>
The number of tapes per dumpcycle is calculated by multiplying the number of
&amdump; runs per dump cycle <amkeyword>runspercycle</amkeyword> (the
<amkeyword>tapecycle</amkeyword> is set to two or four times the tapes
per dumpcycle.</para>
-<note>Amanda is commonly misconfigured with <amkeyword>tapecycle</amkeyword>
-equal to the number of tapes per <amkeyword>dumpcycle</amkeyword>. 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.
-</note>
-
-<para>While Amanda is always willing to use a new tape in its rotation, it refuses to reuse a tape until at
-least '<amkeyword>tapecycle</amkeyword> -1' number of other tapes have been used.
-</para>
-<para>
-It is considered good administrative practice to set the <amkeyword>tapecycle</amkeyword> 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.
-</para>
</listitem>
</varlistentry>
</varlistentry>
<varlistentry>
- <term><amkeyword>label_new_tapes</amkeyword>
+ <term><amkeyword>label-new-tapes</amkeyword>
<amtype>string</amtype></term>
<listitem>
- <para>Deprecated, use <amkeyword>autolabel</amkeyword> option.</para>
+ <para>Deprecated, use <amkeyword>autolabel</amkeyword> option with options <amkeyword>volume-error empty</amkeyword> to get equivalent behavior.</para>
<para>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.</para>
-<para>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:
-<markup>label_new_tapes "DailySet1-%%%"</markup>
-</para>
+tape label to any blank tape she encounters.</para>
</listitem>
</varlistentry>
<term><amkeyword>autolabel</amkeyword>
<amtype>string</amtype>
[<amkeyword>any</amkeyword>]
- [<amkeyword>other_config</amkeyword>]
- [<amkeyword>non_amanda</amkeyword>]
- [<amkeyword>volume_error</amkeyword>]
+ [<amkeyword>other-config</amkeyword>]
+ [<amkeyword>non-amanda</amkeyword>]
+ [<amkeyword>volume-error</amkeyword>]
[<amkeyword>empty</amkeyword>]</term>
<listitem>
<para>Default: not set.
Example:
<markup>autolabel "DailySet1-%%%" empty</markup>
</para>
+<para>Note that many devices cannot distinguish an empty tape from an error
+condition, so it may is often necessary to include
+<amkeyword>volume-error</amkeyword> as an autolabel condition.</para>
<variablelist remap='TP'>
<varlistentry>
<term><amkeyword>any</amkeyword></term>
-<listitem>equivalent to '<amkeyword>other_config non_amanda volume_error empty</amkeyword>'
+<listitem>equivalent to '<amkeyword>other-config non-amanda volume-error empty</amkeyword>'
</listitem>
</varlistentry>
<varlistentry>
-<term><amkeyword>other_config</amkeyword></term>
+<term><amkeyword>other-config</amkeyword></term>
<listitem>Label volumes with a valid Amanda label that do not match our
<amkeyword>labelstr</amkeyword>. Danger: this may erase volumes
from other Amanda configurations without warning!
</listitem>
</varlistentry>
<varlistentry>
-<term><amkeyword>non_amanda</amkeyword></term>
+<term><amkeyword>non-amanda</amkeyword></term>
<listitem>Label volumes which do not start with data that resembles an
Amanda header. Danger: this may erase volumes from other backup applications
without warning!
</listitem>
</varlistentry>
<varlistentry>
-<term><amkeyword>volume_error</amkeyword></term>
+<term><amkeyword>volume-error</amkeyword></term>
<listitem>Label volumes where an error occurs while trying to read the label.
Danger: this may erase arbitrary volumes due to transient errors.
</listitem>
<listitem>
<para>Default:
<amdefault>"null:"</amdefault>.
-The device name, referencing the name of a "device" section in the configuration file. See
-<manref name="amanda-devices" vol="7"/>
-for more information on device names.</para>
+This parameter can either specify a device (explicitly or by referencing a device definition - see <manref name="amanda-devices" vol="7" />)
+or a tape changer (explicitly or by referencing a device definition - see <manref name="amanda-changers" vol="7" />).</para>
-<para>If a tape changer is configured
-(see the
-<amkeyword>tpchanger</amkeyword>
-option), this option might not be used.</para>
-
-<para>If <amkeyword>tapedev</amkeyword> is
-<emphasis remap='B'>null:</emphasis>,
-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
-<amkeyword>record</amkeyword>
-option set to
-<amdefault>no</amdefault>.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><amkeyword>device_property</amkeyword> <amtype>string</amtype> <amtype>string</amtype></term>
+ <term><amkeyword>device-property</amkeyword> <amtype>string</amtype> <amtype>string</amtype></term>
<listitem>
<para>These options can set various device properties. See
<manref name="amanda-devices" vol="7"/>
the property to set, and the second contains its value. For example, to set
a fixed block size of 128k, write:</para>
<programlisting>
-device_property "BLOCK_SIZE" "128k"
+device-property "BLOCK_SIZE" "128k"
</programlisting>
</listitem>
<varlistentry>
<term><amkeyword>tpchanger</amkeyword> <amtype>string</amtype></term>
<listitem>
-<para>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.</para>
-<para>If a tape changer is configured, choose one of the changer scripts
-(e.g. <emphasis remap='B'>chg-scsi</emphasis>)
-and enter that here.</para>
+<para>Default: not set. The tape changer to use. In most cases, only one of
+<amkeyword>tpchanger</amkeyword> or <amkeyword>tapedev</amkeyword> is
+specified, although for backward compatibility both may be specified if
+<amkeyword>tpchanger</amkeyword> gives the name of an old changer script.
+See <manref name="amanda-changers" vol="7" /> for more information on
+configuring changers.</para>
</listitem>
</varlistentry>
<term><amkeyword>changerfile</amkeyword> <amtype>string</amtype></term>
<listitem>
<para>Default:
-<amdefault>"usr/adm/amanda/log/changer-status"</amdefault>.
+<amdefault>"/usr/adm/amanda/log/changer-status"</amdefault>.
A tape changer configuration parameter.
Usage depends on the particular changer defined with the
<amkeyword>tpchanger</amkeyword>
let Amanda write to more than one tape.</para>
<para>Note that this is an upper bound on the number of tapes,
and Amanda may use less.</para>
-<para>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.</para>
</listitem>
</varlistentry>
<term><amkeyword>maxdumpsize</amkeyword> <amtype>int</amtype></term>
<listitem>
<para>Default:
-<amdefault><amkeyword>runtapes</amkeyword>*<amkeyword>tape_length</amkeyword></amdefault>.
+<amdefault><amkeyword>runtapes</amkeyword>*<amkeyword>tape-length</amkeyword></amdefault>.
Maximum number of bytes the planner will schedule for a run.</para>
<para>The default unit is Kbytes if it is not specified.</para>
</listitem>
</listitem>
</varlistentry>
<varlistentry>
+<term><amkeyword>taper-parallel-write</amkeyword> <amtype>int</amtype></term>
+<listitem>
+ </listitem>
+<para>Default: <amdefault>1</amdefault>.
+Amanda can write simultaneously up to that number of volume at any given
+time. The changer must have as many drives.</para>
+ </varlistentry>
+<varlistentry>
<term><amkeyword>labelstr</amkeyword> <amtype>string</amtype></term>
<listitem>
<para>Default:
</varlistentry>
<varlistentry>
- <term><amkeyword>connect_tries</amkeyword> <amtype>int</amtype></term>
+ <term><amkeyword>connect-tries</amkeyword> <amtype>int</amtype></term>
<listitem>
<para>Default:
<amdefault>3</amdefault>.
</varlistentry>
<varlistentry>
- <term><amkeyword>req_tries</amkeyword> <amtype>int</amtype></term>
+ <term><amkeyword>req-tries</amkeyword> <amtype>int</amtype></term>
<listitem>
<para>Default:
<amdefault>3</amdefault>.
</listitem>
</varlistentry>
<varlistentry>
- <term><amkeyword>device_output_buffer_size</amkeyword> <amtype>int</amtype></term>
+ <term><amkeyword>device-output-buffer-size</amkeyword> <amtype>int</amtype></term>
<listitem>
<para>Default:
<amdefault>1280k</amdefault>.
<para>Default:
<amdefault>20</amdefault>.
This option is deprecated; use
-the <amkeyword>device_output_buffer_size</amkeyword> directive
+the <amkeyword>device-output-buffer-size</amkeyword> directive
instead. <amkeyword>tapebufs</amkeyword> works the same way,
but the number specified is multiplied by the device blocksize prior
to use.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><amkeyword>amrecover_do_fsf</amkeyword> <amtype>bool</amtype></term>
+ <term><amkeyword>amrecover-do-fsf</amkeyword> <amtype>bool</amtype></term>
<listitem>
+<para>Deprecated; amrecover always uses fsf, and does not invoke amrestore.</para>
<para>Default:
<amkeyword>on</amkeyword>.
Amrecover will call amrestore with the -f flag for faster positioning of the tape.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><amkeyword>amrecover_check_label</amkeyword> <amtype>bool</amtype></term>
+ <term><amkeyword>amrecover-check-label</amkeyword> <amtype>bool</amtype></term>
<listitem>
+<para>Deprecated; amrecover always checks the label, and does not invoke amrestore.</para>
<para>Default:
<amkeyword>on</amkeyword>.
Amrecover will call amrestore with the -l flag to check the label.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><amkeyword>amrecover_changer</amkeyword> <amtype>string</amtype></term>
+ <term><amkeyword>amrecover-changer</amkeyword> <amtype>string</amtype></term>
<listitem>
<para>Default: not set.
Amrecover will use the changer if you use 'settape <string>' and that string
-is the same as the amrecover_changer setting.</para>
+is the same as the <amkeyword>amrecover-changer</amkeyword> setting.</para>
</listitem>
</varlistentry>
<varlistentry>
</varlistentry>
<varlistentry>
- <term><amkeyword>debug_days</amkeyword> <amtype>int</amtype></term>
+ <term><amkeyword>debug-days</amkeyword> <amtype>int</amtype></term>
<listitem>
<para>Default:
<amdefault>3</amdefault>.
</varlistentry>
<varlistentry>
- <term><amkeyword>debug_auth</amkeyword> <amtype>int</amtype></term>
+ <term><amkeyword>debug-auth</amkeyword> <amtype>int</amtype></term>
<listitem>
<para>Default:
<amdefault>0</amdefault>.
</varlistentry>
<varlistentry>
- <term><amkeyword>debug_event</amkeyword> <amtype>int</amtype></term>
+ <term><amkeyword>debug-event</amkeyword> <amtype>int</amtype></term>
<listitem>
<para>Default:
<amdefault>0</amdefault>.
</varlistentry>
<varlistentry>
- <term><amkeyword>debug_holding</amkeyword> <amtype>int</amtype></term>
+ <term><amkeyword>debug-holding</amkeyword> <amtype>int</amtype></term>
<listitem>
<para>Default:
<amdefault>0</amdefault>.
</varlistentry>
<varlistentry>
- <term><amkeyword>debug_protocol</amkeyword> <amtype>int</amtype></term>
+ <term><amkeyword>debug-protocol</amkeyword> <amtype>int</amtype></term>
<listitem>
<para>Default:
<amdefault>0</amdefault>.
</varlistentry>
<varlistentry>
- <term><amkeyword>debug_planner</amkeyword> <amtype>int</amtype></term>
+ <term><amkeyword>debug-planner</amkeyword> <amtype>int</amtype></term>
<listitem>
<para>Default:
<amdefault>0</amdefault>.
</varlistentry>
<varlistentry>
- <term><amkeyword>debug_driver</amkeyword> <amtype>int</amtype></term>
+ <term><amkeyword>debug-driver</amkeyword> <amtype>int</amtype></term>
<listitem>
<para>Default:
<amdefault>0</amdefault>.
</varlistentry>
<varlistentry>
- <term><amkeyword>debug_dumper</amkeyword> <amtype>int</amtype></term>
+ <term><amkeyword>debug-dumper</amkeyword> <amtype>int</amtype></term>
<listitem>
<para>Default:
<amdefault>0</amdefault>.
</varlistentry>
<varlistentry>
- <term><amkeyword>debug_chunker</amkeyword> <amtype>int</amtype></term>
+ <term><amkeyword>debug-chunker</amkeyword> <amtype>int</amtype></term>
<listitem>
<para>Default:
<amdefault>0</amdefault>.
</varlistentry>
<varlistentry>
- <term><amkeyword>debug_taper</amkeyword> <amtype>int</amtype></term>
+ <term><amkeyword>debug-taper</amkeyword> <amtype>int</amtype></term>
<listitem>
<para>Default:
<amdefault>0</amdefault>.
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><amkeyword>recovery-limit</amkeyword> [ <amtype>string</amtype> | <amkeyword>same-host</amkeyword> ]</term>
+ <listitem>
+<para>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 <manref name="amanda-auth" vol="7"/>; 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 <manref name="amanda-match" vol="7"/>) 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.</para>
+
+<para>Note that match expressions can be constructed to be
+ forgiving of e.g., fully-qualified vs. unqualified hostnames, but
+ <amkeyword>same-host</amkeyword> requires an exact match.</para>
+
+<para>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.</para>
+
+<para>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.</para>
+
+ </listitem>
+ </varlistentry>
+
</variablelist>
</refsect1>
</varlistentry>
<varlistentry>
- <term><amkeyword>amandad_path</amkeyword> <amtype>string</amtype></term>
+ <term><amkeyword>amandad-path</amkeyword> <amtype>string</amtype></term>
<listitem>
<para>Default:
<amdefault>"$libexec/amandad"</amdefault>.
</varlistentry>
<varlistentry>
- <term><amkeyword>client_username</amkeyword> <amtype>string</amtype></term>
+ <term><amkeyword>client-username</amkeyword> <amtype>string</amtype></term>
<listitem>
<para>Default:
<amdefault>CLIENT_LOGIN</amdefault>.
</varlistentry>
<varlistentry>
- <term><amkeyword>client_port</amkeyword> [ <amtype>int</amtype> | <amtype>string</amtype> ]</term>
+ <term><amkeyword>client-port</amkeyword> [ <amtype>int</amtype> | <amtype>string</amtype> ]</term>
<listitem>
<para>Default:
<amdefault>"amanda"</amdefault>.
<varlistentry>
<term>compress client custom</term>
<listitem>
- <para>Specify <emphasis>client_custom_compress</emphasis> "PROG"</para>
+ <para>Specify <amkeyword>client-custom-compress</amkeyword> "PROG"</para>
<para>PROG must not contain white space and it must accept -d for uncompress.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>compress server custom</term>
<listitem>
- <para>Specify <amkeyword>server_custom_compress</amkeyword> "PROG"</para>
+ <para>Specify <amkeyword>server-custom-compress</amkeyword> "PROG"</para>
<para>PROG must not contain white space and it must accept -d for uncompress.</para>
</listitem>
</varlistentry>
</varlistentry>
<varlistentry>
- <term><amkeyword>client_custom_compress</amkeyword> <amtype>string</amtype></term>
+ <term><amkeyword>client-custom-compress</amkeyword> <amtype>string</amtype></term>
<listitem>
<para>Default: none.
The program to use to perform compression/decompression on the client; used with
</varlistentry>
<varlistentry>
- <term><amkeyword>server_custom_compress</amkeyword> <amtype>string</amtype></term>
+ <term><amkeyword>server-custom-compress</amkeyword> <amtype>string</amtype></term>
<listitem>
<para>Default: none.
The program to use to perform compression/decompression on the server; used with
<varlistentry>
<term>encrypt client</term>
<listitem>
- <para>Specify client_encrypt "PROG"</para>
+ <para>Specify client-encrypt "PROG"</para>
<para>PROG must not contain white space.</para>
- <para>Specify client_decrypt_option "decryption-parameter" Default: "-d"</para>
+ <para>Specify client-decrypt-option "decryption-parameter" Default: "-d"</para>
<para>decryption-parameter must not contain white space.</para>
<para>(See dumptype client-encrypt-nocomp in example/amanda.conf for reference)</para>
</listitem>
<varlistentry>
<term>encrypt server</term>
<listitem>
- <para>Specify server_encrypt "PROG"</para>
+ <para>Specify server-encrypt "PROG"</para>
<para>PROG must not contain white space.</para>
- <para>Specify server_decrypt_option "decryption-parameter" Default: "-d"</para>
+ <para>Specify server-decrypt-option "decryption-parameter" Default: "-d"</para>
<para>decryption-parameter must not contain white space.</para>
<para>(See dumptype server-encrypt-fast in example/amanda.conf for reference)</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><amkeyword>client_encrypt</amkeyword> <amtype>string</amtype></term>
+ <term><amkeyword>client-encrypt</amkeyword> <amtype>string</amtype></term>
<listitem>
<para>Default: none.
The program to use to perform encryption/decryption on the client; used with
</varlistentry>
<varlistentry>
- <term><amkeyword>client_decrypt_option</amkeyword> <amtype>string</amtype></term>
+ <term><amkeyword>client-decrypt-option</amkeyword> <amtype>string</amtype></term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><amkeyword>server_encrypt</amkeyword> <amtype>string</amtype></term>
+ <term><amkeyword>server-encrypt</amkeyword> <amtype>string</amtype></term>
<listitem>
<para>Default: none.
The program to use to perform encryption/decryption on the server; used with
</varlistentry>
<varlistentry>
- <term><amkeyword>server_decrypt_option</amkeyword> <amtype>string</amtype></term>
+ <term><amkeyword>server-decrypt-option</amkeyword> <amtype>string</amtype></term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
</listitem>
</varlistentry>
<varlistentry>
- <term><amkeyword>ssh_keys</amkeyword> <amtype>string</amtype></term>
+ <term><amkeyword>ssh-keys</amkeyword> <amtype>string</amtype></term>
<listitem>
<para>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.</para>
</varlistentry>
<varlistentry>
- <term><amkeyword>tape_splitsize</amkeyword> <amtype>int</amtype></term>
+ <term><amkeyword>allow-split</amkeyword> <amtype>bool</amtype></term>
+ <listitem>
+<para>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.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><amkeyword>tape-splitsize</amkeyword> <amtype>int</amtype></term>
<listitem>
+ <para>Deprecated. See "Dump Splitting Configuration" below.</para>
<para>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.</para>
-<para>The default unit is Kbytes if it is not specified.</para>
+The default unit is Kbytes if it is not specified.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><amkeyword>split_diskbuffer</amkeyword> <amtype>string</amtype></term>
+ <term><amkeyword>split-diskbuffer</amkeyword> <amtype>string</amtype></term>
+ <para>Deprecated. See "Dump Splitting Configuration" below.</para>
<listitem>
<para>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.
</varlistentry>
<varlistentry>
- <term><amkeyword>fallback_splitsize</amkeyword> <amtype>int</amtype></term>
+ <term><amkeyword>fallback-splitsize</amkeyword> <amtype>int</amtype></term>
<listitem>
+ <para>Deprecated. See "Dump Splitting Configuration" below.</para>
<para>Default:
<amdefault>10M</amdefault>.
-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 <amkeyword>split-diskbuffer</amkeyword> 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.
-</para>
-<para>The default unit is Kbytes if it is not specified.</para>
+The default unit is Kbytes if it is not specified.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><amkeyword>recovery-limit</amkeyword>
+ [ <amkeyword>same-host</amkeyword> | <amtype>string</amtype> ]*</term>
+ <listitem>
+
+<para>Default: global value. This parameter overrides the global
+ <amkeyword>recovery-limit</amkeyword> parameter for DLEs of this
+ dumptype.</para>
+
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><amkeyword>part-size</amkeyword> <amtype>int</amtype></term>
+ <listitem>
+<para>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
+<amkeyword>part-cache-max-size</amkeyword> 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.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><amkeyword>part-cache-type</amkeyword> [ <amkeyword>none</amkeyword> | <amkeyword>disk</amkeyword> | <amkeyword>memory</amkeyword> ] </term>
+ <listitem>
+<para>Default: none. When part caching is required, this parameter specifies
+the type of caching that will be used. The options include no caching
+(<amkeyword>none</amkeyword>), in which case a failed part will cause the
+entire dump to fail; on-disk caching (<amkeyword>disk</amkeyword>), for
+which <amkeyword>part-cache-dir</amkeyword> must be set properly; and
+in-memory caching (<amkeyword>memory</amkeyword>), which on most systems
+severely restrains the size of the part that can be written. See "Dump
+Splitting Configuration" below.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><amkeyword>part-cache-dir</amkeyword> <amtype>string</amtype></term>
+ <listitem>
+<para>Default: none.
+The directory in which part-cache files can be written when caching on disk.
+See "Dump Splitting Configuration" below.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><amkeyword>part-cache-max-size</amkeyword> <amtype>int</amtype></term>
+ <listitem>
+<para>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.</para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><amkeyword>speed</amkeyword> <amtype>int</amtype></term>
<listitem>
<para>In addition to options, another
<amkeyword>tapetype</amkeyword>
-name may be supplie as an identifier, which makes this
+name may be supplied as an identifier, which makes this
<amkeyword>tapetype</amkeyword>
inherit options from another
<amkeyword>tapetype</amkeyword>.
</listitem>
</varlistentry>
<varlistentry>
- <term><amkeyword>execute_where</amkeyword> [ <amkeyword>client</amkeyword> | <amkeyword>server</amkeyword> ]</term>
+ <term><amkeyword>execute-where</amkeyword> [ <amkeyword>client</amkeyword> | <amkeyword>server</amkeyword> ]</term>
<listitem>
<para>Default: <amkeyword>client</amkeyword>. Where the script must be executed, on the client or server.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><amkeyword>>execute_on</amkeyword> <amtype>execute_on</amtype> [,<amtype>execute_on</amtype>]*</term>
+ <term><amkeyword>execute-on</amkeyword> <amtype>execute_on</amtype> [,<amtype>execute_on</amtype>]*</term>
<listitem>
<para>No default. When the script must be executed, you can specify many of them:</para>
<!-- .RS -->
</listitem>
</varlistentry>
<varlistentry>
- <term><amkeyword>property</amkeyword>> [<amkeyword>append</amkeyword>] [<amkeyword>priority</amkeyword>] <amtype>string</amtype> <amtype>string</amtype>+</term>
+ <term><amkeyword>property</amkeyword> [<amkeyword>append</amkeyword>] [<amkeyword>priority</amkeyword>] <amtype>string</amtype> <amtype>string</amtype>+</term>
<listitem>
<para>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.
define device <emphasis remap='I'>name</emphasis> {
commend "<emphasis remap='I'>comment (optional)</emphasis>"
tapedev "<emphasis remap='I'>device-specifier</emphasis>"
- device_property "<emphasis remap='I'>prop-name</emphasis>" "<emphasis remap='I'>prop-value</emphasis>"
+ device-property "<emphasis remap='I'>prop-name</emphasis>" "<emphasis remap='I'>prop-value</emphasis>"
<literal>...</literal>
}
</programlisting>
parmeter is optional and only for the user's convenience.</para>
<para>An arbitrary number of <emphasis
-remap='I'>device_property</emphasis> parameters can be specified.
+remap='I'>device-property</emphasis> parameters can be specified.
Again, see
<manref name="amanda-devices" vol="7"/>
for information on device properties.</para>
</refsect1>
+<refsect1><title>Dump Splitting Configuration</title>
+
+ <para>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.</para>
+
+ <para>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.</para>
+
+ <para>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.</para>
+
+ <para>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.</para>
+
+ <para>In versions of Amanda through 3.1.*, splitting was controlled by the
+ dumptype parameters <amkeyword>tape-splitsize</amkeyword>,
+ <amkeyword>split-diskbuffer</amkeyword>, and
+ <amkeyword>fallback-splitsize</amkeyword>. These keywords had
+ confusing and non-intuitive interactions, and have since been
+ deprecated.</para>
+
+ <para>If the deprecated keywords are not present, subsequent versions
+ of Amanda use the dumptype parameter
+ <amkeyword>allow-split</amkeyword> to control whether a DLE can be
+ split, and the <emphasis>tapetype</emphasis> parameters
+ <amkeyword>part-size</amkeyword>,
+ <amkeyword>part-cache-type</amkeyword>,
+ <amkeyword>part-cache-dir</amkeyword>, and
+ <amkeyword>part-cache-max-size</amkeyword>. The
+ <amkeyword>part-size</amkeyword> specifies the "normal" part size,
+ while the <amkeyword>part-cache-*</amkeyword> parameters describe
+ how to behave when caching is required (on PORT-WRITE). Full
+ details on these parameters are given above.</para>
+
+</refsect1>
+
<seealso>
<manref name="amanda-client.conf" vol="5"/>,
<manref name="amanda-applications" vol="7"/>,