Nokia Network Card 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

[email protected]

http://www.wapit.com

http://www.kannel.org

Kalle Marjola

Manager

Wapit Ltd

[email protected]

http://www.wapit.com

http://www.kannel.org

Andreas Fink

Chairman & CTO

Global Networks Inc.

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 W A P ..............................................................................................................................1

Overview of W A P 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 package s.................................................................................................7

Installing Kannel from RPM packages.....................................................................................7

Installing Kannel from DEB package s.....................................................................................9

3. Using the gateway ................................................................................................................................12

Conﬁguring the gateway ..................................................................................................................12

Conﬁguration ﬁle syntax ........................................................................................................12

Inclusion of conﬁguration ﬁle s...............................................................................................13

Core conﬁguratio n..................................................................................................................13

Running Kannel ...............................................................................................................................20

Starting the gateway ...............................................................................................................20

Command line options............................................................................................................20

Kannel statuses .......................................................................................................................21

HTTP administratio n..............................................................................................................22

4. Setting up a W A P gatewa y..................................................................................................................24

W A P gateway conﬁguration.............................................................................................................24

Wapbox conﬁguration.............................................................................................................24

Running W A P gateway ....................................................................................................................26

Checking whether the W A P gateway is alive...................................................................................26

5. Setting up a SMS Gateway..................................................................................................................27

Required components.......................................................................................................................27

SMS gateway conﬁguration .............................................................................................................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 In V o ke 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

Smsbox conﬁguratio n.............................................................................................................51

Smsbox routing inside bearerbox ...........................................................................................55

SMS-service conﬁgurations....................................................................................................56

How sms-service interprets the HTTP response.....................................................................62

Extended headers ..........................................................................................................63

Kannel POST ................................................................................................................64

XML Post......................................................................................................................64

SendSMS-user conﬁgurations ................................................................................................65

External delivery report (DLR) storage..................................................................................67

Internal DLR storage.....................................................................................................68

MySQL DLR storage....................................................................................................68

LibSDB DLR storage....................................................................................................68

DLR database ﬁeld conﬁguration .................................................................................69

MySQL connection conﬁguration ..........................................................................................70

Over-The-Air conﬁgurations ..................................................................................................71

Setting up more complex service s..........................................................................................73

Redirected replies..........................................................................................................73

Setting up operator speciﬁc 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 conﬁguration messages ...........................................79

GET method for the OTA HTTP interface....................................................................79

6. Setting up a SMS&W A P gateway ......................................................................................................82

SMS&W A P gateway conﬁguration..................................................................................................82

Running SMS&W A P gateway .........................................................................................................82

7. Setting up Push Proxy Gateway .........................................................................................................83

Conﬁguring ppg core group, for push initiator (PI) interfac e..........................................................83

Conﬁguring PPG user group variables.............................................................................................84

Finishing ppg conﬁguration .............................................................................................................86

Running a push proxy gatewa y........................................................................................................87

An example using HTTP SMS C......................................................................................................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 interfac e...................................................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 W A P sender................................................................................................................93

B. Using the fake SMS center .................................................................................................................94

Setting up fakesmsc..........................................................................................................................94

Compiling fakesmsc ...............................................................................................................94

Conﬁguring Kannel ................................................................................................................94

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 mode m...............................................................................................................................103

ISDN termina l................................................................................................................................104

E. Log ﬁles ..............................................................................................................................................105

Bearerbox Access Log ...................................................................................................................105

Log rotation....................................................................................................................................105

Glossary ..................................................................................................................................................107

Bibliograph y...........................................................................................................................................108

List of Tables

3-1. Core Group V a riable s.........................................................................................................................14

3-2. Kannel Command Line Options.........................................................................................................20

3-3. Kannel HTTP Administration Command s.........................................................................................22

4-1. Wapbox Group V a riables....................................................................................................................24

5-1. SMSC Group V a riables ......................................................................................................................27

5-2. SMSC driver features .........................................................................................................................49

5-3. SMSC driver internal feature s............................................................................................................50

5-4. Smsbox Group V a riable s....................................................................................................................52

5-5. Smsbox-route Group V a riables ..........................................................................................................55

5-6. SMS-Service Group V a riables............................................................................................................56

5-7. Parameters (Escape Codes) ................................................................................................................61

5-8. X-Kannel Header s..............................................................................................................................63

5-9. X-Kannel Post Headers ......................................................................................................................64

5-10. SendSMS-User Group V a riable s......................................................................................................66

5-11. DLR Database Field Conﬁguration Group V a riables.......................................................................69

5-12. MySQL Connection Group V a riables ..............................................................................................71

5-13. OTA Setting Group V a riables...........................................................................................................72

5-14. OTA Bookmark Group V a riables .....................................................................................................73

5-15. SMS Push (send-sms) CGI V a riables...............................................................................................75

5-16. OTA CGI V a riables...........................................................................................................................80

7-1. PPG core group conﬁguration variables.............................................................................................83

7-2. PPG user group conﬁguration variable s.............................................................................................85

B-1. Fakesmsc command line option s.......................................................................................................95

C-1. Test_ppg’s command line options .....................................................................................................99

C-2. Test_ppg’s conﬁguration ﬁle 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

ﬁrst 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 ﬁnd 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 efﬁciently 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

efﬁcient 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 efﬁcient

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

Chapter 1. Introduction

intermittent bandwidth, and extremely awkward input mechanisms. Most existing HTML pages do not

work on mobiles phones, and never will.

WAP deﬁnes a completely new markup language, the Wireless Markup Language (WML), which is

simpler and much more strictly deﬁned than HTML. It also deﬁnes a scripting language, WMLScript,

which all browsers are required to support. To make things even simpler for the phones, it even deﬁnes

its own bitmap format (Wireless Bitmap, or WBMP).

HTTP is also too inefﬁcient 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 deﬁnes 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

Chapter 1. Introduction

instance, when it must send a mail notiﬁcation or a stock quote. For this purpose Wapforum deﬁned

WAP Push.

Push is an application level service, sitting on the top of existing WAP stack. It deﬁnes two protocols,

OTA and PAP. OTA is a ligthweigth protocol speaking with WAP stack (to be more speciﬁc, with WSP),

PAP speaks with the push initiator. It deﬁnes 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 speciﬁc 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

ﬁt 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

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

conﬁgurations.

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 speciﬁc SMS center responsible for that number

(plus possibly many others). This SMS center then sends the message onward to speciﬁed receiver in

intra- or Internet, using an SMS center speciﬁc 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 uniﬁed form.

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 speciﬁc 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 speciﬁc protocol. This way the content provider does not need to know

any SMS center speciﬁc protocol, just uniﬁed 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.

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 ﬂufﬁer. 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.

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 ﬁles in

the correct places; the next chapter will explain how the gateway is conﬁgured.

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 ﬁles 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 modiﬁcations. 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).

Chapter 2. Installing the gateway

• GNU autoconf, if you want to modify the conﬁguration 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 ﬁnishes its job, you have a problem,

and you either need to ﬁx it yourself, if you can, or report the problem to the Kannel project. See Chapter

10 for details.

For detailed instruction on using the conﬁguration script, see ﬁle INSTALL. That ﬁle is a generic

documentation for conﬁgure. Kannel deﬁnes 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 ﬁle 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.

Chapter 2. Installing the gateway

You may need to add compilations ﬂags to conﬁgure:

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

Replace /path/to/directory with the pathname of the actual directory where the programs should

be installed. The programs that are installed are (as ﬁlenames from the root of the source directory):

gw/bearerbox

gw/smsbox

gw/wapbox

The version number of the gateway is added to the ﬁle 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

Chapter 2. Installing the gateway

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

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

conﬁguration 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/.

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 conﬁguration ﬁle which is at

/etc/kannel/kannel.conf. In the same directory there is an example ﬁle called smskannel.conf. It has some

basic examples of the conﬁguration groups needed to run Kannel as a SMS gateway. For more detailed

information please read the section "SMS gateway conﬁguration" later in this same document.

The logging is disabled by default and you can enable it from the kannel.conf ﬁle. Just add the log-ﬁle

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 ﬁle called control.html. It is an example ﬁle 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 ﬁle

1. Download the binary DEB packet from the Kannel web site.

2. Log in as root:

su -

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 conﬁguration ﬁles:

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

conﬁguration 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 conﬁguration ﬁle which is at

/etc/kannel/kannel.conf. In /usr/share/docs/kannel/examples/ there are example ﬁles. They have some

basic examples of the conﬁguration groups needed to run Kannel as a SMS gateway. For more detailed

information please read the section "SMS gateway conﬁguration" later in this same document.

Chapter 2. Installing the gateway

The documentation will be installed at /usr/share/doc/kannel/.

In the Kannel documentation directory there is a html ﬁle called control.html. It is an example ﬁle 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.

Chapter 3. Using the gateway

This chapter explains how the gateway core, bearerbox, is conﬁgured and used. It covers the

conﬁguration ﬁle, 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 conﬁguration and other aspects of gateway of that type.

There is only one conﬁguration ﬁle for all parts of Kannel, although when Kannel is distributed to

several hosts some lines from the conﬁguration ﬁle can be removed in some hosts.

Conﬁguring the gateway

The conﬁguration ﬁle can be divided into three parts: bearerbox conﬁgurations, smsbox conﬁgurations

and wapbox conﬁgurations. 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.

Conﬁguration ﬁle syntax

A conﬁguration ﬁle consists of groups of conﬁguration variables. Groups are separated by empty lines,

and each variable is deﬁned on its own line. Each group in Kannel conﬁguration 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 deﬁnition 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:

# A do-nothing service.

group = sms-service

keyword = nop

text = "You asked nothing and I did it!"

# Default service.

group = sms-service

keyword = default

text = "No services defined"

The above snippet deﬁnes the keyword nop for an SMS service, and a default action for situation when

the keyword in the SMS message does not match any deﬁned service.

Chapter 3. Using the gateway

Lines 1 and 6 are comment lines. Line 5 separates the two groups. The remaining lines deﬁne variables.

The group type is deﬁned by the group variable value.

The various variables that are understood in each type of conﬁguration 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 conﬁguration ﬁles

A conﬁguration ﬁle may contain a special directive called include to include other ﬁle or a directory

with ﬁles to the conﬁguration processing.

This allows to segment the speciﬁc conﬁguration groups required for several services and boxes to

different ﬁles 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 conﬁguration ﬁle that includes the following wapbox.conf ﬁle with

all required directives for the speciﬁc box, and a configurations directory which may include more

ﬁles 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 deﬁned at any point in the conﬁguration ﬁle and at any inclusion

depth. Hence you can cascade numerous inclusions if necessary.

At process start time inclusion of conﬁguration ﬁles breaks if either the included ﬁle can not be opened

and processed or the included ﬁle has been processed already in the stack and a recursive cycling has

been detected.

Chapter 3. Using the gateway

Core conﬁguration

Conﬁguration for Kannel MUST always include a group for general bearerbox conﬁguration. This group

is named as ’core’ in conﬁguration ﬁle, and should be the ﬁrst group in the conﬁguration ﬁle.

As its simplest form, ’core’ group looks like this:

group = core

admin-port = 13000

admin-password = f00bar

Naturally this is not sufﬁcient 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 conﬁguration 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

recommended)

admin-port (m)

port-number

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".

admin-port-ssl (o)

admin-password (m)

bool

Password for HTTP

administration commands (see

below)

string

Password to request Kannel

status. If not set, no password is

required, and if set, either this or

admin-password can be used

status-password

string

Chapter 3. Using the gateway

Description

Variable

Value

These lists can be used to

prevent connection from given IP

addresses. Each list can have

several addresses, separated with

semicolons (’;’). An asterisk

(’*’) can be used as a wildcard in

a place of any ONE number, so

*.*.*.* matches any IP.

admin-deny-ip

admin-allow-ip

IP-list

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

trafﬁc.

smsbox-port (c)

port-number

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

to "no".

smsbox-port-ssl (o)

wapbox-port (c)

bool

Like smsbox-port, but for

wapbox-connections. If not set,

Kannel cannot handle WAP

trafﬁc

port-number

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

layer. Defaults to "no".

wapbox-port-ssl (o)

bool

Chapter 3. Using the gateway

Description

Variable

Value

These lists can be used to

prevent box connections from

given IP addresses. Each list can

have several addresses, separated

with semicolons (’;’). An asterisk

(’*’) can be used as a wildcard in

place of any ONE number, so

*.*.*.* matches any IP.

box-deny-ip

box-allow-ip

IP-list

These lists can be used to

prevent UDP packets from given

IP addresses, thus preventing

unwanted use of the WAP

gateway. Used the same way as

box-deny-ip and

udp-deny-ip

udp-allow-ip

IP-list

box-allow-ip.

If this is set, Kannel listens to

WAP UDP packets incoming to

ports 9200-9208, bound to given

IP. If no speciﬁc IP is needed, use

just an asterisk (’*’). If UDP

messages are listened to,

wapbox-port variable MUST be

set.

wdp-interface-name (c)

IP or ’*’

A ﬁle in which to write a log.

This in addition to stdout and

any log ﬁle deﬁned in command

line. Log-ﬁle in ’core’ group is

only used by the bearerbox.

log-file

ﬁlename

number 0..5

ﬁlename

Minimum level of logﬁle events

logged. 0 is for ’debug’, 1 ’info’,

2 ’warning, 3 ’error’ and 4

’panic’ (see Command Line

Options)

log-level

A ﬁle in which information

about received/sent SMS

messages is stored. Access-log in

’core’ group is only used by the

bearerbox.

access-log

Chapter 3. Using the gateway

Description

Variable

Value

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 ﬁrst

comes the uniﬁed preﬁx, then all

preﬁxes which are replaced by

the uniﬁed preﬁx, separated with

comma (’,’). For example, for

Finland an uniﬁed-preﬁx

"+358,00358,0;+,00" should do

the trick. If there are several

uniﬁed preﬁxes, separate their

rules with semicolon (’;’), like

"+35850,050;+35840,040". Note

that preﬁx routing is next to

useless now that there are SMSC

ID entries. To remove preﬁxes,

use like

unified-prefix

preﬁx-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 ﬁle.

NOTE: the system has only a

precision of last 9 or 18 digits of

phone numbers, so beware!

white-list

black-list

URL

As white-list, but SMS messages

to these numbers are

automatically discarded

Chapter 3. Using the gateway

Description

Variable

Value

A ﬁle 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

down violently.

store-file

ﬁlename

Enable the use of an HTTP

proxy for all HTTP requests.

http-proxy-host

http-proxy-port

hostname

port-number

A list of excluded hosts from

being used via a proxy. Separate

each entry with space.

http-proxy-exceptions

http-proxy-username

http-proxy-password

URL-list

username

URL-list

Username for authenticating

proxy use, for proxies that

require this.

Password for authenticating

proxy use, for proxies that

require this.

A PEM encoded SSL certiﬁcate

and private key ﬁle to be used

with SSL client connections.

This certiﬁcate is used for the

HTTPS client side only, i.e. for

SMS service requests to

ssl-client-certkey-file

(c)

ﬁlename

SSL-enabed HTTP servers.

A PEM encoded SSL certiﬁcate

ﬁle to be used with SSL server

connections. This certiﬁcate 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) ﬁlename

A PEM encoded SSL private

key ﬁle to be used with SSL

server connections. This key is

associated to the speciﬁed

certiﬁcate and is used for the

HTTPS server side only.

ssl-server-key-file (c)

ﬁlename

Chapter 3. Using the gateway

Description

Variable

Value

This ﬁle contains the certiﬁcates

Kannel is willing to trust when

working as a HTTPS client. If

this option is not set, certiﬁcates

are not validated and those the

identity of the server is not

proven.

ssl-trusted-ca-file

ﬁlename

Deﬁnes the way DLRs are

stored. If you have build-in

external DLR storage support,

i.e. using MySQL you may

deﬁne here the alternative storage

type like ’mysql’. Supported

