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