xfsdump(8) - phpMan

Command: man perldoc info search(apropos)  


xfsdump(8)                           System Manager's Manual                           xfsdump(8)

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  se-
       lected  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 com-
       plete 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.

       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: filesys-
       tem, 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  op-
            erator'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 me-
            dia  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.

       -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 op-
            tion 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  destina-
            tions  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 path-
            name 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 cor-
            respond 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 re-
            stored 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.

       -D   Controls  which  directories are backed up during an incremental dump. By default un-
            changed directories are dumped if files or directories  beneath  them  have  changed.
            This  results  in  a  self-contained  dump -- if a base dump is lost, or you know the
            file(s) you wish to restore is in an incremental dump, you can restore just that dump
            without  loading  the base dump(s) first. However, this method requires a potentially
            expensive traversal through the filesystem.

            When -D is specified, unchanged directories are not dumped.  This results in a faster
            dump,  but files will end up in the xfsrestore(8) orphanage directory unless the base
            dump(s) is loaded first.

       -E   Pre-erase media.  If this option is specified, media is erased prior to use.  The op-
            erator 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  ob-
            ject 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  in-
            ventory  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  dis-
            play 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.

       -K   Generate a format 2 dump instead of the current format. This is useful  if  the  dump
            will  be  restored on a system with an older xfsrestore which does not understand the
            current dump format. Use of this option is otherwise not recommended.

       -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.  How-
            ever, this is not currently enabled on 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 de-
       vice 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 sev-
       eral operations, including dump interruption.  After the operator selects  dump  interrup-
       tion,  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 re-
       cent dump at the specified level was interrupted, the new dump does not include files  al-
       ready 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  contain-
       ing  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  filesys-
       tem.   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, ses-
            sion 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 con-
       tains 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 overwrit-
       ing the current version.  To backup the xfsdump inventory, the contents  of  /var/lib/xfs-
       dump  should be copied to another location which may then be safely dumped.  Upon restora-
       tion, 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 inven-
       tory 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  la-
       bel.  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 filesys-
       tem 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  se-
       quence.   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_quo-
       tas 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 op-
       tion 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"  at-
       tribute  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,  xfs-
       dump  will  only report the number of files it will skip.  The -v excluded_files=debug op-
       tion, however, will cause xfsdump to list the inode numbers of the  individual  files  af-
       fected.

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 termi-
       nated 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 (in-
       terrupted), 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)

Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2024-05-07 18:40 @18.218.184.214 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)
Valid XHTML 1.0!Valid CSS!