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
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.
53 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).
58 (either manually or automatically) to decode and reassemble the delta, and
61 to apply it to the source tree.
63 several source trees are distributed, and by several sites.
67 source and CVS trees, distributed by
68 .Li freefall.FreeBSD.org .
70 Command line arguments for
72 .Bl -tag -width indent
74 Instead of appearing on
76 error diagnostics and informational messages (other than command line errors)
77 are time stamped and written to the file
79 .It Fl m Ar maxmsgsize
80 Limit the maximum size mail message that
83 It is approximate since mail headers and other niceties
84 are not counted in this limit.
85 If not specified, it will default to 64000
86 bytes, leaving room for 1535 bytes of headers before the rumoured 64k mail
88 .It Fl c Ar maxctmsize
89 Limit the maximum size delta that will be sent.
90 Deltas bigger that this
91 limit will cause an apology mail message to be sent to the mailing list.
92 This is to prevent massive changes overwhelming users' mail boxes.
94 this is the size before encoding.
95 Encoding causes a 4/3 size increase before
96 mail headers are added.
97 If not specified, there is no limit.
99 Instead of mailing the delta pieces now, store them in the given directory
100 to be mailed later using
102 This feature allows the mailing of large deltas to be spread out over
103 hours or even days to limit the impact on recipients with limited network
104 bandwidth or small mail spool areas.
108 is the delta to be sent, and
110 is the mailing list to send the delta to.
111 The mail messages are sent using
114 Command line arguments for
116 .Bl -tag -width indent
118 Instead of appearing on
120 error diagnostics and informational messages (other than command line errors)
121 are time stamped and written to the file
123 .It Fl n Ar numchunks
124 Limit the number of mail messages that
129 will send one mail message per run.
133 is the directory containing the mail messages stored by
137 mail messages will be sent in each run.
138 The recipient mailing list is already
139 encoded in the queued files.
145 is adding entries to the queue, or even to run
147 multiple times concurrently, but a separate queue directory should be used
148 for each tree being distributed.
149 This is because entries are served in
150 alphabetical order, and one tree will be unfairly serviced before any others,
151 based on the delta names, not delta creation times.
153 Command line arguments for
155 .Bl -tag -width indent
157 Instead of appearing on
159 error diagnostics and informational messages (other than command line errors)
160 are time stamped and written to the file
163 Collect pieces of deltas in this directory.
164 Each piece corresponds to a
166 Pieces are removed when complete deltas are built.
167 If this flag is not given, no input files will be read, but completed
168 deltas may still be applied with
174 Collect completed deltas in this directory.
175 Deltas are built from one or
176 more pieces when all pieces are present.
178 Apply any completed deltas to this source tree.
179 If this flag is not given,
180 deltas will be stored, but not applied.
181 The user may then apply the deltas
182 manually, or by using
187 Deltas will not be applied if they do not match the
195 Delete deltas after successful application by
197 It is probably a good idea to avoid this flag (and keep all the deltas) as
199 has the ability to recover small groups of files from a full set of deltas.
201 Fork and execute in the background while applying deltas with
203 This is useful when automatically invoking
209 can take a very long time to complete, causing other people's mail to
210 be delayed, and can in theory cause spurious
211 mail retransmission due to the remote
213 timing out, or even termination of
215 by mail filters such as
218 Do not worry about zillions of background
220 processes loading your machine, since locking is used to prevent more than one
222 invocation at a time.
228 command when applying the complete deltas, causing it to set the modification
229 time of created and modified files to the CTM delta creation time.
235 command when applying the complete deltas, causing a more informative
239 output appears in the
244 The file arguments (or
246 if there are none) are scanned for delta pieces.
247 Multiple delta pieces
248 can be read from a single file, so an entire maildrop can be scanned
249 and processed with a single command.
253 multiple times concurrently (with different input files),
256 is delivering mail asynchronously.
257 This is because locking is used to
260 Following are the important parts of an actual (very small) delta piece:
264 Subject: ctm-mail src-cur.0003.gz 1/4
266 CTM_MAIL BEGIN src-cur.0003.gz 1 4
267 H4sIAAAAAAACA3VU72/bNhD9bP0VByQoEiyRSZEUSQP9kKTeYCR2gDTdsGFAwB/HRogtG5K8NCj6
268 v4+UZSdtUQh6Rz0eee/xaF/dzx8up3/MFlDkBNrGnbttAwyo1pxoRgoiBNX/QJ5d3c9/X8DcPGGo
269 lggkPiXngE4W1gUjKPJCYyk5MZRbIqmNW/ASglIFcdwIzTUxaAqhnCPcBqloKEkJVNDMF0Azk+Bo
270 dDzzk0Ods/+A5gXv9YyJHjMCtJwQNeESNma7hOmXDRxn
274 The subject of the message always begins with
276 followed by the name of the delta, which piece this is, and how many total
278 The data are bracketed by
282 lines, duplicating the information in the subject line, plus a simple checksum.
286 then a message like this will be received instead:
290 Subject: ctm-notice src-cur.0999.gz
292 src-cur.0999.gz is 792843 bytes. The limit is 300000 bytes.
294 You can retrieve this delta via ftp.
297 You are then on your own!
299 If deltas are to be applied then
306 .Bl -tag -width indent
308 Pieces of deltas encoded as mail messages waiting to be sent to the
311 Pieces of deltas waiting for the rest to arrive.
314 .It Pa BASEDIR/.ctm_status
315 File containing the name and number of the next delta to be applied to this
324 utilities return exit status 0 for success, and 1 for various failures.
327 utility is expected to be called from a mail transfer program, and thus signals
328 failure only when the input mail message should be bounced (preferably into
329 your regular maildrop, not back to the sender).
331 apply a completed delta with
333 is not considered an error important enough to bounce the mail, and
335 returns an exit status of 0.
339 to a group of wonderful code hackers known to
343 limiting the mail size to roughly 60000 bytes, you could use:
344 .Bd -literal -offset indent
345 ctm_smail -m 60000 /wherever/it/is/src-cur.0032.gz src-guys
350 message in your mailbox, assemble them into complete deltas, then apply
351 any deltas built or lying around, you could use:
352 .Bd -literal -offset indent
353 ctm_rmail -p ~/pieces -d ~/deltas -b /usr/ctm-src-cur $MAIL
356 (Note that no messages are deleted by
358 Any mail reader could be used for that purpose.)
360 To create a mail alias called
362 that will automatically decode and assemble deltas, but not apply them,
363 you could put the following lines in your
364 .Pa /etc/mail/aliases
371 file are writable by user
375 .Bd -literal -offset indent
376 receiver-dude: "|ctm_rmail -p /ctm/tmp -d /ctm/deltas -l /ctm/log"
377 owner-receiver-dude: real_dude@wherever.you.like
380 The second line will catch failures and drop them into your regular mailbox,
381 or wherever else you like.
383 To apply all the deltas collected, and delete those applied, you could use:
384 .Bd -literal -offset indent
385 ctm_rmail -D -d /ctm/deltas -b /ctm/src-cur -l /ctm/apply.log
388 For maximum flexibility, consider this excerpt from a
391 .Bd -literal -offset indent
395 * ^Subject: ctm-mail cvs-cur
401 .Pa ~/bin/ctm_incoming :
402 .Bd -literal -offset indent
404 PATH="$HOME/bin:/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin"
407 cd $HOME/ctm && ctm_rmail -f -p pieces -d deltas -l log -b /ctm
410 which will deposit all
414 apply them to the tree in
416 and drop any failures into your regular mail box.
427 machine that this example was taken from.
429 On its own, CTM is an insecure protocol
430 - there is no authentication performed that the
431 changes applied to the source code were sent by a
432 trusted party, and so care should be taken if the
433 CTM deltas are obtained via an unauthenticated
434 medium such as regular email.
435 It is a relatively simple matter for an attacker
436 to forge a CTM delta to replace or precede the
437 legitimate one and insert malicious code into your
439 If the legitimate delta is somehow prevented from
440 arriving, this will go unnoticed until a later
441 delta attempts to touch the same file, at which
442 point the MD5 checksum will fail.
444 To remedy this insecurity, CTM delta pieces generated by
445 FreeBSD.org are cryptographically signed in a
446 format compatible with the GNU Privacy Guard
447 utility, available in /usr/ports/security/gpg, and
448 the Pretty Good Privacy v5 utility,
449 /usr/ports/security/pgp5.
450 The relevant public key can be obtained by
451 fingering ctm@FreeBSD.org.
453 CTM deltas which are thus signed cannot be
454 undetectably altered by an attacker.
455 Therefore it is recommended that you make use of
456 GPG or PGP5 to verify the signatures if you
457 receive your CTM deltas via email.
461 will report messages like:
462 .Bd -literal -offset indent
463 ctm_smail: src-cur.0250.gz 1/2 sent to src-guys
467 .Bd -literal -offset indent
468 ctm_smail: src-cur.0250.gz 1/2 queued for src-guys
473 utility will report messages like:
474 .Bd -literal -offset indent
475 ctm_dequeue: src-cur.0250.gz 1/2 sent
480 utility will report messages like:
481 .Bd -literal -offset indent
482 ctm_rmail: src-cur.0250.gz 1/2 stored
483 ctm_rmail: src-cur.0250.gz 2/2 stored
484 ctm_rmail: src-cur.0250.gz complete
487 If any of the input files do not contain a valid delta piece,
490 .Bd -literal -offset indent
491 ctm_rmail: message contains no delta
494 and return an exit status of 1.
495 You can use this to redirect wayward messages
496 back into your real mailbox if your mail filter goes wonky.
504 Error messages should be self explanatory.
510 .An Stephen McKay Aq mckay@FreeBSD.org