1CPDUP(1)                  BSD General Commands Manual                 CPDUP(1)
2

NAME

4     cpdup — mirror filesystems
5

SYNOPSIS

7     cpdup [-C] [-v[v[v]]] [-d] [-n] [-u] [-I] [-f] [-F ssh-arg] [-s0] [-i0]
8           [-j0] [-l] [-q] [-o] [-m] [-H path] [-M file] [-V] [-VV] [-S] [-R]
9           [-k] [-K file] [-X file] [-x] [[user@]host:]source_dir
10           [[user@]host:]target_dir
11

DESCRIPTION

13     The cpdup utility makes an exact mirror copy of the source in the desti‐
14     nation, creating and deleting files and directories as necessary.
15     UTimes, hardlinks, softlinks, devices, permissions, and flags are mir‐
16     rored.  By default, cpdup asks for confirmation if any file or directory
17     needs to be removed from the destination and does not copy files which it
18     believes to have already been synchronized (by observing that the source
19     and destination files' sizes and mtimes match).  cpdup does not cross
20     mount points in either the source or the destination.  As a safety mea‐
21     sure, cpdup refuses to replace a destination directory with a file.
22
23     The following options are available:
24
25     -C    If the source or target is a remote host, request that the ssh(1)
26           session be compressed.  This is the same as -F -C.
27
28     -v[v[v]]
29           Set verboseness.  By default cpdup does not report its progress
30           except when asking for confirmation.  A single -v will only report
31           modifications made to the destination.  -vv will report directories
32           as they are being traversed as well as modifications made to the
33           destination.  -vvv will cause all files and directories to be
34           reported whether or not modifications are made.
35
36     -d    Print directories as they are being traversed.  Useful to watch the
37           progress; this typically produces much less output than -vv.
38
39     -n    Go through the motions but don't actually make any changes to the
40           target.
41
42     -u    Causes the output generated by -v and -d to be unbuffered.  This
43           can be useful for obtaining prompt progress updates through a pipe.
44
45     -I    will cause cpdup to print a summary at the end with performance
46           counters.
47
48     -f    Forces file updates to occur even if the files appear to be the
49           same.  If the -H option is used, this option will force a byte for
50           byte comparison between the original file and the file in the
51           hardlink path, even if all the stat info matches, but will still
52           use a hardlink if they match.
53
54     -F ssh-arg
55           Pass ssh-arg to ssh.  For example “-F -p222”.  Note the lack of a
56           space.
57
58     -s0   Disable the disallow-file-replaces-directory safety feature.  This
59           safety feature is enabled by default to prevent user mistakes from
60           blowing away everything accidentally.
61
62     -i0   Do not request confirmation when removing something.
63
64     -j0   Do not try to recreate CHR or BLK devices.
65
66     -l    Line buffer verbose output.
67
68     -q    Quiet operation.
69
70     -o    Do not remove any files, just overwrite/add.
71
72     -m    Generate and maintain a MD5 checkfile called .MD5.CHECKSUMS in each
73           directory on the source and do an MD5 check on each file of the
74           destination when the destination appears to be the same as the
75           source.  If the check fails, the source is recopied to the destina‐
76           tion.  When you specify a destination directory, the MD5 checkfile
77           is only updated as needed and may not be updated even if modifica‐
78           tions are made to a source file.  If you do not specify a destina‐
79           tion directory the cpdup command forcefully regenerates the MD5
80           checkfile for every file in the source.
81
82     -M file
83           Works the same as -m but allows you to specify the name of the MD5
84           checkfile.
85
86     -H path
87           cpdup will create a hardlink from a file found under path to the
88           target instead of copying the source to the target if the file
89           found via path is identical to the source.  Note that a remote host
90           specification should not be used for this option's path, but the
91           path will be relative to the target machine.
92
93           This allows one to use cpdup to create incremental backups of a
94           filesystem.  Create a direct ‘level 0’ backup, and then specify the
95           level 0 backup path with this option when creating an incremental
96           backup to a different target directory.  This method works so long
97           as the filesystem does not hit a hardlink limit.  If the system
98           does hit a hardlink limit, cpdup will generate a warning and copy
99           the file instead.  Note that cpdup must record file paths for any
100           hardlinked file while operating and therefore uses a great deal
101           more memory when dealing with hardlinks or hardlink-based backups.
102           Example use:
103
104                 cpdup -i0 -s0 -I -H /backup/home.l0 /home /backup/home.l1
105
106           WARNING: If this option is used cpdup must record the paths for all
107           files it encounters while it operates and it is possible that you
108           may run the process out of memory.
109
110           The file found via the hardlink path will be byte-by-byte compared
111           with the source if the -V or -f option is also used, otherwise only
112           the stat info is checked to determine whether it matches the
113           source.
114
115     -V    This forces the contents of regular files to be verified, even if
116           the files appear to the be the same.  Whereas the -f (force) option
117           forces a copy regardless, this option will avoid rewriting the tar‐
118           get if everything matches and the contents are verified to be the
119           same.
120
121     -VV   This works the same as -V but ignores mtime entirely, making it
122           suitable for comparing HAMMER master and slave filesystems or
123           copies made without mtime retention.
124
125     -S    This places cpdup into slave mode and is used to initiate the slave
126           protocol on a remote machine.  This option is not intended to be
127           used by humans.
128
129     -R    Place the slave into read-only mode.  Can only be used when the
130           source is remote.  Useful for unattended backups via SSH keys.
131
132     -k    Generate and maintain a FSMID checkfile called  .FSMID.CHECK in
133           each directory on the target.  cpdup will check the FSMID for each
134           source file or directory against the checkfile on the target and
135           will not copy the file or recurse through the directory when a
136           match occurs.  Any source file or directory with the same name as
137           the checkfile will be ignored.  The FSMID will be re-checked after
138           the copy has been completed and cpdup will loop on that directory
139           or file until it is sure it has an exact copy.
140
141           Warning: FSMID is not always supported by a filesystem and may not
142           be synchronized if a crash occurs.  DragonFly will simulate an
143           FSMID when it is otherwise not supported by the filesystem, and
144           users should be aware that simulated FSMIDs may change state in
145           such cases even if the underlying hierarchy does not due to cache
146           flushes.  Additionally, the FSMID may not reflect changes made to
147           remote filesystems by other hosts.  For example, using these
148           options with NFS mounted sources will not work well.
149
150     -K file
151           Works the same as -k but allows you to specify the name of the
152           FSMID checkfile.
153
154     -x    Causes cpdup to use the exclusion file .cpignore in each directory
155           on the source to determine which files to ignore.  When this option
156           is used, the exclusion filename itself is automatically excluded
157           from the copy.  If this option is not used then the filename
158           .cpignore is not considered special and will be copied along with
159           everything else.
160
161     -X file
162           Works the same as -x but allows you to specify the name of the
163           exclusion file.  This file is automatically excluded from the copy.
164           Only one exclusion file may be specified.
165

REMOTE COPYING

167     cpdup can mirror directory structures across machines and can also do
168     third-party copies.  This also works between machines that use different
169     byte order.  ssh(1) sessions are used and cpdup is run on the remote
170     machine(s) in slave mode.  You can use the -F option to pass additional
171     flags to the ssh command if necessary.
172
173     The syntax of remote path specifications is similar to scp(1).  In par‐
174     ticular, that means that a local path containing a colon must be preceded
175     by a slash to prevent it being considered a remote host: ‘foo:bar’ causes
176     cpdup to look for a directory called ‘bar’ on host ‘foo’, while
177     ‘./foo:bar’ denotes the directory ‘foo:bar’ on the local machine.
178

DIAGNOSTICS

180     The cpdup utility exits 0 if no error occurred and >0 if an error
181     occurred.
182

SEE ALSO

184     cp(1), cpio(1), scp(1), ssh(1), tar(1)
185

HISTORY

187     The cpdup command was originally created to update servers at BEST Inter‐
188     net circa 1997 and was placed under the FreeBSD copyright for inclusion
189     in the ports area in 1999.  The program was written by Matthew Dillon,
190     Dima Ruban, and later significantly improved by Oliver Fromme.
191

BUGS

193     UFS(5) has a hardlink limit of 32767.  Many programs, in particular CVS
194     with regards to its CVS/Root file, will generate a lot of hard links.
195     When using the -H option it may not be possible for cpdup to maintain
196     these hard links.  If this occurs, cpdup will be forced to copy the file
197     instead of link it, and thus not be able to make a perfect copy of the
198     filesystem.
199
200     When so-called sparse files (i.e. files with "holes") are copied, the
201     holes will be filled in the target files, so they occupy more physical
202     disk space than the source files.
203
204     For compatibility reasons, the slave protocol is not as efficient for
205     writing remote files as it is for reading them.  Therefore it is recom‐
206     mended to run cpdup on the target machine when making remote copies, so
207     the source machine is remote.  If you do it the other way, cpdup will run
208     somewhat slower.
209
210BSD                            November 24, 2009                           BSD
Impressum