Documented ctm_dequeue and the new feature of ctm_smail that goes with it.
Expanded the ctm_rmail example usage section.
This commit is contained in:
parent
1fbf1f7140
commit
147962b004
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=20509
@ -1,6 +1,6 @@
|
||||
PROG= ctm_rmail
|
||||
SRCS= ctm_rmail.c error.c
|
||||
CFLAGS+= -Wall
|
||||
MLINKS+= ctm_rmail.1 ctm_smail.1
|
||||
MLINKS+= ctm_rmail.1 ctm_smail.1 ctm_dequeue.1
|
||||
|
||||
.include <bsd.prog.mk>
|
||||
|
@ -18,8 +18,13 @@ deltas via mail
|
||||
.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
|
||||
@ -31,7 +36,8 @@ deltas via mail
|
||||
In conjuction with the
|
||||
.Xr ctm 1
|
||||
command,
|
||||
.Nm ctm_smail
|
||||
.Nm ctm_smail ,
|
||||
.Nm ctm_dequeue
|
||||
and
|
||||
.Nm ctm_rmail
|
||||
are used to distribute changes to a source tree via email.
|
||||
@ -39,7 +45,8 @@ are used to distribute changes to a source tree via email.
|
||||
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.
|
||||
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
|
||||
@ -73,6 +80,13 @@ 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
|
||||
@ -83,6 +97,42 @@ 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
|
||||
@ -121,10 +171,9 @@ 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
|
||||
It is probably a good idea to avoid this flag (and keep all the deltas) as
|
||||
.Xr ctm
|
||||
is the ability to recover small groups of files from a full set of deltas.
|
||||
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 .
|
||||
@ -161,7 +210,11 @@ Pass the
|
||||
flag to the
|
||||
.Xr ctm
|
||||
command when applying the complete deltas, causing a more informative
|
||||
output. Note that you need to make your own arrangements to capture it.
|
||||
output. All
|
||||
.Xr ctm
|
||||
output appears in the
|
||||
.Nm ctm_rmail
|
||||
log file.
|
||||
.El
|
||||
.Pp
|
||||
The file arguments (or
|
||||
@ -196,7 +249,7 @@ CTM_MAIL END 61065
|
||||
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
|
||||
pieces there are. The data are bracketed by
|
||||
.Dq CTM_MAIL BEGIN
|
||||
and
|
||||
.Dq CTM_MAIL END
|
||||
@ -267,6 +320,45 @@ 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
|
||||
on the (non-FreeBSD) machine that this example was taken from.
|
||||
.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,
|
||||
@ -302,17 +394,21 @@ 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.
|
||||
Pieces of deltas waiting for the rest to arrive.
|
||||
.It Pa DELTADIR/*
|
||||
Completed deltas.
|
||||
.It Pa BASEDIR/.ctm_status
|
||||
File containing name and number of the next delta to be applied to this
|
||||
File containing the 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
|
||||
.Nm ctm_smail ,
|
||||
.Nm ctm_dequeue
|
||||
and
|
||||
.Nm ctm_rmail
|
||||
return exit status 0 for success, and 1 for various failures.
|
||||
@ -333,6 +429,17 @@ will report messages like:
|
||||
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
|
||||
.Nm ctm_dequeue
|
||||
will report messages like:
|
||||
.Bd -literal -offset indent
|
||||
ctm_dequeue: src-cur.0250.gz 1/2 sent
|
||||
.Ed
|
||||
.Pp
|
||||
.Nm ctm_rmail
|
||||
will report messages like:
|
||||
.Bd -literal -offset indent
|
||||
@ -364,5 +471,9 @@ turn up here too. Error messages should be self explanatory.
|
||||
.\" .Sh STANDARDS
|
||||
.\" .Sh HISTORY
|
||||
.Sh AUTHOR
|
||||
Stephen McKay <syssgm@devetir.qld.gov.au>
|
||||
Stephen McKay <mckay@FreeBSD.org>
|
||||
.\" .Sh BUGS
|
||||
.\" Gosh! No bugs here!
|
||||
.\" This message brought to you by the Coalition for More Humour in Man Pages.
|
||||
.\"
|
||||
.\" $Id$
|
||||
|
Loading…
Reference in New Issue
Block a user