xfsdump - XFS filesystem incremental dump utility


SYNOPSIS

       xfsdump -h
       xfsdump [ options ] -f dest [ -f dest ... ] filesystem
       xfsdump [ options ] - filesystem
       xfsdump -I [ subopt=value ... ]


DESCRIPTION

       xfsdump  backs up files and their attributes in a filesys­
       tem.  The files are dumped to  storage  media,  a  regular
       file,  or  standard output.  Options allow the operator to
       have all files dumped, just files that have changed  since
       a  previous  dump,  or  just  files contained in a list of
       pathnames.

       The xfsrestore(8) utility re-populates a  filesystem  with
       the contents of the dump.

       Each  invocation  of  xfsdump  dumps  just one filesystem.
       That invocation is termed a dump session.  The  dump  ses­
       sion  splits the filesystem into one or more dump streams,
       one per destination.  The  split  is  done  in  filesystem
       inode number (ino) order, at boundaries selected to equal­
       ize the size of each stream.  Furthermore, the breakpoints
       between  streams  may be in the middle of very large files
       (at extent boundaries) if necessary to achieve  reasonable
       stream  size equalization.  Each dump stream can span sev­
       eral media objects, and a single media object can  contain
       several  dump streams.  The typical media object is a tape
       cartridge.  The media object records the  dump  stream  as
       one or more media files.  A media file is a self-contained
       partial dump.  The portion of a dump stream contained on a
       media  object can be split into several media files.  This
       minimizes the impact of media dropouts on the entire  dump
       stream, and speeds subtree restores.

       However, the current implementation in Linux only supports
       one destination and running  single  threaded.  Therefore,
       the above comments regarding multiple streams describe the
       possible future capabilities.

       xfsdump   maintains   an   online   dump   inventory    in
       /var/lib/xfsdump/inventory.   The  -I  option displays the
       inventory contents  hierarchically.   The  levels  of  the
       hierarchy are: filesystem, dump session, stream, and media
       file.

       The options to xfsdump are:

       -a   Specifies that files for  which  the  Data  Migration
            Facility  (DMF)  has  complete  offline copies (dual-
            state files) be  treated  as  if  they  were  offline

            dumped by xfsdump, resulting in a smaller dump  file.
            If  the file is later restored the file data is still
            accessible through DMF.

       -b blocksize
            Specifies the blocksize, in bytes, to be used for the
            dump.   The  same  blocksize  must  be  specified  to
            restore the tape.  If the -m option is not used, then
            -b  does not need to be specified. Instead, a default
            blocksize of 1Mb will be used.

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

       -d filesize
            Specifies  the  size,  in  megabytes,  of  dump media
            files.  xfsdump will dump data to tape in one or more
            media  files.   It will attempt to estimate the ideal
            media file size based on the tape device being  used,
            and the amount of data to be written.  The media file
            size may need to be adjusted if, for example, xfsdump
            cannot fit a media file onto a single tape.

       -e   Allow  files to be excluded from the dump.  This will
            cause xfsdump to skip those files  which  are  tagged
            with  the "SGI_XFSDUMP_SKIP_FILE" attribute.  Without
            this flag, xfsdump will  ignore  the  attribute,  and
            continue to dump affected files.

       -f dest [ -f dest ... ]
            Specifies a dump destination.  A dump destination 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  output
            option  (a  lone  -  preceding  the source filesystem
            specification) is specified.

       -l level
            Specifies a dump level of 0 to  9.   The  dump  level
            determines  the base dump to which this dump is rela­
            tive.  The base dump is the most  recent  dump  at  a
            lesser level.  A level 0 dump is absolute - all files
            are dumped.  A dump level where 1 <= level  <=  9  is
            referred  to as an incremental dump.  Only files that
            have been changed since the  base  dump  are  dumped.
            Subtree  dumps  (see  the  -s option below) cannot be
            used as the base for incremental dumps.

       -m   Use the minimal tape protocol for non-scsi tape  des­
            tinations  or  remote tape destinations which are not

            option  cannot be used without specifying a blocksize
            to be used (see -b option above).

       -o   Overwrite the tape. With this  option,  xfsdump  does
            not  read  the tape first to check the contents. This
            option may be used if xfsdump is unable to  determine
            the block size of a tape .

       -p interval
            Causes  progress  reports to be printed at the speci­
            fied interval.  interval is given  in  seconds.   The
            progress  report  indicates  how many files have been
            dumped, the total number of files to dump,  the  per­
            centage of data dumped, and the elapsed time.

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

       -s pathname [ -s pathname ... ]
            Restricts  the  dump to files contained in the speci­
            fied pathnames (subtrees).  Up to 100  pathnames  can
            be  specified.   A  pathname  must be relative to the
            mount point of the filesystem.   For  example,  if  a
            filesystem  is  mounted at /d2, the pathname argument
            for the directory /d2/users is ``users''.  A pathname
            can  be  a file or a directory; if it is a directory,
            the entire  hierarchy  of  files  and  subdirectories
            rooted  at  that  directory is dumped.  Subtree dumps
            cannot be used as the base for incremental dumps (see
            the -l option above).

       -v verbosity
       -v subsys=verbosity[,subsys=verbosity,...]
            Specifies  the level of detail used for messages dis­
            played during the course of the dump.  The  verbosity
            argument can be passed as either a string or an inte­
            ger. 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 log­
            ging across all  dump  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, inomap and excluded_files.

            For example, to dump the root filesystem with tracing


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

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

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

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

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

            To list files that will be excluded from the dump:

                 # xfsdump -e -v excluded_files=debug -f /dev/tape /

       -z size
            Specifies the maximum size, in kilobytes, of files to
            be  included in the dump.  Files over this size, will
            be excluded from the dump.  The size is  an  estimate
            based  on  the number of disk blocks actually used by
            the file, and so does not include  holes.   In  other
            words,  size  refers  to the amount of space the file
            would take in the resulting dump.  On an  interactive
            restore,  the  skipped  file  is  visible with xfsre­
            store's 'ls' and while you  can  use  the  'add'  and
            'extract' commands, nothing will be restored.

       -A   Do not dump extended file attributes.  When dumping 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 dumps containing extended file attributes cannot
            be restored with older versions of xfsrestore(8).

       -B session_id
            Specifies  the ID of the dump session upon which this
            dump session is to be based.  If this option is spec­
            ified, the -l (level) and -R (resume) options are not
            allowed.  Instead, xfsdump determines if the  current
            dump session should be incremental and/or resumed, by
            looking at the base session's level  and  interrupted
            attributes.  If the base session was interrupted, the
            current dump session is a resumption of that base  at
            the  same level.  Otherwise, the current dump session
            is an incremental dump with a level one greater  than
            that  of the base session.  This option allows incre­
            mental and resumed dumps to be based on any  previous


       -E   Pre-erase  media.  If this option is specified, media
            is erased prior to use.  The operator is prompted for
            confirmation, unless the -F option is also specified.

       -F   Don't prompt the operator.  When xfsdump encounters a
            media  object  containing  non-xfsdump  data, xfsdump
            normally asks the operator for  permission  to  over­
            write.   With this option the overwrite is performed,
            no questions asked.  When xfsdump encounters  end-of-
            media during a dump, xfsdump normally asks the opera­
            tor if another media object will be  provided.   With
            this option the dump is instead interrupted.

       -I   Displays  the  xfsdump  inventory  (no  dump  is per­
            formed).  xfsdump records each  dump  session  in  an
            online inventory in /var/lib/xfsdump/inventory.  xfs­
            dump uses this inventory to determine  the  base  for
            incremental  dumps.   It  is also useful for manually
            identifying a dump session to  be  restored.   Subop­
            tions  to  filter the inventory display are described
            later.

       -J   Inhibits the normal update of the inventory.  This is
            useful  when  the  media being dumped to will be dis­
            carded or overwritten.

       -L session_label
            Specifies a label for the dump session.   It  can  be
            any arbitrary string up to 255 characters long.

       -M label [ -M label ... ]
            Specifies  a  label  for  the first media object (for
            example, tape cartridge) written on the corresponding
            destination  during the session.  It can be any arbi­
            trary string up to  255  characters  long.   Multiple
            media  object  labels  can be specified, one for each
            destination.

       -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
            source   filesystem   cannot    be    specified    in
            options_file.

       -R   Resumes  a  previously  interrupted dump session.  If
            the most recent dump at this dump's level (-l option)

            the interrupted dump and consistent with  the  incre­
            mental level.  However, files contained in the inter­
            rupted dump that have been subsequently modified  are
            re-dumped.

       -T   Inhibits  interactive dialogue timeouts.  When the -F
            option is not specified, xfsdump prompts the operator
            for labels and media changes.  Each dialogue normally
            times out if no response is  supplied.   This  option
            prevents the timeout.

       -Y length
            Specify  I/O buffer ring length.  xfsdump uses a ring
            of output buffers to achieve maximum throughput  when
            dumping  to  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 dump stream to  be  sent  to  the
            standard  output,  where  it  can be piped to another
            utility such as  xfsrestore(8)  or  redirected  to  a
            file.  This option cannot be used with the -f option.
            The - must follow all other options and  precede  the
            filesystem specification.

       The  filesystem,  filesystem, can be specified either as a
       mount point or as a  special  device  file  (for  example,
       /dev/dsk/dks0d1s0).   The filesystem must be mounted to be
       dumped.


