====== Homer ====== [[http://sipcapture.org|Homer]] is a SIP packet capture and analysis system with very poor [[https://github.com/sipcapture/docs|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 [[https://en.wikipedia.org/wiki/Homer_(disambiguation)|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 [[https://github.com/sipcapture/homer/wiki/Quick-Install|instructions]] and if you ask on the mailing list why they don't work you'll get pointed at [[https://github.com/sipcapture/homer-installer#page_with_curl-bash-installer|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 [[https://github.com/sipcapture|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 [[https://github.com/search?q=topic%3Ahomer+org%3Asipcapture+fork%3Atrue&type=repositories|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. ===== Installation ===== 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. ==== Server ==== If you're using Debian, the [[https://github.com/sipcapture/homer-installer#page_with_curl-bash-installer|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 [[https://packagecloud.io/install/repositories/qxip/sipcapture/script.deb.sh|script]] to create one which {{:technotes:homer:script.deb.sh?linkonly|works}}. I've included Daedalus, so the following description covers my experiences of installing and using Homer under __current stable__ Devuan. ==== Agent ==== In my case I wanted to capture data from Asterisk and FreeSwitch. [[https://github.com/sipcapture/hep|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 [[https://asteriskfaqs.org/2017/01/03/asterisk-users/does-hep-require-pjsip-or-does-it-also-works-with-sip.html|not documented]]), so if you are still using the SIP channel driver, you do need the Homer Agent. === Asterisk === Ensure that both **res_hep** and **res_hep_rtcp** are listed in /etc/asterisk/modules.conf as modules to be **load**ed. 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**: [[https://asteriskfaqs.org/author/oza4h07|Somebody]] found out that HEP [[https://asteriskfaqs.org/2017/01/03/asterisk-users/does-hep-require-pjsip-or-does-it-also-works-with-sip.html|doesn't work]] with chan_sip, and even filed a [[https://issues-archive.asterisk.org/ASTERISK-26717|bug report]] to get the documentation fixed. The news clearly has not spread. === FreeSwitch === 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. ===== Configuration ===== 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. ===== Use ===== 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. ===== Reboot ===== 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]].