External Commands

Introduction

Nagios can process commands from external applications (including CGIs - see the command CGI for an example) and alter various aspects of its monitoring functions based on the commands it receives.

Enabling External Commands

By default, Nagios does not check for or process any external commands. If you want to enable external command processing, you'll have to do the following...

Enable external command checking with the check_external_commands option
Set the frequency of command checks with the command_check_interval option
Specify the location of the command file with the command_file option. Its best to put the external command file in its own directory (i.e. /usr/local/nagios/var/rw).
Setup proper permissions on the directory containing the external command file. Details on how to do this can be found here.

When Does Nagios Check For External Commands?

At regular intervals specified by the command_check_interval option in the main configuration file
Immediately after event handlers are executed. This is in addtion to the regular cycle of external command checks and is done to provide immediate action if an event handler submits commands to Nagios.

Using External Commands

External commands can be used to accomplish a variety of things while Nagios is running. Example of what can be done include temporarily disabling notifications for services and hosts, temporarily disabling service checks, forcing immediate service checks, adding comments to hosts and services, etc.

External Command Examples

Some example scripts that can be used to issue commands to Nagios can be found in the eventhandlers/ subdirectory of the Nagios distribution. You may have to modify the scripts to accomodate for differences in system command syntaxes, file and directory locations, etc.

Command Format

External commands that are written to the command file have the following format...

[time] command_id;command_arguments

...where time is the time (in time_t format) that the external application or CGI committed the external command to the command file. Some of the commands that are available are described in the table below, along with their command_id and a description of their command_arguments.

Implemented Commands

This is a description of the some of the external commands which have been implemented in Nagios. Note that all time arguments should be specified in time_t format (seconds since the UNIX epoch).

Command ID Command Arguments Command Description

ADD_HOST_COMMENT <host_name>;<persistent>;<author>;<comment> This command is used to associate a comment with the specified host. The author argument generally contains the name of the person who entered the comment. The actual comment should not contain any semi-colons. The persistent flag determines whether or not the comment will survive program restarts (1=save comment across program restarts, 0=delete comment on restart).

ADD_SVC_COMMENT <host_name>;<service_description>;<persistent>;<author>;<comment> This command is used to associate a comment with the specified host. Note that both the host name and service description are required. The author argument generally contains the name of the person who entered the comment. The actual comment should not contain any semi-colons. The persistent flag determines whether or not the comment will survive program restarts (1=save comment across program restarts, 0=delete comment on restart).

DEL_HOST_COMMENT <comment_id> This is used to delete a comment having a ID matching comment_id for the specified host.

DEL_ALL_HOST_COMMENTS <host_name> This is used to delete all comments associated with the specified host.

DEL_SVC_COMMENT <comment_id> This is used to delete a comment having a ID matching comment_id for the specified service.

DEL_ALL_SVC_COMMENTS <host_name>;<service_description> This is used to delete all comments associated with the specified service. Note that both the host name and service description are required.

DELAY_HOST_NOTIFICATION <host_name>;<next_notification_time> This will delay the next notification about this host until the time specified by the next_notification_time argument. This will have no effect if the host state changes before the next notification is scheduled to be sent out.

DELAY_SVC_NOTIFICATION <host_name>;<service_description>;<next_notification_time> This will delay the next notification about this service until the time specified by the next_notification_time argument. Note that both the host name and service description are required. This will have no effect if the service state changes before the next notification is scheduled to be sent out. This does not delay notifications about the host.

SCHEDULE_SVC_CHECK <host_name>;<service_description>;<next_check_time> This will reschedule the next check of the specified service for the time specified by the next_check_time argument. Note that both the host name and service description are required.

SCHEDULE_HOST_SVC_CHECKS <host_name><next_check_time> This will reschedule the next check of all services on the specified host for the time specified by the next_check_time argument.

ENABLE_SVC_CHECK <host_name>;<service_description> This will re-enable checks of the specified service. Note that both the host name and service description are required.

DISABLE_SVC_CHECK <host_name>;<service_description> This will temporarily disable checks of the specified service. Service checks are automatically re-enabled when Nagios restarts. Issuing this command will have the side effect of temporarily preventing notifications from being sent out for the service. It does not prevent notifications about the host from being sent out.

ENABLE_SVC_NOTIFICATIONS <host_name>;<service_description> This is used to re-enable notifications for the specified service. Note that both the host name and service description are required.

