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='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 &configoverride.synopsis;
46 <refsect1><title>DESCRIPTION</title>
47 <para><emphasis remap='B'>Amcheck</emphasis>
48 runs a number of self-checks on both the Amanda tape server host and
49 the Amanda 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 <manref name="amanda" vol="8"/>
68 man page for more details about Amanda.</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>
159 &configoverride.varlistentry;
164 <option>-cs</option>.</para>
167 <refsect1><title>EXAMPLES</title>
168 <para>In this example, both the tape server and client tests are run.
169 The results are displayed on standard output.</para>
173 Amanda Tape Server Host Check
174 -----------------------------
175 /amanda2/amanda/work: 911475 KB disk space available, that's plenty.
176 NOTE: skipping tape-writable test.
178 Server check took 34.966 seconds.
180 Amanda Backup Client Hosts Check
181 --------------------------------
182 WARNING: northstar: selfcheck request timed out. Host down?
183 WARNING: drinkme: selfcheck request timed out. Host down?
184 WARNING: scruffy: selfcheck request timed out. Host down?
185 Client check: 136 hosts checked in 51.945 seconds, 3 problems found.
187 (brought to you by Amanda 2.5.0)
190 <para>In this example, if the line
191 <emphasis remap='B'>mailto csd-amanda</emphasis>
193 <emphasis remap='I'>amanda.conf</emphasis>,
195 <emphasis remap='B'>csd-amanda</emphasis>
196 if the server check returns an error.</para>
199 % amcheck -s -m daily
203 <refsect1><title>MESSAGES</title>
204 <variablelist remap='TP'>
206 <term>fatal slot <emphasis remap='I'>slot</emphasis>: <emphasis remap='I'>error message</emphasis></term>
209 The tape changer detected some kind of fatal error while trying to load slot
210 <emphasis remap='I'>slot</emphasis>.</para>
214 <term>slot <emphasis remap='I'>slot</emphasis>: <emphasis remap='I'>error message</emphasis></term>
217 The tape changer detected some kind of non-fatal error
218 (e.g. an empty slot was detected)
219 while trying to load slot
220 <emphasis remap='I'>slot</emphasis>,
221 or an error was detected trying to read the tape label.</para>
225 <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>
229 <emphasis remap='I'>label</emphasis>
231 <emphasis remap='I'>slot</emphasis>
232 was loaded and found to have been last written on
233 <emphasis remap='I'>YYYYMMDD</emphasis>.
234 If the tape is new, the date field will be an
235 <emphasis remap='I'>X</emphasis>.
237 <emphasis remap='I'>result</emphasis>
238 may be one of:</para>
240 <variablelist remap='TP'>
242 <term>exact label match</term>
244 <para>This is the expected tape.</para>
248 <term>no match</term>
250 <para>This label does not match the
251 <emphasis remap='B'>labelstr</emphasis>
253 <emphasis remap='I'>amanda.conf</emphasis>.
254 Tape scanning will continue.</para>
258 <term>active tape</term>
260 <para>This tape is still active and cannot be overwritten.
261 Tape scanning will continue.</para>
265 <term>first labelstr match</term>
267 <para>This tape is the first one that matches the
268 <emphasis remap='B'>labelstr</emphasis>
270 <emphasis remap='I'>amanda.conf</emphasis>.
271 Tape scanning will continue if necessary.</para>
275 <term>labelstr match</term>
277 <para>This tape is the next one that matches the
278 <emphasis remap='B'>labelstr</emphasis>
280 <emphasis remap='I'>amanda.conf</emphasis>.
281 Tape scanning will continue.</para>
289 <term>ERROR: cannot look up dump user <emphasis remap='I'>user</emphasis></term>
293 <emphasis remap='I'>user</emphasis>
295 <emphasis remap='I'>amanda.conf</emphasis>
296 could not be found in the system password information.</para>
300 <term>ERROR: cannot look up my own uid (<emphasis remap='I'>uid</emphasis>)</term>
304 <emphasis remap='I'>uid</emphasis>
306 <command>amcheck</command>
307 could not be found in the system password information.</para>
311 <term>ERROR: running as user <emphasis remap='I'>runuser</emphasis> instead of <emphasis remap='I'>dumpuser</emphasis></term>
314 <emphasis remap='B'>Amcheck</emphasis>
315 should be run as the dump user
316 <emphasis remap='I'>dumpuser</emphasis>
318 <emphasis remap='I'>amanda.conf</emphasis>
320 <emphasis remap='I'>runuser</emphasis>.</para>
324 <term>ERROR: program dir <emphasis remap='I'>directory</emphasis>: not accessible</term>
327 The directory Amanda expects to find its auxiliary programs in,
328 <emphasis remap='I'>directory</emphasis>,
329 is not accessible.</para>
333 <term>ERROR: program <emphasis remap='I'>program</emphasis>: does not exist</term>
337 <emphasis remap='I'>program</emphasis>
338 needed on the tape server could not be found.</para>
342 <term>ERROR: program <emphasis remap='I'>program</emphasis>: not a file</term>
346 <emphasis remap='I'>program</emphasis>
347 needed on the tape server exists but is not a file.</para>
351 <term>ERROR: program <emphasis remap='I'>program</emphasis>: not executable</term>
355 <emphasis remap='I'>program</emphasis>
356 needed on the tape server exists but is not executable.</para>
360 <term>WARNING: program <emphasis remap='I'>program</emphasis>: not setuid-root</term>
364 <emphasis remap='I'>program</emphasis>
365 needed on the tape server exists but should be owned by user "root"
370 <term>ERROR: <emphasis remap='I'>XXX</emphasis> dir <emphasis remap='I'>directory</emphasis>: not writable</term>
374 <emphasis remap='I'>directory</emphasis>
375 is either not writable,
376 i.e. the dump user will not be able to create or remove files,
377 or cannot be accessed, perhaps because a parent directory
378 does not allow search permission.
380 <emphasis remap='I'>XXX</emphasis>
383 <variablelist remap='TP'>
387 <para>for the Amanda log directory (see
388 <emphasis remap='B'>logdir</emphasis>
390 <emphasis remap='B'>amanda.conf</emphasis>)</para>
396 <para>for the directory that holds the old log files (see
397 <emphasis remap='B'>logdir</emphasis>
399 <emphasis remap='B'>amanda.conf</emphasis>)</para>
405 <para>for an Amanda database information directory (see
406 <emphasis remap='B'>curinfo</emphasis>
408 <emphasis remap='B'>amanda.conf</emphasis>)
415 <para>for an Amanda index directory (see
416 <emphasis remap='B'>indexdir</emphasis>
418 <emphasis remap='B'>amanda.conf</emphasis>)</para>
422 <term>tapelist</term>
424 <para>for the &tapelist;</para>
432 <term>NOTE: <emphasis remap='I'>XXX</emphasis> dir <emphasis remap='I'>directory</emphasis>: does not exist</term>
435 A database (info) or index directory does not exist or cannot be accessed.
436 This might just mean this is a new client or disk,
437 but if that is not the case, this should be treated as an error.</para>
441 <term>NOTE: it will be created on the next run</term>
444 This indicates the info directory listed in the previous message
445 will be created on the next run.</para>
449 <term>ERROR: <emphasis remap='I'>XXX</emphasis> dir <emphasis remap='I'>name</emphasis>: not a directory</term>
452 <emphasis remap='B'>Amcheck</emphasis>
454 <emphasis remap='I'>name</emphasis>
456 but it is something else (e.g. file).</para>
460 <term>WARNING: info file <filename>file</filename>: does not exist</term>
464 <emphasis remap='I'>file</emphasis>
465 does not exist in the text format database.
466 Since the parent directories do exist,
467 the file should already have been created.</para>
471 <term>ERROR: info file <filename>name</filename>: not a file</term>
474 <emphasis remap='B'>Amcheck</emphasis>
476 <emphasis remap='I'>name</emphasis>
478 but it is something else (e.g. file).</para>
482 <term>ERROR: info file <filename>file</filename>: not readable</term>
485 The text format database file
486 <emphasis remap='I'>file</emphasis>
487 is not readable.</para>
491 <term>ERROR: log file <filename>file</filename>: not writable</term>
495 <emphasis remap='I'>file</emphasis>
497 <emphasis remap='B'>log</emphasis>
499 <emphasis remap='B'>logdir</emphasis>
501 <emphasis remap='B'>amanda.conf</emphasis>)
502 is either not writable,
503 or cannot be accessed, perhaps because a parent directory
504 does not allow search permission.</para>
508 <term>ERROR: tape list <emphasis remap='I'>tapelist</emphasis>: not writable</term>
510 <para>(error) &tapelist; is not writable or was not found.</para>
514 <term>ERROR: tape list <emphasis remap='I'>tapelist</emphasis>: parse error</term>
516 <para>(error) &tapelist; could not be read or parsed.</para>
520 <term>WARNING: tapedev is /dev/null, dumps will be thrown away</term>
524 <emphasis remap='B'>tapedev</emphasis>
526 <emphasis remap='B'>amanda.conf</emphasis>
528 <filename>/dev/null</filename>
529 and Amanda uses that when debugging to throw all the dump images away.</para>
533 <term>WARNING: hold file <filename>file</filename> exists</term>
537 <emphasis remap='I'>file</emphasis>
538 exists and will cause
539 <emphasis remap='B'>amdump</emphasis>
540 to pause at the beginning until it is removed.</para>
544 <term>ERROR: holding disk <emphasis remap='I'>disk</emphasis>: statfs: <emphasis remap='I'>error message</emphasis></term>
547 An error was returned from the
548 <emphasis remap='I'>statfs</emphasis>
549 system call on holding disk
550 <emphasis remap='I'>disk</emphasis>
551 (maybe because it does not exist).</para>
555 <term>ERROR: holding disk <emphasis remap='I'>disk</emphasis>: not writable</term>
559 <emphasis remap='I'>disk</emphasis>,
561 probably because the caller does not have write permission
562 or a parent directory does not allow search permission.</para>
566 <term>WARNING: holding disk <emphasis remap='I'>disk</emphasis>: available space unknown <emphasis remap='I'>N</emphasis> KB requested.</term>
569 <emphasis remap='B'>Amcheck</emphasis>
570 could not determine the amount of available space on holding disk
571 <emphasis remap='I'>disk</emphasis>
572 to see if there were at least
573 <emphasis remap='I'>N</emphasis>
574 KBytes available.</para>
578 <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>
581 <emphasis remap='I'>amanda.conf</emphasis>
583 <emphasis remap='I'>R</emphasis>
584 KBytes of free space on holding disk
585 <emphasis remap='I'>disk</emphasis>,
587 <emphasis remap='I'>F</emphasis>
588 KBytes were available.
589 10 MBytes is subtracted for each backup process
591 <emphasis remap='B'>inparallel</emphasis>
592 <emphasis remap='I'>amanda.conf</emphasis>
594 to allow for unexpected overruns.</para>
595 <note><para>Even though this message is listed as a warning, it causes &amcheck; to exit with a non-zero status.</para>
601 <variablelist remap='TP'>
603 <term>Holding disk <emphasis remap='I'>disk</emphasis>: <emphasis remap='I'>N</emphasis> KB disk space available, that's plenty.</term>
606 There was sufficient free space on holding disk
607 <emphasis remap='I'>disk</emphasis>.</para>
611 <term>WARNING: holding disk <emphasis remap='I'>disk</emphasis>: only <emphasis remap='I'>F</emphasis> KB free, using nothing</term>
615 <emphasis remap='I'>disk</emphasis>
617 <emphasis remap='I'>F</emphasis>
618 KBytes of free space, but that is not enough for what is requested in
619 <emphasis remap='I'>amanda.conf</emphasis>.</para>
623 <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>
627 <emphasis remap='I'>disk</emphasis>
629 <emphasis remap='I'>F</emphasis>
630 KBytes of free space and Amanda will be using up to
631 <emphasis remap='I'>U</emphasis>
636 <term>WARNING: if a tape changer is not available, runtapes must be set to 1.</term>
640 <emphasis remap='B'>runtapes</emphasis>
641 <emphasis remap='I'>amanda.conf</emphasis>
642 option must be set to 1 if the
643 <emphasis remap='B'>tpchanger</emphasis>
644 <emphasis remap='I'>amanda.conf</emphasis>
645 option is not set.</para>
649 <term>ERROR: <emphasis remap='I'>error message</emphasis>.</term>
652 An error was detected while initializing the tape changer.</para>
656 <term>ERROR: <emphasis remap='I'>tape device</emphasis>: <emphasis remap='I'>error message</emphasis>.</term>
659 An error was detected while processing the tape label.</para>
663 <term>ERROR: cannot overwrite active tape <emphasis remap='I'>label</emphasis>.</term>
667 <emphasis remap='I'>label</emphasis>
668 is still active and cannot be used.</para>
672 <term>ERROR: label <emphasis remap='I'>label</emphasis> doesn't match labelstr <emphasis remap='I'>pattern</emphasis> .</term>
676 <emphasis remap='I'>label</emphasis>
678 <emphasis remap='B'>labelstr</emphasis>
679 <emphasis remap='I'>amanda.conf</emphasis>
684 <term>(expecting a new tape)</term>
687 The tape is not OK and a new tape was expected.</para>
691 <term>(expecting tape <emphasis remap='I'>label</emphasis> or a new tape)</term>
694 The tape is not OK and either tape
695 <emphasis remap='I'>label</emphasis>
696 or a new tape was expected.</para>
700 <term>ERROR: tape <emphasis remap='I'>label</emphasis> label ok, but is not writable.</term>
704 <emphasis remap='I'>label</emphasis>
705 is OK, but the write enable test failed.</para>
709 <term>Tape <emphasis remap='I'>label</emphasis> is writable.</term>
713 <emphasis remap='I'>label</emphasis>
714 is OK and the write enable test succeeded.</para>
718 <term>NOTE: skipping tape-writable test.</term>
721 The tape write test (see the
723 option) was not enabled.</para>
727 <term>WARNING: skipping tape test because amdump or amflush seem to be running</term>
728 <term>WARNING: if they are not, you must run amcleanup</term>
732 <command>amcheck</command>
734 <emphasis remap='B'>amdump</emphasis>
736 <emphasis remap='B'>amflush</emphasis>
737 were running because a log file or amdump file exists.
738 If they are not running, you probably need to run
739 <emphasis remap='B'>amcleanup</emphasis>
740 to clear up a previous failure.
741 Otherwise, you need to wait until they complete before running
742 <command>amcheck</command><literal>.</literal></para>
746 <term>NOTE: skipping tape checks</term>
749 The tape tests are being skipped because you used the
751 command line option.</para>
755 <term>WARNING: <emphasis remap='I'>compress</emphasis> is not executable, server-compression and indexing will not work</term>
759 <emphasis remap='I'>compress</emphasis>
761 so compression on the tape server host and creating index files will not work.</para>
765 <term>Tape <emphasis remap='I'>label</emphasis> label ok.</term>
769 <emphasis remap='I'>label</emphasis>
775 <term>Server check took <emphasis remap='I'>S</emphasis> seconds.</term>
778 Reports how long the tape server host checks took.</para>
782 <term>ERROR: <emphasis remap='I'>host</emphasis>: could not resolve hostname</term>
785 Could not look up client hostname
786 <emphasis remap='I'>host</emphasis>.</para>
790 <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>
793 Reports the number of client hosts checked,
794 how long it took and the number of errors detected.</para>
798 <term>WARNING: <emphasis remap='I'>host</emphasis>: selfcheck request timed out. Host down?</term>
801 There was no response from
802 <emphasis remap='I'>host</emphasis>
803 when trying to do the client checks.
804 The host might really be down or it might not be configured properly.</para>
808 <term>ERROR: <emphasis remap='I'>host</emphasis> NAK: <emphasis remap='I'>message</emphasis></term>
811 <emphasis remap='I'>Host</emphasis>
812 reported a negative acknowledgment error of
813 <emphasis remap='I'>message</emphasis>
814 to the status check request.</para>
818 <term>ERROR: <emphasis remap='I'>host</emphasis> NAK: [NAK parse failed]</term>
821 <emphasis remap='B'>Amcheck</emphasis>
822 could not parse the negative acknowledgment error from
823 <emphasis remap='I'>host</emphasis>.
824 There might be an Amanda version mismatch between the host running
825 <command>amcheck</command>
827 <emphasis remap='I'>host</emphasis>.</para>
831 <term>ERROR: <emphasis remap='I'>host</emphasis> [mutual-authentication failed]</term>
834 Kerberos authentication failed while contacting
835 <emphasis remap='I'>host</emphasis>.</para>
839 <term>ERROR: <emphasis remap='I'>host</emphasis>: <emphasis remap='I'>message</emphasis></term>
843 <emphasis remap='I'>message</emphasis>
844 was reported by the status check on
845 <emphasis remap='I'>host</emphasis>.</para>
851 <refsect1><title>EXIT CODE</title>
852 The exit code of <command>amcheck</command> is one of:
860 <manref name="amanda.conf" vol="5"/>
861 <manref name="amdump" vol="8"/>