1xfsdump(8) System Manager's Manual xfsdump(8)
2
6 xfsdump - XFS filesystem incremental dump utility
7
9 xfsdump -h
10 xfsdump [ options ] -f dest [ -f dest ... ] filesystem
11 xfsdump [ options ] - filesystem
12 xfsdump -I [ subopt=value ... ]
13
15 xfsdump backs up files and their attributes in a filesystem. The files
16 are dumped to storage media, a regular file, or standard output.
17 Options allow the operator to have all files dumped, just files that
18 have changed since a previous dump, or just files contained in a list
19 of pathnames.
20 The xfsrestore(8) utility re-populates a filesystem with the contents
22 of the dump.
23 Each invocation of xfsdump dumps just one filesystem. That invocation
25 is termed a dump session. The dump session splits the filesystem into
26 one or more dump streams, one per destination. The split is done in
27 filesystem inode number (ino) order, at boundaries selected to equalize
28 the size of each stream. Furthermore, the breakpoints between streams
29 may be in the middle of very large files (at extent boundaries) if nec‐
30 essary to achieve reasonable stream size equalization. Each dump
31 stream can span several media objects, and a single media object can
32 contain several dump streams. The typical media object is a tape car‐
33 tridge. The media object records the dump stream as one or more media
34 files. A media file is a self-contained partial dump, intended to min‐
35 imize the impact of media dropouts on the entire dump stream at the
36 expense of increasing the time required to complete the dump. By
37 default only one media file is written unless a media file size is
38 specified using the -d option. Other techniques, such as making a sec‐
39 ond copy of the dump image, provide more protection against media fail‐
40 ures than multiple media files will.
41 xfsdump maintains an online dump inventory in /var/lib/xfsdump/inven‐
43 tory. The -I option displays the inventory contents hierarchically.
44 The levels of the hierarchy are: filesystem, dump session, stream, and
45 media file.
46 The options to xfsdump are:
48 -a Specifies that files for which the Data Migration Facility (DMF)
50 has complete offline copies (dual-state files) be treated as if
51 they were offline (OFL). This means that the file data will not
52 be dumped by xfsdump, resulting in a smaller dump file. If the
53 file is later restored the file data is still accessible through
54 DMF. If both '-a option' and '-z option' are specified, the '-a
55 option' takes precedence (see '-z option' below).
56 -b blocksize
58 Specifies the blocksize, in bytes, to be used for the dump. The
59 same blocksize must be specified to restore the tape. If the -m
60 option is not used, then -b does not need to be specified.
61 Instead, a default blocksize of 1Mb will be used.
62 -c progname
64 Use the specified program to alert the operator when a media
65 change is required. The alert program is typically a script to
66 send a mail or flash a window to draw the operator's attention.
67 -d filesize
69 Specifies the size, in megabytes, of dump media files. If not
70 specified, xfsdump will dump data to tape using a single media
71 file per media object. The specified media file size may need to
72 be adjusted if, for example, xfsdump cannot fit a media file onto
73 a single tape.
74 -e Allow files to be excluded from the dump. This will cause xfsdump
76 to skip files which have the "no dump" file attribute set. See the
77 "Excluding individual files" section below for details on setting
78 this file attribute.
79 -f dest [ -f dest ... ]
81 Specifies a dump destination. A dump destination can be the path‐
82 name of a device (such as a tape drive), a regular file or a
83 remote tape drive (see rmt(8)). This option must be omitted if
84 the standard output option (a lone - preceding the source filesys‐
85 tem specification) is specified.
86 -l level
88 Specifies a dump level of 0 to 9. The dump level determines the
89 base dump to which this dump is relative. The base dump is the
90 most recent dump at a lesser level. A level 0 dump is absolute -
91 all files are dumped. A dump level where 1 <= level <= 9 is
92 referred to as an incremental dump. Only files that have been
93 changed since the base dump are dumped. Subtree dumps (see the -s
94 option below) cannot be used as the base for incremental dumps.
95 -m Use the minimal tape protocol for non-scsi tape destinations or
97 remote tape destinations which are not scsi Linux tape drives nor
98 IRIX tape drives. This option cannot be used without specifying a
99 blocksize to be used (see -b option above).
100 -o Overwrite the tape. With this option, xfsdump does not read the
102 tape first to check the contents. This option may be used if xfs‐
103 dump is unable to determine the block size of a tape .
104 -p interval
106 Causes progress reports to be printed at the specified interval.
107 interval is given in seconds. The progress report indicates how
108 many files have been dumped, the total number of files to dump,
109 the percentage of data dumped, and the elapsed time.
110 -q Destination tape drive is a QIC tape. QIC tapes only use a 512
112 byte blocksize, for which xfsdump must make special allowances.
113 -s pathname [ -s pathname ... ]
115 Restricts the dump to files contained in the specified pathnames
116 (subtrees). A pathname must be relative to the mount point of the
117 filesystem. For example, if a filesystem is mounted at /d2, the
118 pathname argument for the directory /d2/users is ``users''. A
119 pathname can be a file or a directory; if it is a directory, the
120 entire hierarchy of files and subdirectories rooted at that direc‐
121 tory is dumped. Subtree dumps cannot be used as the base for
122 incremental dumps (see the -l option above).
123 -t file
125 Sets the dump time to the modification time of file rather than
126 using the current time. xfsdump uses the dump time to determine
127 what files need to be backed up during an incremental dump. This
128 option should be used when dumping snapshots so that the dump time
129 matches the time the snapshot was taken. Otherwise files modified
130 after a snapshot is taken may be skipped in the next incremental
131 dump.
132 -v verbosity
134 -v subsys=verbosity[,subsys=verbosity,...]
135 Specifies the level of detail used for messages displayed during
136 the course of the dump. The verbosity argument can be passed as
137 either a string or an integer. If passed as a string the following
138 values may be used: silent, verbose, trace, debug, or nitty. If
139 passed as an integer, values from 0-5 may be used. The values 0-4
140 correspond to the strings already listed. The value 5 can be used
141 to produce even more verbose debug output.
142 The first form of this option activates message logging across all
144 dump subsystems. The second form allows the message logging level
145 to be controlled on a per-subsystem basis. The two forms can be
146 combined (see the example below). The argument subsys can take one
147 of the following values: general, proc, drive, media, inventory,
148 inomap and excluded_files.
149 For example, to dump the root filesystem with tracing activated
151 for all subsystems:
152 # xfsdump -v trace -f /dev/tape /
154 To enable debug-level tracing for drive and media operations:
156 # xfsdump -v drive=debug,media=debug -f /dev/tape /
158 To enable tracing for all subsystems, and debug level tracing for
160 drive operations only:
161 # xfsdump -v trace,drive=debug -f /dev/tape /
163 To list files that will be excluded from the dump:
165 # xfsdump -e -v excluded_files=debug -f /dev/tape /
167 -z size
170 Specifies the maximum size, in kilobytes, of files to be included
171 in the dump. Files over this size, will be excluded from the
172 dump, except for DMF dual-state files when '-a option' is speci‐
173 fied (see '-a option' above). When specified, '-a option' takes
174 precedence over '-z option'. The size is an estimate based on the
175 number of disk blocks actually used by the file, and so does not
176 include holes. In other words, size refers to the amount of space
177 the file would take in the resulting dump. On an interactive
178 restore, the skipped file is visible with xfsrestore's 'ls' and
179 while you can use the 'add' and 'extract' commands, nothing will
180 be restored.
181 -A Do not dump extended file attributes. When dumping a filesystem
183 managed within a DMF environment this option should not be used.
184 DMF stores file migration status within extended attributes asso‐
185 ciated with each file. If these attributes are not preserved when
186 the filesystem is restored, files that had been in migrated state
187 will not be recallable by DMF. Note that dumps containing extended
188 file attributes cannot be restored with older versions of xfsre‐
189 store(8).
190 -B session_id
192 Specifies the ID of the dump session upon which this dump session
193 is to be based. If this option is specified, the -l (level) and
194 -R (resume) options are not allowed. Instead, xfsdump determines
195 if the current dump session should be incremental and/or resumed,
196 by looking at the base session's level and interrupted attributes.
197 If the base session was interrupted, the current dump session is a
198 resumption of that base at the same level. Otherwise, the current
199 dump session is an incremental dump with a level one greater than
200 that of the base session. This option allows incremental and
201 resumed dumps to be based on any previous dump, rather than just
202 the most recent.
203 -D Controls which directories are backed up during an incremental
205 dump. By default unchanged directories are dumped if files or
206 directories beneath them have changed. This results in a self-con‐
207 tained dump -- if a base dump is lost, or you know the file(s) you
208 wish to restore is in an incremental dump, you can restore just
209 that dump without loading the base dump(s) first. However, this
210 method requires a potentially expensive traversal through the
211 filesystem.
212 When -D is specified, unchanged directories are not dumped. This
214 results in a faster dump, but files will end up in the xfsre‐
215 store(8) orphanage directory unless the base dump(s) is loaded
216 first.
217 -E Pre-erase media. If this option is specified, media is erased
219 prior to use. The operator is prompted for confirmation, unless
220 the -F option is also specified.
221 -F Don't prompt the operator. When xfsdump encounters a media object
223 containing non-xfsdump data, xfsdump normally asks the operator
224 for permission to overwrite. With this option the overwrite is
225 performed, no questions asked. When xfsdump encounters end-of-
226 media during a dump, xfsdump normally asks the operator if another
227 media object will be provided. With this option the dump is
228 instead interrupted.
229 -I Displays the xfsdump inventory (no dump is performed). xfsdump
231 records each dump session in an online inventory in /var/lib/xfs‐
232 dump/inventory. xfsdump uses this inventory to determine the base
233 for incremental dumps. It is also useful for manually identifying
234 a dump session to be restored. Suboptions to filter the inventory
235 display are described later.
236 -J Inhibits the normal update of the inventory. This is useful when
238 the media being dumped to will be discarded or overwritten.
239 -K Generate a format 2 dump instead of the current format. This is
241 useful if the dump will be restored on a system with an older xfs‐
242 restore which does not understand the current dump format. Use of
243 this option is otherwise not recommended.
244 -L session_label
246 Specifies a label for the dump session. It can be any arbitrary
247 string up to 255 characters long.
248 -M label [ -M label ... ]
250 Specifies a label for the first media object (for example, tape
251 cartridge) written on the corresponding destination during the
252 session. It can be any arbitrary string up to 255 characters
253 long. Multiple media object labels can be specified, one for each
254 destination.
255 -O options_file
257 Insert the options contained in options_file into the beginning of
258 the command line. The options are specified just as they would
259 appear if typed into the command line. In addition, newline char‐
260 acters (\n) can be used as whitespace. The options are placed
261 before all options actually given on the command line, just after
262 the command name. Only one -O option can be used. Recursive use
263 is ignored. The source filesystem cannot be specified in
264 options_file.
265 -R Resumes a previously interrupted dump session. If the most recent
267 dump at this dump's level (-l option) was interrupted, this dump
268 contains only files not in the interrupted dump and consistent
269 with the incremental level. However, files contained in the
270 interrupted dump that have been subsequently modified are re-
271 dumped.
272 -T Inhibits interactive dialogue timeouts. When the -F option is not
274 specified, xfsdump prompts the operator for labels and media
275 changes. Each dialogue normally times out if no response is sup‐
276 plied. This option prevents the timeout.
277 -Y length
279 Specify I/O buffer ring length. xfsdump uses a ring of output
280 buffers to achieve maximum throughput when dumping to tape drives.
281 The default ring length is 3. However, this is not currently
282 enabled on Linux yet, making this option benign.
283 - A lone - causes the dump stream to be sent to the standard output,
285 where it can be piped to another utility such as xfsrestore(8) or
286 redirected to a file. This option cannot be used with the -f
287 option. The - must follow all other options and precede the
288 filesystem specification.
289 The filesystem, filesystem, can be specified either as a mount point or
291 as a special device file (for example, /dev/dsk/dks0d1s0). The
292 filesystem must be mounted to be dumped.
293
295 Dump Interruption
296 A dump can be interrupted at any time and later resumed. To interrupt,
297 type control-C (or the current terminal interrupt character). The
298 operator is prompted to select one of several operations, including
299 dump interruption. After the operator selects dump interruption, the
300 dump continues until a convenient break point is encountered (typically
301 the end of the current file). Very large files are broken into smaller
302 subfiles, so the wait for the end of the current file is brief.
303 Dump Resumption
305 A previously interrupted dump can be resumed by specifying the -R
306 option. If the most recent dump at the specified level was inter‐
307 rupted, the new dump does not include files already dumped, unless they
308 have changed since the interrupted dump.
309 Media Management
311 A single media object can contain many dump streams. Conversely, a
312 single dump stream can span multiple media objects. If a dump stream
313 is sent to a media object already containing one or more dumps, xfsdump
314 appends the new dump stream after the last dump stream. Media files
315 are never overwritten. If end-of-media is encountered during the
316 course of a dump, the operator is prompted to insert a new media object
317 into the drive. The dump stream continuation is appended after the
318 last media file on the new media object.
319 Inventory
321 Each dump session updates an inventory database in /var/lib/xfs‐
322 dump/inventory. xfsdump uses the inventory to determine the base of
323 incremental and resumed dumps.
324 This database can be displayed by invoking xfsdump with the -I option.
326 The display uses tabbed indentation to present the inventory hierarchi‐
327 cally. The first level is filesystem. The second level is session.
328 The third level is media stream (currently only one stream is sup‐
329 ported). The fourth level lists the media files sequentially composing
330 the stream.
331 The following suboptions are available to filter the display.
333 -I depth=n
335 (where n is 1, 2, or 3) limits the hierarchical depth of the dis‐
336 play. When n is 1, only the filesystem information from the inven‐
337 tory is displayed. When n is 2, only filesystem and session infor‐
338 mation are displayed. When n is 3, only filesystem, session and
339 stream information are displayed.
340 -I level=n
342 (where n is the dump level) limits the display to dumps of that
343 particular dump level.
344 The display may be restricted to media files contained in a specific
346 media object.
347 -I mobjid=value
349 (where value is a media ID) specifies the media object by its
350 media ID.
351 -I mobjlabel=value
353 (where value is a media label) specifies the media object by its
354 media label.
355 Similarly, the display can be restricted to a specific filesystem.
357 -I mnt=mount_point
359 (that is, [hostname:]pathname), identifies the filesystem by
360 mountpoint. Specifying the hostname is optional, but may be use‐
361 ful in a clustered environment where more than one host can be
362 responsible for dumping a filesystem.
363 -I fsid=filesystem_id
365 identifies the filesystem by filesystem ID.
366 -I dev=device_pathname
368 (that is, [hostname:]device_pathname) identifies the filesystem by
369 device. As with the mnt filter, specifying the hostname is
370 optional.
371 More than one of these suboptions, separated by commas, may be speci‐
373 fied at the same time to limit the display of the inventory to those
374 dumps of interest. However, at most four suboptions can be specified
375 at once: one to constrain the display hierarchy depth, one to constrain
376 the dump level, one to constrain the media object, and one to constrain
377 the filesystem.
378 For example, -I depth=1,mobjlabel="tape 1",mnt=host1:/test_mnt would
380 display only the filesystem information (depth=1) for those filesystems
381 that were mounted on host1:/test_mnt at the time of the dump, and only
382 those filesystems dumped to the media object labeled "tape 1".
383 Dump records may be removed (pruned) from the inventory using the xfs‐
385 invutil program.
386 An additional media file is placed at the end of each dump stream.
388 This media file contains the inventory information for the current dump
389 session. Its contents may be merged back into the online inventory
390 database at a later time using xfsrestore(1M).
391 The inventory files stored in /var/lib/xfsdump are not included in the
393 dump, even if that directory is contained within the filesystem being
394 dumped. Including the inventory in the dump may lead to loss or cor‐
395 ruption of data, should an older version be restored overwriting the
396 current version. To backup the xfsdump inventory, the contents of
397 /var/lib/xfsdump should be copied to another location which may then be
398 safely dumped. Upon restoration, those files may be copied back into
399 /var/lib/xfsdump, overwriting whatever files may be there, or xfsinvu‐
400 til(1M) may be used to selectively merge parts of the restored inven‐
401 tory back into the current inventory. Prior to version 1.1.8, xfsdump
402 would include the /var/lib/xfsdump directory in the dump. Care should
403 be taken not to overwrite the /var/lib/xfsdump directory when restoring
404 an old dump, by either restoring the filesystem to another location or
405 by copying the current contents of /var/lib/xfsdump to a safe place
406 prior to running xfsrestore(1M).
407 Labels
409 The operator can specify a label to identify the dump session and a
410 label to identify a media object. The session label is placed in every
411 media file produced in the course of the dump, and is recorded in the
412 inventory.
413 The media label is used to identify media objects, and is independent
415 of the session label. Each media file on the media object contains a
416 copy of the media label. An error is returned if the operator speci‐
417 fies a media label that does not match the media label on a media
418 object containing valid media files. Media labels are recorded in the
419 inventory.
420 UUIDs
422 UUIDs (Universally Unique Identifiers) are used in three places: to
423 identify the filesystem being dumped (using the filesystem UUID, see
424 xfs(5) for more details), to identify the dump session, and to identify
425 each media object. The inventory display (-I) includes all of these.
426 Dump Level Usage
428 The dump level mechanism provides a structured form of incremental
429 dumps. A dump of level level includes only files that have changed
430 since the most recent dump at a level less than level. For example,
431 the operator can establish a dump schedule that involves a full dump
432 every Friday and a daily incremental dump containing only files that
433 have changed since the previous dump. In this case Friday's dump would
434 be at level 0, Saturday's at level 1, Sunday's at level 2, and so on,
435 up to the Thursday dump at level 6.
436 The above schedule results in a very tedious restore procedure to fully
438 reconstruct the Thursday version of the filesystem; xfsrestore would
439 need to be fed all 7 dumps in sequence. A compromise schedule is to
440 use level 1 on Saturday, Monday, and Wednesday, and level 2 on Sunday,
441 Tuesday, and Thursday. The Monday and Wednesday dumps would take
442 longer, but the worst case restore requires the accumulation of just
443 three dumps, one each at level 0, level 1, and level 2.
444 Quotas
446 If the filesystem being dumped contains user quotas, xfsdump will use
447 xfs_quota(8) to store the quotas in a file called xfsdump_quotas in the
448 root of the filesystem to be dumped. This file will then be included in
449 the dump. Upon restoration, xfs_quota [4m(8) can be used to reactivate
450 the quotas for the filesystem. Note, however, that the xfsdump_quotas
451 file will probably require modification to change the filesystem or
452 UIDs if the filesystem has been restored to a different partition or
453 system. Group and project quotas will be handled in a similar fashion
454 and saved in files called xfsdump_quotas_group and xfsdump_quotas_proj
455 , respectively.
456 Excluding individual files
458 It may be desirable to exclude particular files or directories from the
459 dump. The -s option can be used to limit the dump to a specified
460 directory, and the -z option can be used to exclude files over a par‐
461 ticular size. Additionally, when xfsdump is run with the -e option,
462 files that are tagged with the "no dump" file attribute will not be
463 included in the dump. The chattr(1) command can be used to set this
464 attribute on individual files or entire subtrees.
465 To tag an individual file for exclusion from the dump:
467 $ chattr +d file
469 To tag all files in a subtree for exclusion from the dump:
471 $ chattr -R +d directory
473 Note that any new files or directories created in a directory which has
475 the "no dump" attribute set will automatically inherit this attribute.
476 Also note that xfsdump does not check directories for the "no dump"
477 attribute.
478 Care should be taken to note which files have been tagged. Under nor‐
480 mal operation, xfsdump will only report the number of files it will
481 skip. The -v excluded_files=debug option, however, will cause xfsdump
482 to list the inode numbers of the individual files affected.
483
485 To perform a level 0, single stream dump of the root filesystem to a
486 locally mounted tape drive, prompting for session and media labels when
487 required:
488 # xfsdump -f /dev/tape /
490 To specify session and media labels explicitly:
492 # xfsdump -L session_1 -M tape_0 -f /dev/tape /
494 To perform a dump to a remote tape using the minimal rmt protocol and a
496 set blocksize of 64k:
497 # xfsdump -m -b 65536 -f otherhost:/dev/tape /
499 To perform a level 0, multi-stream dump to two locally mounted tape
501 drives:
502 # xfsdump -L session_2 -f /dev/rmt/tps4d6v -M tape_1 \
504 -f /dev/rmt/tps5d6v -M tape_2 /
505 To perform a level 1 dump relative to the last level 0 dump recorded in
507 the inventory:
508 # xfsdump -l 1 -f /dev/tape /
510 To copy the contents of a filesystem to another directory (see xfsre‐
512 store(8)):
513 # xfsdump -J - / | xfsrestore -J - /new
515
518 /var/lib/xfsdump/inventory
519 dump inventory database
520
522 attr(1), rmt(8), xfsrestore(8), xfsinvutil(8), xfs_quota(8),
523 attr_get(2).
524
526 The exit code is 0 on normal completion, non-zero if an error occurs or
527 the dump is terminated by the operator.
528 For all verbosity levels greater than 0 (silent) the final line of the
530 output shows the exit status of the dump. It is of the form:
531 xfsdump: Dump Status: code
533 Where code takes one of the following values: SUCCESS (normal comple‐
535 tion), INTERRUPT (interrupted), QUIT (media no longer usable), INCOM‐
536 PLETE (dump incomplete), FAULT (software error), and ERROR (resource
537 error). Every attempt will be made to keep both the syntax and the
538 semantics of this log message unchanged in future versions of xfsdump.
539 However, it may be necessary to refine or expand the set of exit codes,
540 or their interpretation at some point in the future.
541 The message ``xfsdump: WARNING: unable to open directory: ino N:
543 Invalid argument'' can occur with filesystems which are actively being
544 modified while xfsdump is running. This can happen to either directory
545 or regular file inodes - affected files will not end up in the dump,
546 files below affected directories will be placed in the orphanage direc‐
547 tory by xfsrestore.
548
550 xfsdump does not dump unmounted filesystems.
551 The dump frequency field of /etc/fstab is not supported.
553 xfsdump uses the alert program only when a media change is required.
555 xfsdump requires root privilege (except for inventory display).
557 xfsdump can only dump XFS filesystems.
559 The media format used by xfsdump can only be understood by xfsrestore.
561 xfsdump does not know how to manage CD-ROM or other removable disk
563 drives.
564 xfsdump can become confused when doing incremental or resumed dumps if
566 on the same machine you dump two XFS filesystems and both filesystems
567 have the same filesystem identifier (UUID). Since xfsdump uses the
568 filesystem identifier to identify filesystems, xfsdump maintains one
569 combined set of dump inventories for both filesystems instead of two
570 sets of dump inventories. This scenario can happen only if dd or some
571 other block-by-block copy program was used to make a copy of an XFS
572 filesystem. See xfs_copy(8) and xfs(5) for more details.
573 xfsdump(8)