Setting up Homer: Difference between revisions

From Alpine Linux
m (Specify branches in pkg template.)
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{TOC right}}
{{TOC right}}
{{Obsolete|The homer packages do not exist in alpine 3.16 and later}}


This page describes how to set up [http://sipcapture.org/ HOMER] on
This page describes how to set up [https://sipcapture.org/ HOMER] on
Alpine Linux.
Alpine Linux.


The packages are available in the community repository starting from
The packages are available in the community repository starting from
Alpine Linux 3.6. Make sure that this repository is enabled in
Alpine Linux 3.6. Make sure that this repository is enabled in
<code>/etc/apk/repositories</code>.
{{path|/etc/apk/repositories}}.


== Primary Node ==
== Primary Node ==
Line 13: Line 14:
required services:
required services:


<pre>apk add homer-api-doc homer-ui mariadb kamailio-mysql nginx php7-fpm
{{cmd|# apk add {{pkg|homer-api-doc|branch=v3.15|arch=}} {{pkg|homer-ui|branch=v3.15|arch=}} {{pkg|mariadb|branch=v3.15|arch=}} {{pkg|kamailio-mysql|branch=v3.15|arch=}} {{pkg|nginx|branch=v3.15|arch=}} {{pkg|php7-fpm|branch=v3.15|arch=}}}}


rc-service mariadb setup
{{cmd|<nowiki># rc-service mariadb setup
rc-update add mariadb
# rc-update add mariadb
rc-service mariadb start
# rc-service mariadb start
mysql_secure_installation
# mysql_secure_installation
</nowiki>}}


homer_db_init
{{cmd|<nowiki># homer_db_init
rc-update add crond
# rc-update add crond
rc-service crond start
# rc-service crond start
</nowiki>}}


cp /usr/share/doc/homer-api/examples/sipcapture/sipcapture.kamailio /etc/kamailio/kamailio.cfg
{{cmd|<nowiki># cp /usr/share/doc/homer-api/examples/sipcapture/sipcapture.kamailio /etc/kamailio/kamailio.cfg
echo rc_need=mariadb > /etc/conf.d/kamailio
# echo rc_need=mariadb > /etc/conf.d/kamailio
rc-update add kamailio
# rc-update add kamailio
rc-service kamailio start
# rc-service kamailio start
</nowiki>}}


cp /usr/share/doc/homer-api/examples/web/homer5.php-fpm /etc/php7/php-fpm.d/homer5.conf
{{cmd|<nowiki># cp /usr/share/doc/homer-api/examples/web/homer5.php-fpm /etc/php7/php-fpm.d/homer5.conf
rc-update add php-fpm7
# rc-update add php-fpm7
rc-service php-fpm7 start
# rc-service php-fpm7 start
</pre>
</nowiki>}}


Override the default nginx configuration with the HOMER template:
Override the default nginx configuration with the HOMER template:
Line 41: Line 45:


Make the following changes in
Make the following changes in
<code>/etc/nginx/conf.d/homer5.conf</code>:
{{path|/etc/nginx/conf.d/homer5.conf}}:


{|
{|
|root
|root
|<code>/usr/share/webapps/homer</code>
|{{path|/usr/share/webapps/homer}}
|-
|-
|server_name
|server_name
Line 56: Line 60:
If you are going to deploy database nodes in addition to this primary
If you are going to deploy database nodes in addition to this primary
node, change <code>SINGLE_NODE</code> to <code>0</code> in
node, change <code>SINGLE_NODE</code> to <code>0</code> in
<code>/etc/homer/configuration.php</code>.
{{path|/etc/homer/configuration.php}}.


Set <code>HOMER_TIMEZONE</code> in
Set <code>HOMER_TIMEZONE</code> in
<code>/etc/homer/preferences.php</code> according to your time zone.
{{path|/etc/homer/preferences.php}} according to your time zone.


Enable the <code>nginx</code> service:
Enable the <code>nginx</code> service:


<pre>rc-update add nginx
{{cmd|<nowiki># rc-update add nginx
rc-service nginx start
# rc-service nginx start
</pre>
</nowiki>}}


If using a firewall, you have to allow users to access the nginx
If using a firewall, you have to allow users to access the nginx
Line 76: Line 80:
LDAP authentication module:
LDAP authentication module:


<pre>apk add homer-api-ldap
{{cmd|# apk add {{pkg|homer-api-ldap|branch=v3.15|arch=}}}}
</pre>


In addition, you have to allow connections to the LDAP server if using
In addition, you have to allow connections to the LDAP server if using
a firewall.
a firewall.


==== Changes in /etc/homer/preferences.php ====
==== Changes in {{path|/etc/homer/preferences.php}} ====


Enable LDAP authentication:
Enable LDAP authentication:
<pre>define('AUTHENTICATION',"LDAP");
{{cat|/etc/homer/preferences.php|...
</pre>
define('AUTHENTICATION',"LDAP");
...}}


Uncomment the LDAP section and add/update parameters according to your
Uncomment the LDAP section and add/update parameters according to your
server configuration:
server configuration:


<pre>define('LDAP_HOST',"localhost");
{{cat|/etc/homer/preferences.php|<nowiki>...
define('LDAP_HOST',"localhost");
define('LDAP_PORT',389);
define('LDAP_PORT',389);
define('LDAP_VERSION',3);
define('LDAP_VERSION',3);
Line 97: Line 102:
define('LDAP_BIND_PASSWORD',"secret");
define('LDAP_BIND_PASSWORD',"secret");
define('LDAP_BASEDN',"ou=Users,dc=example,dc=com");
define('LDAP_BASEDN',"ou=Users,dc=example,dc=com");
</pre>
...</nowiki>}}


Add one of the following lines, depending on whether the STARTTLS
Add one of the following lines, depending on whether the STARTTLS
mechanism shall be used to protect the LDAP connection:
mechanism shall be used to protect the LDAP connection:


<pre>define('LDAP_ENCRYPTION',"none");
{{cat|/etc/homer/preferences.php|...
define('LDAP_ENCRYPTION',"none");
define('LDAP_ENCRYPTION',"tls");
define('LDAP_ENCRYPTION',"tls");
</pre>
...}}


If TLS is used, you have to make sure that the relevant root
If TLS is used, you have to make sure that the relevant root
certificate is trusted. If using a self-signed root certificate, one
certificate is trusted. If using a self-signed root certificate, one
way to achieve this is to add the <code>TLS_CACERT</code> parameter to
way to achieve this is to add the <code>TLS_CACERT</code> parameter to
<code>/etc/openldap/ldap.conf</code>, specifying the path to the
{{path|/etc/openldap/ldap.conf}}, specifying the path to the
trusted CA certificate.
trusted CA certificate.


Specify the users who should have admin rights:
Specify the users who should have admin rights:


<pre>define('LDAP_ADMIN_USERS',"donald,mike");
{{cat|/etc/homer/preferences.php|...
</pre>
define('LDAP_ADMIN_USERS',"donald,mike");
...}}


Remove the parameters starting with <code>LDAP_GROUP_</code> unless
Remove the parameters starting with <code>LDAP_GROUP_</code> unless
Line 122: Line 129:
==== Nested Groups with Active Directory ====
==== Nested Groups with Active Directory ====


The default settings in <code>/etc/homer/preferences.php</code> are
The default settings in {{path|/etc/homer/preferences.php}} are
intended for LDAP schemas conforming to
intended for LDAP schemas conforming to
[https://tools.ietf.org/rfc/rfc2307.txt RFC 2307]. Otherwise, you may
[https://www.rfc-editor.org/rfc/rfc2307.txt RFC 2307]. Otherwise, you may
have to modify the parameters starting with
have to modify the parameters starting with
<code>LDAP_USERNAME_ATTRIBUTE_</code>. The following example
<code>LDAP_USERNAME_ATTRIBUTE_</code>. The following example
Line 130: Line 137:
Windows Active Directory based on nested group membership:
Windows Active Directory based on nested group membership:


<pre>define('LDAP_USERNAME_ATTRIBUTE_OPEN',"(&(samaccountname=");
{{cat|/etc/homer/preferences.php|<nowiki>...
define('LDAP_USERNAME_ATTRIBUTE_OPEN',"(&(samaccountname=");
define('LDAP_USERNAME_ATTRIBUTE_CLOSE',")(memberof:1.2.840.113556.1.4.1941:=cn=HOMER,ou=Groups,dc=example,dc=com))");
define('LDAP_USERNAME_ATTRIBUTE_CLOSE',")(memberof:1.2.840.113556.1.4.1941:=cn=HOMER,ou=Groups,dc=example,dc=com))");
</pre>
...</nowiki>}}


== Database Nodes ==
== Database Nodes ==
Line 143: Line 151:
database service:
database service:


<pre>apk add homer-api-doc homer-db mariadb kamailio-mysql
{{cmd|# apk add {{pkg|homer-api-doc|branch=v3.15|arch=}} {{pkg|homer-db|branch=v3.15|arch=}} {{pkg|mariadb|branch=v3.15|arch=}} {{pkg|kamailio-mysql|branch=v3.15|arch=}}}}


rc-service mariadb setup
{{cmd|<nowiki># rc-service mariadb setup
rc-update add mariadb
# rc-update add mariadb
rc-service mariadb start
# rc-service mariadb start
</pre>
</nowiki>}}


Set up the database. You may want to disable remote root logins to the
Set up the database. You may want to disable remote root logins to the
database.
database.


<pre>mysql_secure_installation
{{cmd|<nowiki># mysql_secure_installation
homer_db_init -r
# homer_db_init -r
</pre>
</nowiki>}}


You may want to change the default password for the HOMER database
You may want to change the default password for the HOMER database
user. This can be done as follows:
user. This can be done as follows:


<pre> mysql -e "SET PASSWORD FOR 'homer_user' = PASSWORD('<password>');"
{{cmd|# mysql -e "SET PASSWORD FOR 'homer_user' {{=}} PASSWORD('<password>');"}}
</pre>


Enable the <code>crond</code> service:
Enable the <code>crond</code> service:


<pre>rc-update add crond
{{cmd|<nowiki># rc-update add crond
rc-service crond start
# rc-service crond start
</pre>
</nowiki>}}


Override the Kamailio configuration with the HOMER template:
Override the Kamailio configuration with the HOMER template:


<pre>cp /usr/share/doc/homer-api/examples/sipcapture/sipcapture.kamailio /etc/kamailio/kamailio.cfg
{{cmd|# cp /usr/share/doc/homer-api/examples/sipcapture/sipcapture.kamailio /etc/kamailio/kamailio.cfg}}
</pre>


Change the <code>capture_node</code> parameter in
Change the <code>capture_node</code> parameter in
<code>/etc/kamailio/kamailio.cfg</code> to a unique value. If you
{{path|/etc/kamailio/kamailio.cfg}} to a unique value. If you
changed the database user password, update the
changed the database user password, update the
<code>HOMER_DB_PASSWORD</code> parameter accordingly.
<code>HOMER_DB_PASSWORD</code> parameter accordingly.
Line 181: Line 187:
Enable the <code>kamailio</code> service:
Enable the <code>kamailio</code> service:


<pre>echo rc_need=mariadb > /etc/conf.d/kamailio
{{cmd|<nowiki># echo rc_need=mariadb > /etc/conf.d/kamailio
rc-update add kamailio
# rc-update add kamailio
rc-service kamailio start
# rc-service kamailio start
</pre>
</nowiki>}}


If using a firewall, you have to allow the reception of captured SIP
If using a firewall, you have to allow the reception of captured SIP
Line 197: Line 203:
{|
{|
|Node
|Node
|Value of <code>capture_node</code> in <code>/etc/kamailio/kamailio.cfg</code>
|Value of <code>capture_node</code> in {{path|/etc/kamailio/kamailio.cfg}}
|-
|-
|Host
|Host
Line 222: Line 228:
To capture packets on a SIP server, install the HOMER CaptAgent:
To capture packets on a SIP server, install the HOMER CaptAgent:


<pre>apk add captagent
{{cmd|# apk add {{pkg|captagent|branch=v3.15|arch=}}}}
</pre>


Configure the <code>capture-host</code> and <code>capture-port</code>
Configure the <code>capture-host</code> and <code>capture-port</code>
parameters in <code>/etc/captagent/transport_hep.xml</code>. The
parameters in {{path|/etc/captagent/transport_hep.xml}}. The
capture host is the primary or an additional database node. The port
capture host is the primary or an additional database node. The port
should be set to <code>9060</code>.
should be set to <code>9060</code>.
Line 232: Line 237:
Enable the service:
Enable the service:


<pre>rc-update add captagent
{{cmd|<nowiki># rc-update add captagent
rc-service captagent start
# rc-service captagent start
</pre>
</nowiki>}}


If using a firewall, you have to allow sending the captured SIP
If using a firewall, you have to allow sending the captured SIP
Line 243: Line 248:
A cron job takes care of removing obsolete data from the capture host
A cron job takes care of removing obsolete data from the capture host
databases. The retention period can be adjusted by modifying
databases. The retention period can be adjusted by modifying
<code>/etc/homer/rotation.ini</code>.
{{path|/etc/homer/rotation.ini}}.
 


[[category:Telephony]]
[[category:Telephony]]

Latest revision as of 07:44, 13 January 2024

This material is obsolete ...

The homer packages do not exist in alpine 3.16 and later (Discuss)

This page describes how to set up HOMER on Alpine Linux.

The packages are available in the community repository starting from Alpine Linux 3.6. Make sure that this repository is enabled in /etc/apk/repositories.

Primary Node

Install the required packages, set up the database, and enable required services:

# apk add homer-api-doc homer-ui mariadb kamailio-mysql nginx php7-fpm

# rc-service mariadb setup # rc-update add mariadb # rc-service mariadb start # mysql_secure_installation

# homer_db_init # rc-update add crond # rc-service crond start

# cp /usr/share/doc/homer-api/examples/sipcapture/sipcapture.kamailio /etc/kamailio/kamailio.cfg # echo rc_need=mariadb > /etc/conf.d/kamailio # rc-update add kamailio # rc-service kamailio start

# cp /usr/share/doc/homer-api/examples/web/homer5.php-fpm /etc/php7/php-fpm.d/homer5.conf # rc-update add php-fpm7 # rc-service php-fpm7 start

Override the default nginx configuration with the HOMER template: 

: > /etc/nginx/conf.d/default.conf
cp /usr/share/doc/homer-api/examples/web/homer5.nginx /etc/nginx/conf.d/homer5.conf

Make the following changes in /etc/nginx/conf.d/homer5.conf:

root /usr/share/webapps/homer
server_name your server's host name
fastcgi_pass 127.0.0.1:9001

If you are going to deploy database nodes in addition to this primary node, change SINGLE_NODE to 0 in /etc/homer/configuration.php.

Set HOMER_TIMEZONE in /etc/homer/preferences.php according to your time zone.

Enable the nginx service:

# rc-update add nginx # rc-service nginx start

If using a firewall, you have to allow users to access the nginx server using HTTP. In addition, reception of the captured SIP traffic must be allowed on UDP port 9060.

LDAP Authentication

If you intend to authenticate the HOMER users using LDAP, install the LDAP authentication module:

# apk add homer-api-ldap

In addition, you have to allow connections to the LDAP server if using a firewall.

Changes in /etc/homer/preferences.php

Enable LDAP authentication:

Contents of /etc/homer/preferences.php

... define('AUTHENTICATION',"LDAP"); ...

Uncomment the LDAP section and add/update parameters according to your server configuration:

Contents of /etc/homer/preferences.php

... define('LDAP_HOST',"localhost"); define('LDAP_PORT',389); define('LDAP_VERSION',3); define('LDAP_BIND_USER',"cn=HOMER,ou=Apps,dc=example,dc=com"); define('LDAP_BIND_PASSWORD',"secret"); define('LDAP_BASEDN',"ou=Users,dc=example,dc=com"); ...

Add one of the following lines, depending on whether the STARTTLS mechanism shall be used to protect the LDAP connection:

Contents of /etc/homer/preferences.php

... define('LDAP_ENCRYPTION',"none"); define('LDAP_ENCRYPTION',"tls"); ...

If TLS is used, you have to make sure that the relevant root certificate is trusted. If using a self-signed root certificate, one way to achieve this is to add the TLS_CACERT parameter to /etc/openldap/ldap.conf, specifying the path to the trusted CA certificate.

Specify the users who should have admin rights:

Contents of /etc/homer/preferences.php

... define('LDAP_ADMIN_USERS',"donald,mike"); ...

Remove the parameters starting with LDAP_GROUP_ unless you want to authorize users based on group membership.

Nested Groups with Active Directory

The default settings in /etc/homer/preferences.php are intended for LDAP schemas conforming to RFC 2307. Otherwise, you may have to modify the parameters starting with LDAP_USERNAME_ATTRIBUTE_. The following example demonstrates how to authenticate and authorize users against Microsoft Windows Active Directory based on nested group membership:

Contents of /etc/homer/preferences.php

... define('LDAP_USERNAME_ATTRIBUTE_OPEN',"(&(samaccountname="); define('LDAP_USERNAME_ATTRIBUTE_CLOSE',")(memberof:1.2.840.113556.1.4.1941:=cn=HOMER,ou=Groups,dc=example,dc=com))"); ...

Database Nodes

To make your HOMER system more scalable, you may want to deploy multiple database nodes. This sections instructs how to set up an additional database node.

Install the required packages on the new database node and enable the database service:

# apk add homer-api-doc homer-db mariadb kamailio-mysql

# rc-service mariadb setup # rc-update add mariadb # rc-service mariadb start

Set up the database. You may want to disable remote root logins to the database.

# mysql_secure_installation # homer_db_init -r

You may want to change the default password for the HOMER database user. This can be done as follows:

# mysql -e "SET PASSWORD FOR 'homer_user' = PASSWORD('<password>');"

Enable the crond service:

# rc-update add crond # rc-service crond start

Override the Kamailio configuration with the HOMER template:

# cp /usr/share/doc/homer-api/examples/sipcapture/sipcapture.kamailio /etc/kamailio/kamailio.cfg

Change the capture_node parameter in /etc/kamailio/kamailio.cfg to a unique value. If you changed the database user password, update the HOMER_DB_PASSWORD parameter accordingly.

Enable the kamailio service:

# echo rc_need=mariadb > /etc/conf.d/kamailio # rc-update add kamailio # rc-service kamailio start

If using a firewall, you have to allow the reception of captured SIP packets on UDP port 9060. In addition, you have to allow the primary node to access the local database.

Finally, you have to add the database node to the primary server configuration via the web user interface. Log in as an admin user. Click on Panels, System Admin, and then Add Node. Use the following values:

Node Value of capture_node in /etc/kamailio/kamailio.cfg
Host Host name or IP address of the database node
Port 3306
DB Name homer_data
DB Username homer_user
DB Password Database password, which is homer_password unless you changed it
DB Tables sip_capture

Capture Nodes

To capture packets on a SIP server, install the HOMER CaptAgent:

# apk add captagent

Configure the capture-host and capture-port parameters in /etc/captagent/transport_hep.xml. The capture host is the primary or an additional database node. The port should be set to 9060.

Enable the service:

# rc-update add captagent # rc-service captagent start

If using a firewall, you have to allow sending the captured SIP packets to UDP port 9060 of the specified capture host.

Retention Period of Captured Packets

A cron job takes care of removing obsolete data from the capture host databases. The retention period can be adjusted by modifying /etc/homer/rotation.ini.

Retrieved from "https://wiki.alpinelinux.org/w/index.php?title=Setting_up_Homer&oldid=26249"