yaws.conf設定マニュアル和訳

意訳です。修正歓迎。質問不可。→ しろいわ(shiroiwa3@gmail.com)
内容は保証できませんので、重要な設定を行う場合は必ず原文を確認してください。
原文はこちら

名称

/etc/yaws.conf - yawsサーバーの設定ファイル

概要

Yawsは速くて軽量なWebサーバーです。yaws.confでその動作の設定ができます。
設定は以下の2つパートからなります。
・全てのバーチャルホストに影響するグローバルな設定
・それぞれのバーチャルホスト用の設定

グローバルな設定

logdir = Directory(ディレクトリ)
全てのyawsログがこのディレクトリのファイルに書き込まれます。
いくつかの異なるログがあります。
report.log
yawsが吐き出した全てのエラーログ
Host.access
Common Log Formatによるバーチャルホストのアクセスログ
trace.http
HTTPのトレース(有効になっている場合)
auth.log
もし設定されていればhttp authのメッセージ
trace.traffic
トラフィックトレース(有効になっている場合)
logdirのデフォルトは "."
ebin_dir = Directory(ディレクトリ)
このディレクティブでerlangのサーチディレクトリを追加できます。
このコマンドは設定ファイルで複数記述できます。
id = String(文字列)
同一マシンで複数のyawsサーバーを走らせることができます。
idはそれぞれのyawsサーバーをコントロールするために使います。
例えば、
  # /usr/local/bin/yaws --id foobar --stop
  
