survivor: Mail Gateway (sg)

SURVIVOR: Mail Gateway
About `sg` Dependencies Installation Configuring the Mail System Syslogging With Nextel Two-Way Messaging With SMS Text Messages Relaying Messages
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)