80ef2eaf89
This patch fixes the concurrency problem, and adds a possibly useful -f switch (which you can read about in the man page :-) ). It also removes the absolute path from the invocation of ctm. I'll write a note about how to use a script with sendmail and procmail or some such, and people can fix their PATH there. BTW, this patch changes ctm_rmail.1, ctm_rmail.c and error.c in the ctm_rmail directory. Stephen. Reviewed by: phk Submitted by: Stephen McKay <syssgm@devetir.qld.gov.au>
355 lines
10 KiB
Groff
355 lines
10 KiB
Groff
.\" 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 24, 1995
|
|
.Dt CTM_MAIL 1
|
|
.Os
|
|
.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 Df
|
|
.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
|
|
.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.
|
|
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,
|
|
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
|
|
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 one of the possible future enhancements to
|
|
.Xr ctm
|
|
is 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 .
|
|
Don't 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.
|
|
.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
|
|
.nh
|
|
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 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: 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 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
|
|
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 -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
|
|
.Xr ctm
|
|
disallows absolute pathnames and
|
|
.Dq \&\.\.
|
|
in files it manipulates, so the worst you
|
|
could lose are a few source tree files (recoverable from your deltas).
|
|
Since
|
|
.Xr ctm
|
|
requires that a
|
|
.Xr 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
|
|
.Xr 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
|
|
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
|
|
.sp \n(Ppu
|
|
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
|
|
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
|