1CPDUP(1) BSD General Commands Manual CPDUP(1)
2
4 cpdup — mirror filesystems
5
7 cpdup [-C] [-v[v[v]]] [-d] [-u] [-I] [-f] [-F ssh-arg] [-s0] [-i0] [-j0]
8 [-l] [-q] [-o] [-m] [-H path] [-M file] [-V] [-VV] [-S] [-R] [-k]
9 [-K file] [-X file] [-x] [[user@]host:]source_dir
10 [[user@]host:]target_dir
11
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 The following options are available:
24 -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 -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 -d Print directories as they are being traversed. Useful to watch the
37 progress; this typically produces much less output than -vv.
38 -u Causes the output generated by -v and -d to be unbuffered. This
40 can be useful for obtaining prompt progress updates through a pipe.
41 -I will cause cpdup to print a summary at the end with performance
43 counters.
44 -f Forces file updates to occur even if the files appear to be the
46 same. If the -H option is used, this option will force a byte for
47 byte comparison between the original file and the file in the
48 hardlink path, even if all the stat info matches, but will still
49 use a hardlink if they match.
50 -F ssh-arg
52 Pass ssh-arg to ssh. For example “-F -p222”. Note the lack of a
53 space.
54 -s0 Disable the disallow-file-replaces-directory safety feature. This
56 safety feature is enabled by default to prevent user mistakes from
57 blowing away everything accidentally.
58 -i0 Do not request confirmation when removing something.
60 -j0 Do not try to recreate CHR or BLK devices.
62 -l Line buffer verbose output.
64 -q Quiet operation.
66 -o Do not remove any files, just overwrite/add.
68 -m Generate and maintain an MD5 checkfile called .MD5.CHECKSUMS in
70 each directory on the source and do an MD5 check on each file of
71 the destination when the destination appears to be the same as the
72 source. If the check fails, the source is recopied to the destina‐
73 tion. When you specify a destination directory, the MD5 checkfile
74 is only updated as needed and may not be updated even if modifica‐
75 tions are made to a source file. If you do not specify a destina‐
76 tion directory the cpdup command forcefully regenerates the MD5
77 checkfile for every file in the source.
78 -M file
80 Works the same as -m but allows you to specify the name of the MD5
81 checkfile.
82 -H path
84 cpdup will create a hardlink from a file found under path to the
85 target instead of copying the source to the target if the file
86 found via path is identical to the source. Note that a remote host
87 specification should not be used for this option's path, but the
88 path will be relative to the target machine.
89 This allows one to use cpdup to create incremental backups of a
91 filesystem. Create a direct ‘level 0’ backup, and then specify the
92 level 0 backup path with this option when creating an incremental
93 backup to a different target directory. This method works so long
94 as the filesystem does not hit a hardlink limit. If the system
95 does hit a hardlink limit, cpdup will generate a warning and copy
96 the file instead. Note that cpdup must record file paths for any
97 hardlinked file while operating and therefore uses a great deal
98 more memory when dealing with hardlinks or hardlink-based backups.
99 Example use:
100 cpdup -i0 -s0 -I -H /backup/home.l0 /home /backup/home.l1
102 WARNING: If this option is used cpdup must record the paths for all
104 files it encounters while it operates and it is possible that you
105 may run the process out of memory.
106 The file found via the hardlink path will be byte-by-byte compared
108 with the source if the -V or -f option is also used, otherwise only
109 the stat info is checked to determine whether it matches the
110 source.
111 -V This forces the contents of regular files to be verified, even if
113 the files appear to the be the same. Whereas the -f (force) option
114 forces a copy regardless, this option will avoid rewriting the tar‐
115 get if everything matches and the contents are verified to be the
116 same.
117 -VV This works the same as -V but ignores mtime entirely, making it
119 suitable for comparing HAMMER master and slave filesystems or
120 copies made without mtime retention.
121 -S This places cpdup into slave mode and is used to initiate the slave
123 protocol on a remote machine. This option is not intended to be
124 used by humans.
125 -R Place the slave into read-only mode. Can only be used when the
127 source is remote. Useful for unattended backups via SSH keys.
128 -k Generate and maintain a FSMID checkfile called .FSMID.CHECK in
130 each directory on the target. cpdup will check the FSMID for each
131 source file or directory against the checkfile on the target and
132 will not copy the file or recurse through the directory when a
133 match occurs. Any source file or directory with the same name as
134 the checkfile will be ignored. The FSMID will be re-checked after
135 the copy has been completed and cpdup will loop on that directory
136 or file until it is sure it has an exact copy.
137 Warning: FSMID is not always supported by a filesystem and may not
139 be synchronized if a crash occurs. DragonFly will simulate an
140 FSMID when it is otherwise not supported by the filesystem, and
141 users should be aware that simulated FSMIDs may change state in
142 such cases even if the underlying hierarchy does not due to cache
143 flushes. Additionally, the FSMID may not reflect changes made to
144 remote filesystems by other hosts. For example, using these
145 options with NFS mounted sources will not work well.
146 -K file
148 Works the same as -k but allows you to specify the name of the
149 FSMID checkfile.
150 -x Causes cpdup to use the exclusion file .cpignore in each directory
152 on the source to determine which files to ignore. When this option
153 is used, the exclusion filename itself is automatically excluded
154 from the copy. If this option is not used then the filename
155 .cpignore is not considered special and will be copied along with
156 everything else.
157 -X file
159 Works the same as -x but allows you to specify the name of the
160 exclusion file. This file is automatically excluded from the copy.
161 Only one exclusion file may be specified.
162
164 cpdup can mirror directory structures across machines and can also do
165 third-party copies. This also works between machines that use different
166 byte order. ssh(1) sessions are used and cpdup is run on the remote
167 machine(s) in slave mode. You can use the -F option to pass additional
168 flags to the ssh command if necessary.
169 The syntax of remote path specifications is similar to scp(1). In par‐
171 ticular, that means that a local path containing a colon must be preceded
172 by a slash to prevent it being considered a remote host: ‘foo:bar’ causes
173 cpdup to look for a directory called ‘bar’ on host ‘foo’, while
174 ‘./foo:bar’ denotes the directory ‘foo:bar’ on the local machine.
175
177 The cpdup utility exits 0 if no error occurred and >0 if an error
178 occurred.
179
181 cp(1), cpio(1), scp(1), ssh(1), tar(1)
182
184 The cpdup command was originally created to update servers at BEST Inter‐
185 net circa 1997 and was placed under the FreeBSD copyright for inclusion
186 in the ports area in 1999. The program was written by Matthew Dillon,
187 Dima Ruban, and later significantly improved by Oliver Fromme.
188
190 UFS(5) has a hardlink limit of 32767. Many programs, in particular CVS
191 with regards to its CVS/Root file, will generate a lot of hard links.
192 When using the -H option it may not be possible for cpdup to maintain
193 these hard links. If this occurs, cpdup will be forced to copy the file
194 instead of link it, and thus not be able to make a perfect copy of the
195 filesystem.
196 When so-called sparse files (i.e. files with "holes") are copied, the
198 holes will be filled in the target files, so they occupy more physical
199 disk space than the source files.
200 For compatibility reasons, the slave protocol is not as efficient for
202 writing remote files as it is for reading them. Therefore it is recom‐
203 mended to run cpdup on the target machine when making remote copies, so
204 the source machine is remote. If you do it the other way, cpdup will run
205 somewhat slower.
206BSD November 24, 2009 BSD