Integrating the Ikiwiki myiki created in the earlier articles with a Xymon Server now only requires one configuration addition on the Xymon side. As the wiki might be used for other content we put the host documentation in a separate place.

We will also create a “sitemap”-like page for all xymon files that is kept up-to-date automatically.

First we prepare a sub-dir for our host documentation we link to from the xymon web interface:

$ pwd
/home/vagrant/myiki
$ mkdir xymon

As outlined in How to Integrate Xymon With a Documentation System we add HOSTDOCURL to have the hostnames in the Xymon web interface link to the wiki.

HOSTDOCURL="http://ikiwiki.local/~vagrant/myiki/xymon/%s"

The Xymon server is named bb.local. We create a documentation (markdown) file for this host and publish it:

$ echo "# docs for bb.local" > xymon/bb.local.mdwn
$ git add xymon/bb.local.mdwn
$ git commit -m "add xymon/bb.local.mdwn docs" xymon/bb.local.mdwn
[master 3a883be] add xymon/bb.local.mdwn docs
(...)

Add a (wiki) link to that new page on the main-page for convenience

$ echo -e "\n\n[[xymon/bb.local]]" >> index.mdwn
$ git commit -m "add wikilink" index.mdwn
$ git push

Now all hostnames in the Xymon web interface are links and if you click them you are directed to the wiki-page.

Note the all hostnames become links, no matter weather or not a corresponding wiki-page exists. This is a minor nuisance that can be solved by creating documentation for all hosts (a good idea anyway).

Creating sitemap-pages automatically

To have a better overview of the host documentation already available and to aid navigating myiki creating a “sitemap” is a good thing ™.

Adding individual links on the index page for each host is not feasable. Ikiwiki provides the map directive that makes creating sitemaps very easy.

To have a page listing all the files from our xymon/-directory we create the xymon.mdwn on the top-level directory with the following contents:

[[!map pages="./xymon/*"]]

for convenience add a link to that page to the startpage

$ echo -e "\n\n[[xymon]]" >> index.mdwn

Commit both changes (and push to trigger the update). As new documenation files are created in ./xymon/ the xymon-page is automatically updated from now on.

Final words

This article series walked you through the setup of Ikiwiki and the final integration with Xymon. Ikiwiki is a perfect match for technical oriented teams and the git backend provides state-of-the-art multi-user and offline capabilities. Also non-tech teams can learn the few necessary git-commands fast.

If no preferred markup language is established yet I would recommend using Markdown: It’s easy to lean, flexible and widely supported by other applications.

Be aware that various “dialects” of Markdown exist. MultiMarkdown by Fletcher Penney is a good starting point. I’d suggest to use the discount implementation in that case.

The outlined concept for an integrated documentation system for Xymon can be used with any other system, that is acessible via http(s).

All Ikiwiki articles.