Imported Upstream version 3.2.0
[debian/amanda] / man / xml-source / amrecover.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='amrecover.8'>
12
13 <!-- P1 listing suppressed (not used) -->
14 <refmeta>
15 <refentrytitle>amrecover</refentrytitle>
16 <manvolnum>8</manvolnum>
17 &rmi.source;
18 &rmi.version;
19 &rmi.manual.8;
20 </refmeta>
21 <refnamediv>
22 <refname>amrecover</refname>
23 <refpurpose>Amanda index database browser</refpurpose>
24 </refnamediv>
25 <refentryinfo>
26 &author.alan;
27 &author.sgw.xml;
28 </refentryinfo>
29 <!-- body begins here -->
30 <refsynopsisdiv>
31 <cmdsynopsis>
32   <command>amrecover</command>    
33     <arg choice='opt'>-C <replaceable>config</replaceable></arg>
34     <arg choice='opt'>-s <replaceable>index-server</replaceable></arg>
35     <arg choice='opt'>-t <replaceable>tape-server</replaceable></arg>
36     <arg choice='opt'>-d <replaceable>tape-device</replaceable></arg>
37     <arg choice='opt'>-h <replaceable>hostname</replaceable></arg>
38     <arg choice='plain' rep='repeat'><group><arg choice='plain'>-o </arg><replaceable>configoption</replaceable></group></arg>
39 </cmdsynopsis>
40 </refsynopsisdiv>
41
42
43 <refsect1><title>DESCRIPTION</title>
44 <para><emphasis remap='B'>Amrecover</emphasis>
45 browses the database of Amanda index files to determine which tapes
46 contain files to recover.  Furthermore, it is able to recover files.</para>
47
48 <para>In order to restore files in place, you must invoke
49 <command>amrecover</command>
50 from the root of the backed up filesystem, or use
51 <emphasis remap='B'>lcd</emphasis>
52 to move into that directory, otherwise a directory tree that resembles 
53 the backed up filesystem will be created in the current directory.
54 See the examples below for details.</para>
55
56 <para>Amrecover will read the <emphasis remap='B'>amanda-client.conf</emphasis> file and the <replaceable>config</replaceable><emphasis remap='B'>/amanda-client.conf</emphasis> file.  If no configuration name is supplied on the command line, Amrecover will try the compiled-in default configuration ,usually <emphasis remap='B'>DailySet1</emphasis>.</para>
57
58 <para>See the
59 <manref name="amanda" vol="8"/>
60 man page for more details about Amanda.</para>
61 </refsect1>
62
63 <refsect1><title>OPTIONS</title>
64 <note><para>The Default values are those set at compile-time.
65 Use <command>amrestore</command> to recover client-encrypted or
66 client-custom-compressed tapes.</para>
67 </note>
68 <variablelist remap='TP'>
69   <varlistentry>
70   <term><emphasis remap='B'>[ -C ] config</emphasis></term>
71   <listitem>
72 <para>Amanda configuration.</para>
73   </listitem>
74   </varlistentry>
75   <varlistentry>
76   <term><option>-s index-server</option></term>
77   <listitem>
78 <para>Host that runs the index daemon.</para>
79   </listitem>
80   </varlistentry>
81   <varlistentry>
82   <term><option>-t tape-server</option></term>
83   <listitem>
84 <para>Host that runs the tape server daemon.</para>
85   </listitem>
86   </varlistentry>
87   <varlistentry>
88   <term><option>-d tape-device</option></term>
89   <listitem>
90 <para>Tape device to use on the tape server host.</para>
91   </listitem>
92   </varlistentry>
93   <varlistentry>
94   <term><option>-h hostname</option></term>
95   <listitem>
96 <para>Hostname to begin restoring; defaults to the system's hostname.</para>
97   </listitem>
98   </varlistentry>
99
100   <varlistentry>
101   <term><emphasis remap='B'>-o</emphasis> <replaceable>clientconfigoption</replaceable></term>
102   <listitem>
103 <para>See the "<emphasis remap='B'>CONFIGURATION OVERRIDE</emphasis>"
104  section in <manref name="amanda" vol="8"/>.</para>
105   </listitem>
106   </varlistentry>
107
108 </variablelist>
109 </refsect1>
110
111 <refsect1><title>COMMANDS</title>
112 <para><emphasis remap='B'>Amrecover</emphasis>
113 connects to the index server and then presents a command line prompt.
114 Usage is similar to an ftp client.
115 The GNU readline library is used to provide command line history and editing
116 if it was built in to
117 <command>amrecover</command>.</para>
118
119 <para>The purpose of browsing the database is to build up a
120 <emphasis remap='I'>restore list</emphasis>
121 of files to be extracted from the backup system.
122 The following commands are available:</para>
123 <variablelist remap='TP'>
124   <varlistentry>
125   <term><emphasis remap='B'>sethost hostname</emphasis></term>
126   <listitem>
127 <para>Specifies which host to look at backup files for (default: the local host).</para>
128   </listitem>
129   </varlistentry>
130   <varlistentry>
131   <term><emphasis remap='B'>setdate YYYY-MM-DD-HH-MM[-SS] | YYYY-MM-DD</emphasis></term>
132   <listitem>
133 <para>Set the restore time (default: now).
134 File listing commands only return information on
135 backup images for this day,
136 for the day before with the next lower dump level,
137 and so on,
138 until the most recent level 0 backup on or before
139 the specified date is encountered.</para>
140
141 <para>For example, if:</para>
142
143 <!-- .RS -->
144 <literallayout remap='.nf'>
145 1996-07-01 was a level 0 backup
146 1996-07-02 through 1996-07-05 were level 1 backups
147 1996-07-06 through 1997-07-08 were level 2 backups
148 </literallayout> <!-- .fi -->
149
150 <para>then the command <emphasis remap='B'>setdate 1997-07-08-00</emphasis>
151 would yield files from the following days:</para>
152
153 <!-- .RS -->
154 <literallayout remap='.nf'>
155 1997-07-08 (the latest level 2 backup)
156 1997-07-05 (the latest level 1 backup)
157 1997-07-01 (the latest level 0 backup)
158 </literallayout> <!-- .fi -->
159
160 <para>Only the most recent version of a file will be presented.</para>
161
162 <para>The following abbreviated date specifications are accepted:</para>
163 <!-- .RS -->
164 <variablelist remap='TP'>
165   <varlistentry>
166   <term><option>--MM-DD</option></term>
167   <listitem>
168 <para>dates in the current year</para>
169   </listitem>
170   </varlistentry>
171   <varlistentry>
172   <term><option>---DD</option></term>
173   <listitem>
174 <para>dates in the current month of the current year</para>
175   </listitem>
176   </varlistentry>
177 </variablelist>
178   </listitem>
179   </varlistentry>
180 </variablelist>
181 <!-- .RE -->
182 <variablelist remap='TP'>
183   <varlistentry>
184   <term><emphasis remap='B'>setdisk</emphasis> <emphasis remap='I'>diskname</emphasis> [<emphasis remap='I'>mountpoint</emphasis>]</term>
185   <listitem>
186 <para>Specifies which disk to consider
187 (default: the disk holding the working directory where
188 <command>amrecover</command>
189 is started).
190 It can only be set after the host is set with
191 <emphasis remap='B'>sethost</emphasis>.
192 <emphasis remap='I'>Diskname</emphasis>
193 is the device name specified in the
194 <emphasis remap='I'>amanda.conf</emphasis>
195 or &disklist;.
196 The disk must be local to the host.
197 If
198 <emphasis remap='I'>mountpoint</emphasis>
199 is not specified, all pathnames will be relative to the (unknown)
200 mount point instead of full pathnames.</para>
201   </listitem>
202   </varlistentry>
203   <varlistentry>
204   <term><emphasis remap='B'>listhost</emphasis> [<emphasis remap='I'>diskdevice</emphasis>]</term>
205   <listitem>
206 <para>List all
207 <emphasis remap='B'>host</emphasis></para>
208   </listitem>
209   </varlistentry>
210   <varlistentry>
211   <term><emphasis remap='B'>listdisk</emphasis> [<emphasis remap='I'>diskdevice</emphasis>]</term>
212   <listitem>
213 <para>List all
214 <emphasis remap='B'>diskname</emphasis></para>
215   </listitem>
216   </varlistentry>
217   <varlistentry>
218   <term><emphasis remap='B'>listproperty</emphasis></term>
219   <listitem>
220 <para>List all
221 <emphasis remap='B'>property</emphasis></para>
222   </listitem>
223   </varlistentry>
224   <varlistentry>
225   <term><emphasis remap='B'>setproperty</emphasis> [<emphasis remap='B'>append</emphasis>] [<emphasis remap='B'>priority</emphasis>] <emphasis remap='I'>name</emphasis> [<emphasis remap='I'>value</emphasis> ...]</term>
226   <listitem>
227 <para>Set the property <emphasis remap='I'>name</emphasis> to the value <emphasis remap='I'>value</emphasis>.
228 The <emphasis remap='B'>append</emphasis> keyword appends the <emphasis remap='I'>value</emphasis> to the values already set for this property.
229 Without <emphasis remap='I'>value</emphasis>, the property is unset.
230 The <emphasis remap='B'>priority</emphasis> keyword is unused, it is present for ease of copy/paste from application definition.</para>
231   </listitem>
232   </varlistentry>
233   <varlistentry>
234   <term><emphasis remap='B'>setdevice</emphasis> [[-h <emphasis remap='I'>tape-server</emphasis>] <emphasis remap='I'>tapedev</emphasis>]</term>
235   <listitem>
236 <para>Specifies the host to use as the tape server, and which of its tape devices to use.
237 If the server is omitted, the server name reverts to the configure-time default.
238 If the tape device is omitted, the default is used.</para>
239
240 <para>If you want amrecover to use your changer, the 
241 <emphasis remap='I'>tapedev</emphasis>
242 must be equal to the <amkeyword>amrecover-changer</amkeyword> setting on the server.</para>
243
244 <para>Since device names contain colons, you must always specify the hostname.</para>
245
246 <programlisting>
247 settape 192.168.0.10:file:/file1
248 </programlisting>
249 <para>You can change the tape device when amrecover ask you to load the tape:</para>
250
251 <programlisting>
252 Load tape DMP014 now
253 Continue? [Y/n/t]: t
254 Tape device: server2:/dev/nst2
255 Continue? [Y/n/t]: Y
256 Using tape /dev/nst2 from server server2.
257 </programlisting>
258
259   </listitem>
260   </varlistentry>
261 </variablelist>
262
263 <variablelist remap='TP'>
264   <varlistentry>
265   <term><emphasis remap='B'>setmode</emphasis> <emphasis remap='I'>mode</emphasis></term>
266   <listitem>
267 <para>Set the extraction mode for Samba shares.
268 If
269 <emphasis remap='I'>mode</emphasis>
270 is
271 <emphasis remap='B'>smb</emphasis>,
272 shares are sent to the Samba server
273 to be restored back onto the PC.
274 If
275 <emphasis remap='I'>mode</emphasis>
276 is
277 <emphasis remap='B'>tar</emphasis>,
278 they are extracted on the local machine the same way tar volumes are extracted.</para>
279   </listitem>
280   </varlistentry>
281   <varlistentry>
282   <term><emphasis remap='B'>mode</emphasis></term>
283   <listitem>
284 <para>Displays the extracting mode for Samba shares.</para>
285   </listitem>
286   </varlistentry>
287   <varlistentry>
288   <term><emphasis remap='B'>history</emphasis></term>
289   <listitem>
290 <para>Show the backup history of the current host and disk.
291 Dates, levels, tapes and file position on tape of each backup are displayed.</para>
292   </listitem>
293   </varlistentry>
294   <varlistentry>
295   <term><emphasis remap='B'>pwd</emphasis></term>
296   <listitem>
297 <para>Display the name of the current backup working directory.</para>
298   </listitem>
299   </varlistentry>
300   <varlistentry>
301   <term><emphasis remap='B'>cd</emphasis> <emphasis remap='I'>dir</emphasis></term>
302   <listitem>
303 <para>Change the backup working directory to
304 <emphasis remap='I'>dir.</emphasis>
305 If the mount point was specified with
306 <emphasis remap='B'>setdisk</emphasis>,
307 this can be a full pathname or it can be
308 relative to the current backup working directory.
309 If the mount point was not specified,
310 paths are relative to the mount point if they start with &quot;/&quot;,
311 otherwise they are relative to the current backup working directory.
312 The
313 <emphasis remap='I'>dir</emphasis>
314 can be a shell style wildcards.</para>
315   </listitem>
316   </varlistentry>
317   <varlistentry>
318   <term><emphasis remap='B'>cdx</emphasis> <emphasis remap='I'>dir</emphasis></term>
319   <listitem>
320 <para>Like the
321 <emphasis remap='B'>cd</emphasis>
322 command but allow regular expression.</para>
323   </listitem>
324   </varlistentry>
325   <varlistentry>
326   <term><emphasis remap='B'>lpwd</emphasis></term>
327   <listitem>
328 <para>Display the
329 <command>amrecover</command>
330 working directory.
331 Files will be restored under this directory,
332 relative to the backed up filesystem.</para>
333   </listitem>
334   </varlistentry>
335   <varlistentry>
336   <term><emphasis remap='B'>lcd</emphasis> <emphasis remap='I'>path</emphasis></term>
337   <listitem>
338 <para>Change the
339 <command>amrecover</command>
340 working directory to
341 <emphasis remap='I'>path</emphasis>.</para>
342   </listitem>
343   </varlistentry>
344   <varlistentry>
345   <term><emphasis remap='B'>ls</emphasis></term>
346   <listitem>
347 <para>List the contents of the current backup working directory.
348 See the description of the
349 <emphasis remap='B'>setdate</emphasis>
350 command for how the view of the
351 directory is built up.
352 The backup date is shown for each file.</para>
353   </listitem>
354   </varlistentry>
355   <varlistentry>
356   <term><emphasis remap='B'>add</emphasis> <emphasis remap='I'>item1 item2 ...</emphasis></term>
357   <listitem>
358 <para>Add the specified files or directories to the restore list.
359 Each item may have shell style wildcards.</para>
360   </listitem>
361   </varlistentry>
362   <varlistentry>
363   <term><emphasis remap='B'>addx</emphasis> <emphasis remap='I'>item1 item2 ...</emphasis></term>
364   <listitem>
365 <para>Add the specified files or directories to the restore list.
366 Each item may be a regular expression.</para>
367   </listitem>
368   </varlistentry>
369   <varlistentry>
370   <term><emphasis remap='B'>delete</emphasis> <emphasis remap='I'>item1 item2 ...</emphasis></term>
371   <listitem>
372 <para>Delete the specified files or directories from the restore list.
373 Each item may have shell style wildcards.</para>
374   </listitem>
375   </varlistentry>
376   <varlistentry>
377   <term><emphasis remap='B'>deletex</emphasis> <emphasis remap='I'>item1 item2 ...</emphasis></term>
378   <listitem>
379 <para>Delete the specified files or directories from the restore list.
380 Each item may be a regular expression.</para>
381   </listitem>
382   </varlistentry>
383   <varlistentry>
384   <term><emphasis remap='B'>list</emphasis> <emphasis remap='I'>file</emphasis></term>
385   <listitem>
386 <para>Display the contents of the restore list.
387 If a file name is specified,
388 the restore list is written to that file.
389 This can be used to manually extract the files from the Amanda tapes with
390 <emphasis remap='B'>amrestore</emphasis>.</para>
391   </listitem>
392   </varlistentry>
393   <varlistentry>
394   <term><emphasis remap='B'>clear</emphasis></term>
395   <listitem>
396 <para>Clear the restore list.</para>
397   </listitem>
398   </varlistentry>
399   <varlistentry>
400   <term><emphasis remap='B'>quit</emphasis></term>
401   <listitem>
402 <para>Close the connection to the index server and exit.</para>
403   </listitem>
404   </varlistentry>
405   <varlistentry>
406   <term><emphasis remap='B'>exit</emphasis></term>
407   <listitem>
408 <para>Close the connection to the index server and exit.</para>
409   </listitem>
410   </varlistentry>
411   <varlistentry>
412   <term><emphasis remap='B'>extract</emphasis></term>
413   <listitem>
414 <para>Start the extract sequence (see the examples below).  Make sure the
415 local working directory is the root of the backed up filesystem, or
416 another directory that will behave like that.  Use
417 <emphasis remap='B'>lpwd</emphasis>
418 to display the local working directory, and
419 <emphasis remap='B'>lcd</emphasis>
420 to change it.</para>
421   </listitem>
422   </varlistentry>
423   <varlistentry>
424   <term><emphasis remap='B'>help</emphasis></term>
425   <listitem>
426 <para>Display a brief list of these commands.</para>
427   </listitem>
428   </varlistentry>
429 </variablelist>
430 </refsect1>
431
432 <refsect1><title>EXAMPLES</title>
433 <para>The following shows the recovery of an old
434 <emphasis remap='I'>syslog</emphasis>
435 file.</para>
436
437 <programlisting>
438 # cd /var/log
439 # ls -l syslog.7
440 syslog.7: No such file or directory
441 # amrecover MyConfig
442 AMRECOVER Version 2.4.2. Contacting server on oops ...
443 220 oops Amanda index server (2.4.2) ready.
444 Setting restore date to today (1997-12-09)
445 200 Working date set to 1997-12-09.
446 200 Config set to MyConfig.
447 200 Dump host set to this-host.some.org.
448 $CWD '/var/log' is on disk '/var' mounted at '/var'.
449 200 Disk set to /var.
450 /var/log
451 WARNING: not on root of selected filesystem, check man-page!
452 amrecover&gt; ls
453 1997-12-09 daemon.log
454 1997-12-09 syslog
455 1997-12-08 authlog
456 1997-12-08 sysidconfig.log
457 1997-12-08 syslog.0
458 1997-12-08 syslog.1
459 1997-12-08 syslog.2
460 1997-12-08 syslog.3
461 1997-12-08 syslog.4
462 1997-12-08 syslog.5
463 1997-12-08 syslog.6
464 1997-12-08 syslog.7
465 amrecover&gt; add syslog.7
466 Added /log/syslog.7
467 amrecover&gt; lpwd
468 /var/log
469 amrecover&gt; lcd ..
470 /var
471 amrecover&gt; extract
472
473 Extracting files using tape drive /dev/nst0 on host 192.168.0.10
474
475 The following tapes are needed: DMP014
476
477 Restoring files into directory /var
478 Continue? [Y/n]: y
479
480 Load tape DMP014 now
481 Continue? [Y/n/t]: y
482 set owner/mode for '.'? [yn] n
483 amrecover&gt; quit
484 200 Good bye.
485 # ls -l syslog.7
486 total 26
487 -rw-r--r--   1 root     other      12678 Oct 14 16:36 syslog.7
488 </programlisting>
489
490 <para>If you do not want to overwrite existing files,
491 create a subdirectory to run
492 <command>amrecover</command>
493 from and then move the restored files afterward.</para>
494
495 <programlisting>
496 # cd /var
497 # (umask 077 ; mkdir .restore)
498 # cd .restore
499 # amrecover
500 AMRECOVER Version 2.4.2. Contacting server on oops ...
501 ...
502 amrecover&gt; cd log
503 /var/log
504 amrecover&gt; ls
505 ...
506 amrecover&gt; add syslog.7
507 Added /log/syslog.7
508 amrecover&gt; lpwd
509 /var/.restore
510 amrecover&gt; extract
511
512 Extracting files using tape drive /dev/nst0 on host 192.168.0.10
513 ...
514 amrecover&gt; quit
515 200 Good bye.
516 # mv -i log/syslog.7 ../log/syslog.7-restored
517 # cd ..
518 # rm -fr .restore
519 </programlisting>
520
521 <para>If you need to run
522 <emphasis remap='B'>amrestore</emphasis>
523 by hand instead of letting
524 <command>amrecover</command>
525 control it,
526 use the
527 <emphasis remap='B'>list</emphasis>
528 command after browsing to display the needed tapes.</para>
529
530 <programlisting>
531 # cd /var/log
532 # amrecover
533 AMRECOVER Version 2.4.2. Contacting server on oops ...
534 ...
535 amrecover&gt; ls
536 ...
537 amrecover&gt; add syslog syslog.6 syslog.7
538 Added /log/syslog
539 Added /log/syslog.6
540 Added /log/syslog.7
541 amrecover&gt; list
542 TAPE DMP014 LEVEL 0 DATE 1997-12-08
543         /log/syslog.7
544         /log/syslog.6
545 TAPE DMP015 LEVEL 1 DATE 1997-12-09
546         /log/syslog
547 amrecover&gt; quit 
548 </programlisting>
549
550 <para>The
551 <emphasis remap='B'>history</emphasis>
552 command shows each tape that has a backup of the
553 current disk along with the date of the backup,
554 the level,
555 the tape label
556 and the file position on the tape.
557 All active tapes are listed, not just back to
558 the most recent full dump.</para>
559
560 <para>Tape file position zero is a label.
561 The first backup image is in file position one.</para>
562
563 <programlisting>
564 # cd /var/log
565 # amrecover
566 AMRECOVER Version 2.4.2. Contacting server on oops ...
567 ...
568 amrecover&gt; history
569 200- Dump history for config &quot;MyConfig&quot; host &quot;this-host.some.org&quot; disk &quot;/var&quot;
570 201- 1997-12-09 1 DMP015 9
571 201- 1997-12-08 1 DMP014 11
572 201- 1997-12-07 0 DMP013 22
573 201- 1997-12-06 1 DMP012 16
574 201- 1997-12-05 1 DMP011 9
575 201- 1997-12-04 0 DMP010 11
576 201- 1997-12-03 1 DMP009 7
577 201- 1997-12-02 1 DMP008 7
578 201- 1997-12-01 1 DMP007 9
579 201- 1997-11-30 1 DMP006 6
580 ...
581 amrecover&gt; quit 
582 </programlisting>
583 </refsect1>
584
585 <refsect1><title>ENVIRONMENT</title>
586 <para><envar>PAGER</envar>
587 <!-- .RS -->
588 The 
589 <emphasis remap='B'>ls</emphasis>
590 and 
591 <emphasis remap='B'>list</emphasis>
592 commands will use $PAGER to display the file lists.
593 Defaults to
594 <emphasis remap='I'>more</emphasis>
595 if PAGER is not set.</para>
596 <para><envar>AMANDA_SERVER</envar>
597 If set, $AMANDA_SERVER will be used as index-server.
598 The value will take precedence over the compiled default,
599 but will be overridden by the -s switch.
600 </para>
601 <para><envar>AMANDA_TAPE_SERVER</envar>
602 If set, $AMANDA_TAPE_SERVER will be used as tape-server.
603 The value will take precedence over the compiled default,
604 but will be overridden by the -t switch.
605 </para>
606 <!-- .RE -->
607 </refsect1>
608
609 <seealso>
610 <manref name="amanda-client.conf" vol="5"/>
611 <manref name="amrestore" vol="8"/>
612 <manref name="amfetchdump" vol="8"/>
613 <manref name="readline" vol="3"/>
614 </seealso>
615
616 </refentry>