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