BayServerリファレンス

ドッカー識別子とパラメータ

ドッカー識別子

ドッカーの宣言に付加される文字列をドッカー識別子と言います。

例：

    [port 2020]
    [city host.baykit.yokohama]

ここでは「2020」「host.baykit.yokohama」がドッカー識別子になります。ドッカーには識別子を省略できるものもあります。

パラメータの型

パラメータ値の型はパラメータによって異なります。パラメータの型には以下の種類があります

• 文字列型
• 数値型
• 論理値型
• パス型
• サイズ型

論理値型

論理値型の値は次のように指定します。値が真であることを表すためには true/yes/on/1 のいずれを指定します。次はいずれも同じ意味です

    traceHeader true
    traceHeader yes
    traceHeader on
    traceHeader 1

値が偽であることを表すためには false/no/off/0 のいずれかを指定します。次はいずれも同じ意味です。

    traceHeader false
    traceHeader no
    traceHeader off
    traceHeader 0

パス型

パス型は、文字列型の一種ですが、ファイルシステム上のパスを指定する型です。

     location  /var/www/html

相対パスを指定した場合はBayServerホームからの相対パスとみなされます。

     location www/html

サイズ型

サイズ型は、サイズを指定します。サイズはバイト、キロバイト、メガバイトで指定します。

      tourBufferSize  1024B
      tourBufferSize  1024KB
      tourByfferSize  1024MB

大文字小文字の違いは無視されます。また最後のBは省略可能です。つまり以下の指定も有効です。

     tourBufferSize 1024
     tourBufferSize 1024k
     tourBufferSize 1024m

マルチプレクサ・タイプ指定

Version3より、ネットワークやファイルのI/Oを多重化するための方式(マルチプレクサ・タイプ)を選択できるようになりました。用意されている値は以下です。

ただし、通常は処理系で最適な値がデフォルト値として設定されているため、マルチプレクサ・タイプの設定は不要です。

sensor

select/epoll/kqueueなどの非ブロッキングAPIを使用して多重化をします。通常、非ブロッキングAPIはネットーワークI/Oに最適化されており、またスレッドの切り替えが発生しないため高速な動作が期待できます。

センサーを仕掛けてI/Oが行えるソケットをキャッチするイメージからこの名前がついています

job

I/Oを行う際にスレッドやゴルーチンを起動することで多重化を実現します。OSのスレッドを使用する場合はスレッドの切り替えによるオーバーヘッドが生じますが、ゴルーチンのようにOSに頼らない強力なスケジューリング機能がある場合は切り替えによるオーバーヘッドはほとんど発生しません。

それぞれが小さな仕事(job)を行うことからこの名前がついています

pigeon

イベントAPIを使用することで多重化を実現します。一般的に、非ブロッキングAPIはネットワークI/Oに最適化されており、ファイルI/Oに関しては効率的ではありません。ファイルI/Oを多重化する際はイベントAPIを使用するのが効率が良いとされています。

I/Oが完了した場合に伝書鳩(pigeon)が伝えてくれるイメージからこの名前がついています

spin

無限ループ内で、ブロックせずにI/Oを試みることで多重化を実現します。この方式はCPUリソースを消費するためお勧めはしませんが、ファイルI/Oが高速な場合は空振りする可能性が低く効率がよいかもしれません。また、ファイルI/Oの多重化のためのAPIが用意されていない処理系の場合はこの方式を選ぶことになります。

なお、I/Oを行うファイルがない場合はループは停止しています。

無限ループ内でくるくる回っていることからこの名前がついています。

taxi

BayServerで用意されているTaxiの仕組みを用いて多重化を実現します。スレッドやゴルーチンを使用するためjobと似ていますが、一度に実行可能なタスク数(Taxi数)に制限があるところが異なります。

train

BayServerで用意されているTrainの仕組みを用いて多重化を実現します。スレッドやゴルーチンを使用するためjobと似ていますが、一度に実行可能なタスク数(Train数)に制限があるところが異なります。

valve

TypeScriptのネットワーク通信のようにイベントドリブン方式で多重化を実現します。イベントAPIを使用するpigeonと似ていますが次のような違いがあります。pigeonすなわちイベントAPIの場合は明示的なreadの呼び出しに対する完了のイベントが発火しますが、valveの場合は一方的に読み込みのイベントが発生します。

水道の蛇口のように、開け閉めをしてコントロールするところからこの名前がついています。

Harborドッカー

Harborドッカーは港湾全体に関するパラメータを設定します。Harborドッカーに識別子はありません。

例：

[harbor]
    logLevel debug
    timeout  30

Harborドッカーのパラメータ

logLevel

ログレベルを指定します。

例：

     logLevel trace

指定できる値は trace/debug/info/warn/error/fatal。デフォルトはinfo

charset