idがfoobarのサーバーを止めます。
各yawsサーバーは、各内部データを$HOME/.yaws/yaws/ID(サーバーのid)に保持します。
yawsは ${VARDIR}/run/yaws/ctl-${ID} というファイルも作ります。
ここにはサーバーがコントロールコマンドのためにリッスンしているポート番号が含まれます。
include_dir = Directory(ディレクトリ)
このディレクティブでerlangコンパイラがインクルードファイルを探すディレクトリを追加できます。
これは我々のyawsのerlangコードに.hrlファイルを追加したくなった場合に必要です。
max_num_cached_files = Integer(整数)
yawsはよくアクセスされるGIF画像のような小さなファイルをメモリにキャッシュできます。
このディレクティブでキャッシュするファイル数を設定できます。
デフォルトは400です。
max_num_cached_bytes = Integer(整数)
キャッシュのためのメモリサイズを指定できます。
デフォルトは1000000。1メガバイトです。
(訳者注:これはサーバー一つあたりのサイズです。もし3サーバー定義していると、3MB必要になります)
max_size_cached_file = Integer(整数)
キャッシュされるファイルの最大サイズを指定できます。
デフォルトは8000。8キロバイトです。
cache_refresh_secs = Integer(整数)
キャッシュはcache_refresh_secsで設定された秒数存在します。
デフォルトは30です。
これはdocrootのコンテンツを更新しても30秒経過しないと、変わらないということです。
サイト構築中はこの値を0にしておくと便利でしょう。
yawsスタート時にデバッグフラグ(-d)をつけておくと、この値は自動で0になります。
trace = traffic | http
トラフィックまたはHTTPのトレースを有効にします。
yawsのコマンドラインフラグでも有効にできます。
auth_log = true | false
auth.logを有効または無効にできます。デフォルトは有効です。
log_wrap_size = Integer(整数)
yawsのログは全てラップログです。
オリジナルログがFile.oldにリネームされるのは1000000、1メガバイトです。
この値を設定できます。
tmpdir = Dir(ディレクトリ)
.yawsページを処理したときなど、動的コンテンツが処理された時に、ファイルが生成されます。
それらのファイルがtmpdirに保存されます。
デフォルトは $HOME/.yaws です。
log_resolve_hostname = Bool(trueかfalse)
デフォルトではクライアントホストのIPは(アクセスログで)解決されません。
fail_on_bind_err = Bool(trueかfalse)
リッスンしているソケットのbindに失敗した時に完全に失敗させるかどうか。
デフォルトはtrueです。
enable_soap = Bool(trueかfalse)
有効であればyaws起動時にSOAPサーバーが起動します。
デフォルトはfalseです。
php_exe_path = Path(パス)
PHPスクリプトを実行できるphp.exeへのパス。
デフォルトは php-cgi. です。
copy_error_log = true | false
エラーログのコピーを有効にするかどうか。 embeddedモードで走らせている時は、エラーログを記録するような他のシステムの処理がよくあるかもしれません。
しかし、通常のスタンドアロンモードで走らせている時は、report.logに書かれるerlangのエラーログが欲しいでしょう。
デフォルトはtrueです。
backwards_compat_parse = true | false
1.41よりも上のバージョンのyawsでは parse_query と parse_post 関数の返り値が変わりました。
以前のバージョンはキーが一意の {キー,値} を使っています。
これはDOS攻撃に対する弱点となります。
このフラグをセットすることは推奨されません。
1.41以降のキーは、list/stringです。
username = Username
実際yawsサーバーを運用する時は、rootでないユーザーで走らせるほうが安全だと思います。
この値を"nobody"のようなシステム権限の無いユーザーに設定してください。
yawsは初めに、権限の必要なポートを適切にリッスンするためにrootで走らせる必要があります。
pick_first_virthost_on_nomatch = true | false
yawsはリクエストを受けた時、IP/ポートが同一の全てのサーバーからバーチャルサーバーを選択するため、リクエストの Host: ヘッダーを参照します。
この設定は、その名前がマッチしなかった場合に、yawsが(yaws.confで設定された中から)最初のものを選択するかどうかを設定できます。
実際の運用においては、普通falseにしたいところですが、テスト・開発段階ではtrueにしたいものです。
use_fdsrv = true | false
rootで走らせていなくても、1024以下のポートにbindすることができます。
これには、fd_server と呼ばれる Jungerl パッケージが必要です。
この機能はSSLでは(まだ)動きません。
use_large_ssl_pool = true | false
デフォルトではSSLサーバーは許可処理のペンディングプールを持っています。
SSL接続はユーザーインタラクションを含んでいます。
ある人がサーバー証明書を見るかどうかのダイアログボックスを見ている時、
我々が複数のSSL許可処理を走らせない限り、他の人は新しい接続を確立できません。
このデフォルト値は8で、もし我々が設定できるなら50にします。
多くの低速接続者が除外される環境下であれば、この設定ができるのも納得できます。
subconfig = File(設定ファイル)
設定ファイルをロードします。
subconfigdir = Directory(ディレクトリ)
ディレクトリにある全ての設定ファイルをロードします。

バーチャルホスト設定

yawsは違うIPで複数のWebサーバーを運用するように、同じIPアドレスで複数のWebサーバーをホスティングできます。
SSL付きサーバーは個々のIPアドレスにつき、一つずつ可能という制限はあります。
それぞれのバーチャルホストは、<server ServerName> と </server> で定義されます。
ServerName はWebサーバーの名称です。

下記のディレクティブはserver定義内に記述することができます。

