Configuring xymon monitoring for HydraFerret IoT

Enfield Cat's Blog: Arduino and other projects.


Introduction

xymon is used as a centralised logging and alerting system for HydraFerret. This section won't go into detailed configuration of xymon, see the xymon pages for that level of detail. The xymon project cannot answer questions about HydraFerret, nor can the HydraFerret project answer detailed questions about xymon.

Install xymon

Docker / Containers

xymon can be run as a Docker container. To use these follow the instructions on Docker Hub to install before jumping to the instructions further down this page. Several images are available to select from, including:

Ubuntu/Debian

On Ubuntu and Debian machines xymon should be available as a precompiled package, which can be installed using the following commands. The first one will install xymon, and the second will show the location of the files it installed.

sudo apt-get install xymon
dpkg -L xymon

If your Apache version is version 2.4 or greater which it will be on a new installation, then edit "/etc/apache2/conf-enabled/xymon.conf". Change the references to "Require local" to "Require all granted" or you will have difficulty access the xymon pages. This change is expected about 3 times in this file. eg:

    <IfModule mod_authz_core.c>
        # Apache 2.4+
        # Require local
        Require all granted
    <IfModule>

Other systems

On other operating systems you might need to compile your own xymon server (and optionally client), after downloading from https://xymon.sourceforge.io/ Note you will also need to check any pre-requisite packages such as rrdtool are installed on this server.

The {install-dir} referenced below may vary according to the package used to install xymon or if it is a custom compilation. This could for instance be:

To get xymon to work with Nginx, see PHP and CGI applications in Nginx page.

Configure xymon to receive HydraFerret data

Once installed, xymon will listen on port 1984 for incoming monitoring data. The ESP32 modules should be configured to send data to your server, and any firewalls should be configured to allow data to pass from the ESP32 modules to the server on port 1984. Data from unknown sources will be reported in the xymon "Ghost Client" report. To make the unit appear in xymon it needs its device name configured in the {install-dir}/server/etc/hosts.cfg file. Unless you've set the device name on the HydraFerret unit, it will default to "HydraFerret", therefore it is recommended to customise the device name on each ESP32 unit to distinguish between them.

The hosts.cfg file will show both IP address and device name. But the IP address in this file can be generally ignored (unless you want to have connectivity tests to the unit), what is important is to have a unique name for each unit. for example: lets assume an installation with multiple buildings, and two glasshouses. the hosts file allows the monitoring to be set up as follows:

group Computers
192.168.1.4 xymon

group Office
192.168.1.100 office            # noconn
192.168.1.101 workshop          # noconn

group Glasshouses
192.168.1.200 glass_1_10        # noconn
192.168.1.201 glass_1_20        # noconn
192.168.1.202 glass_1_30        # noconn
192.168.1.203 glass_2_10        # noconn
192.168.1.204 glass_2_20        # noconn
192.168.1.205 glass_2_30        # noconn

Here the "xymon" device is the xymon server, and xymon will provide a number of "out of the box" tests and graphs for it. Each of the remaining devices are HydraFerret modules, it this case we are not running any connectivity checks against them, hence the "noconn" comment in the line. As we have the noconn parameter xymon won't run a ping test against each of these units, so the IP address is effectively just a placeholder. The second parameter will match the name configured with "devicename" on each device. Some devices are more easily created with a human sensible name like "workshop". Other devices might be better defined using a matrix naming scheme, for install the glasshouse number and distance from the door.

Configure custom graphs

The default configuration of xymon includes a temperature graph in Celsius. All other graphs need to be defined, HydraFerret will already send data in a suitable format to xymon. But xymon won't know how to define the axis and labels for each graph, and there will be defined in {install-dir}/server/etc/graphs.cfg You can adjust the definitions of these graphs, but here are suggested initial graph definitions.

To set which graphs appear automatically after each test and which graphs appear in the stats column, edit {install-dir}/server/etc/xymonserver.cfg There are two quote enclosed comma separated variables which are of interest to us. Normally we want all the supported HydraFerret graphs to be included in these lists, with the HydraFerret graphs included inside the quote marks. Do not delete existing entrys but you can rearrange them. This list is suggeted to include the following.

temperature,humidity,pressure,lux,uv,co2,tvoc,volts,amps,watts

The variables are:

Further configuration

Help for new columns can be added to {install-dir}/server/etc/columndoc.csv

Maintenance

since graph data uses a round robin database, there is not normally any database maintence which needs to be done.

To delete a graph that might contain wrong data (for instance if the device name was wrongly set), delete the rrd file in:

To add/rename/delete a node on xymon, first add/rename/remove it from the hosts.cfg file, then tidy up your data by running the following on the xymon server as the xymon user:

To add a new test to a device, nothing more should be required than adding the sensor to the device. If the device has more than one of a sensor type, then give the sensor a suitable name too on the ESP32 module.

To remove a test that no longer is being checked on a device, run the following on the xymon server: ~/server/bin/xymon 127.0.0.1 "drop HOSTNAME TESTNAME"


Thank you for visiting camelthorn.cloudHome