ファイルシステム上の静的なコンテンツを送信する際、content-typeが「text/なんちゃら」でかつcharsetが指定されていなかったときに自動的にキャラクタセットを付加します。デフォルトはシステムから取得した値で、実装言語やOSに依存します。つまり、環境変数やJavaのシステムプロパティなどです。それでも決定できない場合はキャラクタセットは付加されません。

日本語のファイルを送信する場合は必ず指定してください。

例：

     charset UTF-8

charsetはCityドッカーやClubドッカーでも指定可能です

locale

ロケールを指定します。ロケールはエラーメッセージなどの出力に用いられる言語を決定するために必要で、「{言語名}-{国名}」または「{言語名}_{国名}」の形式で指定します。デフォルトはシステムから取得します。この値は実装言語やプラットフォームに依存します。すなわち環境変数やJavaのシステムプロパティなどから取得します。それでも取得できない場合は「en_US」が指定されます。

例：

    locale ja_JP

（対象となるメッセージファイルは lib/conf ディレクトリに存在します。）

groups

グループファイルをパス型の値で指定します。

グループファイルはPermissionドッカーによって使用され、Basic認証を用いたユーザー認証を行うためのファイルです

例：

    groups plan/mygroup.plan

グループファイルのフォーマットはこちらを参照してください。

grandAgents

GrandAgentの数を指定します。GrandAgentはBayServerの最も重要なコンポーネントで、船舶の到着から出発までの間、あらゆるケアを行います。

GrandAgentはBayServerの中核となるスレッドで、各CPUコアに1つずつ張り付いた場合に最も効率よく動作するように設計されています。従ってこの数がCPUコア数と同じ場合、最大のパフォーマンスを発揮することが期待できます。

例：

     grandAgents 8

デフォルトは4です。

マルチコアモードがサポートされていない環境では、理屈の上ではこの値は1にするべきですが、グランドエージェントがハングするリスクを考え、2以上の値を設定した方がよいでしょう。

