DeleGate導入の手引き |
| DeleGate第９版用 / 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本体の機能は、ごく簡単な抜粋です。 詳細につきましては、 ドキュメント一覧、 リファレンスマニュアル を御覧下さい。 付録（Ｚ）の設定例も参考になると思います。
(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
というファイル名で置かれています。サイズは３メガバイト未満です。(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
$ DgExe
DeleGateを一つの用途だけに使用する場合には、このように
デフォルトの設定ファイルで全てのパラメータを指定しても良いでしょう。
(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-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 を実行すればＯＫです。
これは、テストなどのために何度も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) この手引き
#!/path/of/delegated +=
###
##---------------------------------------------------------------------
## A template of default configuration file for DeleGate version 9.X
## ver.0.4alpha, 2014-11-05, Yutaka Sato @ DeleGate.ORG
##---------------------------------------------------------------------
## - The latest version of this file is available at:
## http://www.delegate.org/delegate/dg9.conf.txt
##
## - This is an example of a configuration file of DeleGate.
## - The "configuration" of DeleGate is a set of parameters (or options)
## which can be given in command line options, in configuration files,
## in environment variables, and so on.
## - A "configuration file" of DeleGate is a plain text file including
## a list of configuration parameters one per line.
## - The "default" configuration file is the one named as "XXX.conf"
## that is loaded on invocation of an executable file of DeleGate
## named as "XXX".
## - You may give all of parameters in the default configuration file
## and invoke DeleGate without command line options.
## - But it is more likely that writing a common set of parameters in
## the default configuration file while giving other parameters in
## command line options those are specific to individual usage.
##
## - Category of parameters
## ==A ... access control
## ==C ... configuration file
## ==D ... deployment of directories
## ==L ... logging
## ==N ... networking
## ==P ... application server
## ==R ... resource restriction
## ==S ... daemon and service
## - Multiplicity of parameters
## [0-1] ... at most one is given
## [0-n] ... can be given multiply
#
##==C [0-n] ---- shortcut example --------------- MINIMUM CONFIGURATION
#@ typical and minimum configuraiton for a HTTP proxy, plus alpha
##---------------------------------------------------------------------
## - The following is a typical set of configuraiton parameters for
## DeleGate as a HTTP proxy.
#
#ADMIN=foo@bar.baz # mail-address of the administrator of this DeleGate
#SERVER=http # the protocol DeleGate speaks with its clients
#-P8080 # the entrance port on which DeleGate waits clients
##
## - a little more parameters that are generally used.
#
#-vs # suppress logging of the behavior of DeleGate
#SOCKS=192.168.1.1:1080 # forwarding any protocol to a SOCKS server, or
#PROXY=192.168.1.1:8080 # forwarding HTTP to an upstream HTTP proxy
##
## - a little more, a little tricky usage.
#
#SSTUNNEL=192.168.1.1:8080 # forwarding any protocol to HTTP SSL-tunnel
#SERVER=tcprelay://odst.- # transparent TCPrelay maybe forwarded to SOCKS
#
##==C [0-1] ---- delegated.conf ------------ DEFAULT CONFIGURATION FILE
#@ ${EXECDIR}/${EXECNAME}.conf[.txt] ... the default configuration file
##---------------------------------------------------------------------
## - To be detected as the "default configuration file" by DeleGate,
## this file must be located at and named as:
## /path/of/delegated.conf[.txt]
## where the path of the executable file of DeleGate is:
## /path/of/delegated[.exe]
## - More generally, it must be EXECDIR/EXECNAME.conf[.txt] where
## EXECDIR is the directory under which the executable file of
## DeleGate is, and EXECNAME[.exe] is the name of the executable file.
## - On Unix, an EXECNAME file can be a symbolic link to the executable
## file so that each symbolic name can have each configuration file.
## - In v9.9.13 or later, also EXECDIR/../etc/EXECNAME.conf[.txt] is a
## candidate of a default configuration file.
#
##==L [0-1] ---- -vQ --------------- TRACING CONFIGURATION FILE LOADING
#@ -vQ ... quietly loading the default configuration file
#@ -vq ... quietly loading all configuration files (loaded by +=URL)
##---------------------------------------------------------------------
## - Uncomment the following line to suppress the message shown on the
## invocation of DeleGate as "#### loading default conf: ..."
#
#-vQ
#
##==D [0-1] ---- DGROOT ----------------------- DELEGATE ROOT DIRECTORY
#@ DGROOT=dirPath ... the root directory of DeleGate
##---------------------------------------------------------------------
## - The root directory of DeleGate under which all of directories of
## DeleGate are located by default.
## - DeleGate may load multiple configuration file but only the
## "default configuration file" can set the DGROOT value.
## - It can be specified as an absolute path like bellow:
#DGROOT='/home/${HOME}/delegate' # the default on Unix
#DGROOT='C:/Program Files/DeleGate' # the default on Windows
## - Or it can be specified as a relative path that is relative to the
## executable file of DeleGate using the string '${EXECDIR}'.
## - '${EXECDIR}' is substituted by the path of directory under which
## the executable file of DeleGate is located.
## - For example, if the path of executable is
## ".../DGroot/etc/delegated.exe" then the ${EXECDIR} points
## ".../DGroot/etc", thus "${EXECDIR}/.." points ".../DGroot".
#
DGROOT='${EXECDIR}/..'
#
##==C [0-1] ---- common.conf ---------------- COMMON CONFIGURATION FILE
#@ ${DGROOT}/common.conf ... the common configuration file
##---------------------------------------------------------------------
## - "common" configuration file is commonly used among DeleGates that
## uses the same DGROOT.
## - It is loaded unconditionally if exists.
#
##==C [0-n] ---- +=URL ---------- LOADING CONFIGURATION FILE EXPLICITLY
#@ +=URL ... loading configuration file from the specified URL
##---------------------------------------------------------------------
## - If the URL is a relative path, it is relative from the
## configuration file that loades it.
## - Configuration file can be loaded recursively.
#
#+=http://server/path/dgconf.txt
#+=/path/of/dgconf.txt
#+=dgconf.txt
#
##==D [0-1] ---- LDPATH ------------------------------- DYNAMIC LIBRARY
#@ LDPATH=listOfDirectory ... search path for dynamic libraries
#@ DYLIB=listOfNamePattern ... name pattern of dynamic libraries
##---------------------------------------------------------------------
#LDPATH='${ETCDIR};${LIBDIR};${HOME}/lib;/usr/lib;/lib'
#DYLIB='lib*.so.0.9.8,lib*.so.1,lib*.so' # Unix
#DYLIB='lib*.0.9.8.dylib,lib*.dylib' # MacOSX
#DYLIB='cyg*-0.9.8.dll,cyg*-1.0.0.dll' # Cygwin
#DYLIB='*.dll' # Windows
#
##==L [0-1] ---- ADMIN ---------------------------------- ADMINISTRATOR
#@ ADMIN=mailAddress ... mail address of the administrator
##---------------------------------------------------------------------
## - The address is used to notify fatal "incident" to administrator
## from DeleGate via mail.
## - "Incident" includes a detection of an attack from intruder that
## caused fatal error like segment violation in DeleGate.
## - It is also used to show the contact address of the administrator
## of this DeleGate to clients on usual error like broken links.
## - Thus, it is recommended to be not a personal address but an
## address of a role name like "delegate-admin@bar.baz".
#
#ADMIN=foo@bar.baz
#
##==N [0-1] ---- RESOLV -------------------------- HOST NAME RESOLUTION
#@ RESOLV=orderOfResolver ... order of trial of resolution methods:server
#@ RES_AF={46,64,4,6} ... order of IPv4 and IPv6
##---------------------------------------------------------------------
## - Controls the behavior of host-name resolver of DeleGate.
## + orderOfResolver is a list of followings:
## - cache: cache file for "file", "dns" and "sys" bellow.
## - file[:pathOfHosts] ... file in the format of /etc/hosts
## If the path is a relative one, it is searched under DGROOT/etc.
## - dns[:DNSserver] ... DNS server.
## - sys ... the resolver of the host system.
#
#RESOLV=cache,file,dns,sys # typical configuration
#RESOLV=cache,file:hosts,dns:192.168.1.1,sys
#
##==N [0-n] ---- HOSTS --------------------------- HOST NAME DEFINITION
#@ HOSTS="nameList/addressList" ... defining a pair of hotname/address
##---------------------------------------------------------------------
## - HOSTS pre-defines an entry in the on-memory cache of the resolver
## of DeleGate, suppressing resolution by resolvers listed in RESOLV.
## - It can be used to define hosts that are unresolvable by resolvers
## listed in RESOLV.
#
#HOSTS="localhost/127.0.0.1"
#HOSTS="{host1,host2}/1.2.3.4"
#HOSTS="host3/{1.1.1.1,1.1.1.2}"
#
##==N [0-n] ---- HOSTLIST ------------------------ HOST LIST DEFINITION
#@ HOSTLIST="name:listOfHosts" ... definition of named list of hosts
##---------------------------------------------------------------------
## - HOSTLIST defines a named list of hosts to be referred like a host
## name in other named or unnamed host lists.
## - A host list is used for matchhing of access control list (ex.
## REACHABLE), routing destination (ex. FORWARD), MOUNT, and so on.
## - A member of the list is one of host-name, domain-name with a wild
## card, IP-address, masked IP-address or range of IP-addresses.
## - "*" matches any hosts
## - Wild card in domain name matching is like *.subdoamin.domain
## - The matching can be negation by "!" prefix to a host
## - A masked IP address is n.n.n.n/m.m.m.m, n.n.n.n/m, or host-name/m
## - A range of IP addresses is as n.n.n.[n-m]
#
#HOSTLIST="reachable:host1,host2,*.dom1,!*.dom2.dom1,!10.0.0.0/8"
#HOSTLIST="unreachable:!reachable"
#
##==R [0-n] ---- MAXIMA ----------------------- RESOURCE USAGE LIMITTER
#@ MAXIMA=what:maxValue ... limitter of resource usage
##---------------------------------------------------------------------
## - The number of processes of DeleGate increases/decreases dynamically
## based on the current load onto DeleGate.
## - A "resident" process is the one that stays for a while after it
## finished a processing of a request/session, waiting a next
## connection from clients to process.
#
#MAXIMA=delegated:64 # max. parallel DeleGate processes
#MAXIMA=standby:32 # max. parallel resident DeleGate processes
#MAXIMA=conpch:16 # max. parallel connection from a client host
#MAXIMA=listen:16 # size of the backlog of the entrance socket
#
##==R [0-n] ---- TIMEOUT -------------------------------------- TIMEOUT
#@ TIMEOUT=what:timeOut ... timeout idle connection, process, response
##---------------------------------------------------------------------
##
#
#TIMEOUT=io:60 # breaking idle connection to terminate the session
#TIMEOUT=standby:30 # exit of resident DeleGate on no client connection
#TIMEOUT=dns:10 # giving up DNS response of too long latency
#TIMEOUT=http-cka:30 # breaking idle HTTP connection in keep-alive
#
##==D [0-1] ---- LOGDIR ------------------- LOGGING DIRECTORY AND FILES
#@ LOGDIR=logDirectory ... directory under which logfiles are located
##---------------------------------------------------------------------
#
#LOGDIR=${DGROOT}/log # the default
#LOGDIR=/var/spool/delegate/log
##
## - Logfiles can be split day by day using "[date+format]" specifier
## where "format" is the one like in strftime() function.
## - For example, "%y", "%m", "%d" and "%H" mean two digits
## representation of year, month, day and hour respectively.
## - The following is the recommended one that will be the default in
## future version of DeleGate. With this parameter, the log-file of
## HTTP in 31 October 2014 is "DGROOT/log/y14/m10/31/80.http".
## - On Unix, a hard link for a split log-file created with a name
## without the "[date+format]" part, that is "DGROOT/log/80.http" in
## the example bellow.
#
#LOGDIR='log[date+/y%y/m%m/%d]' # split log-directory day by day
#PROTOLOG='${LOGDIR}/${PORT}.${PROTO}' # the default log-file path
#
##==S [0-n] ---- SERVCONF --------------- RESTARTING SERVICE ON WINDOWS
#@ SERVCONF=[yesall|auto|demand] ... starting service without interaction
##---------------------------------------------------------------------
## - DeleGate on Windows become a service of name with the port number
## as "DeleGate-P8080".
## - It starts with interaction with the user on the console as follows:
## 1) stop the current service if running ... asking [y]/n
## 2) delete the current service if exists
## 3) create a new service ... asking [y]/n
## 4) set automatic start of the service ... asking [y]/n
## 5) start the new service
## - SERVCONF=yesall ... sets "y" for all interaction 1),3),4)
## - SERVCONF=auto ... sets "y" for 4)
## - SERVCONF=demand ... sets "n" for 4)
## - "yesall" behaves like "-r" option for Unix daemon.
#
#SERVCONF=yesall # restart without interaction
#SERVCONF=auto
#SERVCONF=demand
#
##==S [0-1] ---- -r --------------------------------- RESTARTING DAEMON
## -r ... restart after terminating current daemon process
##---------------------------------------------------------------------
## - The process-id of current daemon is recorded in
## '${DGROOT}/act/pid/${PORT}' where '${PORT}' is the "primary" port
## of the daemon.
## - The "primary" port is the one of entrance ports given firstly in
## "-P" or "-Q" option.
## - With "-r" option, DeleGate kills currently running DeleGate daemon
## process by SIGTERM, and wait until the process releases the
## entrance port.
## - This option is applicable to a daemon on Unix, or a daemon running
## in foreground on Windows.
## - "-r" behaves like SERVCONF=yesall for Windows service.
#
#-r
#
##==S [0-n] ---- -f ----------------------------- RUNNING IN FOREGROUND
#@ -f[v] and -v[v] ... running in foreground
##---------------------------------------------------------------------
## - running DeleGate in foreground mainly for testing and debugging.
## - In this mode, DeleGate is kept connected to the console (tty) from
## which it is invoked so that it can put log messages to the console
## and can be terminated with Control-C.
## - Also DeleGate stays on the working directory of the parent process
## (shell command usually) by which it is invoked so that
## configuration files and core files are get from or put to the
## working directory.
#
#-f # Running in foreground
#-fv # like -f, putting log both to console and log-file (LOGFILE)
#-v # Running in foreground, putting log to console
#-vv # like -v, with detailed log
#
##==L [0-1] ---- -v ------------------------------------- LOGGING LEVEL
#@ -v[stud] ... log detailness level
##---------------------------------------------------------------------
## - -v[stud] specifies detailness of information in "LOGFILE".
## - -vS specifies not creating "PROTOLOG".
#
#-vd # detailed
#-vs # silent, don't create LOGFILE.
#-vt # terse
#-vu # usual
#-vS # suppress "PROTOLOG" for HTTP (as 80.http) and FTP (ex. 21.ftp)
#
##==A [0-n] ---- RELIABLE ---------------------------- RESTRICT CLIENTS
#@ RELIABLE=hostList ... list of client hosts to be accepted
##---------------------------------------------------------------------
## - A comma separated list of client hosts to be accepted by DeleGate.
## - It is a unnamed hostList of which syntax follows the one of value
## part of HOSTLIST parameter.
#
#RELIABLE="localhost,10.10.0.0/16,!10.1.2.[5-7],*.delegate.org"
#RELIABLE="+,192.168.1.1/24"
#RELIABLE="*" # running as a server open to public
#
##==A [0-1] ---- REACHABLE --------------------------- RESTRICT SERVERS
#@ REACHABLE=hostList ... server hosts to be reachable
##---------------------------------------------------------------------
## - A comma separated list of server hosts to which connections from
## the DeleGate are allowed.
## - It is a unnamed hostList of which syntax follows the one of value
## part of HOSTLIST parameter.
#
#REACHABLE="*"
#REACHABLE="*,!10.0.0.0/8"
#
##==A [0-n] ---- PERMIT ----------------- RESTRICT CLIENTS WITH SERVERS
#@ PERMIT="protoList:servList:clntList" ... permit by combination
#@ REJECT="protoList:servList:clntList" ... reject by combination
##---------------------------------------------------------------------
#
#PERMIT="+:.reachable:.reliable" ... default
#PERMIT="*:*:*" ... fully open
#
##==A [0-n] ---- AUTHORIZER ---------- AUTHENTICATION AND AUTHORIZATION
#@ AUTHORIZER=listOfAuthMethod ... auth. method of users
#@ MYAUTH=user:pass ... auth. info to be sent to server (by proxy)
##---------------------------------------------------------------------
##
#AUTHORIZER=-list{user:pass},-pam
#AUTHORIZER=-dgauth{user:pass} ... digest authentication (HTTP only)
#
##==N [0-n] ---- FORWARD ----------------------------------- FORWARDING
#@ FORWARD=gwproto://[gwuser:gwpass@]gwhost:gwport[-_-protoL:servL:clntL]
#@ SOCKS=host[:port] ... upstream SOCKS server
#@ PROXY=host[:port] ... upstream proxy in protocol proto of SERVER=proto
#@ SSLTUNNEL=host:port ... upstream HTTP proxy as a SSL-tunnel
##---------------------------------------------------------------------
## - Forwarding to upstream proxy server.
## - Upstream proxy is one of SOCKS, application proxy (HTTP or FTP),
## or SSL-tunnel(HTTP proxy).
## - FORWARD is a generic parameter for forwarding. It defines an
## upstream proxy by its protocol (socks, http, ssltunnel, etc.), its
## host and port, and user name and password if necessary.
## - Multiple FORWARD can be specified and one of them are selected
## based on destination protocol, server, and source client.
## - Examples:
#FORWARD=socks://192.168.1.1:1080
#FORWARD=http://192.168.1.1:8080 # applicable when client's speaks HTTP
#FORWARD=ssltunnel://192.168.1.1:8080
## - Examples: The above can be abbreviated as the bellow.
#SOCKS=192.168.1.1:1080
#PROXY=192.168.1.1:8080
#SSLTUNNEL=192.168.1.1:8080
#
##==N [0-n] ---- -P --------------------------------- LISTENING CLIENTS
#@ -Pnnnn ... entrance ports for clients
#@ -Qnnnn ... an entrance port for clients
##---------------------------------------------------------------------
## - The entrance port(s) on which DeleGate listens and accepts
## connections from clients.
#
#-Q8080
#-Qlocalhost:8080
#-Q192.168.1.1:8080
#-Q8080/http
#-Q1080/socks
#
##==P [0-n] ---- SERVER ----------------- PROTOCOL OF CLIENT AND SERVER
#@ SERVER=protocol[://server[:port]] ... protocol with clients
##---------------------------------------------------------------------
## - The protocol in which DeleGate communicates with clients.
## - If a server is specified, DeleGate forwards its request to the
## server in the protocol with clients.
#
#SERVER=ftp
#SERVER=http
#SERVER=smtp
#SERVER=socks
#SERVER=http://host.domain
#SERVER=tcprelay://host.domain:22
#SERVER=udprelay://host.domain:53
#SERVER=tcprelay://odst.- # transparent proxy
#
##==P [0-n] ---- MOUNT -------------------- MAPPING VIRTUAL TO PHYSICAL
#@ MOUNT="vURL rURL mountOptions" ... serving as a server and a proxy
##---------------------------------------------------------------------
## - This is the central parameter to configure DeleGate as an
## application level origin/proxy server.
## - It maps a logical resource name in a request message from a client
## (like URL) to (more) physical one to access to a server.
## - Also it maps a physical name in a response message from a server
## to a logical name for a client.
## - It is applicable to HTTP, FTP, NNTP, SMTP and POP.
#
#MOUNT="/* file:data/www/*" # an HTTP origin server
#MOUNT="/abc/* http://def/ghi/* moved" # redirection
#MOUNT="/* http://server/* nvhost=xyz" # virtual hosting
#MOUNT="/xyz/* http://server/* # reverse proxy
#MOUNT="/xyz/* ftp://server/* # protocol translation
#MOUNT="/xyz/* sftp://server/* # protocol translation
#MOUNT="//xyz/* smtp://server/* # SMTP routing
#MOUNT="/-/ = AUTHORIZER=-list{adm:xyz} # access control
#MOUNT="/-/builtin/* data:builtin/* # customizing builtin data
#
##==N [0-n] ---- STLS ------------------------------------ SSL WRAPPING
#@ STLS={fsv,fcl}* ... inserting SSL filter
#@ CERTDIR=dirPath ... location of certificates
#@ TLSCONF=options ... configuration and debugging of SSL behavior
##---------------------------------------------------------------------
## - do TLS unconditionally, or on-demand by STARTTLS (or STLS)
## negotiation with client and server.
#
#STLS=fcl # wrapping communication with client by SSL
#STLS=-fcl # like fcl, but if explicit STARTTLS negotiation is done
#STLS=fsv # wrapping communication with server by SSL
#STLS=-fsv # like fsv, but if explicit STARTTLS negotiation is done
#
##==C [0-1] ---- END ------------------------ ENDING CONFIGURATION FILE
#@ END ... ending of a configuration file
##---------------------------------------------------------------------
END
Lines in a configuration file after "END" is ignored.
##--------------------------------------------------------------- ANNEX
#
##==C [0-1] ---- DGOPTS ------------ OPTIONS IN AN ENVIRONMENT VARIABLE
#@ DGOPTS="-opt1;-opt2;..." ... defining options in a parameter
##---------------------------------------------------------------------
## - This parameter is for giving options starting with "-" in a
## environment variable.
#DGOPTS="-Q8080;-r;-vd"
#
##==C [0-1] ---- -eNAME=VALUE ----------- DEFINING ENVIRONMENT VARIABLE
#@ -eNAME=VALUE ... setting environment variable
##---------------------------------------------------------------------
## - Defines an environment variable of name NAME with value VALUE to
## be used in DeleGate or its libraries.
#
#-eTZ=JST
#-ePATH=/usr/bin:/bin
##==C [0-1] ---- scripts ------------ CONFIGURATION BY SCRIPT LANGUAGES
To configure DeleGate reflecting the system environment or so, it
should be invoked by a script language, like /bin/sh for example.
It is recommended to define dynamic configuration in a script language,
static one in a configuration file, then load it by +=URL notation in
the script.
[console]
$ export LD_DEBUG=symbols
$ sh httpd.sh -fv
[httpd.sh]
#/bin/sh
. dgcommon.sh # include a shell script
DgExe=/path/of/delegated # path name of DeleGate executable
$DgExe -P80 +=dghttpd.conf $* # invoke a DeleGate
[dgcommon.sh]
#!/bin/sh
export MALLOC_CHECK_=2
if [ "$OS" = "Windows_NT" ]; then
export DGROOT=C:/DeleGate
else
export DGROOT=$HOME/delegate # this is the default on Unix
fi
[dghttpd.conf]
+=dgcommon.conf # load a configuration file
SERVER=http # speak HTTP with the client
HTTPCONF="max-ckapch:8" # limit the parallel connections to 8
HTTPCONF="methods:GET,POST" # allow only GET and PUT method
MOUNT="/* file:data/www/*" # map /* to DGROOT/data/www/*
RELAY=no # don't relay as a proxy server
[dgcommon.conf]
ADMIN=foo@bar.baz
RESOLV=cache,sys
##==C [0-1] ---- NAME="VALUE" ------------------------------- QUATATION
## - Quations for a parameter value is not necessary in a configuration
## file (except the MOUNT parameter).
## - But it is recommended to do so to be compatible with the
## notation in script languages so that it can be moved between script
## file and configuration file without modification.
#==C [0-1] ---- #!magic ---- CONFIGURATION FILE AS AN EXECUTABLE SCRIPT
On Unix or Cygwin, a configuration file can be used as an executable
script. To do so, the configuration file is needed to be with
executable flag set, and the file starts with a line as this:
#!/path/of/delegated +=
#######################################################################