NOTES

   Dump Interruption
       A dump can be interrupted at any time and  later  resumed.
       To  interrupt,  type  control-C  (or  the current terminal
       interrupt character).  The operator is prompted to  select
       one  of  several  operations, including dump interruption.
       After the operator selects  dump  interruption,  the  dump
       continues  until  a  convenient break point is encountered
       (typically the end of the current file).  Very large files
       are  broken into smaller subfiles, so the wait for the end
       of the current file is brief.

   Dump Resumption
       A previously interrupted dump can be resumed by specifying
       the  -R  option.  If the most recent dump at the specified
       level was interrupted, the new dump does not include files
       already  dumped, unless they have changed since the inter­
       rupted dump.

   Media Management
       A single media object can contain many dump streams.  Con­
       versely,  a  single  dump  stream  can span multiple media

       already  containing one or more dumps, xfsdump appends the
       new dump stream after the last dump stream.   Media  files
       are  never  overwritten.   If  end-of-media is encountered
       during the course of a dump, the operator is  prompted  to
       insert a new media object into the drive.  The dump stream
       continuation is appended after the last media file on  the
       new media object.

   Inventory
       Each   dump  session  updates  an  inventory  database  in
       /var/lib/xfsdump/inventory.  xfsdump uses the inventory to
       determine the base of incremental and resumed dumps.

       This  database  can  be displayed by invoking xfsdump 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  com­
       posing 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.

       -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

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

       The  inventory  files  stored  in /var/lib/xfsdump are not
       included in the dump, even if that directory is  contained
       within  the filesystem being dumped.  Including the inven­
       tory in the dump may lead to loss or corruption  of  data,
       should  an  older version be restored overwriting the cur­
       rent version.  To backup the xfsdump inventory,  the  con­
       tents  of  /var/lib/xfsdump  should  be  copied to another
       location which may then be safely dumped.   Upon  restora­
       tion,  those  files  may be copied back into /var/lib/xfs­
       dump, overwriting whatever files may be there, or xfsinvu­
       til(1M)  may  be  used  to  selectively merge parts of the
       restored inventory back into the current inventory.  Prior
       to  version 1.1.8, xfsdump would include the /var/lib/xfs­
       dump directory in the dump.  Care should be taken  not  to
       overwrite the /var/lib/xfsdump directory when restoring an
       old dump, by either restoring the  filesystem  to  another
       location   or   by   copying   the   current  contents  of
       /var/lib/xfsdump to a safe place prior to  running  xfsre­
       store(1M).

       not create and does not reference the inventory  database.
       Thus incremental and resumed dumps are not allowed.

   Labels
       The operator can specify a label to identify the dump ses­
       sion and a label to identify a media object.  The  session
       label is placed in every media file produced in the course
       of the dump, and is recorded in the inventory.

       The media label is used to identify media objects, and  is
       independent  of the session label.  Each media file on the
       media object contains a copy of the media label.  An error
       is  returned  if the operator specifies a media label that
       does not match the media label on a media object  contain­
       ing  valid  media files.  Media labels are recorded in the
       inventory.

   UUIDs
       UUIDs (Universally Unique Identifiers) are used  in  three
       places: to identify the filesystem being dumped (using the
       filesystem UUID, see xfs(5) for more details), to identify
       the  dump session, and to identify each media object.  The
       inventory display (-I) includes all of these.

   Dump Level Usage
       The dump level mechanism provides  a  structured  form  of
       incremental  dumps.   A  dump of level level includes only
       files that have changed since the most recent  dump  at  a
       level  less  than  level.   For  example, the operator can
       establish a dump schedule that involves a full dump  every
       Friday  and a daily incremental dump containing only files
       that have changed since the previous dump.  In  this  case
       Friday's  dump would be at level 0, Saturday's at level 1,
       Sunday's at level 2, and so on, up to the Thursday dump at
       level 6.

       The  above schedule results in a very tedious restore pro­
       cedure to fully reconstruct the Thursday  version  of  the
       filesystem; xfsrestore would need to be fed all 7 dumps in
       sequence.  A compromise schedule is to use level 1 on Sat­
       urday, Monday, and Wednesday, and level 2 on Sunday, Tues­
       day, and Thursday.  The Monday and Wednesday  dumps  would
       take longer, but the worst case restore requires the accu­
       mulation of just three dumps, one each at level  0,  level
       1, and level 2.

   Quotas
       If  the  filesystem  being dumped contains quotas, xfsdump
       will use xfsdq(8) to store the quotas  in  a  file  called
       xfsdump_quotas in the root of the filesystem to be dumped.
       This file  will  then  be  included  in  the  dump.   Upon
       restoration,  xfsrq (8) can be used to reactivate the quo­
       tas  for  the  filesystem.   Note,   however,   that   the

       change the filesystem or UIDs if the filesystem  has  been
       restored to a different partition or system.

   Excluding individual files
       Occasionally it is desirable to be able to exclude partic­
       ular files or directories from the dump.   The  -s  option
       can  be  used  to limit the dump to a specified directory,
       and the -z option can be used to exclude files over a par­
       ticular  size.  Additionally, when xfsdump is run with the
       -e option individual files can be "tagged" so that xfsdump
       will  not  include  them  in  a dump.  Files are tagged by
       assigning that file an extended attribute  with  the  name
       "SGI_XFSDUMP_SKIP_FILE".    This  can  be  done  with  the
       attr(1) command:

            $ attr -s "SGI_XFSDUMP_SKIP_FILE" -V "" file

       To remove the attribute:

            $ attr -r "SGI_XFSDUMP_SKIP_FILE" file

       It should be noted that xfsdump will not check directories
       for this attribute.  It should also be noted that this use
       of extended attributes is not the same as that used by the
       chattr(1) command.

       Care should be taken to note which files have been tagged.
       Under normal operation, xfsdump will only report the  num­
       ber  of  files  it will skip.  The -v excluded_files=debug
       option, however, will cause xfsdump to list the inode num­
       bers of the individual files affected.

       If  a  file was tagged and skipped for a level 0 dump, and
       subsequently that tag was  removed,  the  file  would  not
       automatically  be  included  in  a higher level dump.  The
       file would only be included if it was modified  since  the
       last  dump.   The touch(1) command can be used on the file
       to update its modification  time  to  ensure  it  will  be
       included in later dumps.


