.\" 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
.\"
.\" %FreeBSD: src/usr.sbin/ctm/ctm_rmail/ctm_rmail.1,v 1.29 2004/07/02 23:12:41 ru Exp %
.\" $FreeBSD$
.\"
.Dd January 24, 1995
.Dt CTM_MAIL 1
.Os
.Sh 名称
.Nm ctm_smail ,
.Nm ctm_dequeue ,
.Nm ctm_rmail
.Nd メールを介しての
.Xr ctm 1
デルタの送受信
.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 1
のデルタとそれを送るメーリングリストを与えます。
するとデルタを送信できる大きさに切り分けて、メールメッセージとして
エンコードしたものをメーリングリストに送ります
(メールの負荷を分散させるためにキューに入れるように選択できます)。
各受信者は
.Nm ctm_rmail
を使い (手動または自動で) デルタのデコードと再組み立てを行い、
それをソースツリーに適用するために
.Xr ctm
を呼び出すようにも指定できます。
現在、
いくつかのソースツリーが、いくつかのサイトによって配布されています。
その中には
.Li freefall.FreeBSD.org
が配布している
.Fx Ns -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
がメールを非同期に配送した時にこのようなことが起こり得ます。
これは処理を順序通りに保つためにロックが行われているからです。
.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.

このデルタは ftp から得られます。
.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/mail/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
の操作は、このサンプルを取って来た (
.Fx
でない) マシンで
.Nm ctm_rmail
から
.Xr ctm 1
の実行を可能にするためのものです。
.Sh セキュリティ
CTM 自身、
安全ではないプロトコルです
- ソースコードへ加えられた修正が信頼できるところから送られたことを
認証しませんので、
通常の電子メール等の信頼できない媒体から
CTM デルタを得た場合には注意が必要です。
CTM デルタを偽造して、正当なものを交換または上書きし、
悪意あるコードをあなたのソースツリーに挿入することは、
攻撃者にとって比較的簡単です。
正当なデルタの到着がなんらかの方法で妨げられた場合、
これを感知できるのは、後のデルタが同じファイルを触ろうとする時点です。
この時点で、MD チェックサムが失敗します。
.Pp
これを回避して安全なものにするために、
FreeBSD.org が作った CTM 部品には、
GNU Privacy Guard ユーティリティ互換なフォーマットで暗号的に署名しています。
このユーティリティは /usr/ports/security/gpg および
Pretty Good Privacy v5 ユーティリティ
/usr/ports/security/pgp5 から入手できます。
適切な公開鍵は ctm@FreeBSD.org を finger することで得られます。
.Pp
このように署名された CTM デルタは、
検知されることなく攻撃者が改変することはできません。
それゆえ、CTM デルタを電子メールで受信する場合には、
GPG または PGP5 を使用して署名を確認することを勧めます。
.\" 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
このソースツリーに次に適用されるべきデルタの名前と番号を含むファイル。
.El
.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
.Pp
そして終了ステータスとして 1 を返します。もしメールフィルタが
当てにならないのなら、これを使って気まぐれなメッセージを
リダイレクトして本当のメールボックスに入れる事ができます。
.Pp
これらのメッセージは
.Em stderr
かログファイルに出力されます。
.Xr ctm 1
からのメッセージも同様にここに現れます。
エラーメッセージは それ自身が説明的であるべきです。
.Sh 関連項目
.Xr ctm 1 ,
.Xr ctm 5
.\" .Sh HISTORY
.Sh 作者
Stephen McKay <mckay@FreeBSD.org>
.Sh 日本語訳
野首 寛高 (h-nokubi@nmit.mt.nec.co.jp): FreeBSD 用に翻訳