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:///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_, where 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.