====== xymon Plugin ======

---- plugin ----
description: Provides a way for a Xymon server to monitor a DokuWiki installation
author     : Erwan Martin 
email      : public@fzwte.net 
type       : action
lastupdate : 2012-01-04
compatible : 2014-09-29a 2014-09-29 2014-05-05 2013-12-08 2013-05-10 2010-11-07 2011-05-25 2011-11-10 angua 2012-10-13
depends    : 
conflicts  : 
similar    : 
tags       : 

downloadurl: https://github.com/ZeWaren/dokuwiki-plugin-xymon/zipball/master
bugtracker : https://github.com/ZeWaren/dokuwiki-plugin-xymon/issues
sourcerepo : https://github.com/ZeWaren/dokuwiki-plugin-xymon
donationurl: 
----

:!: This plugin is currently being tested, so use it at your own risks.

===== Description =====

This plugin will allow a Xymon server to periodically fetch special pages from a Dokuwiki installation to report information and warn about potential updates or security holes.

More information about Xymon can be found at [[http://xymon.sourceforge.net/]].

==== Tests ====

The plugin will test the following things:

=== Update check ===

This test will check if a new version of Dokuwiki is available. The information is the same as the information reported at the top of the pages.

The colors are:
  * **Green**: no new (non RC) release are available
  * **Yellow**: a new (non RC) release is available
  * **Red**: a security patch is available

===== Requirements =====

  * A DokuWiki installation
  * A Xymon server
  * Ruby on the Xymon server host (1.9 or newer prefered since 1.8 has some problems with openssl)

===== Installation =====

==== DokuWiki ====

=== Install the plugin ===

Install the plugin manually by copying the directory //dokuwiki-plugin/xymon// into //lib/plugins//.

<code>
host# ll lib/plugins/xymon/
total 4
-r--r-----  1 wwwdokuwiki  wwwdokuwiki  2453 Jan  4 11:58 action.php
-r--r-----  1 wwwdokuwiki  wwwdokuwiki   224 Jan  3 11:49 plugin.info.txt
</code>

=== Configure the installation ===

The plugin will generate pages under the namespace //xymon//.

So you should:
  * Create a user who can only access this namespace
  * Forbid anyone else to see this namespace

Example:

{{ http://img690.imageshack.us/img690/4074/dokuwikixymonuser.png?nolink |}}

{{ http://img202.imageshack.us/img202/7197/dokuwikixymonacl.png?nolink |}}

The xymon script will fetch the pages using XMLRPC, so you must activate it and allow the corresponding user to use it.

Example:

{{ http://img820.imageshack.us/img820/7496/dokuwikixymonxmlrpcconf.png?nolink |}}

==== Xymon ====

=== Install the script ===

Copy the xymon script to $XYMONHOME/ext. Check the file permissions and make sure it is executable.

=== Add the task in the configuration files ===

In $XYMONHOME/etc/tasks.cfg, add:

<code>
[dokuwikicheck]
    ENVFILE /usr/local/www/xymon/server/etc/xymonserver.cfg
    NEEDS xymond
    GROUP nettests
    CMD /usr/local/www/xymon/server/ext/dokuwiki.rb
    INTERVAL 24h
</code>

=== Add your hosts in the configuration files ===

In $XYMONHOME/etc/hosts.cfg:

<code>
0.0.0.0   wikiname:dokuwiki    #noconn NOCOLUMNS:info,trends dokuwikicheck DOKUWIKIURL:http://example.com/path/to/dokuwiki/ DOKUWIKIUSER:xymon  DOKUWIKIPASSWORD:password
</code>

If you need the xymon server to connect using a ssl client certificate, you can add the corresponding fields:

<code>
0.0.0.0   wikiname:dokuwiki    #noconn NOCOLUMNS:info,trends dokuwikicheck DOKUWIKIURL:https://example.com/path/to/dokuwiki/ DOKUWIKIUSER:xymon  DOKUWIKIPASSWORD:password DOKUWIKISSLCERT:/path/to/certs/client-cert-crt.pem DOKUWIKISSLKEY:/path/to/certs/client-cert-key.pem DOKUWIKISSLCACERT:/path/to/certs/server-ca-crtchain.pem   
</code>

Make sure that the certificate files are readable by the xymon server.

Also make sure that the server certificate chain is correct, because the script will refuse to connect if the webserver can't be authenticated. If you really don't want to verify the server's identity, you can edit the ruby script yourself to allow openssl to connect anyway (but you don't want to do this because you care about your security).


===== Examples/Usage =====

When the plugin and the script are installed, the status of the installation appears in the xymon interface:

{{ http://img856.imageshack.us/img856/5175/dokuwikixymonred.png?nolink |}}

It's time to update this installation:

{{ http://img850.imageshack.us/img850/6479/dokuwikixymonreddetails.png?nolink |}}

===== Development =====

To be written

=== Change Log ===

{{rss>https://github.com/ZeWaren/dokuwiki-plugin-xymon/commits/master.atom date}}

=== Known Bugs and Issues ===

See the bug tracker at GitHub: https://github.com/ZeWaren/dokuwiki-plugin-xymon/issues

  * Ruby 1.8 does not have support for SNI. If your dokuwiki is accessible using HTTPS on a server using SNI, the certificate might not be validated and the script might not connect.

<code>
hostname was not match with the server certificate
</code>

=== ToDo/Wish List ===

===== FAQ =====

===== Discussion =====