.\" 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
.\" jpman %Id: ctm_rmail.1,v 1.3 1997/09/27 16:25:48 ryo2 Stab %
.Dt CTM_MAIL 1
.Os
.Sh 名称
.Nm ctm_smail, ctm_rmail
.Nd メールを介しての
.Nm ctm
デルタの送受信
.Sh 書式
.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 解説
.Nm ctm_smail ,
.Nm ctm_dequeue ,
.Nm ctm_rmail
は
.Xr ctm 1
コマンドと組み合わせて、
ソースツリーへの変更を電子メールで配布するために使われます。
.Nm ctm_smail
には圧縮した
.Xr ctm
のデルタとそれを送るメーリングリストを与えます。
するとデルタを送信できる大きさに切り分けて、メールメッセージとして
エンコードしたものをメーリングリストに送ります
(メールの負荷を分散させるためにキューに入れるように選択できます)。
各受信者は
.Nm ctm_rmail
を使い (手動または自動で) デルタのデコードと再組み立てを行い、
それをソースツリーに適用するために
.Xr ctm
を呼び出すようにも指定できます。
現在、
いくつかのソースツリーが、いくつかのサイトによって配布されています。
その中には
.Li freefall.FreeBSD.org
が配布している FreeBSD-current のソースと CVS のツリーもあります。
.Pp
.Nm ctm_smail
のコマンドラインの引数には以下があります:
.Bl -tag -width indent
.It Fl l Ar log
.Em stderr
に出力する代わりに、
(コマンドラインのエラー以外の) エラー診断と情報メッセージ
にタイムスタンプを付けた物がファイル
.Em log
に書き込まれます。
.It Fl m Ar maxmsgsize
.Nm ctm_smail
が送信できるメールメッセージの最大サイズを制限します。
メールヘッダとその他の細かい物をこの制限に入れていないため
およその値となります。
指定されないとデフォルトは、メールの限界と噂される 64k に対して
ヘッダのための 1535 バイトを残した 64000 バイトです。
.It Fl c Ar maxctmsize
送信されるデルタの最大サイズを制限します。この制限より大きいデルタは
謝罪メールをメーリングリストに送り出します。
これは大幅な変更でユーザのメールボックスを圧迫してしまうのを
避けるためです。これはエンコードする前のサイズなので注意して下さい。
エンコードされるとメールヘッダを付ける前でサイズは 4/3 倍になります。
指定されないと無制限になります。
.It Fl q Ar queue-dir
デルタのかけらをメールする代わりに、後で
.Nm ctm_dequeue
を使ってメールされるように指定されたディレクトリに格納します。
この機能によって、巨大なデルタを数時間または数日にも渡って分散させ、
ネットワークのバンド幅が狭かったりメールのスプール領域が小さい
受信者へのインパクトを押えることが可能です。
.El
.Pp
.Ar ctm-delta
は送信されるデルタで、
.Ar mail-alias
はデルタを送信するメーリングリストです。
メールメッセージは
.Xr sendmail 8
を使って送信されます。
.Pp
.Nm ctm_dequeue
のコマンドラインの引数には以下があります:
.Bl -tag -width indent
.It Fl l Ar log
.Em stderr
に出力する代わりに、
(コマンドラインのエラー以外の) エラー診断と情報メッセージ
にタイムスタンプを付けた物がファイル
.Em log
に書き込まれます。
.It Fl n Ar numchunks
1 回の
.Nm ctm_dequeue
の実行で送信するメールメッセージの数を制限します。
デフォルトでは、
.Nm ctm_dequeue
は 1 回の実行で 1 つのメールメッセージを送信します。
.El
.Pp
.Ar queuedir
は
.Nm ctm_smail
が格納したメールメッセージのあるディレクトリです。
.Ar numchunks
個までのメールメッセージが実行ごとに送信されます。
受信者のメーリングリストは、溜められたファイルに
すでにエンコードされています。
.Pp
.Nm ctm_smail
がキューにエントリを追加している最中や、複数の
.Nm ctm_smail
を並行に実行している最中でも
.Nm ctm_dequeue
を安全に実行できますが、配布される各ツリーごとに独立した
キューのディレクトリを使うべきです。
これはエントリがアルファベット順に処理されるので、デルタの
作成時刻ではなく、デルタ名に従って 1 つのツリーが他の物より
前に処理されて不公平になるからです。
.Pp
.Nm ctm_rmail
のコマンドラインの引数には以下があります:
.Bl -tag -width indent
.It Fl l Ar log
.Em stderr
に出力する代わりに、
(コマンドラインのエラー以外の) エラー診断と情報メッセージ
にタイムスタンプを付けた物がファイル
.Em log
に書き込まれます。
.It Fl p Ar piecedir
デルタのかけらをこのディレクトリに集めます。
それぞれのかけらは 1 つのメールメッセージに対応します。
かけらは完全なデルタが出来上がると削除されます。
もし このフラグが指定されないと、入力ファイルは読まれませんが、
.Fl b
フラグが指定されていれば完成しているデルタは
.Xr ctm
を使って適用されるかもしれません。
.It Fl d Ar deltadir
このディレクトリ内の完成したデルタを集めます。デルタは、すべてのかけらが
揃っている時に 1 つ以上のかけらから組み立てられます。
.It Fl b Ar basedir
完成しているデルタを このソースツリーに適用します。このフラグが
指定されていない場合、デルタは格納されますが適用はされません。
ユーザは手動、または
.Nm ctm_rmail
を
.Fl p
フラグ無しで使ってデルタを適用できます。
もしデルタが
.Ar basedir
の
.Li .ctm_status
ファイルとマッチしない場合 (もしくは
.Li .ctm_status
が存在しない場合) には、デルタは適用されません。
.It Fl D
.Xr ctm
による適用が成功した後でデルタを削除します。
.Xr ctm
はデルタのフルセットからファイルの小グループを回復する機能を
持つので、このフラグを避けて (そしてすべてのデルタを取って) おくのが
良いでしょう。
.It Fl f
fork して
.Xr ctm
でのデルタの適用をバックグラウンドで実行します。
これは
.Xr sendmail
から
.Nm ctm_rmail
を自動的に呼び出す場合に有効です。なぜなら
.Xr ctm
は終了までに、とても長い時間を要し、それによって他の人のメールを
遅らせる原因になり、理論的にはリモート側の
.Xr sendmail
のタイムアウトによるメールの不要な再送信や、
.Xr "MH"
の
.Xr slocal
のようなメールフィルタによる
.Nm ctm_rmail
の強制終了を引き起こす可能性があるからです。
膨大な数のバックグラウンドの
.Xr ctm
プロセスでマシンに負荷がかかる心配はありません。同時に 2 つ以上の
.Xr ctm
が起動されないようにロックが行われているからです。
.It Fl u
完成したデルタを適用する時に
.Fl u
フラグを
.Xr ctm
コマンドに渡します。これによって作成、変更されたファイルの
変更時刻が CTM デルタの作成時刻にセットされます。
.It Fl v
完成したデルタを適用する時に
.Fl v
フラグを
.Xr ctm
コマンドに渡します。これによってより多くの情報出力が得られます。
すべての
.Xr ctm
からの出力は
.Nm ctm_rmail
のログファイルに記録されます。
.El
.Pp
引数のファイル (もし無ければ
.Em 標準入力
) がデルタのかけらとしてスキャンされます。
1 つのファイルから複数のデルタのかけらを読む事ができるので、
メールドロップ全体を 1 回のコマンドでスキャンして処理できます。
.Pp
.Nm ctm_rmail
を並行に (異なる入力ファイルで) 複数回起動しても安全です。
.Xr sendmail
.nh
がメールを非同期に配送した時にこのようなことが起こり得ます。
これは処理を順序通りに保つためにロックが行われているからです。
.Sh ファイルフォーマット
以下は実際の (とても小さい) デルタのかけらの重要部分です:
.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
メッセージのサブジェクトは常に
.Dq ctm-mail
で始まりデルタの名前、いくつ目のかけらか、そして全部でいくつの
かけらがあるのかが続きます。データは
.Dq CTM_MAIL BEGIN
と
.Dq CTM_MAIL END
という行で囲まれており、サブジェクト行の情報の複製、加えて単純な
チェックサムが付きます。
.Pp
デルタが
.Ar maxctmsize
を超えると、代わりに以下のようなメッセージが送られます:
.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.

