{
    "content": [
        {
            "type": "text",
            "text": "# xfsrestore(8) (man)\n\n**Summary:** xfsrestore - XFS filesystem incremental restore utility\n\n**Synopsis:** xfsrestore -h\nxfsrestore [ options ] -f source [ -f source ... ] dest\nxfsrestore [ options ] - dest\nxfsrestore -I [ subopt=value ... ]\n\n## Flags\n\n| Flag | Long | Arg | Description |\n|------|------|-----|-------------|\n| -a | — | — | Each invocation of xfsrestore creates a directory called xfsrestorehousekeepingdir. This directory is normally created d |\n| -b | — | — | Specifies the blocksize, in bytes, to be used for the restore. For other drives such as DAT or 8 mm , the same blocksize |\n| -c | — | — | Use the specified program to alert the operator when a media change is required. The alert program is typically a script |\n| -e | — | — |  |\n| -f | — | — | Specifies a source of the dump to be restored. This can be the pathname of a device (such as a tape drive), a regular fi |\n| -i | — | — | interactive dialogue is begun. The operator uses a small set of commands to peruse the directory hierarchy, selecting fi |\n| -m | — | — | size to be used (see -b option above). |\n| -n | — | — | Allows xfsrestore to restore only files newer than file. The modification time of file (i.e., as displayed with the ls - |\n| -o | — | — | user id of root, xfsrestore restores owner and group of each file and directory. When run with any other effective user  |\n| -p | — | — | Causes progress reports to be printed at intervals of interval seconds. The interval value is approximate, xfsrestore wi |\n| -q | — | — | srestore must make special allowances. |\n| -a | — | — | same for each invocation. |\n| -s | — | — | Specifies a subtree to restore. Any number of -s options are allowed. The restore is constrained to the union of all sub |\n| -t | — | — | ries. It may be desirable to set the verbosity level to silent when using this option. |\n| -v | — | — |  |\n| -v | — | — | Specifies the level of detail used for messages displayed during the course of the re‐ store. The verbosity argument can |\n| -A | — | — | DMF environment this option should not be used. DMF stores file migration status within extended attributes associated w |\n| -B | — | — | root directory of the dump. |\n| -D | — | — | restored filesystem will be managed within the same DMF environment as the original dump it is essential that the -D opt |\n| -E | — | — | time of the on-media file is compared to the inode modification time of corresponding file in the dest directory. The fi |\n| -F | — | — | the operator for verification of the selected dump as the restore target and from prompting for any media change. |\n| -I | — | — | dump is used, an online inventory in /var/lib/xfsdump/inventory is updated. This is used to determine the base for incre |\n| -J | — | — | xfsrestore opportunistically updates the online inventory when it encounters an on-media session inventory, but only if  |\n| -K | — | — | determined automatically, but this option is required on the first xfsrestore invocation in the rare case that a cumulat |\n| -L | — | — | Specifies the label of the dump session to be restored. The source media is searched for this label. It is any arbitrary |\n| -O | — | — | Insert the options contained in optionsfile into the beginning of the command line. The options are specified just as th |\n| -Q | — | — | around one specific pathological scenario. When restoring a dump session which was in‐ terrupted due to an EOM condition |\n| -R | — | — | pressing the terminal interrupt character (see stty(1)). Use this option to resume the restore. The -a and destination o |\n| -S | — | — | Specifies the session UUID of the dump session to be restored. The source media is searched for this UUID. The UUID of t |\n| -T | — | — | changes. This dialogue normally times out if no response is supplied. This option pre‐ vents the timeout. |\n| -X | — | — | Specifies a subtree to exclude. This is the converse of the -s option. Any number of -X options are allowed. Each subtre |\n| -Y | — | — | Specify I/O buffer ring length. xfsrestore uses a ring of input buffers to achieve max‐ imum throughput when restoring f |\n\n## Examples\n\n- `To restore the root filesystem from a locally mounted tape:`\n- `# xfsrestore -f /dev/tape /`\n- `To restore from a remote tape, specifying the dump session id:`\n- `# xfsrestore -L session1 -f otherhost:/dev/tape /new`\n- `To restore the contents a of a dump to another subdirectory:`\n- `# xfsrestore -f /dev/tape /newdir`\n- `To copy the contents of a filesystem to another directory (see xfsdump(8)):`\n- `# xfsdump -J - / | xfsrestore -J - /new`\n\n## See Also\n\n- rmt(8)\n- xfsdump(8)\n- xfsinvutil(8)\n- xfsquota(8)\n- attrset(2)\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **SYNOPSIS** (5 lines)\n- **DESCRIPTION** (24 lines) — 32 subsections\n  - -a (7 lines)\n  - -b (4 lines)\n  - -c (4 lines)\n  - -e (1 lines)\n  - -f -f (5 lines)\n  - -i (36 lines)\n  - -m (2 lines)\n  - -n (6 lines)\n  - -o (3 lines)\n  - -p (4 lines)\n  - -q (2 lines)\n  - -r -a (2 lines)\n  - -s (5 lines)\n  - -t (2 lines)\n  - -v (1 lines)\n  - -v (25 lines)\n  - -A (5 lines)\n  - -B (2 lines)\n  - -D (4 lines)\n  - -E (5 lines)\n  - -F (3 lines)\n  - -I (5 lines)\n  - -J (4 lines)\n  - -K (4 lines)\n  - -L (4 lines)\n  - -O (7 lines)\n  - -Q (8 lines)\n  - -R (3 lines)\n  - -S (4 lines)\n  - -T (3 lines)\n  - -X (5 lines)\n  - -Y (12 lines)\n- **NOTES** (1 lines) — 12 subsections\n  - Cumulative Restoration (19 lines)\n  - Media Management (25 lines)\n  - Inventory (8 lines)\n  - -I (5 lines)\n  - -I (4 lines)\n  - -I (2 lines)\n  - -I (4 lines)\n  - -I (4 lines)\n  - -I (2 lines)\n  - -I (29 lines)\n  - Media Errors (9 lines)\n  - Quotas (21 lines)\n- **EXAMPLES** (17 lines)\n- **FILES** (3 lines)\n- **SEE ALSO** (2 lines)\n- **DIAGNOSTICS** (15 lines)\n- **BUGS** (22 lines)\n\n## Full Content\n\n### NAME\n\nxfsrestore - XFS filesystem incremental restore utility\n\n### SYNOPSIS\n\nxfsrestore -h\nxfsrestore [ options ] -f source [ -f source ... ] dest\nxfsrestore [ options ] - dest\nxfsrestore -I [ subopt=value ... ]\n\n### DESCRIPTION\n\nxfsrestore  restores  filesystems  from dumps produced by xfsdump(8).  Two modes of operation\nare available: simple and cumulative.\n\nThe default is simple mode.  xfsrestore populates the specified destination directory,  dest,\nwith the files contained in the dump media.\n\nThe  -r  option specifies the cumulative mode.  Successive invocations of xfsrestore are used\nto apply a chronologically ordered sequence of delta dumps to a base  (level  0)  dump.   The\ncontents  of  the  filesystem at the time each dump was produced is reproduced.  This can in‐\nvolve adding, deleting, renaming, linking, and unlinking files and directories.\n\nA delta dump is defined as either an incremental dump (xfsdump -l option with level > 0) or a\nresumed  dump  (xfsdump  -R  option).  The deltas must be applied in the order they were pro‐\nduced.  Each delta applied must have been produced with the previously applied delta  as  its\nbase.\n\nxfsrestore keeps state information in the xfsrestorehousekeepingdir, to inform subsequent in‐\nvocations when used in cumulative mode, or in the event a restore is interrupted.  To  ensure\nthat  the state information can be processed, a compatible version of xfsrestore must be used\nfor each subsequent invocation. Additionally, each invocation must run on  a  system  of  the\nsame endianness and page size.\n\nThe options to xfsrestore are:\n\n#### -a\n\nEach  invocation  of  xfsrestore  creates  a directory called xfsrestorehousekeepingdir.\nThis directory is normally created directly under the dest directory.  The -a option al‐\nlows  the  operator to specify an alternate directory, housekeeping, in which xfsrestore\ncreates the xfsrestorehousekeepingdir directory.  When performing a cumulative  (-r  op‐\ntion) restore or resuming (-R option) a restore, each successive invocation must specify\nthe same alternate directory.\n\n#### -b\n\nSpecifies the blocksize, in bytes, to be used for the restore.  For other drives such as\nDAT or 8 mm , the same blocksize used for the xfsdump operation must be specified to re‐\nstore the tape.  The default block size is 1Mb.\n\n#### -c\n\nUse the specified program to alert the operator when a media  change  is  required.  The\nalert  program is typically a script to send a mail or flash a window to draw the opera‐\ntor's attention.\n\n#### -e\n\n#### -f -f\n\nSpecifies a source of the dump to be restored.  This can be the  pathname  of  a  device\n(such as a tape drive), a regular file or a remote tape drive (see rmt(8)).  This option\nmust be omitted if the standard input option (a lone - preceding the dest specification)\nis specified.\n\n#### -i\n\ninteractive dialogue is begun.  The operator uses a small set of commands to peruse  the\ndirectory  hierarchy,  selecting  files and subtrees for extraction.  The available com‐\nmands are given below.  Initially nothing is selected, except for those subtrees  speci‐\nfied with -s command line options.\n\nls [arg]       List  the entries in the current directory or the specified directory, or\nthe specified non-directory file entry.  Both the entry's original  inode\nnumber and name are displayed.  Entries that are directories are appended\nwith a `/'.  Entries that have been selected for extraction are prepended\nwith a `*'.\n\ncd [arg]       Change the current working directory to the specified argument, or to the\nfilesystem root directory if no argument is specified.\n\npwd            Print the pathname of the current directory, relative to  the  filesystem\nroot.\n\nadd [arg]      The  current  directory or specified file or directory within the current\ndirectory is selected for extraction.  If a directory is specified,  then\nit  and  all its descendents are selected.  Entries that are selected for\nextraction are prepended with a `*' when they are listed by ls.\n\ndelete [arg]   The current directory or specified file or directory within  the  current\ndirectory  is  deselected  for  extraction.  If a directory is specified,\nthen it and all its descendents are deselected.  The most  expedient  way\nto  extract most of the files from a directory is to select the directory\nand then deselect those files that are not needed.\n\nextract        Ends the interactive dialogue, and causes all selected subtrees to be re‐\nstored.\n\nquit           xfsrestore  ends  the interactive dialogue and immediately exits, even if\nthere are files or subtrees selected for extraction.\n\nhelp           List a summary of the available commands.\n\n#### -m\n\nsize to be used (see -b option above).\n\n#### -n\n\nAllows  xfsrestore to restore only files newer than file.  The modification time of file\n(i.e., as displayed with the ls -l command) is compared to the inode  modification  time\nof  each  file on the source media (i.e., as displayed with the ls -lc command).  A file\nis restored from media only if its inode modification time is greater than or  equal  to\nthe modification time of file.\n\n#### -o\n\nuser id of root, xfsrestore restores owner and group of each file and  directory.   When\nrun with any other effective user id it does not, unless this option is specified.\n\n#### -p\n\nCauses  progress  reports  to be printed at intervals of interval seconds.  The interval\nvalue is approximate, xfsrestore will delay progress reports to avoid  undue  processing\noverhead.\n\n#### -q\n\nsrestore must make special allowances.\n\n#### -r -a\n\nsame for each invocation.\n\n#### -s\n\nSpecifies  a  subtree to restore.  Any number of -s options are allowed.  The restore is\nconstrained to the union of all subtrees specified.  Each  subtree  is  specified  as  a\npathname  relative  to the restore dest.  If a directory is specified, the directory and\nall files beneath that directory are restored.\n\n#### -t\n\nries.  It may be desirable to set the verbosity level to silent when using this option.\n\n#### -v\n\n#### -v\n\nSpecifies  the  level of detail used for messages displayed during the course of the re‐\nstore. The verbosity argument can be passed as either a string or an integer. If  passed\nas  a  string the following values may be used: silent, verbose, trace, debug, or nitty.\nIf passed as an integer, values from 0-5 may be used. The values 0-4 correspond  to  the\nstrings  already listed. The value 5 can be used to produce even more verbose debug out‐\nput.\n\nThe first form of this option activates message logging across all  restore  subsystems.\nThe second form allows the message logging level to be controlled on a per-subsystem ba‐\nsis. The two forms can be combined (see the example below). The argument subsys can take\none of the following values: general, proc, drive, media, inventory, and tree.\n\nFor example, to restore the root filesystem with tracing activated for all subsystems:\n\n# xfsrestore -v trace -f /dev/tape /\n\nTo enable debug-level tracing for drive and media operations:\n\n# xfsrestore -v drive=debug,media=debug -f /dev/tape /\n\nTo enable tracing for all subsystems, and debug level tracing for drive operations only:\n\n# xfsrestore -v trace,drive=debug -f /dev/tape /\n\n#### -A\n\nDMF environment this option should not be used. DMF stores file migration status  within\nextended  attributes  associated  with  each file. If these attributes are not preserved\nwhen the filesystem is restored, files that had been in migrated state will not  be  re‐\ncallable by DMF. Note that dumping of extended file attributes is also optional.\n\n#### -B\n\nroot directory of the dump.\n\n#### -D\n\nrestored filesystem will be managed within the same DMF environment as the original dump\nit is essential that the -D option be used. Otherwise it is not usually desirable to re‐\nstore these settings.\n\n#### -E\n\ntime of the on-media file is compared to the inode modification  time  of  corresponding\nfile  in the dest directory.  The file is restored only if the on-media version is newer\nthan the version in the dest directory.  The inode modification time of a  file  can  be\ndisplayed with the ls -lc command.\n\n#### -F\n\nthe operator for verification of the selected  dump  as  the  restore  target  and  from\nprompting for any media change.\n\n#### -I\n\ndump is used, an online inventory in /var/lib/xfsdump/inventory  is  updated.   This  is\nused  to determine the base for incremental dumps.  It is also useful for manually iden‐\ntifying a dump session to be restored (see the -L and -S options).  Suboptions to filter\nthe inventory display are described later.\n\n#### -J\n\nxfsrestore opportunistically updates the online inventory when it encounters an on-media\nsession  inventory,  but  only if run with an effective user id of root and only if this\noption is not given.\n\n#### -K\n\ndetermined automatically, but this option is required on the first xfsrestore invocation\nin the rare case that a cumulative restore begins with a format 3 (or  newer)  dump  and\nwill be followed by a format 2 dump.\n\n#### -L\n\nSpecifies  the  label  of the dump session to be restored.  The source media is searched\nfor this label.  It is any arbitrary string up to 255 characters long.  The label of the\ndesired dump session can be copied from the inventory display produced by the -I option.\n\n#### -O\n\nInsert  the  options  contained  in optionsfile into the beginning of the command line.\nThe options are specified just as they would appear if typed into the command line.   In\naddition, newline characters (\\n) can be used as whitespace.  The options are placed be‐\nfore all options actually given on the command line, just after the command name.   Only\none  -O option can be used.  Recursive use is ignored.  The destination directory cannot\nbe specified in optionsfile.\n\n#### -Q\n\naround  one specific pathological scenario.  When restoring a dump session which was in‐\nterrupted due to an EOM condition and no online session inventory is  available,  xfsre‐\nstore  cannot  know  when the restore of that dump session is complete.  The operator is\nforced to interrupt the restore session.  In that case, if the operator tries to  subse‐\nquently  apply  a  resumed dump (using the -r option), xfsrestore refuses to do so.  The\noperator must tell xfsrestore to consider the base restore complete by using this option\nwhen applying the resumed dump.\n\n#### -R\n\npressing the terminal interrupt character (see stty(1)).  Use this option to resume  the\nrestore.  The -a and destination options must be the same.\n\n#### -S\n\nSpecifies  the  session  UUID  of  the dump session to be restored.  The source media is\nsearched for this UUID.  The UUID of the desired dump session can be copied from the in‐\nventory display produced by the -I option.\n\n#### -T\n\nchanges.  This dialogue normally times out if no response is supplied.  This option pre‐\nvents the timeout.\n\n#### -X\n\nSpecifies  a  subtree to exclude.  This is the converse of the -s option.  Any number of\n-X options are allowed.  Each subtree is specified as a pathname relative to the restore\ndest.   If  a directory is specified, the directory and all files beneath that directory\nare excluded.\n\n#### -Y\n\nSpecify I/O buffer ring length.  xfsrestore uses a ring of input buffers to achieve max‐\nimum  throughput  when  restoring from tape drives.  The default ring length is 3.  How‐\never, this is not currently enabled on Linux yet, making this option benign.\n\n-    A lone - causes the standard input to be read as the source of the dump to be  restored.\nStandard  input  can be a pipe from another utility (such as xfsdump(8)) or a redirected\nfile.  This option cannot be used with the -f option.  The - must follow all  other  op‐\ntions, and precede the dest specification.\n\nThe  dumped  filesystem  is  restored into the dest directory.  There is no default; the dest\nmust be specified.\n\n### NOTES\n\n#### Cumulative Restoration\n\nA base (level 0) dump and an ordered set of delta dumps can be sequentially restored, each on\ntop  of  the  previous,  to reproduce the contents of the original filesystem at the time the\nlast delta was produced.  The operator invokes xfsrestore once for each dump.  The -r  option\nmust be specified.  The dest directory must be the same for all invocations.  Each invocation\nleaves a directory named xfsrestorehousekeeping in the dest directory (however,  see  the  -a\noption  above).   This directory contains the state information that must be communicated be‐\ntween invocations.  The operator must remove this directory after the last delta has been ap‐\nplied.\n\nxfsrestore  also generates a directory named orphanage in the dest directory.  xfsrestore re‐\nmoves this directory after completing a simple restore.  However, if orphanage is not  empty,\nit  is not removed.  This can happen if files present on the dump media are not referenced by\nany of the restored directories.  The orphanage has an entry for each such file.   The  entry\nname  is the file's original inode number, a \".\", and the file's generation count modulo 4096\n(only the lower 12 bits of the generation count are used).\n\nxfsrestore does not remove the orphanage after cumulative  restores.   Like  the  xfsrestore‐\nhousekeeping directory, the operator must remove it after applying all delta dumps.\n\n#### Media Management\n\nA  dump  consists of one or more media files contained on one or more media objects.  A media\nfile contains all or a portion of the filesystem dump.  Large filesystems are broken up  into\nmultiple  media  files to minimize the impact of media dropouts, and to accommodate media ob‐\nject boundaries (end-of-media).\n\nA media object is any storage medium: a tape cartridge, a remote tape device (see rmt(8)),  a\nregular  file,  or  the  standard  input (currently other removable media drives are not sup‐\nported).  Tape cartridges can contain multiple media files, which are typically separated  by\n(in  tape parlance) file marks.  If a dump spans multiple media objects, the restore must be‐\ngin with the media object containing the first media file dumped.  The operator  is  prompted\nwhen the next media object is needed.\n\nMedia  objects  can  contain more than one dump.  The operator can select the desired dump by\nspecifying the dump label (-L option), or by specifying the dump UUID (-S option).   If  nei‐\nther  is  specified, xfsrestore scans the entire media object, prompting the operator as each\ndump session is encountered.\n\nThe inventory display (-I option) is useful for identifying the media objects  required.   It\nis  also  useful for identifying a dump session.  The session UUID can be copied from the in‐\nventory display to the -S option argument to unambiguously identify a dump session to be  re‐\nstored.\n\nDumps  placed in regular files or the standard output do not span multiple media objects, nor\ndo they contain multiple dumps.\n\n#### Inventory\n\nEach dump session updates an inventory database in /var/lib/xfsdump/inventory.  This database\ncan be displayed by invoking xfsrestore with the -I option.  The display uses tabbed indenta‐\ntion to present the inventory hierarchically.  The first level  is  filesystem.   The  second\nlevel  is session.  The third level is media stream (currently only one stream is supported).\nThe fourth level lists the media files sequentially composing the stream.\n\nThe following suboptions are available to filter the display.\n\n#### -I\n\n(where n is 1, 2, or 3) limits the hierarchical depth of the display. When n is 1,  only\nthe filesystem information from the inventory is displayed. When n is 2, only filesystem\nand session information are displayed. When n is 3, only filesystem, session and  stream\ninformation are displayed.\n\n#### -I\n\n(where n is the dump level) limits the display to dumps of that particular dump level.\n\nThe display may be restricted to media files contained in a specific media object.\n\n#### -I\n\n(where value is a media ID) specifies the media object by its media ID.\n\n#### -I\n\n(where value is a media label) specifies the media object by its media label.\n\nSimilarly, the display can be restricted to a specific filesystem.\n\n#### -I\n\n(that is, [hostname:]pathname), identifies the filesystem by mountpoint.  Specifying the\nhostname is optional, but may be useful in a clustered environment where more  than  one\nhost can be responsible for dumping a filesystem.\n\n#### -I\n\nidentifies the filesystem by filesystem ID.\n\n#### -I\n\n(that  is, [hostname:]devicepathname) identifies the filesystem by device.  As with the\nmnt filter, specifying the hostname is optional.\n\nMore than one of these suboptions, separated by commas, may be specified at the same time  to\nlimit  the display of the inventory to those dumps of interest.  However, at most four subop‐\ntions can be specified at once: one to constrain the display hierarchy  depth,  one  to  con‐\nstrain  the  dump level, one to constrain the media object, and one to constrain the filesys‐\ntem.\n\nFor  example,  -I  depth=1,mobjlabel=\"tape  1\",mnt=host1:/testmnt  would  display  only  the\nfilesystem  information  (depth=1) for those filesystems that were mounted on host1:/testmnt\nat the time of the dump, and only those filesystems dumped to the media object labeled  \"tape\n1\".\n\nDump records may be removed (pruned) from the inventory using the xfsinvutil program.\n\nAn  additional media file is placed at the end of each dump stream.  This media file contains\nthe inventory information for the current dump session.  If the  online  inventory  files  in\n/var/lib/xfsdump/inventory are missing information for the current dump session, then the in‐\nventory information in the media file is automatically added to the  files  in  /var/lib/xfs‐\ndump/inventory.   If  you  wish  to incorporate the inventory information from the media file\nwithout restoring any data, you may do so using the -t option:\n\n# xfsrestore -t -f /dev/tape\n\nThis is useful to rebuild the inventory database if it is ever lost or corrupted.   The  only\ncaveat  is that xfsrestore needs to read through the entire dump in order to reach the inven‐\ntory media file.  This could become time consuming for dump sessions with large media files.\n\n#### Media Errors\n\nxfsdump is tolerant of media errors, but cannot do error correction.  If a media error occurs\nin  the body of a media file, the filesystem file represented at that point is lost.  The bad\nportion of the media is skipped, and the restoration resumes at the next filesystem file  af‐\nter the bad portion of the media.\n\nIf  a  media  error occurs in the beginning of the media file, the entire media file is lost.\nFor this reason, large dumps are broken into a number of reasonably sized media  files.   The\nrestore resumes with the next media file.\n\n#### Quotas\n\nWhen  xfsdump  dumps a filesystem with user quotas, it creates a file in the root of the dump\ncalled xfsdumpquotas.  xfsrestore can restore this file like any other file included in  the\ndump.   This  file  can be processed by the restore command of xfsquota(8) to reactivate the\nquotas.  However, the xfsdumpquotas file contains information which may first require  modi‐\nfication; specifically the filesystem name and the user ids.  If you are restoring the quotas\nfor the same users on the same filesystem from which the dump was taken, then no modification\nwill  be  necessary.   However,  if you are restoring the dump to a different filesystem, you\nwill need to:\n\n- ensure the new filesystem is mounted with the quota option\n\n- modify the xfsdumpquotas file to contain the new filesystem name\n\n- ensure the uids in the xfsdumpquotas file are correct\n\nOnce the quota information has been verified, the restore command of  xfsquota  (8)  can  be\nused to apply the quota limits to the filesystem.\n\nGroup  and  project  quotas  are  handled  in a similar fashion and will be restored in files\ncalled xfsdumpquotasgroup and xfsdumpquotasproj, respectively.\n\n### EXAMPLES\n\nTo restore the root filesystem from a locally mounted tape:\n\n# xfsrestore -f /dev/tape /\n\nTo restore from a remote tape, specifying the dump session id:\n\n# xfsrestore -L session1 -f otherhost:/dev/tape /new\n\nTo restore the contents a of a dump to another subdirectory:\n\n# xfsrestore -f /dev/tape /newdir\n\nTo copy the contents of a filesystem to another directory (see xfsdump(8)):\n\n# xfsdump -J - / | xfsrestore -J - /new\n\n### FILES\n\n/var/lib/xfsdump/inventory\ndump inventory database\n\n### SEE ALSO\n\nrmt(8), xfsdump(8), xfsinvutil(8), xfsquota(8), attrset(2).\n\n### DIAGNOSTICS\n\nThe exit code is 0 on normal completion, and non-zero if an error occurred or the restore was\nterminated by the operator.\n\nFor  all verbosity levels greater than 0 (silent) the final line of the output shows the exit\nstatus of the restore. It is of the form:\n\nxfsdump: Restore Status: code\n\nWhere code takes one of the following values: SUCCESS (normal completion), INTERRUPT  (inter‐\nrupted),  QUIT (media no longer usable), INCOMPLETE (restore incomplete), FAULT (software er‐\nror), and ERROR (resource error).  Every attempt will be made to keep both the syntax and the\nsemantics of this log message unchanged in future versions of xfsrestore.  However, it may be\nnecessary to refine or expand the set of exit codes, or their interpretation at some point in\nthe future.\n\n### BUGS\n\nPathnames of restored non-directory files (relative to the dest directory) must be 1023 char‐\nacters (MAXPATHLEN) or less.  Longer pathnames are discarded and a warning message displayed.\n\nThere is no verify option to xfsrestore.  This would allow the operator to compare a filesys‐\ntem dump to an existing filesystem, without actually doing a restore.\n\nThe interactive commands (-i option) do not understand regular expressions.\n\nWhen  the  minimal rmt option is specified, xfsrestore applies it to all remote tape sources.\nThe same blocksize (specified by the -b option) is used for all these remote drives.\n\nxfsrestore uses the alert program only when a media change is required.\n\nCumulative mode (-r option) requires that the operator invoke xfsrestore for the base and for\neach  delta  to be applied in sequence to the base.  It would be better to allow the operator\nto identify the last delta in the sequence of interest, and  let  xfsrestore  work  backwards\nfrom  that delta to identify and apply the preceding deltas and base dump, all in one invoca‐\ntion.\n\n\n\nxfsrestore(8)\n\n"
        }
    ],
    "structuredContent": {
        "command": "xfsrestore",
        "section": "8",
        "mode": "man",
        "summary": "xfsrestore - XFS filesystem incremental restore utility",
        "synopsis": "xfsrestore -h\nxfsrestore [ options ] -f source [ -f source ... ] dest\nxfsrestore [ options ] - dest\nxfsrestore -I [ subopt=value ... ]",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [
            {
                "flag": "-a",
                "long": null,
                "arg": null,
                "description": "Each invocation of xfsrestore creates a directory called xfsrestorehousekeepingdir. This directory is normally created directly under the dest directory. The -a option al‐ lows the operator to specify an alternate directory, housekeeping, in which xfsrestore creates the xfsrestorehousekeepingdir directory. When performing a cumulative (-r op‐ tion) restore or resuming (-R option) a restore, each successive invocation must specify the same alternate directory."
            },
            {
                "flag": "-b",
                "long": null,
                "arg": null,
                "description": "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 re‐ store the tape. The default block size is 1Mb."
            },
            {
                "flag": "-c",
                "long": null,
                "arg": null,
                "description": "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 opera‐ tor's attention."
            },
            {
                "flag": "-e",
                "long": null,
                "arg": null,
                "description": ""
            },
            {
                "flag": "-f",
                "long": null,
                "arg": null,
                "description": "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 dest specification) is specified."
            },
            {
                "flag": "-i",
                "long": null,
                "arg": null,
                "description": "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 com‐ mands are given below. Initially nothing is selected, except for those subtrees speci‐ fied 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. pwd Print the pathname of the current directory, relative to the filesystem root. add [arg] The current directory or specified file or directory within the current directory is selected for extraction. If a directory is specified, then it and all its descendents are selected. Entries that are selected for extraction are prepended with a `*' when they are listed by ls. delete [arg] The current directory or specified file or directory within the current directory is deselected for extraction. If a directory is specified, then it and all its descendents are deselected. The most expedient way to extract most of the files from a directory is to select the directory and then deselect those files that are not needed. extract Ends the interactive dialogue, and causes all selected subtrees to be re‐ stored. quit xfsrestore ends the interactive dialogue and immediately exits, even if there are files or subtrees selected for extraction. help List a summary of the available commands."
            },
            {
                "flag": "-m",
                "long": null,
                "arg": null,
                "description": "size to be used (see -b option above)."
            },
            {
                "flag": "-n",
                "long": null,
                "arg": null,
                "description": "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."
            },
            {
                "flag": "-o",
                "long": null,
                "arg": null,
                "description": "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."
            },
            {
                "flag": "-p",
                "long": null,
                "arg": null,
                "description": "Causes progress reports to be printed at intervals of interval seconds. The interval value is approximate, xfsrestore will delay progress reports to avoid undue processing overhead."
            },
            {
                "flag": "-q",
                "long": null,
                "arg": null,
                "description": "srestore must make special allowances."
            },
            {
                "flag": "-a",
                "long": null,
                "arg": null,
                "description": "same for each invocation."
            },
            {
                "flag": "-s",
                "long": null,
                "arg": null,
                "description": "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 dest. If a directory is specified, the directory and all files beneath that directory are restored."
            },
            {
                "flag": "-t",
                "long": null,
                "arg": null,
                "description": "ries. It may be desirable to set the verbosity level to silent when using this option."
            },
            {
                "flag": "-v",
                "long": null,
                "arg": null,
                "description": ""
            },
            {
                "flag": "-v",
                "long": null,
                "arg": null,
                "description": "Specifies the level of detail used for messages displayed during the course of the re‐ store. 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 correspond to the strings already listed. The value 5 can be used to produce even more verbose debug out‐ put. 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 ba‐ sis. 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, and tree. 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 /"
            },
            {
                "flag": "-A",
                "long": null,
                "arg": null,
                "description": "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 re‐ callable by DMF. Note that dumping of extended file attributes is also optional."
            },
            {
                "flag": "-B",
                "long": null,
                "arg": null,
                "description": "root directory of the dump."
            },
            {
                "flag": "-D",
                "long": null,
                "arg": null,
                "description": "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 re‐ store these settings."
            },
            {
                "flag": "-E",
                "long": null,
                "arg": null,
                "description": "time of the on-media file is compared to the inode modification time of corresponding file in the dest directory. The file is restored only if the on-media version is newer than the version in the dest directory. The inode modification time of a file can be displayed with the ls -lc command."
            },
            {
                "flag": "-F",
                "long": null,
                "arg": null,
                "description": "the operator for verification of the selected dump as the restore target and from prompting for any media change."
            },
            {
                "flag": "-I",
                "long": null,
                "arg": null,
                "description": "dump is used, an online inventory in /var/lib/xfsdump/inventory is updated. This is used to determine the base for incremental dumps. It is also useful for manually iden‐ tifying a dump session to be restored (see the -L and -S options). Suboptions to filter the inventory display are described later."
            },
            {
                "flag": "-J",
                "long": null,
                "arg": null,
                "description": "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."
            },
            {
                "flag": "-K",
                "long": null,
                "arg": null,
                "description": "determined automatically, but this option is required on the first xfsrestore invocation in the rare case that a cumulative restore begins with a format 3 (or newer) dump and will be followed by a format 2 dump."
            },
            {
                "flag": "-L",
                "long": null,
                "arg": null,
                "description": "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."
            },
            {
                "flag": "-O",
                "long": null,
                "arg": null,
                "description": "Insert the options contained in optionsfile 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 be‐ fore 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 optionsfile."
            },
            {
                "flag": "-Q",
                "long": null,
                "arg": null,
                "description": "around one specific pathological scenario. When restoring a dump session which was in‐ terrupted due to an EOM condition and no online session inventory is available, xfsre‐ store 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 subse‐ quently 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."
            },
            {
                "flag": "-R",
                "long": null,
                "arg": null,
                "description": "pressing the terminal interrupt character (see stty(1)). Use this option to resume the restore. The -a and destination options must be the same."
            },
            {
                "flag": "-S",
                "long": null,
                "arg": null,
                "description": "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 in‐ ventory display produced by the -I option."
            },
            {
                "flag": "-T",
                "long": null,
                "arg": null,
                "description": "changes. This dialogue normally times out if no response is supplied. This option pre‐ vents the timeout."
            },
            {
                "flag": "-X",
                "long": null,
                "arg": null,
                "description": "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 dest. If a directory is specified, the directory and all files beneath that directory are excluded."
            },
            {
                "flag": "-Y",
                "long": null,
                "arg": null,
                "description": "Specify I/O buffer ring length. xfsrestore uses a ring of input buffers to achieve max‐ imum throughput when restoring from 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 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 op‐ tions, and precede the dest specification. The dumped filesystem is restored into the dest directory. There is no default; the dest must be specified."
            }
        ],
        "examples": [
            "To restore the root filesystem from a locally mounted tape:",
            "# xfsrestore -f /dev/tape /",
            "To restore from a remote tape, specifying the dump session id:",
            "# xfsrestore -L session1 -f otherhost:/dev/tape /new",
            "To restore the contents a of a dump to another subdirectory:",
            "# xfsrestore -f /dev/tape /newdir",
            "To copy the contents of a filesystem to another directory (see xfsdump(8)):",
            "# xfsdump -J - / | xfsrestore -J - /new"
        ],
        "see_also": [
            {
                "name": "rmt",
                "section": "8",
                "url": "https://www.chedong.com/phpMan.php/man/rmt/8/json"
            },
            {
                "name": "xfsdump",
                "section": "8",
                "url": "https://www.chedong.com/phpMan.php/man/xfsdump/8/json"
            },
            {
                "name": "xfsinvutil",
                "section": "8",
                "url": "https://www.chedong.com/phpMan.php/man/xfsinvutil/8/json"
            },
            {
                "name": "xfsquota",
                "section": "8",
                "url": "https://www.chedong.com/phpMan.php/man/xfsquota/8/json"
            },
            {
                "name": "attrset",
                "section": "2",
                "url": "https://www.chedong.com/phpMan.php/man/attrset/2/json"
            }
        ],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 5,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 24,
                "subsections": [
                    {
                        "name": "-a",
                        "lines": 7,
                        "flag": "-a"
                    },
                    {
                        "name": "-b",
                        "lines": 4,
                        "flag": "-b"
                    },
                    {
                        "name": "-c",
                        "lines": 4,
                        "flag": "-c"
                    },
                    {
                        "name": "-e",
                        "lines": 1,
                        "flag": "-e"
                    },
                    {
                        "name": "-f -f",
                        "lines": 5,
                        "flag": "-f"
                    },
                    {
                        "name": "-i",
                        "lines": 36,
                        "flag": "-i"
                    },
                    {
                        "name": "-m",
                        "lines": 2,
                        "flag": "-m"
                    },
                    {
                        "name": "-n",
                        "lines": 6,
                        "flag": "-n"
                    },
                    {
                        "name": "-o",
                        "lines": 3,
                        "flag": "-o"
                    },
                    {
                        "name": "-p",
                        "lines": 4,
                        "flag": "-p"
                    },
                    {
                        "name": "-q",
                        "lines": 2,
                        "flag": "-q"
                    },
                    {
                        "name": "-r -a",
                        "lines": 2,
                        "flag": "-a"
                    },
                    {
                        "name": "-s",
                        "lines": 5,
                        "flag": "-s"
                    },
                    {
                        "name": "-t",
                        "lines": 2,
                        "flag": "-t"
                    },
                    {
                        "name": "-v",
                        "lines": 1,
                        "flag": "-v"
                    },
                    {
                        "name": "-v",
                        "lines": 25,
                        "flag": "-v"
                    },
                    {
                        "name": "-A",
                        "lines": 5,
                        "flag": "-A"
                    },
                    {
                        "name": "-B",
                        "lines": 2,
                        "flag": "-B"
                    },
                    {
                        "name": "-D",
                        "lines": 4,
                        "flag": "-D"
                    },
                    {
                        "name": "-E",
                        "lines": 5,
                        "flag": "-E"
                    },
                    {
                        "name": "-F",
                        "lines": 3,
                        "flag": "-F"
                    },
                    {
                        "name": "-I",
                        "lines": 5,
                        "flag": "-I"
                    },
                    {
                        "name": "-J",
                        "lines": 4,
                        "flag": "-J"
                    },
                    {
                        "name": "-K",
                        "lines": 4,
                        "flag": "-K"
                    },
                    {
                        "name": "-L",
                        "lines": 4,
                        "flag": "-L"
                    },
                    {
                        "name": "-O",
                        "lines": 7,
                        "flag": "-O"
                    },
                    {
                        "name": "-Q",
                        "lines": 8,
                        "flag": "-Q"
                    },
                    {
                        "name": "-R",
                        "lines": 3,
                        "flag": "-R"
                    },
                    {
                        "name": "-S",
                        "lines": 4,
                        "flag": "-S"
                    },
                    {
                        "name": "-T",
                        "lines": 3,
                        "flag": "-T"
                    },
                    {
                        "name": "-X",
                        "lines": 5,
                        "flag": "-X"
                    },
                    {
                        "name": "-Y",
                        "lines": 12,
                        "flag": "-Y"
                    }
                ]
            },
            {
                "name": "NOTES",
                "lines": 1,
                "subsections": [
                    {
                        "name": "Cumulative Restoration",
                        "lines": 19
                    },
                    {
                        "name": "Media Management",
                        "lines": 25
                    },
                    {
                        "name": "Inventory",
                        "lines": 8
                    },
                    {
                        "name": "-I",
                        "lines": 5,
                        "flag": "-I"
                    },
                    {
                        "name": "-I",
                        "lines": 4,
                        "flag": "-I"
                    },
                    {
                        "name": "-I",
                        "lines": 2,
                        "flag": "-I"
                    },
                    {
                        "name": "-I",
                        "lines": 4,
                        "flag": "-I"
                    },
                    {
                        "name": "-I",
                        "lines": 4,
                        "flag": "-I"
                    },
                    {
                        "name": "-I",
                        "lines": 2,
                        "flag": "-I"
                    },
                    {
                        "name": "-I",
                        "lines": 29,
                        "flag": "-I"
                    },
                    {
                        "name": "Media Errors",
                        "lines": 9
                    },
                    {
                        "name": "Quotas",
                        "lines": 21
                    }
                ]
            },
            {
                "name": "EXAMPLES",
                "lines": 17,
                "subsections": []
            },
            {
                "name": "FILES",
                "lines": 3,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "DIAGNOSTICS",
                "lines": 15,
                "subsections": []
            },
            {
                "name": "BUGS",
                "lines": 22,
                "subsections": []
            }
        ]
    }
}