smsd

The SMS daemon takes care of sending alerts queued for SMS dispatch.

The daemon will regularly check the smsq database table via a generalized queue module. Any new messages are dispatched via one or more dispatchers with a generic interface. Support for multiple dispatchers are handled by a dispatcher handler layer.

Usage

For more help on usage, run smsd --help and see the smsd.conf config file.

Message queues

Message queues are generic producers of SMS messages in smsd. At the moment, only the nav.smsd.navdbqueue.NAVDBQueue implementation is available, which will produce SMS messages from the smsq table in the NAV database.

Other message queue implementations can be written using the same interface as implemented by nav.smsd.navdbqueue.NAVDBQueue.

Dispatchers

smsd delegates the actual dispatch of messages to dispatcher plugins. Plugins can be configured in prioritized order in smsd.conf.

Available dispatchers

GammuDispatcher

description:

The Gammu dispatcher uses Gammu to send SMS messages via a cell phone connected to the server with a serial cable, USB cable, IR or Bluetooth. See http://www.gammu.org/ for more information.

depends:

Depends on the gammu Python binding. As a prerequisite, the navcron user must have write privileges to the device where the Gammu-configured mobile phone is connected.

pros:

Works as long as the mobile carrier is up and running, independent of your own network.

cons:

You will need a dedicated mobile phone or other GSM device.

HttpGetDispatcher

description:

Originally contributed by USIT, University of Oslo for use with their HTTP-to-SMS gateway. Generalized to be useful for similar gateways without UiO’s exact URL syntax. Supports both HTTP and HTTPS.

depends:

Depends on urllib and urllib2, which both are parts of core Python.

pros:

Does not need a dedicated mobile phone.

cons:

Depends on a working network connection between you and your HTTP-to-SMS gateway. Does not support POST or HTTP Basic Auth.

BoostDispatcher

description:

This dispatcher sends SMS via Boost Communications’ WebService (SOAP). See http://www.boostcom.no/ for more information.

Note

The dispatcher is provided as a proof-of-concept only; it seems it no longer conforms to Boost’s newest APIs.

depends:

Depends on SOAPpy (python-soappy in Debian). Requires a username and password to send SMS using the SOAP interface. Contact http://www.boostcom.no/ to setup a contract for their External Sender product.

pros:

Does not need a dedicated mobile phone.

cons:

Depends on a working network connection between you and Boost Communcations.

UninettMailDispatcher

description:

This dispatcher sends SMS via Sikt’s (previously Uninett) email-to-SMS gateway. Sikt’s gateway only works internally, but this plugin can serve as a proof-of-concept for someone implementing a similar service. The e-mail adress is configurable in smsd.conf.

depends:

Only depends on smtplib, which is a part of core Python (of course, a working SMTP server is required also).

pros:

If you have an email-to-SMS gateway that accepts e-mails where the subjects is a phone number and the body is an SMS text message, there is no extra setup cost to get the daemon sending SMS messages.

cons:

Unless you have a similar email-to-SMS gatway, this only works for Sikt.

Extending

Write your own dispatcher by extending the nav.smsd.dispatcher.Dispatcher class. You can also implement your own message queue by implementing the same interface as the nav.smsd.navdbqueue.NAVDBQueue class.

nav.smsd.dispatcher

Dispatch handling for smsd

class nav.smsd.dispatcher.Dispatcher

The SMS dispatcher mother class.

__init__()

Constructor.

formatsms(msgs)

Formats a single SMS from one or more messages.

Attempts to squeeze as many messages into the 160-characters that an SMS is limited to.

Parameters:

msgs – a list of messages ordered with the most severe first. Each message is a tuple with ID, text and severity of the message.

Returns:

a 3-value tuple containing:

• the formatted text of the SMS

• a list of IDs of the messages that fit into the single SMS

• if list of IDs of the message that didn’t fit in the SMS and were subsequently ignored

sendsms(phone, msgs)

Sends messages as an SMS to a phone number.

This method must be overridden by implementers to have any effect.

Parameters:

• phone – the phone number the messages are to be dispatched to.

• msgs – a list of messages ordered with the most severe first. Each list element is a tuple with (ID, text, severity)

Returns:

a tuple containing 5 values:

• The formatted SMS.

• A list of IDs of sent messages.

• A list of IDs of ignored messages.

• A boolean which is true for success and false for failure.

• An integer which is the sending ID if available or 0 otherwise.

exception nav.smsd.dispatcher.DispatcherError

Base class for all exceptions raised by dispatchers.

class nav.smsd.dispatcher.DispatcherHandler(config)

Handler for communication with the dispatchers.

This layer makes it possible to use multiple dispatchers which works as failovers for each other.

__init__(config)

Constructor.

importbyname(name)

Imports Python module given by name.

Parameters:

name – a module name.

Returns:

a module object.

sendsms(phone, msgs)

Formats and sends with help of the wanted dispatcher.

Parameters:

• phone – the phone number the messages are to be dispatched to.

• msgs – a list of messages ordered with the most severe first. Each message is a tuple with ID, text and severity of the message.

Returns:

A tuple of four values:

• The formatted SMS.

• A list of IDs of sent messages.

• A list of IDs of ignored messages.

• An integer which is the sending ID if available or 0 otherwise.

Raises:

DispatcherError if it doesn’t find a working dispatcher and succeeds in sending the SMS.

exception nav.smsd.dispatcher.PermanentDispatcherError

Thrown for permanent errors in dispatchers.

nav.smsd.navdbqueue

The smsd queue for the NAV database.

This smsd queue takes care of all communication between smsd and the NAV database. Replacing the NAV database with some other queue/input should be possible by implementing the interface seen in this class.

Generally, a phone number is a user and vice versa.

class nav.smsd.navdbqueue.NAVDBQueue

The smsd queue for the NAV database.

__init__()

cancel(minage='0')

Mark all unsent messages as ignored.

Input:

minage Minimum age required for canceling message, default ‘0’.

Format as PostgreSQL interval type, e.g. ‘1 day 12 hours’.

Returns number of messages canceled.

getmsgs(sent='N')

Get all messages with given sent status (normally unsent).

Returns a list of dictionaries containing messages details of SMS in queue with the specified status.

getusermsgs(user, sent='N')

Get the user’s messages which has given sent status (normally unsent).

Returns a list of messsages ordered with the most severe first. Each message is a tuple with the ID, text, and severity of the message.

getusers(sent='N')

Get users which has messages with given sent status (normally unsent).

Returns a sorted list with the phone numbers for all users with messages with given sent status.

inserttestmsgs(uid, phone, msg)

Insert test messages into the SMS queue for debugging purposes.

Returns a integer indicating how many rows have been inserted.

setsentstatus(identifier, sent, smsid=0)

Set the sent status of a message given ID and status.

Returns number of messages changed.