Installing Xymon

From a package or from source? If your operating system or its ports collection packages Xymon, or you use Homebrew on a Mac, install that: see Installing from a package. Otherwise, follow the six steps below. Problems and explanations are at the end.

1. Install the prerequisites

As root, run the command for your system. A C compiler and OpenSSL come with the base system on the BSDs.

apt-get install build-essential fping libc-ares-dev \
    libldap-dev libpcre2-dev librrd-dev libssl-dev \
    libtirpc-dev

subscription-manager repos --enable \
    codeready-builder-for-rhel-N-$(arch)-rpms
dnf install \
    https://dl.fedoraproject.org/pub/epel/epel-release-latest-N.noarch.rpm
dnf install gcc make fping c-ares-devel openldap-devel \
    pcre2-devel rrdtool-devel openssl-devel libtirpc-devel

dnf install dnf-plugins-core
dnf config-manager --set-enabled crb
dnf install epel-release
dnf install gcc make fping c-ares-devel openldap-devel \
    pcre2-devel rrdtool-devel openssl-devel libtirpc-devel

dnf install gcc make fping c-ares-devel openldap-devel \
    pcre2-devel rrdtool-devel openssl-devel libtirpc-devel

zypper install gcc make gawk fping c-ares-devel \
    openldap2-devel pcre2-devel rrdtool-devel libopenssl-devel \
    libtirpc-devel

apk add build-base fping c-ares-dev openldap-dev pcre2-dev \
    rrdtool-dev openssl-dev libtirpc-dev

pacman -S base-devel fping c-ares openldap pcre2 rrdtool \
    openssl libtirpc

pkg install gmake fping c-ares openldap26-client pcre2 rrdtool

pkg_add gmake fping libcares openldap-client--gssapi pcre2 \
    rrdtool

pkgin install gmake fping libcares openldap-client pcre2 \
    rrdtool

pkg install developer/gcc/gcc-c-15 developer/build/gnu-make \
    library/pcre2 library/libcares system/network/ldap/openldap \
    diagnostic/fping
pkgutil -y -i rrdtool_dev
crle -64 -u -l /opt/csw/lib/amd64

CC=gcc MAKE=gmake ./configure --server --pcreinclude /usr/include/pcre \
    --pcrelib /usr/lib/amd64 --careslib /usr/lib/amd64 \
    --ldaplib /usr/lib/amd64 --rrdinclude /opt/csw/include \
    --rrdlib /opt/csw/lib/amd64

port install gmake fping pcre2 rrdtool c-ares openssl openldap

brew install pcre2 rrdtool fping openssl@3 openldap

2. Create the "xymon" user

Xymon runs as a dedicated user with a home directory, e.g. useradd -m xymon. configure offers that home directory as the place to install Xymon.

3. Build and install

In the unpacked Xymon source, as root, accepting configure's default answers:

./configure --server
make
make install

On the BSDs, macOS and Solaris, use GNU make: MAKE=gmake ./configure --server, gmake, gmake install.

The steps below use configure's default answers: the "xymon" user, ~xymon/server for the installation and /xymon/ for the web pages. If you gave other answers, use yours.

4. Configure the web server

Add ~xymon/server/etc/xymon-apache.conf to your Apache configuration and restart Apache. If configure put the administration pages in a directory of their own (it asks), protect them with a password:

htpasswd -c ~xymon/server/etc/xymonpasswd admin

5. Start Xymon

su - xymon -c "~xymon/server/xymon.sh start"

6. Check

After a couple of minutes, open http://your.server/xymon/: the Xymon server shows its own statuses. To start Xymon at boot, see Starting Xymon at boot.

Next steps

Congratulations, you now have a running Xymon server!

The next step is to configure it to monitor your servers and applications, and to set up the alerts to send you e-mail, call a pager, or send an SMS in case of trouble. For that, see the Xymon configuration guide.

Installing from a package

A package installs the prerequisites itself, and usually starts Xymon at boot. Distribution packages follow Xymon's releases; building from source, as above, gives the current code.

