Console Review

At the Console

[Ref: OpenBSD 5.0, Nagios 3.3.1, Nagios Core 3.x Manuals]

Table of Contents

  • Command Object
    • Macros
    • Reference
  • State Check
    • Host
    • Service

At the command-line, we’ll find a direct way of verifying whether your Nagios box can communicate with the external node. It always troubled me how “black-box” the nagios install seemed, until I realised that one step towards better understanding of what Nagios is “seeing” is to monitor the log files, and launch/execute the nagios tools from the command-line.

Command Object

Nagios is a modular system where much of the functionality is through execution of external utilities. The use of these utilities are defined in the command object which is commonly specified in the file: command.cfg

Commands that can be defined include service checks, service notifications, service event handlers, host checks, host notifications, and host event handlers.

The standard format of the command object is:

define command{ 
	command_name command_name 
	command_line command_line 
}

Where the command_line represents what would be executed at the console command-line with the expected results being OK for success.

command_line: … Before the command line is executed, all valid macros are replaced with their respective values.

If you want to pass arguments to commands during runtime, you can use $ARGn$ macros in the command_line directive of the command definition and then separate individual arguments from the command name (and from each other) using bang (!) characters in the object definition directive (host check command, service event handler command, etc) that references the command. More information on how arguments in command definitions are processed during runtime can be found in the documentation on macros.

For example, the standard check for host alive (ping) is defined as:

define command{
	command_name 	check-host-alive
	command_line	$USER1$/check_ping -H $HOSTADDRESS$ -w 3000.0,80% -c 5000.0,100% -p 5
}

To verify the appropriate command-line options for a command, review the documentation for that command:

/usr/local/libexec/nagios/check_ping --help

An understanding of the purpose and configuratio not the command is important to understanding the results you get from Nagios.

Macros

The command_line demonstrates the use of macros in Nagios, and the two above $USER1$, and $HOSTADDRESS$ demonstrate two types of macros:

  • $USER1$ defined by the configuration
  • $HOSTADDRESS$ defined by the object

Configuration Defined

File excerpt: nagios.cfg

resource_file=/etc/nagios/resource.cfg

File excerpt: resource.cfg

# You can define $USERx$ macros in this file, which can in turn be used
# in command definitions in your host config file(s). $USERx$ macros are
# useful for storing sensitive information such as usernames, passwords,
# etc. 

# Nagios supports up to 32 $USERx$ macros ($USER1$ through $USER32$)

# Sets $USER1$ to be the path to the plugins
$USER1$=/usr/local/libexec/nagios

#Sets $USER2$ to be the path to event handlers
#$USER2$=/usr/local/libexec/nagios/eventhandlers

#$USER3$=someuser
#$USER4$=somepassword

Object Defined

[Ref: Object Definitions]

Many of the object primitives define macros that can be used by other utilities in Nagios. Below is a short list, commonly seen in commands.cfg and you can find more in the Object Definitions reference documentation.

Macro Provided by object primitive
$HOSTNAME$ host:host_name
$HOSTALIAS$ host:alias
$HOSTADDRESS$ host:address
$CONTACTNAME$ contact:contact_name
$CONTACTALIAS$ contact:alias
$CONTACTEMAIL$ contact:email
$CONTACTPAGER$ contact:pager
$CONTACTADDRESSx$ contact:addressx

Reference

To specify a command within the object definition we use the directive check_command

define object {
	::::
	check_command	command_name!$ARG1$!$ARG2$
	::::
}

We specify arguments to be passed to the command separated by exclamation marks:

Where !$ARGn$! is optional

check_command: This directive is used to specify the short name of the command that should be used to check if the host is up or down.

State Checks

the command is used for service or host checks, notifications, or event handlers.

Once you gain an understanding of the utilities for Nagios to check the state of services, hosts, the flexibility of your monitoring system expands dramatically.

The following are simple revisions of some of the more common (?) utilities as a brief to getting you started on refering to the utilities’ documentation and their relationship to your Nagios objects.

Host Check

PING

[Ref: Wikipedia:Ping]

A basic check whether a host is up on the network is to perform a ping against the host.

Ping is a computer network administration utility used to test the reachability of a host on an Internet Protocol (IP) network and to measure the round-trip time for messages sent from the originating host to a destination computer. The name comes from active sonar terminology.

/usr/local/libexec/nagios/check_ping --help

Help Screen extract:

Use ping to check connection statistics for a remote host

check_ping -H  -w ,% -c ,% [-p packets] [-t timeout] [-4|-6]

Options:

 -4 Use IPv4 connection
 -6 Use IPv6 connection
 -H host to ping
 -c critical threshold pair
 -w warning threshold pair
 -p number of ICMP ECHO packets to send (Default: 5)
 
  round trip average (ms) which triggers a WARNING or CRITICAL state.
  percentage of packet loss to trigger an alarm state.

The check-host-live uses the command-line:

define command{
	command_name 	check-host-alive
	command_line	$USER1$/check_ping -H $HOSTADDRESS$ -w 3000.0,80% -c 5000.0,100% -p 5
}

We can obviously execute at the command-line to verify, view the response.

/usr/local/libexec/nagios/check_ping -H 127.0.0.1 -w 3000.0,80% -c 5000.0,100% -p 5
PING OK - Packet loss = 0%, RTA = 0.01 ms|rta=0.014000ms;3000.000000;5000.000000;0.000000 pl=0%;80;100;00

Other configuration / execution samples:

define command{
	command_name	check_ping
	command_line	$USER1$/check_ping -H $HOSTADDRESS$ -w $ARG1$ -c $ARG2$ -p 5
}

define object {
	::::
	check_command	check_ping!100.0,20%!500.0,60%
	::::
}

/usr/local/libexec/nagios/check_ping -H 127.0.0.1 -w 100.0,20% -c 5000.0,60% -p 5
PING OK - Packet loss = 0%, RTA = 0.02 ms|rta=0.017000ms;3000.000000;5000.000000;0.000000 pl=0%;20;60;00

Service Check

SSH

/usr/local/libexec/nagios/check_ssh --help

Help Screen extract:

Try to connect to an SSH server at specified server and port

check_ssh [-46] [-t ] [-r ] [-p port]

Example configurations from default package install

define command{
	command_name	check_ssh
	command_line	$USER1$/check_ssh $ARG1$ $HOSTADDRESS$
}

define object{
	::::
	check_command	check_ssh
	::::
}

Example command-line execution:

/usr/local/libexec/nagios/check_ssh localhost
SSH OK - OpenSSH_5.9 (protocol 2.0)

SMTP

/usr/local/libexec/nagios/check_smtp --help

Help Screen extract:

This plugin will attempt to open an SMTP connection with the host.

check_smtp -H host [-p port][-e export][-C command][-f from addr]
		[-A authtype -U authuser -P authpass][-w warn][-c crit][-t timeout]
		[-F fqdn][-S][-D days][-v][-4|-6]

Successful connects return STATE_OK, refusals and timeouts return
STATE_CRITICAL, other errors return STATE_UNKNOWN.

/usr/local/libexec/nagios/check_smtp your-mailserver
SMTP OK - 0.002 sec. response time/time=0.002335s;;;0.000000

NTP

[Ref: mail archive #1 | #2]

Do not use check_ntp_peer to check against OpenNTPD

The check presumes implementation of