Provided by: xfsdump_3.0.6_i386 bug

NAME

       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 filesystem.  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 session 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 equalize
       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  several 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,  intended
       to  minimize  the impact of media dropouts on the entire dump stream at
       the expense of increasing the time required to complete  the  dump.  By
       default  only  one  media  file  is written unless a media file size is
       specified using the -d option.  Other  techniques,  such  as  making  a
       second  copy  of  the dump image, provide more protection against media
       failures than multiple media files will.

       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 (OFL).  This means that the file data will not
            be dumped by xfsdump, resulting in a smaller dump  file.   If  the
            file  is  later restored the file data is still accessible through
            DMF.  If both '-a option' and '-z option' are specified,  the  '-a
            option' takes precedence (see '-z option' below).

       -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 typically 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.   If  not
            specified,  xfsdump  will  dump  data to tape using a single media
            file per media object.  The specified 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 files which have the "no dump" file attribute set. See the
            "Excluding individual files" section below for details on  setting
            this  file  attribute.  Files  with  an  extended  attribute named
            "SGI_XFSDUMP_SKIP_FILE" will also be skipped, however this  method
            is  deprecated  and  xfsdump will stop checking for it in a future
            version.

       -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 relative.  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  destinations  or
            remote  tape destinations which are not scsi Linux tape drives nor
            IRIX tape drives.  This 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 specified interval.
            interval is given in seconds.  The progress report  indicates  how
            many  files  have  been dumped, the total number of files to dump,
            the percentage 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 specified pathnames
            (subtrees).  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).

       -t file
            Sets the dump time to the modification time of  file  rather  than
            using  the  current time.  xfsdump uses the dump time to determine
            what files need to be backed up during an incremental  dump.  This
            option should be used when dumping snapshots so that the dump time
            matches the time the snapshot was taken. Otherwise files  modified
            after  a  snapshot is taken may be skipped in the next incremental
            dump.

       -v verbosity
       -v subsys=verbosity[,subsys=verbosity,...]
            Specifies the level of detail used for messages  displayed  during
            the  course  of  the dump. 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
            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 activated
            for all subsystems:

                 # 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,  except  for  DMF  dual-state  files  when  '-a  option'  is
            specified (see '-a option' above).  When  specified,  '-a  option'
            takes  precedence  over '-z option'. 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 xfsrestore'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 specified, 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  incremental  and
            resumed  dumps  to be based on any previous dump, rather than just
            the most recent.

       -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 overwrite.  With this option  the  overwrite  is
            performed,  no  questions  asked.  When xfsdump encounters end-of-
            media during a dump, xfsdump normally asks the operator if another
            media  object  will  be  provided.   With  this option the dump is
            instead interrupted.

       -I   Displays the xfsdump inventory (no dump  is  performed).   xfsdump
            records   each   dump   session   in   an   online   inventory  in
            /var/lib/xfsdump/inventory.   xfsdump  uses  this   inventory   to
            determine  the  base for incremental dumps.  It is also useful for
            manually identifying a dump session to be restored.  Suboptions 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 discarded 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  arbitrary 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 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  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) was interrupted, this dump
            contains only files not in the  interrupted  dump  and  consistent
            with  the  incremental  level.   However,  files  contained in the
            interrupted 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 interrupted dump.

   Media Management
       A  single  media  object  can contain many dump streams.  Conversely, a
       single dump stream can span multiple media objects.  If a  dump  stream
       is sent to a media object 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
       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.   Its  contents  may  be merged back into the online inventory
       database at a later time using xfsrestore(1M).

       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 inventory in  the  dump  may  lead  to  loss  or
       corruption of data, should an older version be restored overwriting the
       current version.  To backup the  xfsdump  inventory,  the  contents  of
       /var/lib/xfsdump should be copied to another location which may then be
       safely dumped.  Upon restoration, those files may be copied  back  into
       /var/lib/xfsdump,   overwriting   whatever   files  may  be  there,  or
       xfsinvutil(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/xfsdump 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 xfsrestore(1M).

   Labels
       The operator can specify a label to identify the  dump  session  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  containing 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 procedure 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 Saturday, Monday, and Wednesday, and level 2 on Sunday,
       Tuesday, and Thursday.  The  Monday  and  Wednesday  dumps  would  take
       longer,  but  the  worst case restore requires the accumulation of just
       three dumps, one each at level 0, level 1, and level 2.

   Quotas
       If the filesystem being dumped contains user quotas, xfsdump  will  use
       xfs_quota(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, xfs_quota (8) can be used to reactivate
       the quotas for the filesystem.  Note, however, that the  xfsdump_quotas
       file  will  probably  require  modification to change the filesystem or
       UIDs if the filesystem has been restored to a  different  partition  or
       system.  Group  and project quotas will be handled in a similar fashion
       and saved in files called xfsdump_quotas_group and  xfsdump_quotas_proj
       , respectively.

   Excluding individual files
       It may be desirable to exclude particular 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
       particular size.  Additionally, when xfsdump is run with the -e option,
       files  that  are  tagged  with the "no dump" file attribute will not be
       included in the dump.  The chattr(1) command can be used  to  set  this
       attribute on individual files or entire subtrees.

       To tag an individual file for exclusion from the dump:

            $ chattr +d file

       To tag all files in a subtree for exclusion from the dump:

            $ chattr -R +d directory

       Note that any new files or directories created in a directory which has
       the "no dump" attribute set will automatically inherit this  attribute.
       Also  note  that  xfsdump  does not check directories for the "no dump"
       attribute.

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

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:

            # xfsdump -m -b 65536 -f otherhost:/dev/tape /

       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),    xfsrestore(8),    xfsinvutil(8),   xfs_quota(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.

BUGS

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

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

                                                                    xfsdump(8)