//
// qmail+maildir+apop+virtualdomain+POPbeforeSMTP extensions to uw-imapd
// Japanese Document below
//

[Comentary]
This patch kit enables uw-imapd to handle;
  * maildir
  * qmail's extended mail addresses of user (~/.qmail-ext)
  * Postfix's extended mail addresses of user (~/.forward+ext)
  * Accesses to extended mail addresses (authenticated with ~/.apop-ext)
  * Virtual domain user switching

Because this package is produced those who want to avail all features above,
we recommend you to turn on all switches for every extension.
Please let me recommend you not to use plain POP3 with this package.
If you want to cling onto POP3, please use qmail-pop3d which comes with
qmail distribution.

[Configuration]
You can select these compilation switches.

  Where:	./Makefile
  Switch:	QMAIL
  What:		Support maildir and user's address extension.
  		This switch is requisite.
  
  Where:	./Makefile
  Switch:	INET6
  What:		Support IPv6 address
  		WORKS fine only via ucspi-tcp+ipv6patch
  		If you are using tcpserver-ipv6, set this.
  
  Where:	./Makefile
  Switch:	POSTFIX
  What:		Defaults user address file to ~/.forward and
		extension delimiter to "+".
		Setting this flag on is equavalent to declare
		-DQMAIL -DDOTQMAIL=".forward" -DXADDR_DELIM="+"
		in ./Makefile.
  
  Where:	./Makefile
  Switch:	RESTRICT_POP
  What:		Restrict POP3 access from unsafe network.  Allow
		normal pop3 access only when environment variable
		INTRANET is set.  This can be controled by tcpd with
		/etc/hosts.allow.
  
  Where:	./src/osdep/unix/Makefile
  Switch:	DEFAULTMAILDIR (quoted string)
  What:		Default users' maildir directory when a user does not
		have ~/.qmail file.
		The default value is null.  If null, the default value in
		osdep/unix/maildir.c("Maildir") will be taken.
  
  Where:	./src/osdep/unix/Makefile
  Switch:	QMAILCONTROL (quoted string)
  What:		Default qmail/control directory.
		The default value is "/var/qmail/control"
  
  Where:	./src/osdep/unix/Makefile
  Switch:	USERAPOPFILE (string)
  What:		User's APOP password file relative to their home dir.
		".apop" is set by default.
  		One of recommended values is "Mail/.apop".
		NOTE THAT USERAPOPFILE should NOT be readable by others.
		Do chmod 600 USERAPOPFILE.
  
  Where:	./src/osdep/unix/Makefile
  Switch:	APOPOPEN (string)
  What:		Command name to decode APOP password from USERAPOPFILE
		"/usr/local/sbin/deapop" is set by default.
  		NOTE THAT you should install deapop command too.
		If you don't want to think about this,
		install the following shell script into /usr/local/sbin/deapop

		  #!/bin/sh
		  cat "$@"

  Where:	./src/osdep/unix/Makefile
  Switch:	POPBEFORESMTP
  What:		Turn on `POP before SMTP' feature.
  		The next variable POP3RECORDER takes effect when
		this variable is defined.

  Where:	./src/osdep/unix/Makefile
  Switch:	POP3RECORDER (string)
  What:		Command name to achieve `POP before SMTP'.
		"/usr/local/etc/pop3-record" is set by default.
  		This recorder program should take one argument of
		fully qualified hostname (or IP address) where the POP
		authentication is passed to.

[NO WARRANTY]

	This package  comes from absolutely NO WARRANTY.   The author of
	this package is  not responsible for any result  caused by using
	this software.  The  copyright of the extension part  is held by
	HIROSE, Yuuji [yuuji@gentei.org].

[COPYING]

	You can re-distribute this  package without any cost except some
	practical cost(magnetical  media or so).   Although this package
	basically obeys  the license  terms in a  file CPYRIGHT  in this
	directory,  there is  one exception;  when you  modify  the code
	against   the  extensional   part  (over   uw-imapd)   and  that
	modification is a kind of bug-fix, modification should be telled
	to  the  author of  extensional  part  if  you are  thinking  of
	re-distribute your modification  to the public.  This limitation
	is  to aim  to  make this  extensional  package reasonably  safe
	always in any time.  Please feel free to hack and distribute it!