port = Port(ポート番号)
指定のポートをリッスンします。
listen = IpAddress(IPアドレス)
このIPをリッスンさせることができます。
同一IP/ポート上で複数のサーバーをホスティングする時、ブラウザが Host: フィールドを送信しないと、yawsは(この)設定ファイルに書かれた最初のサーバーを返すでしょう。
もしIPアドレスに 0.0.0.0 が記述されていたらyawsは記述されたポートで、全てのローカルIPアドレスをリッスンします。
rhost = Host[:Port]
サーバーによる内部リダイレクト先をHostにします。
これはユーザーが接続するポートではないポートをリッスンしている場合に有用です。
例えば、80番ポートは権限を持つユーザーによってのみ開かれるので、権限の無いユーザーではリッスンできません。
その代わりにyawsは、高いポート番号、8000番をリッスンし、iptablesが80番へのトラフィックを8000番へリダイレクトします。
(ほとんどのNATファイアウォールもこの仕組みを利用しています)
rscheme = http | https
サーバーによる内部リダイレクトが使うスキームを指定します。
これはyawsの前にSSL Offloaderやstunnelがある場合に有用です。
access_log = true | false
falseにすると、このバーチャルサーバーのトラフィックログを記録しません。
デフォルトはtrueです。
dir_listings = true | true_nozip | false
flaseにするとyawsによる自動ディレクトリ表示が許可されなくなります。
ステータスコード403が返されるでしょう。 true_nozipにすると、自動生成されたall.zipエントリを避けます。
deflate = true | false
サーバーのためのデフレート圧縮の有効・無効を設定します。
docroot = Directory ...
サーバーがDirectoryから全コンテンツを提供するようにします。
スペースで区切りのディレクトリリストを記述できます。
その場合、リクエストされたファイルのために、個々のディレクトリが順に検索されます。
これはssiやyssiを構成する時にも、ssi/yssiインクルードのファイルを探す場合に使われます。
partial_post_size = Integer
yawsが巨大ないくつかのPOSTを受ける場合に、それぞれのチャンクにおける受信総量を設定します。
デフォルトは10240です。
dav = true | false
このサーバーでDAVプロトコルを有効にします。
tilde_expand = true|false
falseを設定すると、チルダー拡張を行いません。
チルダー拡張とは
http://www.foo.com/~username
へのリクエストを、
~username/public_html/
をdocrootとするリクエストへ変換するメカニズムです。
デフォルトはfalseです。
allowed_scripts = [ListOfSuffixes]
許可するスクリプトタイプを指定します。
「yaws」「cgi」「php」が認識されます。
デフォルトは「allowed_scripts = yaws」です。
appmods = [ListOfModuleNames]
コンポーネントとしてListOfModuleNamesにある名前が、リクエストのパス中にある場合、パスリクエストのパースは終了し、そのモジュールが呼び出されます。
もし、内部のerlangモジュール名をURLパスの中にさらしたくなければ、appmodを記述するための両義的なシンタックスもあります。
以下のように書けます。
  appmods = <Path1, Module1> <Path2, Modules2> ...
  
