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 con­
       tained in the dump media.

       The  -r  option specifies the cumulative mode.  Successive
       invocations of xfsrestore are used to apply a  chronologi­
       cally  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 (xfs­
       dump  -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.

       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 xfsre­
            store creates the  xfsrestorehousekeeping  directory.
            When  performing  a  cumulative  (-r option) restore,
            each successive invocation of xfsrestore 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

            ically  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 specifica­
            tion) 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 direc­
                           tory 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 argu­
                           ment 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 extrac­
                           tion are prepended  with  a  `*'  when
                           they are listed by ls.

            delete [arg]   The  current  directory  or  specified
                           file or directory within  the  current

                           tion.  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  dia­
                           logue  and  immediately exits, even if
                           there are files or  subtrees  selected
                           for extraction.

            help           List  a  summary of the available com­
                           mands.

       -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 dis­
            played 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 modi­
            fication time is greater than or equal to the modifi­
            cation 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.

            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 cre­
            ate 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  dis­
            played  during  the  course  of the restore. The ver­
            bosity argument can be passed as either a  string  or
            an  integer. If passed as a string the following val­
            ues 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  log­
            ging  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 /

       -w   This option is not normally recommended.  This option
            will force xfsrestore to use small mmap regions which
            will  reduce  the likelihood of an mmap failure. How­
            ever, this will slow down xfsrestore during directory
            processing when there are over 1 million inodes.

            restoring a filesystem managed within a DMF  environ­
            ment  this option should not be used. DMF stores file
            migration status within extended  attributes  associ­
            ated with each file. If these attributes are not pre­
            served 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 destina­
            tion directory to match those of the  root  directory
            of the dump.

       -D   Restore  DMAPI  (Data Management Application Program­
            ming  Interface)  event  settings.  If  the  restored
            filesystem  will be managed within the same DMF envi­
            ronment as the original dump it is essential that the
            -D option be used. Otherwise it is not usually desir­
            able 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 tar­
            get 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.

       -L session_label
            Specifies  the  label  of  the  dump  session  to  be
            restored.   The  source  media  is  searched for this

            ters 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 spec­
            ified  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 termi­
            nal 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 dia­
            logue 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

            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 only supported when
            running multi-threaded which has not  been  done  for
            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 xfs­
            dump(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

       of  media dropouts, and to accommodate media object bound­
       aries (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 con­
       taining  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  opera­
       tor  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 identify­
       ing 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  argu­
       ment  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 mul­
       tiple dumps.

   Inventory
       Each  dump  session  updates  an  inventory  database   in
       /var/lib/xfsdump/inventory.   This  database  can  be dis­
       played by invoking xfsrestore with  the  -I  option.   The
       display  uses  tabbed indentation to present the inventory
       hierarchically.  The first level is filesystem.  The  sec­
       ond  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  dis­
       play.

       -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.

            (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 environ­
            ment 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, speci­
            fying 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 con­
       strain  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  informa­
       tion  for  the  current  dump  session.  This is currently


   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 quotas, it creates a
       file in the root of the dump called xfsdump_quotas.   xfs­
       restore can restore this file like any other file included
       in the dump.  This file can be processed by  the  xfsrq(8)
       command  to  reactivate  the  quotas.   However,  the xfs­
       dump_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,  xfsrq  (8)
       can be used to apply the quota limits to the filesystem.


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 subdirec­
       tory:


       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), xfsrq(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  mes­
       sage 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.

       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.


Man(1) output converted with man2html