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

<3>-a<1> <2>housekeeping<1>

Each invocation of <2>xfsrestore<1> creates a directory called xfsrestorehousekeepingdir . This directory is normally created directly under the <2>dest<1> directory. The -a option allows the operator to specify an alternate directory, <2>housekeeping<1>, in which xfsrestore creates the xfsrestorehousekeeping directory. When performing a cumulative (<3>-r<1> option) restore, each successive invocation of <2>xfsrestore<1> must specify the same alternate directory.

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

Specifies the blocksize, in bytes, to be used for the restore. For other drives such as DAT or 8 mm , the same blocksize used for the xfsdump operation must be specified to restore the tape. The default block size is 1Mb.

<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>-e<1>

Prevents xfsrestore from overwriting existing files in the <2>dest<1> directory.

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

Specifies a source of the dump to be restored. This can be the pathname of a device (such as a tape drive), a regular file or a remote tape drive (see rmt(8) ). This option must be omitted if the standard input option (a lone - preceding the <2>dest<1> specification) is specified.

-i

Selects interactive operation. Once the on-media directory hierarchy has been read, an interactive dialogue is begun. The operator uses a small set of commands to peruse the directory hierarchy, selecting files and subtrees for extraction. The available commands are given below. Initially nothing is selected, except for those subtrees specified with <3>-s<1> command line options.

-m

Use the minimal tape protocol. This option cannot be used without specifying a blocksize to be used (see -b option above).

<3>-n<1> <2>file<1>

Allows xfsrestore to restore only files newer than <2>file<1>. The modification time of <2>file<1> (i.e., as displayed with the <3>ls -l<1> command) is compared to the inode modification time of each file on the source media (i.e., as displayed with the <3>ls -lc<1> command). A file is restored from media only if its inode modification time is greater than or equal to the modification time of <2>file<1>.

<3>-o<1>

Restore file and directory owner/group even if not root. When run with an effective user id of root, xfsrestore restores owner and group of each file and directory. When run with any other effective user id it does not, unless this option is specified.

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

Causes progress reports to be printed at intervals of <2>interval<1> seconds. The interval value is approximate, <2>xfsrestore<1> will delay progress reports to avoid undue processing overhead.

<3>-q<1>

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

<3>-r<1>

Selects the cumulative mode of operation.

<3>-s<1> <2>subtree<1>

Specifies a subtree to restore. Any number of -s options are allowed. The restore is constrained to the union of all subtrees specified. Each subtree is specified as a pathname relative to the restore <2>dest<1>. If a directory is specified, the directory and all files beneath that directory are restored.

-t

Displays the contents of the dump, but does not create or modify any files or directories. It may be desirable to set the verbosity level to <3>silent<1> when using this option.

<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 restore. 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 restore subsystems. The second form allows the message logging level to be controlled on a per-subsystem basis. The two forms can be combined (see the example below). The argument <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>, and <3>tree<1>.
For example, to restore the root filesystem with tracing activated for all subsystems: # xfsrestore -v trace -f /dev/tape / To enable debug-level tracing for drive and media operations: # xfsrestore -v drive=debug,media=debug -f /dev/tape / To enable tracing for all subsystems, and debug level tracing for drive operations only: # xfsrestore -v trace,drive=debug -f /dev/tape /

-w

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

-A

Do not restore extended file attributes. When restoring 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 dumping of extended file attributes is also optional.

-B

Change the ownership and permissions of the destination directory to match those of the root directory of the dump.

-D

Restore DMAPI (Data Management Application Programming Interface) event settings. If the restored filesystem will be managed within the same DMF environment as the original dump it is essential that the -D option be used. Otherwise it is not usually desirable to restore these settings.

-E

Prevents xfsrestore from overwriting newer versions of files. The inode modification time of the on-media file is compared to the inode modification time of corresponding file in the <2>dest<1> directory. The file is restored only if the on-media version is newer than the version in the <2>dest<1> directory. The inode modification time of a file can be displayed with the <3>ls -lc<1> command.

-F

Inhibit interactive operator prompts. This option inhibits xfsrestore from prompting the operator for verification of the selected dump as the restore target and from prompting for any media change.

-I

Causes the <2>xfsdump<1> inventory to be displayed (no restore is performed). Each time <2>xfsdump<1> is used, an online inventory in <2>/var/lib/xfsdump/inventory<1> is updated. This is used to determine the base for incremental dumps. It is also useful for manually identifying a dump session to be restored (see the -L and -S options). Suboptions to filter the inventory display are described later.