types are: internal, mysql. By

default this is set to ’internal’.

dlr-storage

type

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 inﬁnite length is accepted.

(This works with any normal

input, use this variable only

when Kannel message queues

grow very long).

maximum-queue-length

number of messages

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"

Chapter 3. Using the gateway

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 conﬁguration ﬁle 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 ﬁne). 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.

[confﬁle] is the name of the conﬁguration ﬁle you are using with Kannel. The basic distribution packet

comes with two sample conﬁguration ﬁles, smskannel.conf and wapkannel.conf (in gw

subdirectory), of which the ﬁrst one is for testing out SMS Kannel and the second one for setting up a

WAP Kannel. Feel free to edit those conﬁguration ﬁles 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

Set verbosity level for stdout (screen) logging.

-v <level>

Default is 0, which means ’debug’. 1 is ’info, 2

’warning’, 3 ’error’ and 4 ’panic’

Chapter 3. Using the gateway

--verbosity <level>

Set debug-places for ’debug’ level output.

-D <places>

--debug <places>

Log to ﬁle named ﬁle-name, too. Does not overrun

or affect any logﬁle deﬁned in conﬁguration ﬁle.

-F <file-name>

--logfile <file-name>

Set verbosity level for that extra logﬁle (default 0,

which means ’debug’). Does not affect verbosity

level of the logﬁle deﬁned in conﬁguration ﬁle, not

verbosity level of the stdout output.

-V <level>

--fileverbosity <level>

Start the system initially at SUSPENDED state

(see below, bearerbox only)

-S

--suspended

Start the system initially at ISOLATED state (see

below, bearerbox only)

-I

--isolated

Only try to open HTTP sendsms interface; if it

fails, only warn about that, do not exit. (smsbox

only)

-H

