Perl Ocean

設定ファイルの編集

設定ファイルはプロジェクトルートの中のconfigディレクトリの中にあります。

vi ./config/ocean.yml

サーバーの挙動をコントロールするために、このファイルを編集していくことになります。

ファイルはYAMLで書かれており、複数のセクションにわかれています。

プロジェクトテンプレート生成時にでフォルト値である程度項目を埋められていますので、基本的には、一からコンフィグを生成することなく、値の編集や自分に必要な項目の追加削除を行っていくことになります。

サーバーセクション

サーバーセクションの設定例です。プロジェクトテンプレート生成時のものです。

server:
  type: xmpp
  domain: xmpp.example.org
  host: 127.0.0.1
  port: 5222
  backlog: 1024
  max_connection: 100000
  timeout: 300 
  max_read_buffer: 10000
  report_interval: 60
  pid_file: __path_to(var/run/ocean.pid)__
  context_class: Hoge::Context

上の設定例の中で、pid_fileの値に__path_to()__というヘルパー関数を利用しています。これは引数に渡されたパスを、現在のプロジェクトルートディレクトリを基準とした相対パスとして扱い、絶対パスに変換します。このようにファイルパスを指定する設定項目で、__path_to()__関数を利用して相対パスを記述するようにしておけば、プロジェクトディレクトリを移動した場合も設定を書き換える必要はなくなります。

設定項目 概要
type基本的にはxmppにしておきます。
domainサービスのドメインです。
hostサーバーのlistenポートに使われるIPアドレスです。
portサーバーのlistenポートに使われるポートナンバーです。XMPPのC2Sには5222を利用することが推奨されています。
backlogサーバーで接続要求を保持するlistenキューの長さです。
max_connectionサーバーで許容する同時接続数の最大値です。サービスの開始 [ カーネルチューニング - ソケット数のリミット ]も参照するとよいでしょう。
timeoutここで指定した秒数分、クライアントから何の反応も無い場合、その接続を切断します。ログインからログアウトまでのケーススタディ [ タイムアウト ]もあわせて参照するとよいでしょう。
max_read_buffer一つ一つのクライアントからのコネクションのリードバッファのバイトサイズの最大値です。
report_intervalサーバーは、ここで指定された秒数毎にNodeイベントカテゴリのon_timer_reportイベントハンドラを呼び出します。
use_stanza_counterスタンザのカウンタ制御を行うかどうかをyes, noで指定します。
stanza_counter_expirationuse_stanza_counterがyesの場合、秒数を指定します。指定された秒数を越えるとカウンタがリフレッシュされます。
max_stanza_countuse_stanza_counterがyesの場合、最大スタンザ数を指定します。stanza_counter_expirationで指定された秒数内に、ここで指定した数を越えるスタンザを受け取った場合、サーバーは警告ログを吐いて、そのコネクションを切断します。
pid_fileデーモン化した場合に、ここで指定されたファイルパスにPIDファイルを作成します。デーモン化しない場合はここの値は利用されません。サービスの開始 [ デーモン化 ]を合わせて参照するとよいでしょう。
context_classプロジェクトテンプレートジェネレータ実行時に回答したコンテキストクラスの名前が自動的に指定されています。基本的には自分でこの項目を編集する必要はありません。

ログセクション

ログセクションの設定例です。

log:
  type: print
  formatter: color
  level:  info
  show_packets: yes
  filepath: __path_to(var/log/ocean.log)__

ログセクションでは、typeの値次第で、他に要求される設定項目が変わります。例えば、typeをfileにした場合は、ログをファイルに保存するモードになり、保存先を指定するfilepath項目の記述が必要になります。

まずは、どのtypeでも共通して必要になる、基本的な項目の説明をします。

設定項目 概要
typeprint、warn、file、syslogの四つから選択します。
formatterdefault、color、simpleの三つから選択します。
levelcrit、warn、info、debugの四つから選択します。
show_packets実際にクライアントとやりとりしてるXMLを、ログに表示するかどうか。yes、noから選択します。

ログレベル

