Hi Rene,
Let me apologize for x-posting. This needs to go to devel, but since a few
people in users list were asking about it, it is posted in both.
This is the SMPPBox documentation. I have shamelessly usurped some parts,
especially on configuration, from kannel's userguide, to preserve
continuity. I have also included a few features in the general
decription/functionality, that may not there, but will need to be done (ie
DLR rewriting). All specifics (i.e. configuration) reflect only the current
state. Please review and correct/add any errors/ommisions.
As with all kannel documentation, it is in XML and you will need docbook to
convert it into a useful form.
Enjoy!
Nikos
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN"
[
<!ENTITY figtype "#FIGTYPE#">
<!ENTITY timestamp "#DATE#">
<!ENTITY version "#VERSION#">
<!ENTITY % draft "#DRAFTS#">
]>
<!-- Embbeb your block with these to set it to "draft"
<![%draft;[ <your block> ]]>
-->
<book>
<bookinfo>
<title>SmppBox &version; User's Guide</title>
<subtitle>Open Source SMPP proxy</subtitle>
<authorgroup>
<author>
<firstname>Rene</firstname>
<surname>Kluwen</surname>
<affiliation>
<jobtitle>Chairman & CTO</jobtitle>
<orgname>Chimit Ltd.</orgname>
<address> <email>[email protected]</email>
<otheraddr></otheraddr>
</address>
</affiliation>
</author>
<author>
<firstname>Nikos</firstname>
<surname>Balkanas</surname>
<affiliation>
<jobtitle>Technical Architect</jobtitle>
<orgname>InAccess Networks SA</orgname>
<address>
<email>[email protected]</email>
</address>
</affiliation>
</author>
</authorgroup>
<abstract>
<title>Abstract</title>
<para>
This document describes how to install and use SMPPBox, the Open
Source SMPP proxy originally developed by Chimit Ltd. and now
being developed further by the open source community, namely the
Kannel Group.
</para>
</abstract>
<revhistory>
<revision>
<revnumber>&version;</revnumber>
<date>×tamp;</date>
</revision>
</revhistory>
</bookinfo>
<chapter>
<title>Introduction</title>
<para>This chapter introduces SMPP in general terms, and
explains the role of SMPPBox in SMS flow, outlining its duties
and features.
</para>
<sect1>
<title>Overview of SMPP</title>
<para>
The Short Message Peer to Peer (SMPP) protocol is an open,
industry standard protocol designed to provide a flexible data
communications interface for transfer of short message data
between a Message Center, such as a Short Message Service Centre
(SMSC), GSM Unstructured Supplementary Services Data (USSD) Server
or other type of Message Center and a SMS application system, such
as a WAP Proxy Server, EMail Gateway or other Messaging Gateway.
It was maintained by the SMS Forum until it reached maturity and
was subsequently disbanded in July 2007.
</para>
<para>
SMPP Release v3.4, its most popular version, launched in 12/9/1999.
Now in its latest implementation, v5.0 further development has been
discontinued since the disband of the SMS Forum. All protocols and
specifications can still be downloaded from http://www.smsforum.net/.
</para>
<para>
SMPP supports Digital Cellular Network technologies including:
</para>
<para>
<itemizedlist>
<listitem><para>GSM</para></listitem>
<listitem><para>IS-95 (CDMA)</para></listitem>
<listitem><para>ANSI-136 (TDMA)</para></listitem>
<listitem><para>iDEN</para></listitem>
</itemizedlist>
</para>
<para>
Using the SMPP protocol, an SMS application system called the
"External Short Message Entity" (ESME) may initiate an application
layer connection with an SMSC over a TCP/IP or X.25 network
connection and may then send short messages and receive short
messages to and from the SMSC respectively. The ESME may also query,
cancel or replace short messages using SMPP.
</para>
<para>
SMPP supports a full featured set of two-way messaging functions
such as:
</para>
<para>
<itemizedlist>
<listitem>
<para>Transmit messages from an ESME to single or multiple
destinations via the SMSC</para>
</listitem>
<listitem>
<para>An ESME may receive messages via the SMSC from other
SME's (e.g. mobile stations).</para>
</listitem>
<listitem>
<para>Query the status of a short message stored on the
SMSC</para>
</listitem>
<listitem>
<para>Cancel or replace a short message stored on the
SMSC</para>
</listitem>
<listitem>
<para>Send a registered short message (for which a "delivery
receipt" will be returned by the SMSC to the message
originator)</para>
</listitem>
<listitem>
<para>Schedule the message delivery date and time</para>
</listitem>
<listitem>
<para>Select the message mode, i.e. datagram or store and
forward</para>
</listitem>
<listitem>
<para>Set the delivery priority of the short message</para>
</listitem>
<listitem>
<para>Define the data coding type of the short message</para>
</listitem>
<listitem>
<para>Set the short message validity period</para>
</listitem>
<listitem>
<para>Associate a service type with each message e.g. voice
mail notification</para>
</listitem>
</itemizedlist>
</para>
</sect1>
<sect1>
<title>SMPPBox overview</title>
<para>
SMPPBox is an opensource SMPP proxy, which forwards GSM SMPP PDUs.
It is not a pure proxy in the clear sense of the word, since it
is not limited to the SMPP protocol. It features an SMPP server port
for incoming ESME connections, but the client port uses the more
flexible Kannel (Msg *) protocol for connection to Kannel's Bearerbox.
This way it can take advantage of Bearerbox's client SMSc protocols
not limited to SMPP, but extending to CIMD2, EMI/UUCP etc. As such,
it can be used only for MT SMS traffic.
</para>
<figure>
<title>SMPPBox Layout </title>
<graphic fileref="SMPPBox&figtype;"></graphic>
</figure>
<para>
The ESME connects over SMPP to SMPPBox, thinking that it is an SMSc.
Accounts are configured in SMPPBox to allow connections only from
specific clients. The SMS is forwarded to Bearerbox, which routes it
to the best available SMSc over a variety of protocols.
</para>
<para>
Meanwhile the SMSc will generate both final and intermediate DLRs.
These are routed back from Bearerbox to SMPPbox, which are then
rewritten, as to appear that they originated from SMPPBox. These
are finally routed back to the requesting ESME.
</para>
<para>
SMPPbox presents a layer of abstraction to the ESME. The ESME
doesn't know the real SMScs used for SMS delivery. As far as it
is concerned, it is dealing only with a single SMSc, SMPPBox.
</para>
</sect1>
<sect1>
<title>Features</title>
<para>
SMPPBox provides for compliance to SMPP v3.4 & SMPPv5.0 for
MT SMS routing over GSM. Options are limited by the features
provided by Bearerbox.
</para>
</sect1>
<sect1>
<title>Requirements</title>
<para>
Latest Kannel must be installed (>1.4.3 svn version). Kannel's gwlib
is needed for compilation. Additionally an working Bearerbox is needed
to route SMS to. If it is not available, SMS will collect to queue,
waiting for an active Bearerbox.
</para>
<para>
A C compiler and libraries for ANSI C are needed, with normal
Unix extensions such as BSD sockets and related tools. (GNU's GCC
tool-chain is recommended)
</para>
</sect1>
</chapter>
<chapter>
<title>Installation</title>
<para>
This chapter explains how the gateway can be installed,
either from a source code package or by using a pre-compiled
binary version. The goal of this chapter is to get the gateway
compiled and all the files in the correct places; the next
chapter will explain how the gateway is configured.
</para>
<note>
<para>
If you are upgrading from a previous version, please look at
<xref linkend="upgrading-notes"> for any important information.
</para>
</note>
<sect1>
<title>Getting the source code</title>
<para>
The source code is available from Kannel's site, through svn:
</para>
<para>
<emphasis>svn co https://svn.kannel.org/smppbox/trunk</emphasis>
</para>
<para>
Authentication is not needed.
</para>
</sect1>
<sect1>
<title>Finding the documentation</title>
<para>SMPPBox documentation consists of two parts:
<orderedlist>
<listitem><para><citetitle>User's Guide</citetitle>, i.e., the one
you're reading at the moment.</para></listitem>
<listitem><para>The <filename>README</filename> and various other
text files in the source tree.</para></listitem>
</orderedlist>
</para>
<para>You can also find general information on Kannel's
<ulink url="http://www.kannel.org";>website</ulink> and
information about existing problems at
<ulink url="http://bugs.kannel.org";>our bug tracker</ulink>.
</para>
<para>
We intend to cover everything you need to install and use Kannel
is in <citetitle>User's Guide</citetitle>, but the guide is still
incomplete in this respect. The <filename>README</filename> is not
supposed to be very important, nor contain much information. Instead,
it will just point to the other documentation.
</para>
</sect1>
<sect1>
<title>Compiling the proxy</title>
<para>If you are using SMPPBox on a supported platform, or one
that is similar enough to one, compiling Kannel should be trivial.
After you have unpacked the source package of your choose,
or after you have checked out the source code from CVS, enter
the following commands:
<screen><userinput>
./configure
make
</userinput></screen>
The <filename>configure</filename> script investigates various
things on your computer compilation needs, and writes out the
<filename>Makefile</filename> used to compile SMPPBox.
<command>make</command> then runs the commands to actually
compile it. It generates the <filename>configure.log</filename>,
of all actions taken, usually the first step in debugging in case
of errors.
</para>
<para>
If either command writes out an error message and stops
before it finishes its job, you have a problem, and you either
need to fix it yourself, if you can, or report the
problem to the Kannel project. See <xref linkend="bug-reporting">
for details.
</para>
<para>
For detailed instructions on using the configuration
script, see file <filename>INSTALL</filename>. That file is
a generic documentation for <command>configure</command>.
</para>
<para>
You may need to add compilations flags to configure:
<screen><userinput>
CFLAGS='-pthread' ./configure
</userinput></screen>
The above, for instance, seems to be required on FreeBSD. If you
want to do development, you probably want to add CFLAGS that make
your compiler use warning messages. For example, for GCC:
<screen><userinput>
CFLAGS='-Wall -g' ./configure
</userinput></screen>
(You may, at your preference, use even stricter checking options.)
</para>
</sect1>
<sect1>
<title>Installing the proxy</title>
<para>
After you have compiled SMPPBox, you need to install
certain programs in a suitable place. This is most easily
done by using <command>make</command> again:
<screen><userinput>
make bindir=<replaceable>/path/to/directory</replaceable> install
</userinput></screen>
Replace <replaceable>/path/to/directory</replaceable> with the
pathname of the actual directory where the programs should be
installed. Actually a single program is installed <filename>smppboxi
</filename>
The version number of the proxy is added to the file
during installation. This makes it easier to have several
versions installed, and makes it easy to go back to an older
version if the new version proves problematic.
</para>
<para>
After installation, you should now be able to run the SMPPBox init.d
script that will start the proxy. Run the script as root.
</para>
<screen><userinput>
/etc/init.d/smppbox start
</userinput></screen>
<para>
To stop the gateway just run the same script with the
stop parameter.
</para>
<screen><userinput>
/etc/init.d/smppbox stop
</userinput></screen>
<para>
If SMPPBox is already running and you just want to quickly
stop and start the gateway,e.g.to set a new configuration option,
run the script with the restart parameter.
</para>
<screen><userinput>
/etc/init.d/smppbox restart
</userinput></screen>
</sect1>
</chapter>
<chapter>
<title>Using SMPPBox</title>
<para>
This chapter explains how the proxy, SMPPBox, is configured and used.
It covers the configuration file and keeping an eye on the gateway
while it is running.
</para>
<para>
There is only one configuration file for all parts of SMPPBox. If
several proxy instances are distributed among different hosts, each one
needs to have its own configuration file, with its own options.
</para>
<sect1>
<title>Configuring the proxy</title>
<sect2>
<title>Configuration file syntax</title>
<para>
A configuration file consists of groups of configuration
variables. Groups are separated by empty lines, and each variable
is defined on its own line. Each group in Kannel configuration is
distinguished with a group variable. Comments are lines that begin
with a number sign (<literal>#</literal>) and are ignored (they
don't, for example, separate groups of variables).
</para>
<para>
A variable definition line has the name of the variable,
and equals sign (<literal>=</literal>) and the value of the
variable. The name of the variable can contain any characters
except white space and equals. The value of the variable is a
string, with or without quotation marks (<literal></literal>)
around it. Quotation marks are needed if the variable needs to
begin or end with white space or contain special
characters. Normal C escape character syntax works inside
quotation marks.
</para>
<para>Perhaps an example will make things easier to comprehend:
<programlisting>
1 # Proxy configuration
2 group = smppbox
3 bearerbox-host = 127.0.0.1
4 bearerbox-port = 13000
6 smppbox-id = smppbox1
7 smppbox-port = 13001
8 log-file = /var/log/kannel/smppbox.log
9 log-level = 0
10 our-system-id = Inaccess
11 route-to-smsc = fast_smsc
12 # New accounts
13 smpp-logins = /etc/smppbox/clients
</programlisting>
</para>
<para>
Lines 1 and 12 are comment lines. A blank line is needed to
separate groups. The remaining lines define variables. The
group type is defined by the group variable value.
</para>
<para>
The variables used in each configuration group are explained below:
</para>
<para>
Some variable values are marked as <literal>'bool'</literal>.
The value for such a variable is true, false, yes, no, on, off, 0
or 1. Arbitrary values are treated as 'true' while if the
variable is missing, it is treated as being 'false'.
</para>
<para>
In order to make some configuration lines more readable you may
use the delimiter '\' at the end of a line to wrap and concatenate
the next line up to the current line. Here is an example:
<programlisting>
1 # A group with a wrapped alias line
2 group = dummy
3 anything = hello
4 aliases = hallo;haalloo;\
5 heelloo;haelloo;healloo
6 whatever = "Hello world!"
</programlisting>
The above example shows how a list for various alias keywords
is wrapped to two lines using the line wrap delimiter. In order
to use the delimiter '\' itself, you need to escape it via a
prefixed '\' itself. So this is '\\' to escape the wrapping
function and use the character in the string.
</para>
</sect2>
<sect2 id="includes">
<title id="includes.title">Inclusion of configuration files</title>
<para>
A configuration file may contain a special directive
called <literal>include</literal> to include other
file or a directory with files to the configuration
processing.
</para>
<para>
This allows to segment the specific configuration groups
required for several services and boxes to different files and
hence to have more control in larger setups.
</para>
<para>
Here is an example that illustrates the <literal>include</literal>
statement :
<programlisting>
# SMPPBox configuration
include = "/etc/smppbox/conf/smppbox1.conf"
</programlisting>
Above is the main <literal>smppbox.conf</literal> configuration
file that includes the following <literal>smppbox1.conf</literal>
file with all required directives for the specific box, and a
<literal>configurations</literal> directory which may include
more files to include.
<programlisting>
# smppbox1.conf
group = smppbox
bearerbox-host = 127.0.0.1
bearerbox-port = 13002
smppbox-id = Greek
smppbox-port = 13003
log-file = "/var/log/kannel/smppbox.log"
log-level = 1
our-system-id = Inaccess
route-to-smsc = cardboard
smpp-logins = /etc/smppbox/clients
</programlisting>
The above <literal>include</literal> statement may be defined
at any point in the configuration file and at any inclusion
depth. Hence you can cascade numerous inclusions if necessary.
It must be, however, between groups and must contain whole group
definitions.
</para>
<para>
At process start time inclusion of configuration files
breaks if either the included file can not be opened and
processed or the included file has been processed already in
the stack and a recursive loop has been detected.
</para>
</sect2>
<sect2>
<title>SMPPBox configuration</title>
<para>
SMPPBox configuration <emphasis>MUST</emphasis> always
include a group for general proxy configuration. This group is
named as 'smppbox' in configuration file, and should be the first
group in the configuration file.
</para>
<para>As its simplest form, 'smppbox' group looks like this:
<programlisting>
group = smppbox
our-system-id = Inaccess
smpp-logins = /etc/smppbox/clients
</programlisting>
Naturally this is not sufficient for any real use. Thus, one or
more of the optional configuration variables are used. In following
list (as in any other similar lists), all mandatory variables are
marked with <literal>(m)</literal>, while conditionally mandatory
(variables which must be set in certain cases) are marked with
<literal>(c)</literal>.
</para>
<table frame="none">
<title>smppbox Group Variables</title>
<tgroup cols="3">
<thead>
<row>
<entry>Variable</entry>
<entry>Value</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>group (m)</literal></entry>
<entry><literal>smppbox</literal></entry>
<entry valign="bottom">This is a mandatory variable</entry>
</row>
<row>
<entry><literal>bearerbox-host (o)</literal></entry>
<entry><literal>hostname</literal></entry>
<entry valign="bottom">
Bearerbox server. FQDN or IP address. Defaults to
localhost.
</entry>
</row>
<row>
<entry><literal>bearerbox-port (o)</literal></entry>
<entry><literal>port number</literal></entry>
<entry valign="bottom">
TCP port that bearerbox is listening for incoming
smppbox connections. Should be the same as smsbox-port
configured in bearerbox. Defaults to 13001.
</entry>
</row>
<row>
<entry><literal>smppbox-id (o)</literal></entry>
<entry><literal>string</literal></entry>
<entry valign="bottom">
Optional smoobox instance identifier. This is used to
identify an smppbox connected to a bearerbox for smppbox
specific routing inside bearerbox. So if you have several
boxes (smppbox, smsbox, sqlbox) that need delivery
verification (DLRs) you need to specify this for correct
DLR routing. Additionaly it is used for logging
identification.
</entry>
</row>
<row>
<entry><literal>smppbox-port (o)</literal></entry>
<entry><literal>port number</literal></entry>
<entry valign="bottom">
TCP port that smppbox is listening for incoming ESME
connections. Deafailts to 2345.
</entry>
</row>
<row>
<entry><literal>log-file (o)</literal></entry>
<entry><literal>filename</literal></entry>
<entry valign="bottom">
Filename that smppbox will log messages. If missing,
logging is disabled.
</entry>
</row>
<row>
<entry><literal>log-level (o)</literal></entry>
<entry><literal>integer (0...5)</literal></entry>
<entry valign="bottom">
Logging level. From maximum (0) to minimum (4).
Defaults to 0.
</entry>
</row>
<row>
<entry><literal>our-system-id (m)</literal></entry>
<entry><literal>string</literal></entry>
<entry valign="bottom">
Corresponds to SMSC identification transmitted to connected
ESMEs.
</entry>
</row>
<row>
<entry><literal>route-to-smsc (o)</literal></entry>
<entry><literal>string</literal></entry>
<entry valign="bottom">
Corresponds to smsc-id defined in bearerbox. If set, it
will send SMS through this SMSc, else it will let
bearerbox route the SMS. Defaults to bearerbox routing.
</entry>
</row>
<row>
<entry><literal>smpp-logins (m)</literal></entry>
<entry><literal>filename</literal></entry>
<entry valign="bottom">
File that contains authentication credentials for clients
connecting to smppbox. This should be a file with a single
line per client, with username, password and system-type,
seperated by spaces. System-type is same as defined in
kannel's configuration. Usually can get away with "VMA",
which stands for Voice Mail Activation, or "kannel".
</entry>
</row>
</tbody>
</table>
</sect2>
</sect1>
</chapter>
</book>
