DeleGate導入の手引き |
DeleGate第9版用 / ver.0.95alpha / 2014年11月7日 |
ご注意:この文書はアルファ版です。
(0-0) DeleGate は、多用途で、マルチプロトコル、かつマルチプラットフォーム対応の プロキシサーバです。 導入にあたっては、特定の用途に合わせて仕立ててやる必要があります。
(0-1) この手引きでは、はじめてDeleGate をお使いになる方のために、 インストールや設定などの、導入手順のあらましを説明します。
(0-2) 目次
(0-3) 2014年10月現在の DeleGate の最新安定版は 9.9.13 ですが、この手引きに書かれている内容はそれ以前の(ここ数年以内の) 第9版にも当てはまります。 以下ではこれらを 9.9.X と表記します。
(0-4) DeleGate の詳細情報と配布ファイルは サポートサイト または 公式サイト から提供されています。 どちらかのサイトで閲覧、また配布サーバからダウンロードして下さい。
(0-5) この手引きに書かれたDeleGate本体の機能は、ごく簡単な抜粋です。 詳細につきましては、 ドキュメント一覧、 リファレンスマニュアル を御覧下さい。 付録(Z)の設定例も参考になると思います。
(0-6) この手引き以前に、DeleGate の導入手順など、 周辺情報に関するまとまった文書は(特に 日本語では)、 書かれたことがありませんでした。 この手引き書には、これまで文書化されていない事も書かれています。 v9.9.13では、従来の版との設定の互換性は保たれていますが、 配布ファイルの詰め合わせ形式や、インストールの推奨方法が変更されています。 既にDeleGateをお使いの方にも一読して頂きたいと思います。
(0-7) これを書いているうちに説明が面倒になったので(笑)、 説明しやすいように詰め替えしたv9.9.13 をリリースすることになりました。
(0-8) この手引きは不完全であり、 随時改訂を行なっていく予定です。 誤りや、ご不明な点のご指摘は、 フォーラムのほうでお待ちしています。
(1-0) バイナリ版のススメ
(1-1) バイナリ配布版のダウンロード
(1-2) 各種OS用バイナリ配布
(1-3) バイナリ配布ファイルの内容(v9.9.13以降)
(1-3w) Windows版
win32-dg9_9_X.zip
という名前のZIP 形式ファイルです。 これを展開すると以下のフォルダとファイルができます。dg9_9_X/DGROOT/bin/con32-dg9_9_X.exe ... DeleGate実行形式ファイル dg9_9_X/DGROOT/bin/con32-dg9_9_X.conf.txt ... デフォルトの設定ファイル dg9_9_X/DGROOT/bin/libssl32.dll ... SSL 動的ライブラリ dg9_9_X/DGROOT/bin/* ... その他のDLLおよび補助プログラム
(1-3u) Unix版
osname-dg9_9_X.tar.gz
という名前の圧縮tarファイルです。 これを展開すると以下のディレクトリとファイルができます。dg9_9_X/DGROOT/bin/dg9_9_X ... DeleGate実行形式ファイル dg9_9_X/DGROOT/bin/dg9_9_X.conf.txt ... デフォルトの設定ファイル dg9_9_X/DGROOT/subin/dgbind ... 特権bind実行補助プログラム dg9_9_X/DGROOT/subin/* ... その他の特権実行補助プログラム
(1-4) バイナリ配布ファイルの内容(v9.9.12以前)(この段はいずれ削除します)
(1-4w) Windows版
(1-4wk) win32-dg9.9.X.zipという名前のZIP 形式のファイルです。 この中には、DeleGate の実行形式ファイル con32-dg9_9.X.exe と、補助用の DLL 形式ファイルなどが含まれています。
(1-4u) Unix版
(1-4uk) osname-dg9.9.Xという裸の実行形式ファイルです。 補助用の実行ファイル(dgbindなど) が必要な場合には、ソース版からビルドして下さい。
(2-0) バイナリ配布版で事足りる方にはこの節は不要です。
(2-1) ソース配布版のダウンロード
delegate9.9.X.tar.gz
というファイル名で置かれています。サイズは3メガバイト未満です。(2-2) ビルドに必要な環境
(2-3) ビルドの手順
(2-3w) Windows の場合
(2-3wk) $ tar xfz delegate9.9.X.tar.gz $ cd delegate9.9.X $ nmake ADMIN="foo@bar.baz"なお、開発元では Visual Studio 2005 という10年前の遺物を使用しており、 その後の VC++ でnmake 可能かどうかは不明です。 Windows 上での一時的な利用が目的の場合には、 Cygwin のG++ でmake しても良いでしょう。
(2-3u) Unix または Cygwin の場合
(2-3uk) $ tar xfz delegate9.9.X.tar.gz $ cd delegate9.9.X $ make ADMIN="foo@bar.baz" $ sh install.sh (v9.9.13以降)
make は特権ユーザ(root)ではなく一般ユーザで行なうことを推奨します。 何かが誤った場合に、被害を最小限にするためです。
foo@bar.baz はDeleGateの管理者のメールアドレスです。 このメールアドレスは実行形式に組み込まれ、 起動時に指定が省略された場合のデフォルト値になります。 バイナリ配布版では空になっています。
make が終了すると"src" というディレクトリの下に、 "delegated" という実行形式が出来ます。 また、"subin" というディレクトリの下に、 "dgbind" などの補助用の実行形式が出来ます。
(2-4) バイナリ版とソース版の違い
(3-0) DeleGateのインストール先と実行形式名を決めて、(手動で)移動と 名前変更を行ないます。
(3-1) インストール先と実行ファイル名の決定
DgRoot: DeleGateをどのフォルダ(ディレクトリ)に インストールするか決めます。 以下では、インストール先のディレクトリを DgRoot と表記します。 DgRoot は絶対パスです。 Windows の場合にはドライブ名を含む"C:/DeleGate" のようなものになります。 [→注記:X3-1]
DgExe: DeleGateの実行形式の名前を決めます。 以下では、この名前をDgExe と表記します。 バイナリ配布版のdg9_9_X やcon32-dg9_9_X.exe あるいはソースからビルドして出来た"delegated" のままでも構いません。 (Widows版の場合には ".exe" を除いた部分です)
(3-2) v9.9.13 以降
Unix 版で"subin" を使用する場合 (特権ポートを使用する場合など)には、以下を実行します。
(3-2uk) $ cd DgRoot/subin $ sh setup-subin.sh
(3-3) v9.9.12 以前(この段はいずれ削除します)
DgRoot/bin の下にある con32-dg9_9_X.exe を名前変更します (変更せずにそのままでも構いません)
(3-2uk) $ mkdir DgRoot $ mkdir DgRoot/bin $ mv DgExe DgRoot/bin/必要であれば、DgRoot/subin の下に gbind などの補助プログラムをインストールします。
(4-0) DeleGate には 複数の設定方法と多数の設定パラメータがあります。
(4-1) コマンドパスの設定
(4-2) 設定値の与え方
1) コマンド引数 | ... | NAME=Value あるいは -Option |
2) 明示的にロードされた設定ファイル | ... | +=Url |
3) 共通の設定ファイル | ... | DgRoot/common.conf |
4) デフォルトの設定ファイル | ... | DgExe.conf.txt |
5) 環境変数 | ... | export NAME=Value |
6) 実行形式に埋め込まれた設定値 | ... | -Fimp NAME=Value |
(4-3) 基本的な設定パラメータ
DGROOT=DgRoot | ... | DgRoot のパス |
ADMIN=foo@bar.baz | ... | このDeleGateの管理者のメールアドレス |
SERVER=pppp | ... | クライアントとの通信プロトコル pppp |
-Pnnnn | ... | クライアントからの接続を受け付けるポート番号 nnnn |
(4-4) デフォルトの設定ファイルによる設定方法
(4-4ak) $ cat DgRoot/bin/DgExe.conf.txt DGROOT=DgRoot ADMIN=foo@bar.baz SERVER=http -P8080 $ DgExeDeleGateを一つの用途だけに使用する場合には、このように デフォルトの設定ファイルで全てのパラメータを指定しても良いでしょう。
(4-5) 環境変数による設定方法
(4-5ak) $ export DGROOT=DgRoot $ export ADMIN=foo@bar.baz $ export SERVER=http $ export DGOPTS=-P8080 $ DgExe実際には、環境変数では DGROOT や ADMIN などの固定的なパラメータを指定し、 SERVER やポートなどはコマンド引数で指定するのが良いでしょう。
(4-6) コマンド引数による設定方法
(4-6ak) $ DgExe DGROOT=DgRoot \ ADMIN=foo@bar.baz \ SERVER=http \ -P8080
(4-7) 設定ファイルの明示的なロード
(4-7ak) $ DgExe +=xxx.conf +=http://server/path/yyy.conf .. [xxx.confの内容] ADMIN=foo@bar.baz SERVER=http -P8080なお、+=Url でロードされるファイル中でDGROOT を 指定することはできません。 それは、+=Url が処理される時点では、既にDGROOTは確定しており、 UrlもDGROOTから相対的に解釈されるからです。
(4-8) 設定パラメータの実行ファイルへの埋め込み
(4-8ak) $ DgExe -Fimp DGROOT=DgRoot ADMIN=foo@bar $ DgExe -Fimp SERVER=http -P8080 $ DgExe埋め込まれているパラメータやヘルプ情報を表示するには DgExe -Fimp -h とします。
(5-1) 起動
(5-1ak) $ DgExe [引数リスト]デフォルトの設定ファイルに全てのパラメータを書いてある場合には、 DeleGateのアイコンをクリックするだけです。
(5-1w) Windowsの場合
(5-1u) Unixの場合
(5-2) テスト用の起動
(5-2ak) $ DgExe -fv [引数リスト]
(5-3) 終了
(5-3ak) $ DgExe [引数リスト] -Fkill [-Pnnnn]
(5-4) ホストのブート時の自動的な起動
(5-4w) Windows の場合
(5-4u) Unix の場合
(5-4uk) @reboot /path/of/dgrc.sh
(5-5) 設定変更と再起動
(5-5w) Windowsの場合
(5-5u) Unixの場合
(5-5ak) $ DgExe -r [引数リスト]
(5-5bk) $ DgExe [引数リスト] -Fkill-hup [-Pnnnn] $ DgExe [引数リスト]
(6-0) 増大するファイルの管理
(6-1) ログファイルの切り分け
(6-1ak) LOGDIR='log[date+/y%y/m%m/%d]' ... 将来のデフォルト値 LOGFILE='${LOGDIR}/${PORT}' ... デフォルト値 PROTOLOG='${LOGDIR}/${PORT}.${PROTO}' ... デフォルト値この分割に伴い、[date+format] という部分を除いたログファイルが同時に作られます。 Unixでは以下のようなハードリンクが作られます。
(6-1bk) DgRoot/log/8080.http == DgRoot/log/y14/m10/31/8080.httpこれにより、 ログファイルがどのように分割され、最新のもの(例えば今日の)がどこに あるか意識することなく、LOGDIR の直下を見れば良いようになっています。
(6-2) ログファイルの圧縮・削除
(6-2ak) $ find DgRoot/log -type f -mtime +1 -exec gzip -f "{}" ";"
(6-3) ログの詳細化・無効化オプション
(7-0) アンインストールの基本
(7-1) 実行中のサービスの終了
(7-1w) Windows の場合
(7-1wk) $ DgExe -Pnnnn (サービスを削除するか聞いてくるので y と答える)
(7-1u) Unix の場合
(7-2) ファイルの削除
(8-0) 公式サイトではサポートを提供していません。
(8-1) サポートサイト にある フォーラム で、サポートが提供されています。 ただし、これはあくまでもボランタリベースで提供されているものであり、 お問い合わせ等に対して回答が保証されるものではありません。 あらかじめ御了承下さい。
(8-2) フォーラムに投稿された記事は、ウェブで公開され、アーカイブされ、また Google などの検索エンジンに対する探索・検索の対象にもなります。投稿される際には、個人情報や組織内情報などを書かないようにご注意下さい。
(8-3) フォーラムで質問される場合には、検討や回答のために必要十分な情報を書いて下さい。ひとつの模範的な例がここにあります。
(8-4) サポートサイト側から配信を行なうメーリングリストはありません(過去にはありましたが、廃止されました)
(9-0) DeleGateは(2014年現在)産業技術総合研究所(産総研)がその 全著作権を保持する知的財産です。
(9-1) DeleGateは、 個人または非営利組織による利用、 あるいは営利組織による評価目的での短期間の利用に対して無償で利用許諾されています。 それ以外の場合には、 公式サイト にあるライセンス情報を御覧下さい。
(9-2) 第9版での商用利用のライセンス条件は、第8版のそれから変更されましたのでご注意下さい。
(9-3) この文書「DeleGate導入の手引」は(DeleGateの作者である) 佐藤@DeleGate.ORG によって個人的に書かれたものであり、 その全著作権は佐藤個人に帰属します。
(X0-1) リリース v9.9.13 での変更点
(X1-1) バイナリ配布ファイルの対応プラットフォーム (9.9.X)
(X2-1) make 用設定ファイル -- DELEGATE_CONF
(X2-2) config というステップはありません
make の前に一般に行なわれるconfig (Configure) というステップはありません。 プラットフォーム依存、環境依存、コンパイラ依存といった構成の違いは、 make の過程で自動的に選択されます。 構成に依存した関数は、"maker" というディレクトリの下に置かれています。 この下にあるプログラムのコンパイルが試行され、コンパイルに成功したものが採用されることで、 構成の違いに適応しています。 環境の違いによって有無や版が異なるライブラリについては、 動的にローディングするようにし、無い場合にはスタブを使用することで適応しています。
(X2-3) make install はありません
DeleGateはもともと、一般ユーザが作成して、自分の権限で実行することを
想定して作られています。
root 権限の下で、得体の知れない(笑)プログラムや設定情報をシステムの
あちこちにばらまくのもばらまかれるのも恐ろしい事です。
プラットフォームによっていろいろとある流儀に対応するのも大変です。
アンインストールが面倒なことになるのも面倒です。
そんなこんなで、DeleGateには一般にroot権限で実行されるmake install
というものはありません。
開発者も、使用している多数の実マシン・仮想マシンは全て自分専用なので、当然
rootにもなれますが、恐ろしいrootにはなりたくないので、一般ユーザとして
DeleGateのディレクトリを所有し、一般ユーザとしてDeleGate を実行しています。
DeleGate の使用するファイルは基本的に全てDGROOT の下に置いています。
v9.9.13 でinstall.sh なるものを追加しましたが、これは単にバイナリ配布版と
ソース配布版で共通のDGROOT 以下の構造を作るだけのためのものです。
ただし、どうしても特権ユーザ権限で実行しなければならない機能
(システムコール)があります。代表的なものが、特権ポートの使用
(ソケットの bind() )です。
DeleGateではそれらを行なうためだけに特化したプログラム(例えば
bind() だけを行なうdgbind)を作り、DGROOT/subin の下に配置して使用します。
これらはインストール時に一度だけ、chown とchmod をしてやる必要
があります。v9.9.13 以降では、DGROOT/subin の下にある
setup-subin.sh を実行すればOKです。
これは、テストなどのために何度もmakeを行なうような場合に特に重宝です。
DeleGateに指示するパス名の区切り文字はバックスラッシュ"\" でなく、 スラッシュ "/" を用いて下さい。 DeleGateは(Unix環境で育ったので)"\" を エスケープ文字として解釈することがあります。 また、HTTPのURLやFTPのファイル名、あるいはDeleGateのMOUNT では パスの区切りを"/" を使っていますので、これに統一するのが良いでしょう。
Cygwin をインストールして使用されることを推奨します。
Unix使いの方が、何らかの理由で仕方なく(笑)Windowsを使わなければ ならなくなった場合。Cygwin では cron を提供していますが、インストールが 何やら面倒くさいです。 DeleGate を cronの代替として使うことでより簡便に、 バックグラウンドでの定期的な実行ができます。 例えば、以下のように。
$ DgExe CRON="0 * * * * c:/cygwin/bin/sh.exe d:/path/of/script.sh"
(X3-2) Unixにおいて特権ユーザ権限を代行する外部プログラム [インストール方法]
(X4-1) DgRoot の位置
(X4-2) 関連ファイルのデフォルトの配置
(X4-3) 主な設定パラメータとオプション
(X4-4) 同一名の設定値が複数与えられた場合の解釈
DGROOT や ADMIN など、基本的なパラメータのいくつかは、 そのうち一つだけが優先順位に基づいて使用されます。 与えられた方法によって優先順位がありますが、同じ方法で複数与えられた場合には、最後に与えられたものが使用されます。
TIMEOUTやHTTPCONFなどは、さらにサブの値を指定しており、 起動時に最後に与えられたサブの値が使用されます。
RELIABLE や HOSTLIST など、リストを表すものは、 複数指定された場合、("+," の前置により)リストに追加することを明示しない限り、 後続のもので新たなリストが定義されます。
多くのパラメータは、複数指定したものが全て、起動時には有効になり、 実行時に選択されます。 複数の方法で与えられた場合にも、それらが全て有効です。
PERMITやFORWARD などは、起動時に全てが取り込まれ、 実行時に与えられた順番に従ってマッチングの対象となり、 最初にマッチしたものが使用されます。
MOUNTは例外的に、与えられた順序によらず、起動時にソートされて、 実行時にその順序でマッチングが行なわれます。
(XX-1) 遠隔管理機能の挫折
(Z-1) 設定ファイル
(Z-2) この手引き