Nagios XI - Using Scripts / Plugins With NCPA

Overview

This KB article explains how to use external scripts / plugins with NCPA.

NCPA has a lot of built in functionality however you will likely run into a situation where you need to use a script to provide additional monitoring capabilities.

NCPA is capable of executing scripts such as:

  • Batch Script = .bat

  • Visual Basic Script = .vbs

  • PowerShell Script = .ps1

  •  Bash Script = .sh

This KB article will  provide examples for these three types of scripts as each method is slightly different.

 

 

Requirements

This KB requires that NCPA is installed, please refer to the following KB article:

NCPA - Agent Installation Instructions

 

 

Batch Script

This example demonstrates how to add a batch script to NCPA.

For this example you are going to create a basic script that takes two arguments.

  • Argument 1 = A number  (0, 1, 2, 3) that will be used as the exit code the script will exit with (this is how Nagios XI determines the status)

  • Argument 2 = A message that the script will display

 

Create Batch Script

On your windows machine open the Notepad program.

Type / paste the following into Notepad.

@echo off 
if [%1] == [] echo No exit code was supplied, aborting! & exit /B 3
if [%2] == [] echo No dummy message was supplied, aborting! & exit /B 3
echo %~2
exit /B %1%

 

Save the file into C:\Program Files (x86)\Nagios\NCPA\plugins with the name check_dummy.bat

 

Open a command prompt on your Windows machine and execute the following commands:

cd "\Program Files (x86)\Nagios\NCPA\plugins"
check_dummy.bat 2 "Something is CRITCAL"
echo %errorlevel%

 

The output will be as follows:

C:\Program Files (x86)\Nagios\NCPA\plugins>check_dummy.bat 2 Something_is_CRITICAL
Something_is_CRITICAL
 
C:\Program Files (x86)\Nagios\NCPA\plugins>echo %errorlevel%
2

 

The output from the first command is what will be displayed in Nagios XI.

The output from the second command, the number 2, is how Nagios XI will determine that this plugin is reporting a CRITICAL state.

 

 

Test Script From Nagios XI

The last step is to test the script from your Nagios XI server. Open a terminal session to Nagios XI server and execute the following:

/usr/local/nagios/libexec/check_ncpa.py -H your_windows_server_ip_address -t your_windows_server_ncpa_token -P 5693 -M 'plugins/check_dummy.bat' -q "args=2 Something_is_CRITICAL"
echo $?

 

The output should look like this:

/usr/local/nagios/libexec/check_ncpa.py -H your_windows_server_ip_address -t your_windows_server_ncpa_token -P 5693 -M 'plugins/check_dummy.bat' -q "args=2 Something_is_CRITICAL"
Something_is_CRITICAL

echo $?
2

 

The output from the first command is what will be displayed in Nagios XI.

The output from the second command, the number 2, is how Nagios XI will determine that this plugin is reporting a CRITICAL state.

 

This completes the example of configuring NCPA to use a batch script. You will now need to go and create a service in Nagios XI which is covered in the Creating Service In Nagios XI section of this KB article.

 

 

Visual Basic Script

This example demonstrates how to add a visual basic script (vbs) to NCPA.

For this example you are going to create a script that takes two arguments.

  • Argument 1 = A number  (0, 1, 2, 3) that will be used as the exit code the script will exit with (this is how Nagios XI determines the status)

  • Argument 2 = A message that the script will display

 

Create Visual Basic Script

On your windows machine open the Notepad program.

Type / paste the following into Notepad.

on error resume next 
If wscript.Arguments.Count < 1 Then
    wscript.Echo "No exit code was supplied, aborting!"
    wscript.Quit(3)
ElseIf Wscript.Arguments.Count < 2 Then
    wscript.Echo "No dummy message was supplied, aborting!"
    wscript.Quit(3)
End If
wscript.Echo wscript.arguments.item(1)
wscript.Quit(wscript.arguments.item(0))

 

Save the file into C:\Program Files (x86)\Nagios\NCPA\plugins with the name check_dummy.vbs

 

Open a command prompt on your Windows machine and execute the following commands:

cd "\Program Files (x86)\Nagios\NCPA\plugins"
cscript.exe //T:30 //NoLogo check_dummy.vbs 2 Something_is_CRITCAL
echo %errorlevel%

 

