Table Of Contents

Previous topic

Installing Reef

Next topic

ashttpd

Running and Configuring Reef

Reef Runtime Configuration

Reef is shipped as a WSGI application that may be installed behind a standard web-server (e.g. Apache). However for lightweight, engineering or demonstration deployments a simple web-server called ashttpd is shipped and can be used “out-of-the-box”. ashttpd is a fairly capable, multi-threaded web-server however it is recommended you use it behind a more powerful reverse proxy for production deployments.

Both the Reef Server WSGI application and the ashttpd web server have runtime configuration settings that are desribed in detail in the Runtime Settings section. Additionally the following man pages are available:

Configuring the Database

Reef uses a database to store events and ships with an SQLite database which is suitable for small deployments and proof of concept activities. However for production deployments it is strongly recommended that a more powerful, external database is deployed.

Using the builtin SQLite database

Reefs ships with a default SQLite database which can be used for demos or small deployments. By default it has one superuser configured with the username of “admin” and password “admin”. This allows you to use the admin interface to change the credentials and add other users. It is highly recommended to change at least the password of the admin user.

If you need would like to create a new superuser using the command line you need to invoke the following command:

$ PYTHONPATH=/opt/abilisoft.com/reef/share/reef.pyz
django-admin.py createsuperuser –settings=reef.django_settings –username foo --email=foo@example.com

This will prompt you for a password to use.

Using an external database

Abilisoft recommend PostgreSQL, a powerful, open source object-relational database system. It has had more than 15 years of active development and a proven architecture that has earned it a strong reputation for reliability, data integrity, and correctness. It runs on all major operating systems and is fully ACID compliant.

There a number of steps involved in setting up an external database:

  1. Configure the connection details.
  2. Create the schema and indexes.
  3. Create an initial superuser.

The descriptions below assume that Reef is hosted using ashttpd in its default configuration. When hosting Reef on other WSGI servers some details may differ. Before starting, you will need to configure the database itself, setting up a database is not described in detail here (however refer to the section on Example setting up PostgreSQL for for a high level overview).

Configuring Connection Details

The Reef server needs connection details for the database which are read from $AS_HOME/etc/reef.conf in the [django.db:default] section (see Runtime Settings). For example:

[django.db.:default]
ENGINE = django.db.backends.postgresql_psycopg2
NAME = reef
USER = reef
PASSWORD = secret
HOST = psqlserver

The example above configures a PostgreSQL database running on the host psqlserver that is listening on the default PostgreSQL port (5432). If an alternate port is required then you can set the PORT value accordingly. The ENGINE value specifies the database backend that Reef will use to connect to PostgreSQL. The NAME settings specifies the database name, in this case, reef.

Creating the schema and indexes

The schema and indexes are created using syncdb subcommand of the django-admin.py tool shipped with reef. There are a few things to look out for when using this: you must ensure the reef python library is loaded and you must point the tool at the reef configuration this is done.

$ PYTHONPATH=/opt/abilisoft.com/reef/share/reef.pyz \
    django-admin.py syncdb --settings=reef.django_settings

This will ask you to create an initial superuser, it is best to create one right away in which case you can skip the last step of creating one explicitly.

Creating a Superuser

If you didn’t create a superuser as part of the previous step you will need to do this now. You need to create an initial superuser from the command line. After this it is possible to create new users using the admin interface of reef. This is done using the createsuperuser subcommand of the django-admin.py tool. As before you need to point it to the reef python library and it’s Django configuration.

$ PYTHONPATH=/opt/abilisoft.com/reef/share/reef.pyz
django-admin.py createsuperuser –settings=reef.django_settings –username foo --email=foo@example.com

Example setting up PostgreSQL

This example demonstrates how to set up the PostgreSQL database on CentOS 5.6. Start by installing the database server itself:

# yum install postgresql84-server
...
# service postgresql initdb
# service postgresql start

The database server should now be installed and running. It is installed under the postgres user and only this user is known to the database for now. Next we need to create a user; ensure the user has a password so the Reef server can connect to the database:

# su - postgres
$ createuser --pwprompt myuser
Enter password for new role:
Enter it again:
Shall the new role be a superuser? (y/n) n
$ logout
#

Once the user is defined we need to give that user a database, we’ll create a database named reef:

# createdb -O myuser reef

Next configure the connection in the Reef runtime settings:

# cat >/opt/abilisoft.com/reef/etc/asdjango.conf <<EOF
[django.db:default]
ENGINE = django.db.backends.postgresql_psycopg2
NAME = reef
USER = myuser
PASSWORD = secret
EOF
#

Notice how the HOST and PORT directives are not included, since we connect to the localhost we do not need these and will actually break the default PostgreSQL authentication on a localhost.

Now initialise the database for Reef use. This will also prompt you to create a superuser. This is the user with which you will be able to log into the Reef Administration interface to manage other users:

# PYTHONPATH=/opt/abilisoft.com/reef/share/reef.pyz \
> django-admin.py syncdb --settings=reef.django_settings
Creating tables ...
Creating table auth_permission
Creating table auth_group_permissions
Creating table auth_group
Creating table auth_user_user_permissions
Creating table auth_user_groups
Creating table auth_user
Creating table auth_message
Creating table django_content_type
Creating table django_session
Creating table django_site
Creating table django_admin_log
Creating table app_eventsvc_servicedef_filterdefs
Creating table app_eventsvc_servicedef
Creating table app_eventsvc_filterdef
Creating table app_eventsvc_filterterm
Creating table app_reef_event
Creating table app_reef_eventattr
Creating table app_reef_eventlog
Creating table app_reef_severity

You just installed Django's auth system, which means you
don't have any superusers defined.
Would you like to create one now? (yes/no): yes
Username (Leave blank to use 'flub'): admin
E-mail address: admin@example.com
Password:
Password (again):
Superuser created successfully.
Installing custom SQL ...
Installing indexes ...
Installed 41 object(s) from 2 fixture(s)
#

Start ashttpd as normal:

# ashttpd
ashttpd application initialising (7.1 (donbot.1)  r14146  20130510)
#

Navigate your browser to http://localhost:8000 and log in to Reef client to ensure your setup is working.