Using PowerShell to Write a Nagios Plugin on Windows in 4 Easy Steps

PowerShell is a powerful tool for automating system tasks, and when combined with Nagios, it allows you to create custom plugins tailored to your needs. In this article, I’ll show you how to write a Nagios plugin using PowerShell to detect a specific process running on a Windows system. By leveraging the Nagios Cross Platform Agent (NCPA), you can integrate your script with Nagios XI for seamless monitoring and alerting. This will help you track critical applications and ensure your servers remain healthy and operational!

Still need to install Nagios? Follow this guide!

Getting Started with NCPA

First, you’ll need to download and install the Nagios Cross Platform Agent (NCPA) on the Windows machine you want to monitor. NCPA acts as a bridge between your Windows system and Nagios XI, enabling communication and monitoring of various metrics, including custom scripts like the one we’ll be creating. You can download NCPA and access its documentation here.

Using the NCPA Configuration Wizard

After installing NCPA on your Windows machine, the next step is to configure it in Nagios XI using the NCPA Configuration Wizard. Simply enter the IP address of your Windows machine and the token you generated during the NCPA installation, and you’ll be all set to start monitoring.

Creating a Script

You can create any PowerShell script you’d like, but for this example I created a simple script for monitoring the running status and CPU processing time of a program. I used notepad++ to create the script on the windows machine that I am monitoring. You can download the script I used directly from github right here.
Note: Notepad++ will need to be ran as administrator in order to save the script to the plugins folder.

Saving Your Script

Once you have created your script you will save it to C:/Program Files/Nagios/NCPA/plugins folder. Make sure to save the script as a .ps1 PowerShell script.
Note: If you cannot find the ‘Nagios’ folder it may be in Program Files (x86) instead

Testing Your Script

Now that your script has been saved, it is time to test it and make sure it’s free from syntax errors. Open PowerShell on your Windows machine and navigate to your plugins folder that you saved the script to using the cd command to change directory. Before running the script, you’ll need to enable script execution by entering the command: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser. This will allow you to execute the script.

Now you can execute your script by typing ./myscriptname.ps1 and any arguments will be included after. For example, to run my script I did ./checkprocesses2.ps1 msedge -w 500. This lets me check if msedge is running and will generate a warning if it has used over 500 seconds of CPU processing time.

Testing Your Script on Your Nagios XI Server

Once you have confirmed that your script is running correctly, you will test it on the Nagios XI server to make sure that the NCPA API is communicating with Nagios XI correctly. Run the command below to test this, but replace the <> with your own values.

/usr/local/nagios/libexec/check_ncpa.py -H <windows ip> -t <yourtoken> -P 5693 -M 'plugins/<scriptname.ps1>' -a <arguments>

For example this is what I entered:

If you got an output that was not an error you can confirm that NCPA is working as intended!

Adding the Command to Nagios XI

Once you’ve confirmed that everything is working correctly, you’re ready to add your command to Nagios XI. From the homepage, click the gear icon on the left to access the settings menu. Then, navigate to Core Config Manager > Commands and click Add New. This will take you to the Command Management page. Enter a name for your command, and in the Command Line field, input the command below, making sure to replace check_process2.ps1 with the name of your script.

$USER1$/check_ncpa.py -H $HOSTADDRESS$ -t $ARG1$ -P 5693 -M 'plugins/check_process2.ps1' -a $ARG3$

Leave everything else as default, then save and apply the configuration.

Adding the Service to Nagios XI

Now that your command is created, you can set up the service. Return to the gear icon on the left and navigate to Core Config Manager > Services, then click Add New. This will take you to the Service Management page. Enter a configuration name and description.

Next, click Manage Hosts and select the Windows host you added earlier during the NCPA Configuration Wizard setup. Then, under Check Command, select the command you created in the previous step. Be sure to replace each $ARG$ placeholder with the appropriate information. To test the configuration, click Run Check Command at the bottom, and enter the Windows machine’s IP address.

Once you’ve confirmed that the test is successful, you’ll need to complete the required fields in the Check Settings and Alert Settings tabs. Finally, click Save and apply the configuration to finish setting up your service.

Finishing Up

Congratulations! You’ve successfully created a custom Nagios plugin using PowerShell to monitor a specific process on a Windows system. By leveraging the power of NCPA and Nagios XI, you’ve set up seamless monitoring, ensuring that critical applications are being tracked and your servers are running smoothly. With the steps outlined in this article, you can now easily manage and monitor your systems with greater precision.

As you continue to refine your monitoring setup, feel free to experiment with additional scripts and configurations to meet your specific needs. Remember, custom Nagios plugins allow you to tailor the monitoring experience to your environment, providing better insights and more effective alerts. Thanks for following along, and happy monitoring!