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.24 2007/05/13 18:33:55 swildner 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 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 84.Nm 85to print a summary at the end with performance counter. 86.It Fl f 87Forces file updates to occur even if the files appear to be the same. If 88the 89.Fl H 90option is used, this option will force a byte for byte comparison 91between the original file and the file in the hardlink path, even if 92all the stat info matches, but will still use a hardlink if they match. 93.It Fl s0 94Disable the disallow-file-replaces-directory safety feature. This 95safety feature is enabled by default to prevent user mistakes from blowing 96away everything accidently. 97.It Fl i0 98Do not request confirmation when removing something. 99.It Fl j0 100Do not try to recreate CHR or BLK devices. 101.It Fl q 102Quiet operation 103.It Fl o 104Do not remove any files, just overwrite/add. 105.It Fl m 106Generate and maintain a MD5 checkfile in each directory on the source 107and do an MD5 check on each file of the destination when the destination 108appears to be the same as the source. If the check fails, 109.Nm 110the source is recopied to the destination. When you specify a destination 111directory the MD5 checkfile is only updated as needed and may not be updated 112even if modifications are made to a source file. If you do not specify a 113destination directory the 114.Nm 115command forcefully regenerates the MD5 checkfile for every file in the source. 116.It Fl H Ar path 117.Nm 118will create a hardlink from a file found under 119.Ar path 120to the target instead of copying the source to the target if the file found 121via 122.Ar path 123is identical to the source. 124Note that a remote host specification should not be used in this option, 125but the path will be relative to the target machine. 126.Pp 127This allows one to use 128.Nm 129to create incremental backups of a filesystem. Create a direct 'level 0' 130backup, and then specify the level 0 backup path with this option when 131creating an incremental backup to a different target directory. 132This method works so long as the filesystem does not hit a hardlink limit. 133If the system does hit a hardlink limit 134.Nm 135will generate a warning and copy the file instead. 136Note that 137.Nm 138must record file paths for any hardlinked file while operating and therefore 139uses a great deal more memory when dealing with hardlinks or hardlink-based 140backups. Example use: 141.Pp 142.Dl cpdup -i0 -s0 -I -H /backup/home.l0 /home /backup/home.l1 143.Pp 144WARNING: If this option is used 145.Nm 146must record the paths for all files it encounters while it operates 147and it is possible that you may run the process out of memory. 148.It Fl M Ar file 149Works the same as 150.Fl m 151but allows you to specify the name of the MD5 checkfile. 152.It Fl S 153This places 154.Nm 155into slave mode and is used to initiate the slave protocol on a remote 156machine. 157.It Fl k 158Generate and maintain a FSMID checkfile called .FSMID.CHECK in each 159directory on the target. 160.Nm 161will check the FSMID for each source file or directory against the checkfile 162on the target and will not copy the file or recurse through the directory 163when a match occurs. Any source file or directory with the same name as the 164checkfile will be ignored. The FSMID will be re-checked after the copy 165has been completed and 166.Nm 167will loop on that directory or file until it is sure it has an exact copy. 168.Pp 169Warning: FSMID is not always supported by a filesystem and may not be 170synchronized if a crash occurs. 171.Dx 172will simulate an FSMID when 173it is otherwise not supported by the filesystem, and users should be aware 174that simulated FSMIDs may change state in such cases even if the underlying 175hierarchy does not due to cache flushes. 176Additionally, the FSMID may not reflect changes made to remote filesystems 177by other hosts. For example, using these options with NFS mounted sources 178will not work well. 179.It Fl K Ar file 180Works the same as 181.Fl k 182but allows you to specify the name of the FSMID checkfile. 183.It Fl x 184Causes 185.Nm 186to use the exclusion file ".cpignore" in each directory on the source to 187determine which files to ignore. When this option is used, the exclusion 188filename itself is automatically excluded from the copy. If this option is 189not used then the filename ".cpignore" is not considered special and will 190be copied along with everything else. 191.It Fl X Ar file 192Works the same as 193.Fl x 194but allows you to specify the name of the exclusion file. This file is 195automatically excluded from the copy. Only one exclusion file may be 196specified. 197.El 198.Sh REMOTE COPYING 199.Nm 200can mirror directory structures across machines and can also do third-party 201copies. 202.Xr ssh 1 203sessions are used and 204.Nm 205is run on the remote machine(s) in slave mode. 206.Sh DIAGNOSTICS 207The 208.Nm 209utility exits 0 if no error occurred and >0 if an error occurred. 210.Sh SEE ALSO 211.Xr cp 1 , 212.Xr cpio 1 , 213.Xr tar 1 214.Sh HISTORY 215The 216.Nm 217command was originally created to update servers at BEST Internet circa 1997 218and was placed under the 219.Fx 220copyright for inclusion in the ports area in 1999. 221The program was written by Matthew Dillon and Dima Ruban. 222.Sh BUGS 223UFS has a hardlink limit of 32767. Many programs, in particular CVS 224with regards to its CVS/Root file, will generate a lot of hard links. 225When using the 226.Fl H 227option it may not be possible for 228.Nm 229to maintain these hard links. If this occurs 230.Nm 231will be forced to copy the file instead of link it, and thus not be able 232to make a perfect copy of the filesystem. 233