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