EXAMPLES

       To  perform  a  level  0,  single  stream dump of the root
       filesystem to a locally mounted tape drive, prompting  for
       session and media labels when required:

            # xfsdump -f /dev/tape /

       To specify session and media labels explicitly:

            # xfsdump -L session_1 -M tape_0 -f /dev/tape /

       To  perform  a dump to a remote tape using the minimal rmt
       protocol and a set blocksize of 64k:


       To perform a level 0, multi-stream  dump  to  two  locally
       mounted tape drives:

            # xfsdump -L session_2 -f /dev/rmt/tps4d6v -M tape_1 \
                      -f /dev/rmt/tps5d6v -M tape_2 /

       To  perform  a  level  1 dump relative to the last level 0
       dump recorded in the inventory:

            # xfsdump -l 1 -f /dev/tape /

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

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


FILES

       /var/lib/xfsdump/inventory
                                dump inventory database


SEE ALSO

       attr(1),  rmt(8),  xfsdq(8), xfsrestore(8), xfsinvutil(8),
       xfsdq(8), xfsrq(8), attr_get(2).


DIAGNOSTICS

       The exit code is 0 on normal completion,  non-zero  if  an
       error occurs or the dump is terminated by the operator.

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

            xfsdump: Dump Status: code

       Where  code  takes  one  of  the following values: SUCCESS
       (normal completion), INTERRUPT (interrupted), QUIT  (media
       no  longer  usable),  INCOMPLETE  (dump 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  xfsdump.   However,  it  may be necessary to refine or
       expand the set of exit codes, or their  interpretation  at
       some point in the future.

       The  message ``xfsdump: WARNING: unable to open directory:
       ino N: Invalid argument'' can occur with filesystems which
       are  actively  being  modified  while  xfsdump is running.
       This can happen to either directory or regular file inodes
       -  affected files will not end up in the dump, files below
       affected directories  will  be  placed  in  the  orphanage
       directory by xfsrestore.

       xfsdump does not dump unmounted filesystems.

       The dump frequency field of /etc/fstab is not supported.

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

       xfsdump requires root privilege (except for inventory dis­
       play).

       xfsdump can only dump XFS filesystems.

       The media format used by xfsdump can only be understood by
       xfsrestore.

       xfsdump does not know how to manage CD-ROM or other remov­
       able disk drives.

       xfsdump  can  become  confused  when  doing incremental or
       resumed dumps if on the same  machine  you  dump  two  XFS
       filesystems  and both filesystems have the same filesystem
       identifier (UUID).   Since  xfsdump  uses  the  filesystem
       identifier  to identify filesystems, xfsdump maintains one
       combined set of  dump  inventories  for  both  filesystems
       instead  of  two  sets of dump inventories.  This scenario
       can happen only if dd or some  other  block-by-block  copy
       program was used to make a copy of an XFS filesystem.  See
       xfs_copy(8) and xfs(5) for more details.


Man(1) output converted with man2html