
Installation notes
------------------

The package doesn't currently try to set up the database or
web server automatically.

Set up the database, web application and SIP capture server
using the steps below.  It is important to proceed in this
order.

PostgreSQL
----------

It is only necessary to use one database, PostgreSQL or MySQL (next).

The PostgreSQL database can be set up using the following steps:

Install the PostgreSQL server package and the contrib package
(either on the same host or another host):

sudo apt-get install postgresql postgresql-contrib
sudo su - postgres
cd /usr/share/homer/sql/postgres
psql -f homer_databases.sql

Edit the /etc/postgresql/$VERSION/main/pg_hba.conf to permit
access to the databases from other networked hosts.

psql -f homer_user.sql
psql -h localhost -U homer_user -W -d homer_configuration -f schema_configuration.sql
psql -h localhost -U homer_user -W -d homer_data -f schema_data.sql
psql -h localhost -U homer_user -W -d homer_statistic -f schema_statistic.sql

As UNIX user postgres (PostgreSQL superuser):

$ psql homer_configuration
# CREATE EXTENSION pgcrypto;
# \q

Edit /etc/homer/configuration.php, the database settings
need to be changed, in particular the DATABASE_DRIVER and DB_PORT
values need to be changed:

   define('DB_PORT', 5432);

   define('DATABASE_DRIVER',"pgsql");

MySQL
-----

It is only necessary to use one database, PostgreSQL (previous) or MySQL.

The MySQL database can be set up using the following steps:

Install the mysql-server package (either on the same host
   or another host)

      apt-get install mysql-server

cd /usr/share/homer/sql

mysql -u root --pass < homer_databases.sql
mysql -u root --pass < homer_user.sql

mysql -u root homer_data --pass < schema_data.sql
mysql -u root homer_configuration --pass < schema_configuration.sql
mysql -u root homer_statistic --pass < schema_statistic.sql

Initializing the tables
-----------------------

It is currently necessary to run the cron job once manually to
initialize tables before starting the web application or Kamailio
process.

The cron job needs to be configured with database access parameters
in /etc/homer/rotation.ini

It can be run manually by root:

   $ sudo /usr/lib/homer/libexec/homer_rotate

Web Application configuration
-----------------------------

cd /etc/homer
vi configuration.php
  - configure database parameters
vi preferences.php
  - configure as required

Apache
------

For Apache, mod_rewrite must be enabled.  It should automatically be
enabled when the package is installed, but in case it isn't, it can
be enabled with this command:

    a2enmod rewrite

Once all of the above steps are complete, the web application can be
enabled by running the command:

    a2enconf homer-api


Kamailio
--------

This package provides an independent init script and systemd unit
file to run a dedicated Kamailio process for HOMER.  HOMER uses
a Kamailio process to receive the incoming packets from the
capture agents on the network.

The Kamailio process is configured in /etc/homer/kamailio-homer.cfg
and /etc/default/kamailio-homer

Edit the cfg file to include the correct settings for the database hostname
and credentials.

This process uses a distinct PID file and listens on distinct port
numbers so it can run on the same host as a standard Kamailio process
if required.

The process can be enabled by editing /etc/default/kamailio-homer
and uncommenting the line:

#RUN_KAMAILIO=yes

and then running the necessary command:

   For systemd users:

      systemctl enable kamailio-homer
      systemctl restart kamailio-homer

   For other users:

      service kamailio-homer start

Log in and change default passwords
-----------------------------------

Browse to http://<servername>/homer and the login form should appear.

The default credentials are admin / test123

Change the password immediately.

Review the schema files to identify other default accounts and passwords that
you may want to change.

Monitoring
----------

Availability: use a monitoring system such as Nagios or Icinga
to verify that the Kamailio process is listening on TCP

Performance: use a performance monitoring tool like Ganglia to observe
the impact of HOMER processes on CPU, memory and disk space.

Testing and inspecting the system
---------------------------------

Install the captagent package on the same host where homer-api is
running.

Edit /etc/captagent/transport_hep.xml and change the value of
capture-port from 9060 to 9061.  All other default settings should
be satisfactory for the captagent to communicate with homer-api.

Restart the process:

   systemctl restart captagent

On the homer-api server, you may want to enable debug logging.
Edit /etc/homer/kamailio-homer.cfg and set the parameter:

debug=4

Now watch the logs with

   tail -f /var/log/homer.log

From any other host on the network, use sipsak to send a test message
to the host where captagent and homer-api are running:

   sipsak -M --message-body 'testing' -s sip:user@homer-server.example.org

It doesn't matter if there isn't any SIP process running to receive the
message, captagent will still notice it and send a copy to HOMER.

At this point, you should see a whole lot of activity in /var/log/homer.log

Log into the homer_data database and you can verify the
SIP request was logged by looking in the table sip_capture_rest_<today>,
where <today> is the date in YYYYMMDD format, for example:

  select * from sip_capture_rest_20160913;

Go to the web interface, refresh the search results and you should see
the message you sent.

If you see nothing in the search results, you may need to click the
time range at the top right-hand corner of the screen to properly
initialize the time-based filters.

If problems are encountered accessing the web interface, inspect the
Apache log file:

   tail -f /var/log/apache2/error.log

or the log file for the virtual host if applicable.
