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

- 日本語版はこちら

### Navigation

- index
- next |
- previous |
- groonga v3.0.0 documentation »
- 8. リファレンスマニュアル »
- 8.1. 実行ファイル »

# 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": 0,
        "max_command_version": 2,
        "n_queries": 0,
        "cache_hit_rate": 0.0,
        "version": "2.1.0",
        "alloc_count": 152,
        "command_version": 1,
        "starttime": 1356678595,
        "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.4.2. Performance related directives

The following directives are related to the performance of groonga-httpd.

#### 8.1.4.4.2.1. `worker_processes`

For optimum performance, set this to be equal to the number of CPUs or cores. In many cases, groonga queries may be CPU-intensive work, so to fully utilize multi-CPU/core systems, it's essential to set this accordingly.

This isn't a groonga-httpd specific directive, but an nginx's one. For details, see http://wiki.nginx.org/CoreModule#worker_processes.

By default, this is set to 1. It is nginx's default.

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

### Navigation

- index
- next |
- previous |
- groonga v3.0.0 documentation »
- 8. リファレンスマニュアル »
- 8.1. 実行ファイル »