Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
CTM_MAIL(1)		  BSD General Commands Manual		   CTM_MAIL(1)

     ctm_smail,	ctm_dequeue, ctm_rmail -- send and receive ctm(1) deltas via

     ctm_smail [-l log]	[-m maxmsgsize]	[-c maxctmsize]	[-q queue-dir]
	       ctm-delta mail-alias
     ctm_dequeue [-l log] [-n numchunks] queue-dir
     ctm_rmail [-Dfuv] [-l log]	[-p piecedir] [-d deltadir] [-b	basedir]
	       [file ...]

     In	conjunction with the ctm(1) command, ctm_smail,	ctm_dequeue and
     ctm_rmail are used	to distribute changes to a source tree via email.  The
     ctm_smail utility is given	a compressed 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 ctm_rmail (either manually or
     automatically) to decode and reassemble the delta,	and optionally call
     ctm to apply it to	the source tree.  At the moment, several source	trees
     are distributed, and by several sites.  These include the FreeBSD-current
     source and	CVS trees, distributed by

     Command line arguments for	ctm_smail:

     -l	log  Instead of	appearing on stderr, error diagnostics and informa-
	     tional messages (other than command line errors) are time stamped
	     and written to the	file log.

     -m	maxmsgsize
	     Limit the maximum size mail message that 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.

     -c	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 overwhelm-
	     ing users'	mail boxes.  Note that this is the size	before encod-
	     ing.  Encoding causes a 4/3 size increase before mail headers are
	     added.  If	not specified, there is	no limit.

     -q	queue-dir
	     Instead of	mailing	the delta pieces now, store them in the	given
	     directory to be mailed later using	ctm_dequeue.  This feature al-
	     lows 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.

     ctm-delta is the delta to be sent,	and mail-alias is the mailing list to
     send the delta to.	 The mail messages are sent using sendmail(8).

     Command line arguments for	ctm_dequeue:

     -l	log  Instead of	appearing on stderr, error diagnostics and informa-
	     tional messages (other than command line errors) are time stamped
	     and written to the	file log.

     -n	numchunks
	     Limit the number of mail messages that ctm_dequeue	will send per
	     run.  By default, ctm_dequeue will	send one mail message per run.

     queuedir is the directory containing the mail messages stored by
     ctm_smail.	 Up to numchunks mail messages will be sent in each run.  The
     recipient mailing list is already encoded in the queued files.

     It	is safe	to run ctm_dequeue while ctm_smail is adding entries to	the
     queue, or even to run ctm_smail multiple times concurrently, but a	sepa-
     rate 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.

     Command line arguments for	ctm_rmail:

     -l	log  Instead of	appearing on stderr, error diagnostics and informa-
	     tional messages (other than command line errors) are time stamped
	     and written to the	file log.

     -p	piecedir
	     Collect pieces of deltas in this directory.  Each piece corre-
	     sponds to a single	mail message.  Pieces are removed when com-
	     plete deltas are built.  If this flag is not given, no input
	     files will	be read, but completed deltas may still	be applied
	     with ctm if the -b	flag is	given.

     -d	deltadir
	     Collect completed deltas in this directory.  Deltas are built
	     from one or more pieces when all pieces are present.

     -b	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 ctm_rmail without the
	     -p	flag.  Deltas will not be applied if they do not match the
	     .ctm_status file in basedir (or if	.ctm_status does not exist).

     -D	     Delete deltas after successful application	by ctm.	 It is proba-
	     bly a good	idea to	avoid this flag	(and keep all the deltas) as
	     ctm has the ability to recover small groups of files from a full
	     set of deltas.

     -f	     Fork and execute in the background	while applying deltas with
	     ctm.  This	is useful when automatically invoking ctm_rmail	from
	     sendmail because ctm can take a very long time to complete, caus-
	     ing other people's	mail to	be delayed, and	can in theory cause
	     spurious mail retransmission due to the remote sendmail timing
	     out, or even termination of ctm_rmail by mail filters such	as
	     MH's slocal.  Do not worry	about zillions of background ctm pro-
	     cesses loading your machine, since	locking	is used	to prevent
	     more than one ctm invocation at a time.

     -u	     Pass the -u flag to the 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.

     -v	     Pass the -v flag to the ctm command when applying the complete
	     deltas, causing a more informative	output.	 All ctm output	ap-
	     pears in the ctm_rmail log	file.

     The file arguments	(or stdin, if there are	none) are scanned for delta
     pieces.  Multiple delta pieces can	be read	from a single file, so an en-
     tire maildrop can be scanned and processed	with a single command.

     It	is safe	to invoke ctm_rmail multiple times concurrently	(with differ-
     ent input files), as might	happen when sendmail is	delivering mail	asyn-
     chronously.  This is because locking is used to keep things orderly.

     Following are the important parts of an actual (very small) delta piece:

     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
     CTM_MAIL END 61065

     The subject of the	message	always begins with "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 "CTM_MAIL BEGIN" and "CTM_MAIL END"
     lines, duplicating	the information	in the subject line, plus a simple

     If	the delta exceeds maxctmsize, then a message like this will be re-
     ceived instead:

     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.

     You are then on your own!

     If	deltas are to be applied then ctm(1) and gunzip(1) must	be in your

	     Pieces of deltas encoded as mail messages waiting to be sent to
	     the mailing list.

	     Pieces of deltas waiting for the rest to arrive.

	     Completed deltas.

	     File containing the name and number of the	next delta to be ap-
	     plied to this source tree.

     The ctm_smail, ctm_dequeue	and ctm_rmail utilities	return exit status 0
     for success, and 1	for various failures.  The ctm_rmail utility is	ex-
     pected to be called from a	mail transfer program, and thus	signals	fail-
     ure only when the input mail message should be bounced (preferably	into
     your regular maildrop, not	back to	the sender).  In short,	failure	to ap-
     ply a completed delta with	ctm is not considered an error important
     enough to bounce the mail,	and ctm_rmail returns an exit status of	0.

     To	send delta 32 of src-cur to a group of wonderful code hackers known to
     sendmail as src-guys, limiting the	mail size to roughly 60000 bytes, you
     could use:

	   ctm_smail -m	60000 /wherever/it/is/src-cur.0032.gz src-guys

     To	decode every ctm-mail message in your mailbox, assemble	them into com-
     plete deltas, then	apply any deltas built or lying	around,	you could use:

	   ctm_rmail -p	~/pieces -d ~/deltas -b	/usr/ctm-src-cur $MAIL

     (Note that	no messages are	deleted	by ctm_rmail.  Any mail	reader could
     be	used for that purpose.)

     To	create a mail alias called receiver-dude that will automatically de-
     code and assemble deltas, but not apply them, you could put the following
     lines in your /etc/mail/aliases file (assuming the	/ctm/tmp and
     /ctm/deltas directories and /ctm/log file are writable by user daemon or
     group wheel):

	   receiver-dude: "|ctm_rmail -p /ctm/tmp -d /ctm/deltas -l /ctm/log"

     The second	line will catch	failures and drop them into your regular mail-
     box, or wherever else you like.

     To	apply all the deltas collected,	and delete those applied, you could

	   ctm_rmail -D	-d /ctm/deltas -b /ctm/src-cur -l /ctm/apply.log

     For maximum flexibility, consider this excerpt from a procmail script:


	   :0 w
	   * ^Subject: ctm-mail	cvs-cur
	   | ctm_incoming

     together with the shell script ~/bin/ctm_incoming:

	   #! /bin/sh
	   export PATH

	   cd $HOME/ctm	&& ctm_rmail -f	-p pieces -d deltas -l log -b /ctm

     which will	deposit	all ctm	deltas in ~/ctm/deltas,	apply them to the tree
     in	/ctm, and drop any failures into your regular mail box.	 Note the PATH
     manipulation in ctm_incoming which	allows ctm_rmail to execute ctm(1) on
     the (non-FreeBSD) machine that this example was taken from.

     On	its own, CTM is	an insecure protocol - there is	no authentication per-
     formed 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 le-
     gitimate one and insert malicious code into your source tree.  If the le-
     gitimate 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.

     To	remedy this insecurity,	CTM delta pieces generated by 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 deltas	which are thus signed cannot be	undetectably altered by	an at-
     tacker.  Therefore	it is recommended that you make	use of GPG or PGP5 to
     verify the	signatures if you receive your CTM deltas via email.

     In	normal operation, ctm_smail will report	messages like:

	   ctm_smail: src-cur.0250.gz 1/2 sent to src-guys

     or, if queueing,

	   ctm_smail: src-cur.0250.gz 1/2 queued for src-guys

     The ctm_dequeue utility will report messages like:

	   ctm_dequeue:	src-cur.0250.gz	1/2 sent

     The ctm_rmail utility will	report messages	like:

	   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

     If	any of the input files do not contain a	valid delta piece, ctm_rmail
     will report:

	   ctm_rmail: message contains no delta

     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.

     These messages go to stderr or to the log file.  Messages from ctm(1)
     turn up here too.	Error messages should be self explanatory.

     ctm(1), ctm(5)

     Stephen McKay <>

BSD			       January 24, 1995				   BSD


Want to link to this manual page? Use this URL:

home | help