This is the handbook for SMSC-Gateway, a software package that can be used to send and receive short messages via various connections to SMSCs.
It tries to help you, if you want to use SMSC-Gateway or want to understand how SMSC-Gateway works and then decide if it might be useful to you.
This first chapter gives a short introduction to SMSC-Gateway, chapter two will describe how to get and install SMSC-Gateway and the third chapter will show how to configure SMSC-Gateway and try to help to understand what the configuration files are used for. In the appendix you will find a list of hardware that has already been used with SMSC-Gateway.
SMSC-Gateway has been built as an experimental alarming system for firemen. We wanted to find out if it would be useful to use short messages to GSM phones instead of messages to pagers to call firemen in case of emergency. There were two main advantages expected by this system:
This point has been seen as a possibility to save resources, because there would be no need to always alarm more firemen than actually needed and send those firemen for whom was no need back home.
Because SMSC-Gateway's area of operation was in the field of rescue service it was build to be very reliable. For that reason different connection types have been used so that certain connections can be used as fallback connections should other ones fail for some reason.
SMSC-Gateway was build in a modular way. There is a main server part, a client part that can be used to contact the server to send short messages and finally there are connections that actually hand over the messages to the SMSCs for delivery to the recipients. The different connections work with different hardware; currently available connection types are:
In the future it could be possible that connections are added that not only operate on short messages but also on other things like mail, fax or even synthesize voice mail.
SMSC-Gateway also comes with a rudimentary web-interface that can be used to monitor certain statistics (number of active connections, number of restarted connections, sent messages, received messages...) and to start, stop and restart the server. However, this interface was tailored for the needs of the firestation project and you maybe do not find it useful.
Throughout this manual I will use some terms that may be unfamiliar to you or that should be defined, to avoid misunderstandings. Here is a list of such terms:
smscgwc or a connection to make it transmit a message to one
ore more recipients. A send request consists of a list of recipient
addresses and a message text.
The sources for SMSC-Gateway can be downloaded from http://smscgw.ccamp.de/. Once arrived there, go to the download section and get the latest tar-ball.
Once you downloaded the sources, follow the next steps to build the
binaries. You do not necessarily have to build the sources in the
directory /usr/src/. You can choose any other location.
cd /usr/src/
tar -zxf path_to_the_tar_ball
cd smscgw-1.1.11
configure script to prepare the compilation process:
./configureThere are some options to
configure that you might want to
use:
--prefix
make install will install binaries, configuration
files, etc. The default location is /home/smscgw.
--with-httpdir
/home/smscgw/www/data.
--with-cgidir
/home/smscgw/www/cgi-bin/.
./configure --help
make make install
SMSC-Gateway comes with four configuration files. By default they
will be installed in the directory /home/smscgw/etc/. Here is an
overview about which purposes they serve:
smscgw.conf
smscgw to send messages and the various
connections one wants to use to pass the client's send requests to
SMSCs. Briefly, this file is to tell smscgw about
connections and routes it should use.
m20_conn.conf
ta_conn.conf
tcp_conn.conf
smscgw, you have to edit
smscgw.conf and one of the connection's configuration files, at
least. In smscgw.conf you have to specify which connection(s)
you want to use and, which connection to use for what kind of recipient
address. See The description of smscgw.conf, and the
following pages for a detailed description of the configuration files
for the various connections.
Before running SMSC-Gateway with its server process, clients and
connections it is a good idea to check wether each of the connections
works, i.e. if the hardware is OK and if the configuration files are
correct. This can easily be done, since each connection can be run as
a standalone program and in this case produces error output to the
console.
If you, for example, want to run SMSC-Gateway with a GSM phone attached
to a serial interface, you have to edit the configuration file
/home/smscgw/etc/m20_conn.conf and after that can run
/home/smscgw/bin/m20_conn and see if it starts up correctly.
Here is an example for a startup with an incorrect configuration file:
# /home/smscgw/bin/m20_conn read_config_file: M20_DEVICE MUST be specified! Error in configuration file /home/smscgw/etc/m20_conn.conf!
A startup with a correct configuration file looks like this:
# /home/smscgw/bin/m20_conn Modem device opened. init_m20: Checking for PIN...PIN is OK. init_m20: Setting PDU mode...done. init_m20: Entering SMSC number...done. Modem ready:At this point, you can try to send a message. Each connection accepts input similar to that of
smscgwc:
/home/smscgw/etc/smscgw.conf, but
problems with the connections are excluded.
In this chapter, I will go into the details of each part of SMSC-Gateway: the server process, the client process and the various processes that manage connections to SMSCs.
smscgw is the server process of SMSC-Gateway. It communicates
with clients that want to send messages and with the connections one
uses to connect to SMSCs.
smscgw produces verbose messages that are passed to the syslog
daemon. Lots of the messages are for debugging purposes and are given
the corresponding level of severity. So, if you don't like the huge
amount of logged messages, you may want to configure your syslogd to
ignore smscgw's debug level messages.
On startup, smscgw reads its configuration file and prepares
an internal table of known connections and a routing table. After that,
a call manager process and a transceiver process are
created.
The call manager waits for clients to connect. For each connecting client it forks a new client handler process that hands over send requests to the transceiver and results from the transceiver back to the connected client.
After creation, the transceiver process first starts connections that are marked permanent and then waits for either send requests from clients or incoming data from connections.
If a send request from a client arrives, the transceiver determines what connection(s) to use to transmit the request. That decision is based on the routing table and on the priorities of the connections. If different connections have to be used for the recipients of a single send request, the send request is divided in sub-requests that contain recipients that can all be reached via a single connection. After that, the requests are passed to the connection(s). The transceiver process then waits for result messages from the connection(s) and passes them back to the client handler.
If an incoming message from a connection arrives, the
tranceiver saves that message in a daily file in the incoming
directory. This directory defaults to /tmp and can be changed
with the INCOMING_DIR directive in the configuration file
/home/smscgw/etc/smscgw.conf.
Further, if for the connection that delivers the incoming message, an INCOMING_SCRIPT was specified, that script is executed and the incoming messages is passed to the script via its standard input.
In this section the configuration file of smscgw.conf will be
described.
smscgw.conf consists of sections with various directives.
Sections start with a section name and an opening brace "{" and end with
a closing brace "}".
Empty lines and text following a hash character ("#") are interpreted as comments and ignored.
The directives inside the sections are keyword = value pairs where the values can be one of three types:
There are three sections that may appear in smscgw.conf and they
must be given exactly the section name as shown below:
smscgw without knowing about a connection
that it could use to deliver messages handed over by a client.
In the CALL_MANAGER section configuration directives for the call manager can be specified. There are currently two directives that can be used inside this section:
In the client handler section only one directive can be used:
If this directive is unspecified, the default value of 60 seconds will be used.
As already stated, this section may be used several times - one for each connection you want to use to deliver messages to SMSCs. In a CONNECTION section the following directives can be used; some of them are mandatory, others are optional:
smscgw which
program actually implements the connection and what command line
arguments it will be passed.
Priorities are used when smscgw is about to decide which
connection to use to deliver send requests; higher priority connections
are considered prior to lower priority ones.
smscgw what recipients can be reached via
a connection. The string is interpreted as a regular expression
according to regexec(3). This directive may appear multiple
times inside a single section.
Currently, this directive is optional, but if it left out completely, it means that the connection cannot deliver messages to anywhere.
This will be corrected in a future release.
smscgw in which directory to save
incoming messages. It defaults to /tmp/. When incoming
messages arrive at a connection, they will be saved in daily files
in the directory specified by INCOMING_DIR.
NOTE: Incoming scripts will become new processes and it is possible that multiple of them run in parallel. So, one has to take care for racing conditions when writing programs or scripts for incoming messages!
In the following I will present some examples of configuration files for
smscgw:
Note: In this example the program tcp_conn will
expect its configuration parameters to be in its default configuration
file, i.e. /home/smscgw/etc/tcp_conn.conf.
#
# We accept default values and specify the only one mandatory section.
#
CONNECTION {
NAME = "tcp-connection"
PROGRAM = "/home/smscgw/sbin/tcp_conn"
PRIORITY = 99
ROUTE = "[0-9]+"
}
Here, we have to use the command line option -c for each
connection to tell it where it finds its configuration file. Further,
all connections get the same priority but different routes, so that each
connection only serves recipients whose addresses have a prefix that
belongs to the GSM network that that connection should send
messages to.
#
# Use GSM connection for a fictious GSM network
#
CONNECTION {
NAME = "X1"
PROGRAM = "/home/smscgw/sbin/m20_conn -c /home/smscgw/etc/x1.conf"
PRIORITY = 99
ROUTE = "0171[0-9]+"
ROUTE = "0175[0-9]+"
}
#
# And another GSM device for another GSM network.
#
CONNECTION {
NAME = "X2"
PROGRAM = "/home/smscgw/sbin/m20_conn -c /home/smscgw/etc/x2.conf"
PRIORITY = 99
ROUTE = "0162[0-9]+"
ROUTE = "0172[0-9]+"
}
#
# And a further GSM device for the last GSM network.
#
CONNECTION {
NAME = "X3"
PROGRAM = "/home/smscgw/sbin/m20_conn -c /home/smscgw/etc/x3.conf"
PRIORITY = 99
ROUTE = "0179[0-9]+"
}
Starting smscgw is simple - just type in the path to the
binary, thats it. If you for some reason don't want smscgw to
become a daemon, you can use the option --debug to it, e.g:
/home/smscgw/sbin/smscgw --debug
If you want to stop smscgw, you need to send its call manager
a TERM signal. It then will take care that all processes that belong to
the smscgw session will terminate. To send the call manager a TERM
signal you need to know its process ID which can be found in the
file /var/run/smscgw.pid. So, here is an example on how to terminate a
smscgw daemon:
kill -TERM `cat /var/run/smscgw.pid`
smscgwc is a client program that can be used to connect to a
machine running the server process smscgw and hand it over a
message it should send to one or a list of recipients.
Input to smscgwc is identical to that of the connections:
After a smscgwc handed over a send request to
smscgw it waits for the result from the server. However, the
server may close the connection with a timeout message and in this case
the client should consider the delivery to have failed for some reason.
smscgwcip-addressport
smscgwc must be given the IP-address of the server running
smscgw and the port on which it is listening for client
connections. After the connection to the server has been established,
smscgwc displays the server's greeting message and then
silently waits for input of a send request. After receipt of a send
request, it hands the request over to the server, then waits for the
server's acknowledge message, displays it and terminates.
Here is the output of a sample smscgwc-session:
client: smscgw 192.168.0.2 1025 Welcome to smscgw 01234567890 An example for the handbook;-) . Thanks - please wait for result... Request for 01234567890 successfully transmitted. . client:
In this section, I will talk about the connections smscgw uses
to deliver messages to SMSCs. The connections are standalone
programs that can also be used independently of smscgw. They
all follow three simple rules:
stdin) and have
to be of the following format:
01621234567 01721234567 01711234567 This is the text that should be sent to the above recipients .
stdout).
The format of incoming messages is identical to the format of send
requests, they just start with one sender address instead of one or
several recipient addresses.
stderr).
m20_conn is a connection that can talk to GSM
devices attached to a serial port of the computer.
m20_conn only works with devices that understand AT commands.
It supports text mode and PDU mode operation and is known to work with
devices listed in the supported hardware section.
Once, m20_conn has been started, it waits for send requests to
deliver to the SMSC from standard input and checks for
incoming messages from the GSM device in intervals specified by the
configuration directive CHECK_INCOMING_INTERVAL. If new
incoming messages are present, they are printed to standard output and
deleted from the GSM device's memory.
m20_conn { -c | --config-file } filename
The only one option, m20_conn understands is the one to tell
it to read another configuration file, than the default
/home/smscgw/etc/m20_conn.conf.
This section describes the configuration file for m20_conn.
It must not necessarily be called m20_conn.conf, but I will use
this name to refer to the configuration file for the program
m20_conn.
m20_conn.conf mainly consists of keyword=value
directives. Empty lines and lines starting with a hash character "#"
are comments and ignored. The following table lists the keywords,
m20_conn understands; they must be written exactly as
they appear here:
/dev/cuaa0,
/dev/cuaa1... and on a GNU/Linux system possible values are
/dev/ttyS0, /dev/ttyS1...
4800
9600
19200
38400
ta_conn is a connection that can talk to an ISDN
terminal adapter which on the other side can talk to a SMSC
via X.31. Up to know only one terminal adapter has been used and I am
pretty sure that other products would cause problems.
tcp_conn is a connection that can directly talk to a
SMSC via a TCP/IP connection using the EMI protocol.
Should you ask yourself what provider offers a publicly reachable IP-address for such a connection, I am pretty sure the answer is none. I used a TCP/IP connection via a ISDN line and needed a quite expensive large account at the GSM network provider.
I would like to thank the fire-brigade in Bocholt, Germany for the opportunity to build SMSC-Gateway and for giving me access to hardware and SMSC connections I would otherwise never get my hands on.
Further, many thanks to the following individuals:
Alexander Bergmann
Harald Knapp
Salvatore Mantaci
Roland Moritz
The following table lists connections and hardware that has already been used with them, i.e. is known to work with SMSC-Gateway:
m20_conn
m20_conn
m20_conn
m20_conn
m20_conn
m20_conn
m20_conn
m20_conn
ta_conn
tcp_conn