groonga - An open-source fulltext search engine and column store.

8.1.4. groonga-httpd

8.1.4.1. Summary

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/.

8.1.4.2. Synopsis

groonga-httpd [nginx options]

8.1.4.3. Usage

8.1.4.3.1. Set up

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

8.1.4.3.2. Request queries

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
  }
]

8.1.4.3.3. Browse the administration tool

Also, you can browse Web-based administration tool at http://localhost:10041/.

8.1.4.3.4. Shut down

Finally, to terminate the running groonga-httpd daemon, run this:

% groonga-httpd -s stop

8.1.4.4. Configuration directives

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.

8.1.4.4.1. Groonga-httpd specific directives

The following directives aren't provided by nginx. They are provided by groonga-httpd to configure groonga-httpd specific configurations.

8.1.4.4.1.1. groonga

Synopsis:

groonga on | off;
Default
groonga off;
Context
location

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
}

8.1.4.4.1.2. groonga_database

Synopsis:

groonga_database /path/to/groonga/database;
Default
groonga_database /usr/local/var/lib/groonga/db/db;
Context
http, server, location

Specifies the path to a groonga database. This is the required directive.

8.1.4.4.1.3. groonga_base_path

Synopsis:

groonga_base_path /d/;
Default
The same value as location name.
Context
location

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.
}

8.1.4.5. Available nginx modules

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.