• About check.cf
• Checks
  • About Checks
  • Dependencies
  • Check Stanza Keywords
  • Examples
• Composite Checks
  • About Composite Checks
  • Dependencies
  • Composite Check Stanza Keywords
  • Examples
• Fixes
  • About Fixes
  • Dependencies
  • Fix Stanza Keywords
  • Examples
• Transports
  • About Transports
  • Dependencies
  • Transport Stanza Keywords
  • Examples

     <argname> : [a-zA-Z0-9\._-]+
     <argvalue> : [^ \n\t][^\n]*
     <interval> : "second[s]"|"minute[s]"|"hour[s]"|"day[s]"|"week[s]"
     <name> : [a-zA-Z0-9\.+%@_-]+
     <number> : [0-9]+
  

check.cf defines Checks, which are used to monitor services that run on hosts, Composite Checks, which are Checks defined in terms of other Checks, Fixes, which are used to attempt to correct problems on hosts reported by Checks, and Transports, which are used to execute Checks and Fixes directly on remotely monitored hosts.

     check <name> {
         module <name> {
	     [<argname> <argvalue>]
	     [...]
	 }
	 [via scheduler | via <name>]
	 [check on <name> schedule]
	 [alert on <name> alertplan]
	 [fix with <name>]
	 [check all hosts]
	 [helpfile <name>]
	 [timeout <number> <interval>]
	 [result text significant]
     }

     default timeout <number> <interval>

     default check via (<name> | scheduler)
 

About Checks

Dependencies

• The Schedule specified by the check keyword must be defined in schedule.cf.
• The Alert Plan specified by the alert keyword must be defined in schedule.cf.
• The Transport specified by the via keyword must be defined first in a transport stanza.
• The Fix specified by the fix with keyword must be defined first in a fix stanza.

Check Stanza Keywords

  # Change module timeout
  default timeout 3 minutes
  

  # Run all subsequent check modules via the plaintext transport stanza
  default check via remote

  # Except in this module
  check imap {
    module protocol {
      service imap
    }
    via scheduler
  }
  

Examples

1. A simple Check, using the protocol module. The module is passed the service argument http to instruct it to verify that protocol. This Check will be run for any host found in the corresponding host Group http, as defined in host.cf.

        check http {
          module protocol {
            service http
          }
        }
        

2. A Check using the ping module to monitor every host defined in every HostClass.

        check ping {
          module ping {}
          check all hosts
        }
        

3. An IMAP Check (using the protocol module) that sends out the contents of $helpdir/imap-problems if the relevant format module supports it.

        check imap {
          module protocol {
            service imap
          }
          helpfile imap-problems
        }
        

4. A ping test with a very quick timeout.

        check fastping {
          module ping {}
          timeout 5 seconds
        }
        

5. In order to demonstrate how the override of Schedules and AlertPlans work, here is an excerpt from a sample schedule.cf.

        # From host.cf
        class class1 {
          hosts {
            server1
          }
   
          check on hourly schedule
          alert on standard alertplan
        }
   
        class class2 {
          hosts {
            server2
          }
   
          check on halfhourly schedule
          alert on standard alertplan
        }
   
        group imap {
          server1
          server2
        }
        

   Back in check.cf, server1 will be checked for imap hourly and server2 will be checked every 30 minutes.

        # From check.cf
        check imap {
          module protocol {
            service imap
          }
        }
        

   However, if this next stanza were defined instead, both server1 and server2 would check on the halfhourly schedule and alert on the critical alertplan.

        check imap {
          module protocol {
            service imap
          }
          
          check on halfhourly schedule
          alert on critical alertplan
        }
        

     check <name> {
         [required checks {
	     <name>
	     [...]
	 }]
         [optional checks {
	     <name>
	     [...]
	 }]
	 [check on <name> schedule]
	 [alert on <name> alertplan]
	 [fix with <name>]
	 [check all hosts]
	 [helpfile <name>]
	 [timeout <number> <interval>]
     }

     default timeout <number> <interval>
 

About Composite Checks

Composite Checks cannot be composed of other Composite Checks. This restriction may be lifted in a future release.

Composite Checks are more resource intensive than standard Checks, and so should not be used when a standard Check can accomplish the same task.

Composite Check Result Accumulation

The return value of the Composite Check is determined as follows:

• If any component, whether required or optional, does not complete, then the composite exits with MODEXEC_TIMEDOUT.
• If required components were specified and any failed, then the Composite Check exits with the highest exit code in the order
  • MODEXEC_MISCONFIG
  • MODEXEC_PROBLEM
  • MODEXEC_WARNING
  • MODEXEC_OK
  • For any other return value, larger takes priority over smaller
