groonga-httpd is a program to communicate with a groonga server using the HTTP protocol. It functions as same as groonga HTTPサーバー. Although groonga HTTPサーバー has limited support for HTTP with a minimal built-in HTTP server, groonga-httpd has full support for HTTP with an embedded nginx. All standards-compliance and features provided by nginx is also available in groonga-httpd.
groonga-httpd has an Web-based administration tool implemented with HTML and JavaScript. You can access to it from http://hostname:port/.
日本語版はこちらgroonga-httpd [nginx options]
First, you'll need to edit the groonga-httpd configuration file to specify a database. Edit /etc/groonga/httpd/groonga-httpd.conf to enable the groonga_database directive like this:
# 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;
}
...
}
Then, run groonga-httpd. Note that the control immediately returns back to the console because groonga-httpd runs as a daemon process by default.:
% groonga-httpd
To check, request a simple query (status).
Execution example:
% curl http://localhost:10041/d/status
[
[
0,
1337566253.89858,
0.000355720520019531
],
{
"uptime": 1,
"max_command_version": 2,
"n_queries": 0,
"cache_hit_rate": 0.0,
"version": "2.0.5",
"alloc_count": 142,
"command_version": 1,
"starttime": 1343713471,
"default_command_version": 1
}
]
Also, you can browse Web-based administration tool at http://localhost:10041/.
Finally, to terminate the running groonga-httpd daemon, run this:
% groonga-httpd -s stop
This section decribes only important directives. They are groonga-httpd specific directives and performance related directives.
The following directives can be used in the groonga-httpd configuration file. By default, it's located at /etc/groonga/httpd/groonga-httpd.conf.
The following directives aren't provided by nginx. They are provided by groonga-httpd to configure groonga-httpd specific configurations.
Synopsis:
groonga on | off;
Specifies whether groonga is enabled in the location block. The default is off. You need to specify on to enable groonga.
Examples:
location /d/ {
groonga on; # Enables groonga under /d/... path
}
location /d/ {
groonga off; # Disables groonga under /d/... path
}
Synopsis:
groonga_database /path/to/groonga/database;
Specifies the path to a groonga database. This is the required directive.
Synopsis:
groonga_base_path /d/;
Specifies the base path in URI. groonga uses /d/command?parameter1=value1&... path to run command. The form of path in used in groonga-httpd but groonga-httpd also supports /other-prefix/command?parameter1=value1&... form. To support the form, groonga-httpd removes the base path from the head of request URI and prepend /d/ to the processed request URI. By the path conversion, users can use custom path prefix and groonga can always uses /d/command?parameter1=value1&... form.
Nomally, this directive isn't needed. It is needed for per command configuration.
Here is an example configuration to add authorization to shutdown command:
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.
}
All standard HTTP modules is available. HttpRewriteModule is disabled when you don't have PCRE (Perl Compatible Regular Expressions). For the list of standard HTTP modules, see http://wiki.nginx.org/Modules.