macOS (Apple Silicon and Intel) using Homebrew

The easiest way to install Xymon on a modern Mac is through the official Homebrew tap, which provides a full server formula and a lighter client-only formula:

brew tap xymon-monitoring/xymon
brew install --HEAD xymon-monitoring/xymon/xymon-server     # full server
brew install --HEAD xymon-monitoring/xymon/xymon-client     # client only

and run it under launchd with:

brew services start xymon-server      # or: xymon-client

The formulas install everything under the Homebrew prefix (the server tree ends up in $(brew --prefix)/opt/xymon-server/server) and provide a launchd service. They do not create a dedicated "xymon" user or configure a webserver - edit etc/hosts.cfg (server) or the XYMSRV setting in etc/xymonclient.cfg (client), and set up the web frontend as described in the "Configuring your webserver" section above. As no Xymon release tarballs are published yet, the formulas are --HEAD-only and build the latest Git revision; see the tap README for how to upgrade a HEAD install. The SYSV IPC requirements described in the prerequisites apply on macOS too, where the stock limits are too low for xymond; the xymon-server formula's caveats, shown by brew info xymon-server, give the settings to raise. They allow 64 segments, 64 MB per segment and 128 MB in all, enough for a MAXMSG_STATUS up to about 40 MB. A second macOS kernel setting hides the TCP counters the client reports, which leaves the TCP half of the netstat graph empty: see the netstat graph has no TCP data on macOS below.

To build from source instead, install the dependencies with Homebrew:

brew install pcre2 rrdtool fping openssl@3 openldap

then run ./configure --server, make and make install as described above. The configure script automatically detects libraries installed under the Homebrew prefix (/opt/homebrew on Apple Silicon, /usr/local on Intel Macs), including the keg-only openssl@3 and openldap packages which Homebrew does not symlink into the main prefix; MacPorts (/opt/local) is detected as well.

Testing a development branch or pull request: the formulas always build the "main" branch. To build a feature branch instead (e.g. to test a pending pull request on a Mac), point the head stanza of your local tap checkout at that branch and rebuild:

brew edit xymon-monitoring/xymon/xymon-server
   # change:  head "https://github.com/xymon-monitoring/xymon.git", branch: "main"
   # to:      head "https://github.com/<fork>/xymon.git", branch: "<feature-branch>"
brew reinstall --HEAD xymon-monitoring/xymon/xymon-server

When done, restore the tap to its pristine state and rebuild from main:

git -C "$(brew --repository xymon-monitoring/xymon)" checkout -- .
brew reinstall --HEAD xymon-monitoring/xymon/xymon-server

Two things to be aware of: the edited tap is a dirty git checkout, so brew update will warn about it until you revert the change; and a HEAD reinstall replaces the entire keg including its etc/ directory, so back up your edited configuration files (hosts.cfg, xymonserver.cfg, xymonclient.cfg) before rebuilding.

If something goes wrong

xymond does not start

Xymon uses 9 shared memory segments, ranging in size from 32 KB to 512 KB (2464 KB total) in the default configuration; and 9 sets of 3 semaphores. Experience shows that some systems need tuning to provide the necessary IPC resources that Xymon uses.

The total grows with the MAXMSG_* settings in xymonserver.cfg, which size the segments: MAXMSG_STATUS sizes three of them. When the system refuses one, xymond does not start, and logs "Could not get shm of size ..." followed by "Cannot setup ... channel". The limits on their size are "kernel.shmmax" (one segment) and "kernel.shmall" (all of them) on Linux, the same names under "kern.sysv." on macOS, and "project.max-shm-memory" on Solaris 10 and later. A stock macOS allows 8 segments per process, too few even for the default configuration, and 4 MB in all (see macOS using Homebrew above). See http://www.xymon.com/archive/2005/08/msg00183.html for more information about these issues.

What xymond needs, in KB: the largest segment is the largest MAXMSG_* setting, and the total is

