1xfsrestore(8)               System Manager's Manual              xfsrestore(8)
2
3
4

NAME

6       xfsrestore - XFS filesystem incremental restore utility
7

SYNOPSIS

9       xfsrestore -h
10       xfsrestore [ options ] -f source [ -f source ... ] dest
11       xfsrestore [ options ] - dest
12       xfsrestore -I [ subopt=value ... ]
13

DESCRIPTION

15       xfsrestore restores filesystems from dumps produced by xfsdump(8).  Two
16       modes of operation are available: simple and cumulative.
17
18       The default is simple mode.  xfsrestore populates the specified  desti‐
19       nation directory, dest, with the files contained in the dump media.
20
21       The -r option specifies the cumulative mode.  Successive invocations of
22       xfsrestore are used to apply  a  chronologically  ordered  sequence  of
23       delta  dumps  to a base (level 0) dump.  The contents of the filesystem
24       at the time each dump was produced is  reproduced.   This  can  involve
25       adding,  deleting,  renaming, linking, and unlinking files and directo‐
26       ries.
27
28       A delta dump is defined as  either  an  incremental  dump  (xfsdump  -l
29       option  with  level  >  0)  or a resumed dump (xfsdump -R option).  The
30       deltas must be applied in the order they  were  produced.   Each  delta
31       applied  must  have  been produced with the previously applied delta as
32       its base.
33
34       xfsrestore keeps state information in the xfsrestorehousekeepingdir, to
35       inform  subsequent  invocations when used in cumulative mode, or in the
36       event a restore is interrupted.  To ensure that the  state  information
37       can  be  processed, a compatible version of xfsrestore must be used for
38       each subsequent invocation. Additionally, each invocation must run on a
39       system of the same endianness and page size.
40
41       The options to xfsrestore are:
42
43       -a housekeeping
44            Each  invocation  of  xfsrestore creates a directory called xfsre‐
45            storehousekeepingdir.  This directory is normally created directly
46            under  the  dest  directory.  The -a option allows the operator to
47            specify an alternate directory, housekeeping, in which  xfsrestore
48            creates  the xfsrestorehousekeepingdir directory.  When performing
49            a cumulative  (-r  option)  restore  or  resuming  (-R  option)  a
50            restore,  each  successive invocation must specify the same alter‐
51            nate directory.
52
53       -b blocksize
54            Specifies the blocksize, in bytes, to be  used  for  the  restore.
55            For other drives such as DAT or 8 mm , the same blocksize used for
56            the xfsdump operation must be specified to restore the tape.   The
57            default block size is 1Mb.
58
59       -c progname
60            Use  the  specified  program  to  alert  the operator when a media
61            change is required. The alert program is  typically  a  script  to
62            send a mail or flash a window to draw the operator's attention.
63
64       -e   Prevents  xfsrestore  from  overwriting existing files in the dest
65            directory.
66
67       -f source [ -f source ... ]
68            Specifies a source of the dump to be restored.  This  can  be  the
69            pathname  of  a device (such as a tape drive), a regular file or a
70            remote tape drive (see rmt(8)).  This option must  be  omitted  if
71            the  standard input option (a lone - preceding the dest specifica‐
72            tion) is specified.
73
74       -i   Selects interactive operation.  Once the on-media directory  hier‐
75            archy has been read, an interactive dialogue is begun.  The opera‐
76            tor uses a small set of commands to peruse the  directory  hierar‐
77            chy,  selecting  files and subtrees for extraction.  The available
78            commands are given below.  Initially nothing is  selected,  except
79            for those subtrees specified with -s command line options.
80
81            ls [arg]       List  the  entries  in the current directory or the
82                           specified directory, or the specified non-directory
83                           file entry.  Both the entry's original inode number
84                           and name are displayed.  Entries that are  directo‐
85                           ries  are  appended  with a `/'.  Entries that have
86                           been selected for extraction are prepended  with  a
87                           `*'.
88
89            cd [arg]       Change  the current working directory to the speci‐
90                           fied argument, or to the filesystem root  directory
91                           if no argument is specified.
92
93            pwd            Print  the pathname of the current directory, rela‐
94                           tive to the filesystem root.
95
96            add [arg]      The current directory or specified file  or  direc‐
97                           tory  within  the current directory is selected for
98                           extraction.  If a directory is specified,  then  it
99                           and all its descendents are selected.  Entries that
100                           are selected for extraction are  prepended  with  a
101                           `*' when they are listed by ls.
102
103            delete [arg]   The  current  directory or specified file or direc‐
104                           tory within the current directory is deselected for
105                           extraction.   If  a directory is specified, then it
106                           and all its descendents are deselected.   The  most
107                           expedient  way  to extract most of the files from a
108                           directory is to select the directory and then dese‐
109                           lect those files that are not needed.
110
111            extract        Ends  the  interactive  dialogue,  and  causes  all
112                           selected subtrees to be restored.
113
114            quit           xfsrestore ends the interactive dialogue and  imme‐
115                           diately  exits, even if there are files or subtrees
116                           selected for extraction.
117
118            help           List a summary of the available commands.
119
120       -m   Use the minimal tape protocol.  This option cannot be used without
121            specifying a blocksize to be used (see -b option above).
122
123       -n file
124            Allows xfsrestore to restore only files newer than file.  The mod‐
125            ification time of file (i.e., as displayed with the ls -l command)
126            is  compared  to  the  inode modification time of each file on the
127            source media (i.e., as displayed with the ls -lc command).  A file
128            is  restored  from  media  only  if its inode modification time is
129            greater than or equal to the modification time of file.
130
131       -o   Restore file and directory owner/group even if not root.  When run
132            with  an  effective user id of root, xfsrestore restores owner and
133            group of each file and directory.  When run with any other  effec‐
134            tive user id it does not, unless this option is specified.
135
136       -p interval
137            Causes  progress  reports  to  be printed at intervals of interval
138            seconds.  The interval value is approximate, xfsrestore will delay
139            progress reports to avoid undue processing overhead.
140
141       -q   Source  tape  drive  is a QIC tape.  QIC tapes only use a 512 byte
142            blocksize, for which xfsrestore must make special allowances.
143
144       -r   Selects the cumulative mode of operation. The -a  and  destination
145            options must be the same for each invocation.
146
147       -s subtree
148            Specifies  a  subtree  to  restore.   Any number of -s options are
149            allowed.  The restore is constrained to the union of all  subtrees
150            specified.   Each  subtree  is specified as a pathname relative to
151            the restore dest.  If a directory is specified, the directory  and
152            all files beneath that directory are restored.
153
154       -t   Displays  the  contents of the dump, but does not create or modify
155            any files or directories.  It may be desirable  to  set  the  ver‐
156            bosity level to silent when using this option.
157
158       -v verbosity
159       -v subsys=verbosity[,subsys=verbosity,...]
160            Specifies  the  level of detail used for messages displayed during
161            the course of the restore. The verbosity argument can be passed as
162            either a string or an integer. If passed as a string the following
163            values may be used: silent, verbose, trace, debug, or  nitty.   If
164            passed  as an integer, values from 0-5 may be used. The values 0-4
165            correspond to the strings already listed. The value 5 can be  used
166            to produce even more verbose debug output.
167
168            The first form of this option activates message logging across all
169            restore subsystems. The second form  allows  the  message  logging
170            level to be controlled on a per-subsystem basis. The two forms can
171            be combined (see the example below). The argument subsys can  take
172            one  of  the following values: general, proc, drive, media, inven‐
173            tory, and tree.
174
175            For example, to restore the root filesystem with tracing activated
176            for all subsystems:
177
178                 # xfsrestore -v trace -f /dev/tape /
179
180            To enable debug-level tracing for drive and media operations:
181
182                 # xfsrestore -v drive=debug,media=debug -f /dev/tape /
183
184            To  enable tracing for all subsystems, and debug level tracing for
185            drive operations only:
186
187                 # xfsrestore -v trace,drive=debug -f /dev/tape /
188
189
190       -A   Do  not  restore  extended  file  attributes.   When  restoring  a
191            filesystem managed within a DMF environment this option should not
192            be  used.  DMF  stores  file  migration  status  within   extended
193            attributes  associated with each file. If these attributes are not
194            preserved when the filesystem is restored, files that had been  in
195            migrated state will not be recallable by DMF. Note that dumping of
196            extended file attributes is also optional.
197
198       -B   Change the ownership and permissions of the destination  directory
199            to match those of the root directory of the dump.
200
201       -D   Restore  DMAPI (Data Management Application Programming Interface)
202            event settings. If the restored filesystem will be managed  within
203            the same DMF environment as the original dump it is essential that
204            the -D option be used. Otherwise it is not  usually  desirable  to
205            restore these settings.
206
207       -E   Prevents xfsrestore from overwriting newer versions of files.  The
208            inode modification time of the on-media file is  compared  to  the
209            inode  modification  time of corresponding file in the dest direc‐
210            tory.  The file is restored only if the on-media version is  newer
211            than  the  version  in the dest directory.  The inode modification
212            time of a file can be displayed with the ls -lc command.
213
214       -F   Inhibit interactive operator prompts.  This option inhibits xfsre‐
215            store from prompting the operator for verification of the selected
216            dump as the restore  target  and  from  prompting  for  any  media
217            change.
218
219       -I   Causes  the  xfsdump inventory to be displayed (no restore is per‐
220            formed).  Each time  xfsdump  is  used,  an  online  inventory  in
221            /var/lib/xfsdump/inventory  is updated.  This is used to determine
222            the base for incremental dumps.  It is also  useful  for  manually
223            identifying  a  dump  session  to  be  restored (see the -L and -S
224            options).   Suboptions  to  filter  the  inventory   display   are
225            described later.
226
227       -J   Inhibits  inventory update when on-media session inventory encoun‐
228            tered during restore.  xfsrestore  opportunistically  updates  the
229            online inventory when it encounters an on-media session inventory,
230            but only if run with an effective user id of root and only if this
231            option is not given.
232
233       -K   Force xfsrestore to use dump format 2 generation numbers. Normally
234            the need for this is determined automatically, but this option  is
235            required  on the first xfsrestore invocation in the rare case that
236            a cumulative restore begins with a format 3 (or  newer)  dump  and
237            will be followed by a format 2 dump.
238
239       -L session_label
240            Specifies  the  label  of  the  dump  session to be restored.  The
241            source media is searched for this  label.   It  is  any  arbitrary
242            string  up  to 255 characters long.  The label of the desired dump
243            session can be copied from the inventory display produced  by  the
244            -I option.
245
246       -O options_file
247            Insert the options contained in options_file into the beginning of
248            the command line.  The options are specified just  as  they  would
249            appear if typed into the command line.  In addition, newline char‐
250            acters (\n) can be used as whitespace.   The  options  are  placed
251            before  all options actually given on the command line, just after
252            the command name.  Only one -O option can be used.  Recursive  use
253            is  ignored.   The  destination  directory  cannot be specified in
254            options_file.
255
256       -Q   Force completion of an interrupted restore session.   This  option
257            is  required  to  work  around one specific pathological scenario.
258            When restoring a dump session which was interrupted due to an  EOM
259            condition and no online session inventory is available, xfsrestore
260            cannot know when the restore of that  dump  session  is  complete.
261            The  operator is forced to interrupt the restore session.  In that
262            case, if the operator tries to subsequently apply a  resumed  dump
263            (using  the -r option), xfsrestore refuses to do so.  The operator
264            must tell xfsrestore to consider  the  base  restore  complete  by
265            using this option when applying the resumed dump.
266
267       -R   Resume a previously interrupted restore.  xfsrestore can be inter‐
268            rupted at any time by pressing the  terminal  interrupt  character
269            (see stty(1)).  Use this option to resume the restore.  The -a and
270            destination options must be the same.
271
272       -S session_id
273            Specifies the session UUID of the dump  session  to  be  restored.
274            The  source  media  is  searched  for  this UUID.  The UUID of the
275            desired dump session can be copied from the inventory display pro‐
276            duced by the -I option.
277
278       -T   Inhibits  interactive  dialogue  timeouts.  xfsrestore prompts the
279            operator for media changes.  This dialogue normally times  out  if
280            no response is supplied.  This option prevents the timeout.
281
282       -X subtree
283            Specifies  a  subtree  to exclude.  This is the converse of the -s
284            option.  Any number of -X options are allowed.   Each  subtree  is
285            specified as a pathname relative to the restore dest.  If a direc‐
286            tory is specified, the directory and all files beneath that direc‐
287            tory are excluded.
288
289       -Y io_ring_length
290            Specify  I/O  buffer ring length.  xfsrestore uses a ring of input
291            buffers to achieve maximum throughput  when  restoring  from  tape
292            drives.   The default ring length is 3.  However, this is not cur‐
293            rently enabled on Linux yet, making this option benign.
294
295       -    A lone - causes the standard input to be read as the source of the
296            dump  to  be  restored.  Standard input can be a pipe from another
297            utility (such as xfsdump(8)) or a redirected  file.   This  option
298            cannot  be  used  with the -f option.  The - must follow all other
299            options, and precede the dest specification.
300
301       The dumped filesystem is restored into the dest directory.  There is no
302       default; the dest must be specified.
303

NOTES

305   Cumulative Restoration
306       A  base (level 0) dump and an ordered set of delta dumps can be sequen‐
307       tially restored, each on top of the previous, to reproduce the contents
308       of  the  original  filesystem  at the time the last delta was produced.
309       The operator invokes xfsrestore once for each dump.  The -r option must
310       be specified.  The dest directory must be the same for all invocations.
311       Each invocation leaves a directory named xfsrestorehousekeeping in  the
312       dest directory (however, see the -a option above).  This directory con‐
313       tains the state information that must be communicated  between  invoca‐
314       tions.   The  operator  must remove this directory after the last delta
315       has been applied.
316
317       xfsrestore also generates a  directory  named  orphanage  in  the  dest
318       directory.  xfsrestore removes this directory after completing a simple
319       restore.  However, if orphanage is not empty, it is not removed.   This
320       can happen if files present on the dump media are not referenced by any
321       of the restored directories.  The orphanage has an entry for each  such
322       file.   The  entry name is the file's original inode number, a ".", and
323       the file's generation count modulo 4096 (only the lower 12 bits of  the
324       generation count are used).
325
326       xfsrestore  does  not  remove  the orphanage after cumulative restores.
327       Like the xfsrestorehousekeeping directory, the operator must remove  it
328       after applying all delta dumps.
329
330   Media Management
331       A  dump  consists  of  one or more media files contained on one or more
332       media objects.  A media file contains all or a portion of the  filesys‐
333       tem dump.  Large filesystems are broken up into multiple media files to
334       minimize the impact of media dropouts, and to accommodate media  object
335       boundaries (end-of-media).
336
337       A  media  object is any storage medium: a tape cartridge, a remote tape
338       device (see rmt(8)), a regular file, or the standard  input  (currently
339       other  removable  media drives are not supported).  Tape cartridges can
340       contain multiple media files, which are typically separated by (in tape
341       parlance)  file  marks.   If  a  dump spans multiple media objects, the
342       restore must begin with the media object  containing  the  first  media
343       file  dumped.   The  operator is prompted when the next media object is
344       needed.
345
346       Media objects can contain more than one dump.  The operator can  select
347       the desired dump by specifying the dump label (-L option), or by speci‐
348       fying the dump UUID (-S option).  If neither is  specified,  xfsrestore
349       scans the entire media object, prompting the operator as each dump ses‐
350       sion is encountered.
351
352       The inventory display (-I option) is useful for identifying  the  media
353       objects  required.   It  is also useful for identifying a dump session.
354       The session UUID can be copied from the inventory  display  to  the  -S
355       option  argument  to  unambiguously  identify  a  dump  session  to  be
356       restored.
357
358       Dumps placed in regular files or the standard output do not span multi‐
359       ple media objects, nor do they contain multiple dumps.
360
361   Inventory
362       Each  dump  session  updates  an  inventory  database  in /var/lib/xfs‐
363       dump/inventory.  This database can be displayed by invoking  xfsrestore
364       with the -I option.  The display uses tabbed indentation to present the
365       inventory hierarchically.  The first level is filesystem.   The  second
366       level  is session.  The third level is media stream (currently only one
367       stream is supported).  The fourth level lists the media  files  sequen‐
368       tially composing the stream.
369
370       The following suboptions are available to filter the display.
371
372       -I depth=n
373            (where  n is 1, 2, or 3) limits the hierarchical depth of the dis‐
374            play. When n is 1, only the filesystem information from the inven‐
375            tory is displayed. When n is 2, only filesystem and session infor‐
376            mation are displayed. When n is 3, only  filesystem,  session  and
377            stream information are displayed.
378
379       -I level=n
380            (where  n  is  the dump level) limits the display to dumps of that
381            particular dump level.
382
383       The display may be restricted to media files contained  in  a  specific
384       media object.
385
386       -I mobjid=value
387            (where  value  is  a  media  ID) specifies the media object by its
388            media ID.
389
390       -I mobjlabel=value
391            (where value is a media label) specifies the media object  by  its
392            media label.
393
394       Similarly, the display can be restricted to a specific filesystem.
395
396       -I mnt=mount_point
397            (that  is,  [hostname:]pathname),  identifies  the  filesystem  by
398            mountpoint.  Specifying the hostname is optional, but may be  use‐
399            ful  in  a  clustered  environment where more than one host can be
400            responsible for dumping a filesystem.
401
402       -I fsid=filesystem_id
403            identifies the filesystem by filesystem ID.
404
405       -I dev=device_pathname
406            (that is, [hostname:]device_pathname) identifies the filesystem by
407            device.   As  with  the  mnt  filter,  specifying  the hostname is
408            optional.
409
410       More than one of these suboptions, separated by commas, may  be  speci‐
411       fied  at  the  same time to limit the display of the inventory to those
412       dumps of interest.  However, at most four suboptions can  be  specified
413       at once: one to constrain the display hierarchy depth, one to constrain
414       the dump level, one to constrain the media object, and one to constrain
415       the filesystem.
416
417       For  example,  -I  depth=1,mobjlabel="tape 1",mnt=host1:/test_mnt would
418       display only the filesystem information (depth=1) for those filesystems
419       that  were mounted on host1:/test_mnt at the time of the dump, and only
420       those filesystems dumped to the media object labeled "tape 1".
421
422       Dump records may be removed (pruned) from the inventory using the  xfs‐
423       invutil program.
424
425       An  additional  media  file  is  placed at the end of each dump stream.
426       This media file contains the inventory information for the current dump
427       session.   If  the online inventory files in /var/lib/xfsdump/inventory
428       are missing information for the current dump session, then  the  inven‐
429       tory  information in the media file is automatically added to the files
430       in /var/lib/xfsdump/inventory.  If you wish to incorporate  the  inven‐
431       tory  information  from  the media file without restoring any data, you
432       may do so using the -t option:
433
434            # xfsrestore -t -f /dev/tape
435
436       This is useful to rebuild the inventory database if it is ever lost  or
437       corrupted.   The  only  caveat is that xfsrestore needs to read through
438       the entire dump in order to reach the inventory media file.  This could
439       become time consuming for dump sessions with large media files.
440
441   Media Errors
442       xfsdump  is  tolerant  of media errors, but cannot do error correction.
443       If a media error occurs in the body of a  media  file,  the  filesystem
444       file  represented  at that point is lost.  The bad portion of the media
445       is skipped, and the restoration resumes at  the  next  filesystem  file
446       after the bad portion of the media.
447
448       If  a media error occurs in the beginning of the media file, the entire
449       media file is lost.  For this reason, large dumps  are  broken  into  a
450       number  of  reasonably sized media files.  The restore resumes with the
451       next media file.
452
453   Quotas
454       When xfsdump dumps a filesystem with user quotas, it creates a file  in
455       the  root  of  the  dump called xfsdump_quotas.  xfsrestore can restore
456       this file like any other file included in the dump.  This file  can  be
457       processed by the restore command of xfs_quota(8) to reactivate the quo‐
458       tas.  However, the xfsdump_quotas file contains information  which  may
459       first  require  modification;  specifically the filesystem name and the
460       user ids.  If you are restoring the quotas for the same  users  on  the
461       same  filesystem  from  which  the dump was taken, then no modification
462       will be necessary.  However, if you are restoring the dump to a differ‐
463       ent filesystem, you will need to:
464
465       - ensure the new filesystem is mounted with the quota option
466
467       - modify the xfsdump_quotas file to contain the new filesystem name
468
469       - ensure the uids in the xfsdump_quotas file are correct
470
471       Once  the  quota  information has been verified, the restore command of
472       xfs_quota (8) can be used to apply the quota limits to the filesystem.
473
474       Group and project quotas are handled in a similar fashion and  will  be
475       restored  in files called xfsdump_quotas_group and xfsdump_quotas_proj,
476       respectively.
477

EXAMPLES

479       To restore the root filesystem from a locally mounted tape:
480
481            # xfsrestore -f /dev/tape /
482
483       To restore from a remote tape, specifying the dump session id:
484
485            # xfsrestore -L session_1 -f otherhost:/dev/tape /new
486
487       To restore the contents a of a dump to another subdirectory:
488
489            # xfsrestore -f /dev/tape /newdir
490
491       To copy the contents of a filesystem to  another  directory  (see  xfs‐
492       dump(8)):
493
494            # xfsdump -J - / | xfsrestore -J - /new
495
496

FILES

498       /var/lib/xfsdump/inventory
499                                dump inventory database
500

SEE ALSO

502       rmt(8), xfsdump(8), xfsinvutil(8), xfs_quota(8), attr_set(2).
503

DIAGNOSTICS

505       The  exit  code  is  0  on  normal completion, and non-zero if an error
506       occurred or the restore was terminated by the operator.
507
508       For all verbosity levels greater than 0 (silent) the final line of  the
509       output shows the exit status of the restore. It is of the form:
510
511            xfsdump: Restore Status: code
512
513       Where  code  takes one of the following values: SUCCESS (normal comple‐
514       tion), INTERRUPT (interrupted), QUIT (media no longer  usable),  INCOM‐
515       PLETE (restore incomplete), FAULT (software error), and ERROR (resource
516       error).  Every attempt will be made to keep both  the  syntax  and  the
517       semantics  of  this  log message unchanged in future versions of xfsre‐
518       store.  However, it may be necessary to refine or  expand  the  set  of
519       exit codes, or their interpretation at some point in the future.
520

BUGS

522       Pathnames  of restored non-directory files (relative to the dest direc‐
523       tory) must be 1023 characters (MAXPATHLEN) or less.   Longer  pathnames
524       are discarded and a warning message displayed.
525
526       There is no verify option to xfsrestore.  This would allow the operator
527       to compare a filesystem dump to an existing filesystem,  without  actu‐
528       ally doing a restore.
529
530       The  interactive commands (-i option) do not understand regular expres‐
531       sions.
532
533       When the minimal rmt option is specified, xfsrestore applies it to  all
534       remote tape sources. The same blocksize (specified by the -b option) is
535       used for all these remote drives.
536
537       xfsrestore uses the alert program only when a media change is required.
538
539       Cumulative mode (-r option) requires that the  operator  invoke  xfsre‐
540       store  for the base and for each delta to be applied in sequence to the
541       base.  It would be better to allow the operator to  identify  the  last
542       delta  in  the  sequence of interest, and let xfsrestore work backwards
543       from that delta to identify and apply the  preceding  deltas  and  base
544       dump, all in one invocation.
545
546
547
548                                                                 xfsrestore(8)
Impressum