<3>xfsdump<1> -h
<3>xfsdump<1> [ options ] -f <2>dest<1> [ -f <2>dest<1> ... ] <2>filesystem<1>
<3>xfsdump<1> [ options ] - <2>filesystem<1>
<3>xfsdump<1> -I [ subopt=value ... ]

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

<3>-b<1> <2>blocksize<1>

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

<3>-c<1> <2>progname<1>

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.

<3>-d<1> <2>filesize<1>

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.

<3>-e<1>

Allow files to be excluded from the dump.  This will cause xfsdump to skip files which are tagged with the "SGI_XFLAG_NODUMP" inode flag (previously the "SGI_XFSDUMP_SKIP_FILE" extended attribute).  Without the -e flag, xfsdump will ignore the inode flags and continue to dump affected files.  The preferred flag has changed from "SGI_XFSDUMP_SKIP_FILE" (an extended attribute set within an inode) to "SGI_XFLAG_NODUMP" (an inode flag) for performance purposes.  The extended attribute "SGI_XFSDUMP_SKIP_FILE" remains supported.

<3>-f<1> <2>dest<1> [ <3>-f<1> <2>dest<1> ... ]

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.

<3>-l<1> <2>level<1>

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 <= <2>level<1> <= 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 .

<3>-p<1> <2>interval<1>

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.

<3>-q<1>

Destination tape drive is a QIC tape.  QIC tapes only use a 512 byte blocksize, for which <2>xfsdump<1> must make special allowances.

<3>-s<1> <2>pathname<1> [ <3>-s<1> <2>pathname<1> ... ]

Restricts the dump to files contained in the specified pathnames (subtrees). Up to 100 pathnames can be specified. A <2>pathname<1> must be relative to the mount point of the filesystem. For example, if a filesystem is mounted at <2>/d2<1>, the <2>pathname<1> argument for the directory <2>/d2/users<1> is ``users''. A <2>pathname<1> 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).

<3>-v<1> <2>verbosity<1>

<3>-v<1> <2>subsys<1>=<2>verbosity<1>[,<2>subsys<1>=<2>verbosity<1>,...]

Specifies the level of detail used for messages displayed during the course of the dump. The <2>verbosity<1> argument can be passed as either a string or an integer. If passed as a string the following values may be used: <3>silent<1>, <3>verbose<1>, <3>trace<1>, <3>debug<1>, or <3>nitty<1>. 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 <2>subsys<1> can take one of the following values: <3>general<1>, <3>proc<1>, <3>drive<1>, <3>media<1>, <3>inventory<1>, <3>inomap<1> and <3>excluded_files<1>.
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 /

<3>-z<1> <2>size<1>

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

<3>-B<1> <2>session_id<1>

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 <2>xfsdump<1> inventory (no dump is performed). xfsdump records each dump session in an online inventory in <2>/var/lib/xfsdump/inventory<1>. 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.

<3>-L<1> <2>session_label<1>

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

<3>-M<1> <2>label<1> [ <3>-M<1> <2>label<1> ... ]

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.

<3>-O<1> <2>options_file<1>

Insert the options contained in <2>options_file<1> 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 <3>-O<1> option can be used. Recursive use is ignored. The source filesystem cannot be specified in <2>options_file<1>.

-R

Resumes a previously interrupted dump session. If the most recent dump at this dump's level (<3>-l<1> 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.

<3>-Y<1> <2>length<1>

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, <2>filesystem<1>, can be specified either as a mount point or as a special device file (for example, <2>/dev/dsk/dks0d1s0<1>). The filesystem must be mounted to be dumped.

<3>-I depth=<1><2>n<1>

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

<3>-I level=<1><2>n<1>

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

<3>-I mobjid=<1><2>value<1>

(where value is a media ID) specifies the media object by its media ID.

<3>-I mobjlabel=<1><2>value<1>

(where value is a media label) specifies the media object by its media label. Similarly, the display can be restricted to a specific filesystem.

<3>-I mnt=<1><2>mount_point<1>

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

<3>-I fsid=<1><2>filesystem_id<1>

identifies the filesystem by filesystem ID.

<3>-I dev=<1><2>device_pathname<1>

(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 <2>host1:/test_mnt<1> 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 (<3>-I<1>) includes all of these. Dump Level Usage The dump level mechanism provides a structured form of incremental dumps. A dump of level <2>level<1> includes only files that have changed since the most recent dump at a level less than <2>level<1>. 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; <2>xfsrestore<1> 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 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 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. Excluding individual files Occasionally it is desirable to be able 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 individual files can be "tagged" so that xfsdump will not include them in a dump.  Files are tagged in one of two ways:
1) By setting an inode flag called "SGI_XFLAG_NODUMP" on the file.  This can be done with the chattr(1) command: $ chattr +d file To turn the flag off: $ chattr -d file This is the preferred method and may result in a slightly faster dump, since xfsdump doesn't need to parse an attribute stored in the inode.
2) By assigning the 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 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.

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.

/var/lib/xfsdump/inventory

dump inventory database