=======
Contrib
=======

Currently, the contrib directory contains two scripts - a python script named
*billing.py* and an init script named *osaas*.

Init script
###########

*osaas* is a SuSE-specific init-script which adds the possibility to start and
stop OSAAS-server as a service. You can manually copy it to ``/etc/init.d/``
and set the propper links to the runlevels you want to start the OSAAS-server.
By default this script requires an osaas-user to run under. Make sure that the
script has the executable-permissions set. The startup-script requires a
configuration-file ``/etc/osaas/osaas-config.xml`` to work properly. When using
OSAAS-server from within a RPM-package this is automatically setup correct.


billing.py
##########

*billing.py* searches for GetFeature requests in the database where OSAAS is
logging to. Each GetFeature request that could be found is sent to the WFS
service again - with a little difference: the script doesn't query for the
features itself, but for the number of features that would have been retrieved
by this GetFeature request (the *resultType=hits* parameter is set in this
GetFeature request). Finally, the retrieved number is written into the database.

The next sections describe the configuration and usage of *billing.py*.


PostgreSQL Configuration
------------------------

*billing.py* needs access to the database where OSAAS is logging to. So, make
sure that PostgreSQL is listening to localhost on port 5432. Therefore, you
should find the following lines in ``/var/lib/pgsql/data/postgresql.conf``::

  listen_adress='localhost'
  port = 5432

If OSAAS is logging to a database which is not running on localhost or port
5432, you need to adjust these settings.

Furthermore, you should find a line to allow the user *osaas* to access to
*osaas_logging* database running on localhost in ``/var/lib/pgsql/data/pg_hba.conf``::

  host osaas_logging osaas  127.0.0.1/32 md5

Now, you need to create the user and the database::

  su postgres -c "createuser -SDRleP osaas"
  su postgres -c "createdb -O osaas osaas_logging"

Finally, you need to execute two SQL scripts that create all necessary database
tables. The first one creates the target database table for WFS requests. The
second one adds some additional columns to this table required by the billing
script::

  su postgres -c "psql -U osaas -h localhost -d osaas_logging -f contrib/billing/wfs_requests.sql"
  su postgres -c "psql -U osaas -h localhost -d osaas_logging -f contrib/billing/billing.sql"


Configuration File
------------------

This section describes the options, the user has to configure the *billing.py*
script. In general, the config is devided into two parts - database and logging.
You can find an example configuration *billing.cfg* in ``contrib/billing/``.

[database]
''''''''''

The settings in this section define the database connection. It is absolutely
necessary to have such a section in your configuration - otherwise *billing.py*
is not possible to create a connection to the database *OSAAS* is logging to.

The options of this section are:

database (required):
    This option defines the name of the database where *OSAAS* is logging to. It
    is absolutely necessary to define this option - otherwise the script
    wouldn't be able to connect to a database.

host (optional):
    This option defines the host where the database is running on. If this
    option is missing, its default value is *localhost*.

user (required):
    This option defines the user that is used to connect to *database*. It is
    absolutely necessary to define a user - otherwise the script wouldn't be
    able to connect to database.

password (optional):
    This option defines the password for *user* that is used to create the
    database connection. If there is no password in the configuration, the
    database connection is created without password.

[logging]
'''''''''

The settings in this section define the logging of *billing.py*. All options in
this section are optional.

The options in this section are:

logfile (optional):
    A path to a file that is used for logging. It is recommended to define this
    option to get to know about important information of the execution of the
    script.

loglevel (optional):
    This option defines the level of details. Currently, you are able to choose
    between three levels - *1*, *2* and *3*. The default loglevel is *2*.
    *1*: The script just logs failures that occured while processing.
    *2*: The script logs failures and some additional information.
    *3*: The script is very verbose - logs failures, additional information and
    a lot of further information about the process itself. This loglevel is
    recommended for developers.