1xfsrestore(8) System Manager's Manual xfsrestore(8)
2
6 xfsrestore - XFS filesystem incremental restore utility
7
9 xfsrestore -h
10 xfsrestore [ options ] -f source [ -f source ... ] dest
11 xfsrestore [ options ] - dest
12 xfsrestore -I [ subopt=value ... ]
13
15 xfsrestore restores filesystems from dumps produced by xfsdump(8). Two
16 modes of operation are available: simple and cumulative.
17 The default is simple mode. xfsrestore populates the specified desti‐
19 nation directory, dest, with the files contained in the dump media.
20 The -r option specifies the cumulative mode. Successive invocations of
22 xfsrestore are used to apply a chronologically ordered sequence of
23 delta dumps to a base (level 0) dump. The contents of the filesystem
24 at the time each dump was produced is reproduced. This can involve
25 adding, deleting, renaming, linking, and unlinking files and directo‐
26 ries.
27 A delta dump is defined as either an incremental dump (xfsdump -l
29 option with level > 0) or a resumed dump (xfsdump -R option). The
30 deltas must be applied in the order they were produced. Each delta
31 applied must have been produced with the previously applied delta as
32 its base.
33 xfsrestore keeps state information in the xfsrestorehousekeepingdir, to
35 inform subsequent invocations when used in cumulative mode, or in the
36 event a restore is interrupted. To ensure that the state information
37 can be processed, a compatible version of xfsrestore must be used for
38 each subsequent invocation. Additionally, each invocation must run on a
39 system of the same endianness and page size.
40 The options to xfsrestore are:
42 -a housekeeping
44 Each invocation of xfsrestore creates a directory called xfsre‐
45 storehousekeepingdir. This directory is normally created directly
46 under the dest directory. The -a option allows the operator to
47 specify an alternate directory, housekeeping, in which xfsrestore
48 creates the xfsrestorehousekeepingdir directory. When performing
49 a cumulative (-r option) restore or resuming (-R option) a
50 restore, each successive invocation must specify the same alter‐
51 nate directory.
52 -b blocksize
54 Specifies the blocksize, in bytes, to be used for the restore.
55 For other drives such as DAT or 8 mm , the same blocksize used for
56 the xfsdump operation must be specified to restore the tape. The
57 default block size is 1Mb.
58 -c progname
60 Use the specified program to alert the operator when a media
61 change is required. The alert program is typically a script to
62 send a mail or flash a window to draw the operator's attention.
63 -e Prevents xfsrestore from overwriting existing files in the dest
65 directory.
66 -f source [ -f source ... ]
68 Specifies a source of the dump to be restored. This can be the
69 pathname of a device (such as a tape drive), a regular file or a
70 remote tape drive (see rmt(8)). This option must be omitted if
71 the standard input option (a lone - preceding the dest specifica‐
72 tion) is specified.
73 -i Selects interactive operation. Once the on-media directory hier‐
75 archy has been read, an interactive dialogue is begun. The opera‐
76 tor uses a small set of commands to peruse the directory hierar‐
77 chy, selecting files and subtrees for extraction. The available
78 commands are given below. Initially nothing is selected, except
79 for those subtrees specified with -s command line options.
80 ls [arg] List the entries in the current directory or the
82 specified directory, or the specified non-directory
83 file entry. Both the entry's original inode number
84 and name are displayed. Entries that are directo‐
85 ries are appended with a `/'. Entries that have
86 been selected for extraction are prepended with a
87 `*'.
88 cd [arg] Change the current working directory to the speci‐
90 fied argument, or to the filesystem root directory
91 if no argument is specified.
92 pwd Print the pathname of the current directory, rela‐
94 tive to the filesystem root.
95 add [arg] The current directory or specified file or direc‐
97 tory within the current directory is selected for
98 extraction. If a directory is specified, then it
99 and all its descendents are selected. Entries that
100 are selected for extraction are prepended with a
101 `*' when they are listed by ls.
102 delete [arg] The current directory or specified file or direc‐
104 tory within the current directory is deselected for
105 extraction. If a directory is specified, then it
106 and all its descendents are deselected. The most
107 expedient way to extract most of the files from a
108 directory is to select the directory and then dese‐
109 lect those files that are not needed.
110 extract Ends the interactive dialogue, and causes all
112 selected subtrees to be restored.
113 quit xfsrestore ends the interactive dialogue and imme‐
115 diately exits, even if there are files or subtrees
116 selected for extraction.
117 help List a summary of the available commands.
119 -m Use the minimal tape protocol. This option cannot be used without
121 specifying a blocksize to be used (see -b option above).
122 -n file
124 Allows xfsrestore to restore only files newer than file. The mod‐
125 ification time of file (i.e., as displayed with the ls -l command)
126 is compared to the inode modification time of each file on the
127 source media (i.e., as displayed with the ls -lc command). A file
128 is restored from media only if its inode modification time is
129 greater than or equal to the modification time of file.
130 -o Restore file and directory owner/group even if not root. When run
132 with an effective user id of root, xfsrestore restores owner and
133 group of each file and directory. When run with any other effec‐
134 tive user id it does not, unless this option is specified.
135 -p interval
137 Causes progress reports to be printed at intervals of interval
138 seconds. The interval value is approximate, xfsrestore will delay
139 progress reports to avoid undue processing overhead.
140 -q Source tape drive is a QIC tape. QIC tapes only use a 512 byte
142 blocksize, for which xfsrestore must make special allowances.
143 -r Selects the cumulative mode of operation. The -a and destination
145 options must be the same for each invocation.
146 -s subtree
148 Specifies a subtree to restore. Any number of -s options are
149 allowed. The restore is constrained to the union of all subtrees
150 specified. Each subtree is specified as a pathname relative to
151 the restore dest. If a directory is specified, the directory and
152 all files beneath that directory are restored.
153 -t Displays the contents of the dump, but does not create or modify
155 any files or directories. It may be desirable to set the ver‐
156 bosity level to silent when using this option.
157 -v verbosity
159 -v subsys=verbosity[,subsys=verbosity,...]
160 Specifies the level of detail used for messages displayed during
161 the course of the restore. The verbosity argument can be passed as
162 either a string or an integer. If passed as a string the following
163 values may be used: silent, verbose, trace, debug, or nitty. If
164 passed as an integer, values from 0-5 may be used. The values 0-4
165 correspond to the strings already listed. The value 5 can be used
166 to produce even more verbose debug output.
167 The first form of this option activates message logging across all
169 restore subsystems. The second form allows the message logging
170 level to be controlled on a per-subsystem basis. The two forms can
171 be combined (see the example below). The argument subsys can take
172 one of the following values: general, proc, drive, media, inven‐
173 tory, and tree.
174 For example, to restore the root filesystem with tracing activated
176 for all subsystems:
177 # xfsrestore -v trace -f /dev/tape /
179 To enable debug-level tracing for drive and media operations:
181 # xfsrestore -v drive=debug,media=debug -f /dev/tape /
183 To enable tracing for all subsystems, and debug level tracing for
185 drive operations only:
186 # xfsrestore -v trace,drive=debug -f /dev/tape /
188 -A Do not restore extended file attributes. When restoring a
191 filesystem managed within a DMF environment this option should not
192 be used. DMF stores file migration status within extended
193 attributes associated with each file. If these attributes are not
194 preserved when the filesystem is restored, files that had been in
195 migrated state will not be recallable by DMF. Note that dumping of
196 extended file attributes is also optional.
197 -B Change the ownership and permissions of the destination directory
199 to match those of the root directory of the dump.
200 -D Restore DMAPI (Data Management Application Programming Interface)
202 event settings. If the restored filesystem will be managed within
203 the same DMF environment as the original dump it is essential that
204 the -D option be used. Otherwise it is not usually desirable to
205 restore these settings.
206 -E Prevents xfsrestore from overwriting newer versions of files. The
208 inode modification time of the on-media file is compared to the
209 inode modification time of corresponding file in the dest direc‐
210 tory. The file is restored only if the on-media version is newer
211 than the version in the dest directory. The inode modification
212 time of a file can be displayed with the ls -lc command.
213 -F Inhibit interactive operator prompts. This option inhibits xfsre‐
215 store from prompting the operator for verification of the selected
216 dump as the restore target and from prompting for any media
217 change.
218 -I Causes the xfsdump inventory to be displayed (no restore is per‐
220 formed). Each time xfsdump is used, an online inventory in
221 /var/lib/xfsdump/inventory is updated. This is used to determine
222 the base for incremental dumps. It is also useful for manually
223 identifying a dump session to be restored (see the -L and -S
224 options). Suboptions to filter the inventory display are
225 described later.
226 -J Inhibits inventory update when on-media session inventory encoun‐
228 tered during restore. xfsrestore opportunistically updates the
229 online inventory when it encounters an on-media session inventory,
230 but only if run with an effective user id of root and only if this
231 option is not given.
232 -K Force xfsrestore to use dump format 2 generation numbers. Normally
234 the need for this is determined automatically, but this option is
235 required on the first xfsrestore invocation in the rare case that
236 a cumulative restore begins with a format 3 (or newer) dump and
237 will be followed by a format 2 dump.
238 -L session_label
240 Specifies the label of the dump session to be restored. The
241 source media is searched for this label. It is any arbitrary
242 string up to 255 characters long. The label of the desired dump
243 session can be copied from the inventory display produced by the
244 -I option.
245 -O options_file
247 Insert the options contained in options_file into the beginning of
248 the command line. The options are specified just as they would
249 appear if typed into the command line. In addition, newline char‐
250 acters (\n) can be used as whitespace. The options are placed
251 before all options actually given on the command line, just after
252 the command name. Only one -O option can be used. Recursive use
253 is ignored. The destination directory cannot be specified in
254 options_file.
255 -Q Force completion of an interrupted restore session. This option
257 is required to work around one specific pathological scenario.
258 When restoring a dump session which was interrupted due to an EOM
259 condition and no online session inventory is available, xfsrestore
260 cannot know when the restore of that dump session is complete.
261 The operator is forced to interrupt the restore session. In that
262 case, if the operator tries to subsequently apply a resumed dump
263 (using the -r option), xfsrestore refuses to do so. The operator
264 must tell xfsrestore to consider the base restore complete by
265 using this option when applying the resumed dump.
266 -R Resume a previously interrupted restore. xfsrestore can be inter‐
268 rupted at any time by pressing the terminal interrupt character
269 (see stty(1)). Use this option to resume the restore. The -a and
270 destination options must be the same.
271 -S session_id
273 Specifies the session UUID of the dump session to be restored.
274 The source media is searched for this UUID. The UUID of the
275 desired dump session can be copied from the inventory display pro‐
276 duced by the -I option.
277 -T Inhibits interactive dialogue timeouts. xfsrestore prompts the
279 operator for media changes. This dialogue normally times out if
280 no response is supplied. This option prevents the timeout.
281 -X subtree
283 Specifies a subtree to exclude. This is the converse of the -s
284 option. Any number of -X options are allowed. Each subtree is
285 specified as a pathname relative to the restore dest. If a direc‐
286 tory is specified, the directory and all files beneath that direc‐
287 tory are excluded.
288 -Y io_ring_length
290 Specify I/O buffer ring length. xfsrestore uses a ring of input
291 buffers to achieve maximum throughput when restoring from tape
292 drives. The default ring length is 3. However, this is not cur‐
293 rently enabled on Linux yet, making this option benign.
294 - A lone - causes the standard input to be read as the source of the
296 dump to be restored. Standard input can be a pipe from another
297 utility (such as xfsdump(8)) or a redirected file. This option
298 cannot be used with the -f option. The - must follow all other
299 options, and precede the dest specification.
300 The dumped filesystem is restored into the dest directory. There is no
302 default; the dest must be specified.
303
305 Cumulative Restoration
306 A base (level 0) dump and an ordered set of delta dumps can be sequen‐
307 tially restored, each on top of the previous, to reproduce the contents
308 of the original filesystem at the time the last delta was produced.
309 The operator invokes xfsrestore once for each dump. The -r option must
310 be specified. The dest directory must be the same for all invocations.
311 Each invocation leaves a directory named xfsrestorehousekeeping in the
312 dest directory (however, see the -a option above). This directory con‐
313 tains the state information that must be communicated between invoca‐
314 tions. The operator must remove this directory after the last delta
315 has been applied.
316 xfsrestore also generates a directory named orphanage in the dest
318 directory. xfsrestore removes this directory after completing a simple
319 restore. However, if orphanage is not empty, it is not removed. This
320 can happen if files present on the dump media are not referenced by any
321 of the restored directories. The orphanage has an entry for each such
322 file. The entry name is the file's original inode number, a ".", and
323 the file's generation count modulo 4096 (only the lower 12 bits of the
324 generation count are used).
325 xfsrestore does not remove the orphanage after cumulative restores.
327 Like the xfsrestorehousekeeping directory, the operator must remove it
328 after applying all delta dumps.
329 Media Management
331 A dump consists of one or more media files contained on one or more
332 media objects. A media file contains all or a portion of the filesys‐
333 tem dump. Large filesystems are broken up into multiple media files to
334 minimize the impact of media dropouts, and to accommodate media object
335 boundaries (end-of-media).
336 A media object is any storage medium: a tape cartridge, a remote tape
338 device (see rmt(8)), a regular file, or the standard input (currently
339 other removable media drives are not supported). Tape cartridges can
340 contain multiple media files, which are typically separated by (in tape
341 parlance) file marks. If a dump spans multiple media objects, the
342 restore must begin with the media object containing the first media
343 file dumped. The operator is prompted when the next media object is
344 needed.
345 Media objects can contain more than one dump. The operator can select
347 the desired dump by specifying the dump label (-L option), or by speci‐
348 fying the dump UUID (-S option). If neither is specified, xfsrestore
349 scans the entire media object, prompting the operator as each dump ses‐
350 sion is encountered.
351 The inventory display (-I option) is useful for identifying the media
353 objects required. It is also useful for identifying a dump session.
354 The session UUID can be copied from the inventory display to the -S
355 option argument to unambiguously identify a dump session to be
356 restored.
357 Dumps placed in regular files or the standard output do not span multi‐
359 ple media objects, nor do they contain multiple dumps.
360 Inventory
362 Each dump session updates an inventory database in /var/lib/xfs‐
363 dump/inventory. This database can be displayed by invoking xfsrestore
364 with the -I option. The display uses tabbed indentation to present the
365 inventory hierarchically. The first level is filesystem. The second
366 level is session. The third level is media stream (currently only one
367 stream is supported). The fourth level lists the media files sequen‐
368 tially composing the stream.
369 The following suboptions are available to filter the display.
371 -I depth=n
373 (where n is 1, 2, or 3) limits the hierarchical depth of the dis‐
374 play. When n is 1, only the filesystem information from the inven‐
375 tory is displayed. When n is 2, only filesystem and session infor‐
376 mation are displayed. When n is 3, only filesystem, session and
377 stream information are displayed.
378 -I level=n
380 (where n is the dump level) limits the display to dumps of that
381 particular dump level.
382 The display may be restricted to media files contained in a specific
384 media object.
385 -I mobjid=value
387 (where value is a media ID) specifies the media object by its
388 media ID.
389 -I mobjlabel=value
391 (where value is a media label) specifies the media object by its
392 media label.
393 Similarly, the display can be restricted to a specific filesystem.
395 -I mnt=mount_point
397 (that is, [hostname:]pathname), identifies the filesystem by
398 mountpoint. Specifying the hostname is optional, but may be use‐
399 ful in a clustered environment where more than one host can be
400 responsible for dumping a filesystem.
401 -I fsid=filesystem_id
403 identifies the filesystem by filesystem ID.
404 -I dev=device_pathname
406 (that is, [hostname:]device_pathname) identifies the filesystem by
407 device. As with the mnt filter, specifying the hostname is
408 optional.
409 More than one of these suboptions, separated by commas, may be speci‐
411 fied at the same time to limit the display of the inventory to those
412 dumps of interest. However, at most four suboptions can be specified
413 at once: one to constrain the display hierarchy depth, one to constrain
414 the dump level, one to constrain the media object, and one to constrain
415 the filesystem.
416 For example, -I depth=1,mobjlabel="tape 1",mnt=host1:/test_mnt would
418 display only the filesystem information (depth=1) for those filesystems
419 that were mounted on host1:/test_mnt at the time of the dump, and only
420 those filesystems dumped to the media object labeled "tape 1".
421 Dump records may be removed (pruned) from the inventory using the xfs‐
423 invutil program.
424 An additional media file is placed at the end of each dump stream.
426 This media file contains the inventory information for the current dump
427 session. If the online inventory files in /var/lib/xfsdump/inventory
428 are missing information for the current dump session, then the inven‐
429 tory information in the media file is automatically added to the files
430 in /var/lib/xfsdump/inventory. If you wish to incorporate the inven‐
431 tory information from the media file without restoring any data, you
432 may do so using the -t option:
433 # xfsrestore -t -f /dev/tape
435 This is useful to rebuild the inventory database if it is ever lost or
437 corrupted. The only caveat is that xfsrestore needs to read through
438 the entire dump in order to reach the inventory media file. This could
439 become time consuming for dump sessions with large media files.
440 Media Errors
442 xfsdump is tolerant of media errors, but cannot do error correction.
443 If a media error occurs in the body of a media file, the filesystem
444 file represented at that point is lost. The bad portion of the media
445 is skipped, and the restoration resumes at the next filesystem file
446 after the bad portion of the media.
447 If a media error occurs in the beginning of the media file, the entire
449 media file is lost. For this reason, large dumps are broken into a
450 number of reasonably sized media files. The restore resumes with the
451 next media file.
452 Quotas
454 When xfsdump dumps a filesystem with user quotas, it creates a file in
455 the root of the dump called xfsdump_quotas. xfsrestore can restore
456 this file like any other file included in the dump. This file can be
457 processed by the restore command of xfs_quota(8) to reactivate the quo‐
458 tas. However, the xfsdump_quotas file contains information which may
459 first require modification; specifically the filesystem name and the
460 user ids. If you are restoring the quotas for the same users on the
461 same filesystem from which the dump was taken, then no modification
462 will be necessary. However, if you are restoring the dump to a differ‐
463 ent filesystem, you will need to:
464 - ensure the new filesystem is mounted with the quota option
466 - modify the xfsdump_quotas file to contain the new filesystem name
468 - ensure the uids in the xfsdump_quotas file are correct
470 Once the quota information has been verified, the restore command of
472 xfs_quota [4m(8) can be used to apply the quota limits to the filesystem.
473 Group and project quotas are handled in a similar fashion and will be
475 restored in files called xfsdump_quotas_group and xfsdump_quotas_proj,
476 respectively.
477
479 To restore the root filesystem from a locally mounted tape:
480 # xfsrestore -f /dev/tape /
482 To restore from a remote tape, specifying the dump session id:
484 # xfsrestore -L session_1 -f otherhost:/dev/tape /new
486 To restore the contents a of a dump to another subdirectory:
488 # xfsrestore -f /dev/tape /newdir
490 To copy the contents of a filesystem to another directory (see xfs‐
492 dump(8)):
493 # xfsdump -J - / | xfsrestore -J - /new
495
498 /var/lib/xfsdump/inventory
499 dump inventory database
500
502 rmt(8), xfsdump(8), xfsinvutil(8), xfs_quota(8), attr_set(2).
503
505 The exit code is 0 on normal completion, and non-zero if an error
506 occurred or the restore was terminated by the operator.
507 For all verbosity levels greater than 0 (silent) the final line of the
509 output shows the exit status of the restore. It is of the form:
510 xfsdump: Restore Status: code
512 Where code takes one of the following values: SUCCESS (normal comple‐
514 tion), INTERRUPT (interrupted), QUIT (media no longer usable), INCOM‐
515 PLETE (restore incomplete), FAULT (software error), and ERROR (resource
516 error). Every attempt will be made to keep both the syntax and the
517 semantics of this log message unchanged in future versions of xfsre‐
518 store. However, it may be necessary to refine or expand the set of
519 exit codes, or their interpretation at some point in the future.
520
522 Pathnames of restored non-directory files (relative to the dest direc‐
523 tory) must be 1023 characters (MAXPATHLEN) or less. Longer pathnames
524 are discarded and a warning message displayed.
525 There is no verify option to xfsrestore. This would allow the operator
527 to compare a filesystem dump to an existing filesystem, without actu‐
528 ally doing a restore.
529 The interactive commands (-i option) do not understand regular expres‐
531 sions.
532 When the minimal rmt option is specified, xfsrestore applies it to all
534 remote tape sources. The same blocksize (specified by the -b option) is
535 used for all these remote drives.
536 xfsrestore uses the alert program only when a media change is required.
538 Cumulative mode (-r option) requires that the operator invoke xfsre‐
540 store for the base and for each delta to be applied in sequence to the
541 base. It would be better to allow the operator to identify the last
542 delta in the sequence of interest, and let xfsrestore work backwards
543 from that delta to identify and apply the preceding deltas and base
544 dump, all in one invocation.
545 xfsrestore(8)