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 dest directory
must be the same for all invocations. Each invocation leaves a
directory named xfsrestorehousekeeping in the dest 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 dest
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/lib/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=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. 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
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.
Quotas
When xfsdump dumps a filesystem with user 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 restore command of xfs_quota(8)
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, the restore command
of xfs_quota(8) can be used to apply the quota limits to the
filesystem.
Group and project quotas are handled in a similar fashion and
will be restored in files called xfsdump_quotas_group and
xfsdump_quotas_proj, respectively.
