diff options
Diffstat (limited to 'upstream/debian-bookworm/man8/xfs_copy.8')
| -rw-r--r-- | upstream/debian-bookworm/man8/xfs_copy.8 | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man8/xfs_copy.8 b/upstream/debian-bookworm/man8/xfs_copy.8 new file mode 100644 index 00000000..1eaf85d5 --- /dev/null +++ b/upstream/debian-bookworm/man8/xfs_copy.8 @@ -0,0 +1,151 @@ +.TH xfs_copy 8 +.SH NAME +xfs_copy \- copy the contents of an XFS filesystem +.SH SYNOPSIS +.B xfs_copy +[ +.B \-bd +] [ +.B \-L +.I log +] +.I source target1 +[ +.I target2 +\&... ] +.br +.B xfs_copy \-V +.SH DESCRIPTION +.B xfs_copy +copies an XFS filesystem to one or more targets in parallel (see +.BR xfs (5)). +The first +.RI ( source ) +argument must be the pathname of the device or file containing the +XFS filesystem. The remaining arguments specify one or more +.I target +devices or file names. If the pathnames specify devices, a +copy of the source XFS filesystem is created on each device. The +.I target +can also be the name of a regular file, in which case an image of the +source XFS filesystem is created in that file. If the file does not exist, +.B xfs_copy +creates the file. The length of the resulting file is equal to the size +of the source filesystem. However, if the file is created on an XFS +filesystem, the file consumes roughly the amount of space actually +used in the source filesystem by the filesystem and the XFS log. +The space saving is because +.B xfs_copy +seeks over free blocks instead of copying them and the XFS filesystem +supports sparse files efficiently. +.PP +.B xfs_copy +should only be used to copy unmounted filesystems, read-only mounted +filesystems, or frozen filesystems (see +.BR xfs_freeze (8)). +Otherwise, the generated filesystem(s) would be inconsistent or corrupt. +.PP +.B xfs_copy +does not alter the source filesystem in any way. Each new (target) +filesystem is identical to the original filesystem except that new +filesystems each have a new unique filesystem identifier (UUID). +Therefore, if both the old and new filesystems will be used as +separate distinct filesystems, +.B xfs_copy +or +.BR xfsdump (8)/ xfsrestore (8) +should be used to generate the new filesystem(s) instead of +.BR dd (1) +or other programs that do block-by-block disk copying. +.PP +.B xfs_copy +uses synchronous writes to ensure that write errors are +detected. +.PP +.B xfs_copy +uses +.BR pthreads (7) +to perform simultaneous parallel writes. +.B xfs_copy +creates one additional thread for each target to be written. +All threads die if +.B xfs_copy +terminates or aborts. +.SH OPTIONS +.TP +.B \-d +Create a duplicate (true clone) filesystem. This should be done only +if the new filesystem will be used as a replacement for the original +filesystem (such as in the case of disk replacement). +.TP +.B \-b +The buffered option can be used to ensure direct IO is not attempted +to any of the target files. This is useful when the filesystem holding +the target file does not support direct IO. +.TP +.BI \-L " log" +Specifies the location of the +.I log +if the default location of +.I /var/tmp/xfs_copy.log.XXXXXX +is not desired. +.TP +.B \-V +Prints the version number and exits. +.SH DIAGNOSTICS +.B xfs_copy +reports errors to both +.B stderr +and in more detailed form to a generated log file whose name is of the form +.I /var/tmp/xfs_copy.log.XXXXXX +or a log file specified by the +.B \-L +option. If +.B xfs_copy +detects a write error on a target, the copy of that one target is aborted +and an error message is issued to both stderr and the log file, but +the rest of the copies continue. When +.B xfs_copy +terminates, all aborted targets are reported to both +.B stderr +and the log file. +.PP +If all targets abort or if there is an error reading the source filesystem, +.B xfs_copy +immediately aborts. +.PP +.B xfs_copy +returns an exit code of 0 if all targets are successfully +copied and an exit code of 1 if any target fails. +.SH NOTES +When moving filesystems from one disk to another, if the original +filesystem is significantly smaller than the new filesystem, and will +be made larger, we recommend that +.BR mkfs.xfs "(8) and " xfsdump (8)/ xfsrestore (8) +be used instead of using +.B xfs_copy +and +.BR xfs_growfs (8). +The filesystem layout resulting from using +.BR xfs_copy / xfs_growfs +is almost always worse than the result of using +.BR mkfs.xfs / xfsdump / xfsrestore +but in the case of small filesystems, the differences can have a +significant performance impact. This is due to the way +.BR xfs_growfs (8) +works, and not due to any shortcoming in +.B xfs_copy +itself. +.SH CAVEATS +.B xfs_copy +does not copy XFS filesystems that have a real-time section +or XFS filesystems with external logs. In both cases, +.B xfs_copy +aborts with an error message. +.SH SEE ALSO +.BR mkfs.xfs (8), +.BR xfsdump (8), +.BR xfsrestore (8), +.BR xfs_freeze (8), +.BR xfs_growfs (8), +.BR xfs (5). |