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='amcheck.8'>
14 <refentrytitle>amcheck</refentrytitle>
15 <manvolnum>8</manvolnum>
21 <refname>amcheck</refname>
22 <refpurpose>run Amanda self-checks</refpurpose>
28 <!-- body begins here -->
31 <command>amcheck</command>
32 <arg choice='opt'>-am</arg>
33 <arg choice='opt'>-w</arg>
34 <arg choice='opt'>-sclt</arg>
35 <arg choice='opt'>-M <replaceable>address</replaceable></arg>
36 <arg choice='opt'>--client-verbose</arg>
37 &configoverride.synopsis;
38 <arg choice='plain'><replaceable>config</replaceable></arg>
39 <arg choice='opt' rep='repeat'>
40 <arg choice='plain'><replaceable>host</replaceable></arg>
41 <arg choice='opt' rep='repeat'><replaceable>disk</replaceable></arg>
47 <refsect1><title>DESCRIPTION</title>
48 <para><emphasis remap='B'>Amcheck</emphasis>
49 runs a number of self-checks on both the Amanda tape server host and
50 the Amanda client hosts.</para>
52 <para>On the tape server host,
53 <command>amcheck</command>
54 can go through the same tape checking used at the start of the nightly
55 <emphasis remap='B'>amdump</emphasis>
56 run to verify the correct tape for the next run is mounted.</para>
58 <para><emphasis remap='B'>Amcheck</emphasis>
59 can also do a self-check on all client hosts
60 to make sure each host is running and that permissions
61 on filesystems to be backed up are correct.</para>
63 <para>You can specify many host/disk expressions, only disks that
64 match an expression will be checked. All disks are checked if no
65 expressions are given.</para>
68 <manref name="amanda" vol="8"/>
69 man page for more details about Amanda.</para>
72 <refsect1><title>OPTIONS</title>
73 <variablelist remap='TP'>
75 <term><option>-s</option></term>
77 <para>Run the tape server local and tape checks (same as
78 <option>-lt</option>).</para>
82 <term><option>-c</option></term>
84 <para>Run the client host checks. Multiple specific clients can be
85 checked by specifying the client name.</para>
89 <term><option>-l</option></term>
91 <para>Run the local tests (e.g. permissions) on the server host.</para>
95 <term><option>-t</option></term>
97 <para>Run the tape tests on the server host.</para>
101 <term><option>-w</option></term>
103 <para>Enables a DESTRUCTIVE check for write-protection on the
104 tape (which would otherwise cause the subsequent
105 <emphasis remap='B'>amdump</emphasis>
108 is writable, this check causes all data after the tape label to be
109 erased. If the <amkeyword>autolabel</amkeyword> option is enabled, this check may ERASE
110 any non-Amanda tape in the drive or changer.
111 The check enable the tape tests on the server host
112 and is only made if the tape is otherwise correct.</para>
116 <term><option>-m</option></term>
118 <para>Nothing is printed, but mail is sent if any errors are detected.
120 <emphasis remap='B'>mailto</emphasis>
121 address specified in the
122 <emphasis remap='I'>amanda.conf</emphasis>
124 <emphasis remap='I'>address</emphasis>
131 <term><option>-a</option></term>
135 but the mail is always sent.</para>
140 <term><option>-M</option> <replaceable>address</replaceable></term>
142 <para>Mail the report to
143 <emphasis remap='I'>address</emphasis>
145 <emphasis remap='B'>mailto</emphasis>
147 <emphasis remap='I'>amanda.conf</emphasis>.
149 <option>-m</option>.</para>
154 <term><option>--client-verbose</option></term>
156 <para>Print all client messages.</para>
161 <term><replaceable>host</replaceable> [<replaceable>disk</replaceable>]*</term>
163 <para>Specify the host and disk on which the command will work.</para>
167 &configoverride.varlistentry;
172 <option>-cs</option>.</para>
175 <refsect1><title>EXAMPLES</title>
176 <para>In this example, both the tape server and client tests are run.
177 The results are displayed on standard output.</para>
181 Amanda Tape Server Host Check
182 -----------------------------
183 /amanda2/amanda/work: 911475 KB disk space available, that's plenty.
184 NOTE: skipping tape-writable test.
186 Server check took 34.966 seconds.
188 Amanda Backup Client Hosts Check
189 --------------------------------
190 WARNING: northstar: selfcheck request timed out. Host down?
191 WARNING: drinkme: selfcheck request timed out. Host down?
192 WARNING: scruffy: selfcheck request timed out. Host down?
193 Client check: 136 hosts checked in 51.945 seconds, 3 problems found.
195 (brought to you by Amanda 2.5.0)
198 <para>In this example, if the line
199 <emphasis remap='B'>mailto csd-amanda</emphasis>
201 <emphasis remap='I'>amanda.conf</emphasis>,
203 <emphasis remap='B'>csd-amanda</emphasis>
204 if the server check returns an error.</para>
207 % amcheck -s -m daily
211 <refsect1><title>MESSAGES</title>
212 <variablelist remap='TP'>
214 <term>fatal slot <emphasis remap='I'>slot</emphasis>: <emphasis remap='I'>error message</emphasis></term>
217 The tape changer detected some kind of fatal error while trying to load slot
218 <emphasis remap='I'>slot</emphasis>.</para>
222 <term>slot <emphasis remap='I'>slot</emphasis>: <emphasis remap='I'>error message</emphasis></term>
225 The tape changer detected some kind of non-fatal error
226 (e.g. an empty slot was detected)
227 while trying to load slot
228 <emphasis remap='I'>slot</emphasis>,
229 or an error was detected trying to read the tape label.</para>
233 <term>slot <emphasis remap='I'>slot</emphasis>: date <emphasis remap='I'>YYYYMMDD</emphasis> label <emphasis remap='I'>label</emphasis> (<emphasis remap='I'>result</emphasis>)</term>
237 <emphasis remap='I'>label</emphasis>
239 <emphasis remap='I'>slot</emphasis>
240 was loaded and found to have been last written on
241 <emphasis remap='I'>YYYYMMDD</emphasis>.
242 If the tape is new, the date field will be an
243 <emphasis remap='I'>X</emphasis>.
245 <emphasis remap='I'>result</emphasis>
246 may be one of:</para>
248 <variablelist remap='TP'>
250 <term>exact label match</term>
252 <para>This is the expected tape.</para>
256 <term>no match</term>
258 <para>This label does not match the
259 <emphasis remap='B'>labelstr</emphasis>
261 <emphasis remap='I'>amanda.conf</emphasis>.
262 Tape scanning will continue.</para>
266 <term>active tape</term>
268 <para>This tape is still active and cannot be overwritten.
269 Tape scanning will continue.</para>
273 <term>first labelstr match</term>
275 <para>This tape is the first one that matches the
276 <emphasis remap='B'>labelstr</emphasis>
278 <emphasis remap='I'>amanda.conf</emphasis>.
279 Tape scanning will continue if necessary.</para>
283 <term>labelstr match</term>
285 <para>This tape is the next one that matches the
286 <emphasis remap='B'>labelstr</emphasis>
288 <emphasis remap='I'>amanda.conf</emphasis>.
289 Tape scanning will continue.</para>
297 <term>ERROR: cannot look up dump user <emphasis remap='I'>user</emphasis></term>
301 <emphasis remap='I'>user</emphasis>
303 <emphasis remap='I'>amanda.conf</emphasis>
304 could not be found in the system password information.</para>
308 <term>ERROR: cannot look up my own uid (<emphasis remap='I'>uid</emphasis>)</term>
312 <emphasis remap='I'>uid</emphasis>
314 <command>amcheck</command>
315 could not be found in the system password information.</para>
319 <term>ERROR: running as user <emphasis remap='I'>runuser</emphasis> instead of <emphasis remap='I'>dumpuser</emphasis></term>
322 <emphasis remap='B'>Amcheck</emphasis>
323 should be run as the dump user
324 <emphasis remap='I'>dumpuser</emphasis>
326 <emphasis remap='I'>amanda.conf</emphasis>
328 <emphasis remap='I'>runuser</emphasis>.</para>
332 <term>ERROR: program dir <emphasis remap='I'>directory</emphasis>: not accessible</term>
335 The directory Amanda expects to find its auxiliary programs in,
336 <emphasis remap='I'>directory</emphasis>,
337 is not accessible.</para>
341 <term>ERROR: program <emphasis remap='I'>program</emphasis>: does not exist</term>
345 <emphasis remap='I'>program</emphasis>
346 needed on the tape server could not be found.</para>
350 <term>ERROR: program <emphasis remap='I'>program</emphasis>: not a file</term>
354 <emphasis remap='I'>program</emphasis>
355 needed on the tape server exists but is not a file.</para>
359 <term>ERROR: program <emphasis remap='I'>program</emphasis>: not executable</term>
363 <emphasis remap='I'>program</emphasis>
364 needed on the tape server exists but is not executable.</para>
368 <term>WARNING: program <emphasis remap='I'>program</emphasis>: not setuid-root</term>
372 <emphasis remap='I'>program</emphasis>
373 needed on the tape server exists but should be owned by user "root"
378 <term>ERROR: <emphasis remap='I'>XXX</emphasis> dir <emphasis remap='I'>directory</emphasis>: not writable</term>
382 <emphasis remap='I'>directory</emphasis>
383 is either not writable,
384 i.e. the dump user will not be able to create or remove files,
385 or cannot be accessed, perhaps because a parent directory
386 does not allow search permission.
388 <emphasis remap='I'>XXX</emphasis>
391 <variablelist remap='TP'>
395 <para>for the Amanda log directory (see
396 <emphasis remap='B'>logdir</emphasis>
398 <emphasis remap='B'>amanda.conf</emphasis>)</para>
404 <para>for the directory that holds the old log files (see
405 <emphasis remap='B'>logdir</emphasis>
407 <emphasis remap='B'>amanda.conf</emphasis>)</para>
413 <para>for an Amanda database information directory (see
414 <emphasis remap='B'>curinfo</emphasis>
416 <emphasis remap='B'>amanda.conf</emphasis>)
423 <para>for an Amanda index directory (see
424 <emphasis remap='B'>indexdir</emphasis>
426 <emphasis remap='B'>amanda.conf</emphasis>)</para>
430 <term>tapelist</term>
432 <para>for the &tapelist;</para>
440 <term>NOTE: <emphasis remap='I'>XXX</emphasis> dir <emphasis remap='I'>directory</emphasis>: does not exist</term>
443 A database (info) or index directory does not exist or cannot be accessed.
444 This might just mean this is a new client or disk,
445 but if that is not the case, this should be treated as an error.</para>
449 <term>NOTE: it will be created on the next run</term>
452 This indicates the info directory listed in the previous message
453 will be created on the next run.</para>
457 <term>ERROR: <emphasis remap='I'>XXX</emphasis> dir <emphasis remap='I'>name</emphasis>: not a directory</term>
460 <emphasis remap='B'>Amcheck</emphasis>
462 <emphasis remap='I'>name</emphasis>
464 but it is something else (e.g. file).</para>
468 <term>WARNING: info file <filename>file</filename>: does not exist</term>
472 <emphasis remap='I'>file</emphasis>
473 does not exist in the text format database.
474 Since the parent directories do exist,
475 the file should already have been created.</para>
479 <term>ERROR: info file <filename>name</filename>: not a file</term>
482 <emphasis remap='B'>Amcheck</emphasis>
484 <emphasis remap='I'>name</emphasis>
486 but it is something else (e.g. file).</para>
490 <term>ERROR: info file <filename>file</filename>: not readable</term>
493 The text format database file
494 <emphasis remap='I'>file</emphasis>
495 is not readable.</para>
499 <term>ERROR: log file <filename>file</filename>: not writable</term>
503 <emphasis remap='I'>file</emphasis>
505 <emphasis remap='B'>log</emphasis>
507 <emphasis remap='B'>logdir</emphasis>
509 <emphasis remap='B'>amanda.conf</emphasis>)
510 is either not writable,
511 or cannot be accessed, perhaps because a parent directory
512 does not allow search permission.</para>
516 <term>ERROR: tape list <emphasis remap='I'>tapelist</emphasis>: not writable</term>
518 <para>(error) &tapelist; is not writable or was not found.</para>
522 <term>ERROR: tape list <emphasis remap='I'>tapelist</emphasis>: parse error</term>
524 <para>(error) &tapelist; could not be read or parsed.</para>
528 <term>WARNING: tapedev is /dev/null, dumps will be thrown away</term>
532 <emphasis remap='B'>tapedev</emphasis>
534 <emphasis remap='B'>amanda.conf</emphasis>
536 <filename>/dev/null</filename>
537 and Amanda uses that when debugging to throw all the dump images away.</para>
541 <term>WARNING: hold file <filename>file</filename> exists</term>
545 <emphasis remap='I'>file</emphasis>
546 exists and will cause
547 <emphasis remap='B'>amdump</emphasis>
548 to pause at the beginning until it is removed.</para>
552 <term>ERROR: holding disk <emphasis remap='I'>disk</emphasis>: statfs: <emphasis remap='I'>error message</emphasis></term>
555 An error was returned from the
556 <emphasis remap='I'>statfs</emphasis>
557 system call on holding disk
558 <emphasis remap='I'>disk</emphasis>
559 (maybe because it does not exist).</para>
563 <term>ERROR: holding disk <emphasis remap='I'>disk</emphasis>: not writable</term>
567 <emphasis remap='I'>disk</emphasis>,
569 probably because the caller does not have write permission
570 or a parent directory does not allow search permission.</para>
574 <term>WARNING: holding disk <emphasis remap='I'>disk</emphasis>: available space unknown <emphasis remap='I'>N</emphasis> KB requested.</term>
577 <emphasis remap='B'>Amcheck</emphasis>
578 could not determine the amount of available space on holding disk
579 <emphasis remap='I'>disk</emphasis>
580 to see if there were at least
581 <emphasis remap='I'>N</emphasis>
582 KBytes available.</para>
586 <term>WARNING: holding disk <emphasis remap='I'>disk</emphasis>: only <emphasis remap='I'>F</emphasis> KB free (<emphasis remap='I'>R</emphasis> KB requested).</term>
589 <emphasis remap='I'>amanda.conf</emphasis>
591 <emphasis remap='I'>R</emphasis>
592 KBytes of free space on holding disk
593 <emphasis remap='I'>disk</emphasis>,
595 <emphasis remap='I'>F</emphasis>
596 KBytes were available.
597 10 MBytes is subtracted for each backup process
599 <emphasis remap='B'>inparallel</emphasis>
600 <emphasis remap='I'>amanda.conf</emphasis>
602 to allow for unexpected overruns.</para>
603 <note><para>Even though this message is listed as a warning, it causes &amcheck; to exit with a non-zero status.</para>
609 <variablelist remap='TP'>
611 <term>Holding disk <emphasis remap='I'>disk</emphasis>: <emphasis remap='I'>N</emphasis> KB disk space available, that's plenty.</term>
614 There was sufficient free space on holding disk
615 <emphasis remap='I'>disk</emphasis>.</para>
619 <term>WARNING: holding disk <emphasis remap='I'>disk</emphasis>: only <emphasis remap='I'>F</emphasis> KB free, using nothing</term>
623 <emphasis remap='I'>disk</emphasis>
625 <emphasis remap='I'>F</emphasis>
626 KBytes of free space, but that is not enough for what is requested in
627 <emphasis remap='I'>amanda.conf</emphasis>.</para>
631 <term>Holding disk <emphasis remap='I'>disk</emphasis>: <emphasis remap='I'>F</emphasis> KB disk space available, using <emphasis remap='I'>U</emphasis> KB</term>
635 <emphasis remap='I'>disk</emphasis>
637 <emphasis remap='I'>F</emphasis>
638 KBytes of free space and Amanda will be using up to
639 <emphasis remap='I'>U</emphasis>
644 <term>WARNING: if a tape changer is not available, runtapes must be set to 1.</term>
648 <emphasis remap='B'>runtapes</emphasis>
649 <emphasis remap='I'>amanda.conf</emphasis>
650 option must be set to 1 if the
651 <emphasis remap='B'>tpchanger</emphasis>
652 <emphasis remap='I'>amanda.conf</emphasis>
653 option is not set.</para>
657 <term>ERROR: <emphasis remap='I'>error message</emphasis>.</term>
660 An error was detected while initializing the tape changer.</para>
664 <term>ERROR: <emphasis remap='I'>tape device</emphasis>: <emphasis remap='I'>error message</emphasis>.</term>
667 An error was detected while processing the tape label.</para>
671 <term>ERROR: cannot overwrite active tape <emphasis remap='I'>label</emphasis>.</term>
675 <emphasis remap='I'>label</emphasis>
676 is still active and cannot be used.</para>
680 <term>ERROR: label <emphasis remap='I'>label</emphasis> doesn't match labelstr <emphasis remap='I'>pattern</emphasis> .</term>
684 <emphasis remap='I'>label</emphasis>
686 <emphasis remap='B'>labelstr</emphasis>
687 <emphasis remap='I'>amanda.conf</emphasis>
692 <term>(expecting a new tape)</term>
695 The tape is not OK and a new tape was expected.</para>
699 <term>(expecting tape <emphasis remap='I'>label</emphasis> or a new tape)</term>
702 The tape is not OK and either tape
703 <emphasis remap='I'>label</emphasis>
704 or a new tape was expected.</para>
708 <term>ERROR: tape <emphasis remap='I'>label</emphasis> label ok, but is not writable.</term>
712 <emphasis remap='I'>label</emphasis>
713 is OK, but the write enable test failed.</para>
717 <term>Tape <emphasis remap='I'>label</emphasis> is writable.</term>
721 <emphasis remap='I'>label</emphasis>
722 is OK and the write enable test succeeded.</para>
726 <term>NOTE: skipping tape-writable test.</term>
729 The tape write test (see the
731 option) was not enabled.</para>
735 <term>WARNING: skipping tape test because amdump or amflush seem to be running</term>
736 <term>WARNING: if they are not, you must run amcleanup</term>
740 <command>amcheck</command>
742 <emphasis remap='B'>amdump</emphasis>
744 <emphasis remap='B'>amflush</emphasis>
745 were running because a log file or amdump file exists.
746 If they are not running, you probably need to run
747 <emphasis remap='B'>amcleanup</emphasis>
748 to clear up a previous failure.
749 Otherwise, you need to wait until they complete before running
750 <command>amcheck</command><literal>.</literal></para>
754 <term>NOTE: skipping tape checks</term>
757 The tape tests are being skipped because you used the
759 command line option.</para>
763 <term>WARNING: <emphasis remap='I'>compress</emphasis> is not executable, server-compression and indexing will not work</term>
767 <emphasis remap='I'>compress</emphasis>
769 so compression on the tape server host and creating index files will not work.</para>
773 <term>Tape <emphasis remap='I'>label</emphasis> label ok.</term>
777 <emphasis remap='I'>label</emphasis>
783 <term>Server check took <emphasis remap='I'>S</emphasis> seconds.</term>
786 Reports how long the tape server host checks took.</para>
790 <term>ERROR: <emphasis remap='I'>host</emphasis>: could not resolve hostname</term>
793 Could not look up client hostname
794 <emphasis remap='I'>host</emphasis>.</para>
798 <term>Client check: <emphasis remap='I'>H</emphasis> hosts checked in <emphasis remap='I'>S</emphasis> seconds, <emphasis remap='I'>N</emphasis> problems found.</term>
801 Reports the number of client hosts checked,
802 how long it took and the number of errors detected.</para>
806 <term>WARNING: <emphasis remap='I'>host</emphasis>: selfcheck request timed out. Host down?</term>
809 There was no response from
810 <emphasis remap='I'>host</emphasis>
811 when trying to do the client checks.
812 The host might really be down or it might not be configured properly.</para>
816 <term>ERROR: <emphasis remap='I'>host</emphasis> NAK: <emphasis remap='I'>message</emphasis></term>
819 <emphasis remap='I'>Host</emphasis>
820 reported a negative acknowledgment error of
821 <emphasis remap='I'>message</emphasis>
822 to the status check request.</para>
826 <term>ERROR: <emphasis remap='I'>host</emphasis> NAK: [NAK parse failed]</term>
829 <emphasis remap='B'>Amcheck</emphasis>
830 could not parse the negative acknowledgment error from
831 <emphasis remap='I'>host</emphasis>.
832 There might be an Amanda version mismatch between the host running
833 <command>amcheck</command>
835 <emphasis remap='I'>host</emphasis>.</para>
839 <term>ERROR: <emphasis remap='I'>host</emphasis> [mutual-authentication failed]</term>
842 Kerberos authentication failed while contacting
843 <emphasis remap='I'>host</emphasis>.</para>
847 <term>ERROR: <emphasis remap='I'>host</emphasis>: <emphasis remap='I'>message</emphasis></term>
851 <emphasis remap='I'>message</emphasis>
852 was reported by the status check on
853 <emphasis remap='I'>host</emphasis>.</para>
859 <refsect1><title>EXIT CODE</title>
860 The exit code of <command>amcheck</command> is one of:
868 <manref name="amanda.conf" vol="5"/>
869 <manref name="amdump" vol="8"/>