"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>amrestore</refname>
-<refpurpose>extract backup images from an &A; tape</refpurpose>
+<refpurpose>low-level data-extraction from Amanda volumes</refpurpose>
</refnamediv>
<refentryinfo>
&author.jds;
&author.sgw.xml;
+&author.dustin;
</refentryinfo>
<!-- body begins here -->
<refsynopsisdiv>
<cmdsynopsis>
<command>amrestore</command>
+ <arg choice='opt'>--config <replaceable>config</replaceable></arg>
<group choice='opt'><arg choice='plain'>-r </arg><arg choice='plain'>-c </arg><arg choice='plain'>-C </arg></group>
- <group><arg choice='plain'>-b</arg><arg choice='plain'><replaceable>blocksize</replaceable></arg></group>
- <group><arg choice='plain'>-f</arg><arg choice='plain'><replaceable>fileno</replaceable></arg></group>
- <group><arg choice='plain'>-l </arg><arg choice='plain'><replaceable>label</replaceable></arg></group>
+ <arg choice='opt'>-b <replaceable>blocksize</replaceable></arg>
+ <arg choice='opt'>-f <replaceable>filenum</replaceable></arg>
+ <arg choice='opt'>-l <replaceable>label</replaceable></arg>
<arg choice='opt'>-p</arg>
<arg choice='opt'>-h</arg>
- <arg choice='plain'><arg choice='plain'><replaceable>tapedevice</replaceable></arg>|<arg choice='plain'><replaceable>holdingfile</replaceable></arg></arg>
- <group><arg choice='plain'><replaceable>hostname</replaceable></arg><group><arg choice='plain'><replaceable>diskname</replaceable></arg><group><arg choice='plain'><replaceable>datestamp</replaceable></arg><group><arg choice='plain'><replaceable>hostname</replaceable></arg><group><arg choice='plain'><replaceable>diskname</replaceable></arg><group><arg choice='plain'><replaceable>datestamp</replaceable></arg><arg choice='plain'>...</arg></group></group></group></group></group></group>
+ &configoverride.synopsis;
+ <group>
+ <arg choice='req'><replaceable>changerspec</replaceable></arg>
+ <arg choice='req'><arg choice='opt'>--holding</arg>
+ <replaceable>holdingfile</replaceable></arg>
+ </group>
+ <arg choice='opt'>
+ <replaceable>hostname</replaceable>
+ <arg choice='opt'>
+ <replaceable>diskname</replaceable>
+ <arg choice='opt'>
+ <replaceable>datestamp</replaceable>
+ <arg choice='opt'>
+ <replaceable>hostname</replaceable>
+ <arg choice='opt'>
+ <replaceable>diskname</replaceable>
+ <arg choice='opt'>
+ <replaceable>datestamp</replaceable>
+ ...
+ </arg>
+ </arg>
+ </arg>
+ </arg>
+ </arg>
+ </arg>
</cmdsynopsis>
-</refsynopsisdiv>
+<para>Note that this is the only Amanda command which does not take a configuration name as its first argument.</para>
+
+</refsynopsisdiv>
<refsect1><title>DESCRIPTION</title>
-<para><emphasis remap='B'>Amrestore</emphasis>
-extracts backup images from the tape mounted on
-<emphasis remap='I'>tapedevice</emphasis>
-or from the holding disk file
-<emphasis remap='I'>holdingfile</emphasis>
-that match
-<emphasis remap='I'>hostname</emphasis>,
-<emphasis remap='I'>diskname</emphasis>
-and
-<emphasis remap='I'>datestamp</emphasis>
-patterns given on the command line.
-The tape or holding file must be in a format written by the
-<emphasis remap='B'>amdump</emphasis>
-or
-<emphasis remap='B'>amflush</emphasis>
-program.</para>
-
-<para>If
-<emphasis remap='I'>diskname</emphasis>
-is not specified, all backups on the tape for the previous
-<emphasis remap='I'>hostname</emphasis>
-are candidates.
-If
-<emphasis remap='I'>datestamp</emphasis>
-is not specified, all backups on the tape for the previous
-<emphasis remap='I'>hostname</emphasis>
-and
-<emphasis remap='I'>diskname</emphasis>
-are candidates.
-If no
-<emphasis remap='I'>hostname</emphasis>,
-<emphasis remap='I'>diskname</emphasis>
-or
-<emphasis remap='I'>datestamp</emphasis>
-are specified, every backup on the tape is a candidate.</para>
-
-<para><emphasis remap='I'>Hostname</emphasis>
-and
-<emphasis remap='I'>diskname</emphasis>
-are special expressions described in the "HOST & DISK EXPRESSION" section
-of
-<citerefentry><refentrytitle>amanda</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
-<emphasis remap='I'>Datestamp</emphasis>
-are special expression described in the "DATESTAMP EXPRESSION" section
-of
-<citerefentry><refentrytitle>amanda</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
-For example, if
-<emphasis remap='I'>diskname</emphasis>
-is "rz[23]a", it would match disks
-<emphasis remap='B'>rz2a</emphasis>
-and
-<emphasis remap='B'>rz3a</emphasis>.</para>
-
-<para><emphasis remap='I'>Datestamp</emphasis>
-is useful if
-<emphasis remap='B'>amflush</emphasis>
-writes multiple backup runs to a single tape.</para>
-
-<para>Unless
-<option>-p</option>
-is used,
-candidate backup images are extracted to files
-in the current directory named:</para>
-
-<!-- .RS -->
-<para><emphasis remap='I'>hostname.diskname.datestamp.dumplevel</emphasis></para>
-<!-- .RE -->
-
-<para>Amrestore doesn't use a changer, it restore from the tape already loaded
-in the
-<emphasis remap='I'>tapedevice.</emphasis></para>
-</refsect1>
-<refsect1><title>OPTIONS</title>
-<variablelist remap='TP'>
- <varlistentry>
- <term><option>-b</option></term>
- <listitem>
-<para>Set the blocksize used to read the tape or holding file.
-All holding files must be read with a blocksize of 32 KBytes.
-<emphasis remap='B'>Amrestore</emphasis>
-should normally be able to determine the blocksize for tapes
-on its own and not need this parameter.</para>
- </listitem>
- </varlistentry>
-</variablelist>
+<para><emphasis>Amrestore</emphasis> is a very low-level tool for extracting
+data from Amanda volumes. It does not consult any catalog information or other
+metadata, basing its operations only on the headers found on the volume. This
+makes it an appropriate tool for bare-metal restores of an Amanda server, or
+other situations where the catalog is not available.</para>
+
+<para>See <manref name="amfetchdump" vol="8"/> and <manref name="amrecover"
+vol="8"/> for higher-level recoveries.</para>
+
+<para>The tool does not reassemble split dumps, but can uncompress compressed
+dumps. Note that decompression may fail for split parts after the first. If
+this occurs, extract the parts without decompressing, concatenate them, and
+decompress the result.</para>
+
+<para>Data is restored from the current volume in
+<replaceable>changerspec</replaceable>, or from the holding file
+<replaceable>holdingfile</replaceable>. In most cases,
+<replaceable>changerspec</replaceable> will name a particular device, e.g.,
+<computeroutput>tape:/dev/nst0</computeroutput> or
+<computeroutput>s3:mybucket/tape-1</computeroutput>.</para>
+
+<para>Only dumps matching the dump specification beginning with
+<replaceable>hostname</replaceable> are extracted. If no specification is
+given, every file on the volume (or the entire holdingfile) is restored. See
+the "HOST & DISK EXPRESSIONS" section of <manref name="amanda" vol="8"/>
+for the format of the <replaceable>hostname</replaceable> and
+<replaceable>diskname</replaceable> parameters, and the "DATESTAMP EXPRESSIONS"
+section for the format of the <replaceable>datestamp</replaceable>
+parameters.</para>
+
+<para>Unless <option>-p</option> is used, candidate backup images are extracted
+to files in the current directory named:
+<filename>hostname.diskname.datestamp.dumplevel</filename></para>
-<para>The default is 32 KBytes.</para>
-<variablelist remap='TP'>
- <varlistentry>
- <term><option>-f</option></term>
- <listitem>
-<para>Do a rewind followed by a fsf <fileno> before trying to restore an image.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>-l</option></term>
- <listitem>
-<para>Check if we restoring from the tape with the right
-<emphasis remap='I'>label</emphasis></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>-p</option></term>
- <listitem>
-<para>Pipe output.
-The first matching backup image is sent to standard output,
-which is normally a pipe to
-<emphasis remap='B'>restore</emphasis>
-or
-<emphasis remap='B'>tar</emphasis>,
-then
-<command>amrestore</command>
-quits.
-It may be run again to continue selecting backups to process.
-Make sure you specify the no-rewind
-<emphasis remap='I'>tapedevice</emphasis>
-when doing this.</para>
- </listitem>
- </varlistentry>
-</variablelist>
+</refsect1>
-<para>Note:
-<emphasis remap='B'>restore</emphasis>
-may report "short read" errors when reading from a pipe.
-Most versions of
-<emphasis remap='B'>restore</emphasis>
-support a blocking factor option to let you set the read block size,
-and you should set it to 2.
-See the example below.</para>
-<variablelist remap='TP'>
- <varlistentry>
- <term><option>-c</option></term>
- <listitem>
-<para>Compress output using the fastest method the compression program provides.
-<emphasis remap='B'>Amrestore</emphasis>
-normally writes output files in a format understood by
-<emphasis remap='B'>restore</emphasis>
-or
-<emphasis remap='B'>tar</emphasis>,
-even if the backups on the tape are compressed.
-With the
-<option>-c</option>
-or
-<option>-C</option>
-option,
-<command>amrestore</command>
-writes all files in compressed format,
-even if the backups on the tape are not compressed.
-Output file names will have a
-<markup>.Z</markup>
-or
-<markup>.gz</markup>
-extension depending on whether
-<emphasis remap='B'>compress</emphasis>
-or
-<emphasis remap='B'>gzip</emphasis>
-is the preferred compression program.
-This option is useful when the current directory disk is small.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>-C</option></term>
- <listitem>
-<para>Compress output using the best method the compression program provides
-(may be very CPU intensive).
-See the notes above about the
-<option>-c</option>
-option.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>-r</option></term>
- <listitem>
-<para>Raw output.
-Backup images are output exactly as they are on the tape,
-including the
-<emphasis remap='B'>amdump</emphasis>
-headers.
-Output file names will have a
-<markup>.RAW</markup>
-extension.
-This option is only useful for debugging and other strange circumstances.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>-h</option></term>
- <listitem>
-<para>Header output.
-The tape header block is output at the beginning of each file.
-This is like
-<option>-r</option>
-except
-<option>-c</option>
-or
-<option>-C</option>
-may also be used to compress the result.
-<emphasis remap='B'>Amrecover</emphasis>
-uses the header to determine the restore program to use.</para>
- </listitem>
- </varlistentry>
-</variablelist>
+<refsect1><title>OPTIONS</title>
+<variablelist>
+
+<varlistentry>
+<term><option>-b <replaceable>blocksize</replaceable></option></term>
+<listitem>
+<para>Use the given blocksize to read the volume. The default is defined by the
+device.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-f <replaceable>filenum</replaceable></option></term>
+<listitem>
+<para>Seek to file <replaceable>filenum</replaceable> before beginning the
+restore operation.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-l <replaceable>label</replaceable></option></term>
+<listitem>
+<para>Check that the volume has label <replaceable>label</replaceable>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-p</option></term>
+<listitem>
+<para>Pipe the first matching file to standard output. This is typically used
+in a shell pipeline to send the data to a process like <command>tar</command> for
+extraction.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-c</option></term>
+<term><option>-C</option></term>
+<listitem>
+<para>If the file is not already compressed, compress it using the fastest
+(<option>-c</option>) or best (<option>-C</option>) compression algorithm.
+Note that <command>amrestore</command> will not re-compress an
+already-compressed file. Without either of these options,
+<command>amrestore</command> will automatically uncompress any compressed
+files. This option is useful when the destination disk is small.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-h</option></term>
+<listitem>
+<para>Include 32k headers on all output files, similar to a holding file. This
+header can be read by another application or utility (see
+<command>Amanda::Header</command>) during the next phase of processing.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-r</option></term>
+<listitem>
+<para>Output raw files. This is similar to <option>-h</option>, but also
+disables any automatic decompression. Output file names will have a
+<filename>.RAW</filename> extension.</para>
+</listitem>
+</varlistentry>
+
+ &configoverride.varlistentry;
-<para>If a header is written (-r or -h),
-only 32 KBytes are output regardless of the tape blocksize.
-This makes the resulting image usable as a holding file.</para>
-
-<variablelist remap='TP'>
- <varlistentry>
- <term><emphasis remap='B'>-o</emphasis> <replaceable>configoption</replaceable></term>
- <listitem>
-<para>See the "<emphasis remap='B'>CONFIGURATION OVERRIDE</emphasis>" section in <citerefentry><refentrytitle>amanda</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
- </listitem>
- </varlistentry>
</variablelist>
</refsect1>
<refsect1><title>EXAMPLES</title>
+
<para>The following does an interactive restore of disk
-<emphasis remap='I'>rz3g</emphasis>
-from host
-<emphasis remap='I'>seine</emphasis>,
-to restore particular files.
-Note the use of the
-<emphasis remap='B'>b</emphasis>
-option to
-<emphasis remap='B'>restore</emphasis>,
-which causes it to read in units of two 512-byte blocks (1 Kbyte)
-at a time.
-This helps keep it from complaining about short reads.</para>
-
-<!-- .RS -->
-<literallayout remap='.nf'>
-% amrestore -p /dev/nrmt9 seine rz3g | restore -ivbf 2 -
-</literallayout> <!-- .fi -->
+<emphasis>rz3g</emphasis> from host <emphasis>seine</emphasis>, to restore
+particular files. Note the use of the <emphasis>b</emphasis> option to
+<emphasis>restore</emphasis>, which causes it to read in units of two 512-byte
+blocks (1 Kbyte) at a time. This helps keep it from complaining about short
+reads.</para>
+
+<programlisting>
+ amrestore -p /dev/nrmt9 seine rz3g | tar -xv
+</programlisting>
<para>The next example extracts all backup images for host
-<emphasis remap='I'>seine</emphasis>.
-This is the usual way to extract all data for a host after a disk crash.</para>
+<emphasis>seine</emphasis>. This is a typical way to extract all data for a
+host after a disk crash.</para>
-<!-- .RS -->
-<literallayout remap='.nf'>
-% amrestore /dev/nrmt9 seine
-</literallayout> <!-- .fi -->
+<programlisting>
+ amrestore /dev/nrmt9 seine
+</programlisting>
<para>If the backup datestamp in the above example is
-<literal>19910125</literal>
-and
-<emphasis remap='I'>seine</emphasis>
-has level 0 backups of disks
-<emphasis remap='I'>rz1a</emphasis>
-and
-<emphasis remap='I'>rz1g</emphasis>
-on the tape,
+<literal>20070125</literal> and <emphasis>seine</emphasis> has level 0 backups
+of disks <emphasis>rz1a</emphasis> and <emphasis>rz1g</emphasis> on the tape,
these files will be created in the current directory:</para>
-<!-- .RS -->
-<literallayout remap='.nf'>
-seine.rz1a.19910125.0
-seine.rz1g.19910125.0
-</literallayout> <!-- .fi -->
-
-<para>You may also use
-<command>amrestore</command>
-to extract a backup image from a holding disk
-file that has not yet been flushed to tape:</para>
-
-<!-- .RS -->
-<literallayout remap='.nf'>
-% amrestore -p /amanda/20001119/seine.rz1a.2 | restore -ivbf 2 -
-</literallayout> <!-- .fi -->
-
-<para><emphasis remap='B'>Amrestore</emphasis>
-may be used to generate a listing of images on a tape:</para>
-
-<!-- .RS -->
-<literallayout remap='.nf'>
-% mt -f /dev/nrmt9 rewind
-% amrestore -p /dev/nrmt9 no-such-host > /dev/null
-</literallayout> <!-- .fi -->
-
-<para>This asks
-<command>amrestore</command>
-to find images for host
-<emphasis remap='B'>no-such-host</emphasis>.
-It will not find any entries that match, but along the way will report
-each image it skips.</para>
+<programlisting>
+ seine.rz1a.19910125.0
+ seine.rz1g.19910125.0
+</programlisting>
+
+<para>You may also use <command>amrestore</command> to extract a backup image
+from a holding disk file that has not yet been flushed to tape:</para>
+
+<programlisting>
+ amrestore -p /amanda/20001119/seine.rz1a.2 | tar -xv
+</programlisting>
+
</refsect1>
<refsect1><title>CAVEATS</title>
+
<para>&gnutar; must be used to restore files from backup images created with
-the GNUTAR dumptype.
-Vendor tar programs sometimes fail to read GNU tar images.</para>
-</refsect1>
+the GNUTAR dumptype. Vendor tar programs sometimes fail to read GNU Tar
+images.</para>
-<refsect1><title>SEE ALSO</title>
-<para><citerefentry><refentrytitle>amanda</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-<citerefentry><refentrytitle>amdump</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-<citerefentry><refentrytitle>amflush</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-<citerefentry><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-<citerefentry><refentrytitle>restore</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-<ulink url="http://wiki.zmanda.com"/>
-</para>
</refsect1>
+
+<seealso>
+<manref name="amfetchdump" vol="8"/>,
+<manref name="amrecover" vol="8"/>,
+</seealso>
+
</refentry>
projects / debian / amanda / blobdiff