Extension:Nagios

The Nagios extension adds Nagios tables to MediaWiki pages. The information is pulled from a Nagios server and refreshed within the page at given intervals.

Introduction
With this extension, MediaWiki provides a more configurable frontend for Nagios, and adds the ability to include realtime information in your documentation.

The Nagios extension lets users place one or more Nagios tables in a wiki page using  tags. These tables are customised using the parameters provided to Nagios CGIs, and updated at regular intervals without having to refresh the page.

If combined with Check_MK and livestatus-slave, then realtime data is also presented when hovering over links in those tables. See an example at http://linuxproblems.org/wiki/NagiosGallery.

The nice thing about presenting Nagios in Mediawiki is that one can make use of templates to easily reuse the views or tables on other pages. Also  tags can be placed in  tags and the monitor page styled however required.

Dependencies
This extension requires a nagios backend server with read access. It has been tested with the Centos 6.5 version of Nagios 3.5.1. The graphs displayed in the example are produced by pnp4nagios.

The following are optional dependencies but help get the most out of this extension:


 * Configure Nagios with the livestatus broker module


 * And set up livestatus as a web service using livestatus-slave

Configuration Parameters
The following variables can be tuned in LocalSettings.php.


 * $wgNagiosRefresh: default 60 (seconds). This is the interval at which to fetch data from Nagios.
 * $wgNagiosLiveStatus: default false. Change to true if livestatus-slave is set up.
 * $wgNagiosPnp4Nagios: default false. Set to true if PNP4Nagios is used.

Usage
To insert a Nagios table, add the Nagios tag with the attributes mentioned below. Tables are imported using the parameters provided to status.cgi and extinfo.cgi in Nagios, for example the following url:

http://linuxproblems.org/nagios/cgi-bin/status.cgi?hostgroup=webhosts&style=hostdetail&hoststatustypes=2&hostprops=0

would be entered in a wiki page as:

Web Hosts

and this would display the following table:



There is limited online documentation about these parameters but perhaps the best resource is the icinga site at http://docs.icinga.org/latest/en/cgiparams.html#cgiparams_expl. Not all of them are included in the Nagios extension yet but will be if required.

Tag attributes
The following attributes can be added to  tags to construct a table and the table title is placed between the tags as so:

Title


 * nagiosurl               : This is a mandatory attribute and should be the url of the nagios server with a trailing slash eg, http://www.mysite.com/nagios/
 * pnp4url                 : This is the url of the pnp4nagios server with a trailing slash eg, http://www.mysite.com/pnp4nagios/ . If not specified it defaults to the same website running nagios.
 * extended                : display extended information (default: false)
 * host                    : display all hosts or a specific host whose services should be displayed
 * hostgroup               : display all hostgroups or one specific hostgroup whose hosts and services should be displayed
 * hoststatustypes         : display hosts in a given state 1=Pending; 2=Up; 4=Down; 8=Unreachable
 * service                 : display all services or a specific service
 * servicegroup            : display hosts and services for all servicegroups or one specific servicegroup
 * servicefilter           : display services matching a given pattern
 * servicestatustypes      : display state the services should be in 1=Pending; 2=OK, 4=Warning; 8=Unknown; 16=Critical
 * style                   : display overview; detail; summary; grid; hostdetail
 * type                    : hosts; hostgroups; services; servicegroups; contacts; contactgroups; timeperiods; commands; hostescalations; serviceescalations; hostdependencies; servicedependencies
 * type                    : hosts; hostgroups; services; servicegroups; contacts; contactgroups; timeperiods; commands; hostescalations; serviceescalations; hostdependencies; servicedependencies

If unsure about which attributes to use, the easiest way is to hover over a link to the required table in Nagios, and copy the parameters from that.

Examples
Here are some examples to help get started. Note that the images below are just screenshots. For a real life example see http://linuxproblems.org/wiki/NagiosGallery.

Host Groups
Web hosts



Overview
Chef Clients



Detail
Filesystem Group for Backups



Host
Host www</Nagios>



Service
CPU Load on Centos Host</Nagios>



Customised Views
<pre style="white-space: pre-wrap; white-space: -moz-pre-wrap; white-space: -pre-wrap; white-space: -o-pre-wrap; word-wrap: break-word;">All non-OK services which are neither in downtime nor acknowledged</Nagios>



