Home » Categories » Multiple Categories

NRPE - Agent and Plugin Explained


Nagios Remote Plugin Executor (NRPE) is an agent used by Nagios XI for communicating with remote hosts. Remote hosts are operating systems like Linux and Windows.


This KB article explains:

  • How Nagios XI sends requests to the NRPE Agent

  • How the NRPE Agent receives requests and executes the plugins


The purpose of this KB article is to give you an understanding of how the technology works, which in turn will help you with troubleshooting problems with NRPE.




It is important to clearly define the terminology used in this KB article.

This KB article provides detailed information including screenshots from Nagios XI. The concepts explained in this documentation are also applicable to Nagios Core.



  • NRPE is installed on the remote host you want to monitor from your Nagios XI server

  • This KB article will reference NRPE running on the remote host as the agent

  • The agent waits for check requests from the Nagios XI server

  • Upon receiving the request, the agent will execute a plugin on the remote host to perform the request and return that result back to Nagios XI


Nagios XI Server

  • Nagios XI is responsible for sending requests to the NRPE agent on the remote host

  • The plugin called check_nrpe on Nagios XI server is what executes the request



  • Plugins are binary programs or scripts that are responsible for doing the actual check

  • "Disk Space Usage", "Load" or "Logged On Users" are examples of what can be checked with a plugin

  • These plugins are located on the remote host being monitored




This KB article will assume that NRPE and the plugins are installed in the default directories. If your corporate build or repo installed NRPE or the Nagios-plugins to a different directory than the default location, you will have to make note and substitute your paths for those in this KB article.  The directories referenced most in this KB article are /usr/local/nagios/libexec/ and /usr/local/nagios/etc/.


NRPE Explained

Nagios XI is what sends requests to the agent so the first step is to look at an NRPE service in Core Configuration Manager (CCM). Here is a screenshot from a service definition in Nagios XI CCM.



You can see how the Command view shows the Nagios XI command being used. The variables $USER1$, $HOSTADDRESS$, $ARG1$ and $ARG2$ are dynamically inserted into the command when Nagios XI executes the check.

Here is that same command after the variables have been replaced with the real values:

/usr/local/nagios/libexec/check_nrpe -H -t 30 -c check_users -a '-w 5 -c 10'

What does this mean? The two important options explained here are:

  • -c check_users

    • -c is how Nagios XI tells the agent which command it wants executed

    • In this example check_users is the name of the command

  • -a '-w 5 -c 10'

    • -a is how Nagios XI sends a list of arguments to the agent

    • In this example, the arguments being sent are enclosed in 'single quotes' and hence will be received as ONE argument ($ARG1$). This will be explained in more detail shortly.


On the agent, where is the check_users command defined?

Commands are defined in the nrpe.cfg file, this is commonly located at /usr/local/nagios/etc/nrpe.cfg.

They may also be defined in an additional .cfg file referenced in the nrpe.cfgfile, for example:



What does a command definition look like? Using the example above, the check_users command is defined as follows:

command[check_users]=/usr/local/nagios/libexec/check_users $ARG1$


  • The line begins with the word command, this is how the config file knows this line is a command definition

  • The word between the [square brackets] is the actual command "name"

  • Everything after the = is the actual plugin that is being executed, along with any arguments

  • This example only accepts one argument. Arguments are defined as $ARGx$ where x is the argument number received

Using the example of the request sent by the Nagios XI server, the remote server will execute the following command:

/usr/local/nagios/libexec/check_users -w 5 -c 10

You can see that the $ARG1$ variable has been replaced with -w 5 -c 10.

It's a simple as that.


There was a statement made earlier that requires further explanation. In relation to the value of $ARG2$ in the following screenshot:



  • -a '-w 5 -c 10'

    • This statement was made earlier:
      • The arguments being sent are enclosed in 'single quotes' and hence will be received as ONE argument ($ARG1$).

  • If the command was defined as -a -w 5 -c 10 (without the single quotes), then NRPE on the remote server would receive the following variables:

    • $ARG1$ = -w

    • $ARG2$ = 5

    • $ARG3$ = -c

    • $ARG4$ = 10

  • This means that NRPE on the remote server will execute the following command:

    • /usr/local/nagios/libexec/check_users -w
  • Clearly this is an invalid command

    • The point being made here is that the NRPE agent will only use the variables that have been defined in the command definition.

    • If you wanted to NOT use 'single quotes' then your NRPE command definition would need to be:

      • command[check_users]=/usr/local/nagios/libexec/check_users -w $ARG1$ -c $ARG2$
    • You then define the arguments in CCM as -a 5 10

      • Before NRPE v3 it was not possible to send -c as an "argument", hence you defined these in the command and only send the values




Nagios XI and NRPE both use "variables" or "macros" as a way of creating dynamic configurations.

It is important to remember that the $ARGx$ variable you see in a configuration is directly related to the configuration you are looking at.

Looking at this screenshot:



$ARG2$ in this screenshot contains the values that make up part of the Nagios XI service configuration.


  • -a is how Nagios XI sends a list of arguments to the agent

  • In this example, the arguments being sent are enclosed in 'single quotes' and hence will be received as ONE argument ($ARG1$).


Using the example above, the check_users command is defined as follows:

command[check_users]=/usr/local/nagios/libexec/check_users $ARG1$


It can be easy to mix up the arguments on the Nagios XI server with the arguments in the agent configuration. A common mistake is:

  • Thinking that $ARG2$ will be sent to the agent

  • Only when the -a argument is used will arguments be sent to the agent (anything after -a is an argument that will be sent)

  • The agent receives the arguments starting at $ARG1$




Final Thoughts

This completes the explanation of how the NRPE Agent and Plugin works.

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


3.43 (7)
Article Rating (7 Votes)
Rate this article
  • Icon PDFExport to PDF
  • Icon MS-WordExport to MS Word
Attachments Attachments
There are no attachments for this article.
Related Articles RSS Feed
Nagios XI - Issues with mod_gearman and Performance Data Newlines: "\n"
Viewed 2899 times since Tue, Feb 2, 2016
NRPE - Return Code Of 126 Is Out Of Bounds - Plugin May Not Be Executable
Viewed 5913 times since Fri, Jul 14, 2017
Nagios XI - MK Livestatus Problems With Mod-Gearman
Viewed 4069 times since Thu, Feb 25, 2016
Nagios XI - Apply Configuration Never Completes
Viewed 18357 times since Tue, Jan 27, 2015
Pages Not Displaying Correctly
Viewed 5365 times since Mon, Jan 25, 2016
Nagios XI - Core Config Manager - Bulk Modification Tool
Viewed 5447 times since Sun, Jul 30, 2017
Nagios XI - Missing localhost Alerts
Viewed 4973 times since Sun, Nov 5, 2017
Nagios XI - How to Monitor an AKCP SensorProbe2 using SNMP
Viewed 4873 times since Thu, Jan 28, 2016
Nagios XI - MySQL/MariaDB - Max Connections
Viewed 25925 times since Thu, Jun 2, 2016
Nagios XI - NSP: Sorry Dave, I can’t let you do that
Viewed 19560 times since Tue, Jan 27, 2015