Homer

Homer is a SIP packet capture and analysis system with very poor documentation. It's one of the very few open-source applications I've come across which has been around for over 10 years and does not have a wikipedia page.

https://github.com/sipcapture/homer/wiki/Using-Homer-7 is probably the best example I have come across anywhere of a "documentation" page which is absolutely useless.

If you want to install it under Debian you can find some instructions and if you ask on the mailing list why they don't work you'll get pointed at some others instead.

It's not difficult to adapt these so that they work as well for Devuan and they do for Debian (not that, at the time of writing this, Debian stable "bookworm" is not supported, and therefore neither is Devuan stable "daedalus").

Once you've got things installed, though, what do you do next? I distinctly dislike documentation which lets you install something and then leaves you in the dark about how to make it actually do something.

I don't consider github to be a suitable place to put documentation in the first place (unless you create a very good index to it so that people can find things) because there is no structure to it - it's just a hierarchical tree of web pages with no guidance for the end user to be able to find what they need.

https://github.com/sipcapture/homer-app looks like it tells you how to configure the web front-end, but as far as I can tell all of this has been done for you by the installer script, so these notes are pointless.

Clicking on the homer topic link on these pages illustrates very well why github is not the place to put all your project's documentation - if there's no index or structured walk-though of "this is how it works; this is how to install it; this is how to configure it; this is how to use it" then the new user is simply baffled by too much information in a totally unstructured format with no clue where to start and what to do next.

So, here are my notes on how to get Homer installed and doing something useful under Debian or Devuan.

Note: I haven't achieved this. I think these notes are useful for getting it installed and configured, but I've not yet been able to see any data in its web interface.

Homer is a client/server application (or perhaps agent/server is a more accurate description).

You need to install the Homer Server which will collect and display the data about your calls, and you either need to configure your SIP application (Asterisk, FreeSwitch etc) to send data to the server, or you need to install the Homer Agent on the machine/s handling your phone calls.

If you're using Debian, the homer-installer page seems to be a good place to start. Just make sure you're not trying to use the current stable release of Debian for now…

If you're using Devuan, it's not hard to modify the Debian script to create one which works. I've included Daedalus, so the following description covers my experiences of installing and using Homer under current stable Devuan.

In my case I wanted to capture data from Asterisk and FreeSwitch.

Apparently both of these contain native support for sending data to Homer, so I have not investigated installing the Homer Agent.

Update: It turns out that Asterisk only has native support for HEP if you are using the PJSIP channel driver (this is not documented), so if you are still using the SIP channel driver, you do need the Homer Agent.

Ensure that both res_hep and res_hep_rtcp are listed in /etc/asterisk/modules.conf as modules to be loaded. If you're using chan_pjsip, also load module res_hep_pjsip. Edit /etc/asterisk/hep.conf and enter the appropriate details for your Homer server.

Restart Asterisk.

As far as I can tell so far, it doesn't work (using Asterisk 16.28.0). tshark shows no packets going to the Homer server.

Update: Somebody found out that HEP doesn't work with chan_sip, and even filed a bug report to get the documentation fixed. The news clearly has not spread.

Edit /etc/freeswitch/autoload_modules/sofia.conf.xml and remove the XML commenting <!-- … --> around param name="capture-server" (the one which contains hep=3). Edit the value to point at your Homer server.

Edit each active SIP profile under /etc/freeswitch/sip_profiles and change param name="sip-capture" value="no" to param name="sip-capture" value="yes".

Restart FreeSwitch.

A good amount of the configuration seems to be done for you by the above script. For me, the installer set up everything necessary (as far as I can tell so far) and started the services. I could then connect to the web interface on http://server.domain.com:9080

The first thing I did was to change the admin user password; the second was to change the support user password - otherwise you've set up a monitoring system with open access from the Internet, on a standard port number, with default access passwords. I think it is poor practice that Homer neither requires you to change the password on first login, nor displays a warning message that the password is set to a documented default. The installer also neither gives you the opportunity to set passwords of your choosing, nor tells you that you should change the password immediately.

Point a browser at http://server.domain.com:9080 and log in. You will almost certainly see a search facility on the left which you don't understand, and an empty display panel on the right, which shows you nothing of any interest.

It'll stay like this until you find out what you have to do to get Homer doing what the screenshots in the documentation illustrate - the ones which say nothing about how they were achieved.

For the time being, I haven't found out either.

Once you reboot the machine Homer is running on, you find out that it isn't running any more, because the installer failed to set up an init script for it.

I'll put one here once I find (or make) a working example.

Go up
Return to main index.