The query handler allows two-way communication with Nagios internal processes and external applications. It is designed to be extensible, and future versions of Nagios may provide more functionality using the query handlers.
The query handler communicates using Unix domain sockets (refer to http://en.wikipedia.org/wiki/Unix_domain_socket for more details). These are meant for communication between processes on the same machine. Unix domain sockets use filesystem as names for remote addresses. The location (address) of the Nagios query handler is similar to the Nagios external command pipe—it is called nagios.qh
and by default resides in the same directory as the external commands pipe. For example, /var/nagios/rw/nagios.qh
is the path to query handler's Unix domain socket for an installation performed according to the steps given in Chapter 2, Installing Nagios 4. Filesystem permissions are used to determine if a process can connect to the other side or not. So, it is possible to limit access to the query handler only to specific operating system users or groups.
Unix domain sockets are very similar to named pipes (such as the Nagios external commands pipe), however, it is not possible to use named pipes for two-way communication with more than one client. Another difference is that it is not possible to open it as a file and/or send commands to the socket using shell commands such as echo
—which is possible for named pipes such as the Nagios external command pipe.
Nagios provides its functionality through the query handler using services. There are several built-in services and the ones that are public are described throughout this chapter. Future versions of Nagios (or third-party software) may provide additional services. Each command sent to Nagios is prefixed with the service name, so each service may use any names for its sub-commands.
Nagios uses the query handler internally to distribute jobs to worker processes. Child processes connect to the query handler and receive tasks that should be performed. This is one of the reasons the query handler was originally created—to be able to control the worker processes. The worker processes use the wproc
service, which is an internal service and should only be used by Nagios processes.
Nagios also provides services that can be used by external applications. The first and most basic one is echo
, which simply responds with the data that was sent to it. It is mainly a useful tool for learning to communicate with Nagios.
The core
service allows information about Nagios processes and scheduled jobs queue. The nerd
service allows subscribing to events and can be used to receive real-time updates about Nagios host and/or service status changes.
Let's start understanding the query handler by communicating with it from the shell. There are multiple commands that allow connecting to Unix domain sockets such as netcat
(refer to http://netcat.sourceforge.net/ for more detail) and socat
(refer to http://www.dest-unreach.org/socat/ for more details). Both can be used to send commands to the Nagios query handler and to install the tools; simply run the following command on Ubuntu:
root@ubuntu:# apt-get install socat netcat
For Red Hat Enterprise Linux, CentOS, and Fedora Core you can run the following command:
# yum install socat nc
For Red Hat Enterprise Linux / CentOS 7 and later, both packages are available by default. For earlier versions, the socat
package is available as part of EPEL (refer to https://fedoraproject.org/wiki/EPEL for more detail) and is not available unless EPEL is installed.
This will install both of the tools, which will be used later to check communication with the query handler.
The communication protocol for the query handler is simple. There is no initial message, so after connecting we can simply send commands to the query handler.
All commands that are sent to the query handler are prefixed with the name of the handler and are sent in the following way:
@service command
Where, @service
is the name of the service prefixed with the @
character, command
is the command (and parameters) to send and