NRPE - Agent and Plugin Explained

Overview

The 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 Doc Hub 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 article is to give you an understanding of how the technology works, which in turn will help you with troubleshooting problems with NRPE.

Terminology

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

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

Agent

• NRPE is installed on the remote host you want to monitor from your Nagios XI server
• This 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

• 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

Locations

This 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 article. The directories referenced most in this 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 10.25.13.30 -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.cfg file, for example:

include_dir=/usr/local/nagios/etc/nrpe

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 as 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

$ARGx$

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:

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