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, 0 insertions, 510 deletions
diff --git a/usr.sbin/ctm/ctm_rmail/ctm_rmail.1 b/usr.sbin/ctm/ctm_rmail/ctm_rmail.1 deleted file mode 100644 index 232f646529f8..000000000000 --- a/usr.sbin/ctm/ctm_rmail/ctm_rmail.1 +++ /dev/null @@ -1,510 +0,0 @@ -.\" 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 |