Debian Codegraph @

upstream/debian-unstable/man8/xfs_copy.8

raw
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).