Initial import from FreeBSD RELENG_4:
[dragonfly.git] / usr.sbin / ctm / ctm / ctm.1
1 .\"----------------------------------------------------------------------------
2 .\""THE BEER-WARE LICENSE" (Revision 42):
3 .\"<joerg@FreeBSD.org> wrote this file.  As long as you retain this notice you
4 .\"can do whatever you want with this stuff. If we meet some day, and you think
5 .\"this stuff is worth it, you can buy me a beer in return.       Joerg Wunsch
6 .\"----------------------------------------------------------------------------
7 .\"
8 .\" This manual page is partially obtained from Poul-Hennings CTM README
9 .\" file.
10 .\"
11 .\" CTM and ctm(1) by <phk@FreeBSD.org>
12 .\"
13 .\" $FreeBSD: src/usr.sbin/ctm/ctm/ctm.1,v 1.17.2.9 2003/03/12 22:08:14 trhodes Exp $
14 .\"
15 .Dd March 25, 1995
16 .Os
17 .Dt CTM 1
18 .Sh NAME
19 .Nm ctm
20 .Nd source code mirror program
21 .Sh SYNOPSIS
22 .Nm
23 .Op Fl cFklquv
24 .Op Fl b Ar basedir
25 .Op Fl B Ar backup-file
26 .Op Fl e Ar include-regex
27 .Op Fl t Ar tar-command
28 .Op Fl T Ar tmpdir
29 .Op Fl V Ar level
30 .Op Fl x Ar exclude-regex
31 .Ar
32 .Sh DESCRIPTION
33 The
34 .Nm
35 utility was originally
36 .Dq Cvs Through eMail ,
37 but now instead it seems more fitting to call it
38 .Dq Current Through eMail .
39 .Pp
40 The
41 .Nm
42 utility is now meant to be the definitive way to make and apply a delta between
43 two versions of a directory tree.
44 .Pp
45 There are two parts to this, making the delta and applying it.  These are two
46 entirely different things.
47 .Ss Usage
48 To apply a CTM delta, you pass it to the
49 .Nm
50 command.  You can pass a CTM delta on stdin, or you can give the
51 filename as an argument.  If you do the latter, you make life a lot
52 easier for your self, since the program can accept gzip'ed files and
53 since it will not have to make a temporary copy of your file.  You can
54 specify multiple deltas at one time, they will be processed one at a
55 time.  Deltas that are already applied will be ignored.
56 .Pp
57 The
58 .Nm
59 command runs in a number of passes.  It will process the entire
60 input file in each pass, before commencing with the next pass.
61 .Pp
62 Before working on a file
63 .Ar name
64 .Nm
65 first checks for the existence of the file
66 .Ar name.ctm .
67 If this file exists,
68 .Nm
69 works on it instead.
70 .Pp
71 Pass 1 will verify that the input file is OK.  The syntax, the data
72 and the global MD5 checksum will be checked.  If any of these fail,
73 .Nm
74 will simply reject the input file.
75 .Pp
76 Pass 2 will validate that the directory tree is in the state expected by
77 the CTM delta.  This is done by looking for files and directories which
78 should/should not exist and by checking the MD5 checksums of files.
79 .Pp
80 If a
81 .Ar backup-file
82 had been specified using the
83 .Fl B
84 option, all files that would be modified by this
85 .Nm
86 invocation are backed up
87 to this file using the archiver command specified by the
88 .Fl t
89 option.  The default archiver command is
90 .Nm "tar -rf %s -T -" .
91 .Pp
92 Pass 3 will actually apply the delta.
93 .Pp
94 The list of files that would be modified by
95 .Nm
96 is subject to filtering regular expressions specified
97 using the
98 .Fl e
99 and
100 .Fl x
101 options.
102 The
103 .Fl e
104 and
105 .Fl x
106 options are applied in order of appearance on the command line.  The last
107 filter that matched a given file name determines whether the file would be
108 operated on or left alone by
109 .Nm .
110 .Pp
111 The
112 .Nm
113 utility
114 will extract the file hierarchy below its working directory.  Absolute
115 filenames or filenames containing references through
116 .Sq Pa .\&
117 and
118 .Sq Pa ..\&
119 are explicitly prohibited as a security measure.
120 .Ss Options
121 .Bl -tag -width indent
122 .It Fl b Ar basedir
123 Prepend the path
124 .Ar basedir
125 to every filename.
126 .It Fl B Ar backup-file
127 Backup all files that would be modified by this CTM run to
128 .Ar backup-file .
129 If any filters are specified using the
130 .Fl e
131 and
132 .Fl x
133 options, then the final set of files backed up are those that would be
134 modified by CTM after the filters are applied.
135 .It Fl c
136 Check it out, don't do anything.
137 .It Fl e Ar regular_expression
138 Match each name in the CTM file against
139 .Ar regular_expression ,
140 and if it matches process the file, otherwise leave it alone.  There may be
141 any number of these options.  Use of this option disables the
142 .Pa .ctm_status
143 sequence number checks.  For example, the expression
144 .Ic ^usr.sbin/ctm
145 for example, will select the
146 .Pa usr.sbin/ctm
147 source directory and all pathnames under it.
148 .Pp
149 Pathnames can be disabled from being considered by CTM using the
150 .Fl x
151 option.
152 .It Fl F
153 Force.
154 .It Fl k
155 Keep files and directories and don't remove them even if the CTM file
156 specifies they are to be removed.  If the
157 .Fl B
158 option is specified, these files and directories will not be backed up.
159 .It Fl l
160 List files that would be modified by this invocation of CTM and the
161 actions that would be performed on them.  Use of the
162 .Fl l
163 option disables the
164 .Pa .ctm_status
165 checks and integrity checks on the source tree being operated on.  The
166 .Fl l
167 option can be combined with the
168 .Fl e
169 and
170 .Fl x
171 options to determine which files would be modified by the given set of
172 command line options.
173 .It Fl q
174 Tell us less.
175 .It Fl t Ar tar-command
176 Use
177 .Ar tar-command
178 instead of the default archiver
179 .Nm tar .
180 This option takes effect only if a backup file had been specified using the
181 .Fl B
182 option.  A %s in the tar command will be replaced by the name of the backup
183 file.
184 .It Fl T Ar tmpdir
185 Put temporary files under
186 .Ar tmpdir .
187 .It Fl u
188 Set modification time of created and modified files to the CTM delta
189 creation time.
190 .It Fl v
191 Tell us more.
192 .It Fl V Ar level
193 Tell us more.
194 .Ar Level
195 is the level of verbosity.
196 .It Fl x Ar regular_expression
197 Match each name in the CTM file against
198 .Ar regular_expression
199 and if it matches, leave the file alone.  There may be any number of these
200 options.  Use of this option disables the
201 .Pa .ctm_status
202 sequence number checks.
203 .Pp
204 Pathnames can be selected for CTM's consideration using the
205 .Fl e
206 option.
207 .El
208 .Sh SECURITY
209 On its own, CTM is an insecure protocol
210 - there is no authentication performed that the
211 changes applied to the source code were sent by a
212 trusted party, and so care should be taken if the
213 CTM deltas are obtained via an unauthenticated
214 medium such as regular email.
215 It is a relatively simple matter for an attacker
216 to forge a CTM delta to replace or precede the
217 legitimate one and insert malicious code into your
218 source tree.
219 If the legitimate delta is somehow prevented from
220 arriving, this will go unnoticed until a later
221 delta attempts to touch the same file, at which
222 point the MD5 checksum will fail.
223 .Pp
224 To remedy this insecurity, CTM pieces generated by
225 FreeBSD.org are cryptographically signed in a
226 format compatible with the GNU Privacy Guard
227 utility, available in /usr/ports/security/gpg, and
228 the Pretty Good Privacy v5 utility,
229 /usr/ports/security/pgp5.
230 The relevant public key can be obtained by
231 fingering ctm@FreeBSD.org.
232 .Pp
233 CTM deltas which are thus signed cannot be
234 undetectably altered by an attacker.
235 Therefore it is recommended that you make use of
236 GPG or PGP5 to verify the signatures if you
237 receive your CTM deltas via email.
238 .Sh ENVIRONMENT
239 .Ev TMPDIR ,
240 if set to a pathname, will cause ctm to use that pathname
241 as the location of temporary file.
242 See
243 .Xr tempnam 3 ,
244 for more details on this.
245 The same effect may be achieved with the
246 .Fl T
247 flag.
248 .Sh FILES
249 .Pa .ctm_status
250 contains the sequence number of the last CTM delta applied.  Changing
251 or removing this file will greatly confuse
252 .Nm .
253 .Pp
254 Using the
255 .Fl e
256 and
257 .Fl x
258 options can update a partial subset of the source tree and causes sources
259 to be in an inconsistent state.  It is assumed that you know what you are
260 doing when you use these options.
261 .Sh EXAMPLES
262 .Bd -literal
263 cd ~cvs
264 /usr/sbin/ctm ~ctm/cvs-*
265 .Ed
266 .Pp
267 To extract and patch all sources under `lib'
268 .Bd -literal
269 cd ~/lib-srcs
270 /usr/sbin/ctm -e '^lib' ~ctm/src-cur*
271 .Ed
272 .Sh DIAGNOSTICS
273 Numerous messages, hopefully self-explanatory.  The
274 .Dq noise level
275 can be adjusted with the
276 .Fl q ,
277 .Fl v
278 and
279 .Fl V
280 options.
281 .Sh SEE ALSO
282 .Xr ctm_rmail 1 ,
283 .Xr ctm 5
284 .Sh HISTORY
285 Initial trials were run during the work on
286 .Fx 1.1.5 ,
287 and many bugs and
288 methods were hashed out.
289 .Pp
290 The
291 .Nm
292 command appeared in
293 .Fx 2.1 .
294 .Sh AUTHORS
295 The CTM system has been designed and implemented by
296 .An Poul-Henning Kamp
297 .Aq phk@FreeBSD.org .
298 .Pp
299 .An Joerg Wunsch
300 .Aq joerg@FreeBSD.org
301 wrote this man-page.