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.11 2006/07/04 00:32:03 dillon 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 k
  33 .Oo
  34 .Fl K
  35 .Ar file
  36 .Oc
  37 .Oo
  38 .Fl X
  39 .Ar file
  40 .Oc
  41 .Op Fl x
  42 .Ar source_dir
  43 .Ar target_dir
  44 .Sh DESCRIPTION
  45 The
  46 .Nm
  47 utility makes an exact mirror copy of the source in the destination, creating
  48 and deleting files and directories as necessary.  UTimes, hardlinks,
  49 softlinks, devices, permissions, and flags are mirrored.  By default,
  50 .Nm
  51 asks for confirmation if any file or directory needs to be removed from
  52 the destination and does not copy files which it believes to have already
  53 been synchronized (by observing that the source and destination file's size
  54 and mtimes match).
  55 .Nm
  56 does not cross mount points in either the source or the destination.
  57 As a safety measure,
  58 .Nm
  59 refuses to replace a destination directory with a file.
  60 .Pp
  61 The following options are available:
  62 .Bl -tag -width flag
  63 .It Fl v[vv]
  64 Set verboseness.  By default
  65 .Nm
  66 does not report its progress except when asking for confirmation.  A single
  67 .Fl v
  68 will only report modifications made to the destination.
  69 .Fl vv
  70 will report directories as they are being traversed as well as
  71 modifications made to the destination.
  72 .Fl vvv
  73 will cause all files and directories to be reported whether or not
  74 modifications are made.
  75 .It Fl u
  76 Causes the ouptut generated by
  77 .Fl v[vv]
  78 to be unbuffered.
  79 This can be useful for obtaining prompt progress updates through a pipe.
  80 .It Fl I
  81 will cause cpdup to print a summary at the end with performance counter.
  82 .It Fl f
  83 Forces file updates to occur even if the files appear to be the same.  If
  84 the
  85 .Fl H
  86 option is used, this option will also force a byte for byte comparison
  87 between the original file and the file in the hardlink path, even if
  88 all the stat info matches, but will still use a hardlink if they match.
  89 .It Fl s0
  90 Disable the disallow-file-replaces-directory safety feature.  This
  91 safety feature is enabled by default to prevent user mistakes from blowing
  92 away everything accidently.
  93 .It Fl i0
  94 Do not request confirmation when removing something.
  95 .It Fl q
  96 Quiet operation
  97 .It Fl o
  98 Do not remove any files, just overwrite/add.
  99 .It Fl m
 100 Generate and maintain a MD5 checkfile in each directory on the source
 101 and do an MD5 check on each file of the destination when the destination
 102 appears to be the same as the source.  If the check fails,
 103 .Nm
 104 the source is recopied to the destination.  When you specify a destination
 105 directory the MD5 checkfile is only updated as needed and may not be updated
 106 even if modifications are made to a source file.  If you do not specify a
 107 destination directory the
 108 .Nm
 109 command forcefully regenerates the MD5 checkfile for every file in the source.
 110 .It Fl H Ar path
 111 cpdup will create a hardlink from a file found under
 112 .Ar path
 113 to the target instead of copying the source to the target if the file found
 114 via
 115 .Ar path
 116 is identical to the source.  This allows one to use
 117 .Nm
 118 to create incremental backups of a filesystem.  Create a direct 'level 0'
 119 backup, and then specify the level 0 backup path with this option when
 120 creating an incremental backup to a different target directory.  This
 121 method works so long as the filesystem does not hit a hardlink limit.  Note
 122 that
 123 .Nm
 124 must record file paths for any hardlinked file while operating and therefore
 125 uses a great deal more memory when dealing with hardlinks or hardlink-based
 126 backups.  Example use:
 127 .Pp
 128 .Dl cpdup -i0 -s0 -I -H /backup/home.l0 /home /backup/home.l1
 129 .Pp
 130 WARNING: If this option is used
 131 .Nm
 132 must record the paths for all files it encounters while it operates
 133 and it is possible that you may run the process out of memory.
 134 .It Fl M Ar file
 135 Works the same as
 136 .Fl m
 137 but allows you to specify the name of the MD5 checkfile.
 138 .It Fl k
 139 Generate and maintain a FSMID checkfile called .FSMID.CHECK in each
 140 directory on the target.
 141 .Nm
 142 will check the FSMID for each source file or directory against the checkfile
 143 on the target and will not copy the file or recurse through the directory
 144 when a match occurs.  Any source file or directory with the same name as the
 145 checkfile will be ignored.  The FSMID will be re-checked after the copy
 146 has been completed and
 147 .Nm
 148 will loop on that directory or file until it is sure it has an exact copy.
 149 .Pp
 150 Warning: FSMID is not always supported by a filesystem and may not be
 151 synchronized if a crash occurs.  DragonFly will simulate an FSMID when
 152 it is otherwise not supported by the filesystem, and users should be aware
 153 that simulated FSMIDs may change state in such cases even if the underlying
 154 hierarchy does not due to cache flushes.
 155 Additionally, the FSMID may not reflect changes made to remote filesystems
 156 by other hosts.  For example, using these options with NFS mounted sources
 157 will not work well.
 158 .It Fl K Ar file
 159 Works the same as
 160 .Fl k
 161 but allows you to specify the name of the FSMID checkfile.
 162 .It Fl x
 163 Causes
 164 .Nm
 165 to use the exclusion file ".cpignore" in each directory on the source to
 166 determine which files to ignore.  When this option is used, the exclusion
 167 filename itself is automatically excluded from the copy.  If this option is
 168 not used then the filename ".cpignore" is not considered special and will
 169 be copied along with everything else.
 170 .It Fl X Ar file
 171 Works the same as
 172 .Fl x
 173 but allows you to specify the name of the exclusion file.  This file is
 174 automatically excluded from the copy.  Only one exclusion file may be
 175 specified.
 176 .El
 177 .Sh DIAGNOSTICS
 178 The
 179 .Nm
 180 utility exits 0 if no modifications were made, and >0 if modifications
 181 were made to the destination.
 182 .Sh SEE ALSO
 183 .Xr cp 1 ,
 184 .Xr cpio 1 ,
 185 .Xr tar 1
 186 .Sh HISTORY
 187 The
 188 .Nm
 189 command was original created to update servers at BEST Internet circa 1997
 190 and was placed under the FreeBSD copyright for inclusion in the ports area
 191 in 1999.  The program was written by Matthew Dillon and Dima Ruban.