bin/cpdup/cpdup.1

   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
 134 .Nm
 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
 141 .Nm
 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
 145 via
 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.
 153 .Pp
 154 This allows one to use
 155 .Nm
 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,
 162 .Nm
 163 will generate a warning and copy the file instead.
 164 Note that
 165 .Nm
 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:
 169 .Pp
 170 .Dl cpdup \-i0 \-s0 \-I \-H /backup/home.l0 /home /backup/home.l1
 171 .Pp
 172 WARNING: If this option is used
 173 .Nm
 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.
 176 .Pp
 177 The file found via the hardlink path will be byte-by-byte compared with the
 178 source if the
 179 .Fl V
 180 or
 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
 198 .Nm
 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.
 210 .Nm
 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
 216 .Nm
 217 will loop on that directory or file until it is sure it has an exact copy.
 218 .Pp
 219 Warning: FSMID is not always supported by a filesystem and may not be
 220 synchronized if a crash occurs.
 221 .Dx
 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
 235 .Nm
 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.
 251 .El
 252 .Sh REMOTE COPYING
 253 .Nm
 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
 259 .Nm
 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.
 264 .Pp
 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
 271 .Nm
 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.
 281 .Pp
 282 .Nm
 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 DIAGNOSTICS
 290 The
 291 .Nm
 292 utility exits 0 if no error occurred and >0 if an error occurred.
 293 .Sh SEE ALSO
 294 .Xr cp 1 ,
 295 .Xr cpio 1 ,
 296 .Xr scp 1 ,
 297 .Xr ssh 1 ,
 298 .Xr tar 1
 299 .Sh HISTORY
 300 The
 301 .Nm
 302 command was originally created to update servers at BEST Internet circa 1997
 303 and was placed under the
 304 .Fx
 305 copyright for inclusion in the ports area in 1999.
 306 The program was written by Matthew Dillon, Dima Ruban, and later
 307 significantly improved by Oliver Fromme.
 308 .Sh BUGS
 309 .Xr UFS 5
 310 has a hardlink limit of 32767.  Many programs, in particular CVS
 311 with regards to its CVS/Root file, will generate a lot of hard links.
 312 When using the
 313 .Fl H
 314 option it may not be possible for
 315 .Nm
 316 to maintain these hard links.  If this occurs,
 317 .Nm
 318 will be forced to copy the file instead of link it, and thus not be able
 319 to make a perfect copy of the filesystem.
 320 .Pp
 321 When so-called sparse files (i.e. files with "holes") are copied,
 322 the holes will be filled in the target files, so they occupy
 323 more physical disk space than the source files.
 324 .Pp
 325 For compatibility reasons, the slave protocol is not as efficient
 326 for writing remote files as it is for reading them.
 327 Therefore it is recommended to run
 328 .Nm
 329 on the target machine when making remote copies,
 330 so the source machine is remote.
 331 If you do it the other way,
 332 .Nm
 333 will run somewhat slower.