このデルタは ftpmail か、または大学の仲良しから得られます。
.Ed
.Pp
これでもうあなたのものです!
.Sh 使用例
.Em src-cur
の 32 番目のデルタを
.Em src-guys
として
.Xr sendmail
に登録されている素晴らしいコードハッカーのグループに、
メールのサイズをおよそ 60000 バイトに制限して送るためには
以下のように出来ます:
.Bd -literal -offset indent
ctm_smail -m 60000 /wherever/it/is/src-cur.0032.gz src-guys
.Ed
.Pp
メールボックスの各
.Nm ctm-mail
メッセージをデコードして、それらを完全なデルタに組み立て、そして
出来上がったデルタやそこらに転がっているデルタはどれも、
以下のように適用出来ます:
.Bd -literal -offset indent
ctm_rmail -p ~/pieces -d ~/deltas -b /usr/ctm-src-cur $MAIL
.Ed
.Pp
(
.Nm ctm_rmail
はメッセージを削除しないので注意して下さい。
削除には どんなメールリーダでも使用できます。)
.Pp
.Em receiver-dude
という名前の自動的にデコードとデルタの組み立てを行うけれども、
それらの適用は行わないようなメールエイリアスは、以下の行を
.Pa /etc/aliases
ファイルに入れる事で作成可能です (
.Pa /ctm/tmp
と
.Pa /ctm/deltas
ディレクトリ そして
.Pa /ctm/log
ファイルが
.Em daemon
ユーザか
.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
2 行目は、失敗した場合にそれを通常のメールボックスか、または
どこか好きな所へ転送するためにあります。
.Pp
集められた全デルタを適用して、適用したものを削除するには以下のように
します:
.Bd -literal -offset indent
ctm_rmail -D -d /ctm/deltas -b /ctm/src-cur -l /ctm/apply.log
.Ed
.Pp
柔軟性を最大限生かすためには、この
.Xr procmail
スクリプトからの引用の利用を考えてみて下さい:
.Bd -literal -offset indent
PATH=$HOME/bin:$PATH

:0 w
* ^Subject: ctm-mail cvs-cur
| ctm_incoming
.Ed
.Pp
以下のシェルスクリプト
.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
これは全部の
.Xr ctm
デルタを
.Pa ~/ctm/deltas
に置き、それらを
.Pa /ctm
内のツリーに適用し、失敗したものは、すべてあなたの通常の
メールボックスに落します。
.Pa ctm_incoming
での
.Ev PATH
の操作は、このサンプルを取って来た (FreeBSD でない) マシンで
.Nm ctm_rmail
から
.Xr ctm
の実行を可能にするためのものです。
.Sh セキュリティ
自動的にメールを取ってファイルツリーへのパッチプログラムに
渡している場合、あなたのシステムへの鍵をクラッカーに手渡していると
考えるかも知れません。幸い、損害を起こす窓はとても小さいのです。
.Nm ctm_rmail
は、
(デルタ名中の いかなる
.Dq /
文字も信用しないことによって)
与えられたディレクトリのみにしか書き込まないように注意しています。
そして最新の
.Xr ctm
では操作するファイルに絶対パス名と
.Dq \&\.\.
を許可していないので、最悪でも失われる可能性のあるのは
(デルタから復元できる) 二、三のソースツリーのファイルだけなのです。
.Xr ctm
はファイルにさわる前に
.Xr md5
によるチェックサムが合致する事を要求するので、ソースの受信者だけが
偽造したデルタを生成できる可能性を持ち、そして そういう人達が
そんなことを考えるはずもありません! :-)
.Pp
この可能性さえも暗号化された署名で取り除く事が可能です。
将来の強化の可能性は、
.Nm PGP
を使った安全なラッパの提供があります。
.\" This next request is for sections 1, 6, 7 & 8 only
.Sh 環境変数
デルタを適用するのならば
.Xr ctm 1
と
.Xr gunzip 1
が
.Ev PATH
に含まれていなければなりません。
.Sh 関連ファイル
.Bl -tag -width indent
.It Pa QUEUEDIR/*
メールメッセージとしてエンコードされて、メーリングリストに
送信されるのを待っているデルタのかけら。
.It Pa PIECEDIR/*
残りのかけらの到着を待っているデルタのかけら。
.It Pa DELTADIR/*
完成したデルタ。
.It Pa BASEDIR/.ctm_status
このソースツリーに次に適用されるべきデルタの名前と番号を含むファイル。
.\" This next request is for sections 1, 6, 7 & 8 only
.\"     (command return values (to shell) and fprintf/stderr type diagnostics)
.Sh 診断
.Nm ctm_smail ,
.Nm ctm_dequeue ,
.Nm ctm_rmail
は正常に終了するとステータスとして 0 を、何らかの障害が
あった場合は 1 を返します。
.Nm ctm_rmail
は、メールの配送プログラムから呼ばれる事を想定しています。そして
そのため入力されたメールメッセージが (送信者にではなく、
なるべく あなたの通常のメールドロップに) 返送されるべき状態に
なった時にのみ障害を通知するようになっています。
いいかえれば、完成したデルタを
.Xr ctm
で適用する際に発生した障害はメールを返送する程に重要なエラーでは
ないと判断されて、
.Nm ctm_rmail
は終了ステータスとして 0 を返すということです。
.Pp
通常の操作では、
.Nm ctm_smail
は以下のようなメッセージで報告します:
.Bd -literal -offset indent
ctm_smail: src-cur.0250.gz 1/2 sent to src-guys
.Ed
.Pp
または、キューに入れたなら、
.Bd -literal -offset indent
ctm_smail: src-cur.0250.gz 1/2 queued for src-guys
.Ed
.Pp
.Nm ctm_dequeue
は以下のようなメッセージで報告します:
.Bd -literal -offset indent
ctm_dequeue: src-cur.0250.gz 1/2 sent
.Ed
.Pp
.Nm ctm_rmail
は以下のようなメッセージで報告します:
.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
もし入力ファイルのいずれもが正しいデルタのかけらを含んでいないと、
.Nm ctm_rmail
は以下のように報告します:
.Bd -literal -offset indent
ctm_rmail: message contains no delta
.Ed
.sp \n(Ppu
そして終了ステータスとして 1 を返します。もしメールフィルタが
当てにならないのなら、これを使って気まぐれなメッセージを
リダイレクトして本当のメールボックスに入れる事ができます。
.Pp
これらのメッセージは
.Em stderr
かログファイルに出力されます。
.Xr ctm
からのメッセージも同様にここに現れます。
エラーメッセージは それ自身が説明的であるべきです。
.\" The next request is for sections 2 and 3 error and signal handling only.
.\" .Sh ERRORS
.Sh 関連項目
.Xr ctm 1 ,
.Xr ctm 5
.\" .Sh STANDARDS
.\" .Sh HISTORY
.Sh 作者
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: ctm_rmail.1,v 1.7.2.4 1998/07/18 11:09:52 jkh Exp %
.Sh 日本語訳
野首 寛高(h-nokubi@nmit.mt.nec.co.jp): FreeBSD 用に翻訳