SURVIVOR: sw Specification
About the Web Interface Flags vs Tags Query Specification Page Filters PageSets Entry Points Page Filtering Page Filter Keywords (Tags) Examples
About the Web Interface
syntax |
      sw[?<flag>=&lt;value>[&<flag>=<value>[...]]]
The web interface is used to provide read-only and read-write access to the survivor state. The interface provides access to all configured instances, and provides limited additional functionality. ### Flags vs Tags Flags are the options passed as part of an `HTTP` request. Generally speaking, no state is maintained except in Clipboards, and so URLs may be constructed of any appropriate flags. Tags are commands delimited by `@{}` in pages delivered by `sw`. Tags are processed as the page is delivered, during this processing the values of any provided flags may be analyzed.
Query Specification
`sw` generally accepts flags via both `HTTP GET` and `HTTP POST`. Required Authorization indicates the minimum authorization in an already established session for the requested flag to be processed. Multiple Values Permitted indicates that the flag may be provided more than once. Flag processing, with limited exceptions, is driven by the page being delivered. Flags provided but not required are ignored.
Flag | Definition | Required Authorization | Multiple Values Permitted?
--- | --- | --- | ---
`a` | Action to perform. Only the first unique characters are significant. Valid actions apply over a service specified by `s`, a host specified by `h`, a hostclass specified by `hc`, and/or service@host pairs specified by `sh`, and include `acknowledge` `check` `escalate` `inhibit` `reschedule` `unacknowledge` `uninhibit` After an action is performed, the client will be redirected back to the original URI, minus any action related flags. | rw | No
`ca` | Clipboard action to perform. Only the first unique characters are significant. Valid actions apply over the clipboard specified by `cn`, and include `add*` `clear` `delete*` `save` `send` After an action is performed, the client will be redirected back to the original URI, minus any action related flags. | clipboard (* requires admin) | No
`cc` | Contents for clipboard actions (`ca`). | clipboard | No
`ce` | Clipboard sender email contact. | clipboard | No
`cn` | Clipboard name for clipboard actions (`ca`). | None | No
`cmt` | Comment for actions (`a`). | rw | No
`cp` | Clipboard sender phone contact. | clipboard | No
`cti` | Clipboard individual recipient. | clipboard | No
`ctl` | Clipboard CallList recipient. | clipboard | No
`error` | An error message from the previous transaction. | None | No
`file` | File to filter and deliver from the current PageSet. `.in` is appended to the requested filename, which may not contain slashes (`/`). | None | No
`hc` | Specify a HostClass, as defined in the current instance's `host.cf`. | None | Yes
`h` | Host name to use, as defined in `host.cf`. | None | Yes
`i` | Instance to use, as defined in `instance.cf`. All operations other than Clipboard actions require an instance. | None | No
`info` | An informational message from the previous transaction. | None | No
`l` | Request login (if value is `1`) or logout (if value is `0`). After a login or logout operation is completed, the client will be redirected to the original URI requested, minus the `l` flag. | None | No
`pageset` | PageSet to use, as found in the srcdir directory specified by `cgi.cf`. | None | No
`r` | Page refresh interval, in seconds. If not specified, the default value is 600. | None | No
`ret` | After an action (specified by the `a` flag) is performed, return the browser to the address provided. | rw | No
`reverse` | For report module execution, process the most recent history records first. This will result in more efficient performance when the desired history is recent. | None | No
`rm` | Report module to execute. The module name may not contain slashes (`/`). | exec | No
`s` | Service (check) name to use, as defined in `check.cf`. | None | Yes
`sh` | Service (check) name and host name to use, separated by an `@`. | None | Yes
`status` | Status information to obtain. The reply will be a SurvivorStatus document. Valid status requests include `all`: Obtain all available information. | None | No
`style` | For report module execution, the output style. Valid styles include `html` and `text`. | None | No
`tfile` | File to deliver (unfiltered) from temporary file directory. The file name may not contain slashes (`/`). | None | No
`tmf` | Month portion of from time specification, from 1 through 12. | None | No
`tdf` | Day portion of from time specification, valued 1 through 31. | None | No
`tyf` | Year portion of from time specification, as a four digit number. | None | No
`thf` | Hour portion of from time specification, from 0 through 23. | None | No
`tnf` | Minute portion of from time specification, from 0 through 59. | None | No
`tmu` | Month portion of until time specification, from 1 through 12. | None | No
`tdu` | Day portion of until time specification, valued 1 through 31. | None | No
`tyu` | Year portion of until time specification, as a four digit number. | None | No
`thu` | Hour portion of until time specification, from 0 through 23. | None | No
`tnu` | Minute portion of until time specification, from 0 through 59. | None | No
`vf` | Specify a view flag. Valid view flags include `error`: Show by outstanding error `addressed`: Show inhibited and acknowledged `escalated`: Show escalated | None | No
`vt` | Specify a view type. Valid types include `grid`: Show service@host information in a grid fashion. `summary`: Show a summary of service@host information as one column. | None | No
`which` | For report module execution, which data to process. Valid options include `alert`, `check`, `command`, and `fix`. | None | No
Page Filters
### PageSets PageSets are collections of source files that `sw` reads and processes to deliver content. PageSets are intended to allow multiple customizations to exist concurrently. For example PageSets can exist for different languages, or for views customized for specific audiences (operators, administrators, managers). `sw` will only use one PageSet per transaction. If a `pageset` flag is provided, that PageSet will be used if found. Otherwise, the pageset specified by `cgi.cf` will be used. ### Entry Points If no file is specified in the query string, `sw` will retrieve the page `index.html.in` from the current PageSet. ### Page Filtering `sw` delivers each requested page by looking for the file `$srcdir/$pageset/$file.in`. Tags may be embedded within the page, and begin with `@{` and end with `}`. The contents of each tag are described below. Variables may be referenced anywhere in a tag as `$varname`. Variables are case sensitive, and are evaluated before the tag is processed. If `#` is the first character of a tag, the tag is ignored. For example, `@{# This is a comment}`. ### Page Filter Keywords (Tags) When tags are processed, their results are incorporated into the document in place of the tag. Unless otherwise noted, tags do not require any special privilege to execute.
ALERTPLAN host=<host> service=<service> | Incorporate the name of the AlertPlan used by service@host. Example: `@{ALERTPLAN host=snoopy service=ping}`
ALERTSTATUS type=<type> [ host=<host> ] [ service=<service> ] | Incorporate alert status information of the specifed type: `acknowledged` If service@host is currently inhibited, incorporate who inhibited it. `acknowledgedfor` If service@host is currently inhibited, incorporate the comment explaining why it was inhibited. `alerts` Incorporate the number of alerts that have been generated for service@host. `escalated` Incorporate 1 if service@host is currently escalated, 0 if not. `first` Incorporate the first alert time for service@host in the format returned by `ctime(3)`. `inhibited` If service@host is currently inhibited, incorporate who inhibited it. `inhibitedfor` If service@host is currently inhibited, incorporate the comment explaining why it was inhibited. `last` Incorporate the last alert time for service@host in the format returned by `ctime(3)`. `lastnotify` Incorporate who was notified by the last alert for service@host. `manualescalated` If service@host has been manually escalated, incorporate the level to which it was escalated. `quiet` Incorporate 1 if service@host is currently acknowledged or inhibited, 0 if not. Authorization: This tag requires read only or greater access. Example: `@{ALERTSTATUS type=last host=snoopy service=ping}`
AUTHLEVEL [<authlevel>] | If no authlevel is provided, incorporate the current authorization level, as defined in `cgi.cf`. If authlevel is provided, incorporate 1 if the current user has at least the requested authorization level, 0 otherwise. Example: `@{AUTHLEVEL rw}`
CHECKSCHEDULE host=<host> service=<service> | Incorporate the name of the Check schedule used by service@host. Example: `@{CHECKSCHEDULE host=snoopy service=ping}`
CHECKSTATUS type=<type> [ hostclass=<status> ] [ host=<host> ] [ service=<service> ] | Incorporate check status information of the specifed type: `comment` Incorporate the current check comment for service@host. `duration` Incorporate the execution duration for service@host in milliseconds. `first` Incorporate the first check time for service@host in the format returned by `ctime(3)`. `instances` Incorporate the number of consecutive instances of rc for service@host. `last` Incorporate the last check time for service@host in the format returned by `ctime(3)`. `next` Incorporate the estimated next check time for service@host in the format returned by `ctime(3)`. `rc` Incorporate composite status information, ie the composite status of all requested services and hosts. Status is composited the same way as for required Composite Checks. The numerical returncode (0, 1, 2, etc) will be returned. If both host and service are provided, the status of service@host is obtained. If only host is provided, the composite status of all services monitored for host is obtained. If only service is provided, the composite status of all hosts monitored for service is obtained. If only hostclass is provided, the composite status of all services monitored for all hosts within hostclass is obtained. Authorization: This tag requires read only or greater access. Example: `@{CHECKSTATUS type=rc service=ldap}`
CLIPBOARD <name> | Incorporate the contents of the clipboard name. Authorization: This tag requires clipboard or greater access. Example: `@{CLIPBOARD Notes}`
CLIPEMAIL | Incorporate the default email contact address for sent clipboards, as defined by the `clipemail` keyword in `cgi.cf`. Authorization: This tag requires clipboard or greater access. Example: `@{CLIPEMAIL}`
CLIPPHONE | Incorporate the default phone contact for sent clipboards, as defined by the `clipphone` keyword in `cgi.cf`. Authorization: This tag requires clipboard or greater access. Example: `@{CLIPPHONE}`
ECHO <string> | Incorporate the provided string. Example: `@{ECHO Hello, world!}`
ERROR | Incorporate the error message generated by the prior request (if any). Example: `@{ERROR}`
FIXSTATUS type=<type> [ host=<host> ] [ service=<service> ] | Incorporate fix status information of the specifed type: `attempts` Incorporate the number of fix attempts that have been executed for service@host. `comment` Incorporate the current fix comment for service@host. `first` Incorporate the first fix time for service@host in the format returned by `ctime(3)`. `last` Incorporate the last fix time for service@host in the format returned by `ctime(3)`. `rc` Incorporate the status information for the executed fix. The numerical returncode (0, 1, 2, etc) will be returned. `who` Incorporate who requested the fix for service@host Authorization: This tag requires read only or greater access. Example: `@{FIXSTATUS type=attempts host=snoopy service=ping}`
FLAG <flag> | Incorporate the value of the specified flag. (Where flag can accept more than one value, use a `FOREACH` loop instead.) Example: `@{FLAG h}`
FOREACH [SORT <order>] <name> <type> [<x> ...] | For each item x of type type, set the variable name to an appropriate value and incorporate the contents of the source document until a corresponding `@{ENDEACH}` tag is found. If `SORT` is provided, the values will be sorted according to order, which may be one of the following: `ASC`: Ascending `ASCIN`: Ascending, case insensitive `DESC`: Descending `DESCIN`: Descending, case insensitive The following types of items are understood: `ADDRESSED` Set the variable name to each `service@host` pair that is currently acknowledged or inhibited. `ALLACTIVE` Set the variable name to each `service@host` pair that is currently defined. `CALLLISTADDRESS` Set the variable name to each CallList defined in each instance. x is not used. `CLIPBOARD` Set the variable name to each defined clipboard. x is not used. `ERRORSTATE` Set the variable name to each `service@host` pair that is currently not `MODEXEC_OK`. `ESCALATED` Set the variable name to each `service@host` pair that is currently escalated. `FLAG` The item x is a flag (only one flag is permitted). Set the variable name to the value of the flag. `GROUPMEMBER` The item x is a group (service) name (only one flag is permitted). Set the variable name to each host that is a member of the group. `GROUPS` Set the variable name to each group (with an associated defined Check) that at least one host x is a member of. `HOST` Set the variable name to each host defined in the current instance, based on every member of every HostClass. x is not used. `HOSTCLASS` Set the variable name to each HostClass defined in the current instance. x is not used. `HOSTCLASSMEMBER` The item x is a HostClass name (only one flag is permitted). Set the variable name to each host that is a member of the HostClass. `INSTALLEDMODULES` The item x is a module type, as available under `$INSTDIR/mod/`. (Only one module type is permitted.) `INSTANCE` Set the variable name to each instance defined in `instance.cf`. x is not used. `PERSONADDRESS` Set the variable name to the address of each Person in each CallList defined in each instance. x is not used. `SERVICE` Set the variable name to each service (check) defined in the current instance. x is not used. `SERVICES` Synonym for `GROUPS`. `SERVICEMEMBER` Synonym for `GROUPMEMBER`. `STRING` Each item x is a string. Set the variable name to the contents of the string. `FOREACH` tags may be nested. Example:
       @{FOREACH foo STRING word1 word2 word3}
       Word @{ECHO $foo} is the word.<P>
       @{ENDEACH}

       @{FOREACH SORT ASCIN h HOST}
       @{ECHO $h}<BR>
       @{ENDEACH}
