groonga-httpdはgroongaサーバーとhttpプロトコルで通信するプログラムです。 機能的には、 groonga HTTPサーバー と同じになっています。 groonga HTTPサーバー はHTTPサーバーとしては最小限の機能しか持ちませんが、一方のgroonga-httpdはnginxを組み込むことでnginxが準拠しているHTTPの仕様と機能が全て利用できます。nginxの詳細については、http://www.nginx.org/を参照してください。
groonga-httpdにはHTML + JavaScriptで実装された管理ツールが標準で付属しています。ウェブブラウザでhttp://hostname:port/にアクセスすると、管理ツールを利用できます。
groonga-httpd [nginx options]
まずは、データベースを指定するためにgroonga-httpdの設定ファイルを編集する必要があります。groonga_databaseディレクティブを有効にするために、次のように/etc/groonga/httpd/groonga-httpd.confを編集してください。
# Match this to the file owner of groonga database files if groonga-httpd is
# run as root.
#user groonga;
...
http {
...
# Don't change the location; currently only /d/ is supported.
location /d/ {
groonga on; # <= This means to turn on groonga-httpd.
# Specify an actual database and enable this.
groonga_database /var/lib/groonga/db/db;
}
...
}
次に、groonga-httpdを実行してください。すぐにターミナルに制御が戻ってきますが、groonga-httpdはデフォルトでデーモンプロセスとして実行されるからです。
% groonga-httpd
動作を確認するため、簡単なクエリ(status)をリクエストしてみます。
実行例:
% curl http://localhost:10041/d/status
[
[
0,
1337566253.89858,
0.000355720520019531
],
{
"uptime": 0,
"max_command_version": 2,
"n_queries": 0,
"cache_hit_rate": 0.0,
"version": "2.0.3-278-g6071d65",
"alloc_count": 145,
"command_version": 1,
"starttime": 1340769698,
"default_command_version": 1
}
]
補足ですが、 http://localhost:10041/ にアクセスすると管理ツールを利用できます。
このセクションでは重要なディレクティブのみ説明します。重要なディレクティブとはgroonga-http特有のディレクティブと性能に関するディレクティブです。
以下のディレクティブはgroonga-httpdの設定ファイル中で使用することができます。デフォルトでは、設定ファイルは/etc/groonga/httpd/groonga-httpd.confに置かれています。
以下のディレクティブはnginxが提供しているものではなく、groonga-httpd関連の設定をするためにgroonga-httpdが提供しているディレクティブです。
書式:
groonga on | off;
この location ブロックでgroongaを使うかどうかを指定します。デフォルトは off です。groongaを使うためには on を指定してください。
例:
location /d/ {
groonga on; # Enables groonga under /d/... path
}
location /d/ {
groonga off; # Disables groonga under /d/... path
}
書式:
groonga_database /path/to/groonga/database;
groongaデータベースのパスを指定します。このディレクティブは必須です。
書式:
groonga_base_path /d/;
URIのベースパスを指定します。groongaは command を実行するために /d/command?parameter1=value1&... というパスを使います。groonga-httpdでもこのパスの形式を使いますが、groonga-httpdは /other-prefix/command?parameter1=value1&... というように /d/ ではなく別のプレフィックスを使った形式もサポートしています。この別の形式もサポートするために、groonga-httpdはリクエストURIの先頭からベースパスを削除し、先頭に /d/ を追加します。このパスの変換をすることにより、ユーザーはプレフィックスをカスタムできるようになりますが、groongaは常に /d/command?parameter1=value1&... という形式で処理できます。
通常、このディレクティブを使う必要はありません。このディレクティブはコマンド毎に設定をしたい場合に使います。
以下は shutdown コマンドに認証をかける設定例です。:
groonga_database /var/lib/groonga/db/db;
location /d/shutdown {
groonga on;
# groonga_base_path is needed.
# Because /d/shutdown is handled as the base path.
# Without this configuration, /d/shutdown/shutdown path is required
# to run shutdown command.
groonga_base_path /d/;
auth_basic "manager is required!";
auth_basic_user_file "/etc/managers.htpasswd";
}
location /d/ {
groonga on;
# groonga_base_path doesn't needed.
# Because location name is the base path.
}
HttpRewriteModuleを除く全てのHTTPの標準モジュールが利用可能です。HttpRewriteModuleはPCRE (Perl Compatible Regular Expressions)へ依存しないようにするために無効化されています。残りの標準モジュールの一覧は、 http://wiki.nginx.org/Modules を参照してください。