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"
5 <!-- entities files to use -->
6 <!ENTITY % global_entities SYSTEM 'global.entities'>
10 <!-- lifted from troff+man by doclifter -->
11 <refentry id='amanda.8'>
14 <refentrytitle>amanda</refentrytitle>
15 <manvolnum>8</manvolnum>
21 <refname>amanda</refname>
22 <refpurpose>The Open Source Backup Platform</refpurpose>
28 <!-- body begins here -->
30 <refsect1><title>DESCRIPTION</title>
31 <para>This manual page gives an overview of the Amanda commands and
32 configuration files for quick reference.</para>
35 - NOTE: the comma after each citerefentry works around a bug in the docbook-to-man conversion; using
36 - causes problems in the docbook-to-html conversion.
39 <refsect2><title>COMMANDS</title> <!-- a.k.a. any section 8 manpage -->
40 <para>Here are all the Amanda commands. Each one has its own manual page. See them for all the gory details.</para>
43 <manref name="amaddclient" vol="8"/>,
46 <manref name="amadmin" vol="8"/>,
49 <manref name="amaespipe" vol="8"/>,
52 <manref name="amarchiver" vol="8"/>,
55 <manref name="amcheck" vol="8"/>,
58 <manref name="amcheckdb" vol="8"/>,
61 <manref name="amcheckdump" vol="8"/>,
64 <manref name="amcleanup" vol="8"/>,
67 <manref name="amcrypt-ossl-asym" vol="8"/>,
70 <manref name="amcrypt-ossl" vol="8"/>,
73 <manref name="amcrypt" vol="8"/>,
76 <manref name="amcryptsimple" vol="8"/>,
79 <manref name="amdevcheck" vol="8"/>,
82 <manref name="amdump" vol="8"/>,
85 <manref name="amfetchdump" vol="8"/>,
88 <manref name="amflush" vol="8"/>,
91 <manref name="amgetconf" vol="8"/>,
94 <manref name="amgpgcrypt" vol="8"/>,
97 <manref name="amgtar" vol="8"/>,
100 <manref name="amlabel" vol="8"/>,
103 <manref name="amoverview" vol="8"/>,
106 <manref name="ampgsql" vol="8"/>,
109 <manref name="amplot" vol="8"/>,
112 <manref name="amraw" vol="8"/>,
115 <manref name="amrecover" vol="8"/>,
118 <manref name="amreport" vol="8"/>,
121 <manref name="amrestore" vol="8"/>,
124 <manref name="amrmtape" vol="8"/>,
127 <manref name="amsamba" vol="8"/>,
130 <manref name="amserverconfig" vol="8"/>,
133 <manref name="amservice" vol="8"/>,
136 <manref name="amstar" vol="8"/>,
139 <manref name="amstatus" vol="8"/>,
142 <manref name="amsuntar" vol="8"/>,
145 <manref name="amtape" vol="8"/>,
148 <manref name="amtapetype" vol="8"/>,
151 <manref name="amtoc" vol="8"/>,
154 <manref name="amvault" vol="8"/>,
157 <manref name="amzfs-sendrecv" vol="8"/>,
160 <manref name="amzfs-snapshot" vol="8"/>,
163 <manref name="script-email" vol="8"/>,
167 <refsect2><title>CONFIGURATION FILES</title> <!-- a.k.a. most section 5 manpages -->
170 <manref name="amanda.conf" vol="5"/>,
173 <manref name="amanda-client.conf" vol="5"/>,
176 <manref name="disklist" vol="5"/>,
179 <manref name="tapelist" vol="5"/>,
183 <refsect2><title>DATA FORMATS</title> <!-- a.k.a. section 5 manpages about internal data formats -->
186 <manref name="amanda-archive-format" vol="5"/>,
190 <refsect2><title>CONCEPTS</title> <!-- a.k.a. any section 7 manpage -->
193 <manref name="amanda-applications" vol="7"/>,
196 <manref name="amanda-auth" vol="7"/>,
199 <manref name="amanda-changers" vol="7"/>,
202 <manref name="amanda-compatibility" vol="7"/>,
205 <manref name="amanda-devices" vol="7"/>,
208 <manref name="amanda-scripts" vol="7"/>,
211 <manref name="amanda-taperscan" vol="7"/>,
217 <refsect1><title>CONFIGURATION</title>
218 <para>There are four user-editable files that control the behavior of Amanda.
221 The first two are &amconf; and &amclientconf;,
222 the main configuration files for the server and client, respectively.
223 They contain parameters to customize Amanda for the site.
226 Next is the &disklist; file, which lists hosts and disk partitions to back up.
229 Last is the seldom-edited &tapelist;
230 file, which lists tapes that are currently active.
231 These files are described in more detail in the following sections.</para>
233 <para>All configuration files are stored in individual configuration
234 directories, usually under <filename>/etc/amanda/</filename>.
235 A site will often have more than
237 For example, it might have a
238 <emphasis remap='I'>normal</emphasis>
239 configuration for everyday backups and an
240 <emphasis remap='I'>archive</emphasis>
241 configuration for infrequent full archival backups.
242 The configuration files would be stored under directories
243 <filename>/etc/amanda/normal/</filename> and
244 <filename>/etc/amanda/archive/</filename>, respectively.
245 Part of the job of an Amanda administrator is to create,
246 populate and maintain these directories.</para>
248 <para>Most Amanda applications take a "config" parameter; this is generally the
249 (unqualified) name of the configuration directory, e.g.,
250 <filename>normal</filename>. If the parameter is <filename>.</filename> (dot),
251 the current directory is used. This feature is present for backward
252 compatibility, but is not commonly used.</para>
256 <refsect1><title>LOG FILES</title>
257 <para>All log and database files generated by Amanda go in corresponding
258 directories somewhere.
259 The exact location is controlled by entries in
260 <manref name="amanda.conf" vol="5"/>.
261 A typical location would be under <filename>/var/adm/amanda</filename>.
262 For the above example, the files might go in
263 <filename>/var/adm/amanda/normal/</filename> and
264 <filename>/var/adm/amanda/archive/</filename>.
267 <para>As log files are no longer needed (no longer contain relevant information),
268 Amanda cycles them out in various ways, depending on the type of file.</para>
270 <para>Detailed information about
271 <command>amdump</command>
272 runs are stored in dump logs -- files named
273 <emphasis remap='B'>amdump.</emphasis><emphasis remap='I'>NN</emphasis>
275 <emphasis remap='I'>NN</emphasis>
276 is a sequence number, with 1 being the most recent file.
277 <emphasis remap='B'>Amdump</emphasis>
278 rotates these files each run, keeping roughly the last
279 <emphasis remap='B'>tapecycle</emphasis>
281 worth of them.</para>
283 <para>The file used by
284 <emphasis remap='B'>amreport</emphasis>
285 to generate the mail summary is the trace log. This file constitutes the "catalog"
286 describing the data on the tapes written in a run. It is named
287 <emphasis remap='B'>log.</emphasis><emphasis remap='I'>YYYYMMDDHHMMSS.NN</emphasis>
289 <emphasis remap='I'>YYYYMMDDHHMMSS</emphasis>
290 is the datestamp of the start of the
291 <command>amdump</command> or <command>amflush</command>
293 <emphasis remap='I'>NN</emphasis>
294 is a sequence number started at 0.
296 <command>amdump</command>
298 log files for runs whose tapes have been reused are renamed
299 into a subdirectory of the main log directory (see the
300 <emphasis remap='B'>logdir</emphasis>
303 <emphasis remap='B'>oldlog</emphasis>.
304 It is up to the Amanda administrator to remove them from this
305 directory when desired.</para>
307 <para>Index (backup image catalogue) files older than the full dump
308 matching the oldest backup image for a given client and disk
310 <command>amdump</command>
311 at the end of each run.</para>
315 <refsect1><title>Using Samba</title>
316 <para>For Samba access, Amanda needs a file on the Samba server (which may
317 or may not also be the tape server) named
318 <filename>/etc/amandapass</filename>
319 with share names, (clear text) passwords and (optional) domain names,
320 in that order, one per line, whitespace separated.
321 By default, the user used to connect to the PC is the same for all
322 PC's and is compiled into Amanda.
323 It may be changed on a host by host basis
324 by listing it first in the password field followed
325 by a percent sign and then the password.
328 //some-pc/home normalpw
329 //another-pc/disk otheruser%otherpw
331 <para>With clear text passwords, this file should obviously be tightly protected.
332 It only needs to be readable by the Amanda-user on the Samba server. </para>
335 <refsect1><title>HOST & DISK EXPRESSION</title>
336 <para>All host and disk arguments to programs are special expressions.
337 The command applies to all DLEs that match the arguments.
338 This section describes the matcher.</para>
340 <para>The matcher matches by word, each word is a glob expression, words
341 are separated by the separator '.' for host and '/' for disk. You
342 can anchor the expression at left with a '^'. You can
343 anchor the expression at right with a '$'. The matcher
344 is case insensitive for host but is case sensitive for disk. A match
345 succeeds if all words in your expression match contiguous words in
346 the host or disk.</para>
348 <para>If the disk is a UNC ("\\windows\share") then all '\' are converted to '/' before the match. Using '\' is complicated because of the extra quoting required by the shell and amanda. It's easier to use '/' because it require less quoting ("//windows/share")</para>
350 <variablelist remap='TP'>
353 <term>dot (.)</term> <!-- troff gets confused by a plain dot -->
354 <listitem><para>word separator for a host</para></listitem>
359 <listitem><para>word separator for a disk</para></listitem>
364 <listitem><para>word separator for a UNC disk</para></listitem>
369 <listitem><para>anchor at left</para></listitem>
374 <listitem><para>anchor at right</para></listitem>
379 <listitem><para>match exactly one character except the separator</para></listitem>
384 <listitem><para>match zero or more characters except the separator</para></listitem>
389 <listitem><para>match zero or more characters including the separator</para></listitem>
394 <listitem><para>match a single character, namely any of the characters
395 enclosed by the brackets.</para></listitem>
400 <listitem><para>match a single character, namely any characters that is not
401 enclosed by the brackets.</para></listitem>
406 <para>The shell interpret some of these characters, they must be escaped by a backslash '\' and/or the expression must be enclosed in simple or double quote.</para>
408 <para>Some examples:</para>
410 <variablelist remap='TP'>
414 Will match <filename>hosta</filename>, <filename>foo.hosta.org</filename>, and
415 <filename>hoSTA.dOMAIna.ORG</filename> but not <filename>hostb</filename>.
422 Will match <filename>host</filename> but not <filename>hosta</filename>.
429 Will match <filename>hosta</filename> and <filename>hostb</filename>, but
430 not <filename>host</filename>.
437 Will match <filename>hoina</filename>
438 but not <filename>ho.aina.org</filename>.
445 Will match <filename>hoina</filename>
446 and <filename>ho.aina.org</filename>.
453 Will match <filename>hosta</filename>
454 but not <filename>foo.hosta.org</filename>.
461 Will match <filename>/dev/sda1</filename>
462 and <filename>/dev/sda12</filename>.
469 Will match the disk <filename>opt</filename>
470 but not the host <filename>opt</filename>.
475 <term>(note dots:) .opt.</term> <!-- nroff gets confused by dots -->
477 Will match the host <filename>opt</filename>
478 but not the disk <filename>opt</filename>.
485 Will match the disk <filename>/</filename>
493 Will match the disks <filename>/usr</filename>
494 and <filename>/usr/local</filename>.
501 Will match the disks <filename>/usr</filename>
502 but not <filename>/usr/local</filename>.
509 Will match the disks <filename>\\windows1\share</filename> and <filename>\\windows2\share</filename>.
516 Will match the disks <filename>\\windows\share1</filename> and <filename>\\windows\share2</filename>.
521 <term>//windows/share</term>
523 Will match the disk <filename>\\windows\share</filename>.
532 <refsect1><title>DATESTAMP EXPRESSION</title>
534 <emphasis remap='I'>datestamp</emphasis>
535 expression is a range expression where we only match the prefix.
536 Leading ^ is removed. Trailing $ forces an exact match.</para>
538 <variablelist remap="TP">
541 <term>20001212-14</term>
542 <listitem><para>match all dates beginning with 20001212, 20001213 or 20001214</para></listitem>
546 <term>20001212-4</term>
547 <listitem><para>same as previous</para></listitem>
551 <term>20001212-24</term>
552 <listitem><para>match all dates between 20001212 and 20001224</para></listitem>
557 <listitem><para>match all dates that start with 2000121 (20001210-20001219)</para></listitem>
562 <listitem><para>match all dates that start with 2 (20000101-29991231)</para></listitem>
567 <listitem><para>match all dates between 20000101-20101231</para></listitem>
572 <listitem><para>match only 200010</para></listitem>
579 <refsect1><title>DUMP SPECIFICATIONS</title> <para>A dump
580 specification selects one or more dumps. It has the form <emphasis
581 remap="I">[host][:disk][@datestamp]</emphasis>, where each component
582 is a pattern as described above. If a component is missing, it
583 is treated as a wildcard. The characters ':', '@', and '\' may be
584 escaped within any component by preceding them with a '\'.</para>
586 <para>Some examples:</para>
588 <variablelist remap='TP'>
590 <term>client17</term>
591 <listitem><para>all dumps of client17</para></listitem>
595 <term>@20080615</term>
596 <listitem><para>All dumps on with datestamps matching 20080615</para></listitem>
600 <term>webserver:/var/www</term>
601 <listitem><para>All dumps of /var/www on host webserver</para></listitem>
605 <term>webserver:/var/www@200806150317</term>
606 <listitem><para>The dump of webserver with datestamp 200806150317</para></listitem>
610 <term>:/var/www</term>
611 <listitem><para>All dumps of /var/www on any host</para></listitem>
618 <refsect1><title>CONFIGURATION OVERRIDE</title>
619 <para>Most commands allow the override of specific
620 configuration options on the command line, using the <arg
621 choice="plain">-o</arg> option. This option has the form <arg
622 choice="plain">-o</arg><replaceable>name</replaceable>=<replaceable>value</replaceable>.
623 An optional space is allowed after the <arg choice="plain">-o</arg>.
624 Each configuration option should be specified in a separate
625 command-line option.</para>
627 <para>For global options, <replaceable>name</replaceable> is simply the name of the option, e.g.,
631 For options in a named section of the configuration, <replaceable>name</replaceable> has the
632 form <replaceable>SECTION</replaceable>:<replaceable>section_name</replaceable>:<replaceable>name</replaceable>,
633 where <replaceable>SECTION</replaceable> is one of TAPETYPE, DUMPTYPE, HOLDINGDISK, or INTERFACE, and
634 <replaceable>section_name</replaceable> is the name of the tapetype, dumptype, holdingdisk, or interface.
637 amdump -o TAPETYPE:HP-DAT:length=2000m
638 amdump -o DUMPTYPE:no-compress:compress="server fast"
639 amdump -o HOLDINGDISK:hd1:use="-100 mb"
640 amdump -o INTERFACE:local:use="2000 kbps"
644 <para>When overriding device properties, one must carefully quote the
645 command line to simulate the syntax of real configuration files. The
646 following example should serve as a guide:
648 amdump -o 'device-property="PROPERTY_MAX_VOLUME_USAGE" "100000"'
649 </programlisting></para>
651 <para>Note that configuration overrides are not effective for tape
652 changers, which supply a tapedev based on their own configuration. In order to
653 override <emphasis remap="I">tapedev</emphasis>, you must also disable any changer:
655 amdump -otapedev=/dev/nst1 -otpchanger=''