次の四つのログレベルが存在します。

  • crit
  • warn
  • info
  • debug

指定されたレベルに従い、どのレベルまでのログを出力するかを決定します。

例えばinfoを指定した場合、infoを含み、それよりレベルが高いログ、つまりinfo、warn、critの三つのレベルのログを出力します。debugを指定した場合、全てのログを出力します。

ログフォーマット

次の三つのフォーマットから選択します。

  • simple
  • default
  • color

simpleは、単純にメッセージを吐き出すだけです。

defaultは、次のように "日付 [ログレベル] メッセージ"という整形がなされます。

2012-03-21T15:23:17 [DEBUG]   @send_iq_toward_user

colorの場合は、defaultと同じように整形されますが、ログレベルによって色が異なり、クリティカルや警告のログを発見しやすくなります。

ログタイプがfileなどの場合は、カラーモードには何の意味もありません。カラーコードがノイズになるだけなので気をつけましょう。

ログタイプ

typeの値によってログの動作が変わります。各種ログタイプについて解説します。

開発時はprintで標準出力に流し、サービス運用時にはfileなどにしておくのが一般的です。サーバーをデーモン化する場合は、標準出力にログを流しても仕方ないのでfileにしますが、daemontoolsなどを利用する場合は、標準出力にしておく必要があるのでprintにします。

詳しくはサービスの開始 [ デーモン ]を参照して下さい。

printタイプ

ログは標準出力に流れます。

warnタイプ

ログはエラー出力に流れます。

fileタイプ

ログはファイルに出力されます。このタイプを選んだ場合は次のような項目を設定します。

設定項目 概要
filepathログファイルのパスを指定します。
sizeサイズベースでローテーションを行う場合は、ここでログファイルのバイトサイズを指定します。
date_pattern日付でローテーションを行う場合は、ここで日付のフォーマットを指定します。yyyy-MM-ddがデフォルト値になります。
tzタイムゾーンを指定できます。

sizeパラメータが設定されていればサイズベースのローテーションになります。sizeパラメータが設定されていなければ日付ベースのローテーションになります。 日付ベースのローテーションの場合は、date_patternで指定されたフォーマットのファイル名を利用します。date_patternが指定されていなかった場合はyyyy-MM-ddをデフォルトフォーマットとして利用します。tzが指定されていた場合はその値をタイムゾーンとして利用します。

syslogタイプ

ログはsyslogdに出力されます。このタイプを選んだ場合は次のような項目を設定します。

設定項目 概要
unixdomainUNIXドメインソケットを通じて出力する場合は1にします。
tagタグです。省略された場合、デフォルトとしてoceanが使われます。
facilityファシリティ値です。省略された場合、local0が使われます。

TLSセクション

TLSの設定項目です。デフォルトでは、次のように設定されたものが、コメントアウトされた状態になっています。

tls:
  cert_file: __path_to(certs/cert.pem)__
  key_file: __path_to(certs/server.nopass.key)__
  cipher_list: ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:-LOW:-SSLv2:-EXP:+eNULL

プロジェクトテンプレート生成時に利用されているcert.pm, server.nopass.keyは、あくまでデモやテストのために同梱してある自己署名の証明書ですので、TLSをサポートした正式なサービスを提供する場合は、必ず自分で証明書を準備して下さい。

このセクションが存在するかどうか自体がTLSをサポートするかどうかのスイッチとなっています。このセクションがコメントアウトされている状態ではTLSはサポートされません。TLSをサポートするためには、このセクションがコメントアウトされていないことを確認し、証明書を準備し、適切にこのセクションを設定して下さい。

証明書の準備に関しては、サービスの開始 [ TLS証明書の準備 ]を参照して下さい。

設定項目 概要
verify-
ca_file-
ca_path-
cert_file-
key_file-
cert-
cert_password-
dh_file-
dh_single_use-
cipher_list-

cipher_listによる強度は次のように、opensslコマンドで確認できます。

openssl ciphers -v 'ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:-LOW:-SSLv2:-EXP:+eNULL' | sort

次のようにアルゴリズムがリストアップされます。

