.. -*- rst -*-

.. highlightlang:: none

.. groonga-include : introduction.txt

How to use groonga with network
===============================

You can use groonga with network. When you run groonga by using the groonga original protocol or HTTP, groonga accepts connection for network.

Connect with groonga's original protocol
----------------------------------------

Run groonga daemon
^^^^^^^^^^^^^^^^^^

Form::

  groonga [-p PORT_NUMBER] -d DB_PATH_NAME

The DB_PATH_NAME is set the full-path of existing database.
With this form, you can run groonga as a daemon and connect by
with groonga original protocol on PORT_NUMBER.
(The port number is 10041 when you don't specify PORT_NUMBER.)

Execution example::

  % groonga -d /tmp/groonga-databases/introduction.db
  12345
  %

Groonga shows its process ID on daemon mode.

Connect to groonga server
^^^^^^^^^^^^^^^^^^^^^^^^^

Form::

  groonga [-p PORT_NUMBER] -c [HOST_NAME_OR_IP_ADDRESS]

This command connects to groonga server running at specified HOST_NAME_OR_IP_ADDRESS.

When you don't specify HOST_NAME_OR_IP_ADDRESS, this command connects to groonga server running at localhost. When you don't specify PORT_NUMBER, 10041 is used.

Groonga runs in interactive mode after connect to groonga server successfully. Groonga reads command from standard input and evaluates it repeatedly.

.. groonga-command
.. include:: ../example/tutorial/network-1.log
.. .. % groonga -c
.. status
.. .. > ctrl-d
.. .. %

Terminate groonga daemon
^^^^^^^^^^^^^^^^^^^^^^^^

You can terminate groonga daemon with shutdown command.

.. groonga-command
.. include:: ../example/tutorial/network-2.log
.. .. % groonga -c
.. .. > shutdown
.. .. %

Connect with HTTP
-----------------

You need to run groonga in HTTP protocol mode when you want to use groonga via HTTP.

Form::

  groonga [-p PORT_NUMBER] -d --protocol http DB_PATH_NAME

`--protocol` option specifies a protocol of groonga server. `http` means that groonga accepts connections via HTTP.

Administration tool based on HTML
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can access administration tool based on HTML at `http://[HOST_NAME_OR_IP_ADDRESS]:[PORT_NUMBER]/` after the above command is ran. Your browser must enables JavaScript.

Run command with HTTP
^^^^^^^^^^^^^^^^^^^^^

You can run command at `/d/COMMAND_NAME` when groonga is ran in HTTP protocol mode.

Command options are passed as HTTP's GET parameters. They are in `?OPTION=VALUE&OPTION=VALUE&...` form.

.. groonga-command
.. include:: ../example/tutorial/network-3.log
.. .. http://[HOST_NAME_OR_IP_ADDRESS]:[PORT_NUMBER]/d/status
.. .. Executed command:
.. status
.. .. 
.. .. http://[HOST_NAME_OR_IP_ADDRESS]:[PORT_NUMBER]/d/select?table=Site&query=title:@this
.. .. Executed command:
.. select --table Site --query title:@this


Security
--------

Network service of groonga doesn't support authentication. Everyone can view and modify the database. We recommend that you restrict client accesses by IP address. You can use iptables or any similar tool for it.
