| 1 |
.TH xfs_copy 8 |
| 2 |
.SH NAME |
| 3 |
xfs_copy \- copy the contents of an XFS filesystem |
| 4 |
.SH SYNOPSIS |
| 5 |
.B xfs_copy |
| 6 |
[ |
| 7 |
.B \-bd |
| 8 |
] [ |
| 9 |
.B \-L |
| 10 |
.I log |
| 11 |
] |
| 12 |
.I source target1 |
| 13 |
[ |
| 14 |
.I target2 |
| 15 |
\&... ] |
| 16 |
.br |
| 17 |
.B xfs_copy \-V |
| 18 |
.SH DESCRIPTION |
| 19 |
.B xfs_copy |
| 20 |
copies an XFS filesystem to one or more targets in parallel (see |
| 21 |
.BR xfs (5)). |
| 22 |
The first |
| 23 |
.RI ( source ) |
| 24 |
argument must be the pathname of the device or file containing the |
| 25 |
XFS filesystem. The remaining arguments specify one or more |
| 26 |
.I target |
| 27 |
devices or file names. If the pathnames specify devices, a |
| 28 |
copy of the source XFS filesystem is created on each device. The |
| 29 |
.I target |
| 30 |
can also be the name of a regular file, in which case an image of the |
| 31 |
source XFS filesystem is created in that file. If the file does not exist, |
| 32 |
.B xfs_copy |
| 33 |
creates the file. The length of the resulting file is equal to the size |
| 34 |
of the source filesystem. However, if the file is created on an XFS |
| 35 |
filesystem, the file consumes roughly the amount of space actually |
| 36 |
used in the source filesystem by the filesystem and the XFS log. |
| 37 |
The space saving is because |
| 38 |
.B xfs_copy |
| 39 |
seeks over free blocks instead of copying them and the XFS filesystem |
| 40 |
supports sparse files efficiently. |
| 41 |
.PP |
| 42 |
.B xfs_copy |
| 43 |
should only be used to copy unmounted filesystems, read-only mounted |
| 44 |
filesystems, or frozen filesystems (see |
| 45 |
.BR xfs_freeze (8)). |
| 46 |
Otherwise, the generated filesystem(s) would be inconsistent or corrupt. |
| 47 |
.PP |
| 48 |
.B xfs_copy |
| 49 |
does not alter the source filesystem in any way. Each new (target) |
| 50 |
filesystem is identical to the original filesystem except that new |
| 51 |
filesystems each have a new unique filesystem identifier (UUID). |
| 52 |
Therefore, if both the old and new filesystems will be used as |
| 53 |
separate distinct filesystems, |
| 54 |
.B xfs_copy |
| 55 |
or |
| 56 |
.BR xfsdump (8)/ xfsrestore (8) |
| 57 |
should be used to generate the new filesystem(s) instead of |
| 58 |
.BR dd (1) |
| 59 |
or other programs that do block-by-block disk copying. |
| 60 |
.PP |
| 61 |
.B xfs_copy |
| 62 |
uses synchronous writes to ensure that write errors are |
| 63 |
detected. |
| 64 |
.PP |
| 65 |
.B xfs_copy |
| 66 |
uses |
| 67 |
.BR pthreads (7) |
| 68 |
to perform simultaneous parallel writes. |
| 69 |
.B xfs_copy |
| 70 |
creates one additional thread for each target to be written. |
| 71 |
All threads die if |
| 72 |
.B xfs_copy |
| 73 |
terminates or aborts. |
| 74 |
.SH OPTIONS |
| 75 |
.TP |
| 76 |
.B \-d |
| 77 |
Create a duplicate (true clone) filesystem. This should be done only |
| 78 |
if the new filesystem will be used as a replacement for the original |
| 79 |
filesystem (such as in the case of disk replacement). |
| 80 |
.TP |
| 81 |
.B \-b |
| 82 |
The buffered option can be used to ensure direct IO is not attempted |
| 83 |
to any of the target files. This is useful when the filesystem holding |
| 84 |
the target file does not support direct IO. |
| 85 |
.TP |
| 86 |
.BI \-L " log" |
| 87 |
Specifies the location of the |
| 88 |
.I log |
| 89 |
if the default location of |
| 90 |
.I /var/tmp/xfs_copy.log.XXXXXX |
| 91 |
is not desired. |
| 92 |
.TP |
| 93 |
.B \-V |
| 94 |
Prints the version number and exits. |
| 95 |
.SH DIAGNOSTICS |
| 96 |
.B xfs_copy |
| 97 |
reports errors to both |
| 98 |
.B stderr |
| 99 |
and in more detailed form to a generated log file whose name is of the form |
| 100 |
.I /var/tmp/xfs_copy.log.XXXXXX |
| 101 |
or a log file specified by the |
| 102 |
.B \-L |
| 103 |
option. If |
| 104 |
.B xfs_copy |
| 105 |
detects a write error on a target, the copy of that one target is aborted |
| 106 |
and an error message is issued to both stderr and the log file, but |
| 107 |
the rest of the copies continue. When |
| 108 |
.B xfs_copy |
| 109 |
terminates, all aborted targets are reported to both |
| 110 |
.B stderr |
| 111 |
and the log file. |
| 112 |
.PP |
| 113 |
If all targets abort or if there is an error reading the source filesystem, |
| 114 |
.B xfs_copy |
| 115 |
immediately aborts. |
| 116 |
.PP |
| 117 |
.B xfs_copy |
| 118 |
returns an exit code of 0 if all targets are successfully |
| 119 |
copied and an exit code of 1 if any target fails. |
| 120 |
.SH NOTES |
| 121 |
When moving filesystems from one disk to another, if the original |
| 122 |
filesystem is significantly smaller than the new filesystem, and will |
| 123 |
be made larger, we recommend that |
| 124 |
.BR mkfs.xfs "(8) and " xfsdump (8)/ xfsrestore (8) |
| 125 |
be used instead of using |
| 126 |
.B xfs_copy |
| 127 |
and |
| 128 |
.BR xfs_growfs (8). |
| 129 |
The filesystem layout resulting from using |
| 130 |
.BR xfs_copy / xfs_growfs |
| 131 |
is almost always worse than the result of using |
| 132 |
.BR mkfs.xfs / xfsdump / xfsrestore |
| 133 |
but in the case of small filesystems, the differences can have a |
| 134 |
significant performance impact. This is due to the way |
| 135 |
.BR xfs_growfs (8) |
| 136 |
works, and not due to any shortcoming in |
| 137 |
.B xfs_copy |
| 138 |
itself. |
| 139 |
.SH CAVEATS |
| 140 |
.B xfs_copy |
| 141 |
does not copy XFS filesystems that have a real-time section |
| 142 |
or XFS filesystems with external logs. In both cases, |
| 143 |
.B xfs_copy |
| 144 |
aborts with an error message. |
| 145 |
.SH SEE ALSO |
| 146 |
.BR mkfs.xfs (8), |
| 147 |
.BR xfsdump (8), |
| 148 |
.BR xfsrestore (8), |
| 149 |
.BR xfs_freeze (8), |
| 150 |
.BR xfs_growfs (8), |
| 151 |
.BR xfs (5). |