HELPFILE <service> | Incorporate the contents of the help file for service. Authorization: This tag requires read only or greater access. Example: `@{HELPFILE http}`
HOSTCLASS <host> | Incorporate the name of the HostClass of which host is a member. Example: `@{HOSTCLASS snoopy}`
IF <expression> | If expression evaluates to true, incorporate the contents of the source document until either a corresponding `@{ELSE}` or `@{ENDIF}` tag is found. If expression evaluates to false, incorporate the contents of the source document from a corresponding `@{ELSE}` tag (if any) until a corresponding `@{ENDIF}` tag is found. The following expressions are understood: `AUTHENTICATED` There is a currently authenticated user with at least read only access. `DEFINED FLAG x` The flag x is defined with one or more values. `NOTDEFINED FLAG x` The flag x is not defined. `DEFINED STRING x` The string x is defined. `NOTDEFINED STRING x` The string x is not defined. `NUMBER x < y` The number x is less than the number y. `NUMBER x > y` The number x is greater than the number y. `NUMBER x = y` The numbers x and y are equal. `NUMBER x != y` The numbers x and y are not equal. `STRING x = y` The strings x and y are identical. `STRING x != y` The strings x and y are not identical. `STRING EMPTY x` The string x is empty. `STRING NOTEMPTY x` The string x is not empty. `IF` tags may be nested. Example:
       @{IF STRING $foo = $bar}
       <B>Match!</B>
       @{ELSE}
       @{ECHO $foo} is not @{ECHO $bar}
       @{ENDIF}