--tryhttp

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

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 conﬁgured admin-port in Kannel conﬁguration ﬁle (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 conﬁguration 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

supplied.

HTML version of status

XML version of status

WML version of status

status.xml

status.wml

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

supplied.

store-status or store-status.txt

store-status.html

HTML version of store-status

XML version of store-status

store-status.xml

Set Kannel state as ’suspended’ (see above).

Password required.

suspend

isolate

resume

Set Kannel state as ’isolated’ (see above).

Password required.

Set Kannel state as ’running’ if it is suspended or

isolated. Password required.

Chapter 3. Using the gateway

Bring down the gateway, by setting state to

’shutdown’. After a shutdown is initiated, there is

no other chance to resume normal operation.

However, ’status’ command still works. Password

required. If shutdown is sent for a second time, the

gateway is forced down, even if it has still

messages in queue.

shutdown

If Kannel state is ’suspended’ this will ﬂush all

queued DLR messages in the current storage

space. Password required.

flush-dlr

start-smsc

stop-smsc

Re-start a single SMSC link. Password required.

Additionally the smsc parameter must be given to

identify which smsc-id should be re-started.

Shutdown a single SMSC link. Password

required. Additionally the smsc parameter must be

given (see above).

Chapter 4. Setting up a WAP gateway

This chapter tells you how to set Kannel up as a WAP gateway.

WAP gateway conﬁguration

To set up a WAP Kannel, you have to edit the ’core’ group in the conﬁguration ﬁle, and deﬁne the

’wapbox’ group.

You must set following variables for the ’core’ group: wapbox-port and wdp-interface-name. See

previous chapter about details of these variables.

With standard distribution, a sample conﬁguration ﬁle wapkannel.conf is supplied. You may want to

take a look at that when setting up a WAP Kannel.

Wapbox conﬁguration

If you have set wapbox-port variable in the ’core’ conﬁguration group, you MUST supply a ’wapbox’

group.

The simplest working ’wapbox’ group looks like this:

group = wapbox

bearerbox-host = localhost

There is, however, multiple optional variables for the ’wapbox’ group.

Table 4-1. Wapbox Group Variables

Variable

Value

Description

group (m)

wapbox

This is mandatory variable

The machine in which the

bearerbox is.

bearerbox-host (m)

timer-freq

hostname

The frequency of how often

timers are checked out. Default is

value-in-seconds

Chapter 4. Setting up a WAP gateway

Variable

Value

Description

The pair is separated with space.

Adds a single mapping for the

left side URL to the given

destination. If you append an

asterisk ‘*’ to the left side URL,

its preﬁx Is matched against the

incoming URL. Whenever the

preﬁx matches, the URL will be

replaced completely by the right

side. In addition, if if you append

an asterisk to the right side URL,

the part of the incoming URL

coming after the preﬁx, will be

appended to the right side URL.

Thus, for a line: map-url =

"http://source/*

http://destination/*" and an

incoming URL of

"http://source/some/path", the

result will be

map-url

URL-pair

number

"http://destination/some/path"

If you need more than one

mapping, set this to the highest

number mapping you need. The

default gives you 10 mappings,

numbered from 0 to 9. Default: 9

map-url-max

Adds a mapping for the left side

URL to the given destination

URL. Repeat these lines, with 0

replaced by a number up to

map-url-max, if you need several

mappings.

map-url-0

URL-pair

Adds a mapping for the URL

DEVICE:home (as sent by

Phone.com browsers) to the

given destination URL. There is

no default mapping. NOTE: the

mapping is added with both

asterisks, as described above for

the "map-url" setting. Thus, the

above example line is equivalent

to writing map-url =

"DEVICE:home*

device-home

URL

http://some.where/*"

Chapter 4. Setting up a WAP gateway

Variable

Value

Description

As with bearerbox ’core’ group.

log-file

ﬁlename

log-level

number 0..5

Messages of this log level or

higher will also be sent to syslog,

the UNIX system log daemon.

The wapbox logs under the

’daemon’ category. The default is

not to use syslog, and you can set

that explicitly by setting

syslog-level

number

syslog-level to ’none’.

If set wapbox will force to

process WTP-SAR connections

even while Kannel does not

support this feature now. Some

real phones seem to break

connection if fallback to non

SAR communication is being

tried by the gateway.

force-sar

bool

If set wapbox will return a valid

WML deck describing the eror

that occured while processing an

WSP request. This may be used

to have a smarter gateway and let

the user know what happend

actually.

smart-errorsr

Running WAP gateway

WAP Gateway is ran as explained in previous chapter.

Checking whether the WAP gateway is alive

You can check whether the WAP gateway (both the bearerbox and the wapbox) is alive by fetching the

URL kannel:alive.

Chapter 5. Setting up a SMS Gateway

This chapter is a more detailed guide on how to set up Kannel as an SMS gateway.

Required components

To set up an SMS gateway, you need, in addition to a machine running Kannel, access to (an operator’s)

SMS center, or possibly to multiple ones. The list of supported SMS centers and their conﬁguration

variables is below.

If you do not have such access, you can still use Kannel as an SMS gateway via phone-as-SMSC feature,

by using a GSM phone as a virtual SMS center.

In addition to an SMS center (real or virtual), you need some server to handle any SMS requests

received. This server then has simple or more complex cgi-bins, programs or scripts to serve HTTP

requests generated by Kannel in response to received SMS messages. These services can also initiate

SMS push via Kannel smsbox HTTP sendsms interface.

SMS gateway conﬁguration

To set up a SMS Kannel, you have to edit the ’core’ group in the conﬁguration ﬁle, and deﬁne an

’smsbox’ group plus one or more ’sms-service’ groups, plus possibly one or more ’sendsms-user’ groups.

For the ’core’ group, you must set the following variable: smsbox-port. In addition, you may be

interested to set unified-prefix, white-list and/or black-list variables. See above for details

of these variables.

A sample conﬁguration ﬁle smskannel.conf is supplied with the standard distribution. You may want

to take a look at that when setting up an SMS Kannel.

SMS centers

To set up the SMS center at Kannel, you have to add a ’smsc’ group into conﬁguration ﬁle. This group

must include all the data needed to connect that SMS center. You may also want to deﬁne an ID

(identiﬁcation) name for the SMSC, for logging and routing purposes.

SMSC ID is an abstract name for the connection. It can be anything you like, but you should avoid any

special characters. You do not need to use ID, but rely on SMS center IP address and other information.

However, if you use the ID, you do not need to re-deﬁne sms-services nor routing systems if the IP of the

SMS Center is changed, for example.

Common ’smsc’ group variables are deﬁned in the following table. The ﬁrst two (group and smsc) are

mandatory, but rest can be used if needed.

Table 5-1. SMSC Group Variables

Variable

Value

Description

Chapter 5. Setting up a SMS Gateway

Variable

Value

Description

group (m)

smsc

This is a mandatory variable

Identiﬁes the SMS center type.

See below for a complete list.

smsc (m)

string

An optional name or id for the

smsc. Any string is acceptable,

but semicolon ’;’ may cause

problems, so avoid it and any

other special non-alphabet

characters. This ’id’ is written

into log ﬁles and can be used to

route SMS messages, and to

specify the used SMS-service.

Several SMSCs can have the

same id. The name is

case-insensitive. Note that if

SMS Center connection has an

assigned SMSC ID, it does NOT

automatically mean that

messages with identical SMSC

ID are routed to it; instead

conﬁguration variables

denied-smsc-id,

allowed-smsc-id and

preferred-smsc-id is used

for that.

smsc-id

string

SMS messages with SMSC ID

equal to any of the IDs in this list

are never routed to this SMSC.

Multiple entries are separated

with semicolons (’;’)

denied-smsc-id

allowed-smsc-id

id-list

This list is opposite to previous:

only SMS messages with SMSC

ID in this list are ever routed to

this SMSC. Multiple entries are

separated with semicolons (’;’)

SMS messages with SMSC ID

from this list are sent to this

SMSC instead than to SMSC

without that ID as preferred.

Multiple entries are separated

with semicolons (’;’)

preferred-smsc-id

id-list

Chapter 5. Setting up a SMS Gateway

Variable

Value

Description

A list of phone number preﬁxes

which are accepted to be sent

through this SMSC. Multiple

entries are separated with

semicolon (’;’). For example,

"040;050" prevents sending of

any SMS message with preﬁx of

040 or 050 through this SMSC.

If denied-preﬁx is unset, only

this numbers are allowed. If set,

number are allowed if present in

allowed or not in denied list.

allowed-prefix

denied-prefix

prefix-list

A list of phone number preﬁxes

which are NOT accepted to be

sent through this SMSC.

As denied-prefix, but SMS

messages with receiver starting

with any of these preﬁxes is

preferably sent through this

SMSC. In a case of multiple

preferences, one is selected at

random (also if there are

preferences, SMSC is selected

randomly)

preferred-prefix

prefix-list

Chapter 5. Setting up a SMS 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 ﬁrst

comes the uniﬁed preﬁx, then all

preﬁxes which are replaced by

the uniﬁed preﬁx, separated with

comma (’,’). For example, for

Finland an uniﬁed-preﬁx

"+358,00358,0;+,00" should do

the trick. If there are several

uniﬁed preﬁxes, separate their

rules with semicolon (’;’), like

"+35850,050;+35840,040". Note

that preﬁx routing is next to

useless now that there are SMSC

ID entries. To remove preﬁxes,

use like

unified-prefix

preﬁx-list

"-,+35850,050;-,+35840,040".

As some SMS Centers do not

follow the standards in character

coding, an alt-charset

character conversion is

presented. This directive acts

different for speciﬁc SMSC

tyles. Please see your SMSC

module type you want to use for

more details.

alt-charset

number

In addition to these common variables there are several variables used by certain SMS center

connections. Each currently supported SMS center type is explained below, with conﬁguration group for

each. Note that many of them use variables with same name, but most also have some speciﬁc variables.

NOTE: SMS center conﬁguration variables are a bit incomplete, and will be updated as soon as people

responsible for the protocols are contacted. Meanwhile, please have patience.

Nokia CIMD 1.37 and 2.0

Support for CIMD 1.37 is quite old and will be removed in a future version of Kannel. Please let us know

if you still need it.

Chapter 5. Setting up a SMS Gateway

group = smsc

smsc = cimd

host = 100.101.102.103

port = 600

smsc-username = foo

smsc-password = bar

The driver for CIMD2 is a "receiving SME" and expects the SMSC to be conﬁgured for that. It also

expects the SMSC to automatically send stored messages as soon as Kannel logs in (this is the normal

conﬁguration).

group = smsc

smsc = cimd2

host = 100.101.102.103

port = 600

smsc-username = foo

smsc-password = bar

keepalive = 5

sender-prefix = "12345"

Variable

Value

Description

Machine that runs the SMSC.

As IP (100.100.100.100) or

hostname (their.machine.here)

host (m)

hostname

port-number

string

Port number in the smsc host

machine

port (m)

Username in the SMSC

machine/connection account

smsc-username (m)

smsc-password (m)

Password in the SMSC machine

needed to contact SMSC

string

SMSC connection will not be

left idle for longer than this many

minutes. The right value to use

depends on how eager the SMSC

is to close idle connections. 5

minutes is a good guess. If you

see many unexplained

reconnects, try lowering this

value. Set it to 0 to disable this

feature.

keepalive

number

Chapter 5. Setting up a SMS Gateway

Variable

Value

Description

The number that the SMSC will

add in front of the sender number

of all messages sent from

Kannel. If Kannel is asked to

send a message, it will remove

this preﬁx from the sender

number so that the SMSC will

add it again. If the preﬁx was not

present, Kannel will log a

warning and will not send the

sender number. If

sender-prefix is not set, or is

set to "never", then Kannel will

not send the sender number to the

SMSC at all. If you want Kannel

to pass all sender numbers to the

SMSC unchanged, then just set

sender-prefix to the empty

string "".

sender-prefix

string

CMG UCP/EMI 4.0

Kannel supports two types of connections with CMG SMS centers: direct TCP/IP connections (emi_ip

or emi2) and ISDN/modem (X.25 over D channel ISDN is called X.31) connection (emi). emi2 is a new

implementation of the EMI protocol that supports more features and should work more reliably than the

old one. It is the recommended one to use with TCP/IP connections. Sample conﬁgurations for these are:

group = smsc

smsc = emi2

#smsc = emi_ip to use the old implementation

host = 103.102.101.100

port = 600

smsc-username = foo

smsc-password = bar

keepalive = 55

our-port = 600 (optional bind in our end)

receive-port = 700 (the port in which the SMSC will contact)

idle-timeout = 30

group = smsc

smsc = emi

host = 100.102.100.102

phone = ...

device = /dev/tty0

smsc-username = foo

smsc-password = bar

Chapter 5. Setting up a SMS Gateway

Variable

Value

Description

Machine that runs SMSC. As IP

(100.100.100.100) or hostname

(their.machine.here)

host (c)

port (c)

hostname

Port number in the SMSC host

machine

port-number

Optional alternate Machine that

runs SMSC. As IP

(100.100.100.100) or hostname

(their.machine.here) (If undef but

exists alt-port, emi2 would try

host:alt-port)

alt-host

hostname

Optional alternate Port number

in the SMSC host machine (If

undef but exists alt-host, emi2

would try alt-host:port)

alt-port

port-number

string

Username in the SMSC

machine/connection account

smsc-username

smsc-password

Password in the SMSC machine

needed to contact SMSC

string

The device the modem is

connected to, like /dev/ttyS0.

ISDN connection only.

device (c)

phone (c)

our-host

our-port

device-name

string

Phone number to dial to, when

connecting over a modem to an

SMS center.

Optional hostname in which to

bind the connection in our end.

TCP/IP connection only.

hostname

Optional port number in which

to bind the connection in our

end. TCP/IP connection only.

port-number

Optional port number we listen

to and to which the SMS center

connects when it has messages to

send. Required if SMS center

needs one connection to send and

other to receive. TCP/IP

receive-port

appname

port-number

string

connection only.

Name of a "Send only" service.

Defaults to send. All outgoing

messages are routed through this

service.

Chapter 5. Setting up a SMS Gateway

Variable

Value

Description

If set, only connections from

these IP addresses are accepted

to receive-port. TCP/IP

connection only.

connect-allow-ip

IP-list

If this option is set to a value

larger than 0, then the connection

will be closed after the

conﬁgured amount of seconds

without activity. This option

interacts with the keepalive

conﬁguration option. If

keepalive is smaller than

idle-timeout, then the

connection will never be idle and

those this option has no effect. If

keepalive is larger than

idle-timeout, than

keepalive reopens the

connection. This allows one to

poll for pending mobile

originated Short Messages at the

SMSC.

idle-timeout

number (seconds)

A keepalive command will be

sent to the SMSC connection this

many seconds after the last

message. The right value to use

depends on how eager the SMSC

is to close idle connections. 50

seconds is a good guess. If you

see many unexplained

reconnects, try lowering this

value. Set it to 0 to disable this

feature. Requires username or

my-number to be set.

keepalive

wait-ack

number (seconds)

A message is resent if the

acknowledge from SMSC takes

more than this time. Defaults to

60 seconds.

Chapter 5. Setting up a SMS Gateway

Variable

Value

Description

Deﬁnes what kind of action

should be taken if the the ack of

a message expires. The options

for this value are: 0x00 -

disconnect/reconnect, (default)

0x01 - as is now, requeue, but

this could potentially result in the

msg arriving twice 0x02 - just

carry on waiting (given that the

wait-ack should never expire this

is the mst accurate)

wait-ack-expire

number

This SMSC can support two

types of ﬂow control. The ﬁrst

type of ﬂow control is a

stop-and-wait protocol, when

this parameter equals to ’1’.

During the handling of

commands, no other commands

shall be sent before the a

response is received. Any

command that is sent before the

reception of the response will be

discarded. The second type of

ﬂow control is windowing,

when this parameter is unset or

equals ’0’. In this case a

maximum of n commands can be

sent before a response is

flow-control

number

received.

When using flow-control=0,

emi works in windowed ﬂow

control mode. This variable

deﬁnes the size of the window

used to send messages. (optional,

defaults to the maximum - 100)

window

number (messages)

If SMSC requires that kannel

limits the number of messages

per second, use this variable.

(optional)

throughput

number (messages/sec)

Assuming that kannel is well

conﬁgured and we had one

sucessful connection, if retry is

true, kannel will always retry the

connection even if some related

error ocur.

retry

boolean

Chapter 5. Setting up a SMS Gateway

Variable

Value

Description

If the large account number is

different from the short number,

assign it with this variable. For

example, if short number is

12345 and large account is

0100100100101234 (IP+port),

set my-number to 12345 and

every message received will have

that receiver.

my-number

number

Deﬁnes which character

conversion kludge may be used

for this speciﬁc link. Currently

implemented alternative charsets

are deﬁned in "alt_charsets.h"

and new ones can be added.

alt-charset

SMPP 3.4

This implements Short Message Peer to Peer (SMPP) Protocol 3.4 in a manner that should also be

compatible with 3.3. Sample conﬁguration:

group = smsc

smsc = smpp

host = 123.123.123.123

port = 600

receive-port = 700

smsc-username = "STT"

smsc-password = foo

system-type = "VMA"

address-range = ""

Variable

Value

Description

Machine that runs SMSC. As IP

(100.100.100.100) or hostname

(their.machine.here)

host (m)

hostname

The port number for the

TRANSMITTER connection to

the SMSC. May be the same as

receive-port. Use value 0 to

disable this I/O thread.

port (m)

port-number

Chapter 5. Setting up a SMS Gateway

Variable

Value

Description

Attempt to use a

TRANSCEIVER mode

connection to the SM-SC. It uses

the standard transmit ’port’, there

is no need to set ’receive-port’.

This is a SMPP 3.4 only feature

and will not work on an earlier

SM-SC. This will try a

bind_transceiver only and will

not attempt to fall back to doing

transmit and receive on the same

connection.

transceiver-mode

receive-port

bool

The port number for the

RECEIVER connection to the

SMSC. May be the same as port.

Use value 0 to disable this I/O

thread.

port-number

The ’username’ of the

Messaging Entity connecting to

the SM-SC. If the SM-SC

operator reports that the

"TELEPATH SYSTEM

MANAGER TERMINAL" view

"Control.Apps.View" value

"Name:" is

"SMPP_ZAPVMA_T" for the

transmitter and

"SMPP_ZAPVMA_R" for the

receiver the smsc-username value

is accordingly "SMPP_ZAP".

Note that this used to be called

system-id (the name in SMPP

documentation) and has been

changed to smsc-username to

make all Kannel SMS center

drivers use the same name.

smsc-username (m)

smsc-password (m)

system-type (m)

string

The password matching the

"smsc-username" your

teleoperator provided you with.

Usually you can get away with

"VMA" which stands for Voice

Mail Activation.

Chapter 5. Setting up a SMS Gateway

Variable

Value

Description

Change the "interface version"

parameter sent from Kannel to a

value other then 0x34 (for SMPP

v3.4). the value entered here

should be the hexadecimal

representation of the interface

version parameter. for example,

the default (if not set) is "34"

which stands for 0x34. for SMPP

v3.3 set to "33".

interface-version

address-range (m)

number

string

According to the SMPP 3.4 spec

this is supposed to affect which

MS’s can send messages to this

account. Doesn’t seem to work,

though.

Specicy the outgoing IP address

for connections from a

multi-homed machine. If this is

not deﬁned the default device of

the machine will be used.

our-host

string

number

Optional smsc short number.

Should be set if smsc sends a

different one.

my-number

Optional the time lapse allowed

between operations after which

an SMPP entity should

interrogate whether it’s peer still

has an active session. The default

is 30 seconds.

enquire-link-interval

number

Optional the maximum number

of outstanding (i.e.

acknowledged) SMPP operations

between an ESME and SMSC.

This number is not speciﬁed

explicity in the SMPP Protocol

Speciﬁcation and will be

goverened by the SMPP

implementation on the SMSC.

As a guideline it is recommended

that no more than 10 (default)

SMPP messages are outstanding

at any time.

max-pending-submits

number

Chapter 5. Setting up a SMS Gateway

Variable

Value

Description

Optional the time between

attemps to connect an ESME to

an SMSC having failed to

connect initating or during an

SMPP session. The default is 10

seconds.

reconnect-delay

source-addr-ton

source-addr-npi

number

Optional, source address TON

setting for the link. (Defaults to

0).

Optional, source address NPI

setting for the link. (Defaults to

1).

Optional, if deﬁned tries to scan

the source address and set TON

and NPI settings accordingly. If

you don’t want to autodetect the

source address, turn this off, by

setting it to no. (Defaults to yes).

source-addr-autodetect

dest-addr-ton

boolean

number

Optional, destination address

TON setting for the link.

(Defaults to 0).

Optional, destination address

NPI setting for the link. (Defaults

to 1).

dest-addr-npi

Chapter 5. Setting up a SMS Gateway

Variable

Value

Description

Optional, speciﬁes which

number base the SMSC is using

for the message ID numbers in

the corresponding

submit_sm_resp and

deliver_sm PDUs. This is

required to make delivery reports

(DLR) work on SMSC that

behave differently. The number

is a combined set of bit 1 and bit

2 that indicate as follows: bit 1:

type for submit_sm_resp, bit

2: type for deliver_sm. If the

bit is set then the value is in hex

otherwise in decimal number

base. Which means the following

combinations are possible and

valid: 0x00 deliver_sm

decimal, submit_sm_resp

decimal; 0x01 deliver_sm

decimal, submit_sm_resp hex;

0x02 deliver_sm hex,

submit_sm_resp decimal;

0x03 deliver_sm hex,

submit_sm_resp hex. In

accordance to the SMPP v3.4

specs the default will be a C

string literal if no of the above

values is explicitly indicated

using the conﬁg directive.

msg-id-type

number

Deﬁnes which character

encoding is used for this speciﬁc

smsc link. Uses iconv()

routines to convert from and to

that speciﬁc character set

encoding. See your local

iconv_open(3) manual page for

the supported character

encodings and the type strings

that should be presented for this

directive.

alt-charset

string

Sema Group SMS2000 OIS 4.0 and 5.0

The 4.0 implementation is over Radio PAD (X.28). Following conﬁguration variables are needed, and if

Chapter 5. Setting up a SMS Gateway

you ﬁnd out the more exact meaning, please send a report.

The 5.0 implementation uses X.25 access gateway.

group = smsc

smsc = sema

device = /dev/tty0

smsc_nua = (X121 smsc address)

home_nua = (x121 radio pad address)

wait_report = 0/1 (0 means false, 1 means true)

Variable

Value

Description

device (m)

device

ex: /dev/tty0

The address of an SMSC for

SEMA SMS2000 protocols using

an X.28 connection.

smsc_nua (m)

home_nua (m)

wait_report

X121 smsc address

The address of a radio PAD

implementing Sema SMS2000

using X.28 connection.

X121 radio pad address

0 (false)/1 (true)

Report indicator used by the

Sema SMS2000 protocol.

Optional.

group = smsc

smsc = ois

host = 103.102.101.100

port = 10000

receive-port = 10000

ois-debug-level = 0

Variable

host (m)

port (m)

Value

Description

SMSC Host name or IP

SMSC Port number

port number

The port in which the SMSC

will contact

receive-port (m)

ois-debug-level

port number

extra debug, optional, see

smsc_ois.c

number 0 to 8

SM/ASI (for CriticalPath InVoke SMS Center 4.x)

This implements Short Message/Advanced Service Interface (SM/ASI) Protocol for the use of

connecting to a CriticalPath InVoke SMS Center. Sample conﬁguration:

group = smsc

smsc = smasi

host = 10.11.12.13

port = 23456

Chapter 5. Setting up a SMS Gateway

smsc-username = foo

smsc-password = foo

Variable

Value

Description

Machine that runs SMSC. As IP

(10.11.12.13) or hostname

(host.foobar.com)

host (m)

port (m)

hostname

The port number for the

connection to the SMSC.

port-number

The ’username’ of the

Messaging Entity connecting to

the SMSC.

smsc-username (m)

smsc-password (m)

string

The password matching the

"smsc-username" your

teleoperator provided you with.

Optional, the time between

attemps to connect to an SMSC

having failed to connect initating

or during an session. The default

is 10 seconds.

reconnect-delay

source-addr-ton

source-addr-npi

dest-addr-ton

dest-addr-npi

number

Optional, source address TON

setting for the link. (Defaults to

1).

Optional, source address NPI

setting for the link. (Defaults to

1).

Optional, destination address

TON setting for the link.

(Defaults to 1).

Optional, destination address

NPI setting for the link. (Defaults

to 1).

Optional, sets the default

priority of messages transmitted

over this smsc link. (Defaults to

0, which is the highest priority)

priority

number

GSM modem

Kannel can use a GSM modem as an SMS center.

group = smsc

smsc = at

modemtype = wavecom

device = /dev/ttyS0

Chapter 5. Setting up a SMS Gateway

pin = 2345

Variable

Value

Description

Modems from different

manufacturers have slightly

different behaviour. We need to

know what type of modem is

used.

modemtype

string

The device the modem is

device (m)

device-name

connected to, like /dev/ttyS0.

This is the PIN number of the

SIM card in the GSM modem.

You can specify this option if

your SIM has never been used

before and needs to have the PIN

number entered. The PIN is

usually a four digit number.

string

How long the message will be

valid, i.e., how long the SMS

center (the real one, not the

phone acting as one for Kannel)

will try to send the message to

the recipient. Encoded as per the

GSM 03.40 standard, section

9.2.3.12. Default is 167, meaning

24 hours.

validityperiod

integer

When encoding DCS ﬁeld

internally, there are two formats

with similar functionality. The

0x0X (alt-dcs = false or

non-present) or the 0xFX (alt-dcs

= true). If you have a buggy

modem (like Siemens M20) that

don’t like to send binary

messages, try setting alt-dcs to

true.

alt-dcs

boolean

Modem Type

wavecom

Modems

Wavecom

premicell

Nokia Premicell

Siemens M20 (this modem have

some bugs)

siemens

siemens-tc35

falcom

Siemens TC35

Falcom

Chapter 5. Setting up a SMS Gateway

Modem Type

Modems

Nokia 6210, 7110, 8210 (tested).

Probably other Nokia phones

too.

nokiaphone

ericsson

Ericsson

GSM modem 2

This new driver is replacing the old GSM Modem driver from Kannel. It allows a GSM Modem or Phone

to be connected to Kannel and work as a virtual SMSC

group = smsc

smsc = at2

modemtype = auto

device = /dev/ttyS0

speed = 9600

pin = 2345

Variable

Value

Description

Modems from different

manufacturers have slightly

different behaviour. We need to

know what type of modem is

used. Use "auto" or omit

parameter to have kannel detect

the modem type automatically.

(some types should not be

autodetected like the Nokia

Premicell).

modemtype

string

The device the modem is

device (m)

device-name

connected to, like /dev/ttyS0.

The speed in bits per second.

Default value 0 means to try to

use speed from modem

deﬁnition, or if it fails, try to

autodetect.

speed

serial speed in bps

This is the PIN number of the

SIM card in the GSM modem.

You can specify this option if

your SIM has never been used

before and needs to have the PIN

number entered. The PIN is

usually a four digit number.

string

Chapter 5. Setting up a SMS Gateway

Variable

Value

Description

How long the message will be

valid, i.e., how long the SMS

center (the real one, not the

phone acting as one for Kannel)

will try to send the message to

the recipient. Encoded as per the

GSM 03.40 standard, section

9.2.3.12. Default is 167, meaning

24 hours.

validityperiod

integer

boolean

Assuming that kannel is well

conﬁgured and we had one

sucessful connection, if retry is

true, kannel will always retry the

connection even if some related

error ocur.

retry

Kannel would "ping" the modem

for this many seconds. If the

probe fails, try to reconnect to it.

keepalive

my-number

sms-center

seconds

number

Optional phone number.

SMS Center to send messages.

Whether to enable the so-called

"SIM buffering behaviour" of the

GSM module. if assigned a true

value, the module will query the

message storage memory of the

modem and will process and

delete any messages found there.

this does not alter normal

behaviour, but only add the

capability of reading messages

that were stored in the memory

for some reason. The type of

memory to use can be selected

using the ’message-storage’

parameter of the modem

conﬁguration. Polling the

memory is done at the same

interval as keepalive (if set) or 60

seconds (if not set). NOTE: This

behaviour is known to cause

minor or major hicups for a few

buggy modems. Modems known

to work with this setting are

Wavecom WM02/M1200 and the

Siemens M20.

sim-buffering

boolean

Chapter 5. Setting up a SMS Gateway

Modem deﬁnitions are now multiple groups present in kannel.conf, either directly or, for example, by

including the example modems.conf. (See Inclusion of conﬁguration ﬁles)

Variable

Value

Description

group

modems

This is a mandatory variable

This is the the id that should be

used in modemtype variable

from AT2

string

The name of this modem

conﬁguration. Used in logs

name

String to use when trying to

detect the modem. See

detect-string2

detect-string

string

Second string to use to detect the

modem. For example, if the

modem replies with "SIEMENS

MODEM M20",

detect-string could be

"SIEMENS" and

detect-string2

init-string

speed

string

number

string

detect-strign2 "M20"

Optional initialization string.

Defaults to

"AT+CNMI=1,2,0,1,0"

Serial port hint speed to use.

Optional. Defaults to smsc group

speed or autodetect

Optional AT command to enable

hardware handshake. Defaults to

"AT+IFC=2,2"

enable-hwhs

Optional. Defaults to false.

Some modems needs to sleep

after opening the serial port and

before ﬁrst command

need-sleep

no-pin

boolean

Optional. Defaults to false. If the

modem doesn’t support the PIN

command, enable this

Optional. Defaults to false. If the

modem doesn’t support setting

the SMSC directly on the pdu,

enable this. (Default is to include

a "00" at the beginning of the

PDU to say it’s the default smsc,

and remove the "00" when

receiving)

no-smsc

boolean

Chapter 5. Setting up a SMS Gateway

Variable

Value

Description

Optional, defaults to 100

miliseconds. The sleep time after

sending a AT command.

sendline-sleep

number (miliseconds)

Optional, defaults to "AT". If

keepalive is activated in AT2

group, this is the command to be

sent. If your modem supports it,

for example, use

"AT+CBC;+CSQ", and see in

logs the reply "+CBC: 0,64"

(0=On batery, 64% full) and

"+CSQ: 14,99" (0-31, 0-7: signal

strenght and channel bit error

rate; 99 for unknown). See 3GPP

27007.

keepalive-cmd

string

Message storage memory type

to enable for "SIM buffering".

Possible values are: "SM" - SIM

card memory or "ME" - Mobile

equipment memory (may not be

suppoerted by your modem).

check your modem’s manual for

more types. By default, if the

option is not set, no message

storage command will be sent to

the modem and the modem’s

default message storage will be

used (usually "SM").

message-storage

string

Optional, defaults to false. If

enabled, kannel would send an

AT+CMMS=2 if it have more

than one message on queue and

hopefully will be quickier

sending the messages.

enable-mms

boolean

A note about delivery reports and GSM modems: while it is possible (and supported) to receive delivery

reports on GSM modems, it may not work for you. if you encounter problems, check that your modem’s

init string (if not the default) is set to correctly allow the modem to send delivery reports using unsolicted

notiﬁcation (check your modem’s manual). If the init-string is not set as si, some modems will store

delivery reports to SIM memory, to get at which you will need to enable sim-buffering. ﬁnally your GSM

network provider may not support delivery reports to mobile units.

Fake SMSC

Fake SMSC is a simple protocol to test out Kannel. It is not a real SMS center, and cannot be used to

send or receive SMS messages from real phones. So, it is ONLY used for testing purposes.

Chapter 5. Setting up a SMS Gateway

group = smsc

smsc = fake

port = 10000

connect-allow-ip = 127.0.0.1

Variable

Value

Description

Machine that runs the SMSC.

As IP (100.100.100.100) or

hostname (their.machine.here)

host (m)

hostname

port-number

IP-list

Port number in smsc host

machine

port (m)

If set, only connections from

these IP addresses are accepted.

connect-allow-ip

HTTP-based relay and content gateways

This special "SMSC" is used for HTTP based connections with other gateways and various other relay

services, when direct SMSC is not available.

group = smsc

smsc = http

system-type = kannel

smsc-username = nork

smsc-password = z0rK

port = 13015

send-url = "http://localhost:20022"

Variable

Value

Description

Type of HTTP connection.

’kannel’ is only system currently

supported.

system-type (m)

string

Location to send MT messages.

This URL is expanded by used

system, if need to.

send-url (m)

no-sender

url

Do not add variable sender to

the send-url.

boolean

Do not add variable coding to

the send-url.

no-coding

Represent udh and text as a

numeric string containing the

hexdump. For instance,

text=%2b123 is represented as

text=2b313233.

no-sep

boolean

Chapter 5. Setting up a SMS Gateway

Variable

Value

Description

Port number in which Kannel

listens to (MO) messages from

other gateway

port (m)

port-number

IPs allowed to use this interface.

If not set, "127.0.0.1" (localhost)

is the only host allowed to

connect.

connect-allow-ip

IP-list

Username associated to

connection, if needed. ’kannel’

requires this, and it is the same as

send-sms username at other end.

smsc-username

smsc-password

string

Password for username, if

needed.

Using multiple SMS centers

If you have several SMS center connections (multiple operators or a number of GSM modems) you need

to conﬁgure one smsc group per SMS center (or GSM modem). When doing this, you might want to use

routing systems to rout messages to speciﬁc centers - for example, you have 2 operator SMS centers, and

the other is much faster and cheaper to use.

To set up routing systems, ﬁrst give an unique ID for each SMS center - or if you want to treat multiple

ones completely identical, give them identical ID. Then use preferred-smsc-id and

denied-smsc-id to set up the routing to your taste. See also SMS PUSH settings (’sendsms-user’

groups), below.

Feature checklist

Not all of Kannel’s SMSC drivers support the same set of features. This is because they were written at

different times, and new features are often only added to drivers that the feature author can test.

The table in this section is an attempt to show exactly what features to expect from a driver, and to help

identify areas where drivers need to be updated. Currently most of the entries are marked as "not tested"

because the table is still new.

Table 5-2. SMSC driver features

Featurecimd

emi

emi2

sema ois

at2

http

fake

cimd2

emi_ip

smpp

Can use DLR

Can set DCSa

Can set Alt-DCS

Chapter 5. Setting up a SMS Gateway

Featurecimd

emi

emi2

sema ois

at2

http

fake

cimd2

emi_ip

smpp

Can set Validity

Can set Deferred

Can set PID

Can set RPI

Can send Unicode

Can send 8 bits

Correctly send GSM alphabet

Notes:

a. To use mclass, mwi, coding and compress ﬁelds.

Table 5-3. SMSC driver internal features

Featurecimd

emi

emi2

sema ois

at2

http

fake

cimd2

emi_ip

smpp

Can keep idle connections alive

Can send octet data without UDH

y? y?

Can send octet data with UDH

y? y?

y?a

Can send text messages with UDH

y? y? y?

Can receive octet data without UDH

y?b

Can receive unicode messages

Can receive octet data with UDH

Can receive text messages with UDH

Chapter 5. Setting up a SMS Gateway

Featurecimd

emi

emi2

sema ois

at2

http

fake

cimd2

emi_ip

smpp

Correctly encodes @ when sending

y? y?

Correctly encodes ä when sending

y? y?

Correctly encodes { when sending

Can receive @ in text messages

y? y?

Can receive ä in text messages

y? y?

Can receive { in text messages

Can shut down idle connections

Notes:

a. Does not mark it as octet data

b. However, it looks like the sema driver can’t receive text data.

c. Miscalculates message length

Symbol

Meaning

not yet investigated

driver has this feature, and it has been tested

driver probably has this feature, has not been

tested

driver does not have this feature

driver claims to have this feature but it doesn’t

work

feature is not applicable for this driver

Smsbox conﬁguration

You must deﬁne an ’smsbox’ group into the conﬁguration ﬁle to be able to use SMS Kannel. The

simplest working ’smsbox’ group looks like this:

group = smsbox

bearerbox-host = localhost

...but you would most probably want to deﬁne ’sendsms-port’ to be able to use SMS push.

Chapter 5. Setting up a SMS Gateway

SMSBox inherits from core the following ﬁelds:

smsbox-port

http-proxy-port

http-proxy-host

http-proxy-username

http-proxy-password

http-proxy-exceptions

ssl-certkey-file

Table 5-4. Smsbox Group Variables

Variable

Value

Description

group (m)

smsbox

This is a mandatory variable

The machine in which the

bearerbox is.

bearerbox-host (m)

hostname

Optional smsbox instance

identiﬁer. This is used to identify

an smsbox connected to an

bearerbox for the purpose of

having smsbox speciﬁc routing

inside bearerbox. So if you you

own boxes that do pass messages

into bearerbox for delivery you

may want that answers to those

are routed back to your speciﬁc

smsbox instance, i.e. SMPP or

EMI proxying boxes.

smsbox-id (o)

string

The port in which any sendsms

HTTP requests are done. As with

other ports in Kannel, can be set

as anything desired.

sendsms-port (c)

port-number

If set to true, the sendsms HTTP

interface will use a SSL-enabled

HTTP server with the speciﬁed

ssl-server-cert-ﬁle and

ssl-server-key-ﬁle from the core

group. Defaults to "no".

sendsms-port-ssl (o)

sendsms-url (o)

bool

url

URL locating the sendsms

service. Defaults to

/cgi-bin/sendsms.

URL locating the sendota

service. Defaults to

sendota-url (o)

url

/cgi-bin/sendota.

Chapter 5. Setting up a SMS Gateway

Variable

Value

Description

Only these characters are

allowed in ’to’ ﬁeld when

send-SMS service is requested

via HTTP. Naturally, you should

allow at least 0123456789. The

space character (’ ’) has special

meaning: it is used to separate

multiple phone numbers from

each other in multi-send. To

disable this feature, do not have

it as an accepted character. If this

variable is not set, the default set

"0123456789 +-" is used.

sendsms-chars

global-sender

string

If set, all sendsms originators are

set as these before proceeding.

Note that in a case of most SMS

centers you cannot set the sender

number, but it is automatically

set as the number of SMSC

phone-number

As with the bearerbox ’core’

group. Access-log is used to

store information about MO and

send-sms requests. Can be

named same as the ’main’

access-log (in ’core’ group).

log-file

ﬁlename

log-level

number 0..5

access-log

ﬁlename

Load a list of accepted

destinations of SMS messages. If

a destination of an SMS message

is not in this list, any message

received from the HTTP

interface is rejected. See notes of

phone number format from

numhash.h header ﬁle.

white-list

black-list

URL

As white-list, but SMS messages

to these numbers are

automatically discarded

If set, replaces the SMS message

sent back to user when kannel

could not fetch content. Defaults

to Could not fetch

reply-couldnotfetch

string

content, sorry..

Chapter 5. Setting up a SMS Gateway

Variable

Value

Description

If set, replaces the SMS message

sent back when kannel could not

represent the result as a SMS

message. Defaults to Result

could not be represented

as an SMS message..

reply-couldnotrepresent

reply-requestfailed

string

If set, replaces the SMS message

sent back when kannel could not

contact http service. Defaults to

Request Failed.

If set, replaces the SMS message

sent back when message is

empty. Set to "" to enable empty

messages. Defaults to <Empty

reply from service

reply-emptymessage

string

provider>.

If true, kannel will try to convert

UCS2 messages received to

ISO-8859-1. If it’s possible, the

message will have coding equal

to 7 bits and charset equal to

iso-8859-1.

mo-recode

boolean

If set, speciﬁes how many retries

should be performed for failing

HTTP requests of sms-services.

Defaults to 0, which means no

retries should be performed and

hence no HTTP request queueing

is done.

http-request-retry

integer

If set, speciﬁes how many

seconds should pass within the

HTTP queueing thread for

retrying a failed HTTP request.

Defaults to 10 sec. and is only

obeyed if

http-request-retry is set to

a non-zero value.

http-queue-delay

integer

A typical ’smsbox’ group could be something like this:

group = smsbox

bearerbox-host = localhost

sendsms-port = 13131

sendsms-chars = "0123456789 "

global-sender = 123456

access-log = "kannel.access"

log-file = "smsbox.log"

Chapter 5. Setting up a SMS Gateway

log-level = 0

Smsbox routing inside bearerbox

The communication link between bearerbox and smsbox has been designed for the purpose of

load-balancing via random assignment. Which means, bearerbox holds all smsc connections and passes

inbound message to one of the connected smsboxes. So you have a determined route for outbound

messages, but no determinated route for inbound messages.

The smsbox routing solves this for the inbound direction. In certain scenarios you want that bearerbox to

know to which smsbox instance it should pass messages. I.e. if you implement our own boxes that pass

messages to bearerbox and expect to receive messages deﬁned on certain rules, like receiver number or

smsc-id. This is the case for EMI/UCP and SMPP proxys that can be written easly using smsbox routing

facility.

If you smppbox handles the SMPP speciﬁc communication to your EMSEs, and if an client send a

submit_sm PDU, smppbox would transform the message into Kannel message representation and inject

the message to bearerbox as if it would be an smsbox. As you want to assign your clients shortcuts for

certain networks or route any inbound trafﬁc from a certain smsc link connected to bearerbox, you need

to seperate in the scope of bearerbox where the inbound message will be going to. An example may look

like this:

group = smsbox

...

smsbox-id = mysmsc

...

group = smsbox-route

smsbox-id = mysmsc

shortcuts = "1111;2222;3333"

which means and inbound message with receiver number 1111, 2222 or 3333 will be delivered to the

smsbox instance that has identiﬁed itself via the id "mysmsc" to bearerbox. Using this routing the

smsbox instance (which may be an EMI/UCP or SMPP proxy) is able to send a deliver_sm PDU

smsbox-route inherits from core the following ﬁelds:

Table 5-5. Smsbox-route Group Variables

Variable

Value

Description

group (m)

smsbox-route

This is a mandatory variable

Deﬁnes for which smsbox

instance the routing rules do

apply.

smsbox-id (m)

string

Chapter 5. Setting up a SMS Gateway

Variable

Value

Description

If set, speciﬁes from which

smsc-ids all inbound messages

should be routed to this smsbox

instance. List contains smsc-ids

seperated by semilon (";"). This

rule may be used to pull any

smsc speciﬁc message stream to

an smsbox instance.

smsc-ids

word-list

If set, speciﬁes which receiver

numbers for inbound messages

should be routed to this smsbox

instance. List contains numbers

seperated by semilon (";"). This

rule may be used to pull receiver

number speciﬁc message streams

to an smsbox instance.

shortcuts

number-list

SMS-service conﬁgurations

Now that you have an SMS center connection to send and receive SMS messages you need to deﬁne

services for incoming messages. This is done via ’sms-service’ conﬁguration groups.

These groups deﬁne SMS services in the smsbox, so they are only used by the smsbox. Each service is

recognized from the ﬁrst word in an SMS message and by the number of arguments accepted by the

service conﬁguration (unless catch-all conﬁguration variable is used). By adding a username and

password in the URL in the following manner "http://luser:[email protected]:port/path?query" we

can perform HTTP Basic authentication.

The simplest service group looks like this:

group = sms-service

keyword = www

get-url = "http://%S"

This service grabs any SMS with two words and ’www’ as the ﬁrst word, and then does an HTTP request

to an URL which is taken from the rest of the message. Any result is sent back to the phone (or

requester), but is truncated to the 160 characters that will ﬁt into an SMS message, naturally.

Service group default has a special meaning: if the incoming message is not routed to any other

service, default ’sms-service’ group is used. You should always deﬁne default service.

Service group black-list has a special meaning: if the incoming message is in service’s black-list, this

service is used to reply to user. If unset, message will be discarded.

Table 5-6. SMS-Service Group Variables

Variable

Value

Description

group (m)

sms-service

This is a mandatory variable

Chapter 5. Setting up a SMS Gateway

Variable

Value

Description

Services are identiﬁed by the

ﬁrst word in the SMS Each ‘%s’

in the URL corresponds to one

word in the SMS message.

Words are separated with spaces.

A keyword is matched only if the

number of words in the SMS

message is the same as the

number of ‘%s’ ﬁelds in the

URL. This allows you to

conﬁgure the gateway to use

different URLs for the same

keyword depending on the

number of words the SMS

message contains.

keyword (m)

aliases

name

word

If the service has aliases, they

are listed as a list with each entry

separated with a semicolon (’;’)

word-list

string

Optional name to identify the

service in logs. If unset,

keyword is used.

Requested URL. The url can

include a list of parameters,

which are parsed before the url is

fetched. See below for these

parameters. Also works with

plain ’url’

get-url (c)

post-url (c)

post-xml (c)

file (c)

URL

Requested URL. As above, but

request is done as POST, not

GET. Always matches the

keyword, regardless of pattern

matching. See notes on POST

otherwhere.

URL

Requested URL. As above, but

request is done as XML POST.

Always matches the keyword,

regardless of pattern matching.

See notes on POST otherwhere

and XML Post

URL

File read from a local disc. Use

this variable only if no url is set.

All escape codes (parameters) in

url are supported in ﬁlename.

The last character of the ﬁle

ﬁlename

(usually linefeed) is removed.

Chapter 5. Setting up a SMS Gateway

Variable

Value

Description

Predeﬁned text answer. Only if

there is neither url nor file set.

Escape codes (parameters) are

usable here, too.

text (c)

string

Executes the given shell

command as the current UID of

the running smsbox user and

returns the output to stdout as

reply. Escape codes (parameters)

are usable here, too. BEWARE:

You may harm your system if

you use this sms-service type

without serious caution! Make

sure anyone who is allowed to

use these kind of services is

checked using white/black-list

mechanisms for security reasons.

exec (c)

string

id-list

Accept ONLY SMS messages

arriving from SMSC with

matching ID. a Separate multiple

entries with ’;’. For example, if

accepted-smsc is "RL;SON",

accept messages which originate

from SMSC with ID set as ’RL’

or ’SON’

accepted-smsc

A list of phone number preﬁxes

of the sender number which are

accepted to be received by this

service. b Multiple entries are

separated with semicolon (’;’).

For example, "91;93" selects this

service for these preﬁxes. If

denied-preﬁx is unset, only this

numbers are allowed. If denied is

set, number are allowed if

present in allowed or not in

denied list.

allowed-prefix

denied-prefix

prefix-list

A list of phone number preﬁxes

of the sender number which are

NOT accepted to be sent through

this SMSC.

Chapter 5. Setting up a SMS Gateway

Variable

Value

Description

A list of phone number preﬁxes

of the receiver number which are

accepted to be received by this

service. This may be used to

allow only inbound SMS to

certain shortcut numbers to be

allowed to this service.

allowed-receiver-prefix

prefix-list

A list of phone number preﬁxes

of the receiver number which are

NOT accepted to be sent through

this SMSC.

denied-receiver-prefix

catch-all

prefix-list

Catch keyword regardless of

’%s’ parameters in pattern.

bool

Used only with POST. If set to

true, number of the handset is

set, otherwise not.

send-sender

bool

Used only with POST. Remove

matched keyword from message

text before sending it onward.

strip-keyword

This number is set as sender.

Most SMS centers ignore this,

and use their ﬁxed number

instead. This option overrides all

other sender setting methods.

faked-sender

phone-number

If the message to be sent is

longer than maximum length of

an SMS it will be split into

several parts. max-messages

lets you specify a maximum

number of individual SMS

messages that can be used. If

max-messages is set to 0, no

reply is sent, except for error

messages.

max-messages

number

bool

Request reply can include

special X-Kannel headers but

these are only accepted if this

variable is set to true. See

Extended headers.

accept-x-kannel-headers

Chapter 5. Setting up a SMS Gateway

Variable

Value

Description

If client does not set

Content-Type for reply, it is

normally

application/octet-stream which is

then handled as data in kannel.

This can be forced to be

plain/text to allow backward

compatibility, when data was not

expected.

assume-plain-text

bool

Long messages can be sent as

independent SMS messages with

concatenation = false or

as concatenated messages with

concatenation = true.

Concatenated messages are

reassembled into one long

message by the receiving device.

concatenation

bool

Allowed characters to split the

message into several messages.

So, with "#!" the message is split

from last ’#’ or ’!’, which is

included in the previous part.

split-chars

split-suffix

string

If the message is split into

several ones, this string is

appended to each message except

the last one.

Normally, Kannel sends a

warning to the user if there was

an empty reply from the service

provider. If omit-empty is set to

’true’, Kannel will send nothing

at all in such a case.

omit-empty

bool

If speciﬁed, this string is

automatically added to each

SMS sent with this service. If the

message is split, it is added to

each part.

header

footer

string

As header, but not inserted into

head but appended to end.

Stuff in answer that is cut away,

only things between preﬁx and

sufﬁx is left. Not case sensitive.

Matches the ﬁrst preﬁx and then

the ﬁrst sufﬁx. These are only

used for url type services, and

only if both are speciﬁed.

prefix

string

Chapter 5. Setting up a SMS Gateway

Variable

Value

Description

suffix

string

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 SMSC is rejected, unless a

black-list service is deﬁned.

See notes of phone number

format from numhash.h header

ﬁle.

white-list

URL

As white-list, but SMS messages

from these numbers are

automatically discarded

black-list

Notes:

a. Even if this service is denied, kannel still searches for other service which accepts the message, or

default service.

b. Like in accepted-smsc, kannel still searches for other service which accepts the message. This way

there could be several services with the same keyword and different results.

Table 5-7. Parameters (Escape Codes)

the keyword in the SMS request (i.e., the ﬁrst word

in the SMS message)

next word from the SMS message, starting with

the second one (i.e., the ﬁrst word, the keyword, is

not included); problematic characters for URLs are

encoded (e.g., ’+’ becomes ’%2B’)

same as %s, but ’*’ is converted to ’~’ (useful

when user enters a URL) and URL encoding isn’t

done (all others do URL encode)

words not yet used by %s; e.g., if the message is

"FOO BAR FOOBAR BAZ", and the has been one

%s, %r will mean "FOOBAR BAZ"

all words of the SMS message, including the ﬁrst

one, with spaces squeezed to one

the original SMS message, in a binary form

the time the message was sent, formatted as

"YYYY-MM-DD HH:MM", e.g., "1999-09-21

14:18"

the phone number of the sender of the SMS

message

Chapter 5. Setting up a SMS Gateway

the phone number of the receiver of the SMS

message

like %p, but a leading ‘00’ is replaced with ‘+’

like %P, but a leading ‘00’ is replaced with ‘+’

the smsc-id of the connection that received the

message

the delivery report value

the delivery report SMSC reply, if any

the sendsms-user or sms-service name

message coding: 0 (default, 7 bits), 1 (7 bits), 2 (8

bits) or 3 (unicode)

message charset: for a "normal" message, it will be

"gsm" (coding=1), "binary" (coding=2) or

"UTF16-BE" (coding=3). If the message was

sucessfully recoded from unicode, it will be

"ISO-8859-1"

udh of incoming message

Some sample ’sms-service’ groups:

group = sms-service

keyword = nop

text = "You asked nothing and I did it!"

catch-all = true

group = sms-service

keyword = complex

get-url = "http://host/service?sender=%p&text=%r"

accept-x-kannel-headers = true

max-messages = 3

concatenation = true

group = sms-service

keyword = default

text = "No action specified"

How sms-service interprets the HTTP response

When an sms-service requests a document via HTTP, it will accept one of four types of content types:

text/plain

Blanks are squeezed into one, rest is chopped to ﬁt

an SMS message.

Chapter 5. Setting up a SMS Gateway

text/html

Tags are removed, rest is chopped to ﬁt an SMS

message.

text/vnd.wap.wml

text/xml

Processed like HTML.

Processed as a POST-XML. See XML Post

application/octet-stream

The body will be transmitted as the SMS message,

as 8-bit data. This can be avoided by setting

assume-plain-text variable on for the

SMS-service.

Extended headers

Kannel uses and accepts several X-Kannel headers to be used with SMS-services.

Table 5-8. X-Kannel Headers

SMSPush equivalent

X-Kannel Header

X-Kannel-Username

X-Kannel-Password

X-Kannel-From

X-Kannel-To

username

password

from

text

request body

charset

charset as in Content-Type: text/html;

charset=ISO-8859-1

udh

X-Kannel-UDH

X-Kannel-SMSC

smsc

flash

X-Kannel-Flash (deprecated, see

X-Kannel-MClass

mclass

mwi

X-Kannel-MClass

X-Kannel-MWI

coding

X-Kannel-Coding. If unset, defaults to 1 (7 bits)

if Content-Type is text/plain , text/html

or text/vnd.wap.wml. On

application/octet-stream, defaults to 8 bits

(2). All other Content-Type values are rejected.

validity

deferred

dlrmask

dlrurl

account

pid

X-Kannel-Validity

X-Kannel-Deferred

X-Kannel-DLR-Mask

X-Kannel-DLR-Url

X-Kannel-Account

X-Kannel-PID

alt-dcs

X-Kannel-Alt-DCS

Chapter 5. Setting up a SMS Gateway

Kannel POST

Kannel can do POST if service is contains a post-url="...".

Table 5-9. X-Kannel Post Headers

Parameter (escape code)

equivalent

X-Kannel Header

X-Kannel-From

Notes

%p (from)

Only sent if send

true

%P (to)

X-Kannel-To

X-Kannel-Time

X-Kannel-UDH

%t (time)

%u (udh)

in hex format:

0605041582000

%i (smsc)

X-Kannel-SMSC

- (mclass)

X-Kannel-MClass

X-Kannel-PID

- (pid)

- (alt-dcs)

- (mwi)

X-Kannel-Alt-DCS

X-Kannel-MWI

%c (coding)

- (compress)

- (validity)

- (deferred)

%n (service name)

%a or %r (text)

X-Kannel-Coding

X-Kannel-Compress

X-Kannel-Validity

X-Kannel-Deferred

X-Kannel-Service

request body

1=7 Bits, 2=8 Bit

kannel send all w

unless strip-ke

%C (charset)

present in Content-Type HTTP

Example: Conten

text/plain;

charset=ISO-8

XML Post

Kannel can send and receive XML POST with the following format:

<?xml version="1.0"?>

<!DOCTYPE ...>

<da><number>destination number (to)</number></da>

<oa><number>originating number (from)</number></oa>

<udh>user data header (udh)</udh>

<dcs>

<mclass>mclass</mclass>

<coding>coding</coding>

<compress>compress</compress>

Chapter 5. Setting up a SMS Gateway

<alt-dcs>alt-dcs</alt-dcs>

</dcs>

<dlr-mask>dlr-mask</dlr-mask>

<dlr-url>dlr-url</dlr-url>

</statusrequest>

<from>

<user>username</user>

<username>username</username>

<pass>password</pass>

<password>password</password>

<account>account</account>

</from>

<to>service-name</to>

</submit>

</message>

There could be several da entries for sendsms-user to enable multi-recipient messages. da doesn’t

make sence in sms-service.

Note: Davi: I still have to test binary and unicode <ud> content

udh is the same format as X-Kannel-UDH. Example: <udh>06050415820000</udh>.

On kannel->application, from is the smsc-id that message arrives and to is the service name.

On application->kannel, from contains the credentials ( user/username, pass/password and

account and to corresponds to the smsc-id to submit the message.

user and username are equivalent and only one of them should be used. (same for pass and

password.

When application POST in kannel, as in GET, only user, pass and da are required. Everything else is

optional. (oa could be needed too is there’s no default-sender or forced-sender.

Warning

This is experimental code. XML format could and should change to fully met

IETF’s sms-xml standard (yet in draft) and additional tags needed by kannel

should be pondered.

Chapter 5. Setting up a SMS Gateway

SendSMS-user conﬁgurations

To enable an SMS push, you must set sendsms-port into the ’smsbox’ group and deﬁne one or more

’sendsms-user’ groups. Each of these groups deﬁne one account, which can be used for the SMS push,

via HTTP interface (see below)

Table 5-10. SendSMS-User Group Variables

Variable

Value

Description

group (m)

username (m)

sendsms-user

string

This is a mandatory variable

Name for the user/account.

Password for the user (see

HTTP interface, below)

password (m)

name

string

As in ’sms-service’ groups.

As other deny/allow IP lists, but

for this user (i.e. this user is not

allowed to do the SMS push

HTTP request from other IPs

than allowed ones). If not set,

there is no limitations.

user-deny-ip

user-allow-IP

IP-list

Force SMSC ID as a ’string’

(linked to SMS routing, see

’smsc’ groups)

forced-smsc

default-smsc

string

If no SMSC ID is given with the

send-sms request (see below),

use this one. No idea to use with

forced-smsc.

This number is set as sender if

not set by from get/post

parameter

default-sender

faked-sender

max-messages

concatenation

split-chars

split-suffix

omit-empty

header

phone-number

number

bool

As in ’sms-service’ groups

string

bool

string

footer

string

Chapter 5. Setting up a SMS Gateway

Variable

Value

Description

A list of phone number preﬁxes

which are accepted to be sent

using this username. Multiple

entries are separated with

semicolon (’;’). For example,

"040;050" prevents sending of

any SMS message with preﬁx of

040 or 050 through this SMSC.

If denied-preﬁx is unset, only

this numbers are allowed. If set,

number are allowed if present in

allowed or not in denied list.

allowed-prefix

denied-prefix

prefix-list

A list of phone number preﬁxes

which are NOT accepted to be

sent using this username.

Load a list of accepted

destinations of SMS messages. If

a destination of an SMS message

is not in this list, any message

received from the HTTP

interface is rejected. See notes of

phone number format from

numhash.h header ﬁle.

white-list

URL

As white-list, but SMS messages

from these numbers are

black-list

dlr-url

URL

automatically rejected.

URL to be fetched if a dlrmask

CGI parameter is present.

Some sample ’sendsms-user’ groups:

group = sendsms-user

username = simple

password = elpmis

group = sendsms-user

username = complex

password = 76ftY

user-deny-ip = " . . . "

* * * *

user-allow-ip = "123.234.123.234"

max-messages = 3

concatenation = true

forced-smsc = SOL

The second one is very limited and only allows a user from IP "123.234.123.234". On the other hand, the

user can send a longer message, up to 3 SMSes long, which is sent as concatenated SMS.

Chapter 5. Setting up a SMS Gateway

External delivery report (DLR) storage

Delivery reports are supported by default internaly, which means all DLRs are stored in the memory of

the bearerbox process. This is problematic if bearerbox crashes or you take the process down in a

controlled way, but there are still DLRs open. Therefore you may use external DLR storage places, i.e. a

MySQL database.

Following are the supported DLR storage types and how to use them:

Internal DLR storage

This is the default way in handling DLRs and does not require any special conﬁguration. In order to

conﬁgure bearerbox to use internal DLR storage use dlr-storage = internal in the core group.

MySQL DLR storage

To store DLR information into a MySQL database you may use the dlr-storage = mysql

conﬁguration directive in the core group.

In addition to that you must have a dlr-db group deﬁned that speciﬁes the table ﬁeld names that are

used to the DLR attributes and a mysql-connection group that deﬁnes the connection to the MySQL

server itself.

Here is the example conﬁguration from doc/examples/dlr-mysql.conf:

group = mysql-connection

id = mydlr

host = localhost

mysql-username = foo

mysql-password = bar

database = dlr

group = dlr-db

id = mydlr

table = dlr

field-smsc = smsc

field-timestamp = ts

field-destination = destination

field-service = service

field-url = url

field-mask = mask

field-status = status

field-boxc-id = boxc

LibSDB DLR storage

To store DLR information into a LibSDB ressource (which is an abstraction of a real database) you may

use the dlr-storage = sdb conﬁguration directive in the core group.

Chapter 5. Setting up a SMS Gateway

In addition to that you must have a dlr-db group deﬁned that speciﬁes the table ﬁeld names that are

used to the DLR attributes and a sdb-connection group that deﬁnes the LibSDB ressource itself.

Here is the example conﬁguration from doc/examples/dlr-sdb.conf using a MySQL ressource:

group = sdb-connection

id = mydlr

url = "mysql:host=localhost:db=dlr:uid=foo:pwd=bar"

group = dlr-db

id = mydlr

table = dlr

field-smsc = smsc

field-timestamp = ts

field-destination = destination

field-service = service

field-url = url

field-mask = mask

field-status = status

field-boxc-id = boxc

Beware that you have the DB support build in your LibSDB installation when trying to use a speciﬁc DB

type within the URL.

DLR database ﬁeld conﬁguration

For external database storage of DLR information in relational database management systems (RDMS)

you will have tospecify which table ﬁeld are used to represend the stored data. This is done via the

dlr-db group as follows:

Table 5-11. DLR Database Field Conﬁguration Group Variables

Variable

Value

Description

group

dlr-db

This is a mandatory variable

An id to identify which external

connection should be used for

DLR storage. Any string is

acceptable, but semicolon ’;’

may cause problems, so avoid it

and any other special

id (m)

string

non-alphabet characters.

The name of the table that is

used to store the DLR

information.

table (m)

string

The table ﬁeld that is used for

the smsc data.

field-smsc (m)

Chapter 5. Setting up a SMS Gateway

Variable

Value

string

Description

The table ﬁeld that is used for

the timestamp data.

field-timestamp (m)

field-destination (m)

field-service (m)

The table ﬁeld that is used for

the destination number data.

The table ﬁeld that is used for

the service username data.

The table ﬁeld that is used for

the DLR URL which is triggered

when the DLR for this message

arrives from the SMSC.

field-url (m)

string

The table ﬁeld that is used for

the DLR mask that has been set

for a message.

field-mask (m)

field-status (m)

The table ﬁeld that is used to

reﬂect the status of the DLR for a

speciﬁc message.

The table ﬁeld that is used to

store the smsbox connection id

that has passed the message for

delivery. This is required in cases

you want to garantee that DLR

messages are routed back to the

same smsbox conn instance. This

is done via the smsbox routing. If

you don’t use smsbox routing

simply add this ﬁeld to your

database table and keep it empty.

field-boxc-id (m)

string

A sample ’dlr-db’ group:

group = dlr-db

id = dlr-db

table = dlr

field-smsc = smsc

field-timestamp = ts

field-destination = destination

field-service = service

field-url = url

field-mask = mask

field-status = status

Beware that all variables in this group are mandatory, so you have to specify all ﬁelds to enable

bearerbox to know how to store and retrieve the DLR information from the external storage spaces.

Chapter 5. Setting up a SMS Gateway

MySQL connection conﬁguration

For several reasons external storage may be required to handle dynamical issues, i.e. DLRs, sms-service,

sendsms-user, ota-setting, ota-bookmark deﬁnitions and so on. To deﬁne a MySQL database connection

you simple need to specify a mysql-connection group as follows:

Table 5-12. MySQL Connection Group Variables

Variable

Value

Description

group

mysql-connection

This is a mandatory variable

An optional name or id to

identify this MySQL connection

for internal reference with other

MySQL related conﬁguration

groups. Any string is acceptable,

but semicolon ’;’ may cause

problems, so avoid it and any

other special non-alphabet

characters.

id (m)

string

Hostname or IP of a server

running a MySQL database to

connect to.

host (m)

hostname or IP

username

password

string

User name for connecting to

MySQL database.

mysql-username (m)

mysql-password (m)

database (m)

Password for connecting to

MySQL database.

Name of database in MySQL

database server to connect to.

A sample ’mysql-connection’ group:

group = mysql-connection

id = dlr-db

host = localhost

mysql-username = foo

mysql-password = bar

database = dlr

In case you use different MySQL connections for several storage issues, i.e. one for DLR and another

different one for sms-service you may use the include conﬁguration statement to extract the MySQL

related conﬁguration groups to a seperate mysql.conf ﬁle.

Over-The-Air conﬁgurations

To enable Over-The-Air conﬁguration of phones or other client devices that support the protocol you

need to conﬁgure a sendsms-user.ota-setting group is not necessary, you can send settings to the

Chapter 5. Setting up a SMS Gateway

phone as a XML document, but this method is perhaps more suitable for continous provisioning.

If you want to send multiple OTA conﬁgurations through the smsbox and you do not want to send XML

documents, you will have to declare a ota-id string to the different ota-setting groups.

Table 5-13. OTA Setting Group Variables

Variable

Value

Description

group

ota-setting

This is a mandatory variable

An optional name or id for the

ota-setting. Any string is

acceptable, but semicolon ’;’

may cause problems, so avoid it

and any other special

ota-id

string

non-alphabet characters.

The address of the HTTP server

for your WAP services, i.e.

location

service

URL

http://wap.company.com

string

Description of the service

IP address of your WAP gateway

ipaddress

phonenumber

speed

Phone number used to establish

the PPP connection

phone-number

number

string

Connection speed: 9600 or

14400. Defaults to 9600.

Bearer type: data or sms.

Defaults to data.

bearer

Call type: isdn or analog.

Defaults to isdn.

calltype

Connection type: cont or temp.

Cont uses TCP port 9201 and

Temp uses UDP port 9200.

Defaults to cont.

connection

pppsecurity

string

Enable CHAP authentication if

set to on, PAP otherwise

on or off

normal or secure. Indicates

wether WTLS should be used or

not. Defaults to normal.

authentication

string

secret

A sample ’ota-setting’ group:

group = ota-setting

location = http://wap.company.com

service = "Our company’s WAP site"

ipaddress = 10.11.12.13

Chapter 5. Setting up a SMS Gateway

phonenumber = 013456789

bearer = data

calltype = analog

connection = cont

pppsecurity = off

authentication = normal

secret = thepasswd

And a ’sendsms-user’ to use with it. With concatenation enabled:

group = sendsms-user

username = otauser

password = foo

max-messages = 2

concatenation = 1

Table 5-14. OTA Bookmark Group Variables

Variable

Value

Description

group

ota-bookmark

This is a mandatory variable

An optional name or id for the

ota-bookmark. Any string is

acceptable, but semicolon ’;’

may cause problems, so avoid it

and any other special

ota-id

string

non-alphabet characters.

The address of the HTTP server

for your WAP services, i.e.

url

URL

http://wap.company.com

name

string

Description of the service

A sample ’ota-bookmark’ group:

group = ota-bookmark

ota-id = wap-link

url = "http://wap.company.com"

service = "Our company’s WAP site"

And a ’sendsms-user’ to use with it, with the same conditions as for the ’ota-setting’ group.

Setting up more complex services

The basic service system is very limited - it can only answer to original requester and it cannot send UDH

data, for example. This chapter explains some more sophisticated and complex SMS service setups.

Chapter 5. Setting up a SMS Gateway

Redirected replies

The basic service system always sends the answer back to original requester, but sometimes the content

server needs to send something to other terminals or delay the answer. To create such systems, an SMS

push is used.

The idea is to get the initial request, but then send no reply. Instead, the reply (if any) is sent via HTTP

sendsms-interface as SMS Push. This way the service application has full control of the return content,

and can do all needed formatting beforehand.

Note that when no reply is wanted, remember to set the variable max-messages to zero (0) so that no

reply is sent, unless an error occurs. Simple sample:

group = sms-service

keyword = talk

get-url = "http://my.applet.machine/Servlet/talk?sender=%p&text=%r"

max-messages = 0

Setting up operator speciﬁc services

Those running Kannel with several SMS centers might need to deﬁne services according to the relying

SMS center. To achieve this, ﬁrst you need to give an ID name for SMS center connections (see above).

Then use the accepted-smsc variable to deﬁne which messages can use that service.

group = sms-service

keyword = weather

accepted-smsc = SOL

get-url = "http://my.applet.machine/Servlet/weather?sender=%p&operator=SOL&text=%r"

Setting up multi-operator Kannel

Sometimes there is a need for Kannel to listen to two (or more) distinct SMS centers, and messages must

be routed to services according to where they came from, and replies likewise must return to same

SMSC. This is done via smsc-id magic. Here is a shortened sample conﬁguration, which handles to

distinct SMS servers and services:

group = smsc

smsc-id = A

denied-smsc-id = B

...

group = smsc

smsc-id = B

denied-smsc-id = A

...

group = sms-service

accepted-smsc = A

get-url = "..."

group = sms-service

Chapter 5. Setting up a SMS Gateway

accepted-smsc = B

get-url = "..."

As can be seen, the smsc-id is used to identify the SMS center from which the message came. Then, the

denied-smsc-id variable is used to prevent messages originally from the other SMS center from being

sent through the other one. Finally ’sms-service’ groups are deﬁned with accepted-smsc so that they

only accept messages from certain SMS center.

If you want to use SMS push services, requesters should then set the smsc request parameter, or

’sendsms-user’ groups should be deﬁned like this:

group = sendsms-user

username = operator_A

password = foo

forced-smsc = A

group = sendsms-user

username = operator_B

password = bar

forced-smsc = B

Note that if your SMS centers do not set the sender phone number but rely on number transmitted, you

should set faked-sender to all ’sendsms-user’ groups.

Running SMS gateway

Using the HTTP interface to send SMS messages

After you have conﬁgured Kannel to allow the sendsms service, you can send SMS messages via HTTP,

e.g., using a WWW browser. The URL looks something like this:

http://smsbox.host.name:13013/cgi-bin/sendsms?

username=foo&password=bar&to=0123456&text=Hello+world

Thus, technically, you make an HTTP GET request. This means that all the information is stuffed into

the URL. If you want to use this often via a browser, you probably want to make an HTML form for this.

Table 5-15. SMS Push (send-sms) CGI Variables

Username or account name.

Must be username of the one

’sendsms-user’ group in the

Kannel conﬁguration, or results

username (or user)

string

in ’Authorization failed’ reply.

Chapter 5. Setting up a SMS Gateway

Password associated with given

username. Must match

corresponding ﬁeld in the

’sendsms-user’ group of the

Kannel conﬁguration, or

’Authorization failed’ is

returned.

password (or pass)

string

Phone number of the sender.

This ﬁeld is usually overridden

by the SMS Center, or it can be

overridden by faked-sender

variable in the sendsms-user

group. If this variable is not set,

smsbox global-sender is

used.

from

string

Phone number of the receiver.

To send to multiple receivers,

separate each entry with space (’

’, ’+’ url-encoded) - but note that

this can be deactivated via

sendsms-chars in the

phone number list

’smsbox’ group.

Contents of the message, URL

encoded as necessary. The

content can be more than 160

characters, but then

sendsms-user group must have

max-messages set more than 1.

text

string

Charset of text message. Used to

convert to a format suitable for 7

bits or to UCS2. Defaults to

ISO-8859-1 if coding is 7bits and

UTF16BE if coding is UCS2.

charset

udh

string

Optional User Data Header

(UDH) part of the message. Must

be URL encoded.

Chapter 5. Setting up a SMS Gateway

Optional virtual smsc-id from

which the message is supposed

to have arrived. This is used for

routing purposes, if any denied

or preferred SMS centers are set

up in SMS center conﬁguration.

This variable can be overridden

with a forced-smsc

conﬁguration variable. Likewise,

the default-smsc variable can

be used to set the SMSC if it is

not set otherwise.

smsc

string

number

flash

Deprecated. See mclass.

Optional. Sets the Message

Class in DCS Field. Accepts

values between 1 and 4, for

Message Class 0 to 3, A value of

1 sends the message directly to

display. mclass=2 sends to

mobile, 3 do SIM and 4 to SIM

Toolkit.

mclass

number

Optional. Sets Message Waiting

Indicator bits in DCS ﬁeld. If

given, the message will be

encoded as a Message Waiting

Indicator. The accepted values

are 1,2,3 and 4 for activating the

voice, fax, email and other

indicator, or 5,6,7,8 for

deactivating, respectivly. This

option excludes the flash

option. a

mwi

number

Optional. Sets the coding

scheme bits in DCS ﬁeld.

Accepts values 1 to 3, for 7bit,

8bit or UCS2. If unset, defaults

to 7 bits unless a udh is deﬁned,

which sets coding to 8bits.

coding

Chapter 5. Setting up a SMS Gateway

Optional. If given, kannel will

inform SMS Center that it should

only try to send the message for

this many minutes. If the

destination mobile is off other

situation that it cannot receive

the sms, the smsc discards the

message. Note: you must have

your kannel box time

syncronized with the SMS

Center.

validity

number (minutes)

Optional. If given, the SMS

center will postpone the message

to be delivered at now plus this

many minutes. Note: you must

have your kannel box time

syncronized with the SMS

Center.

deferred

number (minutes)

Optional. Request for delivery

reports with the state of the sent

message. The value is a bit mask

composed of: 1: Delivered to

phone, 2: Non-Delivered to

Phone, 4: Queued on SMSC, 8:

Delivered to SMSC, 16:

Non-Delivered to SMSC. Must

set dlr-url on sendsms-user

group or use the dlrurl CGI

variable.

dlrmask

dlrurl

number (bit mask)

string (url)

Optional. If dlrmask is given,

this is the url to be fetched.

(Must be urlencoded)

Optional. Sets the PID value.

(See ETSI Documentation). Ex:

SIM Toolkit messages would use

something like

&pid=127&coding=2&alt-dcs=1&mclass=3

pid

byte

Optional. If unset, kannel uses

the alt-dcs deﬁned on smsc

conﬁguration, or 0X per default.

If equals to 1, uses FX. If equals

to 2, force 0X.

alt-dcs

rpi

number

Optional. Sets the Return Path

Indicator (RPI) value. (See ETSI

Documentation).

Chapter 5. Setting up a SMS Gateway

Account name or number to

carry forward for billing

purposes. This ﬁeld is logged as

ACT in the log ﬁle so it allows

you to do some accounting on it

if your front end uses the same

username for all services but

wants to distinguish them in the

log. In the case of a HTTP

SMSC type the account name is

prepended with the servicename

(username) and a colon (:) and

forwarded to the next insta ce of

kannel. This allows hierarchical

accounting.

account

string

Notes:

a. To set number of messages, use mwi=[1-4]&coding=1&udh=%04%01%02%<XX>%<YY>, where

YY are the number of messages, in HEX, and XX are mwi-1 plus 0xC0 if text ﬁeld is not empty.

Using the HTTP interface to send OTA conﬁguration

messages

OTA messages can be sent to mobile phones or devices to auto-conﬁgure the settings for WAP. They are

actually complex SMS messages with UDH and sent as concatenated messages if too long (and compiled

if necessary).

You may either pass an HTTP request as GET method or POST method to the HTTP interface.

If you want to send a conﬁguration that is deﬁned within Kannel’s conﬁguration ﬁle itself you have to

pass a valid ota-id value otherwise the content of the request will be compiled to as OTA message.

GET method for the OTA HTTP interface

An example URL (OTA conﬁguration deﬁned in the Kannel conﬁguration ﬁle):

http://smsbox.host.name:13013/cgi-bin/sendota?

otaid=myconfig&username=foo&password=bar&to=0123456

URL containing XML document looks like this (you must URL encode it before sending it over HTTP):

http://smsbox.host.name:13013/cgi-bin/sendota?

username=foo&password=bar&to=0123456&

text=MyURLEncodedXMLdocument&type=settings

Chapter 5. Setting up a SMS Gateway

You can send either settings or bookmark, set CGI variable type accordingly. Default for this variable is

settings.

Here is an example XML document (this one contains CSD settings for logging in to a mobile service;

note that you must store DTD locally):

<?xml version="1.0"?>

<!DOCTYPE CHARACTERISTIC-LIST SYSTEM "file://gw/settings.dtd">

<CHARACTERISTIC-LIST>

</CHARACTERISTIC>

<CHARACTERISTIC TYPE="URL"

VALUE="http://wap.company.com/"/>

</CHARACTERISTIC>

</CHARACTERISTIC-LIST>

A bookmark document looks like this:

<?xml version="1.0"?>

<!DOCTYPE CHARACTERISTIC_LIST SYSTEM "file://gw/settings.dtd">

<CHARACTERISTIC-LIST>

</CHARACTERISTIC>

</CHARACTERISTIC-LIST>

Document type deﬁnition (DTD) for these documents is not available , from Internet, you must supply it

as a ﬁle. Kannel gw directory contains an example, settings.dtd.

Table 5-16. OTA CGI Variables

Chapter 5. Setting up a SMS Gateway

Name or ID of the ’ota-setting’

group in Kannel conﬁguration

that should be sent to the phone.

This variable is optional. If it is

not given the ﬁrst ’ota-setting’

group is sent. This is unnecessary

when a XML document is

otaid

string

sended to the phone.

Username of the ’sendsms-user’

group in Kannel conﬁguration,

that has been conﬁgured to send

OTA messages.

username

Password associated with given

username. Must match

corresponding ﬁeld in

’sendsms-user’ group in Kannel

conﬁguration, or ’Authorization

failed’ is returned.

password

string

number

Number of the phone that is to

receive the OTA conﬁguration

message.

Phone number of the sender.

This ﬁeld is usually overridden

by the SMS Center, or it can be

overridden by faked-sender

variable in the sendsms-user

group. If this variable is not set,

smsbox global-sender is used.

from

string

Optional virtual smsc-id from

which the message is supposed

to have arrived. This is used for

routing purposes, if any denied

or preferred SMS centers are set

up in SMS center conﬁguration.

This variable can be overridden

with a forced-smsc

conﬁguration variable. Likewise,

the default-smsc variable can

be used to set the SMSC if it is

not set otherwise.

smsc

text

type

string

An URL encoded XML

document, containing either

settings or bookmarks.

XML document

string

Type of the XML document,

either "settings" or "bookmarks".

Default is "settings".

Chapter 6. Setting up a SMS&WAP gateway

This chapter tells you how to set Kannel up as a combined WAP and SMS gateway.

SMS&WAP gateway conﬁguration

Conﬁguration is done as explained in previous chapters, you simply have to include all the data from

both chapters into the conﬁguration ﬁle.

Running SMS&WAP gateway

There are no special tricks to this, just launch both the smsbox and the wapbox in addition to the

bearerbox, using multiple hosts if needed.

Chapter 7. Setting up Push Proxy Gateway

This chapter explains how to set up a push proxy gateway (PPG). An example conﬁguration ﬁle are

given. A working push proxy gateway is described.

Conﬁguring ppg core group, for push initiator (PI)

interface

PPG conﬁguration group deﬁnes gateway’s service interface. Conﬁguring a PPG working with a trusted

PI is easiest. Actually, you need no conﬁguration at all: in this case a PPG with default values will be set

up. Do not rely on this, default values may change. For PPG core conﬁguration variables, see table 7.1.

An example of a core conﬁguration for PPG working only with speciﬁc addresses follows. Note that

ppg-deny-ip-list is not actually necessary, but does make conﬁguring simpler: IPs here are always denied,

even when they are mentioned in the allowed IPs list.

Ppg-url is a simple stamp, used for routing requests to the right service. You can change this stamp by

setting push-url conﬁguration variable.

group = ppg

ppg-url = /wappush

ppg-port = 8080

concurrent-pushes = 100

users = 1024

ppg-allow-ip = 194.100.32.125;127.0.0.1

ppg-deny-ip = 194.100.32.89;194.100.32.103

trusted-pi = false

Table 7-1. PPG core group conﬁguration variables

Variable

group

Value

ppg

Description

Mandatory value. Tells that we

are conﬁguring the PPG group.

The port PPG is listening at.

Default 8080.

ppg-port

number

Mandatory value for PPG

HTTPS support. The port at

which PPG listens for HTTPS

requests. There are no defaults;

you must set the value separately.

ppg-ssl-port (o)

number

string

Mandatory value for PPG

HTTPS support. The ﬁle

containing server’s ssl certiﬁcate.

ssl-server-cert-file

Chapter 7. Setting up Push Proxy Gateway

Variable

Value

Description

Mandatory value for PPG

HTTPS support. The ﬁle

containing server’s ssl private

key.

ssl-server-key-file

ppg-url

string

url

URL locating PPG services.

Default /wappush .

Sender phone number required

by some protocols.

global-sender

string

Number of concurrent pushes

expected. Note that PPG does

work even value is too low; it

will only be slower. Default 100.

concurrent-pushes

number

Number of actually conﬁgured

user accounts. Note that PPG

does work even value is too low;

it will only be slower. Default

1024.

users

If true, PI does authentication

for PPG. Obviously, both of them

must reside inside same ﬁrewall.

Default true. If this variable is

true, all security variables are

ignored (even though they may

be present).

trusted-pi

ppg-deny-ip

boolean

ip-list

PPG will not accept pushes from

these IPs. Wildcards are allowed.

If this attribute is missing, no IP

is denied by this list .

PPG will accept pushes from

these, and only these, IPs.

Wildcards are allowed. Adding

this list means that IPs not

mentioned are denied, too.

ppg-allow-ip

default-smsc

ip-list

string

If no SMSC ID is given with the

wappush HTTP request (see

below), use this one as default

route for all push messages.

Conﬁguring PPG user group variables

In addition of pi lists similar to the core group, ppg conﬁguration spesiﬁc to a certain user contains

variables used for authentication and enforcing restrictions to phone numbers pi may contact. All

Chapter 7. Setting up Push Proxy Gateway

variables are elaborated in table 7.2.

As an example, let us see how to conﬁgure a ppg user (a pi, named here ’picom’) allowed to send pushes

only from a speciﬁed ip.

group = wap-push-user

wap-push-user = picom

ppg-username = foo

ppg-password = bar

allow-ip = 62.254.217.163

It goes without saying that in real systems you must use more complex passwords than bar.

Table 7-2. PPG user group conﬁguration variables

Variable

Value

Description

Mandatory value. Tells that we

are conﬁguring the users group.

group

wap-push-user

(More) human readable name of

an user.

wap-push-user

ppg-username

ppg-password

string

Username for this user.

Password for this user.

Phone number preﬁxes allowed

in pushes coming from this pi.

These preﬁxes must conform

international phone number

format.

allowed-prefix

denied-prefix

white-list

number-list

url

Phone number preﬁxes denied in

pushes coming from this pi.

These preﬁxes must conform

international phone number

format.

Deﬁnes an url wherefrom the

whitelist can be fetched. White

list itself contains list of phone

numbers accepting pushes from

this pi.

Deﬁnes an url wherefrom the

blacklist can be fetched.

Blacklist itself contains list of

phone number not accepting

pushes from this pi.

black-list

allow-ip

url

Deﬁnes ips wherefrom this pi

can do pushes. Adding this list

means that ips not mentioned are

denied.

ip-list

Chapter 7. Setting up Push Proxy Gateway

Variable

Value

Description

Deﬁnes ips wherefrom this pi

cannot do pushes. Ips not

mentioned in either list are

denied, too.

deny-ip

ip-list

If no SMSC ID is given with the

wappush HTTP request (see

below), use this one as default

route for this speciﬁc push user.

default-smsc

forced-smsc

string

Allow only routing to a deﬁned

SMSC ID for this speciﬁc push

user.

Finishing ppg conﬁguration

PPG uses SMS for sending SI to the phone and an IP bearer to fetch content speciﬁed by it (see chapter

Overview of WAP Push). This means both wapbox and bearer smsc connections are in use. So your push

proxy gateway conﬁguration ﬁle must contain groups core, wapbox, smsc and smsbox. These are

conﬁgured normal way, only smsc group may have push-speciﬁc variables. Note that following

conﬁgurations are only an example, you may need more complex ones.

Bearerbox setup does not require any new variables:

group = core

admin-port = 13000

smsbox-port = 13001

wapbox-port = 13002

admin-password = b

wdp-interface-name = " "

log-file = "filename"

log-level = 1

box-deny-ip = " . . . "

* * * *

box-allow-ip = "127.0.0.1"

unified-prefix = "00358,0"

You mut set up wapbox, for pulling (fetching) the wap data, and of course starting the push itself. No

new variables here, either.

group = wapbox

bearerbox-host = localhost

log-file = "filename"

log-level = 0

syslog-level = none

To set up smsc connections, for pushing SI or SL over SMS. Here HTTP SMSC is used as an example.

Variables no-sender and no-coding simplify HTTP request generated by Kannel. Send-url speciﬁes

content gateway, or sendsms service.

group = smsc

Chapter 7. Setting up Push Proxy Gateway

smsc = http

smsc-id = HTTP

port = 10000

system-type = kannel

smsc-username = foo

smsc-password = bar

no-sender = true

no-coding = true

send-url = http://host:port/path

To set up smsbox. This group will eventually disappear, use here only necessary conﬁguration variables.

group = smsbox

bearerbox-host = localhost

Kannel sources contain a sample push conﬁguration ﬁle gw/pushkannel.conf.

Running a push proxy gateway

Push proxy gateway is started by simply typing, using separate windows:

gw/bearerbox [conffile]

gw/wapbox [conffile]

You can, of course, use more complex command line options.

An example using HTTP SMSC

An easy way to test and implement push services is to put ppg in the front of an existing sendsms service

capable to send SMS data messages and to to understand HTTP requests generated by HTTP SMSC.

(See next chapter.) Then you need only conﬁgure SMSC conﬁguration send-url to point to sendsms

service.

An example push (tokenised SI) document

HTTP SMSC generates a HTTP get request when it get a sendmessage event, expressed in unicode. The

content gateway, or the sendsms service must, of course, understand this URL. So here is an example, cgi

variable text contains the url escaped form of a SI document. It is usable for testing prototype phones.

http://matrix:8080/phplib/kannelgw.php?user= deleted &

pass= deleted =to=%2B358408676001&text=3D%02%06%17%AE%96localhost

%3A8080%00%AF%80%8D%CF%B4%80%02%05j%00E%C6%0C%03wap.iobox.fi%00%11%03

1%40wiral.com%00%07%0A%C3%07%19%99%06%25%15%23%15%10%C3%04+%02%060%01

%03Want+to+test+a+fetch%3F%00%01%01&udh=%06%05%04%0B%84%23%F0

Chapter 7. Setting up Push Proxy Gateway

Default network and bearer used by push proxy gateway

If network and bearer attributes of the pap control document are missing or set any, Kannel uses address

type for routing purposes: if the address type is a phone number (TYPE=PLMN), network defaults to

GSM and bearer to SMS; if it is a IP-address (TYPE=IPv4), network defaults to GSM and bearer to

CSD. So following minimal pap document works:

<?xml version="1.0"?>

<!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP//EN"

"http://www.wapforum.org/DTD/pap_1.0.dtd">

<pap>

<push-message push-id="[email protected]">

</push-message>

</pap>

Chapter 8. Using SSL for HTTP

This chapter explains how you can use SSL to ensure secure HTTP communication on both, client and

server side.

Beware that the gateway, is acting in both roles of the HTTP model:

1. as HTTP client, i.e. for requesting URLs while acting as WAP gateway and while fetching

information for the SMS services.

2. as HTTP server, i.e. for the administration HTTP interface, the PPG and for the sendsms HTTP

interface.

That is why you can specify seperate certiﬁcation ﬁles within the core group to be used for the HTTP

sides.

You can use one or both sides of the SSL support. There is no mandatory to use both if only one is

desired.

Using SSL client support

To use the client support please use the following conﬁguration directive within the core group

group = core

...

ssl-client-certkey-file = "filename"

Now you are able to use https:// scheme URLs within your WML decks and SMS services.

Using SSL server support for the administration HTTP

interface

To use the SSL-enabled HTTP server please use the following conﬁguration directive within the core

group

group = core

...

admin-port-ssl = true

...

ssl-server-cert-file = "filename"

ssl-server-key-file = "filenane"

Chapter 8. Using SSL for HTTP

Using SSL server support for the sendsms HTTP

interface

To use the SSL-enabled HTTP server please use the following conﬁguration directive within the core and

smsbox groups

group = core

...

ssl-server-cert-file = "filename"

ssl-server-key-file = "filenane"

group = smsbox

...

sendsms-port-ssl = true

Using SSL server support for PPG HTTPS interface

If you want use PAP over HTTPS, (it is, a https scheme) add following directives to the ppg core group:

group = ppg

...

ppg-ssl-port = 8090

ssl-server-cert-file = "/home/aarno/kannelcvs/gateway/gw/cert1.pem"

ssl-server-key-file = "/home/aarno/kannelcvs/gateway/gw/key1.pem"

PPG uses a separate port for HTTPS trafﬁc, so so you must deﬁne it. This means that you can use both

HTTP and HTTPS, when needed.

Chapter 9. Delivery Reports

This chapter explains how to set up kannel to deliver delivery reports.

Delivery reports are a method to tell your system if the message has arrived on the destination phone.

There are different things which can happen to a message on the way to the phone which are:

• Message gets rejected by the SMSC (unknown subscriber, invalid destination number etc).

• Message gets accepted by the SMSC but the phone rejects the message.

• Message gets accepted by the SMSC but the phone is off or out of reach. The message gets buffered.

• Message gets successfully delivered.

When you deliver SMS to Kannel you have to indicate what kind of delivery report messages you would

like to receive back from the system. The delivery report types currrently implemented are:

• 1: delivery success

• 2: delivery failure

• 4: message buffered

• 8: smsc submit

• 16: smsc reject

If you want multiple report types, you simply add the values togeter. For example if you want to get

delivery success and/or failure you set the dlrmask value to 1+2. and so on. If you specify dlrmask on the

URL you pass on to kannel you also need to specify dlrurl. dlrurlshould contain the URL to which kannel

should place a HTTP requests once the delivery report is ready to be delivered back to your system.

An example transaction would work as following.

• 1. you send a message using dlrmaks=7 and dlrurl=www.xyz.com/cgi/dlr.php?type=%d

• 2. Kannel forwards the message to the SMSC and keeps track of the message

• 3. The SMSC can not reach the phone and thus returns a buffered message

• 4. Kannel calls http://www.xyz.com/cgi/dlr.php?type=4 to indicate the message being buffered

• 5. The phone is switched on and the SMS gets delivered from the SMSC. The SMSC reports this to

Kannel

• 4. Kannel calls http://www.xyz.com/cgi/dlr.php?type=2 to indicate the ﬁnal success

Depending on the SMSC type not all type of messages are supported. For example a CIMD SMSC does

not support buffered messages. Also some SMSC drivers have not implemented all DLR types.

Chapter 10. Getting help and reporting bugs

This chapter explains where to ﬁnd help with problems related to the gateway, and the preferred

procedure for reporting bugs and sending corrections to them.

The Kannel development mailing list is [email protected]. To subscribe, send mail to

[email protected] (mailto:[email protected]). This is currently the best

location for asking help and reporting bugs. Please include conﬁguration ﬁle and version number.

Appendix A. Using the fake WAP sender

This appendix explains how to use the fake WAP sender to test the gateway.

Appendix B. Using the fake SMS center

Fakesmsc is a simple testing tool to test out Kannel and its SMS services. It cannot be used to send

messages to mobile terminals, it is just a simulated SMS center with no connection to real terminals.

Setting up fakesmsc

This section sums up needed steps to set up system for fakesmsc use.

Compiling fakesmsc

The fake SMS center should compile at the same time as main Kannel compiles. The outcoming binary,

fakesmsc, is in test directory. The source code is quite simple and trivial, and is easily edited.

Conﬁguring Kannel

To use fakesmsc to test out Kannel, you have to add it to main conﬁguration ﬁle (see above). The

simplest form for this conﬁguration group is like this:

group = smsc

smsc = fake

port = 10000

The fakesmsc conﬁguration group accepts all common ’smsc’ conﬁguration group variables, like

smsc-id, preferred-smsc-id or denied-smsc-id, which can be used to test out routing systems

and diverted services, before setting up real SMS center connections. If you include a fakesmsc group

when bearerbox is connected to real SMS centers, you should add the connect-allow-ip variable to

prevent unauthorized use.

To set up multiple fakesmsc’es, just add new groups. Remember to put a different port number to each

one.

Running Kannel with fakesmsc connections

After conﬁguring Kannel, you can start testing it. The bearerbox will listen for fakesmsc client

connections to the port(s) speciﬁed in the conﬁguration ﬁle.

Starting fake SMS center

Each fakesmsc is started from command line, with all sent messages after command name. If any options

are used (see below), they are put between the command and the messages. The usage is as follows:

test/fakesmsc [options] <message1> [message2 ...]

Appendix B. Using the fake SMS center

Options and messages are explained below, but as a quick example, a typical startup can go like this:

test/fakesmsc -i 0.1 -m 100 "100 200 text nop" "100 300 text echo this"

This tells fakesmsc to connect to bearerbox at localhost:10000 (default) and send a hundred messages

with an interval of 0.1 seconds. Each message is from number 100, and is either to number 200 with

message ’nop’ or to 300 with message ’echo this’.

Messages received from bearerbox are shown in the same format (described below).

Fake messages

Each message consists of four or ﬁve parts: sender number, receiver number, type, udh (if present) and

main message itself. Sender and receiver numbers do not mean anything except for log ﬁles and

number-based routing in Kannel.

The parts of a message are separated with spaces. As each message is taken as one argument, it must be

put in quotation marks.

Message type must be one of the following: "text", "data" and "udh". Here’s an example of using each:

test/fakesmsc -i 0.01 -v 1 -m 1000 "100 300 text echo this message"

test/fakesmsc -i 0.01 -m 1000 "100 300 data echo+these+chars%03%04%7f"

test/fakesmsc -m 1 "100 500 udh %0eudh+stuff+here main+message"

For "text", the rest of the argument is taken as the literal message. For "data", the next part must be the

urlcoded version of the message. Space is coded as ’+’. For "udh", the next 2 parts are the UDH and

main message. Both must be in urlcoded form.

If multiple messages are given, fakesmsc randomly chooses one for each sending.

Fakesmsc command line options

Fake SMS center can be started with various optional command line arguments.

Table B-1. Fakesmsc command line options

Switch

-H

Value

host

Description

Use host host instead of default

localhost.

Use port number port instead of

-p

port

default 10000.

Use message interval interval (in

seconds, fractions accepted)

instead of default interval 1.0

seconds.

-i

interval

Appendix B. Using the fake SMS center

Switch

Value

Description

Send a maximum of max

messages. Value -1 means that an

unlimited number of messages is

sent. Default -1. Using 0 can be

useful to listen for messages sent

via other channels.

-m

max

In addition, fakesmsc accepts all common Kannel Command line options like --verbosity.

Appendix C. Setting up a test environment for

Push Proxy Gateway

This appendix explains how to set a test environment for PPG. This contains a simulated SMSC, for

instance a http server simulation (this is used as example, because it is simplest) and a simulated push

initiator. Between them, there is the push proxy gateway to be tested. This means that you must conﬁgure

HTTP SMSC.

Creating push content and control document for testing

Here is an example of a push control document, which gives PPG instructions how to do the pushing.

<?xml version="1.0"?>

<!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP//EN"

"http://www.wapforum.org/DTD/pap_1.0.dtd">

<pap>

<push-message push-id="[email protected]"

deliver-before-timestamp="2001-09-28T06:45:00Z"

deliver-after-timestamp="2001-02-28T06:45:00Z"

progress-notes-requested="false">

<quality-of-service priority="low"

delivery-method="unconfirmed"

network-required="true"

network="GSM"

bearer-required="true"

bearer="SMS"/>

</push-message>

</pap>

Because the push content is sended to the phone over SMS, rigth value for network-required and

bearer-required is true, for network GSM and for bearer SMS. However, you can omit these

values alltogether, if you use a phone number as an address. Address value is international phone number

and it must start with plus. It is used here as an unique identiﬁer, SMSC, or sendsms script must

transform it to an usable phone number.

Here is an example of Service Indication, a type of push content. Essentially, the phone displays, when it

receives this SI, the text "Want to test a fetch" and if the user wants, fetches the content located by URL

http://wap.iobox.fi.

<?xml version="1.0"?>

<!DOCTYPE si PUBLIC "-//WAPFORUM//DTD SI 1.0//EN"

"http://www.wapforum.org/DTD/si.dtd">

<si>

<indication href="http://wap.iobox.fi"

si-id="[email protected]"

action="signal-high"

created="1999-06-25T15:23:15Z"

Appendix C. Setting up a test environment for Push Proxy Gateway

si-expires="2002-06-30T00:00:00Z">

Want to test a fetch?

</indication>

</si>

Note that the date value of the si-expires attribute contains trailing zeroes. They are OK here, because SI

tokenizer removes them. But phones does not accept them in the ﬁnal SMS data message. You should

probably use action="signal-high" for testing purposes, for it causes an immediate presentation of

the push message. Production usage is a quite another matter.

Another example of push content is Service Loading. In principle, the phone should fetch immediately

content from URL http://wap.iobox.fi when it receives this document. This sounds quite

unsecure, and indeed, user invention is probably required before fetching.

<?xml version="1.0"?>

<!DOCTYPE sl PUBLIC "-//WAPFORUM//DTD SL 1.0//EN"

"http://www.wapforum.org/DTD/sl.dtd">

<sl href="http://wap.iobox.fi"

action="execute-high">

</sl>

Starting necessary programs

PPG test environment contains, in addition of wapbox and bearerbox, two test programs, test_ppg

(simulating push initiator) and test_http_server (simulating a SMSC center accepting pushed

content sended over SMS. You can ﬁnd both of these programs in test directory, and they both are short

and easily editable.

To set up a test environment, you must ﬁrst conﬁgure a push proxy gateway (setting ﬂag trusted-pi true

makes testing easier). This explained in Chapter "Setting up push proxy gateway". Then issue following

commands, in Kannel’s root directory and in separate windows:

gw/bearerbox [conffile]

gw/wapbox [conffile]

Of course you can use more complicated wapbox and bearerbox command line options, if necessary.

To run a http smsc, start http server simulation:

test/test_http_server -p port

You can, of course, select the port at will. Remember, though, that PPG listens at the port deﬁned in the

ppg conﬁguration ﬁle. Other test_http_server options are irrelevant here.

Lastly, start making push requests, for instance with a test program test_ppg. Its ﬁrst argument is a

URL specifying location of push services. Other arguments are two ﬁle names, ﬁrst one push content and

Appendix C. Setting up a test environment for Push Proxy Gateway

second one pap control document. (For command line options, see Table C.1.). For example doing one

push(you can simplify push url by setting a ppg conﬁguration variable, see "Setting up push proxy

gateway"; q ﬂag here prevents dumping of test_ppg program debugging information):

test/test_ppg -q http://ppg-host-name:ppg-port/ppg-url [content_file]

[control_file]

This presumes that you have set trusted-pi true.

If you want use authentication in a test environment, you can pass username and password either using

headers (setting ﬂag -b) or url (you must have set trusted-pi false and added wap-push-user conﬁguration

group):

test/test_ppg -q http://ppg-host-name:ppg-port?username=ppg-username’&’

password=ppg-password [content_file] [control_file]

Table C-1. Test_ppg’s command line options

Switch

Value

string

Description

Use content qualiﬁer string

instead of default si (service

indication). Allowed values are

wml, si, sl, sia, multipart, nil and

scrap. Nil and scrap are used for

debugging purposes. Wml does

work with some older phone

simulators.

-c

Use application id string instead

of default any. Application

identiﬁes the application in the

phone that should handle the

push request. Sia, ua, mms, nil

and scrap are accepted. Nil and

scrap are used for debugging

purposes.

-a

Use tranfer encoding when

sending a push content. Only

base64 is currently supported.

-e

-b

-i

-r

-t

string

Use headers for authentication,

instead of url. Default off.

boolean

number

Wait interval number instead of

default 0 between pushes.

Do number requests instead of

default 1.

Use number threads instead of

default 1.

100

Appendix C. Setting up a test environment for Push Proxy Gateway

Using Nokia Toolkit as a part of a developing

environment

This chapter describes a developing environment using Nokia Toolkit instead of test_http_server

program.

You cannot use a real phone for testing a push server. Sending random messages to a phone does not

work, because its only feedback (if it works properly) in error situations is dropping the offending

message.

Nokia Toolkit, instead, displays push headers, decompiles tokenised documents and outputs debugging

information. It is not, of course, a carbon copy of a real phone. But it is still usefull for checking spec

conformance of push servers.

Toolkit runs on Windows, the ﬁrst thing you must is to install a virtual machine (VMWare is one

possibility) in the machine where Kannel runs. Then you must conﬁgure Toolkit for working with a push

gateway.

Then start bearerbox and wapbox similar way as told before. You must set the correct client address

in the push document sended by test_ppg program. Use IP address of our virtual machine (easiest way

to get this is to ping your virtual machine name in the dos prompt window). Your bearer is in this case IP.

An example pap document follows:

<?xml version="1.0"?>

<!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP//EN"

"http://www.wapforum.org/DTD/pap_1.0.dtd">

<pap>

<push-message push-id="[email protected]"

deliver-before-timestamp="2001-09-28T06:45:00Z"

deliver-after-timestamp="2001-02-28T06:45:00Z"

progress-notes-requested="false">

<quality-of-service priority="low"

delivery-method="unconfirmed"

</quality-of-service>

</push-message>

</pap>

Note address-value format. It is contains type and value, because PAP protocol supports different address

formats.

You must use test_ppg’s -a and -c ﬂags when pushing messages to Toolkit. -A deﬁnes the client

application handling pushes, right value for it is ua. -C deﬁnes the content type of your push message. SI

works with all Toolkits, wml only with some older versions.

Testing PAP protocol over HTTPS

When testing HTTPS connection to PPG, you probably want use test_ppg’s conﬁguration ﬁle, because

number of required parameters is quite high. Here is a example test_ppg conﬁguration ﬁle:

101

Appendix C. Setting up a test environment for Push Proxy Gateway

group = test-ppg

retries = 2

pi-ssl = yes

ssl-client-certkey-file = /home/aarno/kannelcvs/gateway/gw/certkey.pem

group = configuration

push-url = https://localhost:8900/wappush

pap-file = /home/aarno/test/ipnoqos.txt

content-file = /home/aarno/test/si.txt

username = foo

password = bar

With a conﬁguration ﬁle, you can do a push by typing:

test/test_ppg -q [configuration_file]

Table C-2. Test_ppg’s conﬁguration ﬁle directives

Directive

Value

Description

Mandatory parameter. Start of

test_ppg’s core group.

group

test_ppg

The client tries to log in to PPG

number times before discarding

the push request. Default is 2.

retries

number

boolean

ﬁlename

Mandatory parameter for

HTTPS connection. Does the

client use HTTPS connection.

Default is no.

pi-ssl

Mandatory parameter for

HTTPS connection. File

containing the client’s ssl

certiﬁcate and private key.

ssl-client-certkey-file

Mandatory paramenter for

HTTPS connection.This ﬁle

contains the certiﬁcates test_ppg

is willing to trust. If this directive

is not set, certiﬁcates are not

validated and HTTPS would not

be tested.

ssl-trusted-ca-file

group

ﬁlename

conﬁguration

url

Mandatory parameter. Start of

test_ppg’s test group.

Mandatory value. URL locating

PPG’s services.

push-url

Mandatory value. File

containing pap request’s control

document.

pap-file

ﬁlename

102

Appendix C. Setting up a test environment for Push Proxy Gateway

Directive

Value

Description

Mandatory value. File

containing pap request’s content

document.

content-file

username

ﬁlename

string

Mandatory value. PPG service

user’s username.

Mandatory value. PPG service

user’s password.

password

string

103

Appendix D. Setting up a dial-up line

This appendix explains how to set up a dial-up line in Linux for use with the Kannel WAP gateway. In

order for it to work you need a Linux kernel with PPP capabilities. Most distributions provides PPP

kernel support by default. For more information how to compile PPP support into the kernel please read

the "Linux Kernel HOWTO" at http://www.linuxdoc.org/.

Analog modem

This section explains how to set up a dial-up line with an analog modem.

Download and install the mgetty package.

rpm -ivh mgetty-VERSION-rpm

To run mgetty as a daemon, add the following line to /etc/inittab.

Read man inittab for more detailed information. In this example we assume your modem is connected to

the serial port ttyS0 (COM 1).

S0:2345:respawn:/sbin/mgetty ttyS0 -x 6 -D /dev/ttyS0

We need to start the pppd automatically when mgetty receives an AutoPPP request. Add the next line to

/etc/mgetty+sendfax/login.conﬁg

/AutoPPP/ - - /usr/sbin/pppd file /etc/ppp/options.server

In /etc/mgetty+sendfax/mgetty.conﬁg you might need to change the connect speed between the computer

and the modem. Note: this is not the connect speed between the WAP client and the server modem. If

you are e.g. going to use a Nokia 7110 as the server side modem you need to change the speed to 19200.

Usually you can just leave the speed to the default value (38400).

speed 38400

Add the following lines to /etc/ppp/options.server

refuse-chap

require-pap

lock

modem

crtscts

passive

192.168.1.10:192.168.1.20

debug

104

Appendix D. Setting up a dial-up line

In /etc/ppp/pap-secrets add the username and password for the ppp account. The IP address is the one

assigned to the phone.

wapuser

wappswd 192.168.0.20

Conﬁgure your phone (this example is for Nokia 7110)

homepage http:/yourhost/hello.wml

connection type continuous

connection security off

bearer data

dial up number (your phone number)

ip address (IP of host running bearerbox)

auth type normal

data call type analogue

data call speed 9600

username wapuser

password wappswd

ISDN terminal

This section needs to be written

105

Appendix E. Log ﬁles

This appendix describes the log ﬁle format.

Bearerbox Access Log

2001-01-01 12:00:00 Sent SMS [SMSC:smsc] [SVC:sms] [from:12345]

[to:67890] [flags:0:1:0:0:0] [msg:11:Hello World] [udh:0]

Variable

Value

Description

Date

2001-01-01 12:00:00

Date

Result: Send, failed, DLR

Result

SMSC

Sent SMS

smsc

(deliver report), Received, etc.

Smsc id (smsc-id) deﬁned in

conﬁguration group smsc

Service name (name) deﬁned in

conﬁguration group

SVC

from

sms

sendsms-user

12345

67890

Sender

Recipient

Flags: MClass, Coding, MWI,

Compress, DLRMask

Flags

0:1:0:0:0

Size of message and message

dump (in text or hex if it’s

binary)

Message Text

11:Hello World

Size of UDH and UDH Hex

dump

User Data Header

Log rotation

If Kannel is conﬁgured so that the bearerbox, wapbox and/or smsbox log to ﬁle each of these log ﬁles

will continue to grow unless administered in some way (this is especially true if access logs are created

and/or the log level is set to debug).

A typical way of administering log ﬁles is to ’rotate’ the logs on a regular basis using a tool such as

logrotate. A sample logrotate script (to be added to /etc/logrotate.d) is shown below. In this example the

Kannel log ﬁles found in /var/log/kannel are rotated and compressed daily over 365 days. See the

documentation for logrotate for more details. Of particular note however is the postrotate command, this

killall -HUP issues a HUP command to each kannel box running. The HUP signal has the effect of

reopening the log ﬁle, without this command Kannel will continue to write to the rotated log ﬁle.

/var/log/kannel/ .log {

106

Appendix E. Log ﬁles

daily

missingok

rotate 365

compress

delaycompress

notifempty

create 640 kannel adm

sharedscripts

postrotate

killall -HUP bearerbox smsbox wapbox || true > /dev/null 2> /dev/null

endscript

}

107

Glossary

Mobile Originated - a SMS from mobile to application

Mobile Terminated - a SMS from application to mobile

Message Waiting Indicator (See [BIBLIO-3GPP-23038])

MWI

MClass

Message Class (See [BIBLIO-3GPP-23038])

Coding

Message Coding (See [BIBLIO-3GPP-23038])

108

Bibliography

RFC 2616 - Hypertext Transfer Protocol -- HTTP/1.1,

http://www.w3.org/Protocols/rfc2616/rfc2616.html, Request for Comments: 2616, The Internet

Society, 1999.

3GPP 23.038, http://www.3gpp.org/ftp/Specs/latest/Rel-5/23_series/23038-500.zip, ..., 3GPP, ?.

3GPP 23.040, http://www.3gpp.org/ftp/Specs/latest/Rel-5/23_series/23040-530.zip, ..., 3GPP, ?.

109

Miele Ventilation Hood DA 5100 D User Manual
MTD Trimmer YM1000 User Manual
NeoDigitscom DVD Player X3000 HD User Manual
N Tron Switch 304TX N User Manual
Numark Industries Karaoke Machine KMX01 User Manual
OWI Portable Speaker CVT User Manual
Palsonic TV Converter Box 3425G User Manual
Panasonic Cell Phone KX PRW110FX User Manual
Panasonic Cell Phone KX TD7895 User Manual
Panasonic Portable DVD Player DVD LX95 User Manual