## External Commands

Introduction

NetSaint 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, NetSaint 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

Note: If external applications or CGIs will be issuing commands to NetSaint, you will have to grant the user that those processes run as permission to write to the command file. An outline of how to configure proper permissions for the command file can be found here.

When Does NetSaint 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 NetSaint.

Using External Commands

External commands can be used to accomplish a variety of things while NetSaint is running. Example of what can be done include changing program modes, 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 NetSaint can be found in the eventhandlers/ subdirectory of the NetSaint 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. The various commands that are available, along with their command_id and a description of their command_arguments, can be found in the table below.

Implemented Commands

This is a description of the external commands which have been implemented in NetSaint thus far. More commands will be added in future releases. 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 NetSaint 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 NetSaint 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 NetSaint 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 NetSaint 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 NetSaint). 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 NetSaint). Notifications are automatically re-enabled when NetSaint restarts. This command is most often used in conjunction with redundant monitoring hosts.
ENTER_STANDBY_MODE | <execution_time> | This will change the current program mode to Standby at the time specified by the execution time argument.
ENTER_ACTIVE_MODE | <execution_time> | This will change the current program mode to Active at the time specified by the execution time argument.
SHUTDOWN_PROGRAM | <execution_time> | This will cause NetSaint to shutdown at the time specified by the execution_time argument. Note: NetSaint cannot be restarted via the web interface once it has been shutdown.
RESTART_PROGRAM | <execution_time> | This will cause NetSaint 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 NetSaint. 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 NetSaint 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 NetSaint 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, NetSaint will not keep requeuing checks for a later time, but will not actually execute any checks. This essentially puts NetSaint 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.