Add an option that causes cpdup to skip CHR or BLK devices. This option
[dragonfly.git] / bin / cpdup / cpdup.1
CommitLineData
3a42736d
MD
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.\"
ac482a7e 6.\" $DragonFly: src/bin/cpdup/cpdup.1,v 1.18 2006/09/21 04:09:28 dillon Exp $
3a42736d
MD
7.Dd October 28, 1999
8.Dt CPDUP 1
b28a9db4 9.Os
3a42736d
MD
10.Sh NAME
11.Nm cpdup
12.Nd mirror filesystems
13.Sh SYNOPSIS
14.Nm cpdup
15.Op Fl v[vv..]
4d2076d3 16.Op Fl u
3a42736d
MD
17.Op Fl I
18.Op Fl f
19.Op Fl s0
20.Op Fl i0
ac482a7e 21.Op Fl j0
3a42736d
MD
22.Op Fl q
23.Op Fl o
24.Op Fl m
25.Oo
4e316ad5
MD
26.Fl H
27.Ar path
28.Oc
29.Oo
3a42736d
MD
30.Fl M
31.Ar file
32.Oc
4d858d58 33.Op Fl S
577109ea
MD
34.Op Fl k
35.Oo
36.Fl K
37.Ar file
38.Oc
3a42736d 39.Oo
c0d18d1d 40.Fl X
3a42736d
MD
41.Ar file
42.Oc
c0d18d1d 43.Op Fl x
4d858d58
MD
44.Ar [[user@]host:]source_dir
45.Ar [[user@]host:]target_dir
3a42736d 46.Sh DESCRIPTION
1bf4b486 47The
3a42736d
MD
48.Nm
49utility makes an exact mirror copy of the source in the destination, creating
1bf4b486 50and deleting files and directories as necessary. UTimes, hardlinks,
3a42736d
MD
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
1bf4b486 55been synchronized (by observing that the source and destination file's size
3a42736d
MD
56and mtimes match).
57.Nm
73afa964
CP
58does not cross mount points in either the source or the destination.
59As a safety measure,
3a42736d
MD
60.Nm
61refuses to replace a destination directory with a file.
62.Pp
63The following options are available:
64.Bl -tag -width flag
0dc55843 65.It Fl v[vv]
3a42736d
MD
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
1bf4b486 72will report directories as they are being traversed as well as
3a42736d
MD
73modifications made to the destination.
74.Fl vvv
75will cause all files and directories to be reported whether or not
76modifications are made.
4d2076d3
CP
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.
3a42736d
MD
82.It Fl I
83will cause cpdup to print a summary at the end with performance counter.
84.It Fl f
4e316ad5
MD
85Forces file updates to occur even if the files appear to be the same. If
86the
87.Fl H
6db8f15d 88option is used, this option will force a byte for byte comparison
4e316ad5
MD
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.
3a42736d
MD
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.
ac482a7e
MD
97.It Fl j0
98Do not try to recreate CHR or BLK devices.
3a42736d
MD
99.It Fl q
100Quiet operation
101.It Fl o
102Do not remove any files, just overwrite/add.
103.It Fl m
577109ea 104Generate and maintain a MD5 checkfile in each directory on the source
3a42736d 105and do an MD5 check on each file of the destination when the destination
1bf4b486 106appears to be the same as the source. If the check fails,
3a42736d
MD
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.
4e316ad5
MD
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
4d858d58
MD
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
4e316ad5
MD
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
6910d61c
SW
128creating an incremental backup to a different target directory.
129This method works so long as the filesystem does not hit a hardlink limit.
9b2d9484
MD
130If the system does hit a hardlink limit
131.Nm
132will generate a warning and copy the file instead.
133Note that
4e316ad5
MD
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.
577109ea 145.It Fl M Ar file
3a42736d
MD
146Works the same as
147.Fl m
148but allows you to specify the name of the MD5 checkfile.
4d858d58
MD
149.It Fl S
150This places
151.Nm
152into slave mode and is used to initiate the slave protocol on a remote
153machine.
577109ea
MD
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
8709c5ef 164will loop on that directory or file until it is sure it has an exact copy.
577109ea 165.Pp
8709c5ef 166Warning: FSMID is not always supported by a filesystem and may not be
577109ea
MD
167synchronized if a crash occurs. DragonFly will simulate an FSMID when
168it is otherwise not supported by the filesystem, and users should be aware
169that simulated FSMIDs may change state in such cases even if the underlying
8709c5ef 170hierarchy does not due to cache flushes.
577109ea
MD
171Additionally, the FSMID may not reflect changes made to remote filesystems
172by other hosts. For example, using these options with NFS mounted sources
173will not work well.
174.It Fl K Ar file
8709c5ef 175Works the same as
577109ea
MD
176.Fl k
177but allows you to specify the name of the FSMID checkfile.
3a42736d
MD
178.It Fl x
179Causes
180.Nm
181to use the exclusion file ".cpignore" in each directory on the source to
182determine which files to ignore. When this option is used, the exclusion
183filename itself is automatically excluded from the copy. If this option is
2653401f
CP
184not used then the filename ".cpignore" is not considered special and will
185be copied along with everything else.
577109ea 186.It Fl X Ar file
3a42736d
MD
187Works the same as
188.Fl x
189but allows you to specify the name of the exclusion file. This file is
190automatically excluded from the copy. Only one exclusion file may be
191specified.
52ac7bd7 192.El
4d858d58
MD
193.Sh REMOTE COPYING
194.Nm
195can mirror directory structures across machines and can also do third-party
196copies.
197.Xr ssh 1
198sessions are used and
199.Nm
200is run on the remote machine(s) in slave mode.
3a42736d
MD
201.Sh DIAGNOSTICS
202The
203.Nm
9b2d9484 204utility exits 0 if no error occured and >0 if an error occured.
3a42736d
MD
205.Sh SEE ALSO
206.Xr cp 1 ,
207.Xr cpio 1 ,
2653401f 208.Xr tar 1
de023c90
SW
209.Sh HISTORY
210The
211.Nm
212command was original created to update servers at BEST Internet circa 1997
213and was placed under the FreeBSD copyright for inclusion in the ports area
214in 1999. The program was written by Matthew Dillon and Dima Ruban.
9b2d9484
MD
215.Sh BUGS
216UFS has a hardlink limit of 32767. Many programs, in particular CVS
217with regards to its CVS/Root file, will generate a lot of hard links.
218When using the
219.Fl H
220option it may not be possible for
221.Nm
222to maintain these hard links. If this occurs
223.Nm
6910d61c 224will be forced to copy the file instead of link it, and thus not be able
9b2d9484 225to make a perfect copy of the filesystem.