Using check_webinject for dummies

So contrary to my previous post, this article is not SCOM related… quite the opposite actually. If you’ve been interested at all in doing some APM monitoring of web applications with Nagios you’ve probably heard of check_webinject, you may also have heard of some alternative that this blog does a great job of summarizing.

If  you have looked in to webinject however you may have noticed that information is a little bit schizophrenic, with different sites offering different explanations on how it’s used. The reason for this is that development on the original webinject appears to have ceased around 2009 and was since picked up by another developer.

Since the project changed hands some important changes were made to it that make the applications function similarly but different enough to be confusing for a first time user. So my goal here is to provide a simple, no-nonsense guide for complete beginners on getting some basic web application monitoring happening.

  1. First step is to ensure that you have all of the Webinject perl dependencies installed, use CPAN to grab anything you don’t have:

    • LWP
    • XML::Simple
    • HTTP::Request::Common
    • HTTP::Cookies
    • Crypt::SSLeay
    • XML::Parser
    • Error
  2. Next download webinject off cpan by running cpan Webinject (Installs don’t come much simpler).

  3. Download the latest version of check_webinject from https://labs.consol.de/nagios/check_webinject/ as of the writing of this article… the latest version is http://labs.consol.de/wp-content/uploads/2010/07/check_webinject-1.84.tar.gz

  4. Untar the check_webinject package into your nagios libexec directory by default that is /usr/local/nagios/libexec/ on most distros.

  5. In your nagios libexec directory create an XML file called whatever you want… I’ll call mine my_first_web_apm.xml. These XML files will contain what you want to monitor, in each XML file you will put in a series of pages/queries that you want to perform for a single Nagios check.

As an example this might be to login to your website, then go to your products page and then query for a particular item to test the response time.

In this example I am going to be showing you how to log on to a basic ASP.NET login form, the process for other languages is similar. Instead of capturing the __VIEWSTATE variable you will need to capture the JSESSIONID variable.

  1. Use whatever text editor takes your fancy to open my_first_web_apm.xml. First we need to add in the opening XML lines:
<testcases repeat="1">
</testcases>
  1. Now before we log in we need to get a session happening and actually make sure that the login page is alive… so lets add in some basic tests for the login page:
<testcases repeat="1">
  <case
    id="1"
    url="http://my_website.com/Login.aspx"
    verifyresponsecode="200"
    method="get"
    description="Get login page"
    parseresponse='__VIEWSTATE" value="|"|escape'
    label="login_load"
    warning="6"
    critical="8"
  />
</testcases>

That’s a lot of stuff… so what does it all mean:

  • Id: The id is used to determine the execution order, so 1 is the first page in the sequence.
  • url: The URL is the URL you want to check.
  • verifyresponsecode: If we don’t get the expected response code back from the server then check_webinject will return critical to Nagios because a page failed to load properly. Code 200 means everything is OK!
  • method: We can use this to tell it to either perform a web “get” or “post” you usually use get for retrieving pages and post for submitting forms.
  • description: This is a friendly human description that it uses to tell you what part of the check failed when it raises an alert in Nagios.
  • parseresponse: We use this to save the response from a page to use on another page. In this case we are saving the __VIEWSTATE variable for later use… I won’t explain what all of the stuff in the field means but you can find a pretty good explanation here.
  • label: This is used for performance data, so no spaces!
  • warning / critical: If the time to check a page exceeds the defined time in seconds then it will raise an alert in Nagios of the appropriate state.
  1. Now we’re getting somewhere! But how do we log in to the page? How do we know what to send to the web server in order to complete the next step of logging in? You can either a. Ask the developer (*yawn* boring) OR b. We could break out either Firebug in Firefox or the developer tools in chrome to capture the information we need! I’ll be using the later.

Assuming you are using Chrome navigate to the login page you want to monitor and hit the F12 button to open the developer tools and navigate to the Network tab. Down the very bottom there is a solid dot picture, click that and it will turn red! Now enter your username and password and click login.

Once the next page has loaded look through the slew of files that appeared until you find your original login.aspx and click on it. Under the Form Data heading you will see the details your browser submitted in order to do its login! In the case of ASP.NET applications it will often look something similar to _ctl0:MainContent:FormView:FieldName: MYINFO

  1. So now that we know what we need to send, lets go back to modifying our XML file again:
<testcases repeat="1">
  <case
    id="1"
    url="http://my_website.com/Login.aspx"
    verifyresponsecode="200"
    method="get"
    description="Get login page"
    parseresponse='__VIEWSTATE" value="|"|escape'
    label="login_load"
    warning="6"
    critical="8"
  />

  <case
    id="2"
    description="Request login"
    url="http://my_website.com/Login.aspx"
    verifyresponse="302"
    method="post"
    postbody="_ct10:MainContent:FormView:txtUserName=MYUSERNAME&_ct10:MainContent:FormView:txtPassword=MYPASSWORD&_ct10MainContent:FormView:btnLogin=Login&__VIEWSTATE={PARSEDRESULT}"
    label="login_request"
  />
<testcases>

This time around we have verifyresponse set to 302 because we expect that a successful login will redirect us to a new page, we are using post as the method because we need to submit a form and we have an entirely new command this time in postbody. We use postbody to submit data to the web server when using the post method, in this example you can see we are using the three form fields we captured from the previous step.

We are also sending a forth variable though, which is the __VIEWSTATE we captured when we did the first get request. {PARSEDRESULT} is a special variable for check_webinject that will insert the previously captured result… which in this case is the __VIEWSTATE.

  1. You’re pretty much done now! All you need to do is save the file and take it for a test drive. Execute ./check_webinject my_first_web_apm.xml and hopefully you are well on your way to APM.
comments powered by Disqus