The output will be as follows:

C:\Program Files (x86)\Nagios\NCPA\plugins>cscript.exe //T:30 //NoLogo check_dummy.vbs 2 Something_is_CRITCAL
Something_is_CRITICAL
 
C:\Program Files (x86)\Nagios\NCPA\plugins>echo %errorlevel%
2

 

The output from the first command is what will be displayed in Nagios XI.

The output from the second command, the number 2, is how Nagios XI will determine that this plugin is reporting a CRITICAL state.

 

You need to execute the check_dummy.vbs script using cscript.exe as if forces the command to run in a command prompt and all output is passed to the command prompt.

  • //T:30 is a timeout of 30 seconds

  • //NoLogo suppresses the Microsoft banner from being displayed

 

Test Script From Nagios XI

The last step is to test the script from your Nagios XI server. Open a terminal session to Nagios XI and execute the following:

/usr/local/nagios/libexec/check_ncpa.py -H your_windows_server_ip_address -t your_windows_server_ncpa_token -P 5693 -M 'plugins/check_dummy.vbs' -q "args=2 Something_is_CRITICAL"
echo $?

 

The output should look like this:

/usr/local/nagios/libexec/check_ncpa.py -H your_windows_server_ip_address -t your_windows_server_ncpa_token -P 5693 -M 'plugins/check_dummy.vbs' -q "args=2 Something_is_CRITICAL"
Something is CRITICAL

echo $?
2

 

The output from the first command is what will be displayed in Nagios XI.

The output from the second command, the number 2, is how Nagios XI will determine that this plugin is reporting a CRITICAL state.

 

This completes the example of configuring NCPA to use a visual basic script. You will now need to go and create a service in Nagios XI which is covered in the Creating Service In Nagios XI section of this KB article.

 

 

PowerShell Script

This example demonstrates how to add a PowerShell script to NCPA.

For this example you are going to create a basic script that takes two arguments.

  • Argument 1 = A number  (0, 1, 2, 3) that will be used as the exit code the script will exit with (this is how Nagios XI determines the status)

  • Argument 2 = A message that the script will display

 

Create PowerShell Script

On your windows machine open the Notepad program.

Type / paste the following into Notepad.

if ($args.count -lt 1) { write-host "No exit code was supplied, aborting!"; exit 3 } 
if ($args.count -lt 2) { write-host "No dummy message was supplied, aborting!"; exit 3 }
write-host $args[1]
exit $args[0]

 

Save the file into C:\Program Files (x86)\Nagios\NCPA\plugins with the name check_dummy.ps1

 

Open a command prompt as an administrator on your Windows machine and execute the following commands:

cd "\Program Files (x86)\Nagios\NCPA\plugins"
powershell.exe -executionpolicy bypass -File check_dummy.ps1 2 Something_is_CRITICAL
echo %errorlevel%

 

The output will be as follows:

C:\Program Files (x86)\Nagios\NCPA\plugins>powershell.exe -executionpolicy bypass -File check_dummy.ps1 2 Something_is_CRITICAL
Something_is_CRITICAL
 
C:\Program Files (x86)\Nagios\NCPA\plugins>echo %errorlevel%
2

 

The output from the first command is what will be displayed in Nagios XI.

The output from the second command, the number 2, is how Nagios XI will determine that this plugin is reporting a CRITICAL

state.

 

Test PowerShell Script From Nagios XI

The last step is to test the script from your Nagios XI server. Open an SSH session to Nagios XI and execute the following:

/usr/local/nagios/libexec/check_ncpa.py -H your_windows_server_ip_address -t your_windows_server_ncpa_token -P 5693 -M 'plugins/check_dummy.ps1' -q "args=2 Something_is_CRITICAL"
echo $?

 

The output should look like this:

/usr/local/nagios/libexec/check_ncpa.py -H your_windows_server_ip_address -c check_dummy_ps1 -q "args=2 Something_is_CRITICAL"
Something_is_CRITICAL

echo $?
2

 

The output from the first command is what will be displayed in Nagios XI.

The output from the second command, the number 2, is how Nagios XI will determine that this plugin is reporting a CRITICAL state.

 

