bin/cpdup/cpdup.1

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