The custom variables allow you to include your own directives when defining objects. These can then be used in commands. This allows you to define objects in a more concise way and define service checks in a more general fashion.

The idea is that you define directives that are not standard Nagios parameters in host, service, or contact objects, and they can be accessed from all commands, such as check commands, notifications, and event handlers. This is very useful for complex Nagios configurations, where you might want commands to perform nontrivial tasks for which they will require additional information.

Let's assume we want Nagios to check that the hosts have correct MAC addresses. We can then define a service once and use that custom variable for the check command. When defining an object, a custom variable needs to be prefixed with an underscore and written in uppercase.

The custom variables are accessible as the following macros:

For the preceding example, a macro definition would be $_HOSTMAC$.

These variables can be used for command definitions, notifications, or time periods. The following is an example of a contact and notification command that uses a custom variable for the Jabber address:

  define contact 
  { 
    contact_name               jdoe 
    alias                      John Doe 
    host_notification_commands host-notify-by-jabber 
    _JABBERID                  [email protected] 
  } 
  define command 
  { 
    command_name        host-notify-by-jabber 
    command_line        $USER1$/notify_via_jabber $_CONTACTJABBERID$ 
                        "Host $HOSTDISPLAYNAME$ changed state to                           $HOSTSTATE$" 
  } 

Of course, you will also need a plugin to send notifications over Jabber. This can be downloaded from the Nagios project on SourceForge (http://nagios.sf.net/download/contrib/notifications/notify_via_jabber). The previous example will work with any other protocol you might be using. All that's needed is a plugin that will send commands over such a protocol.

A major benefit of custom variables is that they can also be changed on the fly over an external command pipe. This way, the custom variables' functionality can be used in more complex configurations. Event handlers may trigger changes in the attributes of other checks.

An example might be that a ping check with 50 ms and 20 percent packet loss limits is made to ensure that the network connectivity is working correctly. However, if the main router is down and a failover connection is used, the check is set to a more relaxed limit of 400 ms and 50 percent packet loss.

An example configuration might be as follows:

  define service 
  { 
    host_name           router2 
    service_description PING 
    check_command       check_ping_limits 
    _LIMITS             50.0,20% 
  } 
  define command 
  { 
    command_name        check_ping_limits 
    command_line        $USER1$/check_ping -H $HOSTADDRESS$ 
                        -w $_SERVICELIMITS$ -c $_SERVICELIMITS$ 
  } 

When a service checks if the main router is up (that is, it is in a critical state), an event handler will invoke a change in the limits by sending a CHANGE_CUSTOM_SVC_VAR command (documented here: http://www.nagios.org/developerinfo/externalcommands/commandinfo.php?command_id=140) over the external commands pipe to set the _LIMITS custom variable. Chapter 8, Notifications and Events, covers event handlers and external commands pipe in more detail. It will also show how to change custom host and service variables to a Nagios instance.