top bar top logo bar top bar
left design right design
spacer bar

Monitoring Web Applications/Services With Nagios and WebInject

More tools by Corey Goldberg:
Subscribe To Corey's Blog Subscribe To Goldblog

Nagios Plugins

Aside from the normal usage as an individual test harness, WebInject can run in a mode that allows it to be used as a plugin for Nagios.

Nagios is an open source host, service, and network monitoring program. It is very popular and used by many big companies and organizations for enterprise monitoring. Nagios was originally designed to run under Linux, but should run on other Unix variants as well. Nagios is a very powerful, very flexible monitoring solution, with many plugins available to do almost anything, and with a large number of options for notification and service monitoring. Nagios is based on a central server that runs external commands or plugins to test distributed hosts and services.

For information on Nagios, visit

Why Another HTTP Plugin for Nagios?

There is an existing plugin for Nagios named 'check_http' that is installed along with the official set of Nagios plugins. The check_http plugin tests the HTTP service on a specified host and port. It has a variety of options and is useful for cursory monitoring of an HTTP service.

However there are instances when it would be useful to do more than send a single request to test your HTTP service. WebInject is a test harness that can operate as an intelligent test agent that is able to chain together test cases to form a functional test suite for your web application or web service.

For example, lets say you wanted to monitor a web application's functionality through multiple phases:

Phase 1 - Connect to the application
Phase 2 - Authenticate a user under the web application's login/authentication system
Phase 3 - Verify that you can navigate through the application while you're authenticated
Phase 4 - Do a sample request that accesses a database to verify it is available to the web application

This could not be done in Nagios with a simple check_http which just verifies results of a single request without chaining tests that depend on previous responses. However, we can use WebInject in the Nagios plugin mode to do the job. The idea is to consider all of these 4 consecutive WebInject tests as one global test in the Nagios environment.

WebInject Plugin Return Codes

After the test has been launched, WebInject could return these codes to Nagios:


We consider that the test is OK if all the consecutives tests have been successfully passed. The return code 0 is sent to Nagios with a message giving the global time needed to pass all the tests.


If you declare a 'globaltimeout' in your config file, this value given in seconds will be compared to the global time elapsed to run all the tests. If the tests have all been successful, but have taken more time than the 'globaltimeout' value, This is considered a WARNING. The return code 1 is sent to Nagios with a warning message stating that your tests took longer than the 'globaltimeout' to run.


We consider that the test failed (CRITICAL) if any of the WebInject declared tests in the test case file failed. The return code 2 is then sent to Nagios with a simple message describing which test number has failed. This message could easily be personalized by adding an 'erromessage' section in your test case.

WebInject Configuration

First you must install WebInject and the necessary Perl modules on your Nagios server. See the WebInject Build page for help getting it setup. Use of remote test computers with nrpe and nsca should also work but have not been tested.

Then you have to modify the config.xml and add this line in it to enable the Nagios plugin mode:


Note: you may also create an alternate config file that you can then specify on the command line used to call

This will modify the output of WebInject to be compatible with Nagios. Only one result line will be given and the return code will depend on the results of the tests.

You could also add a <globaltimeout> setting to your configuration file if you want obtain a warning if the test is slow.

Here is an example config file (we will refer to it as myconfig.xml in later examples) which is useable with Nagios:

<useragent>WebInject Application Tester</useragent>

(see the WebInject manual for a full list of config settings that are available)

Now you would setup a test case file. In each case you may specify an errormessage section which will contain a descriptive message of the problem which will be set as the problem description in Nagios interface.

Based on the example we described earlier, here is a minimal MyApplication.xml test case file:

<testcases repeat="1">

    description1="Connecting to MyAppication"
    errormessage="Unable to connect to the login page of MyApplication"

    description1="Authentication on MyApplication"
    verifynegative="User unknown"
    errormessage="Unable to authenticate user foo in MyApplication"

    description1="Navigate through MyApplication while authenticated"
    verifypositive="Welcome to the MyApplication help"
    errormessage="Unable to navigate through MyApplication even though correctly authenticated"

    description1="Test access to the database"
    errormessage="Unable to do a sample request that accesses the MyApplication database"


(see the WebInject manual for a full list of test case parameters that are available)

Once everything is setup, it is advisable to manually validate your WebInject test before configuring Nagios to use it. Continuing with our example, this can be done by launching: -c myconfig.xml MyApplication.xml

or a simple: -c config-proxy.xml

because the test case file name MyApplication.xml is already specified in the myconfig.xml config file.

To obtain more debugging information on standard output, you could change the 'reporttype' config setting to:


and of course have a look at the http.log file.

You could also force false errors by modifying the verify conditions to test everything is working in your tests and that errors are correctly signaled.

Once it works correctly, don't forget to change back the 'reporttype' setting to 'nagios'.

Nagios Configuration

You must first define a new command in the Nagios checkcommands.cfg file (assuming you have installed WebInject in /usr/local/webinject):

define command {
    command_name    webinject
    command_line    /usr/local/webinject/ -c $ARG1$ $ARG2$

Then you should declare a new service in the Nagios services.cfg file:

define service {
    use                      generic-service
    host_name                MyApplication-server
    service_description      WebInject test of MyApplication
    is_volatile              0
    check_period             24x7
    max_check_attempts       3
    normal_check_interval    1
    retry_check_interval     1
    contact_groups           myapplication-admins
    notification_interval    120
    notification_period      24x7
    notification_options     w,u,c,r
    check_command            webinject!myconfig.xml!MyApplication.xml

Of course, replace MyApplication-server with a host that you have declared in the hosts.cfg file, myapplication-admins by a contact group defined in the contactgroups.cfg file, and config-proxy.xml and MyApplication.xml by your own WebInject defined files.

After your configurations are setup, stop and start the Nagios process to reload the configuration files.

Now, if your database server is down but not the MyApplication server, you should receive a critical alert in Nagios with the message:

    WebInject CRITICAL: Unable to do a sample request that accesses the MyApplication database

If you don't have an 'errormessage' specified in your WebInject test case, you will receive something like:

    WebInject CRITICAL - Test case number 4 failed

If your test works but takes more than 20 seconds (the threshold defined by your WebInject 'globaltimeout' value), you will receive:

    WebInject WARNING - All tests passed successfully but global timeout (20 seconds) has been reached

If everything works perfectly, you will receive something like:

    WebInject OK - All tests passed successfully in 4.932 seconds


Beware that if you run WebInject with a user other than the default 'nagios', some files may be created with this user. Nagios will obtain an error if it can't write to these files. So give the ownership of these files to 'nagios' or remove them and run WebInject again as the 'nagios' user (the one declared in nagios.cfg). If you have file ownership issues, this will show up in Nagios with an error like "Return code of 13 for check of service ... on host ... was out of bounds"

Make sure the 'nagios' user has sufficient rights to execute, and to write to output files http.log, result.xml, and result.html. (if you don't have this setup correctly, you will get back invalid return codes from the plugin)