-- Japanese document follows...

【qmail+maildir+APOP用POPサーバ】

	このimapパッケージは、qmailとIMAPを組み合わせて使うこと *ではな
	く* qmail+maildir+APOPを柔軟に利用しようということを目的として作
	られましたのでIMAPでのテストは十分に行なわれていません。このパッ
	ケージは以下のような方を満足させるでしょう。

	* qmailを利用している
	* mail spool には安全性の高い Maildir 形式を利用し(させ)ている
	* ~/.qmail-ext ファイルによるqmailの拡張アドレスをよく利用している
	* virtual domain を活用しまくっている

	上記のようなことができるqmailですが、この機能を使いこなすために
	はUNIXマシンにログインしてローカルファイルを見に行くメイルリーダ
	を使うという方法しかありませんでした。これでは不便なので、上記の
	使い分けを認識するPOPサーバを作ろうということで作成したのがこの
	パッケージです。またPOPのみのサーバ利用が多い昨今、リモートから
	の認証にログインパスワードを使わずにメイル専用パスワードを利用さ
	せる変更も行なっています。これによりPOPもAPOP(POPのパスワード認
	証の暗号化版)も共通のパスワードを利用できるようにしました。また、
	POP の場合は既存ユーザのパスワード管理を考えて、認証時にUNIXパス
	ワードも参照するようにしています。

	もう一点、POPはパスワードをプレインテキストで流すため、外部ネッ
	トワークからの利用は危険です。そこでPOPの利用を一部のネットワー
	クに限定する機能もつけました(tcp_wrappersやtcpserverが必要)。

【インストール】

	デフォルト設定では

	* POP3は拒否する
	* ユーザのパスワード設定ファイルは ~/.apop
	* ~/.apop のデコードプログラムは /usr/local/sbin/deapop

	となっています。APOP認証はサーバ側で必ず元のパスワードを知る必要
	があります。これまでのAPOPサーバは全てのユーザ毎に管理者権限でパ
	スワードを設定する必要がありました。一見安全そうですが、じつはユー
	ザがパスワードを変更する頻度を限りなくゼロに近づけているだけです。
	そもそもAPOPはサーバ側で元パスワードを取得する必要があるので必ず
	復元可能な形で保存されなければなりません。ということはどんなに凝っ
	た方法で保存しても結局は復号できるのですから、複雑な方法で暗号化
	&格納をすることは手間を増やすだけです。いずれにしてもroot権限さ
	えあれば元のパスワードは簡単に読めるわけですから、最初からユーザ
	自身にパスワード管理をさせてしまっても何ら問題は無く、むしろその
	方がパスワードをこまめに変えてくれる可能性が(ちょりっと)上がりま
	す。ただし、誰にでもパスワードが読めては困るので、パスワードファ
	イルを chmod 600 しておかないとメイルの取り込みが出来ないように
	なっています。またどうしても平文でファイルに保存するのだけはいや
	だーという場合のために、APOPパスワードファイルは 
	/usr/local/sbin/deapop というコマンドを経由して読み込むようになっ
	ています。これにデコードする処理を書いておきます。もし、とくにエ
	ンコードしなくてもいいという場合は

	  #!/bin/sh
	  cat "$@"

	というシェルスクリプトでも入れておいてください。このパスワードは
	ログインパスワードとは独立しているのでこれで大きな問題は起こらな
	いでしょう(責任は持ちませんが:-)。

	コンパイル時の変数は上記英文解説の場所を読んでください。

