Provided by: xfsdump_3.1.6+nmu2_amd64 bug

NAME

       xfsrestore - XFS filesystem incremental restore utility

SYNOPSIS

       xfsrestore -h
       xfsrestore [ options ] -f source [ -f source ... ] dest
       xfsrestore [ options ] - dest
       xfsrestore -I [ subopt=value ... ]

DESCRIPTION

       xfsrestore restores filesystems from dumps produced by xfsdump(8).  Two modes of operation
       are available: simple and cumulative.

       The default is simple mode.  xfsrestore populates  the  specified  destination  directory,
       dest, with the files contained in the dump media.

       The  -r  option  specifies  the cumulative mode.  Successive invocations of xfsrestore are
       used to apply a chronologically ordered sequence of delta dumps to a base (level 0)  dump.
       The contents of the filesystem at the time each dump was produced is reproduced.  This can
       involve adding, deleting, renaming, linking, and unlinking files and directories.

       A delta dump is defined as either an incremental dump (xfsdump -l option with level  >  0)
       or  a resumed dump (xfsdump -R option).  The deltas must be applied in the order they were
       produced.  Each delta applied must have been produced with the previously applied delta as
       its base.

       xfsrestore  keeps state information in the xfsrestorehousekeepingdir, to inform subsequent
       invocations when used in cumulative mode, or in the event a restore  is  interrupted.   To
       ensure  that  the  state  information can be processed, a compatible version of xfsrestore
       must be used for each subsequent invocation. Additionally, each invocation must run  on  a
       system of the same endianness and page size.

       The options to xfsrestore are:

       -a housekeeping
            Each  invocation  of xfsrestore creates a directory called xfsrestorehousekeepingdir.
            This directory is normally created directly under the dest directory.  The -a  option
            allows  the  operator  to  specify  an  alternate  directory,  housekeeping, in which
            xfsrestore  creates  the  xfsrestorehousekeepingdir  directory.   When  performing  a
            cumulative  (-r  option)  restore  or resuming (-R option) a restore, each successive
            invocation must specify the same alternate directory.

       -b blocksize
            Specifies the blocksize, in bytes, to be used for the restore.  For other drives such
            as  DAT or 8 mm , the same blocksize used for the xfsdump operation must be specified
            to restore the tape.  The default block size is 1Mb.

       -c progname
            Use the specified program to alert the operator when a media change is required.  The
            alert  program  is  typically  a  script to send a mail or flash a window to draw the
            operator's attention.

       -e   Prevents xfsrestore from overwriting existing files in the dest directory.

       -f source [ -f source ... ]
            Specifies a source of the dump to be restored.  This can be the pathname of a  device
            (such  as  a  tape  drive), a regular file or a remote tape drive (see rmt(8)).  This
            option must be omitted if the standard input option (a  lone  -  preceding  the  dest
            specification) is specified.

       -i   Selects  interactive operation.  Once the on-media directory hierarchy has been read,
            an interactive dialogue is begun.  The operator uses  a  small  set  of  commands  to
            peruse  the  directory  hierarchy,  selecting files and subtrees for extraction.  The
            available commands are given below.  Initially nothing is selected, except for  those
            subtrees specified with -s command line options.

            ls [arg]       List  the entries in the current directory or the specified directory,
                           or the specified non-directory file entry.  Both the entry's  original
                           inode number and name are displayed.  Entries that are directories are
                           appended with a `/'.  Entries that have been selected  for  extraction
                           are prepended with a `*'.

            cd [arg]       Change  the current working directory to the specified argument, or to
                           the filesystem root directory if no argument is specified.

            pwd            Print  the  pathname  of  the  current  directory,  relative  to   the
                           filesystem root.

            add [arg]      The  current  directory  or  specified  file  or  directory within the
                           current directory is selected  for  extraction.   If  a  directory  is
                           specified, then it and all its descendents are selected.  Entries that
                           are selected for extraction are prepended with a  `*'  when  they  are
                           listed by ls.

            delete [arg]   The  current  directory  or  specified  file  or  directory within the
                           current directory is deselected for extraction.   If  a  directory  is
                           specified,  then  it and all its descendents are deselected.  The most
                           expedient way to extract most of the files  from  a  directory  is  to
                           select  the  directory  and  then  deselect  those  files that are not
                           needed.

            extract        Ends the interactive dialogue, and causes all selected subtrees to  be
                           restored.

            quit           xfsrestore  ends  the interactive dialogue and immediately exits, even
                           if there are files or subtrees selected for extraction.

            help           List a summary of the available commands.

       -m   Use the minimal tape protocol.  This option  cannot  be  used  without  specifying  a
            blocksize to be used (see -b option above).

       -n file
            Allows  xfsrestore  to  restore only files newer than file.  The modification time of
            file (i.e.,  as  displayed  with  the  ls  -l  command)  is  compared  to  the  inode
            modification  time  of  each file on the source media (i.e., as displayed with the ls
            -lc command).  A file is restored from media only if its inode modification  time  is
            greater than or equal to the modification time of file.

       -o   Restore  file and directory owner/group even if not root.  When run with an effective
            user id of root, xfsrestore restores owner and group  of  each  file  and  directory.
            When  run  with  any  other  effective  user  id  it  does not, unless this option is
            specified.

       -p interval
            Causes progress reports to be printed at intervals of interval seconds.  The interval
            value  is  approximate,  xfsrestore  will  delay  progress  reports  to  avoid  undue
            processing overhead.

       -q   Source tape drive is a QIC tape.  QIC tapes only use a 512 byte blocksize, for  which
            xfsrestore must make special allowances.

       -r   Selects  the cumulative mode of operation. The -a and destination options must be the
            same for each invocation.

       -s subtree
            Specifies a subtree to restore.  Any number of -s options are allowed.   The  restore
            is  constrained to the union of all subtrees specified.  Each subtree is specified as
            a pathname relative to the restore dest.  If a directory is specified, the  directory
            and all files beneath that directory are restored.

       -t   Displays  the  contents  of  the  dump,  but  does  not create or modify any files or
            directories.  It may be desirable to set the verbosity level  to  silent  when  using
            this option.

       -v verbosity
       -v subsys=verbosity[,subsys=verbosity,...]
            Specifies  the  level  of detail used for messages displayed during the course of the
            restore. The verbosity argument can be passed as either a string or  an  integer.  If
            passed  as  a string the following values may be used: silent, verbose, trace, debug,
            or nitty.  If passed as an integer, values from 0-5  may  be  used.  The  values  0-4
            correspond  to  the  strings  already listed. The value 5 can be used to produce even
            more verbose debug output.

            The  first  form  of  this  option  activates  message  logging  across  all  restore
            subsystems.  The  second  form allows the message logging level to be controlled on a
            per-subsystem basis. The two forms can be  combined  (see  the  example  below).  The
            argument  subsys  can  take one of the following values: general, proc, drive, media,
            inventory, and tree.

            For  example,  to  restore  the  root  filesystem  with  tracing  activated  for  all
            subsystems:

                 # xfsrestore -v trace -f /dev/tape /

            To enable debug-level tracing for drive and media operations:

                 # xfsrestore -v drive=debug,media=debug -f /dev/tape /

            To  enable  tracing  for all subsystems, and debug level tracing for drive operations
            only:

                 # xfsrestore -v trace,drive=debug -f /dev/tape /

       -A   Do not restore extended file attributes.  When restoring a filesystem managed  within
            a  DMF  environment  this option should not be used. DMF stores file migration status
            within extended attributes associated with each file. If  these  attributes  are  not
            preserved when the filesystem is restored, files that had been in migrated state will
            not be recallable by DMF. Note that dumping  of  extended  file  attributes  is  also
            optional.

       -B   Change  the  ownership and permissions of the destination directory to match those of
            the root directory of the dump.

       -D   Restore DMAPI (Data Management Application Programming Interface) event settings.  If
            the  restored  filesystem  will  be  managed  within  the same DMF environment as the
            original dump it is essential that the -D option be used. Otherwise it is not usually
            desirable to restore these settings.

       -E   Prevents xfsrestore from overwriting newer versions of files.  The inode modification
            time of the on-media file is compared to the inode modification time of corresponding
            file  in  the  dest  directory.  The file is restored only if the on-media version is
            newer than the version in the dest directory.  The inode modification time of a  file
            can be displayed with the ls -lc command.

       -F   Inhibit interactive operator prompts.  This option inhibits xfsrestore from prompting
            the operator for verification of the selected dump as the  restore  target  and  from
            prompting for any media change.

       -I   Causes  the  xfsdump  inventory to be displayed (no restore is performed).  Each time
            xfsdump is used, an online inventory in /var/lib/xfsdump/inventory is updated.   This
            is  used to determine the base for incremental dumps.  It is also useful for manually
            identifying a dump session to be restored (see the -L and -S options).  Suboptions to
            filter the inventory display are described later.

       -J   Inhibits inventory update when on-media session inventory encountered during restore.
            xfsrestore opportunistically updates the online inventory when it encounters  an  on-
            media  session  inventory, but only if run with an effective user id of root and only
            if this option is not given.

       -K   Force xfsrestore to use dump format 2 generation numbers. Normally the need for  this
            is  determined  automatically,  but  this  option is required on the first xfsrestore
            invocation in the rare case that a cumulative restore begins  with  a  format  3  (or
            newer) dump and will be followed by a format 2 dump.

       -L session_label
            Specifies the label of the dump session to be restored.  The source media is searched
            for this label.  It is any arbitrary string up to 255 characters long.  The label  of
            the  desired dump session can be copied from the inventory display produced by the -I
            option.

       -O options_file
            Insert the options contained in options_file into the beginning of the command  line.
            The  options  are specified just as they would appear if typed into the command line.
            In addition, newline characters (\n) can be used  as  whitespace.   The  options  are
            placed  before all options actually given on the command line, just after the command
            name.  Only one -O option can be used.  Recursive use is  ignored.   The  destination
            directory cannot be specified in options_file.

       -Q   Force  completion of an interrupted restore session.  This option is required to work
            around one specific pathological scenario.  When restoring a dump session  which  was
            interrupted  due  to  an  EOM condition and no online session inventory is available,
            xfsrestore cannot know when the restore  of  that  dump  session  is  complete.   The
            operator  is  forced to interrupt the restore session.  In that case, if the operator
            tries to subsequently apply a resumed dump (using the -r option), xfsrestore  refuses
            to do so.  The operator must tell xfsrestore to consider the base restore complete by
            using this option when applying the resumed dump.

       -R   Resume a previously interrupted restore.  xfsrestore can be interrupted at  any  time
            by  pressing  the  terminal  interrupt  character  (see stty(1)).  Use this option to
            resume the restore.  The -a and destination options must be the same.

       -S session_id
            Specifies the session UUID of the dump session to be restored.  The source  media  is
            searched  for this UUID.  The UUID of the desired dump session can be copied from the
            inventory display produced by the -I option.

       -T   Inhibits interactive dialogue timeouts.  xfsrestore prompts the  operator  for  media
            changes.   This  dialogue normally times out if no response is supplied.  This option
            prevents the timeout.

       -X subtree
            Specifies a subtree to exclude.  This is the converse of the -s option.   Any  number
            of  -X  options are allowed.  Each subtree is specified as a pathname relative to the
            restore dest.  If a directory is specified, the directory and all files beneath  that
            directory are excluded.

       -Y io_ring_length
            Specify  I/O  buffer ring length.  xfsrestore uses a ring of input buffers to achieve
            maximum throughput when restoring from tape drives.  The default ring  length  is  3.
            However, this is not currently enabled on Linux yet, making this option benign.

       -    A  lone  -  causes  the  standard  input  to  be read as the source of the dump to be
            restored.  Standard input can be a pipe from another utility (such as xfsdump(8))  or
            a redirected file.  This option cannot be used with the -f option.  The - must follow
            all other options, and precede the dest specification.

       The dumped filesystem is restored into the dest directory.  There is no default; the  dest
       must be specified.

NOTES

   Cumulative Restoration
       A base (level 0) dump and an ordered set of delta dumps can be sequentially restored, each
       on top of the previous, to reproduce the contents of the original filesystem at  the  time
       the  last delta was produced.  The operator invokes xfsrestore once for each dump.  The -r
       option must be specified.  The dest directory must be the same for all invocations.   Each
       invocation leaves a directory named xfsrestorehousekeeping in the dest directory (however,
       see the -a option above).  This directory contains the  state  information  that  must  be
       communicated  between invocations.  The operator must remove this directory after the last
       delta has been applied.

       xfsrestore also generates a directory named orphanage in the dest  directory.   xfsrestore
       removes  this  directory  after completing a simple restore.  However, if orphanage is not
       empty, it is not removed.  This can happen if files present on  the  dump  media  are  not
       referenced  by  any of the restored directories.  The orphanage has an entry for each such
       file.  The entry name is  the  file's  original  inode  number,  a  ".",  and  the  file's
       generation count modulo 4096 (only the lower 12 bits of the generation count are used).

       xfsrestore   does   not   remove  the  orphanage  after  cumulative  restores.   Like  the
       xfsrestorehousekeeping directory, the operator must remove it  after  applying  all  delta
       dumps.

   Media Management
       A  dump  consists  of  one  or more media files contained on one or more media objects.  A
       media file contains all or a portion of the filesystem dump.  Large filesystems are broken
       up  into multiple media files to minimize the impact of media dropouts, and to accommodate
       media object boundaries (end-of-media).

       A media object is any storage medium: a tape cartridge, a remote tape device (see rmt(8)),
       a  regular  file,  or  the  standard input (currently other removable media drives are not
       supported).  Tape cartridges  can  contain  multiple  media  files,  which  are  typically
       separated  by  (in tape parlance) file marks.  If a dump spans multiple media objects, the
       restore must begin with the media object containing the  first  media  file  dumped.   The
       operator is prompted when the next media object is needed.

       Media objects can contain more than one dump.  The operator can select the desired dump by
       specifying the dump label (-L option), or by specifying the dump  UUID  (-S  option).   If
       neither  is specified, xfsrestore scans the entire media object, prompting the operator as
       each dump session is encountered.

       The inventory display (-I option) is useful for identifying the  media  objects  required.
       It is also useful for identifying a dump session.  The session UUID can be copied from the
       inventory display to the -S option argument to unambiguously identify a dump session to be
       restored.

       Dumps  placed  in regular files or the standard output do not span multiple media objects,
       nor do they contain multiple dumps.

   Inventory
       Each dump session updates  an  inventory  database  in  /var/lib/xfsdump/inventory.   This
       database  can  be  displayed  by invoking xfsrestore with the -I option.  The display uses
       tabbed  indentation  to  present  the  inventory  hierarchically.   The  first  level   is
       filesystem.  The second level is session.  The third level is media stream (currently only
       one stream is supported).  The fourth level lists the media files  sequentially  composing
       the stream.

       The following suboptions are available to filter the display.

       -I depth=n
            (where  n  is  1, 2, or 3) limits the hierarchical depth of the display. When n is 1,
            only the filesystem information from the inventory is displayed. When n  is  2,  only
            filesystem  and  session  information  are  displayed.  When n is 3, only filesystem,
            session and stream information are displayed.

       -I level=n
            (where n is the dump level) limits the display  to  dumps  of  that  particular  dump
            level.

       The display may be restricted to media files contained in a specific media object.

       -I mobjid=value
            (where value is a media ID) specifies the media object by its media ID.

       -I mobjlabel=value
            (where value is a media label) specifies the media object by its media label.

       Similarly, the display can be restricted to a specific filesystem.

       -I mnt=mount_point
            (that  is, [hostname:]pathname), identifies the filesystem by mountpoint.  Specifying
            the hostname is optional, but may be useful in a  clustered  environment  where  more
            than one host can be responsible for dumping a filesystem.

       -I fsid=filesystem_id
            identifies the filesystem by filesystem ID.

       -I dev=device_pathname
            (that  is,  [hostname:]device_pathname) identifies the filesystem by device.  As with
            the mnt filter, specifying the hostname is optional.

       More than one of these suboptions, separated by commas, may be specified at the same  time
       to  limit  the display of the inventory to those dumps of interest.  However, at most four
       suboptions can be specified at once: one to constrain the display hierarchy depth, one  to
       constrain  the  dump  level,  one  to constrain the media object, and one to constrain the
       filesystem.

       For example, -I depth=1,mobjlabel="tape  1",mnt=host1:/test_mnt  would  display  only  the
       filesystem   information   (depth=1)   for   those   filesystems   that  were  mounted  on
       host1:/test_mnt at the time of the dump, and only those filesystems dumped  to  the  media
       object labeled "tape 1".

       Dump records may be removed (pruned) from the inventory using the xfsinvutil program.

       An  additional  media  file  is  placed  at  the end of each dump stream.  This media file
       contains the inventory information for the current dump session.  If the online  inventory
       files  in /var/lib/xfsdump/inventory are missing information for the current dump session,
       then the inventory information in the media file is automatically added to  the  files  in
       /var/lib/xfsdump/inventory.  If you wish to incorporate the inventory information from the
       media file without restoring any data, you may do so using the -t option:

            # xfsrestore -t -f /dev/tape

       This is useful to rebuild the inventory database if it is ever  lost  or  corrupted.   The
       only caveat is that xfsrestore needs to read through the entire dump in order to reach the
       inventory media file.  This could become time consuming for dump sessions with large media
       files.

   Media Errors
       xfsdump  is  tolerant  of  media errors, but cannot do error correction.  If a media error
       occurs in the body of a media file, the filesystem file represented at that point is lost.
       The  bad  portion  of  the  media  is  skipped,  and  the  restoration resumes at the next
       filesystem file after the bad portion of the media.

       If a media error occurs in the beginning of the media file, the entire media file is lost.
       For  this  reason,  large  dumps are broken into a number of reasonably sized media files.
       The restore resumes with the next media file.

   Quotas
       When xfsdump dumps a filesystem with user quotas, it creates a file in  the  root  of  the
       dump called xfsdump_quotas.  xfsrestore can restore this file like any other file included
       in the dump.  This file can be  processed  by  the  restore  command  of  xfs_quota(8)  to
       reactivate  the  quotas.   However, the xfsdump_quotas file contains information which may
       first require modification; specifically the filesystem name and the user ids.  If you are
       restoring  the  quotas  for  the same users on the same filesystem from which the dump was
       taken, then no modification will be necessary.  However, if you are restoring the dump  to
       a different filesystem, you will need to:

       - ensure the new filesystem is mounted with the quota option

       - modify the xfsdump_quotas file to contain the new filesystem name

       - ensure the uids in the xfsdump_quotas file are correct

       Once  the quota information has been verified, the restore command of xfs_quota (8) can be
       used to apply the quota limits to the filesystem.

       Group and project quotas are handled in a similar fashion and will be  restored  in  files
       called xfsdump_quotas_group and xfsdump_quotas_proj, respectively.

EXAMPLES

       To restore the root filesystem from a locally mounted tape:

            # xfsrestore -f /dev/tape /

       To restore from a remote tape, specifying the dump session id:

            # xfsrestore -L session_1 -f otherhost:/dev/tape /new

       To restore the contents a of a dump to another subdirectory:

            # xfsrestore -f /dev/tape /newdir

       To copy the contents of a filesystem to another directory (see xfsdump(8)):

            # xfsdump -J - / | xfsrestore -J - /new

FILES

       /var/lib/xfsdump/inventory
                                dump inventory database

SEE ALSO

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

DIAGNOSTICS

       The  exit code is 0 on normal completion, and non-zero if an error occurred or the restore
       was terminated by the operator.

       For all verbosity levels greater than 0 (silent) the final line of the  output  shows  the
       exit status of the restore. It is of the form:

            xfsdump: Restore Status: code

       Where  code  takes  one  of  the  following values: SUCCESS (normal completion), INTERRUPT
       (interrupted), QUIT (media no  longer  usable),  INCOMPLETE  (restore  incomplete),  FAULT
       (software error), and ERROR (resource error).  Every attempt will be made to keep both the
       syntax and the semantics of this log message unchanged in future versions  of  xfsrestore.
       However,  it  may  be  necessary  to  refine  or  expand  the  set of exit codes, or their
       interpretation at some point in the future.

BUGS

       Pathnames of restored non-directory files (relative to the dest directory)  must  be  1023
       characters  (MAXPATHLEN)  or  less.   Longer pathnames are discarded and a warning message
       displayed.

       There is no verify option to xfsrestore.  This would  allow  the  operator  to  compare  a
       filesystem dump to an existing filesystem, without actually doing a restore.

       The interactive commands (-i option) do not understand regular expressions.

       When  the  minimal  rmt  option  is  specified,  xfsrestore  applies it to all remote tape
       sources. The same blocksize (specified by the -b option) is  used  for  all  these  remote
       drives.

       xfsrestore uses the alert program only when a media change is required.

       Cumulative  mode (-r option) requires that the operator invoke xfsrestore for the base and
       for each delta to be applied in sequence to the base.  It would be  better  to  allow  the
       operator  to  identify the last delta in the sequence of interest, and let xfsrestore work
       backwards from that delta to identify and apply the preceding deltas and base dump, all in
       one invocation.

                                                                                    xfsrestore(8)