DISABLE_SVC_NOTIFICATIONS <host_name>;<service_description> This is used to temporarily disable notifications from being sent out about the specified service. Notifications are automatically re-enabled when Nagios restarts. Note that both the host name and service description are required. This does not disable notifications for the host.

ENABLE_HOST_SVC_NOTIFICATIONS <host_name> This is used to re-enable notifications for all services on the specified host. This does not enable notifications for the host.

DISABLE_HOST_SVC_NOTIFICATIONS <host_name> This is used to temporarily disable notifications for all services on the specified host. This does not disable notifications for the host.

ENABLE_HOST_SVC_CHECKS <host_name> This will re-enable checks of all services on the specified host. If one or more services were in a non-OK state when they were disabled, contacts may receive notifications if the service(s) recover after the checks are re-enabled.

DISABLE_HOST_SVC_CHECKS <host_name> This will temporarily disable checks of all services on the specified host. Service checks are automatically re-enabled when Nagios restarts. Issuing this command will have the side effect of temporarily preventing notifications from being sent out for any of the affected services. It does not prevent notifications about the host from being sent out.

ENABLE_HOST_NOTIFICATIONS <host_name> This will temporarily disable notifications for this host. Note that this does not enable notifications for the services associated with this host.

DISABLE_HOST_NOTIFICATIONS <host_name> This will temporarily disable notifications for this host. Notifications are automatically re-enabled when Nagios restarts. Note that this does not disable notifications for the services associated with this host.

ENABLE_ALL_NOTIFICATIONS_BEYOND_HOST <host_name> This will enable notifications for all hosts and services "beyond" the host specified by the host_name argument (from the view of Nagios). This command is most often used in conjunction with redundant monitoring hosts.

DISABLE_ALL_NOTIFICATIONS_BEYOND_HOST <host_name> This will temporarily disable notifications for all hosts and services "beyond" the host specified by the host_name argument (from the view of Nagios). Notifications are automatically re-enabled when Nagios restarts. This command is most often used in conjunction with redundant monitoring hosts.

ENABLE_NOTIFICATIONS <execution_time> This will enable host and service notifications on a program-wide basis at the time specified by the execution time argument.

DISABLE_NOTIFICATIONS <execution_time> This will disable host and service notifications on a program-wide basis at the time specified by the execution time argument.

SHUTDOWN_PROGRAM <execution_time> This will cause Nagios to shutdown at the time specified by the execution_time argument. Note: Nagios cannot be restarted via the web interface once it has been shutdown.

RESTART_PROGRAM <execution_time> This will cause Nagios to flush all configuration state information, re-read all the config files, and restart monitoring at the time specified by the execution_time argument

PROCESS_SERVICE_CHECK_RESULT <host_name>;<service_description>;<return_code>;<plugin_output> This command is used to submit check results for a particular service to Nagios. These "passive" checks are acted upon in the same manner as normal "active" checks. More information on passive service checks can be found here.

SAVE_STATE_INFORMATION <execution_time> This will force Nagios to dump current state information for all services and hosts to the file specified by the state_retention_file variable. You must enable the retain_state_information option for this to work.

READ_STATE_INFORMATION <execution_time> This will force Nagios to read previously saved state information for all services and hosts from the file specified by the state_retention_file variable. You must enable the retain_state_information option for this to work.

START_EXECUTING_SVC_CHECKS This is used to resume the execution of service checks. The execution of service checks may have been stopped at an earlier time by either receiving a STOP_EXECUTING_SVC_CHECKS command, or by setting the execute_service_checks option in the main config file to 0. Most often used when implementing redundant monitoring hosts.

STOP_EXECUTING_SVC_CHECKS This is used to stop the execution of service checks. When service checks are not being executed, Nagios will keep requeuing checks for a later time, but will not actually execute any checks. This essentially puts Nagios into a "sleep" mode, as far as monitoring is concerned. Most often used when implementing redundant monitoring hosts.

START_ACCEPTING_PASSIVE_SVC_CHECKS This is used to resume the acceptance of passive service checks for all services. The acceptance of passive service checks may have been stopped at an earlier time by either receiving a STOP_ACCEPTING_PASSIVE_SVC_CHECKS command, or by setting the accept_passive_service_checks option in the main config file to 0. If passive checks have been disabled for specific services using the DISABLE_PASSIVE_SVC_CHECKS command, passive checks will not be accepted for those services, but will for all others.