【ユーザから見た使い方】

	まず、~/.qmail に正しくmaildirが設定されていることを確認します。
	maildirをまだ作っていない場合は、
	
	% /var/qmail/bin/maildirmake ~/maildir

	とし、~/.qmail に

	./maildir/

	と書きます。またメイル専用パスワードを ~/.apop に記録します。
	これは apoppasswd コマンドで行ないます。

	% apoppasswd

	これで完了です。apoppasswdコマンドは APOPtools/apoppasswd にある
	ので管理者がサイトの環境に手直しした上で一般ユーザのPATHの通る場
	所にインストールして使って下さい。

	さて、拡張アドレスを使いましょう。ログイン名を login とします。
	login-isogi@hogehoge.co.jp のようなアドレスは ~/.qmail-isogi とい
	うファイルで作成できます。login-isogi 用のmaildirを作ります。

	% /var/qmail/bin/maildirmake ~/isogidir

	これを ~/.qmail-isogi に登録します。

	./isogidir/

	最後に login-isogi 用のパスワードを設定します。

	% apoppasswd -e isogi -c
	Enter APOP Password:

	とすると、maildirの作成とパスワードの設定が同時に行えます。
	maildirとパスワードの作成が完了したら、利用してるメイルリーダの
	APOP アカウントの「アカウント名」をlogin-isogi にして接続します。

【POP before SMTPについて】

	まず tcp_wrappers を利用している場合について説明します。
	tcpserverを利用する場合も原理は同じなので仕組みだけ理解してくだ
	さい。

	tcp_wrapperとtcp-envを組み合わせてSMTPサーバを中継用に使うドメイ
	ンを限定して使っていると思います。これの発展形でPOP接続して来た
	ドメインだけにSMTPサーバを使わせる手法のことを "POP before SMTP" 
	と呼びます。このパッケージでも APOP 接続をしたドメインに対して
	SMTPの中継許可を与えることが出来ます。本パッケージの ./APOPtools 
	ディレクトリにある pop3-* を /usr/local/etc にインストールします。
	3つのファイルの実体は同じです。さらに以下の作業をします。

	* 原本となる /etc/hosts.allow を /etc/hosts.allow.src にコピー
	* crontab で10分毎に /usr/local/etc/pop3-age を起動させる

	後者は、大抵のOSの場合 root の crontab に

	     */10  *  *  *  *   root    /usr/local/etc/pop3-age

	などと書けば設定できます。pop3-* スクリプトは自身の環境に合わせ
	て適宜修正して下さい。この段階で、tcp_wrapper の定義ファイルは 
	/etc/hosts.allow.src が大元で、/etc/hosts.allow はcronによって自
	動生成されるものとなります。hosts.allowをいじっても自動的に上書
	きされてしまうので、設定を変えるときは *必ず hosts.allow.src を
	編集する* ことに注意して下さい。

	さらにipop3dを起動するときに接続してきたホストが環境変数
	RELAYCLIENT に入るようにしておきます。/etc/inetd.conf でipop3dを
	起動するときに tcp_wrapper 経由となることを確認します。

	[/etc/inetd.conf]
	  pop3 stream tcp nowait root /usr/libexec/tcpd /usr/libexec/ipop3d

	1999年頃以降のPC-UNIXではinetdにデフォルトでtcpdが組み込まれてい
	ることが多いので、inetd.confにtcpdははさまなくて良いこともありま
	す。続いて /etc/hosts.allow.src で環境変数の設定が起きるようにし
	ます。

	[/etc/hosts.allow.src]
		ipop3d : all : setenv RELAYCLIENT %h

	これで POPサービスを利用しに来たクライアントのアドレスが環境変数
	に入ります。

	tcpserverの場合は、付属の pop3-record スクリプトの後半に例がある
	のでそれを利用してください。

	なお、tcp_wrappers 用の pop3-age スクリプトは負荷の高いマシンで
	は hosts.allow ファイルが空になる可能性があります。lockすれば多
	少ましになるでしょうが完ぺきではありません。もし、hosts.allowの
	書き換えに失敗するような負荷の高い環境で使う場合は tcp_wrappers 
	ではなく、tcpserverでのアクセス制御をすることを強く勧めます。こ
	ちらはロックの必要もなく、安全にアクセス制御ファイルの更新ができ
	ます。

