Properly handle an error return from udev2dev().
[dragonfly.git] / usr.sbin / ctm / ctm_rmail / ctm_rmail.1
1 .\" NOTICE: This is free documentation.  I hope you get some use from these
2 .\" words.  In return you should think about all the nice people who sweat
3 .\" blood to document their free software.  Maybe you should write some
4 .\" documentation and give it away.  Maybe with a free program attached!
5 .\"
6 .\" Author: Stephen McKay
7 .\"
8 .\" $FreeBSD: src/usr.sbin/ctm/ctm_rmail/ctm_rmail.1,v 1.19.2.7 2003/03/12 22:08:14 trhodes Exp $
9 .\" $DragonFly: src/usr.sbin/ctm/ctm_rmail/Attic/ctm_rmail.1,v 1.2 2003/06/17 04:29:53 dillon Exp $
10 .\"
11 .Dd January 24, 1995
12 .Dt CTM_MAIL 1
13 .Os
14 .Sh NAME
15 .Nm ctm_smail ,
16 .Nm ctm_dequeue ,
17 .Nm ctm_rmail
18 .Nd send and receive
19 .Xr ctm 1
20 deltas via mail
21 .Sh SYNOPSIS
22 .Nm ctm_smail
23 .Op Fl l Ar log
24 .Op Fl m Ar maxmsgsize
25 .Op Fl c Ar maxctmsize
26 .Op Fl q Ar queue-dir
27 .Ar ctm-delta
28 .Ar mail-alias
29 .Nm ctm_dequeue
30 .Op Fl l Ar log
31 .Op Fl n Ar numchunks
32 .Ar queue-dir
33 .Nm ctm_rmail
34 .Op Fl Dfuv
35 .Op Fl l Ar log
36 .Op Fl p Ar piecedir
37 .Op Fl d Ar deltadir
38 .Op Fl b Ar basedir
39 .Op Ar
40 .Sh DESCRIPTION
41 In conjunction with the
42 .Xr ctm 1
43 command,
44 .Nm ctm_smail ,
45 .Nm ctm_dequeue
46 and
47 .Nm ctm_rmail
48 are used to distribute changes to a source tree via email.
49 The
50 .Nm ctm_smail
51 utility is given a compressed
52 .Xr ctm
53 delta, and a mailing list to send it to.  It splits the delta into manageable
54 pieces, encodes them as mail messages and sends them to the mailing list
55 (optionally queued to spread the mail load).
56 Each recipient uses
57 .Nm ctm_rmail
58 (either manually or automatically) to decode and reassemble the delta, and
59 optionally call
60 .Xr ctm
61 to apply it to the source tree.
62 At the moment,
63 several source trees are distributed, and by several sites.  These include
64 the
65 .Fx Ns -current
66 source and CVS trees, distributed by
67 .Li freefall.FreeBSD.org .
68 .Pp
69 Command line arguments for
70 .Nm ctm_smail :
71 .Bl -tag -width indent
72 .It Fl l Ar log
73 Instead of appearing on
74 .Em stderr ,
75 error diagnostics and informational messages (other than command line errors)
76 are time stamped and written to the file
77 .Em log .
78 .It Fl m Ar maxmsgsize
79 Limit the maximum size mail message that
80 .Nm ctm_smail
81 is allowed to send.  It is approximate since mail headers and other niceties
82 are not counted in this limit.  If not specified, it will default to 64000
83 bytes, leaving room for 1535 bytes of headers before the rumoured 64k mail
84 limit.
85 .It Fl c Ar maxctmsize
86 Limit the maximum size delta that will be sent.  Deltas bigger that this
87 limit will cause an apology mail message to be sent to the mailing list.
88 This is to prevent massive changes overwhelming users' mail boxes.  Note that
89 this is the size before encoding.  Encoding causes a 4/3 size increase before
90 mail headers are added.  If not specified, there is no limit.
91 .It Fl q Ar queue-dir
92 Instead of mailing the delta pieces now, store them in the given directory
93 to be mailed later using
94 .Nm ctm_dequeue .
95 This feature allows the mailing of large deltas to be spread out over
96 hours or even days to limit the impact on recipients with limited network
97 bandwidth or small mail spool areas.
98 .El
99 .Pp
100 .Ar ctm-delta
101 is the delta to be sent, and
102 .Ar mail-alias
103 is the mailing list to send the delta to.
104 The mail messages are sent using
105 .Xr sendmail 8 .
106 .Pp
107 Command line arguments for
108 .Nm ctm_dequeue :
109 .Bl -tag -width indent
110 .It Fl l Ar log
111 Instead of appearing on
112 .Em stderr ,
113 error diagnostics and informational messages (other than command line errors)
114 are time stamped and written to the file
115 .Em log .
116 .It Fl n Ar numchunks
117 Limit the number of mail messages that
118 .Nm ctm_dequeue
119 will send per run.  By default,
120 .Nm ctm_dequeue
121 will send one mail message per run.
122 .El
123 .Pp
124 .Ar queuedir
125 is the directory containing the mail messages stored by
126 .Nm ctm_smail .
127 Up to
128 .Ar numchunks
129 mail messages will be sent in each run.  The recipient mailing list is already
130 encoded in the queued files.
131 .Pp
132 It is safe to run
133 .Nm ctm_dequeue
134 while
135 .Nm ctm_smail
136 is adding entries to the queue, or even to run
137 .Nm ctm_smail
138 multiple times concurrently, but a separate queue directory should be used
139 for each tree being distributed.  This is because entries are served in
140 alphabetical order, and one tree will be unfairly serviced before any others,
141 based on the delta names, not delta creation times.
142 .Pp
143 Command line arguments for
144 .Nm ctm_rmail :
145 .Bl -tag -width indent
146 .It Fl l Ar log
147 Instead of appearing on
148 .Em stderr ,
149 error diagnostics and informational messages (other than command line errors)
150 are time stamped and written to the file
151 .Em log .
152 .It Fl p Ar piecedir
153 Collect pieces of deltas in this directory.  Each piece corresponds to a
154 single mail message.  Pieces are removed when complete deltas are built.
155 If this flag is not given, no input files will be read, but completed
156 deltas may still be applied with
157 .Xr ctm
158 if the
159 .Fl b
160 flag is given.
161 .It Fl d Ar deltadir
162 Collect completed deltas in this directory.  Deltas are built from one or
163 more pieces when all pieces are present.
164 .It Fl b Ar basedir
165 Apply any completed deltas to this source tree.  If this flag is not given,
166 deltas will be stored, but not applied.  The user may then apply the deltas
167 manually, or by using
168 .Nm ctm_rmail
169 without the
170 .Fl p
171 flag.
172 Deltas will not be applied if they do not match the
173 .Li .ctm_status
174 file in
175 .Ar basedir
176 (or if
177 .Li .ctm_status
178 does not exist).
179 .It Fl D
180 Delete deltas after successful application by
181 .Xr ctm .
182 It is probably a good idea to avoid this flag (and keep all the deltas) as
183 .Xr ctm
184 has the ability to recover small groups of files from a full set of deltas.
185 .It Fl f
186 Fork and execute in the background while applying deltas with
187 .Xr ctm .
188 This is useful when automatically invoking
189 .Nm ctm_rmail
190 from
191 .Xr sendmail
192 because
193 .Xr ctm
194 can take a very long time to complete, causing other people's mail to
195 be delayed, and can in theory cause spurious
196 mail retransmission due to the remote
197 .Xr sendmail
198 timing out, or even termination of
199 .Nm ctm_rmail
200 by mail filters such as
201 .Xr "MH's"
202 .Xr slocal .
203 Don't worry about zillions of background
204 .Xr ctm
205 processes loading your machine, since locking is used to prevent more than one
206 .Xr ctm
207 invocation at a time.
208 .It Fl u
209 Pass the
210 .Fl u
211 flag to the
212 .Xr ctm
213 command when applying the complete deltas, causing it to set the modification
214 time of created and modified files to the CTM delta creation time.
215 .It Fl v
216 Pass the
217 .Fl v
218 flag to the
219 .Xr ctm
220 command when applying the complete deltas, causing a more informative
221 output.  All
222 .Xr ctm
223 output appears in the
224 .Nm ctm_rmail
225 log file.
226 .El
227 .Pp
228 The file arguments (or
229 .Em stdin ,
230 if there are none) are scanned for delta pieces.  Multiple delta pieces
231 can be read from a single file, so an entire maildrop can be scanned
232 and processed with a single command.
233 .Pp
234 It is safe to invoke
235 .Nm ctm_rmail
236 multiple times concurrently (with different input files),
237 as might happen when
238 .Xr sendmail
239 is delivering mail asynchronously.  This is because locking is used to
240 keep things orderly.
241 .Sh FILE FORMAT
242 Following are the important parts of an actual (very small) delta piece:
243 .Bd -literal
244 From: owner-src-cur
245 To: src-cur
246 Subject: ctm-mail src-cur.0003.gz 1/4
247
248 CTM_MAIL BEGIN src-cur.0003.gz 1 4
249 H4sIAAAAAAACA3VU72/bNhD9bP0VByQoEiyRSZEUSQP9kKTeYCR2gDTdsGFAwB/HRogtG5K8NCj6
250 v4+UZSdtUQh6Rz0eee/xaF/dzx8up3/MFlDkBNrGnbttAwyo1pxoRgoiBNX/QJ5d3c9/X8DcPGGo
251 lggkPiXngE4W1gUjKPJCYyk5MZRbIqmNW/ASglIFcdwIzTUxaAqhnCPcBqloKEkJVNDMF0Azk+Bo
252 dDzzk0Ods/+A5gXv9YyJHjMCtJwQNeESNma7hOmXDRxn
253 CTM_MAIL END 61065
254 .Ed
255 .Pp
256 The subject of the message always begins with
257 .Dq ctm-mail
258 followed by the name of the delta, which piece this is, and how many total
259 pieces there are.  The data are bracketed by
260 .Dq CTM_MAIL BEGIN
261 and
262 .Dq CTM_MAIL END
263 lines, duplicating the information in the subject line, plus a simple checksum.
264 .Pp
265 If the delta exceeds
266 .Ar maxctmsize ,
267 then a message like this will be received instead:
268 .Bd -literal
269 From: owner-src-cur
270 To: src-cur
271 Subject: ctm-notice src-cur.0999.gz
272
273 src-cur.0999.gz is 792843 bytes.  The limit is 300000 bytes.
274
275 You can retrieve this delta via ftpmail, or your good mate at the university.
276 .Ed
277 .Pp
278 You are then on your own!
279 .Sh EXAMPLES
280 To send delta 32 of
281 .Em src-cur
282 to a group of wonderful code hackers known to
283 .Xr sendmail
284 as
285 .Em src-guys ,
286 limiting the mail size to roughly 60000 bytes, you could use:
287 .Bd -literal -offset indent
288 ctm_smail -m 60000 /wherever/it/is/src-cur.0032.gz src-guys
289 .Ed
290 .Pp
291 To decode every
292 .Nm ctm-mail
293 message in your mailbox, assemble them into complete deltas, then apply
294 any deltas built or lying around, you could use:
295 .Bd -literal -offset indent
296 ctm_rmail -p ~/pieces -d ~/deltas -b /usr/ctm-src-cur $MAIL
297 .Ed
298 .Pp
299 (Note that no messages are deleted by
300 .Nm ctm_rmail .
301 Any mail reader could be used for that purpose.)
302 .Pp
303 To create a mail alias called
304 .Em receiver-dude
305 that will automatically decode and assemble deltas, but not apply them,
306 you could put the following lines in your
307 .Pa /etc/mail/aliases
308 file (assuming the
309 .Pa /ctm/tmp
310 and
311 .Pa /ctm/deltas
312 directories and
313 .Pa /ctm/log
314 file are writable by user
315 .Em daemon
316 or group
317 .Em wheel ) :
318 .Bd -literal -offset indent
319 receiver-dude: "|ctm_rmail -p /ctm/tmp -d /ctm/deltas -l /ctm/log"
320 owner-receiver-dude: real_dude@wherever.you.like
321 .Ed
322 .Pp
323 The second line will catch failures and drop them into your regular mailbox,
324 or wherever else you like.
325 .Pp
326 To apply all the deltas collected, and delete those applied, you could use:
327 .Bd -literal -offset indent
328 ctm_rmail -D -d /ctm/deltas -b /ctm/src-cur -l /ctm/apply.log
329 .Ed
330 .Pp
331 For maximum flexibility, consider this excerpt from a
332 .Xr procmail
333 script:
334 .Bd -literal -offset indent
335 PATH=$HOME/bin:$PATH
336
337 :0 w
338 * ^Subject: ctm-mail cvs-cur
339 | ctm_incoming
340 .Ed
341 .Pp
342 together with the
343 shell script
344 .Pa ~/bin/ctm_incoming :
345 .Bd -literal -offset indent
346 #! /bin/sh
347 PATH="$HOME/bin:/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin"
348 export PATH
349
350 cd $HOME/ctm && ctm_rmail -f -p pieces -d deltas -l log -b /ctm
351 .Ed
352 .Pp
353 which will deposit all
354 .Xr ctm
355 deltas in
356 .Pa ~/ctm/deltas ,
357 apply them to the tree in
358 .Pa /ctm ,
359 and drop any failures into your regular mail box.
360 Note the
361 .Ev PATH
362 manipulation in
363 .Pa ctm_incoming
364 which allows
365 .Nm ctm_rmail
366 to execute
367 .Xr ctm 1
368 on the
369 .Pq non- Ns Fx
370 machine that this example was taken from.
371 .Sh SECURITY
372 On its own, CTM is an insecure protocol
373 - there is no authentication performed that the
374 changes applied to the source code were sent by a
375 trusted party, and so care should be taken if the
376 CTM deltas are obtained via an unauthenticated
377 medium such as regular email.
378 It is a relatively simple matter for an attacker
379 to forge a CTM delta to replace or precede the
380 legitimate one and insert malicious code into your
381 source tree.
382 If the legitimate delta is somehow prevented from
383 arriving, this will go unnoticed until a later
384 delta attempts to touch the same file, at which
385 point the MD5 checksum will fail.
386 .Pp
387 To remedy this insecurity, CTM delta pieces generated by
388 FreeBSD.org are cryptographically signed in a
389 format compatible with the GNU Privacy Guard
390 utility, available in /usr/ports/security/gpg, and
391 the Pretty Good Privacy v5 utility,
392 /usr/ports/security/pgp5.
393 The relevant public key can be obtained by
394 fingering ctm@FreeBSD.org.
395 .Pp
396 CTM deltas which are thus signed cannot be
397 undetectably altered by an attacker.
398 Therefore it is recommended that you make use of
399 GPG or PGP5 to verify the signatures if you
400 receive your CTM deltas via email.
401 .\" This next request is for sections 1, 6, 7 & 8 only
402 .Sh ENVIRONMENT
403 If deltas are to be applied then
404 .Xr ctm 1
405 and
406 .Xr gunzip 1
407 must be in your
408 .Ev PATH .
409 .Sh FILES
410 .Bl -tag -width indent
411 .It Pa QUEUEDIR/*
412 Pieces of deltas encoded as mail messages waiting to be sent to the
413 mailing list.
414 .It Pa PIECEDIR/*
415 Pieces of deltas waiting for the rest to arrive.
416 .It Pa DELTADIR/*
417 Completed deltas.
418 .It Pa BASEDIR/.ctm_status
419 File containing the name and number of the next delta to be applied to this
420 source tree.
421 .El
422 .Sh DIAGNOSTICS
423 The
424 .Nm ctm_smail ,
425 .Nm ctm_dequeue
426 and
427 .Nm ctm_rmail
428 utilities return exit status 0 for success, and 1 for various failures.
429 The
430 .Nm ctm_rmail
431 utility is expected to be called from a mail transfer program, and thus signals
432 failure only when the input mail message should be bounced (preferably into
433 your regular maildrop, not back to the sender).  In short, failure to
434 apply a completed delta with
435 .Xr ctm
436 is not considered an error important enough to bounce the mail, and
437 .Nm ctm_rmail
438 returns an exit status of 0.
439 .Pp
440 In normal operation,
441 .Nm ctm_smail
442 will report messages like:
443 .Bd -literal -offset indent
444 ctm_smail: src-cur.0250.gz 1/2 sent to src-guys
445 .Ed
446 .Pp
447 or, if queueing,
448 .Bd -literal -offset indent
449 ctm_smail: src-cur.0250.gz 1/2 queued for src-guys
450 .Ed
451 .Pp
452 The
453 .Nm ctm_dequeue
454 utility will report messages like:
455 .Bd -literal -offset indent
456 ctm_dequeue: src-cur.0250.gz 1/2 sent
457 .Ed
458 .Pp
459 The
460 .Nm ctm_rmail
461 utility will report messages like:
462 .Bd -literal -offset indent
463 ctm_rmail: src-cur.0250.gz 1/2 stored
464 ctm_rmail: src-cur.0250.gz 2/2 stored
465 ctm_rmail: src-cur.0250.gz complete
466 .Ed
467 .Pp
468 If any of the input files do not contain a valid delta piece,
469 .Nm ctm_rmail
470 will report:
471 .Bd -literal -offset indent
472 ctm_rmail: message contains no delta
473 .Ed
474 .Pp
475 and return an exit status of 1.  You can use this to redirect wayward messages
476 back into your real mailbox if your mail filter goes wonky.
477 .Pp
478 These messages go to
479 .Em stderr
480 or to the log file.  Messages from
481 .Xr ctm 1
482 turn up here too.  Error messages should be self explanatory.
483 .Sh SEE ALSO
484 .Xr ctm 1 ,
485 .Xr ctm 5
486 .\" .Sh HISTORY
487 .Sh AUTHORS
488 .An Stephen McKay Aq mckay@FreeBSD.org