netMultiplexer (バージョン3.0以上）

ネットワーク通信に関するI/O多重化の方法を、マルチプレクサ・タイプで指定します。

各言語で指定できる値は以下の通りです

	OS	spider	job	pigeon	valve
Java版	Unix系	○	○	○	×
	Windows	○	○	○	×
PHP版	Unix系
	Windows
Python版	Unix系
	Windows
Ruby版	Unix系	○	○	×	×
	Windows	○	○	×	×
TypeScript版	Unix系	×	×	×	○
	Windows	×	×	×	○
Go版	Unix系	×	○	×	×
	Windows	×	○	×	×

fileMultiplexer (バージョン3.0以上）

ファイルを読み出す際のI/O多重化の方法を、マルチプレクサ・タイプで指定します。

各言語で指定できる値は以下の通りです

	OS	spider	job	pigeon	taxi	spin
Java版	Unix系	×	○	○	○	○
	Windows	×	○	○	○	○
PHP版	Unix系
	Windows
Python版	Unix系
	Windows
Ruby版	Unix系	○	○	×	×	○
	Windows	○	○	×	×	○
TypeScript版	Unix系	×	×	○	×	×
	Windows	×	×	○	×	×
Go版	Unix系	×	○	×	×	×
	Windows	×	○	×	×	×

logMultiplexer (バージョン3.0以上）

ログをファイルに書き出す際のI/O多重化の方法を、マルチプレクサ・タイプで指定します。

各言語で指定できる値は以下の通りです

	OS	spider	job	pigeon	taxi	spin
Java版	Unix系	×	○	○	○	×
	Windows	×	○	○	○	×
PHP版	Unix系
	Windows
Python版	Unix系
	Windows
Ruby版	Unix系	○	○	×	○	×
	Windows	○	○	×	○	×
TypeScript版	Unix系	×	×	×	○	×
	Windows	×	×	×	○	×
Go版	Unix系	×	○	×	×	×
	Windows	×	○	×	×	×

cgiMultiplexer (バージョン3.0以上）

CGIプロセスと通信を行う際のI/O多重化の方法を、マルチプレクサ・タイプで指定します。

各言語で指定できる値は以下の通りです

	OS	spider	job	pigeon	taxi	train	spin	valve
Java版	Unix系	×	○	×	○	○	○	×
	Windows	×	○	×	○	○	○	×
PHP版	Unix系
	Windows
Python版	Unix系
	Windows
Ruby版	Unix系	○	○	×	○	○	○	×
	Windows	○	○	×	○	○	○	×
TypeScript版	Unix系	×	×	×	×	×	×	○
	Windows	×	×	×	×	×	×	○
Go版	Unix系	×	○	×	×	×	×	×
	Windows	×	○	×	×	×	×	×

trains

このパラメータはバージョン2.1よりtrainRunnersに変更になります。

同時に走らせられるTrainの数を指定します。Train(列車)は観光客をツアーとして目的地に連れて行き、また連れて返ります。

TrainはBayServer上の常駐スレッドで、ツアーとは1回分のリクエストに相当します。

ツアーには、同期型と非同期型がありますが、Trainで行くツアーは同期型のツアーです。同期型ツアーの例を示します。

• CGIスクリプト(実装言語によっては非同期)
• Servletアプリケーション
• Rackアプリケーション(Ruby on Rainsなど)
• WSGIアプリケーション(Djangoなど)

（「Train」という名は、「Railsアプリケーションを動かすためのプラットフォーム」であることに由来しています！）

例：

    trains 16

なぜ同期型ツアーをわざわざ別のスレッドで動かす必要があるのでしょうか？

それは、同期型ツアーをGrandAgent上で動かしてしまうと、処理が終わるまでブロックしてしまい、同時に他のツアーを実行できないからです。このようなツアーはバックグラウンドで実行する必要があるのです。

Trainを増やせば同時に処理できるツアーの数は増えますが、CPUコアには限りがあるため、増やせる数には限界があります。これはCPUコアを線路に例えると良いでしょう。列車を増やせば増やすほど同時に開催できるツアーは増やせますが、増やしすぎると線路が詰まって渋滞してしまいます。

一般的には、I/Oの多いWebアプリケーションならばTrain数を増やせますが、I/Oが少なく計算量の多いWebアプリケーションの場合はTrain数を増やしても意味がありません。

また、Trainは各プロセスごと指定した数だけ準備されます。従って、BayServer全体としていくつのTrainが存在するかは環境に依存します。

Java版の場合、BayServerはプロセスを1つしか使用しないため、BayServer全体でTrainを共有します。

Python/Ruby版の場合、multiCoreパラメータがonの場合は grandAgents × trains だけのTrainが準備されます。なぜなら各GrandAgentは異なるプロセスとして実行されるからです。multiCoreパラメータがoffの場合はBayServer全体でtrainsに指定した数のTrainが存在します。

なお、以下のツアーは非同期型なのでTrainは使用されません

• 静的ファイルの送信
• 別のサーバーへのワープ（プロキシ）

また、PHPはマルチスレッド化が難しいため、Trainは使用できません。

taxis or taxies

このパラメータはバージョン2.1よりtaxiRunnersに変更になります。

同時に走ることのできるTaxiの数を指定します。Taxi(タクシー)はTrainと比べると、1回の移動で短い距離を移動します。具体的には1回分のファイルI/Oなど比較的小さな仕事を行う常駐スレッドです。

Taxiは静的ファイルを送信する際やアクセスログを書き込む際に使用されます。

デフォルトは8です。

例：

    taxis 16

Taxiが必要な理由はTrainの場合と同じです。

つまり、ファイルI/OをGrandAgentの仕事としてしまうと、HDDからの読み込みやHDDへの書き込みが終わるまでブロックされ、その間他の処理を行うことができなくなります。このことは同時アクセス数が増えてきた場合のパフォーマンスに重大な影響を与えます。C10Kを実現するためにはファイルI/Oはバックグラウンドで行う必要があるのです。

Taxiの数を増やせばI/Oの多重度を増やせますが、増やしすぎるとI/Oが詰まりパフォーマンスが悪くなる原因にもなるので注意してください。

taxisで指定する値はプロセス内のTaxiの数です。BayServer全体でのTaxiの総数はプロセス数に存在します。詳細はtrainsパラメータの解説を参照してください。

maxShips

1つのGrandAgentが扱える外国舶の最大値を指定します。具体的にはクライアントから同時に接続できるTCPコネクションの数を指定します。この数を超えた接続は待機されます。最小値は1024です(Ruby版は128)。

    maxShips 10000

この数に指定できる値はプラットフォームの制限を受ける場合があります。

Ruby版BayServerでは、1つのGrandAgentが同時に扱えるソケットは1024までです。これはrubyのselect関数が最大1024個のソケットしか扱えないという制限からです。またこの1024という数には、Listenポートやプロキシに使用されるソケットも含まれます。つまり、Ruby版BayServerの場合はmaxShipsの値を、設計状況に応じた小さな値を設定しなければなりません。目安としては、プロキシ機能を使う場合は500、使わない場合は1000を指定しておくとよいでしょう。

なお、Ruby版BayServerで同時接続数をもっと増やしたい場合は、grandAgentsの値を増やすと良いでしょう。

timeout

ソケットのタイムアウトを指定します。ソケットへのI/Oがこの時間を超えても応答がない場合、タイムアウトが発生します。

例：

    timeout 30

デフォルトは120（秒）です。

keepTimeout

KeepAliveのタイムアウトを指定します。

例：

    keepTimeout 10

keepTimeoutにtimeoutよりも大きな値を設定するのは意味がありません。

tourBufferSize

ツアーバッファ（1回のツアーでの要求および応答をキャッシュする内部バッファ）のサイズをサイズ型で指定します。

例：

    tourBufferSize  256MB

ツアーバッファは、スロークライアント、スローアプリケーション対策のために用意されています。

POSTされたデータをアプリケーションが読み込まずツアーバッファが一杯になった場合、POSTデータの読み込みは中断します。その後アプリケーションがデータを読み込んだらその分だけクライアントからPOSTデータを読み込みます。

また、アプリケーションからの応答データをクライアントが読み込まずツアーバッファが一杯になった場合、アプリケーションの出力は中断します。その後クライアントが応答データを読み込んだらその分だけアプリケーションは出力を再開できます。

traceHeader

HTTPヘッダなどリクエストの情報を出力するかどうかを論理値で指定します。デフォルトはoffです。

例：

    traceHeader on

traceHeaderを有効にすると、以下の情報が出力されます

• リクエストヘッダ情報
• レスポンスヘッダ情報
• CGI環境変数
• CGIの応答ヘッダ
• プロキシサーバーへのリクエストヘッダ情報
• プロキシサーバーからのレスポンスヘッダ情報

これらはINFOレベルで標準出力に出力されます。

redirectFile

標準出力・標準エラー出力に出力されるログをリダイレクトするためのファイル名をパス型で指定します。

例：

    redirectFile  logs/bserv.log

controlPort

制御コマンドを受信するためのポート番号を指定します。起動や停止などの制御コマンドは通常、BayServerへシグナルを送信することで送信されます。しかし、Windowsのように十分なシグナル送受信環境が整っていない場合、代わりにcontrolPortを開きます。

例：

    controlPort  2022

multiCore

BayServerをマルチコアで動かすことで、リクエストを並列に処理することができ、最大のパフォーマンスを引き出すことができます。このパラメータは、BayServerをマルチコアモードで動作させるかどうかを論理値型で指定します。デフォルトはonです。

例：

    multiCore off

マルチコアモードを実現する手段がマルチスレッドなのかマルチプロセスなのかは実装言語やプラットフォームによって異なります。

	OS	マルチコアモード	シングルコアモード
Java版	Unix系	マルチスレッド	N/A
	Windows	マルチスレッド	N/A
PHP版	Unix系	マルチプロセス	シングルスレッド
	Windows	N/A	N/A
Python版	Unix系	マルチプロセス	マルチスレッド
	Windows	N/A	マルチスレッド
Ruby版	Unix系	マルチプロセス	マルチスレッド
	Windows	N/A	マルチスレッド
TypeScript版	Unix系	マルチプロセス	シングルスレッド
	Windows	マルチプロセス	シングルスレッド
Go版	Unix系	Goルーチン	Goルーチン
	Windows	Goルーチン	Goルーチン

Java VMはスレッドをシングルコアで動かすことができないため、マルチコアモード一択です。

RubyおよびPythonインタプリタはGILが存在するため、マルチスレッドプログラムはシングルコアで動作します（いわゆる「並行処理」ってやつ）。これを回避するため、fork() APIを使用してマルチプロセス化し、それぞれのプロセスが別コアで動作するようにしています。

ただし、Windows版RubyおよびPythonはfork() APIがサポートされていないため、マルチコアで動作させることはできません。（MinGWやCygwin版Ruby/Pythonの場合は動作する可能性があるが未確認）

なお、マルチコアモードで動作させても、最終的にCPUコアへの配置はOSが行うため、確実にマルチコアで動く保証はないことに注意してください。

PHPはWindows上での動作はサポートされません。（MinGWやCygwin版PHPの場合は動作する可能性があるが未確認）

Goでは、スケジュール管理はOSではなくGoの処理系が行います。

gzipComp

コンテンツをgzip圧縮するかどうかを論理値で指定します。デフォルトはoffです。

例：

    gzipComp on

このパラメータがonでかつ、テキスト系のコンテンツの場合にはgzip圧縮をして送信されます。

enableCache（バージョン3.1以降）

ファイルキャッシュを有効にするかどうかを論理値で指定します。デフォルトはoffです。

例：

    enableCache on

cacheLifespan（バージョン3.1以降）

キャッシュの存在期間（秒）を指定します。この期間を超えたファイルは自動的にメモリから消去されます。デフォルトは60です。

例：

    enableLifeSpan 300

cacheSize（バージョン3.1以降）

キャッシュのサイズ（MB）を指定します。このサイズを超えるファイルはキャッシュされません。また、ファイルをキャッシュすることでこのサイズを超えてしまう場合は、キャッシュ内のコンテンツは、アクセス時間の古いものからevictされます。デフォルトは32です。

例：

    enableSize 128

sendFileMethod (バージョン 2.X)

静的ファイルを送信する際の読み込みの方法を指定します。指定できる値は select/spin/taxi で、デフォルトはtaxiです。

例：

    sendFileMethod select

ファイルの読み込みがブロックされるとパフォーマンスに大きな影響を与えてしまいます。そこでBayServerではいくつかの方法でこれを回避します。

selectはノンブロッキングAPI、すなわちセレクタを使用することで、読み込みが可能になって初めてファイルを読み込みます。

spinは、ノンブロッキングモードで read() APIを呼び出します。読み込みが行えなくても呼び出しはブロックしません。このモードではファイルI/Oが完了するまでスピンするため、CPUに負荷がかかる恐れがあります。

taxiは、ファイルI/OをTaxi（ファイルI/O専用のスレッド）で行います。Taxiとは小さな処理を行う常駐スレッドのことです。ちょこっと乗って別のところに行き、またちょこっと乗ってまた別のところに行く、すなわちちょっとずつファイルを読み込むイメージです。つまり、バックグラウンドでファイルの読み込みを行います。

どの方法が使用できるかは、実装言語やプラットフォームに依存します。

	OS	select	spin	taxi
Java版	Unix系	N/A	〇	〇
	Windows	N/A	〇	〇
PHP版	Unix系	〇	〇	N/A
	Windows	N/A	N/A	N/A
Python版	Unix系	〇	〇	〇
	Windows	N/A	N/A	〇
Ruby版	Unix系	N/A	〇	〇
	Windows	〇	〇	〇

JVMのセレクタはファイルI/Oに対応していないためselectを指定できません。

Ruby/Pythonインタプリタは、Windowsではファイルのselectおよびノンブロッキング読み込みはサポートされないため、taxi一択です。（MinGWやCygwinでは動作するかもしれませんが未確認）

PHP版はWindowsではサポートされません。（MinGWやCygwinでは動作するかもしれませんが未確認）また、PHPでマルチスレッドプログラムは難しいため、Taxiは動作しません。

Portドッカー

Portドッカーは、外国船を入港させるためのドッカーです。ここでいう外国船とは外部からのTCP接続のことです。

Portドッカーの識別子は、（OS上の）ポート番号です。

[port 2020]
    docker ajp

なお、次のようにすることで、ポートを開くIPアドレスを指定できます。

[port 127.0.0.1:2020]

UNIXドメインソケットを使用する場合は以下のように指定します。

[port :unix:/tmp/hoge]

HTTP/3使用時、udpポートで待ち受ける場合は以下のように指定します。

[port :udp:2024]

実は最初の2020番ポートの例は、以下のような指定の省略形となっています。

[port :tcp:0.0.0.0:2020]

Portドッカーにはhttp/ajp/fcgiの3種類のドッカーが存在します。Portドッカーの種類はdockerパラメータで指定します。

Portドッカーのパラメータ

timeout

このポートに関するソケットのタイムアウトを秒数で指定します。デフォルトはharborドッカーのtimout値です

例：

    timeout 120

docker

portドッカーの種類を指定します。指定可能な値はhttp/ajp/fcgiです。デフォルトはhttpです。

対応するプロトコルは以下です。

プロトコル	値	使用されるドッカー
HTTP 1.1	http	http portドッカー
HTTP/2	http	http portドッカー
AJP(Apache JServ Protocol)	ajp	ajp portドッカー
FCGI(Fast CGI)	fcgi	fcgi portドッカー
HTTP/3	h3	h3 portドッカー(Java/Python版のみ)

例：

    docker ajp

HTTP Portドッカー

HTTP PortドッカーはHTTPプロトコルをサポートするPortドッカーです。

Http Portドッカーのパラメータ

supportH2 or enableH2

HTTP2を有効にするかを論理値で指定します。デフォルトはonです。

例：

    supportH2 off

AJP Portドッカー

AJP PortドッカーはAJPプロトコルをサポートするPortドッカーです。固有のパラメータはありません

FCGI Portドッカー

FCGI PortドッカーはFCGIプロトコルをサポートするPortドッカーです。固有のパラメータはありません

Cityドッカー

Cityは観光客の行先の都市、具体的には仮想ホストを表します。CityドッカーはCityを管理します。

クライアントは行きたい都市を仮想ホストで指定します。例えば次のようなURLの場合、行きたい都市は「www.baykit.yokohama」となります。

http://www.baykit.yokohama/pub/index.html

都市名はCityドッカーの識別子として指定します。

[city www.baykit.yokohama]

都市名は完全一致です。すなわちサブネットを使用する場合はサブネットごとにCityドッカーを準備する必要があります。

行きたい都市がどのCityドッカーの識別子と一致しなかった場合の特殊な書き方として、識別子に「*」を指定できます。

[city *]

Cityドッカーに固有のパラメータはありません。

通常、Cityドッカーはトップレベル（どのドッカーの配下にもない状態）に配置しますが、Portドッカーの下に配置することもできます。この場合は、そのポートへのアクセス時のみ有効な設定となります。例えば、HTTP/3を使用する場合は、CityドッカーをPortドッカーの下に配置しなければなりません。

[port :udp:2024]
    docker h3

    [secure]
       cert cert/quicui.crt
       key cert/quicui.key

    [city *]
        [town /]

        [club *]
            docker httpWarp
            destCity :unix:/tmp/hoge
            destTown /

Townドッカー

Townは観光客の行きたい町、具体的には仮想パス（URLのホスト名以降のパスの部分）の一部を表します。TownドッカーはTownを管理します。

TownドッカーはCityドッカーに属し、識別子は仮想パスの一部です。

[city www.baykit.yokohama]
    [town /documents]

この場合、http://www.baykit.yokohama/documents/ で始まるURLはすべてこのTownとみなされます。

（最後のスラッシュがない場合はスラッシュを付加したURLにリダイレクトされます。）

Townの識別子の最初のスラッシュは省略できます。

    [town documents]

URLからTownを推測する際、マッチするTownが複数ある場合、Town名が長い方を優先します。例えばリクエストされたURLが http://www.baykit.yokohama/documents/install/index.html で、以下の2つの設定があった場合は /documents/install にマッチします。

    [town /documents]
    
    [town /documents/install]

また、どのTownにもマッチしなかった場合の特別な書き方として「*」を指定可能です。

    [town *]

Townドッカーのパラメータ

location

このTownドッカーが扱うディレクトリをパス型で指定します。静的ファイルを扱わないアプリケーションの場合は指定しなくても構いません。

例：

    location /var/www/html

welcome

ディレクトリをリクエストされた場合に、このファイルが存在すればそれを表示します。

例：

    welcome  index.php

index

welcomeと同じです。

例：

    index index.php

Clubドッカー

Clubは、観光客が行き先で何をしたいのかを表します。何をしたいのかはTown以降の行き先によって判定されます。例えば拡張子であったり、特定のパスだったりします。ClubドッカーはClubを管理します。

例えば拡張子がphpであるURLをひとまとまりのClubとして扱うためには以下のように指定します。

    [club *.php]

Town以降のパスが「api/list」に一致するClubを定義するには以下のように指定します。

    [club api/list」

（なお、部分一致を定義することはできません。）

全てのClubにマッチしなかった場合の特殊な書き方として「*」を指定できます。

    [club *]

ClubドッカーはCityまたはTown内で定義できます。始めにTown内でマッチするClubを検索し、見つからなければCity内でマッチするClubを検索します。それでも見つからなければOS上のファイルが送信されます。（それでも見つからなければ404 Not Foundが返されます）

Clubドッカーにはいくつか種類があります。

ドッカーの種類	dockerパラメータ値	説明
Fileドッカー	file	OS上のファイルを返すドッカー（デフォルト）
CGIドッカー	cgi	CGIスクリプトを実行するためのドッカー
PHPドッカー	phpCgi	PHPアプリケーションを実行するためのドッカー
HTTP Warpドッカー	httpWarp	HTTPワープ、すなわちバックエンドのサーバーとHTTPプロトコルで通信するプロキシとして機能させるためのドッカー
AJP Warpドッカー	ajpWarp	AJPワープ、すなわちバックエンドのサーバーとAJPプロトコルで通信するプロキシとして機能させるためのドッカー
FCGI Warpドッカー	fcgiWarp	FCGIワープ、すなわちバックエンドのサーバーとFCGIプロトコルで通信するプロキシとして機能させるためのドッカー
Servletドッカー	servlet	サーブレットアプリケーションを実行します。(Java版のみ)
Terminalドッカー	terminal	Ruby on RailsなどのRackアプリケーションを実行します。(Ruby版のみ)
Banjoドッカー	banjo	DjangoなどのWSGIアプリケーションを実行します。(Python版のみ)

Clubドッカーのパラメータ

decodePathInfo

URLエンコードされたPATH_INFOをデコードするかどうかを論理値で指定します。デフォルトはonです。

    decodePathInfo  off

charset

このClubが使用するキャラクタセットを指定します。デフォルトはharborドッカーで指定した値です。

    charset EUC-JP

docker

clubドッカーの種類を指定します。デフォルトはfileです。

    docker servlet

Fileドッカー

Fileドッカーはファイルシステム上のファイルを返すドッカーです。

固有のパラメータはありません。

CGIドッカー

CGIドッカーはCGIプログラムを実行するためのドッカーです。CGIアプリケーションは通常、特定の拡張子のファイルへのリクエストに対しCGIプログラムを起動します。例えばplという拡張子のファイルをリクエストされた場合、そのファイルを実行するには次のように指定します。

    [club *.pl]
       docker cgi

このような指定を行う場合、リクエストされたplファイルは実行可能でなければなりません。指定したファイルがそのOSで実行可能でない場合や、特定のインタプリタの引数としてファイルが指定される場合はinterpreterパラメータを使用します。

CGIドッカーのパラメータ

interpreter

リクエストされたファイルを特定のインタプリタで実行する場合、実行するインタプリタを指定します。

    interpreter /usr/bin/perl

scriptBase

SCRIPT_BASE環境を決定する際のヒントとなるベースディレクトリを指定します。デフォルトはこのClubドッカーが呼び出された際のTownドッカーのlocationになります。

dorRoot

DOCUMENT_ROOT環境変数に指定されるディレクトリを指定します。デフォルトはこのClubドッカーが呼び出された際のTownドッカーのlocationになります。

maxProcesses (バージョン3.0以上)

起動するプロセス数の上限を指定します。上限に達すると、次のリクエストは他のプロセスが終了するまで実行を待たされます。

PHPドッカー

PHPアプリケーションを実行する際に使用します。CGIドッカーのパラメータはそのまま使用できます。

PHPドッカーのパラメータ

interpreter

PHPインタプリタのパスを指定します。デフォルトはphp-cgiです。

Warpドッカー

Warpドッカーは、特定の仮想パスに対しプロキシとして機能させるためのドッカーです。プロトコルの種類により HTTP Warpドッカー、AJP Warpドッカー、FCGI Warpドッカーの3種類存在します。

Warpドッカー共通のパラメータは以下です。

Warpドッカーのパラメータ

destCity

バックエンドサーバーのCity（ホスト名 or IPアドレス)を指定します。

例：

    destCity localhost

UNIXドメインソケットの場合は次のように指定します。

    destCity :unix:/tmp/hoge

destPort

バックエンドサーバーのポート番号を指定します。

例：

    destPort 8080

destTown

バックエンドサーバーのTown（パス)を指定します。

例：

    destTown /app

maxShips

Warp先に同時に運航できる船舶の数（バックエンドサーバーに同時に接続できるコネクション）の数を指定します。-1を指定すると上限はありません。デフォルトは-1です。

同時に運航する船舶の数が上限に達するとクライアントにService Unavailableが返されます。

例：

    maxShips 128

timeout

バックエンドサーバーとの接続のタイムアウトを指定します。-1を指定するとOSの永遠に待ち続けます。デフォルトは-1です。

例：

    timeout 120

HTTP Warpドッカー

HTTP バックエンドのサーバーとはHTTP通信を行います。

現在サポートされているのは非SSLのHTTP1.1通信のみです。

HTTP Wapドッカーのパラメータ

secure

バックエンドのサーバーとSSL通信を行うかを論理値で指定します。現状SSLはサポートされていないので、このパラメータはoff固定です。

例：

    secure off

supportH2 or enableH2

HTTP2をサポートするかどうかを論理値で指定します。現状HTTP2はサポートされていないので、このパラメータは現在off固定です。

例：

    supportH2 off

AJP Warpドッカー

固有のパラメータはありません。

FCGI Warpドッカー

FCGI Warpドッカーのパラメータ

scriptBase

SCRIPT_BASE環境変数を設定する際のベースとなるディレクトリを指定します。省略した場合、実行時のTownドッカーのlocationが採用されます。

docRoot

DOCUMENT_ROOT環境変数の値を指定します。省略した場合、実行時のTownドッカーのlocationが採用されます。

Secureドッカー

Secureドッカーは、TLSによる通信の暗号化を行うためのドッカーで、HTTP Portドッカーの下に配置します。

supportH2 or enableH2

HTTP2を有効にするかを論理値で指定します。デフォルトはonです。

例：

    supportH2 off

key

鍵ファイルをパス型で指定します。

例：

    key  cert/oreore.key

cert

証明書ファイルをパス型で指定します。

例：

    cert cert/oreore.crt

keyStore

鍵や証明書をまとめた鍵ストアファイルをパス型で指定します。サポートされる鍵ストアの形式は実装言語やプラットフォームに依存します。Javaではjks(Java Key Store)形式のファイルも使用可能です。

例：

    keyStore cert/keystore.p8

keyStorePass

鍵ストアを読み込むためのパスワードを指定します。

例：

    keyStorePass mypassword

traceSSL

SSLに関するログを出力するかどうかを論理値で指定します。デフォルトはoffです。

例：

    traceSSL on

Logドッカー

Logドッカーはアクセスログを記録するためのドッカーです。LogドッカーはCityドッカーの中で指定します。

Logドッカーを複数指定することで、異なる形式で複数のログファイルを作成できます。

Logドッカーの識別子は保存されるログファイル名をパス型で指定します。

例：

    [log logs/access.log]

ただし、マルチプロセスで動いている場合、実際に出力されるファイル名にはグランドエージェント識別番号が付加されます。例えば上記の例の場合、実際に生成されるファイルは

     logs/access_1.log
     logs/access_2.log
     logs/access_3.log

のようになります。これはプロセス間で書き込みの競合が起きるのを防ぐためですが、将来改善される可能性もあります。

Logドッカーはビルトインされたドッカーのみです。

Logドッカーのパラメータ

format

Logファイルに記録する際のフォーマットを指定します。書式はApacheのログ形式に準拠します。

例：

    format %h %l %u %t "%r" %>s %b

%に指定できるパラメータは以下です。

%a	リモートIP
%A	サーバーIP
%b	リクエストの長さ。不明なときは「-」
%B	リクエストの長さ。不明なときは0
%c	接続のステータス。アボートされたら「X」正常なら「-」
%e	何も出力されない（空文字列）
%h	リモートホスト名。このパラメータを指定すると、DNS逆引きが発生し、パフォーマンスに影響を及ぼす場合があります。
%H	リクエストプロトコル
%i{name}	ヘッダ「name」の値
%l	何も出力されない（空文字列）
%m	リクエストメソッド
%n	何も出力されない（空文字列）
%o{name}	応答ヘッダ「name」の値
%p	ポート番号
%P	何も出力されない（空文字列）
%q	クエリ文字列
%r	HTTP開始行
%s	HTTPステータス
%>s	HTTPステータス
%t	現在時刻
%T	所要時間
%u	リモートユーザー
%U	リクエストURL
%v	サーバー名
%V	何も出力されない（空文字列）

Rerouteドッカー

Rerouteドッカーは行先を変更する、すなわちリクエストURIを書き換えるドッカーです。WordPressのように、多くのリクエストをindex.phpで処理するようなWebアプリケーションを実行するのに必要です。

RerouteドッカーはTownドッカーの中で指定します。以下にRerouteドッカーの例を示します。

    [town /wordpress]
        location /var/www/wordpress
        index index.php
        [reroute *]
            docker wordpress
        [club *.php]
            docker php

Rerouteドッカーの種類は現状WordPressドッカーのみです。

Rerouteドッカーのパラメータ

docker

dockerの種類を指定します。指定できる値は現在のところwordpressのみです。デフォルト値はありません。

WordPressドッカー

WordPressを動かすために、リクエストURIを書き換えます。WordPressは存在しないファイルへのリクエストはすべてindex.phpが処理します。WordPressドッカーは存在しないファイルへのリクエストをPATH_INFOに変換してindex.phpを呼び出すように変換します。

固有のパラメータはありません。

Permissionドッカー

Permissionドッカーは入国審査、すなわち指定した仮想パスにアクセスできるかどうかをチェックするドッカーです。

Permissionドッカーは船舶がどこの国から来たのかをチェックします。すなわち許可されてないIPアドレスやホスト名からの接続を拒否します。

Permissionドッカーはまた、都市や町に入れるメンバーをチェックします。すなわち登録されたユーザーが正しいパスワードを入力しない場合、403 Unauthorizedエラーを返します。

Permissionドッカーは、Port、City、Townいずれかのドッカーの中で指定します。

以下はPermissionドッカーの設計例です

    [town /servlet/]
        location www/servlet
        [club *]
            docker servlet
        [permission]
           refuse ip 127.0.0.1/32 192.168.10.0/24
           admit host *
           group rocker

Permissionドッカーはデフォルトの1種類のみです。

Permissionドッカーのパラメータ

refuse or deny

接続を拒否するIPまたはホスト名を列挙します。

IPはIPアドレスの範囲をCIDR形式で指定します。以下はIPを指定する例です。(バージョン3.0以上)

    refuse ip 127.0.0.1/32 192.168.10.0/24

バージョン2.Xでは、CIDR形式ではなく、ネットマスクを指定します。

    refuse ip 127.0.0.1/255.255.255.255 192.168.10.0/255.255.255.0

このように記述すると127.0.0.1および192.168.10.XXX(XXXは任意の数字)からの接続を拒否します。また、次のようにすると、すべてのIPアドレスを拒否できます。

    refuse ip *

ホスト名は、完全一致または部分一致（サブドメイン指定）で指定します。以下は完全一致の例です

    refuse host hoge.baykit.yokohama

以下は部分一致の例です

    refuse host *.baykit.yokohama

なお、「*」を指定すると、すべてのホストを拒否できます

    refuse host *

group

アクセス可能なグループを指定します。グループはHarborドッカーのgroupsパラメータで指定したファイル内のグループです

例：

    group salesGroup

Troubleドッカー

Troubleドッカーは、旅行者のツアーにトラブルがあったときに特定の応答を返すようにするためのドッカーです。

TroubleドッカーはHarborドッカーの内部で使用します。

Troubleドッカーの識別子はありません。

Troubleドッカーのパラメータ

Troubleドッカーのパラメータ名はHTTPエラー番号です。

パラメータ値は以下の3種類とります。

guide	指定されたパスにアクセスする
text	指定されたテキストメッセージを返す
redirect	指定されたURLにリダイレクトする

guideの場合は指定されたパスのコンテンツを返します。

例：

      [trouble]
           404  guild /err/404.html

この場合、パス/err/404.htmlに相当するコンテンツを返します。

textの場合は指定されたテキストメッセージを返します

例：

      [trouble]
           404  text File Not Found

redirectの場合は、指定されたURLにリダイレクトします。

例：

      [trouble]
           404 redirect  http://www.google.com