<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
[
<!-- entities files to use -->
<!ENTITY % global_entities SYSTEM 'global.entities'>
%global_entities;
]>
<!-- lifted from troff+man by doclifter -->
<refentry id='amreport.8'>
<refmeta>
<refentrytitle>amreport</refentrytitle>
<manvolnum>8</manvolnum>
&rmi.source;
&rmi.version;
&rmi.manual.8;
</refmeta>
<refnamediv>
<refname>amreport</refname>
<refpurpose>generate a formatted output of statistics for an Amanda run</refpurpose>
</refnamediv>
<refentryinfo>
&author.sgw.xml;
</refentryinfo>
<!-- body begins here -->
<refsynopsisdiv>
<cmdsynopsis>
<command>amreport</command>
&configoverride.synopsis;
<group>
<synopfragmentref linkend="cmdline">command-line options</synopfragmentref> | <synopfragmentref linkend="script">script options</synopfragmentref>
</group>
<arg choice='opt'><replaceable>config</replaceable></arg>
<synopfragment id="cmdline">
<arg choice='opt'>--log=<replaceable>logfile</replaceable></arg>
<arg choice='opt'>--format=<replaceable>MODULE:DEST,DEST-ARG</replaceable></arg>
<arg choice='opt'>--ps=<replaceable>filename</replaceable></arg>
<arg choice='opt'>--text=<replaceable>filename</replaceable></arg>
<arg choice='opt'>--xml=<replaceable>filename</replaceable></arg>
<arg choice='opt'>--print=<replaceable>printer</replaceable></arg>
<arg choice='opt'>--mail-text=<replaceable>recipient</replaceable></arg>
</synopfragment>
<synopfragment id="script">
<arg choice='opt'>-i</arg>
<arg choice='opt'>-M <replaceable>address</replaceable></arg>
<arg choice='opt'>-l <replaceable>logfile</replaceable></arg>
<arg choice='opt'>-f <replaceable>outputfile</replaceable></arg>
<arg choice='opt'>-p <replaceable>postscriptfile</replaceable></arg>
<arg choice='opt'>--from-amdump</arg>
</synopfragment>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>DESCRIPTION</title>
<para><emphasis remap='B'>Amreport</emphasis> generates a summary report of an
Amanda backup run. </para>
<para>See the <manref name="amanda" vol="8"/> man page for more details about
Amanda.</para>
</refsect1>
<refsect1><title>OPTIONS</title>
<variablelist remap='TP'>
<varlistentry>
<term><emphasis remap='I'>config</emphasis></term>
<listitem>
<para>Name of the configuration to process. If no configuration name is
specified, amanda.conf is read from the current directory.</para>
</listitem>
</varlistentry>
&configoverride.varlistentry;
</variablelist>
<para>Amreport operates in two distinct modes. Command-line mode is intended for use
by an administrator from the command line, and uses long command-line options
for clarity. Script mode is intended for use from scripts such as amdump, and
has a lot of non-obvious default behaviors to suit that need.</para>
<para>Unless a script-mode option is given, amreport defaults to command-line mode.
If no options are given, amreport writes a report for the most recent logfile to
stdout.</para>
<refsect2><title>Command-Line Mode Options</title>
<variablelist remap='TP'>
<varlistentry>
<term><option>--log=<replaceable>logfile</replaceable></option></term>
<listitem>
<para>Use this logfile as the basis for the report. If this option is given, then
the report is a "historical" report and will not include current state from
e.g., holding disk and curinfo. If this option is not specified, then the
most recent logfile will be used.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--format=<replaceable>MODULE:DEST,DEST-ARG</replaceable></option></term>
<listitem>
<para>Use the given perl module to format the report and send it to DEST with the given DEST-ARG.</para>
<para>Valid module provided with amanda are: human, json, json_raw, ps and xml,
valid destination are file, mail and print, the DEST-ARG depend on the
destination.</para>
<para>The default destination is file.</para>
<para>The default arg for file destination is '-' (stdout).</para>
<para>The default arg for mail destination is the MAILTO configuration option.</para>
<para>The default arg for print destination is the PRINTER configuration option.</para>
<para>Examples:</para>
<programlisting>
<option>--format=<replaceable>human</replaceable></option>
<option>--format=<replaceable>human:mail</replaceable></option>
<option>--format=<replaceable>human:mail:root</replaceable></option>
<option>--format=<replaceable>human:file:/tmp/report.text</replaceable></option>
<option>--format=<replaceable>xml:file:/tmp/report.xml</replaceable></option>
<option>--format=<replaceable>ps:file:/tmp/report.ps</replaceable></option>
<option>--format=<replaceable>ps:print:lp</replaceable></option>
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--ps=<replaceable>filename</replaceable></option></term>
<listitem>
<para>Write a postscript label to <replaceable>filename</replaceable>.
See "LABEL PRINTING" below. If filename is not specified, then the
label is written to stdout.</para>
<para>Same as --format=ps, --format=ps:file:filename</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--text=<replaceable>filename</replaceable></option></term>
<listitem>
<para>Write a human-readable text report to <replaceable>filename</replaceable>.
If filename is not specified, then the report is written to stdout.</para>
<para>Same as --format=human, --format=human:file:filename</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--xml=<replaceable>filename</replaceable></option></term>
<listitem>
<para>Write an XML-formatted report to <replaceable>filename</replaceable>.
If filename is not specified, then the report is written to stdout.</para>
<para>Same as --format=xml, --format=xml:file:filename</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--print=<replaceable>printer</replaceable></option></term>
<listitem>
<para>Pipe a postscript label to <command>lp</command> or <command>lpr</command>,
specifying the given <replaceable>printer</replaceable>. If the printer is
not specified, uses the default from the Amanda configuration, or the system
default printer.</para>
<para>Same as --format=ps:print, --format=ps:print:printer</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--mail-text=<replaceable>recipient</replaceable></option></term>
<listitem>
<para>Send a human-readable text report to the given <replaceable>recipient</replaceable> via
the mailer specified in the Amanda configuration. If the recipient is
not specified, this uses the <emphasis>mailto</emphasis> from the Amanda configuration.</para>
<para>Same as --format=human:mail, --format=human:mail:recipient</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2><title>Script Mode Options</title>
<variablelist remap='TP'>
<varlistentry>
<term><option>-i</option></term>
<listitem>
<para>Don't email the report.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-M</option> <replaceable>address</replaceable></term>
<listitem>
<para>Mail the report to <emphasis remap='I'>address</emphasis>
instead of the <emphasis remap='B'>mailto</emphasis> value from
<emphasis remap='I'>amanda.conf</emphasis>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-l</option> <replaceable>logfile</replaceable></term>
<listitem>
<para>Name of the log file to parse to generate the report.
If a log file is not specified, it defaults to the file
<filename>$logdir/log</filename>, where
<filename>$logdir</filename> is the log directory defined in amanda.conf.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-f</option> <replaceable>outputfile</replaceable></term>
<listitem>
<para>Normally, <command>amreport</command> sends the report via e-mail to the
<emphasis remap='I'>mailto</emphasis> user as defined in the amanda.conf
file. If <emphasis remap='I'>outputfile</emphasis> is specified, then the
report is put in <emphasis remap='I'>outputfile</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-p</option> <replaceable>postscriptfile</replaceable></term>
<listitem>
<para>Send the postscript output to the file
<emphasis remap='I'>postscriptfile</emphasis> instead of to the
<manref name="lpr" vol="1"/> command. This option has an effect only if the
<emphasis remap='I'>lbl-templ</emphasis> directive is specified in amanda.conf.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--from-amdump</option></term>
<listitem>
<para>Force script mode. Has no other effect.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<refsect1><title>TEXT REPORT FORMAT</title>
<para>Amanda's text report format is divided into several sections. Some of these
sections only appear if they are not empty.</para>
<para>Although newer versions of Amanda try to use the term "volume" to refer
to a unit of storage, amreport still uses the term "tape", even if backups
are done to non-tape devices, to allow scripts which parse amreport's
output to continue to function.</para>
<refsect2><title>Summary</title>
<programlisting>
Hostname: bkserver
Org : DailySet1
Config : Daily
Date : February 25, 2009
These dumps were to tape Daily-103.
The next tape Amanda expects to use is: Daily-142
FAILURE DUMP SUMMARY:
jamon.slikon.local /var lev 0 FAILED [/bin/tar exited with status 2]
</programlisting>
<para>The summary section describes the run in broad terms, giving the server
hostname, organization (from the <amkeyword>org</amkeyword> configuration
parameter), configuration name, and dump date. This is followed by a
description of the volumes and holding disk used, and an rough estimate of the
volume(s) Amanda will use on the next run.</para>
<para>Brief notices of any unusual circumstances will also be included
here.</para>
</refsect2>
<refsect2><title>Statistics</title>
<programlisting>
STATISTICS:
Total Full Incr.
-------- -------- --------
Estimate Time (hrs:min) 0:00
Run Time (hrs:min) 0:01
Dump Time (hrs:min) 0:00 0:00 0:00
Output Size (meg) 1.6 0.0 1.6
Original Size (meg) 1.6 0.0 1.6
Avg Compressed Size (%) 100.0 100.0 100.0 (level:#disks ...)
Filesystems Dumped 4 1 3 (1:3)
Avg Dump Rate (k/s) 1555.1 134.2 1787.3
Tape Time (hrs:min) 0:00 0:00 0:00
Tape Size (meg) 1.6 0.0 1.6
Tape Used (%) 5.5 0.1 5.4 (level:#disks ...)
Filesystems Taped 4 1 3 (1:3)
(level:#parts ...)
Parts Taped 4 1 3 (1:3)
Avg Tp Write Rate (k/s) 143966 27624.3 151811
USAGE BY TAPE:
Label Time Size % DLEs Parts
metals-013 0:00 1650k 5.4 4 4
</programlisting>
<para>This section contains aggregate statistics for the entire run. The three
columns break down the results into a total for all data handled, only full
dumps, and only incremental dumps. In the right margin, amreport indicates
the breakdown of dump levels at the dumper and the taper.</para>
<para>The rows have the following meanings:</para>
<variablelist>
<!-- ============= -->
<varlistentry><term>Estimate Time</term><listitem>
<para>
The time used by the planner to estimate dump sizes.
</para></listitem></varlistentry>
<!-- ============= -->
<varlistentry><term>Run Time</term><listitem>
<para>
Total runtime, from the invocation of amdump to its completion.
</para></listitem></varlistentry>
<!-- ============= -->
<varlistentry><term>Dump Time</term><listitem>
<para>
Total time spent dumping clients.
</para></listitem></varlistentry>
<!-- ============= -->
<varlistentry><term>Output Size</term><listitem>
<para>
Total quantity of data dumped, after compression.
</para></listitem></varlistentry>
<!-- ============= -->
<varlistentry><term>Original Size</term><listitem>
<para>
Total quantity of data dumped, before compression.
</para></listitem></varlistentry>
<!-- ============= -->
<varlistentry><term>Avg Compressed Size</term><listitem>
<para>
Compression ratio, calculated from the previous two rows.
</para></listitem></varlistentry>
<!-- ============= -->
<varlistentry><term>Filesystems Dumped</term><listitem>
<para>
Number of DLEs dumped.
</para></listitem></varlistentry>
<!-- ============= -->
<varlistentry><term>Avg Dump Rate</term><listitem>
<para>
Average speed at which clients produced data. Note that, for dumps done
directly to a slow device, rather than to holding disk, this rate may
reflect a write speed constrained by the device speed.
</para></listitem></varlistentry>
<!-- ============= -->
<varlistentry><term>Tape Time</term><listitem>
<para>
Total time spent writing to storage volumes. This includes time spent changing
tapes, including time spent waiting for flush thresholds to be met.
</para></listitem></varlistentry>
<!-- ============= -->
<varlistentry><term>Tape Size</term><listitem>
<para>
Total quantity of data written to storage volumes.
</para></listitem></varlistentry>
<!-- ============= -->
<varlistentry><term>Tape Used</term><listitem>
<para>
Fraction of the total allocated storage (tapetype length times runtapes) actually used.
</para></listitem></varlistentry>
<!-- ============= -->
<varlistentry><term>Filesystems Taped</term><listitem>
<para>
Number of filesystems written to storage. This may be larger or smaller than the
number of filesystems dumped, due to flushes or dumps left on holding disk.
</para></listitem></varlistentry>
<!-- ============= -->
<varlistentry><term>Parts Taped</term><listitem>
<para>
Number of split parts writtten to storage. If this number is very large, then the split
size may be too small.
</para></listitem></varlistentry>
<!-- ============= -->
<varlistentry><term>Avg Tp Write Rate</term><listitem>
<para>
Taper speed, based on the tape time and tape size, above. Note that, because the tape time
includes time spent on tasks other than writing to tape, this does not necessary reflect the
device's real write speed. However, the value is useful for capacity planning, as it reflects
a realistic estimate of how quickly Amanda can write data to storage.
</para></listitem></varlistentry>
</variablelist>
</refsect2>
<refsect2><title>Usage by Tape</title>
<programlisting>
USAGE BY TAPE:
Label Time Size % DLEs Parts
Conf-001 0:00 20320k 66.2 1 4
Conf-002 0:00 6470k 21.1 0 2
</programlisting>
<para>This short section gives per-volume statistics: time spent writing to the
volume; bytes written to the volume; portion of the expected tape length
used; number of DLEs started, and total number of split parts
written.</para>
</refsect2>
<refsect2><title>Notes</title>
<programlisting>
NOTES:
taper: tape DAILY-37 kb 30720 fm 3 [OK]
</programlisting>
<para>This section contains any informational log messages from the run. Most
messages are self-explanatory. The taper message shown in the example is
always present, and is redundant to the previous section. It indicates that
30720 kb were written to "DAILY-37" in 3 files. </para>
</refsect2>
<refsect2><title>Failure and Strange Details</title>
<programlisting>
FAILED DUMP DETAILS:
/-- jamon.slikon.local /var lev 0 FAILED [/bin/tar exited with status 2]
sendbackup: info BACKUP=APPLICATION
sendbackup: info APPLICATION=amgtar
sendbackup: info RECOVER_CMD=/usr/bin/gzip -dc |amgtar -f... -
sendbackup: info COMPRESS_SUFFIX=.gz
sendbackup: info end
? /bin/tar: ./gdm: Cannot savedir: Permission denied
| Total bytes written: 943831040 (901MiB, 4.9MiB/s)
| /bin/tar: Error exit delayed from previous errors
sendbackup: error [/bin/tar exited with status 2]
sendbackup: size 921710
sendbackup: end
\\--------
STRANGE DUMP DETAILS:
/-- bsdfw.slikon.local / lev 0 STRANGE
sendbackup: info BACKUP=APPLICATION
sendbackup: info APPLICATION=amgtar
sendbackup: info RECOVER_CMD=/usr/bin/gzip -dc |amgtar -f... -
sendbackup: info COMPRESS_SUFFIX=.gz
sendbackup: info end
| /bin/tar: ./tmp/.X11-unix/X0: socket ignored
| Total bytes written: 5530869760 (5.2GiB, 3.0MiB/s)
sendbackup: size 5401240
sendbackup: end
\\--------
</programlisting>
<para>This section expands on failures and strange results indicated in earlier
sections. In both cases, the details contain a messages produced by the
underlying backup tool - GNU tar, in this example. Failed dumps have
actually failed, and the reasons are usually clear. Strange dumps,
however, are regarded as successful by Amanda, but contain messages that
Amanda did not recognize and which may be of interest to the
operator.</para>
</refsect2>
<refsect2><title>Dump Summary</title>
<programlisting>
DUMP SUMMARY:
DUMPER STATS TAPER STATS
HOSTNAME DISK L ORIG-kB OUT-kB COMP% MMM:SS KB/s MMM:SS KB/s
-------------------------- ------------------------------------- ---------------
strontium /etc 1 270 270 -- 0:00 1146.3 0:00 140918.6
strontium -me/elantra 1 10 10 -- 0:00 65.6 0:00 9033.4
strontium /local 0 20 20 -- 0:00 133.9 0:00 27624.3
strontium -ository_13 1 1350 1350 -- 0:01 2568.5 0:00 175006.5
</programlisting>
<para>The dump summary table has one row for each DLE processed during the run.
The "L" column gives the level of the dump. The remaining colums are
divided into dumper stats and taper stats. </para>
<para>The dumper stats give the original (before compression) and output (after
compression) size of each dump, as well as a compression ratio, if
applicable. The column labeled "MMM:SS" gives the time spent on that dump,
and the next column is the calculated dump rate.</para>
<para>The taper stats give the time and speed with which the dump was written
to storage. This value is the sum of the times for each part, and as such
does not include time spent switching volumes.</para>
</refsect2>
</refsect1>
<refsect1><title>LABEL PRINTING</title>
<para>Amanda can print postscript labels describing the contents
of tape(s) written in a run.
The labels are designed to be folded and
inserted into the tape case along with the tape or hole punched and put
in a 3-ring binder.
Various label templates are provided to
format data for different tape sizes.</para>
<para>The information printed varies slightly between label templates
due to size constraints.
Labels contain one line for each host/file-system
pair and may also contain the file number on the tape,
the level of the dump,
the original size of the dump
and the size of the (possibly compressed) tape file.</para>
<para>Add the
<emphasis remap='I'>lbl-templ</emphasis>
parameter to the tapetype definition in amanda.conf to enable labels.
If you don't add this line to your
tapetype definition,
<command>amreport</command>
will not print tape labels.</para>
<para>You may use the
<emphasis remap='I'>printer</emphasis>
keyword in amanda.conf to print to other than the system default printer.</para>
</refsect1>
<refsect1><title>TEMPLATES</title>
<para>Amanda provides label templates for the following tape types.
These are pretty generic labels and should be easy to customize for
other tape types or particular site needs.</para>
<!-- .RS -->
<!-- .RS -->
<literallayout remap='.nf'>
* ExaByte 8mm tapes
* DAT 4mm tapes
* DLT tapes
* 3-ring binder
</literallayout> <!-- .fi -->
<para>The 3-ring binder type is the most generic.
It may be used to make a hardcopy log of the tapes.</para>
</refsect1>
<refsect1><title>EXIT CODE</title>
The exit code of <command>amreport</command> is the ORed value of:
<programlisting>
0 = success
1 = error
2 = a dle give strange message
4 = a dle failed
8 = Don't know the status of a dle (RESULT_MISSING in the report)
16 = tape error or no more tape
</programlisting>
</refsect1>
<seealso>
<manref name="amflush" vol="8"/>
</seealso>
</refentry>