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