• If required components were specified and none failed, then the Composite Check exits with MODEXEC_OK regardless of the status of any optional components.
• If no required components were specified and any optional components succeeded, then the Composite Check exits with MODEXEC_OK.
• If no required components were specified and no optional component succeeded, then the Composite Check exits with the lowest exit code in the order
  • MODEXEC_OK
  • MODEXEC_WARNING
  • MODEXEC_PROBLEM
  • MODEXEC_MISCONFIG
  • For any other return value, smaller takes priority over larger

Comments generated by each component are concatenated together in the order they are received, delimited by a semi-colon (;).

Scalar values, as defined in the check module specification and recorded in the history files as specified in instance.cf, consist of the number of completed component Checks. The scalar values returned by each component Check are ignored.

Composite Checks vs Check Dependencies

Check Dependencies prevent other Checks from executing. This is useful when a host becomes unavailable. Only one alert notification (say, for ping) will be transmitted, instead of one alert notification for every service configured for that host.

Dependencies

• The component Checks specified by the required and optional keywords must be defined first in check stanzas.
• All dependencies that apply to Checks also apply here.

Composite Check Stanza Keywords

Examples

1. A Composite Check to monitor an application that has both a web interface and a directory interface. Both Checks must complete successfully for the composite Check to be successful. Only the gizmo group would be defined in host.cf.

        check gizmoldap {
          module ldap {
            port     6389
   	 filter   uid=testuser
   	 response objectclass=candidate
          }
        }
   
        check gizmohttp {
          module httpurl {
            path     /cgi-bin/welcome
   	 query    newuser=true
          }
        }
   
        check gizmo {
          required checks {
            gizmoldap
   	 gizmohttp
          }
   
          check on critical schedule
          alert on critical alertplan
        }
        

     fix <name> {
         module <name> {
	     [<argname> <argvalue>]
	     [...]
	 }
	 [via scheduler | via <name>]
	 [require host locking | require service locking]
	 [expire lock after <number> <interval>]
	 [timeout <number> <interval>]
     }

     default expire fix lock after <number> <interval>
     
     default fix via (<name> | scheduler)

     default timeout <number> <interval>
 

About Fixes

A Fix will be attempted automatically when the following criteria are met:

1. A Fix has been defined in check.cf.
2. An Alert Plan has been defined in schedule.cf that includes an attempt fix try.
3. A Check has been defined which uses the Fix and Alert Plan described above.
4. The Check failure status meets the requirements of the Alert Plan.
5. There is no outstanding acknowledgement or inhibition for the service@host that has failed.

Fixes may also be manually attempted, regardless of outstanding failures, acknowledgements, or inhibitions.

When a Fix executes, a lock is established for the service@host to prevent the Fix from being run more than once concurrently for the same service@host. It is possible to establish wider scoped Fix locking, to service@ or @host, to prevent multiple Fixes for a given service from running simultaneously on multiple hosts or to prevent multiple Fixes for a given host from running simultaneously, regardless of service. Fix modules are subject to timeouts in the same fashion as check modules. In the event a module times out, its lock may not be correctly removed. As such, Fix locks may be expired when they are found to be stale.

Dependencies

• The Transport specified by the via keyword must be defined first in a transport stanza.

Fix Stanza Keywords

  # Run all subsequent fix modules via the plaintext transport stanza
  default fix via remote
  

  # Expire fix locks after 5 minutes
  default expire fix lock after 5 minutes
  

Examples

1. In this example, a Fix is defined for syslog using the init.d module to restart the syslog daemon and the process module to detect the failure. Both use a remote Transport, described below.

        fix syslog {
          module init.d {
            service syslog
          }
          via remote
        }
   
        check syslogd {
          module process {
            name  .*syslogd
          }
          via remote
          fix with syslog
        }
        

2. Here, a Fix is defined that can only be run by resetting a central control, regardless of which host is broken. As such, service level locking is required. Because the Fix takes a while to run, the timeout is also extended.

        fix gizmo {
          module gizmofix {
            # A locally written module to fix gizmo
   	 restartkey foobar
          }
          # Use a locally written transport that knows where the fix runs
          via gizmotransport
   
          require service locking
          timeout 5 minutes
          expire lock after 5 minutes
        }
        

     transport <name> {
         module <name> {
	     [<argname> <argvalue>]
	     [...]
	 }
     }
 

About Transports

By default, check and fix modules are run directly on the scheduler host. However, some check modules and most fix modules run directly on the host to be monitored. (See the check module documentation for more information.) Checks and Fixes that are to be run remotely must be configured to run via a transport module. The appropriate transport stanza must be defined before the Check or Fix that uses it.

Dependencies

• None.

Transport Stanza Keywords

Examples

1. In this example, the mailq module is configured to run via the plaintext transport module.

        transport remote {
          module plaintext {}
        }
   
        check mailq {
          module mailq {
            warn 1000
   	 prob 2000
          }
          via remote
        }
        

Next: dependency.cf