This is $Revision: 1.2 $ dated $Date: 1996/09/13 16:46:50 $.
README.perl_hook の日本語訳は kondou@uxd.fc.nec.co.jp によって行われました。

innd と nnrpd では他のサイトから受け取った記事や、ポストされた記事の perl
によるある程度のフィルタリングをサポートしています。このコードは、
Christophe Wolfhugel <wolf@pasteur.fr> が非常に苦労した作業の結果をベースと
しています。彼の作業のベースはすでに存在していた TCL によるフィルタのコード
からのものでした。その後、私がコードに手を入れていて、どのような問題もおそ
らくは私に原因があるため、バグ報告は Christophe では無く、私(<inn@isc.org>)
に送ってください。

perl でのフィルタリングサポートにより可能となることの説明は以下でより詳細に
説明しますが、基本的に innd が他のサイトから記事を受け取ったり、nnrpd が
ニュースリーダからポストされた記事を受け取ったりする毎に起動される perl の
サブルーチンを使用することができるということです。このサブルーチンにより、
nnrpd や innd に記事を受け入れたり、拒否させることができます。これは、spam
となっている記事を排除させるために有用です。

perl でのフィルタリングサポートを行うためには、perl のバージョン 5.003 が必
要です。バージョン 5.001 ではまったく動作しません。5.002 では動作するかもし
れませんが、試していません。最新のバージョンの perl を
http://www.perl.com/CPAN から入手してください。

config.dist には、perl についてのセクション(#17)があります。perl でのフィル
タリングサポートを行うためには、PERL_SUPPORT を DO にし、使用するシステムで
問題無くコンパイルさせるために PERL_INC と PERL_LIB に適切なものを指定しな
ければいけません。

--------------------------------------------------

innd:
	innd が起動されると、_PATH_PERL_STARTUP_INND をロードし、次に
_PATH_PERL_FILTER_INND をロードします。_PATH_PERL_FILTER_INND がロードされ
る前には、起動時も含めて常に ``filter_before_reload'' というサブルーチンが
定義されていれば、引数無しで呼ばれます。このサブルーチンの戻り値は期待され
ていません。_PATH_PERL_FILTER_INND がロードされた後、``filter_after_reload''
というサブルーチンが同様に実行されます。この二つの関数は通常
_PATH_PERL_STARTUP_INND で定義されます。これらの関数は、キャッシュされた
データをディスクにフラッシュしたり、キャッシュをロードしたり等のようなこと
を行うために使用することができます。

	ctlinnd を ``reload'' のコマンドで、第一引数を ``filter.perl'' ある
いは ``all'' で実行すると、先に説明したように前後でサブルーチンを実行して、
フィルタを行うファイルの _PATH_PERL_FILTER_INND がロードされます。ファイル
が再ロードされた後に ``filter_art'' が定義されていれば、フィルタを行うよう
になります。定義されていなければ、フィルタは行われません。
	
	ctlinnd を ``throttle''、``pause'' あるいは ``go'' のコマンドで実行
すると、``filter_mode'' というサブルーチンが呼ばれます。このサブルーチンは
引数無しで呼ばれ、戻り値は無視されます。このサブルーチンでは、この処理に関
連する ``%mode'' というグローバルな配列にアクセスでき、この配列には次のよう
に三つの key と value があります。

	'Mode' ==> 現在のモード (``throttled''、``paused'' あるいは
			``running'')
	'NewMode' ==> 新しいモード
	'reason' ==> モードの変更で使用された reason

	他のサイトから IHAVE あるいは TAKETHIS で記事を受け取り、フィルタを
行うようになっている場合、``filter_art'' というサブルーチンが呼ばれます。こ
のサブルーチンは引数無しで呼ばれ、単一のあるいは不定義のスカラー値を返しま
す。このサブルーチンでは、この処理に関連する ``%hdr'' というグローバルな配
列にアクセスでき、記事に存在しているすべての標準ヘッダの value を持ちます。
標準ヘッダは次の通りです。

	Approved, Control, Date, Distribution, Expires, From, Lines,
	Message-ID, Newsgroups, Path, Reply-To, Sender, Subject, Supersedes,
	Bytes, Also-Control, References

例:

   %hdr = ('Subject', 'MAKE MONEY FAST!!', 
	   'From', 'Joe Spamer <him@aol.com>',
	   'Date', '10 Sep 1996 15:32:28 UTC',
	   'Newsgroups', 'alt.test',
	   'Path', 'data.ramona.vix.com!gw.home.vix.com!not-for-mail',
	   'Organization', 'Spammers Anonymous',
	   'Lines' '5',
	   'Distribution', 'world'
	   'Message-ID', '<6.20232.842369548@home.octet.com.au>'
	   )


``filter_art'' が(0 でない)ヌルの文字列を返す場合、記事は受け入れられます。
0 以外の値を返す場合、その記事は拒否され、その値(通常は文字列ですが)が、
ログにどうして拒否されたのかを残すために使用されます。

--------------------------------------------------

nnrpd:

	nnrpd が起動されると、_PATH_PERL_FILTER_NNRPD がロードされます。
``filter_post'' というサブルーチンが定義されていると、フィルタは行われます。
定義されていなければ、フィルタは行われません。フィルタを行う場合、POST コマ
ンド経由で受け取った記事は innd での filter_art とまったく同様な方式で
``filter_post'' というサブルーチンに渡されます。記事を受け入れるためには、
戻り値はヌルの文字列でなければいけません。それ以外は、記事は拒否され、クラ
イアントに返される拒否の理由には ``filter_post'' の戻り値が使用されます。

--------------------------------------------------

その他注意すべき点:

samples ディレクトリには filter_inn.pl、filter_nnrpd.pl および
startup_innd.pl があり、それぞれどのように使用するかについての簡単な例と
なっています。すべての perl の処理は ``eval'' により行われているため、die()
を呼んでも、innd あるいは nnrpd を終了させることにはなりませんし、シンタッ
クスや機能的なエラーでも終了することはありません。

フィルタで使用するファイルを再ロードする前には、'perl -c -w file' を実行し
てシンタックスの確認をするべきです。innd を起動後にファイルを変更して再ロー
ドしてもファイルに(シンタックス)エラーがあれば、フィルタは行われません。こ
の場合は、ファイルを修正し再ロードすることになります。
