1.\" (c) Copyright 1997-2009 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.Dd November 24, 2009 6.Dt CPDUP 1 7.Os 8.Sh NAME 9.Nm cpdup 10.Nd mirror filesystems 11.Sh SYNOPSIS 12.Nm 13.Op Fl C 14.Op Fl v Ns Op Cm v Ns Op Cm v 15.Op Fl d 16.Op Fl u 17.Op Fl I 18.Op Fl f 19.Op Fl F Ar ssh-arg 20.Op Fl s0 21.Op Fl i0 22.Op Fl j0 23.Op Fl l 24.Op Fl q 25.Op Fl o 26.Op Fl m 27.Op Fl H Ar path 28.Op Fl M Ar file 29.Op Fl V 30.Op Fl VV 31.Op Fl S 32.Op Fl k 33.Op Fl K Ar file 34.Op Fl X Ar file 35.Op Fl x 36.Oo Oo Ar user Ns Li @ Oc Ns Ar host : Oc Ns Ar source_dir 37.Oo Oo Ar user Ns Li @ Oc Ns Ar host : Oc Ns Ar target_dir 38.Sh DESCRIPTION 39The 40.Nm 41utility makes an exact mirror copy of the source in the destination, creating 42and deleting files and directories as necessary. UTimes, hardlinks, 43softlinks, devices, permissions, and flags are mirrored. By default, 44.Nm 45asks for confirmation if any file or directory needs to be removed from 46the destination and does not copy files which it believes to have already 47been synchronized (by observing that the source and destination files' sizes 48and mtimes match). 49.Nm 50does not cross mount points in either the source or the destination. 51As a safety measure, 52.Nm 53refuses to replace a destination directory with a file. 54.Pp 55The following options are available: 56.Bl -tag -width flag 57.It Fl C 58If the source or target is a remote host, request that the 59.Xr ssh 1 60session be compressed. 61This is the same as 62.Fl F 63.Fl C . 64.It Fl v Ns Op Cm v Ns Op Cm v 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 d 77Print directories as they are being traversed. 78Useful to watch the progress; 79this typically produces much less output than 80.Fl vv . 81.It Fl u 82Causes the output generated by 83.Fl v 84and 85.Fl d 86to be unbuffered. 87This can be useful for obtaining prompt progress updates through a pipe. 88.It Fl I 89will cause 90.Nm 91to print a summary at the end with performance counters. 92.It Fl f 93Forces file updates to occur even if the files appear to be the same. If 94the 95.Fl H 96option is used, this option will force a byte for byte comparison 97between the original file and the file in the hardlink path, even if 98all the stat info matches, but will still use a hardlink if they match. 99.It Fl F Ar ssh-arg 100Pass 101.Ar ssh-arg 102to ssh. For example 103.Dq Fl F Fl p222 . 104Note the lack of a space. 105.It Fl s0 106Disable the disallow-file-replaces-directory safety feature. This 107safety feature is enabled by default to prevent user mistakes from blowing 108away everything accidentally. 109.It Fl i0 110Do not request confirmation when removing something. 111.It Fl j0 112Do not try to recreate CHR or BLK devices. 113.It Fl l 114Line buffer verbose output. 115.It Fl q 116Quiet operation. 117.It Fl o 118Do not remove any files, just overwrite/add. 119.It Fl m 120Generate and maintain a MD5 checkfile called 121.Pa \&.MD5.CHECKSUMS 122in each directory on the source 123and do an MD5 check on each file of the destination when the destination 124appears to be the same as the source. If the check fails, 125the source is recopied to the destination. When you specify a destination 126directory, the MD5 checkfile is only updated as needed and may not be updated 127even if modifications are made to a source file. If you do not specify a 128destination directory the 129.Nm 130command forcefully regenerates the MD5 checkfile for every file in the source. 131.It Fl M Ar file 132Works the same as 133.Fl m 134but allows you to specify the name of the MD5 checkfile. 135.It Fl H Ar path 136.Nm 137will create a hardlink from a file found under 138.Ar path 139to the target instead of copying the source to the target if the file found 140via 141.Ar path 142is identical to the source. 143Note that a remote host specification should not be used for this option's 144.Ar path , 145but the 146.Ar path 147will be relative to the target machine. 148.Pp 149This allows one to use 150.Nm 151to create incremental backups of a filesystem. Create a direct 152.Sq level 0 153backup, and then specify the level 0 backup path with this option when 154creating an incremental backup to a different target directory. 155This method works so long as the filesystem does not hit a hardlink limit. 156If the system does hit a hardlink limit, 157.Nm 158will generate a warning and copy the file instead. 159Note that 160.Nm 161must record file paths for any hardlinked file while operating and therefore 162uses a great deal more memory when dealing with hardlinks or hardlink-based 163backups. Example use: 164.Pp 165.Dl cpdup \-i0 \-s0 \-I \-H /backup/home.l0 /home /backup/home.l1 166.Pp 167WARNING: If this option is used 168.Nm 169must record the paths for all files it encounters while it operates 170and it is possible that you may run the process out of memory. 171.Pp 172The file found via the hardlink path will be byte-by-byte compared with the 173source if the 174.Fl V 175or 176.Fl f 177option is also used, otherwise only the stat info is checked to determine 178whether it matches the source. 179.It Fl V 180This forces the contents of regular files to be verified, even if the 181files appear to the be the same. Whereas the 182.Fl f 183(force) option forces a copy regardless, this option will avoid rewriting 184the target if everything matches and the contents are verified to be the 185same. 186.It Fl VV 187This works the same as 188.Fl V 189but ignores mtime entirely, making it suitable for comparing HAMMER 190master and slave filesystems or copies made without mtime retention. 191.It Fl S 192This places 193.Nm 194into slave mode and is used to initiate the slave protocol on a remote 195machine. 196.It Fl k 197Generate and maintain a FSMID checkfile called 198.Pa \& .FSMID.CHECK 199in each directory on the target. 200.Nm 201will check the FSMID for each source file or directory against the checkfile 202on the target and will not copy the file or recurse through the directory 203when a match occurs. Any source file or directory with the same name as the 204checkfile will be ignored. The FSMID will be re-checked after the copy 205has been completed and 206.Nm 207will loop on that directory or file until it is sure it has an exact copy. 208.Pp 209Warning: FSMID is not always supported by a filesystem and may not be 210synchronized if a crash occurs. 211.Dx 212will simulate an FSMID when 213it is otherwise not supported by the filesystem, and users should be aware 214that simulated FSMIDs may change state in such cases even if the underlying 215hierarchy does not due to cache flushes. 216Additionally, the FSMID may not reflect changes made to remote filesystems 217by other hosts. For example, using these options with NFS mounted sources 218will not work well. 219.It Fl K Ar file 220Works the same as 221.Fl k 222but allows you to specify the name of the FSMID checkfile. 223.It Fl x 224Causes 225.Nm 226to use the exclusion file 227.Pa \&.cpignore 228in each directory on the source to 229determine which files to ignore. When this option is used, the exclusion 230filename itself is automatically excluded from the copy. If this option is 231not used then the filename 232.Pa \&.cpignore 233is not considered special and will 234be copied along with everything else. 235.It Fl X Ar file 236Works the same as 237.Fl x 238but allows you to specify the name of the exclusion file. This file is 239automatically excluded from the copy. Only one exclusion file may be 240specified. 241.El 242.Sh REMOTE COPYING 243.Nm 244can mirror directory structures across machines and can also do third-party 245copies. 246.Xr ssh 1 247sessions are used and 248.Nm 249is run on the remote machine(s) in slave mode. 250You can use the 251.Fl F 252option to pass additional flags to the ssh command if necessary. 253.Pp 254The syntax of remote path specifications is similar to 255.Xr scp 1 . 256In particular, that means that a local path containing a colon must 257be preceded by a slash to prevent it being considered a remote host: 258.Ql foo:bar 259causes 260.Nm 261to look for a directory called 262.Ql bar 263on host 264.Ql foo , 265while 266.Ql \&./foo:bar 267denotes the directory 268.Ql foo:bar 269on the local machine. 270.Sh DIAGNOSTICS 271The 272.Nm 273utility exits 0 if no error occurred and >0 if an error occurred. 274.Sh SEE ALSO 275.Xr cp 1 , 276.Xr cpio 1 , 277.Xr scp 1 , 278.Xr ssh 1 , 279.Xr tar 1 280.Sh HISTORY 281The 282.Nm 283command was originally created to update servers at BEST Internet circa 1997 284and was placed under the 285.Fx 286copyright for inclusion in the ports area in 1999. 287The program was written by Matthew Dillon and Dima Ruban. 288.Sh BUGS 289.Xr UFS 5 290has a hardlink limit of 32767. Many programs, in particular CVS 291with regards to its CVS/Root file, will generate a lot of hard links. 292When using the 293.Fl H 294option it may not be possible for 295.Nm 296to maintain these hard links. If this occurs, 297.Nm 298will be forced to copy the file instead of link it, and thus not be able 299to make a perfect copy of the filesystem. 300.Pp 301Currently the remote protocol uses host byte order. Therefore, 302.Nm 303cannot talk to machines that use a byte order 304different from the local machine. 305.Pp 306When so-called sparse files (i.e. files with "holes") are copied, 307the holes will be filled in the target files, so they occupy 308more physical disk space than the source files. 309