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