3 x MAXMSG_STATUS + 2 x MAXMSG_CLIENT + MAXMSG_DATA + MAXMSG_NOTES + MAXMSG_USER + MAXMSG_ENADIS

as long as MAXMSG_STACHG and MAXMSG_PAGE are left to follow MAXMSG_STATUS, and MAXMSG_CLICHG to follow MAXMSG_CLIENT, which is their default. For example, MAXMSG_STATUS="1024" with the other settings at their defaults needs a 1024 KB segment and 3 x 1024 + 2 x 512 + 256 + 256 + 128 + 32 = 4768 KB in all: shmmax of at least 1048576 bytes, and shmall of at least 1192 pages of 4 KB. That is more than the 4 MB a stock macOS allows.

The defaults of a recent Linux (kernel 3.16 and later) and of Solaris 10 and later are usually far above this, so the limits mostly need raising on macOS and on older systems.

The netstat graph has no TCP data on macOS

The netstat graph is drawn from the client's "netstat -s" output. macOS ships the kernel setting "net.inet.tcp.disable_access_to_stats" at 1, which the kernel describes as "Disable access to tcpstat": netstat then reports every TCP counter as 0, to every user and every process, while the UDP counters are real. The client sends those zeros, and xymond_rrd stores the graph's TCP data sources (tcpActiveOpens, tcpCurrEstab, tcpOutDataBytes and the rest) as unknown, so only the UDP lines of the graph are drawn. Seen on macOS 26 and 27; Apple documents nothing beyond that description.

The setting can be changed by root, and takes effect at once:

sudo sysctl net.inet.tcp.disable_access_to_stats=0

It returns to 1 at reboot, so to keep it add the line net.inet.tcp.disable_access_to_stats=0 to /etc/sysctl.conf, the same file that holds the shared-memory limits above. The setting is unrelated to the shared-memory limits, and to the socket list the ports test reads, which the client collects by other means when netstat does not provide it.

The build fails

Note: Although many systems have these libraries pre-installed, they often include only the run-time libraries and not the files that are needed to compile and build programs such as Xymon. So if you think you have all of these libraries installed but Xymon will not build, do check that you have the development files installed as well. Often these are in packages called "something-dev".

HP-UX users should note that the HP-supplied C compiler is known to mis-compile the lib/environ.c file, and produces an output file lib/environ.o of length 0 bytes. HP-UX users on the Xymon mailing list agree that the default C compiler shipped with HP-UX should not be used to compile Xymon - it is only for re-building the HP-UX kernel. The GNU C compiler works fine on HP-UX. More details in this e-mail from the Xymon mailing list.

No graphs

NetBSD: the pre-built rrdtool package links against the base X11 sets in /usr/X11R7 (e.g. libfontconfig.so.2). These are not present on systems installed without X11, and cannot be added with pkg_add. Install the xbase set - no reinstall needed (adjust release and architecture):
ftp https://cdn.netbsd.org/pub/NetBSD/NetBSD-10.1/amd64/binary/sets/xbase.tar.xz
tar -xJpf xbase.tar.xz -C /
Without it, the RRDtool link test fails and Xymon builds with trend-graph support disabled.

Reference

What the prerequisites are for

• PCRE2 - Perl Compatible Regular Expression library, version 2 - is a library for matching text-strings. It is available from https://www.pcre.org/. Xymon needs PCRE2; the older PCRE library (version 8.x) is no longer used. Xymon 4.3.30 is the last release that builds with it.
• RRDtool is a library for handling the Round-Robin Databases used to hold the historical data Xymon gathers. It is available from http://www.mrtg.org/rrdtool/. No minimum version is set; the versions current Linux and *BSD systems ship, which have it pre-packaged, are the ones tested.
  Note that RRDtool requires various graphics-libraries. RRDtool 1.2.x uses libpng, newer versions rely on the Cairo graphics library.
