"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
[
<!-- entities files to use -->
- <!ENTITY % global_entities SYSTEM '../entities/global.entities'>
+ <!ENTITY % global_entities SYSTEM 'global.entities'>
%global_entities;
]>
</refmeta>
<refnamediv>
<refname>amvault</refname>
-<refpurpose>Copy &A; dumps from one volume to another</refpurpose>
+<refpurpose>Copy Amanda dumps from one volume to another</refpurpose>
</refnamediv>
<refentryinfo>
&author.dustin;
<refsynopsisdiv>
<cmdsynopsis>
<command>amvault</command>
- <arg choice='plain' rep='repeat'><group><arg choice='plain'>-o </arg><replaceable>configoption</replaceable></group></arg>
+ &configoverride.synopsis;
+ <group choice='opt'><arg choice='plain'>--dry-run</arg><arg choice='plain'>-n</arg></group>
+ <group choice='opt'><arg choice='plain'>--quiet</arg><arg choice='plain'>-q</arg></group>
+ <arg choice='opt'>--fulls-only </arg>
+ <arg choice='opt'>--export </arg>
+ <arg choice='opt'><option>--src-timestamp</option>
+ <replaceable>src-timestamp</replaceable></arg>
+ <sbr/>
+ <arg choice='plain'><option>--label-template</option>
+ <replaceable>label-template</replaceable></arg>
+ <arg choice='plain'><option>--dst-changer</option>
+ <replaceable>dst-changer</replaceable></arg>
+ <arg choice='opt' rep='repeat'><option>--autolabel</option>
+ <replaceable>autolabel-arg</replaceable></arg>
+ <sbr/>
<arg choice='plain'><replaceable>config</replaceable></arg>
- <arg choice='plain'><replaceable>src-run-timestamp</replaceable></arg>
- <arg choice='plain'><replaceable>dst-changer</replaceable></arg>
- <arg choice='plain'><replaceable>label-template</replaceable></arg>
+ <arg choice='opt'>
+ <arg choice='plain'><replaceable>hostname</replaceable></arg>
+ <arg choice='opt'>
+ <arg choice='plain'><replaceable>disk</replaceable></arg>
+ <arg choice='opt'>
+ <arg choice='plain'><replaceable>date</replaceable></arg>
+ <arg choice='opt'>
+ <arg choice='plain'><replaceable>level</replaceable></arg>
+ <arg choice='opt'>
+ <arg choice='plain'><replaceable>hostname</replaceable></arg>
+ <arg choice='opt'>...</arg>
+ </arg>
+ </arg>
+ </arg>
+ </arg>
+ </arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>WARNING</title>
+
<para>This application is not yet in its final form, and is subject to major revision
in subsequent versions of Amanda. Backward compatibility is not guaranteed.</para>
-<para>The significant limitations of this version of amvault are: tapetypes for
-secondary and tertiary volumes much match (including length and
-device_properties); tertiary volumes must be blank (manual erasure is required
-to re-use tertiary media; restore/recover operations will request tertiary
-media by label when dumpfiles are not found on secondary media, but there is no
-provision to automatically fetch such media from a different changer; and all
-dumpfiles on a secondary volume are moved to tertiary media - there is no
-provision to filter dumps.</para>
+<para>Note that Amanda restore/recover operations will request tertiary media
+by label when dumpfiles are not found on secondary media, but there is no
+provision to automatically fetch such media from a different changer</para>
<para>Feedback on and patches to this application are invited and
encouraged!</para>
<refsect1><title>DESCRIPTION</title>
+<para>Amvault is conceptually equivalent to "amfetchdump | taper". That is, it reads
+specified dumps from secondary media and re-writes them on tertiary media.</para>
+
<para><emphasis remap='B'>Amvault</emphasis> Copies data from the run with
-timestamp <emphasis remap='I'>src-run-timestamp</emphasis> onto volumes using
-the changer <emphasis remap='I'>dst-changer</emphasis>, labeling new volumes
-with <emphasis remap='I'>label-template</emphasis>. If <emphasis
-remap='I'>src-run-timestamp</emphasis> is "latest", then the most recent amdump
-or amflush run will be used.</para>
+timestamp <option>src-timestamp</option> onto volumes using the changer
+<option>dst-changer</option>, and labeling new volumes with
+<option>label-template</option>.</para>
+
+<refsect2><title>Secondary Media</title>
+
+<para>The dumps to be read from secondary media can be specified by any
+combination of dump specifications, <option>--fulls-only</option>, and
+<option>--src-timestamp</option>. At least one must be specified, lest
+amvault attempt to vault all dumps in the catalog. See <manref
+ name="amanda-match" vol="7"/> for more information on dump
+specifications.</para>
+
+<para>Note that the datestamp given in the dumpspec is the
+<emphasis>dump</emphasis> datestamp - the run in which the backup was taken
+on the Amanda client. The <option>--src-timestamp</option>, on the other
+hand, is the <emphasis>write</emphasis> timestamp - the run in which the
+dump was written to secondary media. The latter option facilitates
+duplicating the results of an entire backup run, including any dumps that
+might have been flushed from holding disk.</para>
+
+</refsect2>
+
+<refsect2><title>Tertiary Media</title>
+
+<para>The <option>--dst-changer</option> must be specified, and names the
+changer in which tertiary media are stored.</para>
-<para>In a vaulting operation, the source media is referred to as "secondary
-media", while the destination is referred to as "tertiary media".</para>
+<para>If &amconf; contains the new <amkeyword>part-size</amkeyword>
+splitting parameters, then amvault will use them without any additional configuration.
+However, if the configuration still uses the old splitting parameters
+(<amkeyword>tape_splitsize</amkeyword>,
+<amkeyword>split_diskbuffer</amkeyword>, and
+<amkeyword>fallback_splitsize</amkeyword>), then amvault will need some
+additional configuration in order to properly split dumps to tertiary
+media. To do so, specify a new tapetype in &amconf;, say "TERTIARY",
+and set the <amkeyword>part-size</amkeyword> and other appropriate
+parameters there. Then reference that tapetype in the amvault invocation:
+<programlisting>
+ amvault -otapetype=TERTIARY ...
+</programlisting></para>
+
+</refsect2>
+
+</refsect1>
+
+<refsect1><title>OPTIONS</title>
+<variablelist remap='TP'>
+ <varlistentry>
+ <term><option>--autolabel</option> <arg choice='opt'>any</arg>
+ <arg choice='opt'>other-config</arg>
+ <arg choice='opt'>non-amanda</arg>
+ <arg choice='opt'>volume-error</arg>
+ <arg choice='opt'>empty</arg></term>
+ <listitem>
+<para>Works just like the
+<amkeyword>autolabel</amkeyword> parameter in &amconf;, and can be
+specified multiple times if necessary. The default is 'empty'.</para>
+ </listitem>
+ </varlistentry>
-<para>Each source volume will be copied to a new destination volume; no
-re-assembly or splitting will be performed. Destination volumes must be at
-least as large as the source volumes.</para>
+ <varlistentry>
+ <term><option>--dst-changer</option> <replaceable>dst-changer</replaceable></term>
+ <listitem>
+<para>Specifies the changer
+in which tertiary media are stored. In general, this should be different
+from the secondary changer, to eliminate the possibility of overwriting
+secondary media with tertiary data.</para>
-<para>The changer parameter should specify the name of a changer defined in
+<para>The <amkeyword>dst-changer</amkeyword> parameter should specify the name of a changer defined in
&amconf;. For example:
<programlisting>
define changer vaulting_tape {
changerfile "vaulting-changer.conf"
}
</programlisting></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--dry-run</option></term><term><option>-n</option></term>
+ <listitem>
+<para>Cause amvault to print the dumps it would vault, but not actually
+perform any vaulting operations.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--export</option></term>
+ <listitem>
+<para>Cause amvault to attempt to move completed tertiary volumes to
+import/export slots, where they can be more easily removed by an operator.
+</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>---fulls-only</option></term>
+ <listitem>
+<para>Only full (level-0) dumps are copied.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--label-template</option> <replaceable>label-template</replaceable></term>
+ <listitem>
+<para>Specifies a label template which is used to generate new labels for
+tertiary volumes.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--quiet</option></term><term><option>-q</option></term>
+ <listitem>
+<para>Eliminate non-error messages, and is useful when running amvault from
+cron.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--src-timestamps</option> <replaceable>src-timestamps</replaceable></term>
+ <listitem>
+<para>Specifies the timestamps in the format 'YYYYMMDDHHMMSS' of the run to
+vault, can be "latest", then the most recent amdump or amflush run will be
+used.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-o</option> <replaceable>configoption</replaceable></term>
+ <listitem>
+<para>See the "<emphasis remap='B'>CONFIGURATION OVERRIDE</emphasis>"
+ section in <manref name="amanda" vol="8"/>.</para>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
-<para>The label template functions identically to the <emphasis
-remap='I'>label-new-tapes</emphasis> parameter in &amconf;.</para>
</refsect1>
-<refsect1><title>SEE ALSO</title>
-<para><citerefentry><refentrytitle>amanda</refentrytitle><manvolnum>8</manvolnum></citerefentry></para>
+<refsect1><title>EXAMPLES</title>
+
+<para>Vault all dump written to tape in the latest amdump or amflush run:</para>
+<programlisting>
+$ amvault --src-timestamps latest --label-template "CONF-%%%" --dst-changer vault-changer CONF
+</programlisting>
+
+<para>Vault all dump written on the run of December 7 2011 12:13:14 :</para>
+<programlisting>
+$ amvault --src-timestamps 20111207121314 --label-template "CONF-%%%" --dst-changer vault-changer CONF
+</programlisting>
+
+<para>Vault all dump dumped on any run of December 7 2011:</para>
+<programlisting>
+$ amvault --label-template "CONF-%%%" --dst-changer vault-changer CONF \* \* 20111207
+</programlisting>
+
</refsect1>
+
+<seealso>
+<manref name="amanda-changers" vol="7"/>
+<manref name="amfetchdump" vol="8"/>
+</seealso>
+
</refentry>