Nokia WAP and SMS gateway User Manual
Kannel 1.3.1 User’s Guide
Open Source WAP and SMS gateway
Lars Wirzenius
Gateway architect
Wapit Ltd
liw@wapit.com
http://www.wapit.com
http://www.kannel.org
Kalle Marjola
Manager
Wapit Ltd
rpr@wapit.com
http://www.wapit.com
http://www.kannel.org
Andreas Fink
Chairman & CTO
Global Networks Inc.
andreas@fink.org
http://www.smsrelay.com
http://www.gni.ch
Bruno Rodrigues
bruno.rodrigues@litux.org
http://litux.org/bruno
Stipe Tolj
CTO & CIO
Wapme Systems AG
tolj@wapme-systems.de
http://www.wapme.de
http://www.kannel.org
Aarno Syvänen
Chief MMS Developer
Global Networks Inc.
as@gni.ch
http://www.gni.ch
Kannel 1.3.1 User’s Guide: Open Source WAP and SMS gateway
by Lars Wirzenius, Kalle Marjola, Andreas Fink, Bruno Rodrigues, Stipe Tolj, and Aarno Syvänen
Abstract
This document describes how to install and use Kannel, the Open Source WAP and SMS Gateway originally
developed by Wapit Ltd (now out of business) and now being developed further by the open source community,
namely the Kannel Group.
Revision History
Revision 1.3.1 2006.07.01
Table of Contents
1. Introduction............................................................................................................................................1
Overview of WAP ..............................................................................................................................1
Overview of WAP Push......................................................................................................................2
Overview of SMS...............................................................................................................................3
Features .............................................................................................................................................. 4
Requirements .....................................................................................................................................4
2. Installing the gateway............................................................................................................................5
Getting the source code ......................................................................................................................5
Finding the documentation.................................................................................................................5
Compiling the gateway.......................................................................................................................6
Installing the gateway.........................................................................................................................7
Using pre-compiled binary packages .................................................................................................7
Installing Kannel from RPM packages.....................................................................................7
Installing Kannel from DEB packages .....................................................................................9
3. Using the gateway ................................................................................................................................12
Configuring the gateway .................................................................................................................. 12
Configuration file syntax ........................................................................................................12
Inclusion of configuration files ...............................................................................................13
Core configuration ..................................................................................................................13
Running Kannel ...............................................................................................................................20
Starting the gateway ...............................................................................................................20
Command line options............................................................................................................20
Kannel statuses .......................................................................................................................21
HTTP administration ........................................................ ...................................................... 22
4. Setting up a WAP gateway .................................................................................................................. 24
WAP gateway configuration.............................................................................................................24
Wapbox configuration.............................................................................................................24
Running WAP gateway ....................................................................................................................26
Checking whether the WAP gateway is alive...................................................................................26
5. Setting up a SMS Gateway..................................................................................................................27
Required components.......................................................................................................................27
SMS gateway configuration .............................................................................................................27
SMS centers............................................................................................................................27
Nokia CIMD 1.37 and 2.0.............................................................................................30
CMG UCP/EMI 4.0 ......................................................................................................32
SMPP 3.4 ......................................................................................................................36
Sema Group SMS2000 OIS 4.0 and 5.0 .......................................................................40
SM/ASI (for CriticalPath InVoke SMS Center 4.x)......................................................41
GSM modem .................................................................................................................42
GSM modem 2..............................................................................................................44
Fake SMSC ...................................................................................................................47
HTTP-based relay and content gateways......................................................................48
Using multiple SMS centers .........................................................................................49
Feature checklist ...........................................................................................................49
iv
Smsbox configuration .............................................................................................................51
Smsbox routing inside bearerbox ...........................................................................................55
SMS-service configurations....................................................................................................56
How sms-service interprets the HTTP response.....................................................................62
Extended headers ..........................................................................................................63
Kannel POST ................................................................................................................64
XML Post......................................................................................................................64
SendSMS-user configurations ................................................................................................65
External delivery report (DLR) storage ..................................................................................67
Internal DLR storage.....................................................................................................68
MySQL DLR storage....................................................................................................68
LibSDB DLR storage....................................................................................................68
DLR database field configuration .................................................................................69
MySQL connection configuration ..........................................................................................70
Over-The-Air configurations ..................................................................................................71
Setting up more complex services..........................................................................................73
Redirected replies..........................................................................................................73
Setting up operator specific services.............................................................................74
Setting up multi-operator Kannel..................................................................................74
Running SMS gateway.....................................................................................................................75
Using the HTTP interface to send SMS messages .................................................................75
Using the HTTP interface to send OTA configuration messages ...........................................79
GET method for the OTA HTTP interface....................................................................79
6. Setting up a SMS&WAP gateway ......................................................................................................82
SMS&WAP gateway configuration..................................................................................................82
Running SMS&WAP gateway .........................................................................................................82
7. Setting up Push Proxy Gateway .........................................................................................................83
Configuring ppg core group, for push initiator (PI) interface ..........................................................83
Configuring PPG user group variables.............................................................................................84
Finishing ppg configuration .............................................................................................................86
Running a push proxy gateway........................................................................................................87
An example using HTTP SMSC......................................................................................................87
An example push (tokenised SI) document .....................................................................................87
Default network and bearer used by push proxy gateway................................................................87
8. Using SSL for HTTP............................................................................................................................89
Using SSL client support .................................................................................................................89
Using SSL server support for the administration HTTP interface...................................................89
Using SSL server support for the sendsms HTTP interface ............................................................89
Using SSL server support for PPG HTTPS interface ......................................................................90
9. Delivery Reports ..................................................................................................................................91
10. Getting help and reporting bugs....................................................................................................... 92
A. Using the fake WAP sender ................................................................................................................93
B. Using the fake SMS center .................................................................................................................94
Setting up fakesmsc..........................................................................................................................94
Compiling fakesmsc ...............................................................................................................94
Configuring Kannel ................................................................................................................94
v
Running Kannel with fakesmsc connections ................................................................................... 94
Starting fake SMS center........................................................................................................94
Fake messages...............................................................................................................95
Fakesmsc command line options ..................................................................................95
C. Setting up a test environment for Push Proxy Gateway..................................................................97
Creating push content and control document for testing .................................................................97
Starting necessary programs ............................................................................................................98
Using Nokia Toolkit as a part of a developing environment..........................................................100
Testing PAP protocol over HTTPS ................................................................................................100
D. Setting up a dial-up line....................................................................................................................103
Analog modem ...............................................................................................................................103
ISDN terminal ................................................................................................................................104
E. Log files ..............................................................................................................................................105
Bearerbox Access Log ...................................................................................................................105
Log rotation ....................................................................................................................................105
Glossary ..................................................................................................................................................107
Bibliography...........................................................................................................................................108
vi
List of Tables
3-1. Core Group Variables .........................................................................................................................14
3-2. Kannel Command Line Options.........................................................................................................20
3-3. Kannel HTTP Administration Commands .........................................................................................22
4-1. Wapbox Group Variables....................................................................................................................24
5-1. SMSC Group Variables ......................................................................................................................27
5-2. SMSC driver features .........................................................................................................................49
5-3. SMSC driver internal features ............................................................................................................50
5-4. Smsbox Group Variables ....................................................................................................................52
5-5. Smsbox-route Group Variables ..........................................................................................................55
5-6. SMS-Service Group Variables............................................................................................................56
5-7. Parameters (Escape Codes) ................................................................................................................61
5-8. X-Kannel Headers ..............................................................................................................................63
5-9. X-Kannel Post Headers ......................................................................................................................64
5-10. SendSMS-User Group Variables ......................................................................................................66
5-11. DLR Database Field Configuration Group Variables.......................................................................69
5-12. MySQL Connection Group Variables ..............................................................................................71
5-13. OTA Setting Group Variables ...........................................................................................................72
5-14. OTA Bookmark Group Variables .....................................................................................................73
5-15. SMS Push (send-sms) CGI Variables...............................................................................................75
5-16. OTA CGI Variables...........................................................................................................................80
7-1. PPG core group configuration variables.............................................................................................83
7-2. PPG user group configuration variables .............................................................................................85
B-1. Fakesmsc command line options .......................................................................................................95
C-1. Test_ppg’s command line options .....................................................................................................99
C-2. Test_ppg’s configuration file directives ...........................................................................................101
vii
Chapter 1. Introduction
This chapter introduces WAP and SMS in general terms, and explains the role of the gateway in WAP
and SMS, outlining their duties and features. It also explains why the Kannel project was started in the
first place, and why it is open source.
With hundreds of millions of mobile phones in use all over the world, the market for services targeted at
mobile users is mind-bogglingly immense. Even simple services find plenty of users, as long as they’re
useful or fun. Being able to get news, send e-mail or just be entertained wherever you are is extremely
attractive to many.
The hottest technology for implementing mobile services is WAP, short for Wireless Application
Protocol. It lets the phone act as a simple web browser, but optimizes the markup language, scripting
language, and the transmission protocols for wireless use. The optimized protocols are translated to plain
old HTTP by a WAP gateway.
Kannel is an open source WAP gateway. It attempts to provide this essential part of the WAP
infrastructure freely to everyone so that the market potential for WAP services, both from wireless
operators and specialized service providers, will be realized as efficiently as possible.
Kannel also works as an SMS gateway for GSM networks. Almost all GSM phones can send and receive
SMS messages, so this is a way to serve many more clients than just those using a new WAP phone.
In addition, Kannel operates as Push Proxy Gateway , or PPG, making possible for content servers to
send data to the phones. This is a new type of WAP service, and have many interesting applications.
Usually servers know whether some data is new, not the users.
Open Source (http://www.opensource.org) is a way to formalize the principle of openness by placing the
source code of a product under a Open Source compliant software license. The BSD license was chosen
over other Open Source licenses by the merit of placing the least amount of limitations on what a third
party is able to do with the source code. In practice this means that Kannel is going to be a fully-featured
WAP implementation and compatible with the maximum number of bearers with special emphasis on
SMSC compatibility. The Kannel project was founded by Wapit Ltd in June, 1999.
Overview of WAP
WAP, short for Wireless Application Protocol, is a collection of various languages and tools and an
infrastructure for implementing services for mobile phones. Traditionally such services have worked via
normal phone calls or short textual messages (e.g., SMS messages in GSM networks). Neither are very
efficient to use, nor very user friendly. WAP makes it possible to implement services similar to the World
Wide Web.
Unlike marketers claim, WAP does not bring the existing content of the Internet directly to the phone.
There are too many technical and other problems for this to ever work properly. The main problem is that
Internet content is mainly in the form of HTML pages, and they are written in such way that they require
fast connections, fast processors, large memories, big screens, audio output and often also fairly efficient
input mechanisms. That’s OK, since they hopefully work better for traditional computers and networks
that way. However, portable phones have very slow processors, very little memory, abysmal and
1
Chapter 1. Introduction
intermittent bandwidth, and extremely awkward input mechanisms. Most existing HTML pages do not
work on mobiles phones, and never will.
WAP defines a completely new markup language, the Wireless Markup Language (WML), which is
simpler and much more strictly defined than HTML. It also defines a scripting language, WMLScript,
which all browsers are required to support. To make things even simpler for the phones, it even defines
its own bitmap format (Wireless Bitmap, or WBMP).
HTTP is also too inefficient for wireless use. However, by using a semantically similar binary and
compressed format it is possible to reduce the protocol overhead to a few bytes per request, instead of the
usual hundreds of bytes. Thus, WAP defines a new protocol stack to be used. However, to make things
simpler also for the people actually implementing the services, WAP introduces a gateway between the
phones and the servers providing content to the phones.
Figure 1-1. Logical position of WAP gateway (and PPG)between a phone and a content server.
The WAP gateway talks to the phone using the WAP protocol stack, and translates the requests it receives
to normal HTTP. Thus content providers can use any HTTP servers and utilize existing know-how about
HTTP service implementation and administration.
In addition to protocol translations, the gateway also compresses the WML pages into a more compact
form, to save on-the-air bandwidth and to further reduce the phone’s processing requirements. It also
compiles WMLScript programs into a bytecode format.
Kannel is not just a WAP gateway. It also works as an SMS gateway. Although WAP is the hot and
technically superior technology, SMS phones exist in huge numbers and SMS services are thus quite
useful. Therefore, Kannel functions simultaneously as both a WAP and an SMS gateway.
Overview of WAP Push
Previous chapter explained pull mode of operation: the phone iniatiates the transaction. There is,
however, situations when the server (called in this context a push initiator) should be the initiator, for
2
instance, when it must send a mail notification or a stock quote. For this purpose Wapforum defined
WAP Push.
Push is an application level service, sitting on the top of existing WAP stack. It defines two protocols,
OTA and PAP. OTA is a ligthweigth protocol speaking with WAP stack (to be more specific, with WSP),
PAP speaks with the push initiator. It defines three kind of XML documents, one for the push data itself
and another for protocol purposes (these are called pap document or push control documents).
The server does not simply send push content to the phone, the user would surely not accept, for
instance, interrupting of a voice call. Instead it sends a specific XML document, either Service Indication
or Service Loading. These inform the user about the content becomed available, and it is displayed only
when it is not interrupting anything. It contains an URL specifying the service and a text for user
describing the content. Then the user can decide does he accept push or not.
The push content is sended to the phones over SMS, but the content is fetched by the phone over IP
bearer, for instance CSD or GPRS. Because Push Proxy Gateway tokenises SI and SL documents, it may
fit one SMS message (if not, it is segmented for transfer).
Using two bearers seems to be an unnecessary complication. But quite simply, phones currently operate
this way. Push over GPRS can only simplify matters.
Overview of SMS
Chapter 1. Introduction
SMS, short messaging service, is a way to send short (160 character) messages from one GSM phone to
another. It can also be used to send operator logos, ringing tones, business cards and phone
configurations.
SMS services are content services initiated by SMS message to certain (usually short) phone number,
which then answers with requested content, if available.
When SMS services are used, the client (mobile terminal) sends an SMS message to certain number,
usually a very short specialized number, which points to specific SMS center responsible for that number
(plus possibly many others). This SMS center then sends the message onward to specified receiver in
intra- or Internet, using an SMS center specific protocol. For example, a Nokia SMS center uses CIMD
protocol.
As practically every different kind of SMS center uses different protocol, an SMS gateway is used to
handle connections with SMS centers and to relay them onward in an unified form.
3
Chapter 1. Introduction
Figure 1-2. Logical position of SMS gateway between a phone and a content server.
An SMS gateway can also be used to relay SMS messages from one GSM network to another, if the
networks do not roam messages normally.
Kannel works as an SMS gateway, talking with many different kind of SMS centers, and relaying the
messages onward to content providers, as HTTP queries. Content providers then answer to this HTTP
query and the answer is sent back to mobile terminal, with appropriate SMS center connection using
SMS center specific protocol.
In addition to serving mobile originated (MO) SMS messages Kannel also works as an SMS push
gateway - content providers can request Kannel to send SMS messages to terminals. Kannel then
determines the correct SMS center to relay the SMS message and sends the SMS message to that SMS
center, again using SMS center specific protocol. This way the content provider does not need to know
any SMS center specific protocol, just unified Kannel SMS sending interface.
Features
This section needs to be written.
Requirements
Kannel is being developed on Linux systems, and should be fairly easy to export to other Unix-like
systems. However, we don’t yet support other platforms, due to lack of time. Kannel requires the
following software environment:
• C compiler, development libraries and related tools.
4
Chapter 1. Introduction
• The Gnome XML library (known as gnome-xml and libxml), version 2.2.5 or newer. See
http://xmlsoft.org/xml.html.
• GNU Make.
• Posix threads (pthread.h).
• GNU Bison 1.28 if you modify the WMLScript compiler.
• DocBook markup language tools (jade, jadetex, DocBook stylesheets, etc; see README.docbook), if
you want to format the documentation (pre-formatted versions are available).
Hardware requirements are fluffier. We haven’t benchmarked Kannel yet, so there are no hard numbers,
but a reasonably fast PC workstation (400 MHz Pentium II, 128 MB RAM) should serve several
concurrent users or tens of SMS messages per second without problems.
5
Chapter 2. Installing the gateway
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.
Getting the source code
The source code to Kannel is available for download at http://www.kannel.3glab.org/download.shtml. It
is available in various formats and you can choose to download either the latest release version or the
daily snapshot of the development source tree for the next release version, depending on whether you
want to use Kannel for production use or to participate in the development.
If you’re serious about development, you probably want to use CVS, the version control system used by
the Kannel project. This allows you to participate in Kannel development much more easily than by
downloading the current daily snapshot and integrating any changes you’ve made every day. CVS does
that for you. (See the Kannel web site for more information on how to use CVS.)
Finding the documentation
The documentation for Kannel consists of three parts:
1. User’s Guide, i.e., the one you’re reading at the moment.
2. Architecture and Design, in doc/arch or at http://www.kannel.3glab.org/arch.shtml
(http://www.kannel.3glab.org/arch.shtml)
3. The README and various other text files in the source tree.
We intend to cover everything you need to install and use Kannel is in User’s Guide, but the guide is still
incomplete in this respect. Similarly, the Architecture and Design document should tell you everything
you need to know to dive into the sources and quickly make your own modifications. It’s not a
replacement for actually reading the source code, but it should work as a map to the source code. The
README is not supposed to be very important, nor contain much information. Instead, it will just point at
the other documentation.
You need the following tools to compile Kannel:
• C compiler and libraries for ANSI C, with normal Unix extensions such as BSD sockets.
• An implementation of POSIX threads (pthread.h).
• GNU Bison 1.28, if you want to modify the WMLScript compiler (a pre-generated parser is included
for those who just want to compile Kannel).
• DocBook processing tools: DocBook stylesheets, jade, jadetex, etc; see README.docbook for more
information (pre-formatted versions of the documentation are available, and you can compile Kannel
itself even without the documentation tools).
6
• GNU autoconf, if you want to modify the configuration script.
Compiling the gateway
If you are using Kannel on a supported platform, or one that is similar enough to one, compiling Kannel
is trivial. After you have unpacked the source package of your choosing, or after you have checked out
the source code from CVS, enter the following commands:
./configure
make
The configure script investigates various things on your computer for the Kannel compilation needs,
and writes out the Makefile used to compile Kannel. make then runs the commands to actually
compile Kannel.
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 Chapter
10
for details.
Chapter 2. Installing the gateway
For detailed instruction on using the configuration script, see file INSTALL. That file is a generic
documentation for configure. Kannel defines a few additional options:
• --with-defaults=type Set defaults for the other options. type is either speed or debug. The
default is debug.
• --enable-docs (default) Build documentation, b.e., converting the User Guide and the
Architecture Guide from the DocBook markup language to PostScript and HTML.
• --disable-docs Don’t build documentation.
• --enable-drafts When building documentation, include the sections marked as draft.
• --disable-drafts (default) When building documentation, don’t include the sections marked
as draft.
• --enable-debug Enable non-reentrant development time debugging of WMLScript compiler.
• --enable-localtime Write log file time stamps in local time, not GMT.
• --disable-assertions Turn off runtime assertion checking. This makes Kannel faster, but gives
less information if it crashes.
• --with-malloc=type Select memory allocation module to use: type is native, checking (the
default), or slow. For production use you probably want native. The slow module is more thorough
than checking, but much slower.
• --enable-mutex-stats Produce information about lock contention.
• --enable-start-stop-daemon Compile the start-stop-daemon program.
• --enable-pam Enable using PAM for authentication of sendsms users for smsbox.
7
You may need to add compilations flags to configure:
CFLAGS=’-pthread’ ./configure
The above, for instance, seems to be required on FreeBSD. If you want to develop Kannel, you probably
want to add CFLAGS that make your compiler use warning messages. For example, for GCC:
CFLAGS=’-Wall -O2 -g’ ./configure
(You may, at your preference, use even stricter checking options.)
Installing the gateway
After you have compiled Kannel, you need to install certain programs in a suitable place. This is most
easily done by using make again:
make bindir=/path/to/directory install
Chapter 2. Installing the gateway
Replace /path/to/directory with the pathname of the actual directory where the programs should
be installed. The programs that are installed are (as filenames from the root of the source directory):
gw/bearerbox
gw/smsbox
gw/wapbox
The version number of the gateway is added to the file names 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.
Kannel consists of three programs called boxes: the bearer box is the interface towards the phones. It
accepts WAP and SMS messages from the phones and sends them to the other boxes. The SMS box
handles SMS gateway functionality, and the WAP box handles WAP gateway functionality. There can be
several SMS boxes and several WAP boxes running and they don’t have to run on the same host. This
makes it possible to handle much larger loads.
Using pre-compiled binary packages
Installing Kannel from RPM packages
This chapter explains how to install, upgrade and remove Kannel binary RPM packages.
Before you install Kannel, check that you have libxml2 installed on your system:
rpm -q libxml2
8
Installing Kannel
1. Download the binary RPM packet from the Kannel web site.
2. Log in as root:
su -
3. Install the RPM package:
rpm -ivh kannel-VERSION.i386.rpm
Upgrading Kannel
1. Download the binary RPM packet from the Kannel web site.
2. Log in as root
3. Upgrade the RPM package:
rpm -Uvh kannel-VERSION.i386.rpm
Chapter 2. Installing the gateway
Removing Kannel
1. Log in as root:
2. Remove the RPM package:
rpm -e kannel
After you have installed Kannel from the RPM packages you x should now be able to run the Kannel
init.d script that will start Kannel as a WAP gateway. Run the script as root.
/etc/rc.d/init.d/kannel start
To stop the gateway just run the same script with the stop parameter.
/etc/rc.d/init.d/kannel stop
If Kannel 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.
/etc/rc.d/init.d/kannel restart
If you want Kannel to run as a daemon, you need to add a symbolic link to the Kannel script from the
runlevel you want Kannel to run in. E.g. to run Kannel in runlevel 5 add symbolic links to /etc/rc.d/rc5.d/.
9
Chapter 2. Installing the gateway
cd /etc/rc.d/rc5.d/
ln -s ../init.d/kannel S91kannel
ln -s ../init.d/kannel K91kannel
To run Kannel as a SMS gateway you need to edit the configuration file which is at
/etc/kannel/kannel.conf. In the same directory there is an example file called smskannel.conf. It has some
basic examples of the configuration groups needed to run Kannel as a SMS gateway. For more detailed
information please read the section "SMS gateway configuration" later in this same document.
The logging is disabled by default and you can enable it from the kannel.conf file. Just add the log-file
option to the group of which box you want to log.
The documentation will be installed at /usr/share/doc/kannel-VERSION/ or /usr/doc/kannel-VERSION/
depending on if you used the RedHat 7.x or 6.x package.
In the Kannel documentation directory there is a html file called control.html. It is an example file that
shows how to use the Kannel http administration interface. It also has a template for sending SMS
messages.
Installing Kannel from DEB packages
This chapter explains how to install, upgrade and remove Kannel binary DEB packages.
Before you install Kannel, check that you have libxml2 installed on your system:
dpkg -l libxml2
Installing or upgrading Kannel using APT
1. Log in as root:
su -
3. Install or upgrade the package:
apt-get install kannel
See http://kannel.org/download.shtml#debian_repository for informations about kannel repository
sources.list
Installing or upgrading Kannel from a file
1. Download the binary DEB packet from the Kannel web site.
2. Log in as root:
su -
10
Chapter 2. Installing the gateway
3. Install or upgrade the DEB package:
dpkg -i kannel-VERSION .deb
Removing Kannel
1. Log in as root:
2. Remove the package keeping configuration files:
dpkg --remove kannel
3. Remove the package completely:
dpkg --purge kannel
After you have installed Kannel from the DEB packages you should now be able to run the Kannel init.d
script that will start Kannel as a WAP gateway. Run the script as root.
/etc/init.d/kannel start
To stop the gateway just run the same script with the stop parameter.
/etc/init.d/kannel stop
If Kannel 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.
/etc/init.d/kannel restart
If you don’t want Kannel to run as a daemon, run:
update-rc.d -f kannel remove
If you want to restore Kannel runing as a daemon, you need to add a symbolic link to the Kannel script
from the runlevel you want Kannel to run in. E.g. to run Kannel in default runlevel, just run:
update-rc.d kannel defaults
Kannel package starts by default with a wapbox daemon. To activate smsbox or select which box you
want to start, edit /etc/default/kannel and comment/uncomment START_xxxBOX.
To run Kannel as a SMS gateway you need to edit the configuration file which is at
/etc/kannel/kannel.conf. In /usr/share/docs/kannel/examples/ there are example files. They have some
basic examples of the configuration groups needed to run Kannel as a SMS gateway. For more detailed
information please read the section "SMS gateway configuration" later in this same document.
11
Chapter 2. Installing the gateway
The documentation will be installed at /usr/share/doc/kannel/.
In the Kannel documentation directory there is a html file called control.html. It is an example file that
shows how to use the Kannel http administration interface. It also has a template for sending SMS
messages.
Aditionally to kannel-VERSION.deb, there’s now an optional kannel-docs-VERSION.deb with
documentation (userguide et al) and a kannel-extras-VERSION.deb with contrib and test stuff.
If you want to test development version, use the packages called kannel-devel-*.deb.
12
Chapter 3. Using the gateway
This chapter explains how the gateway core, bearerbox, is configured and used. It covers the
configuration file, keeping an eye on the gateway while it is running, and using the HTTP interface to
control the gateway.
After this chapter there is distinct chapter for each kind of gateway use: WAP gateway, SMS gateway and
combined gateway. These chapters explain the configuration and other aspects of gateway of that type.
There is only one configuration file for all parts of Kannel, although when Kannel is distributed to
several hosts some lines from the configuration file can be removed in some hosts.
Configuring the gateway
The configuration file can be divided into three parts: bearerbox configurations, smsbox configurations
and wapbox configurations. Bearerbox part has one ’core’ group and any used SMS center groups, while
wapbox part has only one wapbox group. In smsbox part there is one smsbox group and then number of
sms-service and sendsms-user groups.
Details of each part are in an appropriate section of this documentation. The ’core’ group used by the
bearerbox is explained in this chapter, while ’wapbox’ part is in the next chapter and ’smsbox’, ’smsc’
(SMS center), ’sms-service’ and ’sendsms-user’ groups are in the SMS Kannel chapter.
Configuration file syntax
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 (#) and are ignored (they don’t, for
example, separate groups of variables).
A variable definition line has the name of the variable, and equals sign (=) and the value of the variable.
The name of the variable can contain any characters except whitespace and equals. The value of the
variable is a string, with or without quotation marks () around it. Quotation marks are needed if the
variable needs to begin or end with whitespace or contain special characters. Normal C escape character
syntax works inside quotation marks.
Perhaps an example will make things easier to comprehend:
1 # A do-nothing service.
2 group = sms-service
3 keyword = nop
4 text = "You asked nothing and I did it!"
5
6 # Default service.
7 group = sms-service
8 keyword = default
9 text = "No services defined"
The above snippet defines the keyword nop for an SMS service, and a default action for situation when
the keyword in the SMS message does not match any defined service.
13
Chapter 3. Using the gateway
Lines 1 and 6 are comment lines. Line 5 separates the two groups. The remaining lines define variables.
The group type is defined by the group variable value.
The various variables that are understood in each type of configuration group are explained below.
Some variable values are marked as ’bool’. The value for variable can be like true, false, yes, no, on,
off, 0 or 1. Other values are treated as ’true’ while if the variable is not present at all, it is treated as being
’false’.
Inclusion of configuration files
A configuration file may contain a special directive called include to include other file or a directory
with files to the configuration processing.
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.
Here is an example that illustrates the include statement :
group = core
admin-port = 13000
wapbox-port = 13002
admin-password = bar
wdp-interface-name = "*"
log-file = "/var/log/bearerbox.log"
log-level = 1
box-deny-ip = "*.*.*.*"
box-allow-ip = "127.0.0.1"
include = "wapbox.conf"
include = "configurations"
Above is the main kannel.conf configuration file that includes the following wapbox.conf file with
all required directives for the specific box, and a configurations directory which may include more
files to include.
group = wapbox
bearerbox-host = localhost
log-file = "/var/log/wapbox.log"
log-level = 0
syslog-level = none
The above include statement may be defined at any point in the configuration file and at any inclusion
depth. Hence you can cascade numerous inclusions if necessary.
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 cycling has
been detected.
14
Chapter 3. Using the gateway
Core configuration
Configuration for Kannel MUST always include a group for general bearerbox configuration. This group
is named as ’core’ in configuration file, and should be the first group in the configuration file.
As its simplest form, ’core’ group looks like this:
group = core
admin-port = 13000
admin-password = f00bar
Naturally this is not sufficient for any real use, as you want to use Kannel as an SMS gateway, or WAP
gateway, or both. 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 (m), while conditionally mandatory
(variables which must be set in certain cases) are marked with (c).
Table 3-1. Core Group Variables
Variable Value Description
group (m) core This is a mandatory variable
The port number in which the
bearerbox listens to HTTP
administration commands. It is
NOT the same as the HTTP port
of the local www server, just
invent any port, but it must be
over 1023 unless you are running
Kannel as a root process (not
admin-port (m) port-number
admin-port-ssl (o) bool
admin-password (m) string
status-password string
recommended)
If set to true a SSL-enabled
administration HTTP server will
be used instead of the default
unsecure plain HTTP server. To
access the administration pacges
you will have to use a HTTP
client that is capable of talking to
such a server. Use the "https://"
scheme to access the secured
HTTP server. Defaults to "no".
Password for HTTP
administration commands (see
below)
Password to request Kannel
status. If not set, no password is
required, and if set, either this or
admin-password can be used
15
Chapter 3. Using the gateway
Variable Value Description
These lists can be used to
prevent connection from given IP
addresses. Each list can have
admin-deny-ip IP-list
several addresses, separated with
semicolons (’;’). An asterisk
admin-allow-ip
(’*’) can be used as a wildcard in
a place of any ONE number, so
*.*.*.* matches any IP.
This is the port number to which
the smsboxes, if any, connect. As
with admin-port, this can be
anything you want. Must be set if
you want to handle any SMS
smsbox-port (c) port-number
traffic.
If set to true, the smsbox
connection module will be
SSL-enabled. Your smsboxes
will have to connect using SSL
to the bearerbox then. This is
used to secure communication
between bearerbox and smsboxes
in case they are in seperate
networks operated and the TCP
communication is not secured on
a lower network layer. Defaults
smsbox-port-ssl (o) bool
to "no".
Like smsbox-port, but for
wapbox-connections. If not set,
Kannel cannot handle WAP
wapbox-port (c) port-number
traffic
If set to true, the wapbox
connection module will be
SSL-enabled. Your wapboxes
will have to connect using SSL
to the bearerbox then. This is
used to secure communication
between bearerbox and
wapboxes in case they are in
seperate networks operated and
the TCP communication is not
secured on a lower network
wapbox-port-ssl (o) bool
layer. Defaults to "no".
16
Chapter 3. Using the gateway
Variable Value Description
These lists can be used to
prevent box connections from
given IP addresses. Each list can
box-deny-ip IP-list
have several addresses, separated
with semicolons (’;’). An asterisk
box-allow-ip
(’*’) can be used as a wildcard in
place of any ONE number, so
*.*.*.* matches any IP.
These lists can be used to
prevent UDP packets from given
IP addresses, thus preventing
udp-deny-ip IP-list
unwanted use of the WAP
gateway. Used the same way as
udp-allow-ip
box-deny-ip and
box-allow-ip.
If this is set, Kannel listens to
WAP UDP packets incoming to
ports 9200-9208, bound to given
IP. If no specific IP is needed, use
just an asterisk (’*’). If UDP
messages are listened to,
wapbox-port variable MUST be
wdp-interface-name (c) IP or ’*’
set.
A file in which to write a log.
This in addition to stdout and
any log file defined in command
line. Log-file in ’core’ group is
log-file filename
only used by the bearerbox.
Minimum level of logfile events
logged. 0 is for ’debug’, 1 ’info’,
2 ’warning, 3 ’error’ and 4
’panic’ (see Command Line
log-level number 0..5
Options)
A file in which information
about received/sent SMS
messages is stored. Access-log in
’core’ group is only used by the
access-log filename
bearerbox.
17
Chapter 3. Using the gateway
Variable Value Description
String to unify received phone
numbers, for SMSC routing and
to ensure that SMS centers can
handle them properly. This is
applied to ’sender’ number when
receiving SMS messages from
SMS Center and for ’receiver’
number when receiving messages
from SMSbox (either sendsms
message or reply to original
message). Format is that first
comes the unified prefix, then all
prefixes which are replaced by
the unified prefix, separated with
comma (’,’). For example, for
Finland an unified-prefix
"+358,00358,0;+,00" should do
the trick. If there are several
unified prefixes, separate their
rules with semicolon (’;’), like
"+35850,050;+35840,040". Note
that prefix routing is next to
useless now that there are SMSC
ID entries. To remove prefixes,
use like
unified-prefix prefix-list
"-,+35850,050;-,+35840,040".
Load a list of accepted senders
of SMS messages. If a sender of
an SMS message is not in this
list, any message received from
the SMS Center is discarded. See
notes of phone number format
from numhash.h header file.
NOTE: the system has only a
precision of last 9 or 18 digits of
white-list URL
phone numbers, so beware!
As white-list, but SMS messages
to these numbers are
black-list URL
automatically discarded
18
Chapter 3. Using the gateway
Variable Value Description
A file in which any received
SMS messages are stored until
they are successfully handled. By
using this variable, no SMS
messages are lost in Kannel, but
theoretically some messages can
duplicate when system is taken
store-file filename
down violently.
Enable the use of an HTTP
http-proxy-host hostname
http-proxy-port port-number
proxy for all HTTP requests.
A list of excluded hosts from
being used via a proxy. Separate
http-proxy-exceptions URL-list
each entry with space.
Username for authenticating
proxy use, for proxies that
http-proxy-username username
require this.
Password for authenticating
proxy use, for proxies that
http-proxy-password URL-list
require this.
A PEM encoded SSL certificate
and private key file to be used
with SSL client connections.
This certificate is used for the
HTTPS client side only, i.e. for
SMS service requests to
ssl-client-certkey-file
(c)
filename
SSL-enabed HTTP servers.
A PEM encoded SSL certificate
file to be used with SSL server
connections. This certificate is
used for the HTTPS server side
only, i.e. for the administration
HTTP server and the HTTP
interface to send SMS messages.
ssl-server-cert-file (c) filename
A PEM encoded SSL private
key file to be used with SSL
server connections. This key is
associated to the specified
certificate and is used for the
ssl-server-key-file (c) filename
HTTPS server side only.
19
Chapter 3. Using the gateway
Variable Value Description
This file contains the certificates
Kannel is willing to trust when
working as a HTTPS client. If
this option is not set, certificates
are not validated and those the
identity of the server is not
ssl-trusted-ca-file filename
proven.
Defines the way DLRs are
stored. If you have build-in
external DLR storage support,
i.e. using MySQL you may
define here the alternative storage
type like ’mysql’. Supported
types are: internal, mysql. By
dlr-storage type
default this is set to ’internal’.
Set maximum size of incoming
message queue. After number of
messages has hit this value,
Kannel began to discard them.
Value 0 means giving strict
priority to outgoing messages.
-1, default, means that the queue
of infinite length is accepted.
(This works with any normal
input, use this variable only
when Kannel message queues
maximum-queue-length number of messages
grow very long).
A sample more complex ’core’ group could be something like this:
group = core
admin-port = 13000
admin-password = f00bar
status-password = sTat
admin-deny-ip = "*.*.*.*"
admin-allow-ip = "127.0.0.1;200.100.0.*"
smsbox-port = 13003
wapbox-port = 13004
box-deny-ip = "*.*.*.*"
box-allow-ip = "127.0.0.1;200.100.0.*"
wdp-interface-name = "*"
log-file = "kannel.log"
log-level = 1
access-log = "kannel.access"
unified-prefix = "+358,00358,0;+,00"
white-list = "http://localhost/whitelist.txt"
20
Running Kannel
To start the gateway, you need to start each box you need. You always need the bearer box, and
depending on whether you want WAP and SMS gateways you need to start the WAP and SMS boxes. If
you want, you can run several of them, but we’ll explain the simple case of only running one each.
Starting the gateway
After you have compiled Kannel and edited configuration file for your taste, you can either run Kannel
from command line or use supplied start-stop-daemon and run_kannel_box programs to use it as
a daemon service (more documentation about that later).
If you cannot or do not know how to set up daemon systems or just want to test Kannel, you probably
want to start it from command line. This means that you probably want to have one terminal window for
each box you want to start (xterm or screen will do fine). To start the bearerbox, give the following
command:
./bearerbox -v 1 [conffile]
The -v 1 sets the logging level to INFO. This way, you won’t see a large amount of debugging output
(the default is DEBUG). Full explanation of Kannel command line arguments is below.
Chapter 3. Using the gateway
[conffile] is the name of the configuration file you are using with Kannel. The basic distribution packet
comes with two sample configuration files, smskannel.conf and wapkannel.conf (in gw
subdirectory), of which the first one is for testing out SMS Kannel and the second one for setting up a
WAP Kannel. Feel free to edit those configuration files to set up your own specialized system.
After the bearer box, you can start the WAP box:
./wapbox -v 1 [conffile]
or the SMS box:
./smsbox -v 1 [conffile]
or both, of course. The order does not matter, except that you need to start the bearer box before the other
boxes. Without the bearer box, the other boxes won’t even start.
Command line options
Bearerbox, smsbox and wapbox each accept certain command line options and arguments when they are
launched. These arguments are:
Table 3-2. Kannel Command Line Options
-v <level>
Set verbosity level for stdout (screen) logging.
Default is 0, which means ’debug’. 1 is ’info, 2
’warning’, 3 ’error’ and 4 ’panic’
21
--verbosity <level>
-D <places>
--debug <places>
-F <file-name>
--logfile <file-name>
-V <level>
--fileverbosity <level>
-S
--suspended
-I
--isolated
Chapter 3. Using the gateway
Set debug-places for ’debug’ level output.
Log to file named file-name, too. Does not overrun
or affect any logfile defined in configuration file.
Set verbosity level for that extra logfile (default 0,
which means ’debug’). Does not affect verbosity
level of the logfile defined in configuration file, not
verbosity level of the stdout output.
Start the system initially at SUSPENDED state
(see below, bearerbox only)
Start the system initially at ISOLATED state (see
below, bearerbox only)
Only try to open HTTP sendsms interface; if it
-H
--tryhttp
fails, only warn about that, do not exit. (smsbox
only)
Kannel statuses
In Kannel, there are four states for the program (which currently directly only apply to bearerbox):
a. Running. The gateway accepts, proceeds and relies messages normally. This is the default state for
the bearerbox.
b. Suspended. The gateway does not accept any new messages from SMS centers nor from UDP ports.
Neither does it accept new sms and wapbox connections nor sends any messages already in the
system onward.
c. Isolated. In this state, the gateway does not accept any messages from external message providers,
which means SMS Centers and UDP ports. It still processes any messages in the system and can
accept new messages from sendsms interface in smsbox.
d. Full. Gateway does not accept any messages from SMS centers, because maximum-queue-length
is achieved.
e. Shutdown. When the gateway is brought down, it does not accept any new messages from SMS
centers and UDP ports, but processes all systems already in the system. As soon as any queues are
emptied, the system exits
22
Chapter 3. Using the gateway
The state can be changed via HTTP administration interface (see below), and shutdown can also be
initiated via TERM or INT signal from terminal. In addition, the bearerbox can be started already in
suspended or isolated state with -S or -I command line option, see above.
HTTP administration
Kannel can be controlled via an HTTP administration interface. All commands are done as normal HTTP
queries, so they can be easily done from command line like this:
lynx -dump "http://localhost:12345/shutdown?password=bar"
...in which the ’12345’ is the configured admin-port in Kannel configuration file (see above). For most
commands, admin-password is required as a argument as shown above. In addition, HTTP administration
can be denied from certain IP addresses, as explained in configuration chapter.
Note that you can use these commands with WAP terminal, too, but if you use it through the same
Kannel, replies to various suspend commands never arrive nor can you restart it via WAP anymore.
Table 3-3. Kannel HTTP Administration Commands
Get the current status of the gateway in a text
version. Tells the current state (see above) and
total number of messages relied and queueing in
the system right now. Also lists the total number of
smsbox and wapbox connections. No password
required, unless status-password set, in which
case either that or main admin password must be
status or status.txt
status.html HTML version of status
status.xml XML version of status
status.wml WML version of status
supplied.
Get the current content of the store queue of the
gateway in a text version. No password required,
unless status-password set, in which case
either that or main admin password must be
store-status or store-status.txt
store-status.html HTML version of store-status
store-status.xml XML version of store-status
supplied.
Set Kannel state as ’suspended’ (see above).
suspend
Password required.
Set Kannel state as ’isolated’ (see above).
isolate
Password required.
Set Kannel state as ’running’ if it is suspended or
resume
isolated. Password required.
23
Loading...