kernel - Disable vmm by default
[dragonfly.git] / bin / cpdup / cpdup.1
blobb705835928aaa7c62b1d1f8c1d6c3a04dbef7493
1 .\" (c) Copyright 1997-2010 by Matthew Dillon, Dima Ruban, and Oliver Fromme.
2 .\"    Permission to use and distribute based on the DragonFly copyright.
3 .\"    Supplied as-is, USE WITH CAUTION.
4 .\"
5 .Dd November 24, 2009
6 .Dt CPDUP 1
7 .Os
8 .Sh NAME
9 .Nm cpdup
10 .Nd mirror filesystems
11 .Sh SYNOPSIS
12 .Nm
13 .Op Fl C
14 .Op Fl v Ns Op Cm v Ns Op Cm v
15 .Op Fl d
16 .Op Fl n
17 .Op Fl u
18 .Op Fl I
19 .Op Fl f
20 .Op Fl F Ar ssh-arg
21 .Op Fl s0
22 .Op Fl i0
23 .Op Fl j0
24 .Op Fl l
25 .Op Fl q
26 .Op Fl o
27 .Op Fl m
28 .Op Fl H Ar path
29 .Op Fl M Ar file
30 .Op Fl V
31 .Op Fl VV
32 .Op Fl S
33 .Op Fl R
34 .Op Fl k
35 .Op Fl K Ar file
36 .Op Fl X Ar file
37 .Op Fl x
38 .Oo Oo Ar user Ns Li @ Oc Ns Ar host : Oc Ns Ar source_dir
39 .Oo Oo Ar user Ns Li @ Oc Ns Ar host : Oc Ns Ar target_dir
40 .Sh DESCRIPTION
41 The
42 .Nm
43 utility makes an exact mirror copy of the source in the destination, creating
44 and deleting files and directories as necessary.  UTimes, hardlinks,
45 softlinks, devices, permissions, and flags are mirrored.  By default,
46 .Nm
47 asks for confirmation if any file or directory needs to be removed from
48 the destination and does not copy files which it believes to have already
49 been synchronized (by observing that the source and destination files' sizes
50 and mtimes match).
51 .Nm
52 does not cross mount points in either the source or the destination.
53 As a safety measure,
54 .Nm
55 refuses to replace a destination directory with a file.
56 .Pp
57 The following options are available:
58 .Bl -tag -width flag
59 .It Fl C
60 If the source or target is a remote host, request that the
61 .Xr ssh 1
62 session be compressed.
63 This is the same as
64 .Fl F
65 .Fl C .
66 .It Fl v Ns Op Cm v Ns Op Cm v
67 Set verboseness.  By default
68 .Nm
69 does not report its progress except when asking for confirmation.  A single
70 .Fl v
71 will only report modifications made to the destination.
72 .Fl vv
73 will report directories as they are being traversed as well as
74 modifications made to the destination.
75 .Fl vvv
76 will cause all files and directories to be reported whether or not
77 modifications are made.
78 .It Fl d
79 Print directories as they are being traversed.
80 Useful to watch the progress;
81 this typically produces much less output than
82 .Fl vv .
83 .It Fl n
84 Go through the motions but don't actually make any changes to
85 the target.
86 .It Fl u
87 Causes the output generated by
88 .Fl v
89 and
90 .Fl d
91 to be unbuffered.
92 This can be useful for obtaining prompt progress updates through a pipe.
93 .It Fl I
94 will cause
95 .Nm
96 to print a summary at the end with performance counters.
97 .It Fl f
98 Forces file updates to occur even if the files appear to be the same.  If
99 the
100 .Fl H
101 option is used, this option will force a byte for byte comparison
102 between the original file and the file in the hardlink path, even if
103 all the stat info matches, but will still use a hardlink if they match.
104 .It Fl F Ar ssh-arg
105 Pass
106 .Ar ssh-arg
107 to ssh.  For example
108 .Dq Fl F Fl p222 .
109 Note the lack of a space.
110 .It Fl s0
111 Disable the disallow-file-replaces-directory safety feature.  This
112 safety feature is enabled by default to prevent user mistakes from blowing
113 away everything accidentally.
114 .It Fl i0
115 Do not request confirmation when removing something.
116 .It Fl j0
117 Do not try to recreate CHR or BLK devices.
118 .It Fl l
119 Line buffer verbose output.
120 .It Fl q
121 Quiet operation.
122 .It Fl o
123 Do not remove any files, just overwrite/add.
124 .It Fl m
125 Generate and maintain a MD5 checkfile called
126 .Pa \&.MD5.CHECKSUMS
127 in each directory on the source
128 and do an MD5 check on each file of the destination when the destination
129 appears to be the same as the source.  If the check fails,
130 the source is recopied to the destination.  When you specify a destination
131 directory, the MD5 checkfile is only updated as needed and may not be updated
132 even if modifications are made to a source file.  If you do not specify a
133 destination directory the
135 command forcefully regenerates the MD5 checkfile for every file in the source.
136 .It Fl M Ar file
137 Works the same as
138 .Fl m
139 but allows you to specify the name of the MD5 checkfile.
140 .It Fl H Ar path
142 will create a hardlink from a file found under
143 .Ar path
144 to the target instead of copying the source to the target if the file found
146 .Ar path
147 is identical to the source.
148 Note that a remote host specification should not be used for this option's
149 .Ar path ,
150 but the
151 .Ar path
152 will be relative to the target machine.
154 This allows one to use
156 to create incremental backups of a filesystem.  Create a direct
157 .Sq level 0
158 backup, and then specify the level 0 backup path with this option when
159 creating an incremental backup to a different target directory.
160 This method works so long as the filesystem does not hit a hardlink limit.
161 If the system does hit a hardlink limit,
163 will generate a warning and copy the file instead.
164 Note that
166 must record file paths for any hardlinked file while operating and therefore
167 uses a great deal more memory when dealing with hardlinks or hardlink-based
168 backups.  Example use:
170 .Dl cpdup \-i0 \-s0 \-I \-H /backup/home.l0 /home /backup/home.l1
172 WARNING: If this option is used
174 must record the paths for all files it encounters while it operates
175 and it is possible that you may run the process out of memory.
177 The file found via the hardlink path will be byte-by-byte compared with the
178 source if the
179 .Fl V
181 .Fl f
182 option is also used, otherwise only the stat info is checked to determine
183 whether it matches the source.
184 .It Fl V
185 This forces the contents of regular files to be verified, even if the
186 files appear to the be the same.  Whereas the
187 .Fl f
188 (force) option forces a copy regardless, this option will avoid rewriting
189 the target if everything matches and the contents are verified to be the
190 same.
191 .It Fl VV
192 This works the same as
193 .Fl V
194 but ignores mtime entirely, making it suitable for comparing HAMMER
195 master and slave filesystems or copies made without mtime retention.
196 .It Fl S
197 This places
199 into slave mode and is used to initiate the slave protocol on a remote
200 machine.
201 This option is not intended to be used by humans.
202 .It Fl R
203 Place the slave into read-only mode.
204 Can only be used when the source is remote.
205 Useful for unattended backups via SSH keys.
206 .It Fl k
207 Generate and maintain a FSMID checkfile called
208 .Pa \& .FSMID.CHECK
209 in each directory on the target.
211 will check the FSMID for each source file or directory against the checkfile
212 on the target and will not copy the file or recurse through the directory
213 when a match occurs.  Any source file or directory with the same name as the
214 checkfile will be ignored.  The FSMID will be re-checked after the copy
215 has been completed and
217 will loop on that directory or file until it is sure it has an exact copy.
219 Warning: FSMID is not always supported by a filesystem and may not be
220 synchronized if a crash occurs.
222 will simulate an FSMID when
223 it is otherwise not supported by the filesystem, and users should be aware
224 that simulated FSMIDs may change state in such cases even if the underlying
225 hierarchy does not due to cache flushes.
226 Additionally, the FSMID may not reflect changes made to remote filesystems
227 by other hosts.  For example, using these options with NFS mounted sources
228 will not work well.
229 .It Fl K Ar file
230 Works the same as
231 .Fl k
232 but allows you to specify the name of the FSMID checkfile.
233 .It Fl x
234 Causes
236 to use the exclusion file
237 .Pa \&.cpignore
238 in each directory on the source to
239 determine which files to ignore.  When this option is used, the exclusion
240 filename itself is automatically excluded from the copy.  If this option is
241 not used then the filename
242 .Pa \&.cpignore
243 is not considered special and will
244 be copied along with everything else.
245 .It Fl X Ar file
246 Works the same as
247 .Fl x
248 but allows you to specify the name of the exclusion file.  This file is
249 automatically excluded from the copy.  Only one exclusion file may be
250 specified.
252 .Sh REMOTE COPYING
254 can mirror directory structures across machines and can also do third-party
255 copies.
256 This also works between machines that use different byte order.
257 .Xr ssh 1
258 sessions are used and
260 is run on the remote machine(s) in slave mode.
261 You can use the
262 .Fl F
263 option to pass additional flags to the ssh command if necessary.
265 The syntax of remote path specifications is similar to
266 .Xr scp 1 .
267 In particular, that means that a local path containing a colon must
268 be preceded by a slash to prevent it being considered a remote host:
269 .Ql foo:bar
270 causes
272 to look for a directory called
273 .Ql bar
274 on host
275 .Ql foo ,
276 while
277 .Ql \&./foo:bar
278 denotes the directory
279 .Ql foo:bar
280 on the local machine.
283 also supports a
284 .Ql localhost:
285 prefix which is silently discarded but prevents any colons in the remainder
286 of the path from being interpreted as a host:path form.
287 this form can be used with relative filenames when you do not want colons in
288 the filename to be misinterpreted.
289 .Sh EXIT STATUS
290 .Ex -std
291 .Sh SEE ALSO
292 .Xr cp 1 ,
293 .Xr cpio 1 ,
294 .Xr scp 1 ,
295 .Xr ssh 1 ,
296 .Xr tar 1
297 .Sh HISTORY
300 command was originally created to update servers at BEST Internet circa 1997
301 and was placed under the
303 copyright for inclusion in the ports area in 1999.
304 The program was written by Matthew Dillon, Dima Ruban, and later
305 significantly improved by Oliver Fromme.
306 .Sh BUGS
307 .Xr UFS 5
308 has a hardlink limit of 32767.  Many programs, in particular CVS
309 with regards to its CVS/Root file, will generate a lot of hard links.
310 When using the
311 .Fl H
312 option it may not be possible for
314 to maintain these hard links.  If this occurs,
316 will be forced to copy the file instead of link it, and thus not be able
317 to make a perfect copy of the filesystem.
319 When so-called sparse files (i.e. files with "holes") are copied,
320 the holes will be filled in the target files, so they occupy
321 more physical disk space than the source files.
323 For compatibility reasons, the slave protocol is not as efficient
324 for writing remote files as it is for reading them.
325 Therefore it is recommended to run
327 on the target machine when making remote copies,
328 so the source machine is remote.
329 If you do it the other way,
331 will run somewhat slower.