AES128-SHA              SSLv3 Kx=RSA      Au=RSA  Enc=AES(128)  Mac=SHA1
AES256-SHA              SSLv3 Kx=RSA      Au=RSA  Enc=AES(256)  Mac=SHA1
DES-CBC3-SHA            SSLv3 Kx=RSA      Au=RSA  Enc=3DES(168) Mac=SHA1
DHE-DSS-AES128-SHA      SSLv3 Kx=DH       Au=DSS  Enc=AES(128)  Mac=SHA1
DHE-DSS-AES256-SHA      SSLv3 Kx=DH       Au=DSS  Enc=AES(256)  Mac=SHA1
DHE-DSS-SEED-SHA        SSLv3 Kx=DH       Au=DSS  Enc=SEED(128) Mac=SHA1
DHE-RSA-AES128-SHA      SSLv3 Kx=DH       Au=RSA  Enc=AES(128)  Mac=SHA1
DHE-RSA-AES256-SHA      SSLv3 Kx=DH       Au=RSA  Enc=AES(256)  Mac=SHA1
DHE-RSA-SEED-SHA        SSLv3 Kx=DH       Au=RSA  Enc=SEED(128) Mac=SHA1
EDH-DSS-DES-CBC3-SHA    SSLv3 Kx=DH       Au=DSS  Enc=3DES(168) Mac=SHA1
EDH-RSA-DES-CBC3-SHA    SSLv3 Kx=DH       Au=RSA  Enc=3DES(168) Mac=SHA1
RC4-MD5                 SSLv3 Kx=RSA      Au=RSA  Enc=RC4(128)  Mac=MD5 
RC4-SHA                 SSLv3 Kx=RSA      Au=RSA  Enc=RC4(128)  Mac=SHA1
SEED-SHA                SSLv3 Kx=RSA      Au=RSA  Enc=SEED(128) Mac=SHA1

サポートしたいクライアントのカバレッジやセキュリティ強度などのバランスを取りながら、適切なcipher_listを設定するようにしましょう。

SASL認証セクション

SASL認証セクションの設定例です。SASL認証について詳しくはログインからログアウトまでのケーススタディ [ SASL認証 ]を参照するとよいでしょう。

sasl:
  max_attempt: 10
  mechanisms:
    - PLAIN
    - CRAM-MD5
    - DIGEST-MD5
    - X-OAUTH2
設定項目 概要
max_attempt一つの接続からの認証試行回数の最大値です。この数をオーバーして認証失敗すると、サーバーは接続を切断し、Authenカテゴリの on_too_many_auth_attempt イベントを呼びます。
mechanismsサーバーが許可するSASL認証のメカニズムのリストです。PLAIN、CRAM-MD5、DIGEST-MD5、X-OAUTH2の四つから複数選択できます。

イベントハンドラセクション

イベントハンドラセクションの設定例です。プロジェクトテンプレートジェネレータ実行時に、回答した名前空間をベースにして自動生成されています。この設定項目は基本的には自分で編集する必要はありません。

イベントカテゴリやハンドラクラスについて詳しくは前章のイベントを参照してください。

event_handler:
  node:       Hoge::Handler::Node
  authen:     Hoge::Handler::Authen
  connection: Hoge::Handler::Connection
  message:    Hoge::Handler::Message
  people:     Hoge::Handler::People
  room:       Hoge::Handler::Room
  p2p:        Hoge::Handler::P2P
設定項目 概要
nodeNodeイベントカテゴリ用ハンドラクラスを指定します。
authenAuthenイベントカテゴリ用ハンドラクラスを指定します。
connectionConnectionイベントカテゴリ用ハンドラクラスを指定します。
peoplePeopleイベントカテゴリ用ハンドラクラスを指定します。
messageMessageイベントカテゴリ用ハンドラクラスを指定します。
roomRoomイベントカテゴリ用ハンドラクラスを指定します。
p2pP2Pイベントカテゴリ用ハンドラクラスを指定します。

カスタムセクション

ハンドラ内から利用したい項目をここで独自に定義しておくとよいでしょう。

handler: