SURVIVOR: sr Protocol Specification
Specification v2
syntax
  • Whitespace is generally significant, unless otherwise noted.
  • boldface denotes keywords.
  • [brackets] denote optional keywords or values.
  • Separators (|) denote mutually exclusive keywords.
  • The line terminator is \n. 
     <command> : check|exit|fix|version
     <command specific arguments> : [^\n]+
     <command specific data> : .+
     <command specific result> : [^\n]+
     <command specific response> : .+
  
  CLIENT: <command> [<command specific arguments>]
  SERVER: [OK|ERROR] [<command specific result>]
  CLIENT: [BEGIN DATA
  CLIENT: <command specific data>
  CLIENT: END DATA]
  SERVER: [BEGIN RESPONSE
  SERVER: <command specific response>
  SERVER: END RESPONSE]

About Version 2

The protocol consists of one or more exchanges, beginning with the client issuing a command, possibly with one or more arguments, to the server. The server then provides a one line result to the command. If the command permits, the client may then send a data block with more information for the request, and the server may respond with a data block containing more detailed results. This process may be repeated until either end closes the connection or until the client transmits the command exit.

The daemon must know from out-of-band configuration where the module directory is.

Because sr should only be run within a given site, no specific port number is expected.

Version 2 was introduced with release 0.9.6.

Version 2 Keywords

check <module> Execute a check using the specified module.

On success, the server result will be 

   OK send SurvivorCheckData
The client should then send a DATA block with a SurvivorCheckData document (in which the Host element should be "localhost"). The server will return a RESPONSE block with a SurvivorCheckResult document.
exit Terminate the current session.
fix <module> Execute a fix using the specified module.

On success, the server result will be 

   OK send SurvivorFixData
The client should then send a DATA block with a SurvivorFixData document The server will return a RESPONSE block with a SurvivorFixResult document.
version Obtain the server's protocol version. Defined response strings are
  • OK v2
    Protocol version 2.
  • 4:0:Unrecognized command version
    Protocol version 1.

Examples

  1.      version
     OK v2
     check mailq
     OK send SurvivorCheckData
     BEGIN DATA
     <?xml version="1.0" encoding="iso-8859-1"?>
      <SurvivorCheckData Version="1.0">
       <Host>localhost</Host>
       <Timeout>180</Timeout>
       <ModuleOption OptionName="warn">
        <OptionValue>100</OptionValue>
       </ModuleOption>
       <ModuleOption OptionName="prob">
        <OptionValue>1000</OptionValue>
       </ModuleOption>
      </SurvivorCheckData>
     END DATA
     BEGIN RESPONSE
     <?xml version="1.0" encoding="iso-8859-1"?>
      <SurvivorCheckResult Version="1.0">
       <Host>localhost</Host>
       <ReturnCode>2</ReturnCode>
       <Scalar>188</Scalar>
       <Comment>188 messages queued</Comment>
      </SurvivorCheckResult>
     END RESPONSE
     exit

Specification v1
syntax 
 CLIENT: command[:module[:timeout]]
 CLIENT: [argname=argvalue]
 CLIENT: [...]
 CLIENT: 
 SERVER: returnvalue:scalevalue:[comment]

About Version 1

The protocol consists of one or more exchanges, beginning with the client issuing a request to the daemon. The daemon then provides a one line response to that request. This process may be repeated until either end closes the connection or until the client transmits the command exit.

The daemon must know from out-of-band configuration where the module directory is.

Because sr should only be run within a given site, no specific port number is expected.

Version 1 was used in all versions of the package up to and including 0.9.5a.

Version 1 Keywords

command check to indicate that a check module is to be executed, fix to indicate that a fix module is to be executed, or exit to terminate the session.
module The module to be executed. This value must be a relative path name and must not contain '/' characters.
timeout Number of seconds to wait before failing (defaults to 0, for no timeout).
argname Name of argument to be passed to the module.
argvalue Value of argument to be passed to the module.
returnvalue As specified in the check module specification.
scalevalue As specified in the check module specification.
commentvalue As specified in the check module specification.

Examples

  1.      check:mailq
     warn=100
     prob=1000

     2:188:188 messages queued
$Date: 2006/11/20 00:13:18 $
$Revision: 0.7 $
 keywords
check
exit
fix
version
argname (v1)
argvalue (v1)
command (v1)
comment (v1)
module (v1)
returnvalue (v1)
scalevalue (v1)
timeout (v1)