diff options
Diffstat (limited to 'usr.sbin/ctm/ctm_rmail/ctm_rmail.1')
| -rw-r--r-- | usr.sbin/ctm/ctm_rmail/ctm_rmail.1 | 510 |
1 files changed, 510 insertions, 0 deletions
diff --git a/usr.sbin/ctm/ctm_rmail/ctm_rmail.1 b/usr.sbin/ctm/ctm_rmail/ctm_rmail.1 new file mode 100644 index 0000000..232f646 --- /dev/null +++ b/usr.sbin/ctm/ctm_rmail/ctm_rmail.1 @@ -0,0 +1,510 @@ +.\" NOTICE: This is free documentation. I hope you get some use from these +.\" words. In return you should think about all the nice people who sweat +.\" blood to document their free software. Maybe you should write some +.\" documentation and give it away. Maybe with a free program attached! +.\" +.\" Author: Stephen McKay +.\" +.\" $FreeBSD$ +.\" +.Dd January 24, 1995 +.Dt CTM_MAIL 1 +.Os +.Sh NAME +.Nm ctm_smail , +.Nm ctm_dequeue , +.Nm ctm_rmail +.Nd send and receive +.Xr ctm 1 +deltas via mail +.Sh SYNOPSIS +.Nm ctm_smail +.Op Fl l Ar log +.Op Fl m Ar maxmsgsize +.Op Fl c Ar maxctmsize +.Op Fl q Ar queue-dir +.Ar ctm-delta +.Ar mail-alias +.Nm ctm_dequeue +.Op Fl l Ar log +.Op Fl n Ar numchunks +.Ar queue-dir +.Nm ctm_rmail +.Op Fl Dfuv +.Op Fl l Ar log +.Op Fl p Ar piecedir +.Op Fl d Ar deltadir +.Op Fl b Ar basedir +.Op Ar +.Sh DESCRIPTION +In conjunction with the +.Xr ctm 1 +command, +.Nm ctm_smail , +.Nm ctm_dequeue +and +.Nm ctm_rmail +are used to distribute changes to a source tree via email. +The +.Nm ctm_smail +utility is given a compressed +.Xr ctm +delta, and a mailing list to send it to. +It splits the delta into manageable +pieces, encodes them as mail messages and sends them to the mailing list +(optionally queued to spread the mail load). +Each recipient uses +.Nm ctm_rmail +(either manually or automatically) to decode and reassemble the delta, and +optionally call +.Xr ctm +to apply it to the source tree. +At the moment, +several source trees are distributed, and by several sites. +These include +the +.Fx Ns -current +source and CVS trees, distributed by +.Li freefall.FreeBSD.org . +.Pp +Command line arguments for +.Nm ctm_smail : +.Bl -tag -width indent +.It Fl l Ar log +Instead of appearing on +.Em stderr , +error diagnostics and informational messages (other than command line errors) +are time stamped and written to the file +.Em log . +.It Fl m Ar maxmsgsize +Limit the maximum size mail message that +.Nm ctm_smail +is allowed to send. +It is approximate since mail headers and other niceties +are not counted in this limit. +If not specified, it will default to 64000 +bytes, leaving room for 1535 bytes of headers before the rumoured 64k mail +limit. +.It Fl c Ar maxctmsize +Limit the maximum size delta that will be sent. +Deltas bigger that this +limit will cause an apology mail message to be sent to the mailing list. +This is to prevent massive changes overwhelming users' mail boxes. +Note that +this is the size before encoding. +Encoding causes a 4/3 size increase before +mail headers are added. +If not specified, there is no limit. +.It Fl q Ar queue-dir +Instead of mailing the delta pieces now, store them in the given directory +to be mailed later using +.Nm ctm_dequeue . +This feature allows the mailing of large deltas to be spread out over +hours or even days to limit the impact on recipients with limited network +bandwidth or small mail spool areas. +.El +.Pp +.Ar ctm-delta +is the delta to be sent, and +.Ar mail-alias +is the mailing list to send the delta to. +The mail messages are sent using +.Xr sendmail 8 . +.Pp +Command line arguments for +.Nm ctm_dequeue : +.Bl -tag -width indent +.It Fl l Ar log +Instead of appearing on +.Em stderr , +error diagnostics and informational messages (other than command line errors) +are time stamped and written to the file +.Em log . +.It Fl n Ar numchunks +Limit the number of mail messages that +.Nm ctm_dequeue +will send per run. +By default, +.Nm ctm_dequeue +will send one mail message per run. +.El +.Pp +.Ar queuedir +is the directory containing the mail messages stored by +.Nm ctm_smail . +Up to +.Ar numchunks +mail messages will be sent in each run. +The recipient mailing list is already +encoded in the queued files. +.Pp +It is safe to run +.Nm ctm_dequeue +while +.Nm ctm_smail +is adding entries to the queue, or even to run +.Nm ctm_smail +multiple times concurrently, but a separate queue directory should be used +for each tree being distributed. +This is because entries are served in +alphabetical order, and one tree will be unfairly serviced before any others, +based on the delta names, not delta creation times. +.Pp +Command line arguments for +.Nm ctm_rmail : +.Bl -tag -width indent +.It Fl l Ar log +Instead of appearing on +.Em stderr , +error diagnostics and informational messages (other than command line errors) +are time stamped and written to the file +.Em log . +.It Fl p Ar piecedir +Collect pieces of deltas in this directory. +Each piece corresponds to a +single mail message. +Pieces are removed when complete deltas are built. +If this flag is not given, no input files will be read, but completed +deltas may still be applied with +.Xr ctm +if the +.Fl b +flag is given. +.It Fl d Ar deltadir +Collect completed deltas in this directory. +Deltas are built from one or +more pieces when all pieces are present. +.It Fl b Ar basedir +Apply any completed deltas to this source tree. +If this flag is not given, +deltas will be stored, but not applied. +The user may then apply the deltas +manually, or by using +.Nm ctm_rmail +without the +.Fl p +flag. +Deltas will not be applied if they do not match the +.Li .ctm_status +file in +.Ar basedir +(or if +.Li .ctm_status +does not exist). +.It Fl D +Delete deltas after successful application by +.Xr ctm . +It is probably a good idea to avoid this flag (and keep all the deltas) as +.Xr ctm +has the ability to recover small groups of files from a full set of deltas. +.It Fl f +Fork and execute in the background while applying deltas with +.Xr ctm . +This is useful when automatically invoking +.Nm ctm_rmail +from +.Xr sendmail +because +.Xr ctm +can take a very long time to complete, causing other people's mail to +be delayed, and can in theory cause spurious +mail retransmission due to the remote +.Xr sendmail +timing out, or even termination of +.Nm ctm_rmail +by mail filters such as +.Xr "MH's" +.Xr slocal . +Do not worry about zillions of background +.Xr ctm +processes loading your machine, since locking is used to prevent more than one +.Xr ctm +invocation at a time. +.It Fl u +Pass the +.Fl u +flag to the +.Xr ctm +command when applying the complete deltas, causing it to set the modification +time of created and modified files to the CTM delta creation time. +.It Fl v +Pass the +.Fl v +flag to the +.Xr ctm +command when applying the complete deltas, causing a more informative +output. +All +.Xr ctm +output appears in the +.Nm ctm_rmail +log file. +.El +.Pp +The file arguments (or +.Em stdin , +if there are none) are scanned for delta pieces. +Multiple delta pieces +can be read from a single file, so an entire maildrop can be scanned +and processed with a single command. +.Pp +It is safe to invoke +.Nm ctm_rmail +multiple times concurrently (with different input files), +as might happen when +.Xr sendmail +is delivering mail asynchronously. +This is because locking is used to +keep things orderly. +.Sh FILE FORMAT +Following are the important parts of an actual (very small) delta piece: +.Bd -literal +From: owner-src-cur +To: src-cur +Subject: ctm-mail src-cur.0003.gz 1/4 + +CTM_MAIL BEGIN src-cur.0003.gz 1 4 +H4sIAAAAAAACA3VU72/bNhD9bP0VByQoEiyRSZEUSQP9kKTeYCR2gDTdsGFAwB/HRogtG5K8NCj6 +v4+UZSdtUQh6Rz0eee/xaF/dzx8up3/MFlDkBNrGnbttAwyo1pxoRgoiBNX/QJ5d3c9/X8DcPGGo +lggkPiXngE4W1gUjKPJCYyk5MZRbIqmNW/ASglIFcdwIzTUxaAqhnCPcBqloKEkJVNDMF0Azk+Bo +dDzzk0Ods/+A5gXv9YyJHjMCtJwQNeESNma7hOmXDRxn +CTM_MAIL END 61065 +.Ed +.Pp +The subject of the message always begins with +.Dq ctm-mail +followed by the name of the delta, which piece this is, and how many total +pieces there are. +The data are bracketed by +.Dq CTM_MAIL BEGIN +and +.Dq CTM_MAIL END +lines, duplicating the information in the subject line, plus a simple checksum. +.Pp +If the delta exceeds +.Ar maxctmsize , +then a message like this will be received instead: +.Bd -literal +From: owner-src-cur +To: src-cur +Subject: ctm-notice src-cur.0999.gz + +src-cur.0999.gz is 792843 bytes. The limit is 300000 bytes. + +You can retrieve this delta via ftp. +.Ed +.Pp +You are then on your own! +.Sh ENVIRONMENT +If deltas are to be applied then +.Xr ctm 1 +and +.Xr gunzip 1 +must be in your +.Ev PATH . +.Sh FILES +.Bl -tag -width indent +.It Pa QUEUEDIR/* +Pieces of deltas encoded as mail messages waiting to be sent to the +mailing list. +.It Pa PIECEDIR/* +Pieces of deltas waiting for the rest to arrive. +.It Pa DELTADIR/* +Completed deltas. +.It Pa BASEDIR/.ctm_status +File containing the name and number of the next delta to be applied to this +source tree. +.El +.Sh EXIT STATUS +The +.Nm ctm_smail , +.Nm ctm_dequeue +and +.Nm ctm_rmail +utilities return exit status 0 for success, and 1 for various failures. +The +.Nm ctm_rmail +utility is expected to be called from a mail transfer program, and thus signals +failure only when the input mail message should be bounced (preferably into +your regular maildrop, not back to the sender). +In short, failure to +apply a completed delta with +.Xr ctm +is not considered an error important enough to bounce the mail, and +.Nm ctm_rmail +returns an exit status of 0. +.Sh EXAMPLES +To send delta 32 of +.Em src-cur +to a group of wonderful code hackers known to +.Xr sendmail +as +.Em src-guys , +limiting the mail size to roughly 60000 bytes, you could use: +.Bd -literal -offset indent +ctm_smail -m 60000 /wherever/it/is/src-cur.0032.gz src-guys +.Ed +.Pp +To decode every +.Nm ctm-mail +message in your mailbox, assemble them into complete deltas, then apply +any deltas built or lying around, you could use: +.Bd -literal -offset indent +ctm_rmail -p ~/pieces -d ~/deltas -b /usr/ctm-src-cur $MAIL +.Ed +.Pp +(Note that no messages are deleted by +.Nm ctm_rmail . +Any mail reader could be used for that purpose.) +.Pp +To create a mail alias called +.Em receiver-dude +that will automatically decode and assemble deltas, but not apply them, +you could put the following lines in your +.Pa /etc/mail/aliases +file (assuming the +.Pa /ctm/tmp +and +.Pa /ctm/deltas +directories and +.Pa /ctm/log +file are writable by user +.Em daemon +or group +.Em wheel ) : +.Bd -literal -offset indent +receiver-dude: "|ctm_rmail -p /ctm/tmp -d /ctm/deltas -l /ctm/log" +owner-receiver-dude: real_dude@wherever.you.like +.Ed +.Pp +The second line will catch failures and drop them into your regular mailbox, +or wherever else you like. +.Pp +To apply all the deltas collected, and delete those applied, you could use: +.Bd -literal -offset indent +ctm_rmail -D -d /ctm/deltas -b /ctm/src-cur -l /ctm/apply.log +.Ed +.Pp +For maximum flexibility, consider this excerpt from a +.Xr procmail +script: +.Bd -literal -offset indent +PATH=$HOME/bin:$PATH + +:0 w +* ^Subject: ctm-mail cvs-cur +| ctm_incoming +.Ed +.Pp +together with the +shell script +.Pa ~/bin/ctm_incoming : +.Bd -literal -offset indent +#! /bin/sh +PATH="$HOME/bin:/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin" +export PATH + +cd $HOME/ctm && ctm_rmail -f -p pieces -d deltas -l log -b /ctm +.Ed +.Pp +which will deposit all +.Xr ctm +deltas in +.Pa ~/ctm/deltas , +apply them to the tree in +.Pa /ctm , +and drop any failures into your regular mail box. +Note the +.Ev PATH +manipulation in +.Pa ctm_incoming +which allows +.Nm ctm_rmail +to execute +.Xr ctm 1 +on the +.Pq non- Ns Fx +machine that this example was taken from. +.Sh SECURITY +On its own, CTM is an insecure protocol +- there is no authentication performed that the +changes applied to the source code were sent by a +trusted party, and so care should be taken if the +CTM deltas are obtained via an unauthenticated +medium such as regular email. +It is a relatively simple matter for an attacker +to forge a CTM delta to replace or precede the +legitimate one and insert malicious code into your +source tree. +If the legitimate delta is somehow prevented from +arriving, this will go unnoticed until a later +delta attempts to touch the same file, at which +point the MD5 checksum will fail. +.Pp +To remedy this insecurity, CTM delta pieces generated by +FreeBSD.org are cryptographically signed in a +format compatible with the GNU Privacy Guard +utility, available in /usr/ports/security/gpg, and +the Pretty Good Privacy v5 utility, +/usr/ports/security/pgp5. +The relevant public key can be obtained by +fingering ctm@FreeBSD.org. +.Pp +CTM deltas which are thus signed cannot be +undetectably altered by an attacker. +Therefore it is recommended that you make use of +GPG or PGP5 to verify the signatures if you +receive your CTM deltas via email. +.Sh DIAGNOSTICS +In normal operation, +.Nm ctm_smail +will report messages like: +.Bd -literal -offset indent +ctm_smail: src-cur.0250.gz 1/2 sent to src-guys +.Ed +.Pp +or, if queueing, +.Bd -literal -offset indent +ctm_smail: src-cur.0250.gz 1/2 queued for src-guys +.Ed +.Pp +The +.Nm ctm_dequeue +utility will report messages like: +.Bd -literal -offset indent +ctm_dequeue: src-cur.0250.gz 1/2 sent +.Ed +.Pp +The +.Nm ctm_rmail +utility will report messages like: +.Bd -literal -offset indent +ctm_rmail: src-cur.0250.gz 1/2 stored +ctm_rmail: src-cur.0250.gz 2/2 stored +ctm_rmail: src-cur.0250.gz complete +.Ed +.Pp +If any of the input files do not contain a valid delta piece, +.Nm ctm_rmail +will report: +.Bd -literal -offset indent +ctm_rmail: message contains no delta +.Ed +.Pp +and return an exit status of 1. +You can use this to redirect wayward messages +back into your real mailbox if your mail filter goes wonky. +.Pp +These messages go to +.Em stderr +or to the log file. +Messages from +.Xr ctm 1 +turn up here too. +Error messages should be self explanatory. +.Sh SEE ALSO +.Xr ctm 1 , +.Xr ctm 5 +.\" .Sh HISTORY +.Sh AUTHORS +.An Stephen McKay Aq Mt mckay@FreeBSD.org |