This completes the example of configuring NCPA to use a PowerShell script. You will now need to go and create a service in Nagios XI which is covered in the Creating Service In Nagios XI section of this KB article.

 

Bash Script

This example demonstrates how to add a Bash script to NCPA.

For this example you are going to create a basic script that takes two arguments.

  • Argument 1 = A number  (0, 1, 2, 3) that will be used as the exit code the script will exit with (this is how Nagios XI determines the status)

  • Argument 2 = A message that the script will display

 

Create Bash Script

On your linux machine with NCPA installed, create the file check_dummy.sh in /usr/local/ncpa/plugins

Type / paste the following into the vi editor.

#!/bin/bash
if [[ -z $1 ]]; then
echo "No exit code was supplied, aborting!"
exit
fi
if [[ -z $2 ]]; then
echo "No dummy message was supplied, aborting!"
exit
fi
echo $2
exit $1

 

:wq to save.

chmod 755 check_dummy.sh

 

On your linux machine, execute the following commands:

cd /usr/local/ncpa/plugins
./check_dummy.sh 2 Something_is_CRITICAL
echo $?

 

The output will be as follows:

[xxxx plugins]#./check_dummy.sh 2 Something_is_CRITICAL
Something_is_CRITICAL 
 
[xxxx plugins]#echo $?
2

 

The output from the first command is what will be displayed in Nagios XI.

The output from the second command, the number 2, is how Nagios XI will determine that this plugin is reporting a CRITICAL

state.

 

Test Bash Script From Nagios XI

The last step is to test the script from your Nagios XI server. Open an SSH session to Nagios XI and execute the following:

/usr/local/nagios/libexec/check_ncpa.py -H your_linux_server_ip_address -t your_linux_server_ncpa_token -P 5693 -M 'plugins/check_dummy.sh' -q "args=2 Something_is_CRITICAL"
echo $?

 

The output should look like this:

/usr/local/nagios/libexec/check_ncpa.py -H your_linux_server_ip_address -c check_dummy_sh -q "args=2 Something_is_CRITICAL"
Something_is_CRITICAL

echo $?
2

 

The output from the first command is what will be displayed in Nagios XI.

The output from the second command, the number 2, is how Nagios XI will determine that this plugin is reporting a CRITICAL state.

 

This completes the example of configuring NCPA to use a Bash script. You will now need to go and create a service in Nagios XI which is covered in the Creating Service In Nagios XI section of this KB article.

 

 

 

Creating Service In Nagios XI

The last step is to create the service in Nagios XI. It is assumed that you have already run the NCPA Agent configuration wizard in Nagios XI to monitor your Windows/Linux machine. The following steps will create a copy of an existing service and then change it so it uses the custom plugin on the Windows/Linux machine (this makes it quick and easy). If you have not run the wizard already please refer to the following documentation:

Documentation - How To Monitor Devices Using The NCPA Agent and Wizard

 

Log into Nagios XI and navigate to Configure > Core Config Manager.

In the left pane under Monitoring click Services.

Locate the existing services of the Windows/Linux machine being monitored and click the Copy icon to create a duplicate of this service. From the screenshot below you can see the CPU Usage service is being copied.

 

 

Click the new _copy_1 service that has been created to edit it.

Remove _copy_1 from the Config Name field.

In the Description field provide a name, this example will use Check Dummy.

In the $ARG1$ field you will need to replace everything past the -M just the same as you tested from the Nagios XI terminal session. In the screenshot below the field is cut off but the contents are:

-M 'plugins/check_dummy.ps1' -q "args=2 Something_is_CRITICAL"

 

 

Click the Active check box and then click the Save button.

Click Apply Configuration so Nagios XI can begin monitoring the new service.

Once the service has been checked it should resemble what you saw in the terminal session:

 

 

 

Final Thoughts

For any support related questions please visit the Nagios Support Forums at:

http://support.nagios.com/forum/

Posted by: - Wed, Jul 19, 2017 at 9:14 PM. This article has been viewed 24332 times.
Online URL: https://support.nagios.com/kb/article/nagios-xi-using-scripts-plugins-with-ncpa-722.html

Powered by PHPKB (Knowledge Base Software)