Breaking large monolithic configuration files into smaller chunks is a common technique for keeping them maintainable. Xymon too has very good support to modularise the configuration. Unfortunately this is rather hidden (in the otherwise excellent) documentation.

This is especially helpful if Xymon extensions are installed or heavy customisation of the default-configuration is needed. Later updates of add-ons and Xymon itself run much smoother with such a modularized setup.

There are two directives that help with breaking the configuration files into separate files:

  • include: to include a specific file at the location of the tag. This is very helpful in hosts.cfg to break it into up into files that match the structure of the network or the responsibilities for the systems.
  • directory: to include all files in a directory.

The include tags can be nested too, so an included file may itself contain include tags.

Examples to follow …

using include for the hosts-file

The include-tag does what one would expect: it includes the specified file at the current position. The hosts.cfg-file may contain the following line

include /usr/lib/xymon/server/etc/hosts-dmz.cfg

to include the file that contains all monitored hosts in the DMZ only.

That way the main hosts.cfg may only contain the basic structure and all (main-) pages are in separate files that are included at the correct position.

For larger teams this also helps with collisions with file-edits.

using directory for new graphing definitions

To extend the default graphs known by Xymon in graphs.cfg the order and position of the included files does not matter so using the directory-directive is easier. It’s common (and the Debian package already does this) to have the directory to be included named like the config-file with the .cfg replaced by .d.

After appending the tag to graphs.cfg wit

echo "directory /usr/lib/xymon/server/etc/graphs.d/" >> graphs.cfg

any files placed /usr/lib/xymon/server/etc/graphs.d/ will be read and appended to the graphing definition automatically. So all graphing definitions of extensions can be placed in that directory to keep this neatly separated and updateable. Even removing an extension is just a matter of deleting the corresponding file instead of searching the relevant sections in graphs.cfg and manipulating the main graph definition file.

Also see my sample Xymon extension ttime: the graphing definitions for that extension are in the file ttime-graph.cfg:

  • append the directory-tag to graphs.cfg (if not already present):

      echo "directory /usr/lib/xymon/server/etc/graphs.d/" >> graphs.cfg
  • and copy the graphing-definition from the extension to that directory

      $ ls -1 /usr/lib/xymon/server/etc/graphs.d/

more advanced uses

The directory-tag also works in xymonserver.cfg. It is even possible to append to already defined variables.

Again the ttime extension is used to demonstrate this:

  • xymonserver.cfg: Append the inclusion of the directory to the file (if not already present)

      echo "directory /usr/lib/xymon/server/etc/xymonserver.d/" >> xymonserver.cfg

    (using the paths to /usr/lib/xymon also works on Debian/Ubuntu, as there is a symlink) and place the configuration file from the extension (ttime-xymonserver.cfg in this case) there:

      $ ls -1 /usr/lib/xymon/server/etc/xymonserver.d/

    That file contains the required additions to the TEST2RRD– and GRAPHS-variables in the main configfile and the new SPLITNCV_ttime-variable to configure the NCV-graphing module of Xymon:

      $ egrep -v '^#|^$' /usr/lib/xymon/server/etc/xymonserver.d/ttime-xymonserver.cfg
  • clientlaunch.cfg: This works the same way as above, just replace xymonserver by clientlaunch.

The graphing was shown above already.

and more …

This also works with the other configuration-files, e.g. adding a new simple tcp-check for CFEngine3 could be done by adding the the directory-tag to the protocols.cfg file and creating a new definition file like:

$ cat /usr/lib/xymon/server/etc/protocols.d/cfengine.cfg
## CFEngine3 default-port
    port 5308

And test the hosts running cf-serverd of CFEngine3 by adding the (new) cf3conn-tag to them in hosts.cfg.


The two options shown above to break up the configuration files of Xymon can make the overall configuration much cleaner, easier to understand and mutch better maintainable.

Of course directory ignores common package-manager files from deb and rpm packages, RCS-file, dot-file and files ending with a tilde.

The official documentation can be found in hosts.cfg(5) in the section “TAGS RECOGNIZED BY ALL TOOLS”.