【POPアクセス制御について】

	POP3とAPOPは同じポートを使うので「外部からはAPOPだけ許す」などの
	制御はルータやtcp_wrappersなどだけではできません。このipop3dでは、
	生のPOP3は環境変数INTRANETが定義されているときだけに利用を制限す
	ることができます。tcp_wrappers の例を示します。

		ipop3d : localhost .localnet.hoge.jp \
			: setenv INTRANET : setenv RELAYCLIENT %h
		ipop3d : all : setenv RELAYCLIENT %h

	としておけば、ローカルネットワーク内だけで生POP3を使うことができ
	ます。

【virtualdomain機能について】

	qmailでは /var/qmail/control/virtualdomains を使うことで、ユーザ
	が任意のメイルドメインを持つことができます。これを解釈するように
	しました。/var/qmail/control/virtualdomain ファイルで

		virtual.hoge.co.jp:user1
		dokan.hoge.co.jp:user2-dokan

	としておくと、XX@virtual.hoge.co.jp は ~user1/.qmail-XX に配送さ
	れ、YY@dokan.hoge.co.jp は ~user2/.qmail-dokan-YY に配送されます。
	それがMaildirスプールを含む場合、本パッケージのIMAP/POPで取り込
	むことができます。デフォルトではこのためのパスワードはそれぞれ

		~user1/.apop-XX
		~user2/.apop-dokan-YY

	ファイルに保存しておかなければなりません。

【Postfixの拡張アドレス対応について】

	Postfixによる ~/.forward+ext で発生する拡張アドレスは、その配送
	先がMaildirであれば本パッケージでも利用できます。Postfix のデフォ
	ルト設定の
		forward_path = $home/.forward$recipient_delimiter$extension,
			     $home/.forward
		recipient_delimiter = +

	のまま Postfix を動かしている場合はトップレベルのMakefileの
	EXTRACFLAGS に -DPOSTFIX を追加して下さい(-DQMAILも必要です)。こ
	れにより、拡張アドレスを決めるファイルが ".forward" に、拡張部分
	を区切る文字列が "+" になります。いずれかを変更している場合はた
	とえば、

		-DDOTQMAIL=".postfix" -DXADDR_DELIM="-"

	のように変更できます。もし、Postfix の .forward+ext を利用する場
	合は周辺ツールの APOPtools/apoppasswd, APOPtools/apopcall.c の対
	応する変数も変更する必要があることに注意して下さい。また、パスワー
	ドファイルも ~/.apop-ext ではなく~ /.apop+ext となることに注意が
	必要です。これらが面倒な場合は、Postfix の設定の方で .qmail-ext 
	を見るようにしてしまうのも手です。この場合は

		recipient_delimiter = -
		forward_path = $home/.forward$recipient_delimiter$extension,
				$home/.qmail$recipient_delimiter$extension,
				$home/.forward

	とすると ~/.qmail-ext も参照するようになり、デフォルト状態の本パッ
	ケージのまま利用することができるでしょう。

【Postfixの POP before SMTPについて】

	main.cf で たとえば次のようにします。

		smtpd_recipient_restrictions = 
			permit_mynetworks
			check_client_access hash:/etc/postfix/client_access

	ここで /etc/postfix/client_access は POP before SMTP の許可ホス
	トリストを保持するためのファイル名で、既に使われてはいないものに
	します。配布ディレクトリの APOPtools/pop3-record.postfix は
	/etc/postfix/client_access ファイルをリレー許可判定に使うことを
	前提とした Postfix 用のスクリプトです。

【謝辞】

	安井卓さん(tach@debian.or.jp)にはsyslog関係のパッチを頂きました。
	ここに感謝の意を表します。

【免責】

	IMAPパッケージに本ドキュメントで説明した拡張機能を追加する部分の
	著作権は広瀬雄二[yuuji@gentei.org]が保持します。このプログラムを
	用いて生じた如何なる結果に対しても著作権者は責任を負いません。

						2009/9/14 yuuji@gentei.org
