SURVIVOR: sw Specification
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.

  1. If a pageset flag is provided, that PageSet will be used if found.
  2. Otherwise, the pageset specified by cgi.cf will be used.

Entry Points

  1. 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.

    1. If both host and service are provided, the status of service@host is obtained.
    2. If only host is provided, the composite status of all services monitored for host is obtained.
    3. If only service is provided, the composite status of all hosts monitored for service is obtained.
    4. 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