git.gag.com Git - debian/amanda/blob - man/xml-source/amreport.8.xml

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
   4 [
   5   <!-- entities files to use -->
   6   <!ENTITY % global_entities SYSTEM 'global.entities'>
   7   %global_entities;
   8 ]>
   9
  10 <!-- lifted from troff+man by doclifter -->
  11 <refentry id='amreport.8'>
  12
  13 <refmeta>
  14 <refentrytitle>amreport</refentrytitle>
  15 <manvolnum>8</manvolnum>
  16 &rmi.source;
  17 &rmi.version;
  18 &rmi.manual.8;
  19 </refmeta>
  20 <refnamediv>
  21 <refname>amreport</refname>
  22 <refpurpose>generate a formatted output of statistics for an Amanda run</refpurpose>
  23 </refnamediv>
  24 <refentryinfo>
  25 &author.sgw.xml;
  26 </refentryinfo>
  27 <!-- body begins here -->
  28 <refsynopsisdiv>
  29 <cmdsynopsis>
  30   <command>amreport</command>
  31     <arg choice='opt'><replaceable>config</replaceable></arg>
  32     &configoverride.synopsis;
  33     <group>
  34         <synopfragmentref linkend="cmdline">command-line options</synopfragmentref> | <synopfragmentref linkend="script">script options</synopfragmentref>
  35     </group>
  36   <synopfragment id="cmdline">
  37     <arg choice='opt'>--log=<replaceable>logfile</replaceable></arg>
  38     <arg choice='opt'>--ps=<replaceable>filename</replaceable></arg>
  39     <arg choice='opt'>--text=<replaceable>filename</replaceable></arg>
  40     <arg choice='opt'>--xml=<replaceable>filename</replaceable></arg>
  41     <arg choice='opt'>--print=<replaceable>printer</replaceable></arg>
  42     <arg choice='opt'>--mail-text=<replaceable>recipient</replaceable></arg>
  43   </synopfragment>
  44   <synopfragment id="script">
  45     <arg choice='opt'>-i</arg>
  46     <arg choice='opt'>-M <replaceable>address</replaceable></arg>
  47     <arg choice='opt'>-l <replaceable>logfile</replaceable></arg>
  48     <arg choice='opt'>-f <replaceable>outputfile</replaceable></arg>
  49     <arg choice='opt'>-p <replaceable>postscriptfile</replaceable></arg>
  50     <arg choice='opt'>--from-amdump</arg>
  51   </synopfragment>
  52 </cmdsynopsis>
  53 </refsynopsisdiv>
  54
  55
  56 <refsect1><title>DESCRIPTION</title>
  57
  58 <para><emphasis remap='B'>Amreport</emphasis> generates a summary report of an
  59 Amanda backup run.  </para>
  60
  61 <para>See the <manref name="amanda" vol="8"/> man page for more details about
  62 Amanda.</para>
  63
  64 </refsect1>
  65
  66 <refsect1><title>OPTIONS</title>
  67
  68 <variablelist remap='TP'>
  69   <varlistentry>
  70   <term><emphasis remap='I'>config</emphasis></term>
  71   <listitem>
  72 <para>Name of the configuration to process.  If no configuration name is
  73 specified, amanda.conf is read from the current directory.</para>
  74   </listitem>
  75   </varlistentry>
  76   &configoverride.varlistentry;
  77 </variablelist>
  78
  79 <para>Amreport operates in two distinct modes.  Command-line mode is intended for use
  80 by an administrator from the command line, and uses long command-line options
  81 for clarity.  Script mode is intended for use from scripts such as amdump, and
  82 has a lot of non-obvious default behaviors to suit that need.</para>
  83
  84 <para>Unless a script-mode option is given, amreport defaults to command-line mode.
  85 If no options are given, amreport writes a report for the most recent logfile to
  86 stdout.</para>
  87
  88 <refsect2><title>Command-Line Mode Options</title>
  89 <variablelist remap='TP'>
  90   <varlistentry>
  91   <term><option>--log=<replaceable>logfile</replaceable></option></term>
  92   <listitem>
  93 <para>Use this logfile as the basis for the report.  If this option is given, then
  94 the report is a "historical" report and will not include current state from
  95 e.g., holding disk and curinfo.  If this option is not specified, then the
  96 most recent logfile will be used.</para>
  97   </listitem>
  98   </varlistentry>
  99   <varlistentry>
 100   <term><option>--ps=<replaceable>filename</replaceable></option></term>
 101   <listitem>
 102 <para>Write a postscript label to <replaceable>filename</replaceable>.
 103 See "LABEL PRINTING" below.  If filename is not specified, then the
 104 label is written to stdout.</para>
 105   </listitem>
 106   </varlistentry>
 107   <varlistentry>
 108   <term><option>--text=<replaceable>filename</replaceable></option></term>
 109   <listitem>
 110 <para>Write a human-readable text report to <replaceable>filename</replaceable>.
 111 If filename is not specified, then the report is written to stdout.</para>
 112   </listitem>
 113   </varlistentry>
 114   <varlistentry>
 115   <term><option>--xml=<replaceable>filename</replaceable></option></term>
 116   <listitem>
 117 <para>Write an XML-formatted report to <replaceable>filename</replaceable>.
 118 If filename is not specified, then the report is written to stdout.</para>
 119   </listitem>
 120   </varlistentry>
 121   <varlistentry>
 122   <term><option>--print=<replaceable>printer</replaceable></option></term>
 123   <listitem>
 124 <para>Pipe a postscript label to <command>lp</command> or <command>lpr</command>,
 125 specifying the given <replaceable>printer</replaceable>.  If the printer is
 126 not specified, uses the default from the Amanda configuration, or the system
 127 default printer.</para>
 128   </listitem>
 129   </varlistentry>
 130   <varlistentry>
 131   <term><option>--mail-text=<replaceable>recipient</replaceable></option></term>
 132   <listitem>
 133 <para>Send a human-readable text report to the given <replaceable>recipient</replaceable> via
 134 the mailer specified in the Amanda configuration.  If the recipient is
 135 not specified, this uses the <emphasis>mailto</emphasis> from the Amanda configuration.</para>
 136   </listitem>
 137   </varlistentry>
 138 </variablelist>
 139 </refsect2>
 140
 141 <refsect2><title>Script Mode Options</title>
 142 <variablelist remap='TP'>
 143   <varlistentry>
 144   <term><option>-i</option></term>
 145   <listitem>
 146 <para>Don't email the report.</para>
 147   </listitem>
 148   </varlistentry>
 149   <varlistentry>
 150   <term><option>-M</option> <replaceable>address</replaceable></term>
 151   <listitem>
 152 <para>Mail the report to <emphasis remap='I'>address</emphasis>
 153 instead of the <emphasis remap='B'>mailto</emphasis> value from
 154 <emphasis remap='I'>amanda.conf</emphasis>.
 155 </para>
 156   </listitem>
 157   </varlistentry>
 158   <varlistentry>
 159   <term><option>-l</option> <replaceable>logfile</replaceable></term>
 160   <listitem>
 161 <para>Name of the log file to parse to generate the report.
 162 If a log file is not specified, it defaults to the file
 163 <filename>$logdir/log</filename>, where
 164 <filename>$logdir</filename> is the log directory defined in amanda.conf.</para>
 165   </listitem>
 166   </varlistentry>
 167   <varlistentry>
 168   <term><option>-f</option> <replaceable>outputfile</replaceable></term>
 169   <listitem>
 170 <para>Normally, <command>amreport</command> sends the report via e-mail to the
 171 <emphasis remap='I'>mailto</emphasis> user as defined in the amanda.conf
 172 file.  If <emphasis remap='I'>outputfile</emphasis> is specified, then the
 173 report is put in <emphasis remap='I'>outputfile</emphasis>.</para>
 174   </listitem>
 175   </varlistentry>
 176   <varlistentry>
 177   <term><option>-p</option> <replaceable>postscriptfile</replaceable></term>
 178   <listitem>
 179 <para>Send the postscript output to the file
 180 <emphasis remap='I'>postscriptfile</emphasis> instead of to the
 181 <manref name="lpr" vol="1"/> command.  This option has an effect only if the
 182 <emphasis remap='I'>lbl-templ</emphasis> directive is specified in amanda.conf.</para>
 183   </listitem>
 184   </varlistentry>
 185   <varlistentry>
 186   <term><option>--from-amdump</option></term>
 187   <listitem>
 188   <para>Force script mode.  Has no other effect.</para>
 189   </listitem>
 190   </varlistentry>
 191
 192 </variablelist>
 193 </refsect2>
 194 </refsect1>
 195
 196 <refsect1><title>TEXT REPORT FORMAT</title>
 197
 198 <para>Amanda's text report format is divided into several sections.  Some of these
 199 sections only appear if they are not empty.</para>
 200
 201 <para>Although newer versions of Amanda try to use the term "volume" to refer
 202 to a unit of storage, amreport still uses the term "tape", even if backups
 203 are done to non-tape devices, to allow scripts which parse amreport's
 204 output to continue to function.</para>
 205
 206 <refsect2><title>Summary</title>
 207 <programlisting>
 208 Hostname: bkserver
 209 Org     : DailySet1
 210 Config  : Daily
 211 Date    : February 25, 2009
 212
 213 These dumps were to tape Daily-103.
 214 The next tape Amanda expects to use is: Daily-142
 215
 216 FAILURE DUMP SUMMARY:
 217    jamon.slikon.local /var lev 0  FAILED [/bin/tar exited with status 2]
 218 </programlisting>
 219
 220 <para>The summary section describes the run in broad terms, giving the server
 221 hostname, organization (from the <amkeyword>org</amkeyword> configuration
 222 parameter), configuration name, and dump date.  This is followed by a
 223 description of the volumes and holding disk used, and an rough estimate of the
 224 volume(s) Amanda will use on the next run.</para>
 225
 226 <para>Brief notices of any unusual circumstances will also be included
 227 here.</para>
 228
 229 </refsect2>
 230
 231 <refsect2><title>Statistics</title>
 232 <programlisting>
 233 STATISTICS:
 234                           Total       Full      Incr.
 235                         --------   --------   --------
 236 Estimate Time (hrs:min)    0:00
 237 Run Time (hrs:min)         0:01
 238 Dump Time (hrs:min)        0:00       0:00       0:00
 239 Output Size (meg)           1.6        0.0        1.6
 240 Original Size (meg)         1.6        0.0        1.6
 241 Avg Compressed Size (%)   100.0      100.0      100.0   (level:#disks ...)
 242 Filesystems Dumped            4          1          3   (1:3)
 243 Avg Dump Rate (k/s)      1555.1      134.2     1787.3
 244
 245 Tape Time (hrs:min)        0:00       0:00       0:00
 246 Tape Size (meg)             1.6        0.0        1.6
 247 Tape Used (%)               5.5        0.1        5.4   (level:#disks ...)
 248 Filesystems Taped             4          1          3   (1:3)
 249                                                         (level:#parts ...)
 250 Parts Taped                   4          1          3   (1:3)
 251 Avg Tp Write Rate (k/s)  143966    27624.3     151811
 252
 253 USAGE BY TAPE:
 254   Label            Time      Size      %  DLEs Parts
 255   metals-013       0:00     1650k    5.4     4     4
 256 </programlisting>
 257
 258 <para>This section contains aggregate statistics for the entire run.  The three
 259 columns break down the results into a total for all data handled, only full
 260 dumps, and only incremental dumps.  In the right margin, amreport indicates
 261 the breakdown of dump levels at the dumper and the taper.</para>
 262
 263 <para>The rows have the following meanings:</para>
 264 <variablelist>
 265 <!-- ============= -->
 266 <varlistentry><term>Estimate Time</term><listitem>
 267 <para>
 268 The time used by the planner to estimate dump sizes.
 269 </para></listitem></varlistentry>
 270 <!-- ============= -->
 271 <varlistentry><term>Run Time</term><listitem>
 272 <para>
 273 Total runtime, from the invocation of amdump to its completion.
 274 </para></listitem></varlistentry>
 275 <!-- ============= -->
 276 <varlistentry><term>Dump Time</term><listitem>
 277 <para>
 278 Total time spent dumping clients.
 279 </para></listitem></varlistentry>
 280 <!-- ============= -->
 281 <varlistentry><term>Output Size</term><listitem>
 282 <para>
 283 Total quantity of data dumped, after compression.
 284 </para></listitem></varlistentry>
 285 <!-- ============= -->
 286 <varlistentry><term>Original Size</term><listitem>
 287 <para>
 288 Total quantity of data dumped, before compression.
 289 </para></listitem></varlistentry>
 290 <!-- ============= -->
 291 <varlistentry><term>Avg Compressed Size</term><listitem>
 292 <para>
 293 Compression ratio, calculated from the previous two rows.
 294 </para></listitem></varlistentry>
 295 <!-- ============= -->
 296 <varlistentry><term>Filesystems Dumped</term><listitem>
 297 <para>
 298 Number of DLEs dumped.
 299 </para></listitem></varlistentry>
 300 <!-- ============= -->
 301 <varlistentry><term>Avg Dump Rate</term><listitem>
 302 <para>
 303 Average speed at which clients produced data.  Note that, for dumps done
 304 directly to a slow device, rather than to holding disk, this rate may
 305 reflect a write speed constrained by the device speed.
 306 </para></listitem></varlistentry>
 307 <!-- ============= -->
 308 <varlistentry><term>Tape Time</term><listitem>
 309 <para>
 310 Total time spent writing to storage volumes.  This includes time spent changing
 311 tapes, including time spent waiting for flush thresholds to be met.
 312 </para></listitem></varlistentry>
 313 <!-- ============= -->
 314 <varlistentry><term>Tape Size</term><listitem>
 315 <para>
 316 Total quantity of data written to storage volumes.
 317 </para></listitem></varlistentry>
 318 <!-- ============= -->
 319 <varlistentry><term>Tape Used</term><listitem>
 320 <para>
 321 Fraction of the total allocated storage (tapetype length times runtapes) actually used.
 322 </para></listitem></varlistentry>
 323 <!-- ============= -->
 324 <varlistentry><term>Filesystems Taped</term><listitem>
 325 <para>
 326 Number of filesystems written to storage.  This may be larger or smaller than the
 327 number of filesystems dumped, due to flushes or dumps left on holding disk.
 328 </para></listitem></varlistentry>
 329 <!-- ============= -->
 330 <varlistentry><term>Parts Taped</term><listitem>
 331 <para>
 332 Number of split parts writtten to storage.  If this number is very large, then the split
 333 size may be too small.
 334 </para></listitem></varlistentry>
 335 <!-- ============= -->
 336 <varlistentry><term>Avg Tp Write Rate</term><listitem>
 337 <para>
 338 Taper speed, based on the tape time and tape size, above.  Note that, because the tape time
 339 includes time spent on tasks other than writing to tape, this does not necessary reflect the
 340 device's real write speed.  However, the value is useful for capacity planning, as it reflects
 341 a realistic estimate of how quickly Amanda can write data to storage.
 342 </para></listitem></varlistentry>
 343 </variablelist>
 344
 345 </refsect2>
 346
 347 <refsect2><title>Usage by Tape</title>
 348 <programlisting>
 349 USAGE BY TAPE:
 350   Label          Time      Size      %  DLEs Parts
 351   Conf-001       0:00    20320k   66.2     1     4
 352   Conf-002       0:00     6470k   21.1     0     2
 353 </programlisting>
 354
 355 <para>This short section gives per-volume statistics: time spent writing to the
 356 volume; bytes written to the volume; portion of the expected tape length
 357 used; number of DLEs started, and total number of split parts
 358 written.</para>
 359
 360 </refsect2>
 361
 362 <refsect2><title>Notes</title>
 363 <programlisting>
 364 NOTES:
 365   taper: tape DAILY-37 kb 30720 fm 3 [OK]
 366 </programlisting>
 367
 368 <para>This section contains any informational log messages from the run.  Most
 369 messages are self-explanatory. The taper message shown in the example is
 370 always present, and is redundant to the previous section. It indicates that
 371 30720 kb were written to "DAILY-37" in 3 files.  </para>
 372 </refsect2>
 373
 374 <refsect2><title>Failure and Strange Details</title>
 375 <programlisting>
 376 FAILED DUMP DETAILS:
 377
 378 /--  jamon.slikon.local /var lev 0 FAILED [/bin/tar exited with status 2]
 379 sendbackup: info BACKUP=APPLICATION
 380 sendbackup: info APPLICATION=amgtar
 381 sendbackup: info RECOVER_CMD=/usr/bin/gzip -dc |amgtar -f... -
 382 sendbackup: info COMPRESS_SUFFIX=.gz
 383 sendbackup: info end
 384 ? /bin/tar: ./gdm: Cannot savedir: Permission denied
 385 | Total bytes written: 943831040 (901MiB, 4.9MiB/s)
 386 | /bin/tar: Error exit delayed from previous errors
 387 sendbackup: error [/bin/tar exited with status 2]
 388 sendbackup: size 921710
 389 sendbackup: end
 390 \\--------
 391
 392 STRANGE DUMP DETAILS:
 393
 394 /--  bsdfw.slikon.local / lev 0 STRANGE
 395 sendbackup: info BACKUP=APPLICATION
 396 sendbackup: info APPLICATION=amgtar
 397 sendbackup: info RECOVER_CMD=/usr/bin/gzip -dc |amgtar -f... -
 398 sendbackup: info COMPRESS_SUFFIX=.gz
 399 sendbackup: info end
 400 | /bin/tar: ./tmp/.X11-unix/X0: socket ignored
 401 | Total bytes written: 5530869760 (5.2GiB, 3.0MiB/s)
 402 sendbackup: size 5401240
 403 sendbackup: end
 404 \\--------
 405 </programlisting>
 406
 407 <para>This section expands on failures and strange results indicated in earlier
 408 sections.  In both cases, the details contain a messages produced by the
 409 underlying backup tool - GNU tar, in this example.  Failed dumps have
 410 actually failed, and the reasons are usually clear.  Strange dumps,
 411 however, are regarded as successful by Amanda, but contain messages that
 412 Amanda did not recognize and which may be of interest to the
 413 operator.</para>
 414 </refsect2>
 415
 416 <refsect2><title>Dump Summary</title>
 417 <programlisting>
 418 DUMP SUMMARY:
 419                                        DUMPER STATS                TAPER STATS
 420 HOSTNAME     DISK        L ORIG-kB  OUT-kB  COMP%  MMM:SS   KB/s MMM:SS     KB/s
 421 -------------------------- ------------------------------------- ---------------
 422 strontium    /etc        1     270     270    --     0:00 1146.3   0:00 140918.6
 423 strontium    -me/elantra 1      10      10    --     0:00   65.6   0:00   9033.4
 424 strontium    /local      0      20      20    --     0:00  133.9   0:00  27624.3
 425 strontium    -ository_13 1    1350    1350    --     0:01 2568.5   0:00 175006.5
 426 </programlisting>
 427
 428 <para>The dump summary table has one row for each DLE processed during the run.
 429 The "L" column gives the level of the dump.  The remaining colums are
 430 divided into dumper stats and taper stats.  </para>
 431
 432 <para>The dumper stats give the original (before compression) and output (after
 433 compression) size of each dump, as well as a compression ratio, if
 434 applicable.  The column labeled "MMM:SS" gives the time spent on that dump,
 435 and the next column is the calculated dump rate.</para>
 436
 437 <para>The taper stats give the time and speed with which the dump was written
 438 to storage.  This value is the sum of the times for each part, and as such
 439 does not include time spent switching volumes.</para>
 440 </refsect2>
 441
 442 </refsect1>
 443
 444 <refsect1><title>LABEL PRINTING</title>
 445 <para>Amanda can print postscript labels describing the contents
 446 of tape(s) written in a run.
 447 The labels are designed to be folded and
 448 inserted into the tape case along with the tape or hole punched and put
 449 in a 3-ring binder.
 450 Various label templates are provided to
 451 format data for different tape sizes.</para>
 452
 453 <para>The information printed varies slightly between label templates
 454 due to size constraints.
 455 Labels contain one line for each host/file-system
 456 pair and may also contain the file number on the tape,
 457 the level of the dump,
 458 the original size of the dump
 459 and the size of the (possibly compressed) tape file.</para>
 460
 461 <para>Add the
 462 <emphasis remap='I'>lbl-templ</emphasis>
 463 parameter to the tapetype definition in amanda.conf to enable labels.
 464 If you don't add this line to your
 465 tapetype definition,
 466 <command>amreport</command>
 467 will not print tape labels.</para>
 468
 469 <para>You may use the
 470 <emphasis remap='I'>printer</emphasis>
 471 keyword in amanda.conf to print to other than the system default printer.</para>
 472
 473 </refsect1>
 474
 475 <refsect1><title>TEMPLATES</title>
 476
 477 <para>Amanda provides label templates for the following tape types.
 478 These are pretty generic labels and should be easy to customize for
 479 other tape types or particular site needs.</para>
 480
 481 <!-- .RS -->
 482 <!-- .RS -->
 483 <literallayout remap='.nf'>
 484 * ExaByte 8mm tapes
 485 * DAT 4mm tapes
 486 * DLT tapes
 487 * 3-ring binder
 488 </literallayout> <!-- .fi -->
 489
 490 <para>The 3-ring binder type is the most generic.
 491 It may be used to make a hardcopy log of the tapes.</para>
 492 </refsect1>
 493
 494 <refsect1><title>EXIT CODE</title>
 495 The exit code of <command>amreport</command> is the ORed value of:
 496 <programlisting>
 497  0  = success
 498  1  = error
 499  2  = a dle give strange message
 500  4  = a dle failed
 501  8  = Don't know the status of a dle (RESULT_MISSING in the report)
 502  16 = tape error or no more tape
 503 </programlisting>
 504 </refsect1>
 505
 506 <seealso>
 507 <manref name="amflush" vol="8"/>
 508 </seealso>
 509
 510 </refentry>
 511