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