survivor: Command Interface (sc)

SURVIVOR: Command Interface
About `sc` Commands Dependencies Examples Installation
About `sc`
usage |
        sc [-sV] [-c comment] [-d debuglevel] [-f fromtime] [-i instance]
           [-I instcf] [-L logmethod] [-m moddir] [-o commandflags] [-u untiltime]
           command [commandargs]
where -s: Generates timestamps for each line of debugging output. -V: Outputs the package version information and exits. comment: For `acknowledge` and `inhibit` commands, record comment with the acknowledgement or inhibition. (Comments are deleted when the acknowledgement or inhibition is cleared.) This option can be required by editing `instance.cf`. debuglevel: Output debugging at the specified level (if enabled, see `include/debug.H` for level definitions). Note that debugging at level `DEBUG_CONFIG` may generate numerous warnings about undefined hosts in the configuration file. These warnings may be suppressed by also debugging at level `DEBUG_CFLESS`. `DEBUG_CFERRS` may be used to only display the actual parse errors. fromtime: For `history`, `clsub`, and `archivehistory` commands, specify the beginning of the relevant time period. The format is `[HHMM]MMDDYYYY`, where the time, if omitted, is midnight. instance: The Instance to use. instcf: The instance configuration file (default: `/etc/survivor/instance.cf`). logmethod: The method for logging debugging and warning information. `std` is the default, and uses stderr. `syslog` logs to the syslog `user.debug` facility. `none` disables all debugging and warning information. Specifying this switch before the `-d` switch may prevent initial debugging logs from being written to stderr. moddir: The location where modules may be found. commandflags: Command specific flags. untiltime: For `history`, `clsub`, `clunsub`, and `archivehistory` commands, specify the end of the relevant time period (up to, but not including, the untiltime). The format is `[HHMM]MMDDYYYY`, where the time, if omitted, is midnight.
The Survivor Command Interface allows for examination and manipulation of system state. The user running `sc` must be a member of the group specified by the `--enable-group` option to `configure` in order to change state. By default, anybody may view state who otherwise has access to the file systems maintaining the state. By default, the root user is not permitted to use the command interface. To change this, edit `instance.cf`. ### Commands Only the first unique letter(s) are required. multiple indicates the command accepts arguments of the form `[ service | host | service@host ]`, in any combination.
status <multiple> | Get all available current status information.
status | Flags: `-o match=addressed|error|escalated|stalled` Obtain the service@host pairs whose status is of the specified type. Addressed will match all those acknowledged or inhibited, error will match all those not `MODEXEC_OK`, escalated will match all those escalated, whether automatically or manually, stalled will match any pair that has not been checked within a reasonable time of its next scheduled check.
check <multiple> | Perform an immediate Check and display the results. State and history are not updated. While this command is executing, `^C` will terminate the current Check and `^Z` will terminate the entire command.
checkcf | Attempt to parse the configuration files.
reschedule <multiple> | Schedule a Check at the next run of the scheduler. When rechecked, state and history are updated.
acknowledge <multiple> | Acknowledge the current problem, preventing new alert notifications from being generated until unacknowledged or the underlying problem clears or otherwise changes return code. The Alert Plan keywords `do not clear state` and `clear state honors` can be used to adjust which return codes cause acknowledgements to be cleared. If `result text significant` is defined for the check, a comment change will also clear the acknowledgement.
unacknowledge <multiple> | Remove an existing acknowledgement.
escalate <service@host> | Escalate the current Alert Plan to the next Alert Plan notification level, if one is defined.
inhibit <multiple> | Silence all alert notifications. Unlike acknowledgements, inhibitions must be manually removed (by the `uninhibit` command).
uninhibit <multiple> | Remove the existing inhibition, allowing alert notifications to again be generated.
fix <service@host> | Execute the predefined Fix. There need not be an outstanding error, but if there is, the Check will be automatically rescheduled upon successful execution of the Fix.
alerthistory <multiple> | Flags: `[-o reverse]` Retrieve the alert history records, optionally limited by fromtime and untiltime. If the reverse flag is provided, retrieve most recent history first.
checkhistory <multiple> | Flags: `[-o reverse]` Retrieve the check history records, optionally limited by fromtime and untiltime. If the reverse flag is provided, retrieve most recent history first.
commandhistory <multiple> | Flags: `[-o reverse]` Retrieve the command history records, optionally limited by fromtime and untiltime. If the reverse flag is provided, retrieve most recent history first.
fixhistory <multiple> | Flags: `[-o reverse]` Retrieve the fix history records, optionally limited by fromtime and untiltime. If the reverse flag is provided, retrieve most recent history first.
report <services> <hosts> | Flags: `-o module=<module>,type=alert|check|command|fix[,reverse]` Execute the report module module for the data type specified. The report will be generated for each of the specified services on each of the specified hosts for the time period specified by the `-f` and `-u` flags, or for all available history if neither flag is specified. If the reverse flag is provided, the most recent history will be processed first. At least one service and at least one host must be provided.
trip <service@host> | Flags: `-o rc=<returncode>` Set service@host to have the specified returncode, as if the check failed or exited with that value. If a comment was provided via `-c`, the human readable comment will be set to it. This command is intended primarily for debugging.
clstat <calllist> | Obtain the current status for the specified calllist.
clcal <calllist> | Flags: `[-o person=<person>]` Obtain the calendar for the specified calllist, showing who is on call, including any substitutions. Note that Broadcast Call Lists do not have calendars. If person is provided, only information for that Person will be displayed. If no begin time is provided with `-f`, the current time will be used. If no end time is provided with `-u`, the calendar will continue until the Call List cycles.
clprune <calllist> | Remove any old substitution information (where the scheduled end time of the substitution has passed) from calllist.
clsub <calllist> | Flags: `-o replace=<substitutee>,with=<substitutor>` Add a substitution, having substitutor replace substitutee. The beginning and end times of the substitution must be specified using the `-f` and `-u` flags. The substitutor must be defined as a member of the Call List. The substitutee need not be on call during the exact time of the substitution. The replacement will only take effect while the substitutee is on call.
clunsub <calllist> | Remove any substitution that falls within beginning and end times specified using the `-f` and `-u` flags. To remove all past substitutions, use clprune.
clset <calllist> | Flags: `-o person=<person>` Set person to be the currently on call Person for the Call List. For Simple Call Lists, person will be considered the last Person notified.
archivehistory | Flags: `-o [stale|all],[directory=<dir>|file=<file>]` When the `all` flag is used, all history is archived. For active history, the time period specified by `-f` and `-u` applies. If either is omitted, then archiving begins at the beginning or ends at the end, respectively. If both are omitted, all available history is archived. The `all` flag also implies the `stale` flag. When the `stale` flag is used, all history for services or hosts that are no longer actively defined in the configuration files (hosts must be in a HostClass, services must be defined as Checks, and the hosts must be a member of the Group with the same name as the service in order to be considered actively defined) are archived. Time period specification via `-f` and `-u` does not apply. Note that there is a minor race condition when archiving stale history. If the configuration files are updated while archiving, what was stale could become valid again, and what was valid could become stale. For this reason, it is recommended that configuration files not be updated while archiving stale history. Note also that when archiving stale history, the old history files will be removed. The old directories in which these files resided will only be removed if the `archivehistory` command is run by the survivor user or by root. When history is archived, all entries within the requested time range are transferred from the history files to the specified destination. If the destination given is directory, a new tree is created under the path named. If the destination given is file, all records are appended to that file, prefixed with the type of history record, the service, and the host. Note that when history is archived to a file, archiving is subject to operating system imposed file size limits. Ordinarily, this limit is 2GB. (If the package is built using a 64-bit compiler, this limit would not apply. This is not the default and has not been tested.) When large amounts of history are to be archived, using a directory tree is recommended. The system should detect when the file size limit has been reached, and fail gracefully. Any history records not archived remain in their existing history files. By default, this command is disabled. To enable it, edit `instance.cf`.
archivehistory <multiple> | Flags: `-o [directory=<dir>|file=<file>]` Archive the history for the specified services and/or hosts. The period archived is specified by `-f` and `-u`. If either is omitted, then archiving begins at the beginning or ends at the end, respectively. If both are omitted, all available history is archived. When history is archived, all entries within the requested time range are transferred from the history files to the specified destination. If the destination given is directory, a new tree is created under the path named. If the destination given is file, all records are appended to that file, prefixed with the type of history record, the service, and the host. Note that when history is archived to a file, archiving is subject to operating system imposed file size limits. Ordinarily, this limit is 2GB. (If the package is built using a 64-bit compiler, this limit would not apply. This is not the default and has not been tested.) When large amounts of history are to be archived, using a directory tree is recommended. The system should detect when the file size limit has been reached, and fail gracefully. Any history records not archived remain in their existing history files. By default, this command is disabled. To enable it, edit `instance.cf`.
1. ### Dependencies The command interface must run on the same host as the scheduler. ### Examples To archive all history for the Check `ping` prior to 1 January 2004, to a new tree under `/spare/archive`:
            sc -u 01012004 -o directory=/spare/archive archivehistory ping
2. To archive all history for the host `hal` from 1 July 2003 through 23:59:59 14 July 2003, to the file `/export/history/hal.txt`:
            sc -f 07012003 -u 07152003 -o file=/export/history/hal.txt \
            archivehistory hal
3. To archive all stale history, as of the time the command is run, to the tree `/spare/archive/stale`:
            sc -o stale -o directory=/spare/archive/stale archivehistory
Installation
The command interface is installed in `$INSTDIR/bin/sc`. The modules it expects to run are installed under `$INSTDIR/mod`. $Date: 2006/11/19 17:31:50 $ $Revision: 0.24 $ | keywords acknowledge alerthistory archivehistory archivehistory (multiple) check checkcf checkhistory clcal clprune clset clstat clsub clunsub commandhistory escalate fix fixhistory inhibit reschedule report status status (match) trip unacknowledge uninhibit