Introduction
Beginning with release 0.0.5, 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 those commands.
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...
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 do this for CGIs can be found in this FAQ.
When Does NetSaint Check For External Commands?
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>;<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. |
ADD_SVC_COMMENT | <host_name>;<service_description>;<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. |
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 |