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.
10 .Nd mirror filesystems
14 .Op Fl v Ns Op Cm v Ns Op Cm v
37 .Oo Oo Ar user Ns Li @ Oc Ns Ar host : Oc Ns Ar source_dir
38 .Oo Oo Ar user Ns Li @ Oc Ns Ar host : Oc Ns Ar target_dir
42 utility makes an exact mirror copy of the source in the destination, creating
43 and deleting files and directories as necessary. UTimes, hardlinks,
44 softlinks, devices, permissions, and flags are mirrored. By default,
46 asks for confirmation if any file or directory needs to be removed from
47 the destination and does not copy files which it believes to have already
48 been synchronized (by observing that the source and destination files' sizes
51 does not cross mount points in either the source or the destination.
54 refuses to replace a destination directory with a file.
56 The following options are available:
59 If the source or target is a remote host, request that the
61 session be compressed.
65 .It Fl v Ns Op Cm v Ns Op Cm v
66 Set verboseness. By default
68 does not report its progress except when asking for confirmation. A single
70 will only report modifications made to the destination.
72 will report directories as they are being traversed as well as
73 modifications made to the destination.
75 will cause all files and directories to be reported whether or not
76 modifications are made.
78 Print directories as they are being traversed.
79 Useful to watch the progress;
80 this typically produces much less output than
83 Causes the output generated by
88 This can be useful for obtaining prompt progress updates through a pipe.
92 to print a summary at the end with performance counters.
94 Forces file updates to occur even if the files appear to be the same. If
97 option is used, this option will force a byte for byte comparison
98 between the original file and the file in the hardlink path, even if
99 all the stat info matches, but will still use a hardlink if they match.
105 Note the lack of a space.
107 Disable the disallow-file-replaces-directory safety feature. This
108 safety feature is enabled by default to prevent user mistakes from blowing
109 away everything accidentally.
111 Do not request confirmation when removing something.
113 Do not try to recreate CHR or BLK devices.
115 Line buffer verbose output.
119 Do not remove any files, just overwrite/add.
121 Generate and maintain a MD5 checkfile called
123 in each directory on the source
124 and do an MD5 check on each file of the destination when the destination
125 appears to be the same as the source. If the check fails,
126 the source is recopied to the destination. When you specify a destination
127 directory, the MD5 checkfile is only updated as needed and may not be updated
128 even if modifications are made to a source file. If you do not specify a
129 destination directory the
131 command forcefully regenerates the MD5 checkfile for every file in the source.
135 but allows you to specify the name of the MD5 checkfile.
138 will create a hardlink from a file found under
140 to the target instead of copying the source to the target if the file found
143 is identical to the source.
144 Note that a remote host specification should not be used for this option's
148 will be relative to the target machine.
150 This allows one to use
152 to create incremental backups of a filesystem. Create a direct
154 backup, and then specify the level 0 backup path with this option when
155 creating an incremental backup to a different target directory.
156 This method works so long as the filesystem does not hit a hardlink limit.
157 If the system does hit a hardlink limit,
159 will generate a warning and copy the file instead.
162 must record file paths for any hardlinked file while operating and therefore
163 uses a great deal more memory when dealing with hardlinks or hardlink-based
164 backups. Example use:
166 .Dl cpdup \-i0 \-s0 \-I \-H /backup/home.l0 /home /backup/home.l1
168 WARNING: If this option is used
170 must record the paths for all files it encounters while it operates
171 and it is possible that you may run the process out of memory.
173 The file found via the hardlink path will be byte-by-byte compared with the
178 option is also used, otherwise only the stat info is checked to determine
179 whether it matches the source.
181 This forces the contents of regular files to be verified, even if the
182 files appear to the be the same. Whereas the
184 (force) option forces a copy regardless, this option will avoid rewriting
185 the target if everything matches and the contents are verified to be the
188 This works the same as
190 but ignores mtime entirely, making it suitable for comparing HAMMER
191 master and slave filesystems or copies made without mtime retention.
195 into slave mode and is used to initiate the slave protocol on a remote
197 This option is not intended to be used by humans.
199 Place the slave into read-only mode.
200 Can only be used when the source is remote.
201 Useful for unattended backups via SSH keys.
203 Generate and maintain a FSMID checkfile called
205 in each directory on the target.
207 will check the FSMID for each source file or directory against the checkfile
208 on the target and will not copy the file or recurse through the directory
209 when a match occurs. Any source file or directory with the same name as the
210 checkfile will be ignored. The FSMID will be re-checked after the copy
211 has been completed and
213 will loop on that directory or file until it is sure it has an exact copy.
215 Warning: FSMID is not always supported by a filesystem and may not be
216 synchronized if a crash occurs.
218 will simulate an FSMID when
219 it is otherwise not supported by the filesystem, and users should be aware
220 that simulated FSMIDs may change state in such cases even if the underlying
221 hierarchy does not due to cache flushes.
222 Additionally, the FSMID may not reflect changes made to remote filesystems
223 by other hosts. For example, using these options with NFS mounted sources
228 but allows you to specify the name of the FSMID checkfile.
232 to use the exclusion file
234 in each directory on the source to
235 determine which files to ignore. When this option is used, the exclusion
236 filename itself is automatically excluded from the copy. If this option is
237 not used then the filename
239 is not considered special and will
240 be copied along with everything else.
244 but allows you to specify the name of the exclusion file. This file is
245 automatically excluded from the copy. Only one exclusion file may be
250 can mirror directory structures across machines and can also do third-party
252 This also works between machines that use different byte order.
254 sessions are used and
256 is run on the remote machine(s) in slave mode.
259 option to pass additional flags to the ssh command if necessary.
261 The syntax of remote path specifications is similar to
263 In particular, that means that a local path containing a colon must
264 be preceded by a slash to prevent it being considered a remote host:
268 to look for a directory called
274 denotes the directory
276 on the local machine.
280 utility exits 0 if no error occurred and >0 if an error occurred.
290 command was originally created to update servers at BEST Internet circa 1997
291 and was placed under the
293 copyright for inclusion in the ports area in 1999.
294 The program was written by Matthew Dillon, Dima Ruban, and later
295 significantly improved by Oliver Fromme.
298 has a hardlink limit of 32767. Many programs, in particular CVS
299 with regards to its CVS/Root file, will generate a lot of hard links.
302 option it may not be possible for
304 to maintain these hard links. If this occurs,
306 will be forced to copy the file instead of link it, and thus not be able
307 to make a perfect copy of the filesystem.
309 When so-called sparse files (i.e. files with "holes") are copied,
310 the holes will be filled in the target files, so they occupy
311 more physical disk space than the source files.
313 For compatibility reasons, the slave protocol is not as efficient
314 for writing remote files as it is for reading them.
315 Therefore it is recommended to run
317 on the target machine when making remote copies,
318 so the source machine is remote.
319 If you do it the other way,
321 will run somewhat slower.
nant's projects / dragonfly.git / blob