SURVIVOR: Mail Gateway
About sg
usage 
 
    sg

The Survivor Mail Gateway allows email based reply messages to affect the system state. It reads the messages on stdin, executes any valid commands found, and records its actions via syslog. The gateway can also relay messages to Persons and Call Lists.

The gateway is used to accept replies in response to previously generated alert notifications. It is not intended to be a general purpose interface. Tokens are required in replies to prevent delayed replies from inadvertantly changing state when they are no longer relevant, and to provide a frustration against nuisance attacks against the gateway. Tokens are not guaranteed to be secure against more sophisticated attacks.

The gateway will not accept messages larger than MAXMESSAGESIZE as defined in include/gateway.H. This value defaults to 50,000 bytes.

Dependencies

  • The gateway must run on the same host as the scheduler.
  • sg uses the standard instance configuration file /etc/survivor/instance.cf to obtain information about the configured Instances. The location of this file cannot be overridden.

Installation

The gateway is installed in $INSTDIR/sbin/sg. Two-way reply messages must be piped into sg, the specific method for doing so is dependent on the mail system in use.

Configuring the Mail System

By default, alert notifications sent by the scheduler should have a return address of $INSTUSER@schedulerhost, although this is dependent on the local mail configuration. The key installation step is to intercept reply messages sent to this address and direct them to sg. An easy way to do this is by creating $INSTUSER/.forward with contents like 
 |$INSTDIR/sbin/sg
or, to keep a copy of each messages received 
 |$INSTDIR/sbin/sg,\$INSTUSER
$INSTDIR and $INSTUSER must be replaced with their actual values. Additionally, some mail handlers may require the entire line to be surrounded by quotes ("). Note that for Sendmail, sg may need to be run via smrsh.

Using procmail, $INSTUSER/.procmailrc could contain an entry like 

 # Pipe all mail to sg for processing two-way replies
 :0 H
 * ^To:.*$INSTUSER@schedulerhost
 | $INSTDIR/sbin/sg
Again, $INSTDIR and $INSTUSER must be replaced with their actual values.

It may also make sense to intercept the messages at a system-wide level, rather than wait until delivery to the local user. This would require changes to /etc/aliases, /etc/mail/aliases, the global procmailrc, sendmail.cf, or any other relevant file.

Syslogging

The gateway syslogs as follows:
  • mail.debug: Debugging information, including configuration file parse errors. It is possible to enable additional debugging to this facility with the debug level keyword in gateway.cf.
  • mail.warning: Warnings and errors other than configuration.
  • mail.info: Non-critical message processing information.
In order to generate appropriate processing logs, configure these service in /etc/syslog.conf.

With Nextel Two-Way Messaging

Messages formatted with the nextel format module are capable of being replied to and processed by the gateway. Messages must be transmitted via Nextel's two-way messaging infrastructure, which as of this writing is not available via TAP (modem transmission of pages). Simply select the appropriate command when replying to the alert notification.

message syntax 
  From: <address>
  Subject: [optional unrelated text] ALERT: <service>@<hostname>

  <replycommand>
  Token=<token>
  Instance=<instance>
where
  • address: The sender of the reply command
  • service: The name of the service (Check) the reply is for
  • hostname: The name of the host the reply is for
  • replycommand: One of Acknowledge, Escalate, or Inhibit
  • token: The same token than was transmitted in the original alert notification
  • instance: The name of the Instance that the original alert notification was generated from
example reply 
  From: foo@bar.com
  Date: Mon, 06 Aug 2001 11:01:06 -0400
  To: survivor@bar.com
  Subject: RE: ALERT: test1@apple

  Acknowledge

  In Reply To Your Message
  
  Connection refused
  11:00:21 08/06/2001
  Token=1811060716
  Instance=test

With SMS Text Messages

Messages formatted with the sms format module are capable of being replied to and processed by the gateway, however the mechanism is more complicated due to the limitations of SMS text messaging.

First, the mail system must be capable of delivering messages addressed to $INSTUSER+x@scheduler, where x is the one letter command described below. For example, survivor+e@monitor.foo.edu must be delivered to survivor@monitor.foo.edu. Sendmail sites may already have this functionality enabled. Other sites may need to make adjustments. One approach would be to define aliases in /etc/aliases (if appropriate for the local mail system): 

 survivor+a: survivor
 survivor+e: survivor
 survivor+i: survivor

In order to reply to an alert notification, forward the message (do not reply to it) to the address for the appropriate command:

  • +a: Acknowledge
  • +e: Escalate
  • +i: Inhibit

message limitations The length of the address the reply message is forwarded to plus the length of the address the reply message is sent from (usually of the form phonenumber@provider.com) cannot exceed 60 characters. Note the message body consists of one line.
message syntax 
  From: <address>
  To: <survivor>+<command>@<scheduler>
  Subject: [optional unrelated text]ALERT: <service>@<hostname>

  [optional unrelated text]T=<token>,I=<instance> \
  [optional unrelated text]
or 
  From: <address>
  To: <survivor>+<command>@<scheduler>

  [optional unrelated text]ALERT: <service>@<hostname>/\
  [optional unrelated text]T=<token>,I=<instance> \
  [optional unrelated text]
where
  • address: The sender of the reply command
  • command: One of a, e, or i
  • service: The name of the service (Check) the reply is for
  • hostname: The name of the host the reply is for
  • scheduler: The host the scheduler runs on
  • survivor: The name of the survivor user
  • token: The same token than was transmitted in the original alert notification
  • instance: The name of the instance that the original alert notification was generated from
example reply 
  Date: Mon, 27 Jan 2003 15:48:42 -0500 (EST)
  From: foo@mar.com
  To: survivor+e@bar.com
  Subject: ALERT: test1@apple

  T=Q874954334,I=test  No response from host  15:10:04 01/27/2003
example reply 
  Date: Mon, 27 Jan 2003 15:48:42 -0500 (EST)
  From: foo@mar.com
  To: survivor+e@bar.com

  ALERT: test1@apple/ T=Q874954334,I=test  No response from host \
  15:10:04 01/27/2003

Relaying Messages

The gateway can accept messages and relay them to Persons or Call Lists. By default, this functionality is disabled. To enable message relaying, edit the configuration file gateway.cf.
$Date: 2006/11/19 17:33:07 $
$Revision: 0.12 $
 (sg)