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 '../entities/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 &A; 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='plain'><replaceable>config</replaceable></arg>
37 <arg choice='opt' rep='repeat'>
38 <arg choice='plain'><replaceable>host</replaceable></arg>
39 <arg choice='opt' rep='repeat'><replaceable>disk</replaceable></arg>
41 <arg choice='plain' rep='repeat'><group><arg choice='plain'>-o </arg><replaceable>configoption</replaceable></group></arg>
46 <refsect1><title>DESCRIPTION</title>
47 <para><emphasis remap='B'>Amcheck</emphasis>
48 runs a number of self-checks on both the &A; tape server host and
49 the &A; client hosts.</para>
51 <para>On the tape server host,
52 <command>amcheck</command>
53 can go through the same tape checking used at the start of the nightly
54 <emphasis remap='B'>amdump</emphasis>
55 run to verify the correct tape for the next run is mounted.</para>
57 <para><emphasis remap='B'>Amcheck</emphasis>
58 can also do a self-check on all client hosts
59 to make sure each host is running and that permissions
60 on filesystems to be backed up are correct.</para>
62 <para>You can specify many host/disk expressions, only disks that
63 match an expression will be checked. All disks are checked if no
64 expressions are given.</para>
67 <citerefentry><refentrytitle>amanda</refentrytitle><manvolnum>8</manvolnum></citerefentry>
68 man page for more details about &A;.</para>
71 <refsect1><title>OPTIONS</title>
72 <variablelist remap='TP'>
74 <term><option>-s</option></term>
76 <para>Run the tape server local and tape checks (same as
77 <option>-lt</option>).</para>
81 <term><option>-c</option></term>
83 <para>Run the client host checks. Multiple specific clients can be
84 checked by specifying the client name.</para>
88 <term><option>-l</option></term>
90 <para>Run the local tests (e.g. permissions) on the server host.</para>
94 <term><option>-t</option></term>
96 <para>Run the tape tests on the server host.</para>
100 <term><option>-w</option></term>
102 <para>Enables a DESTRUCTIVE check for write-protection on the
103 tape (which would otherwise cause the subsequent
104 <emphasis remap='B'>amdump</emphasis>
107 is writable, this check causes all data after the tape label to be
108 erased. If the label_new_tapes option is enabled, this check may ERASE
109 any non-Amanda tape in the drive or changer.
110 The check enable the tape tests on the server host
111 and is only made if the tape is otherwise correct.</para>
115 <term><option>-m</option></term>
117 <para>Nothing is printed, but mail is sent if any errors are detected.
119 <emphasis remap='B'>mailto</emphasis>
120 address specified in the
121 <emphasis remap='I'>amanda.conf</emphasis>
123 <emphasis remap='I'>address</emphasis>
130 <term><option>-a</option></term>
134 but the mail is always sent.</para>
139 <term><option>-M</option> <replaceable>address</replaceable></term>
141 <para>Mail the report to
142 <emphasis remap='I'>address</emphasis>
144 <emphasis remap='B'>mailto</emphasis>
146 <emphasis remap='I'>amanda.conf</emphasis>.
148 <option>-m</option>.</para>
153 <term><replaceable>host</replaceable> [<replaceable>disk</replaceable>]*</term>
155 <para>Specify the host and disk on which the command will work.</para>
160 <term><emphasis remap='B'>-o</emphasis> <replaceable>configoption</replaceable></term>
162 <para>See the "<emphasis remap='B'>CONFIGURATION OVERRIDE</emphasis>" section in <citerefentry><refentrytitle>amanda</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
168 <option>-cs</option>.</para>
171 <refsect1><title>EXAMPLES</title>
172 <para>In this example, both the tape server and client tests are run.
173 The results are displayed on standard output.</para>
177 &A; Tape Server Host Check
178 -----------------------------
179 /amanda2/amanda/work: 911475 KB disk space available, that's plenty.
180 NOTE: skipping tape-writable test.
182 Server check took 34.966 seconds.
184 &A; Backup Client Hosts Check
185 --------------------------------
186 WARNING: northstar: selfcheck request timed out. Host down?
187 WARNING: drinkme: selfcheck request timed out. Host down?
188 WARNING: scruffy: selfcheck request timed out. Host down?
189 Client check: 136 hosts checked in 51.945 seconds, 3 problems found.
191 (brought to you by &A; 2.5.0)
194 <para>In this example, if the line
195 <emphasis remap='B'>mailto csd-amanda</emphasis>
197 <emphasis remap='I'>amanda.conf</emphasis>,
199 <emphasis remap='B'>csd-amanda</emphasis>
200 if the server check returns an error.</para>
203 % amcheck -s -m daily
207 <refsect1><title>MESSAGES</title>
208 <variablelist remap='TP'>
210 <term>fatal slot <emphasis remap='I'>slot</emphasis>: <emphasis remap='I'>error message</emphasis></term>
213 The tape changer detected some kind of fatal error while trying to load slot
214 <emphasis remap='I'>slot</emphasis>.</para>
218 <term>slot <emphasis remap='I'>slot</emphasis>: <emphasis remap='I'>error message</emphasis></term>
221 The tape changer detected some kind of non-fatal error
222 (e.g. an empty slot was detected)
223 while trying to load slot
224 <emphasis remap='I'>slot</emphasis>,
225 or an error was detected trying to read the tape label.</para>
229 <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>
233 <emphasis remap='I'>label</emphasis>
235 <emphasis remap='I'>slot</emphasis>
236 was loaded and found to have been last written on
237 <emphasis remap='I'>YYYYMMDD</emphasis>.
238 If the tape is new, the date field will be an
239 <emphasis remap='I'>X</emphasis>.
241 <emphasis remap='I'>result</emphasis>
242 may be one of:</para>
244 <variablelist remap='TP'>
246 <term>exact label match</term>
248 <para>This is the expected tape.</para>
252 <term>no match</term>
254 <para>This label does not match the
255 <emphasis remap='B'>labelstr</emphasis>
257 <emphasis remap='I'>amanda.conf</emphasis>.
258 Tape scanning will continue.</para>
262 <term>active tape</term>
264 <para>This tape is still active and cannot be overwritten.
265 Tape scanning will continue.</para>
269 <term>first labelstr match</term>
271 <para>This tape is the first one that matches the
272 <emphasis remap='B'>labelstr</emphasis>
274 <emphasis remap='I'>amanda.conf</emphasis>.
275 Tape scanning will continue if necessary.</para>
279 <term>labelstr match</term>
281 <para>This tape is the next one that matches the
282 <emphasis remap='B'>labelstr</emphasis>
284 <emphasis remap='I'>amanda.conf</emphasis>.
285 Tape scanning will continue.</para>
293 <term>ERROR: cannot look up dump user <emphasis remap='I'>user</emphasis></term>
297 <emphasis remap='I'>user</emphasis>
299 <emphasis remap='I'>amanda.conf</emphasis>
300 could not be found in the system password information.</para>
304 <term>ERROR: cannot look up my own uid (<emphasis remap='I'>uid</emphasis>)</term>
308 <emphasis remap='I'>uid</emphasis>
310 <command>amcheck</command>
311 could not be found in the system password information.</para>
315 <term>ERROR: running as user <emphasis remap='I'>runuser</emphasis> instead of <emphasis remap='I'>dumpuser</emphasis></term>
318 <emphasis remap='B'>Amcheck</emphasis>
319 should be run as the dump user
320 <emphasis remap='I'>dumpuser</emphasis>
322 <emphasis remap='I'>amanda.conf</emphasis>
324 <emphasis remap='I'>runuser</emphasis>.</para>
328 <term>ERROR: program dir <emphasis remap='I'>directory</emphasis>: not accessible</term>
331 The directory &A; expects to find its auxiliary programs in,
332 <emphasis remap='I'>directory</emphasis>,
333 is not accessible.</para>
337 <term>ERROR: program <emphasis remap='I'>program</emphasis>: does not exist</term>
341 <emphasis remap='I'>program</emphasis>
342 needed on the tape server could not be found.</para>
346 <term>ERROR: program <emphasis remap='I'>program</emphasis>: not a file</term>
350 <emphasis remap='I'>program</emphasis>
351 needed on the tape server exists but is not a file.</para>
355 <term>ERROR: program <emphasis remap='I'>program</emphasis>: not executable</term>
359 <emphasis remap='I'>program</emphasis>
360 needed on the tape server exists but is not executable.</para>
364 <term>WARNING: program <emphasis remap='I'>program</emphasis>: not setuid-root</term>
368 <emphasis remap='I'>program</emphasis>
369 needed on the tape server exists but should be owned by user "root"
374 <term>ERROR: <emphasis remap='I'>XXX</emphasis> dir <emphasis remap='I'>directory</emphasis>: not writable</term>
378 <emphasis remap='I'>directory</emphasis>
379 is either not writable,
380 i.e. the dump user will not be able to create or remove files,
381 or cannot be accessed, perhaps because a parent directory
382 does not allow search permission.
384 <emphasis remap='I'>XXX</emphasis>
387 <variablelist remap='TP'>
391 <para>for the &A; log directory (see
392 <emphasis remap='B'>logdir</emphasis>
394 <emphasis remap='B'>amanda.conf</emphasis>)</para>
400 <para>for the directory that holds the old log files (see
401 <emphasis remap='B'>logdir</emphasis>
403 <emphasis remap='B'>amanda.conf</emphasis>)</para>
409 <para>for an &A; database information directory (see
410 <emphasis remap='B'>curinfo</emphasis>
412 <emphasis remap='B'>amanda.conf</emphasis>)
419 <para>for an &A; index directory (see
420 <emphasis remap='B'>indexdir</emphasis>
422 <emphasis remap='B'>amanda.conf</emphasis>)</para>
426 <term>tapelist</term>
428 <para>for the &tapelist;</para>
436 <term>NOTE: <emphasis remap='I'>XXX</emphasis> dir <emphasis remap='I'>directory</emphasis>: does not exist</term>
439 A database (info) or index directory does not exist or cannot be accessed.
440 This might just mean this is a new client or disk,
441 but if that is not the case, this should be treated as an error.</para>
445 <term>NOTE: it will be created on the next run</term>
448 This indicates the info directory listed in the previous message
449 will be created on the next run.</para>
453 <term>ERROR: <emphasis remap='I'>XXX</emphasis> dir <emphasis remap='I'>name</emphasis>: not a directory</term>
456 <emphasis remap='B'>Amcheck</emphasis>
458 <emphasis remap='I'>name</emphasis>
460 but it is something else (e.g. file).</para>
464 <term>WARNING: info file <filename>file</filename>: does not exist</term>
468 <emphasis remap='I'>file</emphasis>
469 does not exist in the text format database.
470 Since the parent directories do exist,
471 the file should already have been created.</para>
475 <term>ERROR: info file <filename>name</filename>: not a file</term>
478 <emphasis remap='B'>Amcheck</emphasis>
480 <emphasis remap='I'>name</emphasis>
482 but it is something else (e.g. file).</para>
486 <term>ERROR: info file <filename>file</filename>: not readable</term>
489 The text format database file
490 <emphasis remap='I'>file</emphasis>
491 is not readable.</para>
495 <term>ERROR: log file <filename>file</filename>: not writable</term>
499 <emphasis remap='I'>file</emphasis>
501 <emphasis remap='B'>log</emphasis>
503 <emphasis remap='B'>logdir</emphasis>
505 <emphasis remap='B'>amanda.conf</emphasis>)
506 is either not writable,
507 or cannot be accessed, perhaps because a parent directory
508 does not allow search permission.</para>
512 <term>ERROR: tape list <emphasis remap='I'>tapelist</emphasis>: not writable</term>
514 <para>(error) &tapelist; is not writable or was not found.</para>
518 <term>ERROR: tape list <emphasis remap='I'>tapelist</emphasis>: parse error</term>
520 <para>(error) &tapelist; could not be read or parsed.</para>
524 <term>WARNING: tapedev is /dev/null, dumps will be thrown away</term>
528 <emphasis remap='B'>tapedev</emphasis>
530 <emphasis remap='B'>amanda.conf</emphasis>
532 <filename>/dev/null</filename>
533 and &A; uses that when debugging to throw all the dump images away.</para>
537 <term>WARNING: hold file <filename>file</filename> exists</term>
541 <emphasis remap='I'>file</emphasis>
542 exists and will cause
543 <emphasis remap='B'>amdump</emphasis>
544 to pause at the beginning until it is removed.</para>
548 <term>ERROR: holding disk <emphasis remap='I'>disk</emphasis>: statfs: <emphasis remap='I'>error message</emphasis></term>
551 An error was returned from the
552 <emphasis remap='I'>statfs</emphasis>
553 system call on holding disk
554 <emphasis remap='I'>disk</emphasis>
555 (maybe because it does not exist).</para>
559 <term>ERROR: holding disk <emphasis remap='I'>disk</emphasis>: not writable</term>
563 <emphasis remap='I'>disk</emphasis>,
565 probably because the caller does not have write permission
566 or a parent directory does not allow search permission.</para>
570 <term>WARNING: holding disk <emphasis remap='I'>disk</emphasis>: available space unknown <emphasis remap='I'>N</emphasis> KB requested.</term>
573 <emphasis remap='B'>Amcheck</emphasis>
574 could not determine the amount of available space on holding disk
575 <emphasis remap='I'>disk</emphasis>
576 to see if there were at least
577 <emphasis remap='I'>N</emphasis>
578 KBytes available.</para>
582 <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>
585 <emphasis remap='I'>amanda.conf</emphasis>
587 <emphasis remap='I'>R</emphasis>
588 KBytes of free space on holding disk
589 <emphasis remap='I'>disk</emphasis>,
591 <emphasis remap='I'>F</emphasis>
592 KBytes were available.
593 10 MBytes is subtracted for each backup process
595 <emphasis remap='B'>inparallel</emphasis>
596 <emphasis remap='I'>amanda.conf</emphasis>
598 to allow for unexpected overruns.</para>
599 <note><para>Even though this message is listed as a warning, it causes &amcheck; to exit with a non-zero status.</para>
605 <variablelist remap='TP'>
607 <term>Holding disk <emphasis remap='I'>disk</emphasis>: <emphasis remap='I'>N</emphasis> KB disk space available, that's plenty.</term>
610 There was sufficient free space on holding disk
611 <emphasis remap='I'>disk</emphasis>.</para>
615 <term>WARNING: holding disk <emphasis remap='I'>disk</emphasis>: only <emphasis remap='I'>F</emphasis> KB free, using nothing</term>
619 <emphasis remap='I'>disk</emphasis>
621 <emphasis remap='I'>F</emphasis>
622 KBytes of free space, but that is not enough for what is requested in
623 <emphasis remap='I'>amanda.conf</emphasis>.</para>
627 <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>
631 <emphasis remap='I'>disk</emphasis>
633 <emphasis remap='I'>F</emphasis>
634 KBytes of free space and &A; will be using up to
635 <emphasis remap='I'>U</emphasis>
640 <term>WARNING: if a tape changer is not available, runtapes must be set to 1.</term>
644 <emphasis remap='B'>runtapes</emphasis>
645 <emphasis remap='I'>amanda.conf</emphasis>
646 option must be set to 1 if the
647 <emphasis remap='B'>tpchanger</emphasis>
648 <emphasis remap='I'>amanda.conf</emphasis>
649 option is not set.</para>
653 <term>ERROR: <emphasis remap='I'>error message</emphasis>.</term>
656 An error was detected while initializing the tape changer.</para>
660 <term>ERROR: <emphasis remap='I'>tape device</emphasis>: <emphasis remap='I'>error message</emphasis>.</term>
663 An error was detected while processing the tape label.</para>
667 <term>ERROR: cannot overwrite active tape <emphasis remap='I'>label</emphasis>.</term>
671 <emphasis remap='I'>label</emphasis>
672 is still active and cannot be used.</para>
676 <term>ERROR: label <emphasis remap='I'>label</emphasis> doesn't match labelstr <emphasis remap='I'>pattern</emphasis> .</term>
680 <emphasis remap='I'>label</emphasis>
682 <emphasis remap='B'>labelstr</emphasis>
683 <emphasis remap='I'>amanda.conf</emphasis>
688 <term>(expecting a new tape)</term>
691 The tape is not OK and a new tape was expected.</para>
695 <term>(expecting tape <emphasis remap='I'>label</emphasis> or a new tape)</term>
698 The tape is not OK and either tape
699 <emphasis remap='I'>label</emphasis>
700 or a new tape was expected.</para>
704 <term>ERROR: tape <emphasis remap='I'>label</emphasis> label ok, but is not writable.</term>
708 <emphasis remap='I'>label</emphasis>
709 is OK, but the write enable test failed.</para>
713 <term>Tape <emphasis remap='I'>label</emphasis> is writable.</term>
717 <emphasis remap='I'>label</emphasis>
718 is OK and the write enable test succeeded.</para>
722 <term>NOTE: skipping tape-writable test.</term>
725 The tape write test (see the
727 option) was not enabled.</para>
731 <term>WARNING: skipping tape test because amdump or amflush seem to be running</term>
732 <term>WARNING: if they are not, you must run amcleanup</term>
736 <command>amcheck</command>
738 <emphasis remap='B'>amdump</emphasis>
740 <emphasis remap='B'>amflush</emphasis>
741 were running because a log file or amdump file exists.
742 If they are not running, you probably need to run
743 <emphasis remap='B'>amcleanup</emphasis>
744 to clear up a previous failure.
745 Otherwise, you need to wait until they complete before running
746 <command>amcheck</command><literal>.</literal></para>
750 <term>NOTE: skipping tape checks</term>
753 The tape tests are being skipped because you used the
755 command line option.</para>
759 <term>WARNING: <emphasis remap='I'>compress</emphasis> is not executable, server-compression and indexing will not work</term>
763 <emphasis remap='I'>compress</emphasis>
765 so compression on the tape server host and creating index files will not work.</para>
769 <term>Tape <emphasis remap='I'>label</emphasis> label ok.</term>
773 <emphasis remap='I'>label</emphasis>
779 <term>Server check took <emphasis remap='I'>S</emphasis> seconds.</term>
782 Reports how long the tape server host checks took.</para>
786 <term>ERROR: <emphasis remap='I'>host</emphasis>: could not resolve hostname</term>
789 Could not look up client hostname
790 <emphasis remap='I'>host</emphasis>.</para>
794 <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>
797 Reports the number of client hosts checked,
798 how long it took and the number of errors detected.</para>
802 <term>WARNING: <emphasis remap='I'>host</emphasis>: selfcheck request timed out. Host down?</term>
805 There was no response from
806 <emphasis remap='I'>host</emphasis>
807 when trying to do the client checks.
808 The host might really be down or it might not be configured properly.</para>
812 <term>ERROR: <emphasis remap='I'>host</emphasis> NAK: <emphasis remap='I'>message</emphasis></term>
815 <emphasis remap='I'>Host</emphasis>
816 reported a negative acknowledgment error of
817 <emphasis remap='I'>message</emphasis>
818 to the status check request.</para>
822 <term>ERROR: <emphasis remap='I'>host</emphasis> NAK: [NAK parse failed]</term>
825 <emphasis remap='B'>Amcheck</emphasis>
826 could not parse the negative acknowledgment error from
827 <emphasis remap='I'>host</emphasis>.
828 There might be an &A; version mismatch between the host running
829 <command>amcheck</command>
831 <emphasis remap='I'>host</emphasis>.</para>
835 <term>ERROR: <emphasis remap='I'>host</emphasis> [mutual-authentication failed]</term>
838 Kerberos authentication failed while contacting
839 <emphasis remap='I'>host</emphasis>.</para>
843 <term>ERROR: <emphasis remap='I'>host</emphasis>: <emphasis remap='I'>message</emphasis></term>
847 <emphasis remap='I'>message</emphasis>
848 was reported by the status check on
849 <emphasis remap='I'>host</emphasis>.</para>
855 <refsect1><title>EXIT CODE</title>
856 The exit code of <command>amcheck</command> is one of:
863 <refsect1><title>SEE ALSO</title>
864 <para><citerefentry><refentrytitle>amanda</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
865 <citerefentry><refentrytitle>amdump</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
866 <ulink url="http://wiki.zmanda.com"/>