bin/cpdup/cpdup.1

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