-J

Inhibits inventory update when on-media session inventory encountered during restore. xfsrestore opportunistically updates the online inventory when it encounters an on-media session inventory, but only if run with an effective user id of root and only if this option is not given.

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

Specifies the label of the dump session to be restored. The source media is searched for this label. It is any arbitrary string up to 255 characters long. The label of the desired dump session can be copied from the inventory display produced by the -I option.

<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 destination directory cannot be specified in <2>options_file<1>.

-Q

Force completion of an interrupted restore session. This option is required to work around one specific pathological scenario. When restoring a dump session which was interrupted due to an EOM condition and no online session inventory is available, xfsrestore cannot know when the restore of that dump session is complete. The operator is forced to interrupt the restore session. In that case, if the operator tries to subsequently apply a resumed dump (using the <3>-r<1> option), xfsrestore refuses to do so. The operator must tell xfsrestore to consider the base restore complete by using this option when applying the resumed dump.

-R

Resume a previously interrupted restore. xfsrestore can be interrupted at any time by pressing the terminal interrupt character (see stty(1) ). Use this option to resume the restore. The -a and destination options must be the same.

<3>-S<1> <2>session_id<1>

Specifies the session UUID of the dump session to be restored. The source media is searched for this UUID. The UUID of the desired dump session can be copied from the inventory display produced by the -I option.

-T

Inhibits interactive dialogue timeouts. xfsrestore prompts the operator for media changes. This dialogue normally times out if no response is supplied. This option prevents the timeout.

<3>-X<1> <2>subtree<1>

Specifies a subtree to exclude. This is the converse of the -s option. Any number of -X options are allowed. Each subtree is specified as a pathname relative to the restore <2>dest<1>. If a directory is specified, the directory and all files beneath that directory are excluded.

<3>-Y<1> <2>io_ring_length<1>

Specify I/O buffer ring length. xfsrestore uses a ring of input buffers to achieve maximum throughput when restoring from tape drives. The default ring length is 3. However, this is only supported when running multi-threaded which has not been done for Linux yet - making this option benign.

-

A lone - causes the standard input to be read as the source of the dump to be restored. Standard input can be a pipe from another utility (such as xfsdump(8) ) or a redirected file. This option cannot be used with the -f option. The - must follow all other options, and precede the <2>dest<1> specification. The dumped filesystem is restored into the <2>dest<1> directory. There is no default; the <2>dest<1> must be specified.

<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.  If the online inventory files in /var/lib/xfsdump/inventory are missing information for the current dump session, then the inventory information in the media file is automatically added to the files in /var/lib/xfsdump/inventory. If you wish to incorporate the inventory information from the media file without restoring any data, you may do so using the -t option: # xfsrestore -t -f /dev/tape This is useful to rebuild the inventory database if it is ever lost or corrupted.  The only caveat is that xfsrestore needs to read through the entire dump in order to reach the inventory media file.  This could become time consuming for dump sessions with large media files. Media Errors <2>xfsdump<1> is tolerant of media errors, but cannot do error correction. If a media error occurs in the body of a media file, the filesystem file represented at that point is lost. The bad portion of the media is skipped, and the restoration resumes at the next filesystem file after the bad portion of the media. If a media error occurs in the beginning of the media file, the entire media file is lost. For this reason, large dumps are broken into a number of reasonably sized media files. The restore resumes with the next media file. Quotas When xfsdump dumps a filesystem with quotas, it creates a file in the root of the dump called xfsdump_quotas . xfsrestore can restore this file like any other file included in the dump.  This file can be processed by the xfsrq(8) command to reactivate the quotas.  However, the xfsdump_quotas file contains information which may first require modification; specifically the filesystem name and the user ids.  If you are restoring the quotas for the same users on the same filesystem from which the dump was taken, then no modification will be necessary. However, if you are restoring the dump to a different filesystem, you will need to: - ensure the new filesystem is mounted with the quota option - modify the xfsdump_quotas file to contain the new filesystem name - ensure the uids in the xfsdump_quotas file are correct Once the quota information has been verified, xfsrq(8) can be used to apply the quota limits to the filesystem.

/var/lib/xfsdump/inventory

dump inventory database