CTM email tools.

Reviewed by:	phk
Submitted by:	Stephen McKay <syssgm@devetir.qld.gov.au>

1 files changed, 310 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 000000000000..a6dbc646ef9d
--- /dev/null
+++ b/usr.sbin/ctm/ctm_rmail/ctm_rmail.1
@@ -0,0 +1,310 @@
+.\" 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
+.\"
+.Dd January 15, 1995
+.Os
+.Dt CTM_MAIL 1
+.Sh NAME
+.Nm ctm_smail, ctm_rmail
+.Nd send and receive
+.Nm ctm
+deltas via mail
+.Sh SYNOPSIS
+.Nm ctm_smail
+.Op Fl l Ar log
+.Op Fl m Ar maxmsgsize
+.Op Fl c Ar maxctmsize
+.Ar ctm-delta
+.Ar mail-alias
+.Nm ctm_rmail
+.Op Fl D
+.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 conjuction with the
+.Xr ctm 1
+command,
+.Nm ctm_smail
+and
+.Nm ctm_rmail
+are used to distribute changes to a source tree via email.
+.Nm ctm_smail
+is given a compressed
+.Nm 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.
+Each recipient uses
+.Nm ctm_rmail
+(either manually or automatically) to decode and reassemble the delta, and
+optionally call
+.Xr ctm 1
+to apply it to the source tree.
+At the moment,
+only two source trees are distributed, and both by the same site.  These are
+the FreeBSD-current source and CVS trees, distributed by
+.Li ref.tfs.com .
+.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.
+.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_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 1
+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 1 .
+It is probably a good idea to avoid this flag (and keep all the deltas)
+as one of the possible future enhancements to
+.Xr ctm 1
+is the ability to recover small groups of files from a full set of deltas.
+.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.
+.Sh FILE FORMAT
+Following are the important parts of an actual (very small) delta piece:
+.Bd -literal
+From: src-cur-owner
+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 is 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: src-cur-owner
+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 ftpmail, or your good mate at the university.
+.Ed
+.Pp
+You are then on your own!
+.Sh EXAMPLES
+To send delta 32 of
+.Em src-cur
+to a group of wonderful code hackers known to
+.Xr sendmail 8
+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/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 /ctm/deltas -b /ctm/src-cur -l /ctm/apply.log
+.Ed
+.Sh SECURITY
+If you automatically take your mail and pass it to a file tree patcher, you
+might think you are handing the keys to your system to the hackers!  Happily,
+the window for mischief is quite small.
+.Nm ctm_rmail
+is careful to write only to the directories given to it (by not believing any
+.Dq /
+characters in the delta name), and the latest
+.Nm ctm
+disallows absolute pathnames in files it manipulates, so the worst you
+could lose are a few source tree files (recoverable from your deltas).
+Since
+.Nm ctm
+requires that a
+.Nm md5
+checksum match before it touches a file, only fellow
+source recipients would be able to generate a fake delta, and they're such
+nice folk that they wouldn't even think of it! :-)
+.Pp
+Even this possibility could be removed by using cryptographic signatures.
+A possible future enhancement would be to use
+.Nm PGP
+to provide a secure wrapper.
+.\" This next request is for sections 1, 6, 7 & 8 only
+.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 PIECEDIR/*
+Pieces of deltas waiting for the rest.
+.It Pa DELTADIR/*
+Completed deltas.
+.It Pa BASEDIR/.ctm_status
+File containing name and number of the next delta to be applied to this
+source tree.
+.\" This next request is for sections 1, 6, 7 & 8 only
+.\"     (command return values (to shell) and fprintf/stderr type diagnostics)
+.Sh DIAGNOSTICS
+.Nm ctm_smail
+and
+.Nm ctm_rmail
+return exit status 0 for success, and 1 for various failures.
+.Nm ctm_rmail
+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
+.Nm ctm
+is not considered an error important enough to bounce the mail, and
+.Nm ctm_rmail
+returns an exit status of 0.
+.Pp
+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
+.Nm ctm_rmail
+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
+These messages go to
+.Em stderr
+or to the log file.  Messages from
+.Nm ctm
+turn up here too.  Error messages should be self explanatory.
+.\" The next request is for sections 2 and 3 error and signal handling only.
+.\" .Sh ERRORS
+.Sh SEE ALSO
+.Xr ctm 1
+(coming soon)
+.\" .Sh STANDARDS
+.\" .Sh HISTORY
+.Sh AUTHOR
+Stephen McKay <syssgm@devetir.qld.gov.au>
+.\" .Sh BUGS