STOP_ACCEPTING_PASSIVE_SVC_CHECKS This is used to disable the acceptance of passive service checks for all services.

ENABLE_PASSIVE_SVC_CHECKS <host_name>;<service_description> This is used to resume the acceptance of passive service checks for a specific service. The acceptance of passive checks may have been disabled for a service at an earlier time by receiving a DISABLE_PASSIVE_SVC_CHECKS command. If passive checks have been disabled for all services either by using the STOP_ACCEPTING_PASSIVE_SVC_CHECKS command or by setting the accept_passive_service_checks option in the main config file to 0, passive checks will not be accepted for this service.

DISABLE_PASSIVE_SVC_CHECKS <host_name>;<service_description> This is used to disable the acceptance of passive service checks for a specific service.

Command ID	Command Arguments	Command Description
ADD_HOST_COMMENT	<host_name>;<persistent>;<author>;<comment>	This command is used to associate a comment with the specified host. The author argument generally contains the name of the person who entered the comment. The actual comment should not contain any semi-colons. The persistent flag determines whether or not the comment will survive program restarts (1=save comment across program restarts, 0=delete comment on restart).
ADD_SVC_COMMENT	<host_name>;<service_description>;<persistent>;<author>;<comment>	This command is used to associate a comment with the specified host. Note that both the host name and service description are required. The author argument generally contains the name of the person who entered the comment. The actual comment should not contain any semi-colons. The persistent flag determines whether or not the comment will survive program restarts (1=save comment across program restarts, 0=delete comment on restart).
DEL_HOST_COMMENT	<comment_id>	This is used to delete a comment having a ID matching comment_id for the specified host.
DEL_ALL_HOST_COMMENTS	<host_name>	This is used to delete all comments associated with the specified host.
DEL_SVC_COMMENT	<comment_id>	This is used to delete a comment having a ID matching comment_id for the specified service.
DEL_ALL_SVC_COMMENTS	<host_name>;<service_description>	This is used to delete all comments associated with the specified service. Note that both the host name and service description are required.
DELAY_HOST_NOTIFICATION	<host_name>;<next_notification_time>	This will delay the next notification about this host until the time specified by the next_notification_time argument. This will have no effect if the host state changes before the next notification is scheduled to be sent out.
DELAY_SVC_NOTIFICATION	<host_name>;<service_description>;<next_notification_time>	This will delay the next notification about this service until the time specified by the next_notification_time argument. Note that both the host name and service description are required. This will have no effect if the service state changes before the next notification is scheduled to be sent out. This does not delay notifications about the host.
SCHEDULE_SVC_CHECK	<host_name>;<service_description>;<next_check_time>	This will reschedule the next check of the specified service for the time specified by the next_check_time argument. Note that both the host name and service description are required.
SCHEDULE_HOST_SVC_CHECKS	<host_name><next_check_time>	This will reschedule the next check of all services on the specified host for the time specified by the next_check_time argument.
ENABLE_SVC_CHECK	<host_name>;<service_description>	This will re-enable checks of the specified service. Note that both the host name and service description are required.
DISABLE_SVC_CHECK	<host_name>;<service_description>	This will temporarily disable checks of the specified service. Service checks are automatically re-enabled when Nagios restarts. Issuing this command will have the side effect of temporarily preventing notifications from being sent out for the service. It does not prevent notifications about the host from being sent out.
ENABLE_SVC_NOTIFICATIONS	<host_name>;<service_description>	This is used to re-enable notifications for the specified service. Note that both the host name and service description are required.
DISABLE_SVC_NOTIFICATIONS	<host_name>;<service_description>	This is used to temporarily disable notifications from being sent out about the specified service. Notifications are automatically re-enabled when Nagios restarts. Note that both the host name and service description are required. This does not disable notifications for the host.
ENABLE_HOST_SVC_NOTIFICATIONS	<host_name>	This is used to re-enable notifications for all services on the specified host. This does not enable notifications for the host.
DISABLE_HOST_SVC_NOTIFICATIONS	<host_name>	This is used to temporarily disable notifications for all services on the specified host. This does not disable notifications for the host.
ENABLE_HOST_SVC_CHECKS	<host_name>	This will re-enable checks of all services on the specified host. If one or more services were in a non-OK state when they were disabled, contacts may receive notifications if the service(s) recover after the checks are re-enabled.
DISABLE_HOST_SVC_CHECKS	<host_name>	This will temporarily disable checks of all services on the specified host. Service checks are automatically re-enabled when Nagios restarts. Issuing this command will have the side effect of temporarily preventing notifications from being sent out for any of the affected services. It does not prevent notifications about the host from being sent out.
ENABLE_HOST_NOTIFICATIONS	<host_name>	This will temporarily disable notifications for this host. Note that this does not enable notifications for the services associated with this host.
DISABLE_HOST_NOTIFICATIONS	<host_name>	This will temporarily disable notifications for this host. Notifications are automatically re-enabled when Nagios restarts. Note that this does not disable notifications for the services associated with this host.
ENABLE_ALL_NOTIFICATIONS_BEYOND_HOST	<host_name>	This will enable notifications for all hosts and services "beyond" the host specified by the host_name argument (from the view of Nagios). This command is most often used in conjunction with redundant monitoring hosts.
DISABLE_ALL_NOTIFICATIONS_BEYOND_HOST	<host_name>	This will temporarily disable notifications for all hosts and services "beyond" the host specified by the host_name argument (from the view of Nagios). Notifications are automatically re-enabled when Nagios restarts. This command is most often used in conjunction with redundant monitoring hosts.
ENABLE_NOTIFICATIONS	<execution_time>	This will enable host and service notifications on a program-wide basis at the time specified by the execution time argument.
DISABLE_NOTIFICATIONS	<execution_time>	This will disable host and service notifications on a program-wide basis at the time specified by the execution time argument.
SHUTDOWN_PROGRAM	<execution_time>	This will cause Nagios to shutdown at the time specified by the execution_time argument. Note: Nagios cannot be restarted via the web interface once it has been shutdown.
RESTART_PROGRAM	<execution_time>	This will cause Nagios to flush all configuration state information, re-read all the config files, and restart monitoring at the time specified by the execution_time argument
PROCESS_SERVICE_CHECK_RESULT	<host_name>;<service_description>;<return_code>;<plugin_output>	This command is used to submit check results for a particular service to Nagios. These "passive" checks are acted upon in the same manner as normal "active" checks. More information on passive service checks can be found here.
SAVE_STATE_INFORMATION	<execution_time>	This will force Nagios to dump current state information for all services and hosts to the file specified by the state_retention_file variable. You must enable the retain_state_information option for this to work.
READ_STATE_INFORMATION	<execution_time>	This will force Nagios to read previously saved state information for all services and hosts from the file specified by the state_retention_file variable. You must enable the retain_state_information option for this to work.
START_EXECUTING_SVC_CHECKS		This is used to resume the execution of service checks. The execution of service checks may have been stopped at an earlier time by either receiving a STOP_EXECUTING_SVC_CHECKS command, or by setting the execute_service_checks option in the main config file to 0. Most often used when implementing redundant monitoring hosts.
STOP_EXECUTING_SVC_CHECKS		This is used to stop the execution of service checks. When service checks are not being executed, Nagios will keep requeuing checks for a later time, but will not actually execute any checks. This essentially puts Nagios into a "sleep" mode, as far as monitoring is concerned. Most often used when implementing redundant monitoring hosts.
START_ACCEPTING_PASSIVE_SVC_CHECKS		This is used to resume the acceptance of passive service checks for all services. The acceptance of passive service checks may have been stopped at an earlier time by either receiving a STOP_ACCEPTING_PASSIVE_SVC_CHECKS command, or by setting the accept_passive_service_checks option in the main config file to 0. If passive checks have been disabled for specific services using the DISABLE_PASSIVE_SVC_CHECKS command, passive checks will not be accepted for those services, but will for all others.
STOP_ACCEPTING_PASSIVE_SVC_CHECKS		This is used to disable the acceptance of passive service checks for all services.
ENABLE_PASSIVE_SVC_CHECKS	<host_name>;<service_description>	This is used to resume the acceptance of passive service checks for a specific service. The acceptance of passive checks may have been disabled for a service at an earlier time by receiving a DISABLE_PASSIVE_SVC_CHECKS command. If passive checks have been disabled for all services either by using the STOP_ACCEPTING_PASSIVE_SVC_CHECKS command or by setting the accept_passive_service_checks option in the main config file to 0, passive checks will not be accepted for this service.
DISABLE_PASSIVE_SVC_CHECKS	<host_name>;<service_description>	This is used to disable the acceptance of passive service checks for a specific service.