Styling
There are all sorts of ways to style Nagios tables on MediaWiki pages so this is just one example to demonstrate the idea. Here there are 3 tables grouped together on the same row. They are wrapped within a div tag, and the style applied to the div. Web hosts</Nagios>

Physical hosts</Nagios>

Virtual hosts</Nagios>



Templating
In terms of the Nagios Extension, Templates could be aligned to a hostgroup, or servicegroup. For example, imagine a wiki page such as Template:DMZWebHosts, then add a nagios table that filters out the DMZ Web hostsgroup. Now when it comes to documenting pages for DMZ applications, there's an easy way to display the web hosts by adding.

Authentication
The Nagios extension is not designed for administration, but does require read access. Refer to the documentation on authenticating to the Nagios CGIs at http://nagios.sourceforge.net/docs/3_0/cgiauth.html

If authentication is required, the nagiosurl can be specified as follows:

nagiosurl=http://rouser:ropass@linuxproblems.org/nagios/

The obvious downside there being that the password is then in the wiki page.

Authentication on the Nagios Apache server can be configured to handle requests without requiring a password. There are some helpful notes on the NagVis Extension page about authentication

Here are two possible workarounds. In both cases a read-only user is configured in the Nagios cgi.cfg file as shown below. <pre style='width:60%'>
 * 1) READ-ONLY USERS
 * 2) A comma-delimited list of usernames that have read-only rights in
 * 3) the CGIs.  This will block any service or host commands normally shown
 * 4) on the extinfo CGI pages.  It will also block comments from being shown
 * 5) to read-only users.

authorized_for_read_only=rouser

Method 1
In this method, the Nagios web server gives read access by default to any users on the internal network 192.168.1.0\24.

<pre style='width:60%'> ScriptAlias /nagios/cgi-bin/ "/usr/lib64/nagios/cgi-bin/"

<Directory "/usr/lib64/nagios/cgi-bin/"> Options ExecCGI AllowOverride None

AuthName "Nagios Access" AuthType Basic AuthUserFile /etc/nagios/passwd Require valid-user Order allow,deny Allow from 192.168.1 SetEnvIf Remote_Addr 192.168.1 REMOTE_USER=rouser Satisfy Any </Directory>

Alias /nagios "/usr/share/nagios/html"

<Directory "/usr/share/nagios/html"> Options None AllowOverride None AuthName "Nagios Access" AuthType Basic AuthUserFile /etc/nagios/passwd Require valid-user Order allow,deny Allow from 192.168.1 SetEnvIf Remote_Addr 192.168.1 REMOTE_USER=rouser Satisfy Any </Directory>

Method 2
This method provides an entry point with read access for all users. It adds a local proxy on port 5080 to the nagios web server and forwards all requests with an authorization header so it appears as if the user is already authenticated. Obviously choose a different port if 5080 is already in use.

Determine the authorization header value for the read-only user. One way to do that (on Linux) is passing the username:password through base64, but you could just as easily retrieve it from Fiddler or Firebug doing a network capture. -bash-4.1$ echo "rouser:rouser" | base64 | xargs -I{} echo "Basic {}=" Basic cm91c2VyOnJvdXNlcgo==

Add a VirtualHost container that listens on port 5080 as shown below, to the nagios configuration in Apache. Replace the authorization header value with your own read-only user.

[root@centos conf.d]# cat /etc/httpd/conf.d/nagios.conf

Listen 5080 <VirtualHost _default_:5080> ProxyPass /nagios http://127.0.0.1/nagios ProxyPassReverse /nagios http://127.0.0.1/nagios ProxyPass /pnp4nagios http://127.0.0.1/pnp4nagios ProxyPassReverse /pnp4nagios http://127.0.0.1/pnp4nagios RequestHeader set authorization "Basic cm91c2VyOnJvdXNlcg==" </VirtualHost>

ScriptAlias /nagios/cgi-bin/ "/usr/lib64/nagios/cgi-bin/" ...

Now in the wiki page, specify the urls on port 5080. <pre style="white-space: pre-wrap; white-space: -moz-pre-wrap; white-space: -pre-wrap; white-space: -o-pre-wrap; word-wrap: break-word;">All hosts</Nagios>

Credits
This extension was inspired by Extension:NagVis and uses the following software:

Pretty Powerful Tooltips at http://qtip2.com/

PHP Simple HTML DOM Parser at http://simplehtmldom.sourceforge.net/