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
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:
In erlier versions the configuration was done by adding
--docurl="http://docs.example.com/%s" to the
XYMONGENOPTS-variable in the
%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.
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:
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
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"
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
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” ;)