NAME

xfsrestore - XFS filesystem incremental restore utility

SYNOPSIS

xfsrestore [ -a housekeeping ] [ -b blocksize ]

[ -c media_change_alert_program ] [ ­e ]

[ -f source ... ] [ -i ] [ -m force usage of minimal tape strategy ]

[ -n file ] [ -o ] [ -p report_interval ] [ -r ]

[ -s subtree ... ] [ -t ] [ -v verbosity ] [ -A ] [ -D ]

[ -E ] [ -F ] [ -I [ subopt=value ... ] ] [ -J ] [ -L session_label ]

[ -O options_file ] [ -Q ] [ -R ] [ -S session_id ] [ -T ]

[ -Y io_ring_length ] [ - ] destination

DESCRIPTION

xfsrestore restores filesystems from dumps produced by xfsdump(8). Two modes of operation are available: simple and cumulative.

The default is simple mode. xfsrestore populates the specified destination directory, destination, with the files contained in the dump media.

The -r option specifies the cumulative mode. Successive invocations of xfsrestore are used to apply a chronologically ordered sequence of delta dumps to a base (level 0) dump. The contents of the filesystem at the time each dump was produced is reproduced. This can involve adding, deleting, renaming, linking, and unlinking files and directories.

A delta dump is defined as either an incremental dump (xfsdump -l option with level > 0) or a resumed dump (xfsdump -R option). The deltas must be applied in the order they were produced. Each delta applied must have been produced with the previously applied delta as its base.

-a housekeeping

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

-b blocksize

Specifies the blocksize 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.

-c media_change_alert_program

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.

-e Prevents xfsrestore from overwriting existing files in the destination directory.

-f source

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 destination 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 -s command line options. ls [arg] List the entries in the current directory or the specified directory, or the specified non­directory file entry. Both the entry's original inode number and name are displayed. Entries that are directories are appended with a `/'. Entries that have been selected for extraction are prepended with a `*'. cd [arg] Change the current working directory to the specified argument, or to the filesystem root directory if no argument is specified.

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

-n file

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

-o

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.

-p report_interval

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

-r Selects the cumulative mode of operation.

-s subtree

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 destination. 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 silent when using this option.

-v verbosity_level

Specifies the level of detail of the messages displayed during the course of the restore. The argument can be silent, verbose, or trace. The default is verbose.

	-A	Do not restore extended file attributes. If this option is not specified, extended file attributes are restored. Note that dumping of extended file attributes is also optional.
	-D	Restore DMAPI (Data Management Application Programming Interface) event settings. xfsdump backs backs up these settings, but it is usually not desirable to restore them. However, the current implementation in Linux does not yet support the -D option.
	-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 destination directory. The file is restored only if the on­media version is newer than the version in the destination directory. The inode modification time of a file can be displayed with the ls ­lc 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.

-L session_label

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.

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

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

-S session_id

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. changes. This dialogue normally times prevents the timeout.

xfsrestore prompts the operator for media out if no response is supplied. This option

-X subtree

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 destination. If a directory is specified, the directory and all files beneath that directory are excluded.

-Y io_ring_length

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

The dumped filesystem is restored into the destination directory. There is no default; the destination must be specified.

NOTES

Cumulative Restoration

A base (level 0) dump and an ordered set of delta dumps can be sequentially restored, each on top of the previous, to reproduce the contents of the original filesystem at the time the last delta was produced. The operator invokes xfsrestore once for each dump. The -r option must be specified. The destination directory must be the same for all invocations. Each invocation leaves a directory named xfsrestorehousekeeping in the destination directory (however, see the -a option above). This directory contains the state information that must be communicated between invocations. The operator must remove this directory after the last delta has been applied.

xfsrestore also generates a directory named orphanage in the destination directory. xfsrestore removes this directory after completing a simple restore. However, if orphanage is not empty, it is not removed. This can happen if files present on the dump media are not referenced by any of the restored directories. The orphanage has an entry for each such file. The entry name is the file's original inode number, a ".", and the file's generation count modulo 4096 (only the lower 12 bits of the generation count are used).

xfsrestore does not remove the orphanage after cumulative restores. Like the xfsrestorehousekeeping directory, the operator must remove it after applying all delta dumps.

Media Management

A dump consists of one or more media files contained on one or more media objects. A media file contains all or a portion of the filesystem dump. Large filesystems are broken up into multiple media files to minimize the impact of media dropouts, and to accommodate media object boundaries (end­of­media).

A media object is any storage medium: a tape cartridge, a remote tape device (see rmt(8)), a regular file, or the standard input (currently other removable media drives are not supported). Tape cartridges can contain multiple media files, which are typically separated by (in tape parlance) file marks. If a dump spans multiple media objects, the restore must begin with the media object containing the first media file dumped. The operator is prompted when the next media object is needed.

Media objects can contain more than one dump. The operator can select the desired dump by specifying the dump label (-L option), or by specifying the dump UUID (-S option). If neither is specified, xfsrestore scans the entire media object, prompting the operator as each dump session is encountered.

The inventory display (-I option) is useful for identifying the media objects required. It is also useful for identifying a dump session. The session UUID can be copied from the inventory display to the -S option argument to unambiguously identify a dump session to be restored.

Dumps placed in regular files or the standard output do not span multiple media objects, nor do they contain multiple dumps.

Inventory

Each dump session updates an inventory database in /var/xfsdump/inventory. This database can be displayed by invoking xfsrestore 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=host­qualified_mount_point_pathname (that is, hostname:pathname), identifies the filesystem by mountpoint. -I fsid=filesystem_id identifies the filesystem by filesystem ID. -I dev=host­qualified_device_pathname (that is, hostname:device_pathname) identifies the filesystem by device.

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. This is currently unused.

Media Errors

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

FILES

/var/xfsdump/inventory dump inventory database

SEE ALSO

rmt(8), xfsdump(8), xfsinvutil(8), attr_set(2).

DIAGNOSTICS

The exit code is 0 on normal completion, and non­zero if an error occurred or the restore was terminated by the operator.

BUGS

Pathnames of restored non­directory files (relative to the destination directory) must be 1023 characters (MAXPATHLEN) or less. Longer pathnames are discarded and a warning message displayed.

There is no verify option to xfsrestore. This would allow the operator to compare a filesystem dump to an existing filesystem, without actually doing a restore.

The interactive commands (-i option) do not understand regular expressions.

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

Cumulative mode (-r option) requires that the operator invoke xfsrestore for the base and for each delta to be applied in sequence to the base. It would be better to allow the operator to identify the last delta in the sequence of interest, and let xfsrestore work backwards from that delta to identify and apply the preceding deltas and base dump, all in one invocation.