Guide to Writing Custom Plugins in Nagios XI

Updated on February 6, 2025

Nicole Vagle

Overview

This guide walks you through building a custom Nagios XI plugin, using a simple script that monitors the last 1-minute load average within a VM.

This article will go over these following steps:

Creating a bash script plugin in the Nagios XI VM
- Includes testing the script
Adding the script as a Command in Nagios XI
Using the Command to make a monitoring Service
Where to find more options for the service

Step 1: Create a bash script plugin in the Nagios XI VM

In order to write a script in the Nagios XI VM, you must first log in using the root user found in the banner upon starting the VM or as a user with sufficient credentials.

Use the following commands to get to the directory that holds all of the plugins for Nagios XI. Nano is a text editor that will be used to make the script.

cd /usr/local/nagios/libexec
nano check_load_average.sh

Now that you are in nano, you can start writing your script. The script below takes in the threshold arguments passed in through the command and sets the variables to those values. Then it compares the load value with the threshold values (critical and warning) and returns a message based on how it compared to the thresholds.

You can find the following code here: https://github.com/NagiosEnterprises/plugins-extra/tree/check_load_average

#!/bin/bash

# Variables
LOAD_AVG=""
HOST=""
WARN=""
CRIT=""


# Parse arguments
while getopts "H:w:c:" arg; do
  case $arg in
    H) HOST=${OPTARG} ;;
    w) WARN=${OPTARG} ;;
    c) CRIT=${OPTARG} ;;
  esac
done


# Validate args
if [[ -z "$HOST" || -z "$WARN" || -z "$CRIT" ]]; then
  echo "UNKNOWN - Invalid arguments. USAGE: $0 -H <host> -w <warning_threshold> -c <critical_threshold>"
  echo "H: $HOST w: $WARN c: $CRIT"
  exit 3
fi


# Set load average variable
LOAD_AVG=$(uptime | awk -F 'load average: ' '{print $2}' | cut -d',' -f1)


# Compare with thresholds | give computer readable info for performance graphs
if (( $(echo "$LOAD_AVG > $CRIT" | bc -l) )); then
  echo "CRITICAL - Load Average is $LOAD_AVG in the last minute (threshold: $CRIT) | loadaverage=$LOAD_AVG"
  exit 2
elif (( $(echo "$LOAD_AVG > $WARN" | bc -l) )); then
  echo "WARN - Load Average is $LOAD_AVG in the last minute (threshold: $WARN) | loadaverage=$LOAD_AVG"
  exit 1
else
  echo "OK - Load Average is $LOAD_AVG in the last minute | loadaverage=$LOAD_AVG"
  exit 0
fi

To close nano, use the keys ^X, y, then [Enter]

When you first close the script, you will not have permission to execute it. To get permission use the following command:

chmod +x /usr/local/nagios/libexec/check_load_average.sh

To make sure the script is working properly, type in this command:

./check_load_average.sh -H <host> -w <warning_threshold> -c <critical_threshold>

The output could be one of four options. It would appear like this:

# An Unknown Response 
UNKNOWN - Invalid arguments. USAGE: $0 -H <host> -w <warning_threshold> -c <critical_threshold>

# A Critical Response
CRITICAL - Load Average is 5.78 in the last minute (threshold: 4)

# A Warning Response
WARNING - Load Average is 2.43 in the last minute (threshold: 2)

# An OK Response
OK - Load Average is 1.39 in the last minute

Step 2: Setting up a Command in Nagios XI

Now that the script is running in the VM, the next step is to add it as a command. To do that, go to Core Configuration Manager and go to Commands.

At the top of the Commands page is button, select + Add New.

Fill out the fields. It should look like this after.

Select Save. At the top right of the Command page will be a message saying Apply Configuration. Go through the apply configuration process.

Apply Configuaration — Apply Configuration

Step 3: Setting up a Service in Nagios XI

On the side bar, go under Monitoring and select Services.

An easy way to get a new service up and running is to copy an existing service and edit it to fit your needs. To do that go under actions and select copy on any of services. The copied service will be inactive and unapplied. Select the edit icon under actions to make the changes to fit the plugin.

Change the Config Name and other fields to whatever values you want to check the load average of. The other settings tabs can also be changed to fit specific needs. At the bottom right of the Common Settings tab, is a Run Check Command button. This can be used to test if the command works as expected before saving the changes.

When the settings are all complete, select Save. A message will appear on the top if the service page saying that changes were made and you need to Apply Configuration. Follow that process the same as you did with Commands.