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.20 2006/12/26 03:38:50 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 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. 168.Dx 169will simulate an FSMID when 170it is otherwise not supported by the filesystem, and users should be aware 171that simulated FSMIDs may change state in such cases even if the underlying 172hierarchy does not due to cache flushes. 173Additionally, the FSMID may not reflect changes made to remote filesystems 174by other hosts. For example, using these options with NFS mounted sources 175will not work well. 176.It Fl K Ar file 177Works the same as 178.Fl k 179but allows you to specify the name of the FSMID checkfile. 180.It Fl x 181Causes 182.Nm 183to use the exclusion file ".cpignore" in each directory on the source to 184determine which files to ignore. When this option is used, the exclusion 185filename itself is automatically excluded from the copy. If this option is 186not used then the filename ".cpignore" is not considered special and will 187be copied along with everything else. 188.It Fl X Ar file 189Works the same as 190.Fl x 191but allows you to specify the name of the exclusion file. This file is 192automatically excluded from the copy. Only one exclusion file may be 193specified. 194.El 195.Sh REMOTE COPYING 196.Nm 197can mirror directory structures across machines and can also do third-party 198copies. 199.Xr ssh 1 200sessions are used and 201.Nm 202is run on the remote machine(s) in slave mode. 203.Sh DIAGNOSTICS 204The 205.Nm 206utility exits 0 if no error occured and >0 if an error occured. 207.Sh SEE ALSO 208.Xr cp 1 , 209.Xr cpio 1 , 210.Xr tar 1 211.Sh HISTORY 212The 213.Nm 214command was original created to update servers at BEST Internet circa 1997 215and was placed under the FreeBSD copyright for inclusion in the ports area 216in 1999. The program was written by Matthew Dillon and Dima Ruban. 217.Sh BUGS 218UFS has a hardlink limit of 32767. Many programs, in particular CVS 219with regards to its CVS/Root file, will generate a lot of hard links. 220When using the 221.Fl H 222option it may not be possible for 223.Nm 224to maintain these hard links. If this occurs 225.Nm 226will be forced to copy the file instead of link it, and thus not be able 227to make a perfect copy of the filesystem. 228