INCLUDE <filename> | Incorporate the contents of filename. Any tags found within the file are processed. Example: `@{INCLUDE /var/survivor/header.html.in}`
INSTANCE | If an instance has been selected, incorporate the name of the instance. Example: `@{INSTANCE}`
PAGESET | Incorporate the name of the current PageSet. Example: `@{PAGESET}`
RCTEXT <rc> | Incorporate the text description corresponding to the return code rc. Example: `@{RCTEXT 0}`
REFERER | Incorporate the contents of the `HTTP_REFERER` environment variable. Example: `@{REFERER}`
REFRESH | Incorporate the current refresh interval, as specified by the `r` flag. Example: `@{REFRESH}`
RUNNINGSTATE <arg>=<value> | Determine the requested running state. The following state is available, via arg: `lastrun` Incorporate the time, in minutes, since the last run of the specified scheduler. value may be `alert` or `check`. Authorization: This tag requires read only or greater access. Example: `@{RUNNINGSTATE lastrun=alert}`
SET <name>=<string> | Define or redefine the variable name to string. The variable is then accessible as `$name`. Name is case sensitive. If string is of the form `@[TAG]`, then process `TAG` as `@{TAG}`, as long as it is not `FOREACH` or `IF`. Important: Spaces should not be placed immediately on either side of the `=`. Example: `@{SET foo="This is foo"}`
SPLIT <string> <chars> <name> [<name> ...] | Split string on any character provided in chars, storing each token in variables named using the provided names. Example: `@{SPLIT service@host @ $service $host}`
TIME [field=<field>] [offset=<number>] | Incorporate the current time. By default, the format is that returned by `ctime(3)`. If offset is provided, the current time is adjusted by the provided number of seconds. If field is provided, only that field is returned, with the following defined fields: `hour` The hour, 0 through 23. `mday` The day of the month, 1 through 31. `min` The minute, 00 through 59. `mon` The numeric value of the month, 1 through 12. `year` The year, as a four digit number. Example: `@{TIME}`
URI [<flag>=<value> ...] | Incorporate a relative URI that will regenerate the current page. If provided, the optional flag/value pairs will be appended to the URI, properly escaped. If value is omitted, flag will be excluded from the generated URI. Example: `@{URI l=1 r=}` To replace the existing value of a flag with a new value, both omit and add it. Example: `@{URI file= file=new-file.html}`
URITAGS style=<style> [<omit>=<value>[,<value>,...]] | Incorporate the tags used to generate the current page, optionally omitting the tags specified by omit. style indicates the output type, of the following: `hidden` As hidden input values of a form. Example: `@{URITAGS style=hidden omit=hc,v}`
URITOP | Incorporate a relative URI that will regenerate the top (entry) page. Example: `@{URITOP}`
USERNAME | If the current session is authenticated, incorporate the name of the authenticated user. Example: `@{USERNAME}`
VERSION type=<type> | Incorporate the package version information, according to the selected type: `build` Full build information, including compilation timestamp. `package` Just the version number, for example `0.9.4`. Example: `@{VERSION type=package}`
### Examples For examples of source pages, see the PageSets included as part of the distribution, either in `src/cgi/pagesets` or `$INSTDIR/html/sw`. $Date: 2006/11/20 00:16:27 $ $Revision: 0.13 $ | keywords alertplan alertstatus authlevel checkschedule checkstatus clipboard clipemail clipphone echo error fixstatus flag foreach helpfile hostclass if include instance pageset rctext referer refresh runningstate set split time uri uritags uritop username version