このようにしたとすると、
http://www.hyber.org/myapp/foo/bar/baz?user=joe
このようなURLを使えます。
モジュールfooをappmodとして定義している間、foo:out(Arg)という関数が、foo以下のファイルを探す代わりに呼び出されます。
Arg引数は、そのappmodデータフィールドにおいて供給されていた失われたパス部分です。
errormod_404 = Module
404 Not Found メッセージを扱うモジュールを指定できます。
Module:out404(Arg, GC, SC) 関数が呼び出されます。
引数は、
Arg は #arg{} レコード、
GC は #gconf{} レコード (yaws.hrlで定義)
SC は #sconf{} レコード (yaws.hrlで定義)
関数は通常の out/1 が行うのと同じことができるし、するべきです。
errormod_crash = Module
サーバークラッシュメッセージのHTML生成を扱うモジュールを指定できます。
デフォルトでは整形済みクラッシュメッセージをブラウザに表示します。
これはデバッグでは有用ですが、実際の運用ではそうではありません。
Module:crashmsg(Arg, SC, Str)関数が呼ばれます。
Strは文字列として整形された実際のクラッシュメッセージです。
arg_rewrite_mod = Module
yawsサーバーの初期段階で、全てのArg #arg{} レコードを書き換えるモジュールをインストールすることができます。
これはCOOKIEのチェック、パスのリライト、その他様々なことに利用できます。
start_mod = Module
ユーザー定義のコールバックモジュールを定義できます。
サーバースタート時に、Module:start/1 が呼ばれます。
#sconf{} レコード(yaws.hrlで定義)が入力引数として利用されます。
これにより、ユーザーアプリケーションに、ユーザーの記述した設定データ(<opaque>コンテキストの説明を参照)の取得に加え、スタートアップをyawsサーバーと同期させることができます。
revproxy = Prefix Url
yawsサーバーをリバースプロキシーにできます。
Prefix は内部のdocrootパス、Url 引数はPrefixパスで「マウント」したいウェブサイトを指すURLです。
例:revproxy = /tmp/foo http://yaws.hyber.org
は、hyberのサイトを /tmp/foo のもとに表示させます。
同一サーバー内で複数のリバースプロキシを持つことが可能です。
警告:この機能はまだ製品レベルの品質ではありません。
servername = Name
いくつかのバーチャルホストを立てていて、Host: ヘッダーとマッチさせたい場合、このディレクティブによって行うことができるようになります。
この名前は特定のNATシナリオのもとでは、<server Name>の名前と同じである必要はありません。
滅多に使われない機能です。
<ssl> .... </ssl>
このサーバーにおけるSSL設定の始まりと終わりを示します。
keyfile = File
証明に使われるプライベートキーを含むファイルを指定します。
certfile = File
サーバー証明書を含むファイルを指定します。
cacertfile
サーバーがクライアント証明書を必要とするセットアップであれば、ファイルを。
このファイルは、クライアント証明のための許可可能なサイン者の全ての証明書を含んでいる必要があります。
verify = 1 | 2 | 3
クライアント証明におけるサーバーの検証レベルを指定します。
1・・何もしない
2・・クライアントへ問い合わせるがクライアントが証明を提示しなくても失敗しない
3・・クライアントの証明を求める
depth = Int
クライアント証明の検証時に、サーバーがフォローできる証明書チェインの深さを指定します。
password = String
プライベートキーがディスクに暗号化されている場合には、文字列。
このpasswordは複合化するための3DESキーです。
ciphers = String
SSL Cipher文字列を指定します。
SSL Cipher文字列のシンタックスは、それ自身が多少複雑なサブランケージ(sublanguage)です。
SSLマニュアルの"ciphers"でドキュメント化されています。
</ssl>
SSL定義の終わりです。
<redirect> ... </redirect>
リダイレクトマッピングを記述します。
続く項目は <redirect> </redirect> 内で許可されています。
Path = [Scheme://]Host[:Port]
Path への全てのアクセスが、
[Scheme://]Host[:Port]Path へリダイレクトされます。
Scheme と Port はオプションです。
デフォルトでは、rsheme と rport が(もし定義されていれば)使用されます。
サイトへの全ての参照をリダイレクトする場合は、"/" をPathに指定します。
<auth> ... </auth>
認証構造を定義します。
続く項目は <auth> </auth> 内で許可されています。
dir = Dir
WWW-authenticateヘッダーで制御されるディレクトリを指定します。
このディレクトリにアクセスするにはユーザーはパスワードを入力する必要があります。
ディレクトリはdocroot内でなければなりません。
realm = Realm
ここで定義したディレクトリ内における、WWW-AuthenticateのRealmを指定できます。
authmod = AuthMod
認証モジュールが定義されていれば、そのディレクトリのアクセス時にAuthMod:auth(Arg, Auth) が呼び出されます。
auth/2 関数は true、false、{false, realm}、{appmod, Mod}、のうち一つを返さなければなりません。
{appmod, Mod} が返された場合、Mod:out(Arg) の呼び出しがコンテンツの配信に使われます。
これは例えば、COOKIEによる認証の実装に利用できます。
auth()コールバックは、適切なCOOKIEヘッダーがあるかどうかチェックし、無ければ、{appmod, ?MODULE}を返し、同モジュール内の out/1 関数は {redirect_local, "/login.html"} を返します。
user = User:Password
このディレクトリ内では、User は ブラウザに表示されるポップアップダイアログで Password を入力することでアクセスすることができます。
このディレクティブは一つの<auth> </auth>内で複数記述できます。
実際の設定で、User:Password の使い方は1.51をリリースした時に非難されました。
むしろ、そのディレクトリに .yaws_auth ファイルを置いたほうが良いのです。
.yaws_auth ファイルは file:consult/1 によってパースされうるファイルです。
ファイルの各行は以下のような項が含まれます。
  {User, Password}.
  
User、Password、共に文字列です。
.yaws_auth ファイル方式は(まだ)再帰的ではありません。
従って、サブディレクトリは自動的には保護されません。
.yaws_auth ファイルはディレクトリリスト内には表示されません。
pam service = pam-service
pamが認証構造の一部である場合、Yawsは pam service で示された"pam"を使って認証を試みます。
多くのサービスは /etc/pam.d 以下にあります。
大抵の値は "system-auth" などです。
pam認証はErlangポートプログラムによって実行されます。
このプログラムは普通、yawsのインストールプログラムによって、suid rootとしてインストールされます。
</auth>
auth定義の終わりです。
<opaque> .... </opaque>
このサーバーに対するOpaqueの設定をします。
「Key = Value」のディレクティブを記述できます。
これらのディレクティブはyawsには無視されます(なのでOpaque(不透明)と言う)が、これらは、#sconf.opaque レコードに {Key,Value}タプルのリストとして保持され、アクセスできます。
start_mod ディレクティブも参照してください。
この仕組みは各 .yaws ページに関連するアプリケーションへデータを渡すのに利用されます。

設定サンプル

下記の例は、80番ポートをリッスンする一つのサーバーを定義します。

       logdir = /var/log/yaws
       <server www.mydomain.org>
               port = 80
               listen = 192.168.128.31
               docroot = /var/yaws/www
       </server>

そして、この例は上のと似ていますが、同一IPで二つのサーバーを定義しています。

       logdir = /var/log/yaws
       <server www.mydomain.org>
               port = 80
               listen = 192.168.128.31
               docroot = /var/yaws/www
       </server>

       <server www.funky.org>
               port = 80
               listen = 192.168.128.31
               docroot = /var/yaws/www_funky_org
       </server>

この例は WWW認証をして、アクセスログを取りません。

       logdir = /var/log/yaws
       <server www.mydomain.org>
               port = 80
               listen = 192.168.128.31
               docroot = /var/yaws/www
               access_log = false
               <auth>
                   dir = secret/dir1
                   realm = foobar
                   user = jonny:verysecretpwd
                   user = benny:thequestion
                   user = ronny:havinganamethatendswithy
              </auth>

       </server>

この例では、ユーザー設定に加え、最初にユーザー定義のモジュールを呼び出します。

       <server www.funky.org>
               port = 80
               listen = 192.168.128.31
               docroot = /var/yaws/www_funky_org
            start_mod = btt
            <opaque>
                 mydbdir = /tmp
                 mylogdir = /tmp/log
            </opaque>
       </server>

最後に、同一IPで二つのサーバーを立て、別のIPでSSLサーバーを立てる、という少し複雑な例です。
同一IPで一つ以上のサーバーがあり、それぞれ異なった名前を持つ場合、クライアントが Host: ヘッダーを送信しない場合に、それらのうちから一つ選べるようにしなければなりません。
yawsはconfファイルで定義された一番最初のものを選ぶでしょう。

       logdir = /var/log/yaws
       max_num_cached_files = 8000
       max_num_cached_bytes = 6000000

       <server www.mydomain.org>
               port = 80
               listen = 192.168.128.31
               docroot = /var/yaws/www
       </server>

       <server www.funky.org>
               port = 80
               listen = 192.168.128.31
               docroot = /var/yaws/www_funky_org
       </server>

       <server www.funky.org>
               port = 443
               listen = 192.168.128.32
               docroot = /var/yaws/www_funky_org
               <ssl>
                  keyfile = /etc/funky.key
                  certfile = /etc/funky.cert
                  password = gazonk
               </ssl>
       </server>

著作者

Claes Wikstrom

参照

yaws(1) erl(1)