• c-ares is an asynchronous DNS resolver library, required to build the "xymonnet" network test tool. Xymon no longer ships a bundled copy, so the c-ares development files must be installed (packages are commonly named libc-ares-dev, c-ares-devel or c-ares). It is available from https://c-ares.org/
• fping is used for the network ping tests. Xymon's own xymonping does not work at the moment, so fping is required. Every system below has it as a package named "fping".
• OpenSSL is a library for communicating with network services, that use SSL encryption - e.g. secure websites. Although this library is not absolutely required for Xymon, I strongly recommend that you install it because sooner or later you will probably need it anyway. It is available from http://www.openssl.org/.
• OpenLDAP is used to query LDAP directory servers. If you would like to test that your directory server is up and running, you will need this library. It is available from http://www.openldap.org/

xymon.sh

Xymon runs as the user configure was given ("xymon" by default), and xymon.sh refuses to start it as any other. Log in as that user and run
XYMONHOME/xymon.sh start
where XYMONHOME is the "server" directory of the installation - with the default answers to configure, ~xymon/server. The same script also takes stop, restart and status; reload sends xymond a HUP signal so it re-reads hosts.cfg, and rotate sends a HUP to every Xymon program that keeps a pid file, so they reopen their logfiles after a log rotation.

Starting Xymon at boot

Building from source installs nothing that starts Xymon when the system boots; a Xymon package from your operating system does that for you. Otherwise, have your system's startup run, as root, something like
su - xymon -c "XYMONHOME/xymon.sh start"
and the matching stop at shutdown - through an init script, an rc.d script, a launchd job or /etc/rc.local, whichever your system uses. Since xymon.sh only accepts the xymon user, a script running as root must switch to it, as above.

What runs

xymon.sh starts xymonlaunch, which starts and watches every other Xymon server program. Which programs those are is set in etc/tasks.cfg; with the default file, these run all the time:

• xymond is the network daemon that receives status updates from the clients and the network test tool. It also provides the current status of all your systems to the tool that generates the webpages.
• xymond_channel passes messages from xymond to each of the helper programs below; there is one per helper.
• xymond_history records the history of status changes for each item you monitor: when it was red, when it was green, and what the error reported at 2:51 AM last Friday looked like.
• xymond_alert sends out alerts when your servers begin to report a critical status.
• xymond_client analyses the data the Xymon clients send, and turns it into statuses such as cpu, disk and memory.
• xymond_rrd updates the RRD files with the numeric data from the status reports, to track e.g. how the disk utilization of a server changes over time. There are two of these, because the data can arrive in two different ways.
• xymond_hostdata saves the latest data a client sent whenever one of that host's statuses goes red, yellow or purple, so you can see what it reported around the time a problem occurred.

Others run at intervals: xymongen updates the webpages, xymonnet runs the network tests (and xymonnet-again.sh repeats the failing ones on a faster cycle), combostatus computes combined statuses, and the Xymon server's own client reports on the server itself. More programs are listed in tasks.cfg but disabled, for setups that need them - storing status files, proxying, fetching from clients that cannot connect, distributing to other servers.

The server's statuses

Each of the little faces indicate an item that is being monitored for this host. Here you see the default set of items that the Xymon installation sets up for a Xymon server:

• bbd is the availability of the Xymon network daemon.
• conn is a simple "ping" test of the host.
• http is the status of the HTTP-server running on the Xymon server.
• info contains information about how the host is configured in Xymon, such as what IP-address it has, what network tests are being run against this host etc.
• trends is a collection of the various RRD graphs available for this host.
• xymond is the status of the Xymon daemon, with statistics about how many monitored items are being tracked.
• xymongen is the status of the xymongen tool, which updates the webpages.
• xymonnet is the status of the xymonnet network tester that performs all of the network tests you configure in Xymon.

The server's own client adds its columns too: cpu, disk, memory and others.

You can click on each of the green icons to see a more detailed status.

Upgrading

It is safe to run make install when upgrading a Xymon server. It installs the programs, adds new template-files that were not present in your previous version, and updates your configuration files with any new sections that have been added. Any changes you have made yourself are preserved.

configure

You can see what configure looks like, and how the Apache configuration it installs looks here.