Wouldn’t it be great to integrate your (web based) documentation into the Xymon webinterface, so you can easily check the docs for the host you are currently looking at?

While there is a very basic “notes” mechanism included in Xymon I would recommend to use an external documentation system for more flexibility and features.

This article shows how to integrate Xymon with an external documentation system.

Chances are that you already have some sort of documentation system for the systems your are maintaining (some wiki?). If you don’t have one you really should consider setting one up. An article for setting up ikiwiki is in the works and will be posted soon.

Linking to the Documentation

Since Xymon v4.3.5 the option HOSTDOCURL in xymonserver.cfg can be defined to point to the documenation-URL. The hostname defined in hosts.cfg is used as the identifier for the documentation file:

HOSTDOCURL="http://docs.example.com/%s"

In erlier versions the configuration was done by adding --docurl="http://docs.example.com/%s" to the XYMONGENOPTS-variable in the xymonserver.cfg.

The placeholder %s is expanded to the hostname. Once this is configured the hostnames on the web interface will turn in to a link that points to the documentation. As a slight nuisance all hostnames turn into a link, regardless weather or not documentation exists.

Currently this is the only escape available, in particular the page a host is configured on is not available, so the documentation files have to be in a flat (non-) hierarchy.

A script with some heuristic/find logic might help to work around this in some situations. Some might even store the documentation in a database — which is breaking the KISS principle in my opinion.

Page Titles

The page titles also become links in the same way. This can be utilised to collect more general information on the page/group level. Depending on the organisation of pages in the xymon configuration the “page documentation” can hold general setup instructions for this “page/group” of machines, mass-changes to all these machines, deployment dates, update information, … you get the idea.

Configure this Using a Modularised Configuration

As pointed out earlier (How to Modularize the Configuration Files of Xymon) the possibility to modularise most configuration-files of Xymon is a bit hidden in the (otherwise excellent) documentation.

Quick recap and how to configure the documenation-linking feature: For xymonserver.cfg using the directory-statement is a good choice, as extensions often require changes that can be kept in separate files without further adjustments of the main-file:

  • if not already present add the directory-statement to the server configuration

      echo "directory /usr/lib/xymon/server/etc/xymonserver.d" >> xymonserver.cfg
    
  • create a documentation-file in that directory, that contains the required documentation URL

      # cat /usr/lib/xymon/server/etc/xymonserver.d/documentation
      HOSTDOCURL="http://docs.example.com/%s"
    

Summary

A final note about the basic builtin notes mechanism of Xymon. In the default configuration (i.e. no HOSTDOCURL configured) files from the directory defined in XYMONNOTES (defaulting to $XYMONHOME/www/notes/) are served as documentation. Beside being builtin the advantage of this is that only hostnames, for which a documentation file exists, turn into links.

If the documentation is compiled into static html-fles (like Ikiwiki does) the builtin “notes”-directory could be chosen as the destination. That way one could use the best of both worlds. Up to now I did not set it up that way, as the documentation systems either were not on the same host as the xymon server and/or were used for other things beside “simple” host documentation.

Integrating Xymon with an external documenation system is very easy and make it much faster and convenient to check the latest notes for the monitored hosts. This might even motivate to write some journal for individual hosts as now the documentation is “at your fingertips” ;)