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!
6 .\" Author: Stephen McKay
8 .\" $FreeBSD: src/usr.sbin/ctm/ctm_rmail/ctm_rmail.1,v 1.19.2.7 2003/03/12 22:08:14 trhodes Exp $
23 .Op Fl m Ar maxmsgsize
24 .Op Fl c Ar maxctmsize
40 In conjunction with the
47 are used to distribute changes to a source tree via email.
50 utility is given a compressed
52 delta, and a mailing list to send it to. It splits the delta into manageable
53 pieces, encodes them as mail messages and sends them to the mailing list
54 (optionally queued to spread the mail load).
57 (either manually or automatically) to decode and reassemble the delta, and
60 to apply it to the source tree.
62 several source trees are distributed, and by several sites. These include
65 source and CVS trees, distributed by
66 .Li freefall.FreeBSD.org .
68 Command line arguments for
70 .Bl -tag -width indent
72 Instead of appearing on
74 error diagnostics and informational messages (other than command line errors)
75 are time stamped and written to the file
77 .It Fl m Ar maxmsgsize
78 Limit the maximum size mail message that
80 is allowed to send. It is approximate since mail headers and other niceties
81 are not counted in this limit. If not specified, it will default to 64000
82 bytes, leaving room for 1535 bytes of headers before the rumoured 64k mail
84 .It Fl c Ar maxctmsize
85 Limit the maximum size delta that will be sent. Deltas bigger that this
86 limit will cause an apology mail message to be sent to the mailing list.
87 This is to prevent massive changes overwhelming users' mail boxes. Note that
88 this is the size before encoding. Encoding causes a 4/3 size increase before
89 mail headers are added. If not specified, there is no limit.
91 Instead of mailing the delta pieces now, store them in the given directory
92 to be mailed later using
94 This feature allows the mailing of large deltas to be spread out over
95 hours or even days to limit the impact on recipients with limited network
96 bandwidth or small mail spool areas.
100 is the delta to be sent, and
102 is the mailing list to send the delta to.
103 The mail messages are sent using
106 Command line arguments for
108 .Bl -tag -width indent
110 Instead of appearing on
112 error diagnostics and informational messages (other than command line errors)
113 are time stamped and written to the file
115 .It Fl n Ar numchunks
116 Limit the number of mail messages that
118 will send per run. By default,
120 will send one mail message per run.
124 is the directory containing the mail messages stored by
128 mail messages will be sent in each run. The recipient mailing list is already
129 encoded in the queued files.
135 is adding entries to the queue, or even to run
137 multiple times concurrently, but a separate queue directory should be used
138 for each tree being distributed. This is because entries are served in
139 alphabetical order, and one tree will be unfairly serviced before any others,
140 based on the delta names, not delta creation times.
142 Command line arguments for
144 .Bl -tag -width indent
146 Instead of appearing on
148 error diagnostics and informational messages (other than command line errors)
149 are time stamped and written to the file
152 Collect pieces of deltas in this directory. Each piece corresponds to a
153 single mail message. Pieces are removed when complete deltas are built.
154 If this flag is not given, no input files will be read, but completed
155 deltas may still be applied with
161 Collect completed deltas in this directory. Deltas are built from one or
162 more pieces when all pieces are present.
164 Apply any completed deltas to this source tree. If this flag is not given,
165 deltas will be stored, but not applied. The user may then apply the deltas
166 manually, or by using
171 Deltas will not be applied if they do not match the
179 Delete deltas after successful application by
181 It is probably a good idea to avoid this flag (and keep all the deltas) as
183 has the ability to recover small groups of files from a full set of deltas.
185 Fork and execute in the background while applying deltas with
187 This is useful when automatically invoking
193 can take a very long time to complete, causing other people's mail to
194 be delayed, and can in theory cause spurious
195 mail retransmission due to the remote
197 timing out, or even termination of
199 by mail filters such as
202 Don't worry about zillions of background
204 processes loading your machine, since locking is used to prevent more than one
206 invocation at a time.
212 command when applying the complete deltas, causing it to set the modification
213 time of created and modified files to the CTM delta creation time.
219 command when applying the complete deltas, causing a more informative
222 output appears in the
227 The file arguments (or
229 if there are none) are scanned for delta pieces. Multiple delta pieces
230 can be read from a single file, so an entire maildrop can be scanned
231 and processed with a single command.
235 multiple times concurrently (with different input files),
238 is delivering mail asynchronously. This is because locking is used to
241 Following are the important parts of an actual (very small) delta piece:
245 Subject: ctm-mail src-cur.0003.gz 1/4
247 CTM_MAIL BEGIN src-cur.0003.gz 1 4
248 H4sIAAAAAAACA3VU72/bNhD9bP0VByQoEiyRSZEUSQP9kKTeYCR2gDTdsGFAwB/HRogtG5K8NCj6
249 v4+UZSdtUQh6Rz0eee/xaF/dzx8up3/MFlDkBNrGnbttAwyo1pxoRgoiBNX/QJ5d3c9/X8DcPGGo
250 lggkPiXngE4W1gUjKPJCYyk5MZRbIqmNW/ASglIFcdwIzTUxaAqhnCPcBqloKEkJVNDMF0Azk+Bo
251 dDzzk0Ods/+A5gXv9YyJHjMCtJwQNeESNma7hOmXDRxn
255 The subject of the message always begins with
257 followed by the name of the delta, which piece this is, and how many total
258 pieces there are. The data are bracketed by
262 lines, duplicating the information in the subject line, plus a simple checksum.
266 then a message like this will be received instead:
270 Subject: ctm-notice src-cur.0999.gz
272 src-cur.0999.gz is 792843 bytes. The limit is 300000 bytes.
274 You can retrieve this delta via ftpmail, or your good mate at the university.
277 You are then on your own!
281 to a group of wonderful code hackers known to
285 limiting the mail size to roughly 60000 bytes, you could use:
286 .Bd -literal -offset indent
287 ctm_smail -m 60000 /wherever/it/is/src-cur.0032.gz src-guys
292 message in your mailbox, assemble them into complete deltas, then apply
293 any deltas built or lying around, you could use:
294 .Bd -literal -offset indent
295 ctm_rmail -p ~/pieces -d ~/deltas -b /usr/ctm-src-cur $MAIL
298 (Note that no messages are deleted by
300 Any mail reader could be used for that purpose.)
302 To create a mail alias called
304 that will automatically decode and assemble deltas, but not apply them,
305 you could put the following lines in your
306 .Pa /etc/mail/aliases
313 file are writable by user
317 .Bd -literal -offset indent
318 receiver-dude: "|ctm_rmail -p /ctm/tmp -d /ctm/deltas -l /ctm/log"
319 owner-receiver-dude: real_dude@wherever.you.like
322 The second line will catch failures and drop them into your regular mailbox,
323 or wherever else you like.
325 To apply all the deltas collected, and delete those applied, you could use:
326 .Bd -literal -offset indent
327 ctm_rmail -D -d /ctm/deltas -b /ctm/src-cur -l /ctm/apply.log
330 For maximum flexibility, consider this excerpt from a
333 .Bd -literal -offset indent
337 * ^Subject: ctm-mail cvs-cur
343 .Pa ~/bin/ctm_incoming :
344 .Bd -literal -offset indent
346 PATH="$HOME/bin:/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin"
349 cd $HOME/ctm && ctm_rmail -f -p pieces -d deltas -l log -b /ctm
352 which will deposit all
356 apply them to the tree in
358 and drop any failures into your regular mail box.
369 machine that this example was taken from.
371 On its own, CTM is an insecure protocol
372 - there is no authentication performed that the
373 changes applied to the source code were sent by a
374 trusted party, and so care should be taken if the
375 CTM deltas are obtained via an unauthenticated
376 medium such as regular email.
377 It is a relatively simple matter for an attacker
378 to forge a CTM delta to replace or precede the
379 legitimate one and insert malicious code into your
381 If the legitimate delta is somehow prevented from
382 arriving, this will go unnoticed until a later
383 delta attempts to touch the same file, at which
384 point the MD5 checksum will fail.
386 To remedy this insecurity, CTM delta pieces generated by
387 FreeBSD.org are cryptographically signed in a
388 format compatible with the GNU Privacy Guard
389 utility, available in /usr/ports/security/gpg, and
390 the Pretty Good Privacy v5 utility,
391 /usr/ports/security/pgp5.
392 The relevant public key can be obtained by
393 fingering ctm@FreeBSD.org.
395 CTM deltas which are thus signed cannot be
396 undetectably altered by an attacker.
397 Therefore it is recommended that you make use of
398 GPG or PGP5 to verify the signatures if you
399 receive your CTM deltas via email.
400 .\" This next request is for sections 1, 6, 7 & 8 only
402 If deltas are to be applied then
409 .Bl -tag -width indent
411 Pieces of deltas encoded as mail messages waiting to be sent to the
414 Pieces of deltas waiting for the rest to arrive.
417 .It Pa BASEDIR/.ctm_status
418 File containing the name and number of the next delta to be applied to this
427 utilities return exit status 0 for success, and 1 for various failures.
430 utility is expected to be called from a mail transfer program, and thus signals
431 failure only when the input mail message should be bounced (preferably into
432 your regular maildrop, not back to the sender). In short, failure to
433 apply a completed delta with
435 is not considered an error important enough to bounce the mail, and
437 returns an exit status of 0.
441 will report messages like:
442 .Bd -literal -offset indent
443 ctm_smail: src-cur.0250.gz 1/2 sent to src-guys
447 .Bd -literal -offset indent
448 ctm_smail: src-cur.0250.gz 1/2 queued for src-guys
453 utility will report messages like:
454 .Bd -literal -offset indent
455 ctm_dequeue: src-cur.0250.gz 1/2 sent
460 utility will report messages like:
461 .Bd -literal -offset indent
462 ctm_rmail: src-cur.0250.gz 1/2 stored
463 ctm_rmail: src-cur.0250.gz 2/2 stored
464 ctm_rmail: src-cur.0250.gz complete
467 If any of the input files do not contain a valid delta piece,
470 .Bd -literal -offset indent
471 ctm_rmail: message contains no delta
474 and return an exit status of 1. You can use this to redirect wayward messages
475 back into your real mailbox if your mail filter goes wonky.
479 or to the log file. Messages from
481 turn up here too. Error messages should be self explanatory.
487 .An Stephen McKay Aq mckay@FreeBSD.org