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