Nokia WAP and SMS gateway User Manual

Download

Kannel 1.3.1 User’s Guide

Open Source WAP and SMS gateway

Lars Wirzenius

Gateway architect

Wapit Ltd

liw@wapit.com

http://www.wapit.com

http://www.kannel.org

Kalle Marjola

Manager

Wapit Ltd

rpr@wapit.com

http://www.wapit.com

http://www.kannel.org

Andreas Fink

Chairman & CTO

Global Networks Inc.

andreas@ﬁnk.org

http://www.smsrelay.com

http://www.gni.ch

Bruno Rodrigues

bruno.rodrigues@litux.org

http://litux.org/bruno

Stipe Tolj

CTO & CIO

Wapme Systems AG

tolj@wapme-systems.de

http://www.wapme.de

http://www.kannel.org

Aarno Syvänen

Chief MMS Developer

Global Networks Inc.

as@gni.ch

http://www.gni.ch

Kannel 1.3.1 User’s Guide: Open Source WAP and SMS gateway

by Lars Wirzenius, Kalle Marjola, Andreas Fink, Bruno Rodrigues, Stipe Tolj, and Aarno Syvänen

Abstract

This document describes how to install and use Kannel, the Open Source WAP and SMS Gateway originally developed by Wapit Ltd (now out of business) and now being developed further by the open source community, namely the Kannel Group.

Revision History

Revision 1.3.1 2006.07.01

1. Introduction............................................................................................................................................1

Overview of WAP ..............................................................................................................................1

Overview of WAP Push......................................................................................................................2

Overview of SMS...............................................................................................................................3

Features .............................................................................................................................................. 4

Requirements .....................................................................................................................................4

2. Installing the gateway............................................................................................................................5

Getting the source code ......................................................................................................................5

Finding the documentation.................................................................................................................5

Compiling the gateway.......................................................................................................................6

Installing the gateway.........................................................................................................................7

Using pre-compiled binary packages .................................................................................................7

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

Installing Kannel from DEB packages .....................................................................................9

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

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

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

Inclusion of conﬁguration ﬁles ...............................................................................................13

Core conﬁguration ..................................................................................................................13

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

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

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

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

HTTP administration ........................................................ ...................................................... 22

4. Setting up a WAP gateway .................................................................................................................. 24

WAP gateway conﬁguration.............................................................................................................24

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

Running WAP gateway ....................................................................................................................26

Checking whether the WAP gateway is alive...................................................................................26

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

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

SMS gateway 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 InVoke SMS Center 4.x)......................................................41

GSM modem .................................................................................................................42

GSM modem 2..............................................................................................................44

Fake SMSC ...................................................................................................................47

HTTP-based relay and content gateways......................................................................48

Using multiple SMS centers .........................................................................................49

Feature checklist ...........................................................................................................49

Smsbox conﬁguration .............................................................................................................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 services..........................................................................................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&WAP gateway ......................................................................................................82

SMS&WAP gateway conﬁguration..................................................................................................82

Running SMS&WAP gateway .........................................................................................................82

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

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

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

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

Running a push proxy gateway........................................................................................................87

An example using HTTP SMSC......................................................................................................87

An example push (tokenised SI) document .....................................................................................87

Default network and bearer used by push proxy gateway................................................................87

8. Using SSL for HTTP............................................................................................................................89

Using SSL client support .................................................................................................................89

Using SSL server support for the administration HTTP interface...................................................89

Using SSL server support for the sendsms HTTP interface ............................................................89

Using SSL server support for PPG HTTPS interface ......................................................................90

9. Delivery Reports ..................................................................................................................................91

10. Getting help and reporting bugs....................................................................................................... 92

A. Using the fake WAP sender ................................................................................................................93

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

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

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

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 modem ...............................................................................................................................103

ISDN terminal ................................................................................................................................104

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

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

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

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

Bibliography...........................................................................................................................................108

List of Tables

3-1. Core Group Variables .........................................................................................................................14

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

3-3. Kannel HTTP Administration Commands .........................................................................................22

4-1. Wapbox Group Variables....................................................................................................................24

5-1. SMSC Group Variables ......................................................................................................................27

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

5-3. SMSC driver internal features ............................................................................................................50

5-4. Smsbox Group Variables ....................................................................................................................52

5-5. Smsbox-route Group Variables ..........................................................................................................55

5-6. SMS-Service Group Variables............................................................................................................56

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

5-8. X-Kannel Headers ..............................................................................................................................63

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

5-10. SendSMS-User Group Variables ......................................................................................................66

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

5-12. MySQL Connection Group Variables ..............................................................................................71

5-13. OTA Setting Group Variables ...........................................................................................................72

5-14. OTA Bookmark Group Variables .....................................................................................................73

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

5-16. OTA CGI Variables...........................................................................................................................80

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

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

B-1. Fakesmsc command line options .......................................................................................................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

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

Chapter 1. Introduction

SMS, short messaging service, is a way to send short (160 character) messages from one GSM phone to another. It can also be used to send operator logos, ringing tones, business cards and phone 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).

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

Chapter 2. Installing the gateway

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.

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

Chapter 2. Installing the gateway

Replace /path/to/directory with the pathname of the actual directory where the programs should be installed. The programs that are installed are (as ﬁ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

Installing Kannel

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

2. Log in as root:

su -

3. Install the RPM package:

rpm -ivh kannel-VERSION.i386.rpm

Upgrading Kannel

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

2. Log in as root

3. Upgrade the RPM package:

rpm -Uvh kannel-VERSION.i386.rpm

Chapter 2. Installing the gateway

Removing Kannel

1. Log in as root:

2. Remove the RPM package:

rpm -e kannel

After you have installed Kannel from the RPM packages you x should now be able to run the Kannel init.d script that will start Kannel as a WAP gateway. Run the script as root.

/etc/rc.d/init.d/kannel start

To stop the gateway just run the same script with the stop parameter.

/etc/rc.d/init.d/kannel stop

If Kannel is already running and you just want to quickly stop and start the gateway,e.g.to set a new 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/.

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:

1 # A do-nothing service. 2 group = sms-service 3 keyword = nop 4 text = "You asked nothing and I did it!" 5 6 # Default service. 7 group = sms-service 8 keyword = default 9 text = "No services defined"

The above snippet 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

admin-port (m) port-number

admin-port-ssl (o) bool

admin-password (m) string

status-password string

recommended)

If set to true a SSL-enabled administration HTTP server will be used instead of the default unsecure plain HTTP server. To access the administration pacges you will have to use a HTTP client that is capable of talking to such a server. Use the "https://" scheme to access the secured HTTP server. Defaults to "no".

Password for HTTP administration commands (see below)

Password to request Kannel status. If not set, no password is required, and if set, either this or

admin-password can be used

Chapter 3. Using the gateway

Variable Value Description

These lists can be used to prevent connection from given IP addresses. Each list can have

admin-deny-ip IP-list

several addresses, separated with semicolons (’;’). An asterisk

admin-allow-ip

(’*’) can be used as a wildcard in a place of any ONE number, so *.*.*.* matches any IP.

This is the port number to which the smsboxes, if any, connect. As with admin-port, this can be anything you want. Must be set if you want to handle any SMS

smsbox-port (c) port-number

trafﬁc.

If set to true, the smsbox connection module will be SSL-enabled. Your smsboxes will have to connect using SSL to the bearerbox then. This is used to secure communication between bearerbox and smsboxes in case they are in seperate networks operated and the TCP communication is not secured on a lower network layer. Defaults

smsbox-port-ssl (o) bool

to "no".

Like smsbox-port, but for wapbox-connections. If not set, Kannel cannot handle WAP

wapbox-port (c) port-number

trafﬁc

If set to true, the wapbox connection module will be SSL-enabled. Your wapboxes will have to connect using SSL to the bearerbox then. This is used to secure communication between bearerbox and wapboxes in case they are in seperate networks operated and the TCP communication is not secured on a lower network

wapbox-port-ssl (o) bool

layer. Defaults to "no".

Chapter 3. Using the gateway

Variable Value Description

These lists can be used to prevent box connections from given IP addresses. Each list can

box-deny-ip IP-list

have several addresses, separated with semicolons (’;’). An asterisk

box-allow-ip

(’*’) can be used as a wildcard in place of any ONE number, so *.*.*.* matches any IP.

These lists can be used to prevent UDP packets from given IP addresses, thus preventing

udp-deny-ip IP-list

unwanted use of the WAP gateway. Used the same way as

udp-allow-ip

box-deny-ip and box-allow-ip.

If this is set, Kannel listens to WAP UDP packets incoming to ports 9200-9208, bound to given IP. If no speciﬁc IP is needed, use just an asterisk (’*’). If UDP messages are listened to, wapbox-port variable MUST be

wdp-interface-name (c) IP or ’*’

set.

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

log-file ﬁlename

only used by the bearerbox.

Minimum level of logﬁle events logged. 0 is for ’debug’, 1 ’info’, 2 ’warning, 3 ’error’ and 4 ’panic’ (see Command Line

log-level number 0..5

Options)

A ﬁle in which information about received/sent SMS messages is stored. Access-log in ’core’ group is only used by the

access-log ﬁlename

bearerbox.

Chapter 3. Using the gateway

Variable Value Description

String to unify received phone numbers, for SMSC routing and to ensure that SMS centers can handle them properly. This is applied to ’sender’ number when receiving SMS messages from SMS Center and for ’receiver’ number when receiving messages from SMSbox (either sendsms message or reply to original message). Format is that ﬁ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

white-list URL

phone numbers, so beware!

As white-list, but SMS messages to these numbers are

black-list URL

automatically discarded

Chapter 3. Using the gateway

Variable Value Description

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

store-file ﬁlename

down violently.

Enable the use of an HTTP

http-proxy-host hostname

http-proxy-port port-number

proxy for all HTTP requests.

A list of excluded hosts from being used via a proxy. Separate

http-proxy-exceptions URL-list

each entry with space.

Username for authenticating proxy use, for proxies that

http-proxy-username username

require this.

Password for authenticating proxy use, for proxies that

http-proxy-password URL-list

require this.

A PEM encoded SSL 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

ssl-server-key-file (c) ﬁlename

HTTPS server side only.

Chapter 3. Using the gateway

Variable Value Description

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

ssl-trusted-ca-file ﬁlename

proven.

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

dlr-storage type

default this is set to ’internal’.

Set maximum size of incoming message queue. After number of messages has hit this value, Kannel began to discard them. Value 0 means giving strict priority to outgoing messages.

-1, default, means that the queue of inﬁnite length is accepted. (This works with any normal input, use this variable only when Kannel message queues

maximum-queue-length number of messages

grow very long).

A sample more complex ’core’ group could be something like this:

group = core admin-port = 13000 admin-password = f00bar status-password = sTat admin-deny-ip = "*.*.*.*" admin-allow-ip = "127.0.0.1;200.100.0.*" smsbox-port = 13003 wapbox-port = 13004 box-deny-ip = "*.*.*.*" box-allow-ip = "127.0.0.1;200.100.0.*" wdp-interface-name = "*" log-file = "kannel.log" log-level = 1 access-log = "kannel.access" unified-prefix = "+358,00358,0;+,00" white-list = "http://localhost/whitelist.txt"

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.

Chapter 3. Using the gateway

[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

-v <level>

Set verbosity level for stdout (screen) logging. Default is 0, which means ’debug’. 1 is ’info, 2 ’warning’, 3 ’error’ and 4 ’panic’

--verbosity <level>

-D <places>

--debug <places>

-F <file-name>

--logfile <file-name>

-V <level>

--fileverbosity <level>

-S

--suspended

-I

--isolated

Chapter 3. Using the gateway

Set debug-places for ’debug’ level output.

Log to ﬁle named ﬁle-name, too. Does not overrun or affect any logﬁle deﬁned in conﬁguration ﬁle.

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.

Start the system initially at SUSPENDED state (see below, bearerbox only)

Start the system initially at ISOLATED state (see below, bearerbox only)

Only try to open HTTP sendsms interface; if it

-H

--tryhttp

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

Kannel statuses

In Kannel, there are four states for the program (which currently directly only apply to bearerbox):

a. Running. The gateway accepts, proceeds and relies messages normally. This is the default state for

the bearerbox.

b. Suspended. The gateway does not accept any new messages from SMS centers nor from UDP ports.

Neither does it accept new sms and wapbox connections nor sends any messages already in the system onward.

c. Isolated. In this state, the gateway does not accept any messages from external message providers,

which means SMS Centers and UDP ports. It still processes any messages in the system and can accept new messages from sendsms interface in smsbox.

d. Full. Gateway does not accept any messages from SMS centers, because maximum-queue-length

is achieved.

e. Shutdown. When the gateway is brought down, it does not accept any new messages from SMS

centers and UDP ports, but processes all systems already in the system. As soon as any queues are emptied, the system exits

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 HTML version of status

status.xml XML version of status

status.wml WML version of status

supplied.

Get the current content of the store queue of the gateway in a text version. No password required, unless status-password set, in which case either that or main admin password must be

store-status or store-status.txt

store-status.html HTML version of store-status

store-status.xml XML version of store-status

supplied.

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

suspend

Password required.

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

isolate

Password required.

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

resume

isolated. Password required.

shutdown

flush-dlr

start-smsc

stop-smsc

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.

If Kannel state is ’suspended’ this will ﬂush all queued DLR messages in the current storage space. Password required.

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-host (m) hostname

timer-freq value-in-seconds

bearerbox is.

The frequency of how often timers are checked out. Default is 1

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

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

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

map-url-0 URL-pair

mappings.

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

force-sar bool

smart-errorsr bool

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.

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.

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.

smsc (m) string

See below for a complete list.

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

smsc-id string

for that.

SMS messages with SMSC ID equal to any of the IDs in this list are never routed to this SMSC. Multiple entries are separated

denied-smsc-id id-list

with semicolons (’;’)

This list is opposite to previous: only SMS messages with SMSC ID in this list are ever routed to this SMSC. Multiple entries are

allowed-smsc-id id-list

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

preferred-smsc-id id-list

with semicolons (’;’)

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-prefix prefix-list

allowed or not in denied list.

A list of phone number preﬁxes which are NOT accepted to be

denied-prefix prefix-list

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

preferred-prefix prefix-list

randomly)

Chapter 5. Setting up a SMS Gateway

Variable Value Description

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

alt-charset number

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

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

host (m) hostname

hostname (their.machine.here)

Port number in the smsc host

port (m) port-number

machine

Username in the SMSC

smsc-username (m) string

machine/connection account

Password in the SMSC machine

smsc-password (m) string

needed to contact SMSC

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

keepalive number

feature.

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

sender-prefix string

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

host (c) hostname

(their.machine.here)

Port number in the SMSC host

port (c) port-number

machine

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

alt-host hostname

host:alt-port)

Optional alternate Port number in the SMSC host machine (If undef but exists alt-host, emi2

alt-port port-number

would try alt-host:port)

Username in the SMSC

smsc-username string

machine/connection account

Password in the SMSC machine

smsc-password string

needed to contact SMSC

The device the modem is connected to, like /dev/ttyS0.

device (c) device-name

ISDN connection only.

Phone number to dial to, when connecting over a modem to an

phone (c) string

SMS center.

Optional hostname in which to bind the connection in our end.

our-host hostname

TCP/IP connection only.

Optional port number in which to bind the connection in our

our-port port-number

end. TCP/IP connection only.

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 port-number

connection only.

Name of a "Send only" service. Defaults to send. All outgoing messages are routed through this

appname string

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

connect-allow-ip IP-list

connection only.

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

idle-timeout number (seconds)

SMSC.

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

keepalive number (seconds)

my-number to be set.

A message is resent if the acknowledge from SMSC takes more than this time. Defaults to

wait-ack number (seconds)

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

wait-ack-expire number

is the mst accurate)

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,

window number (messages)

defaults to the maximum - 100)

If SMSC requires that kannel limits the number of messages per second, use this variable.

throughput number (messages/sec)

(optional)

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

retry boolean

error ocur.

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

my-number number

that receiver.

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"

alt-charset number

and new ones can be added.

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

host (m) hostname

(their.machine.here)

The port number for the TRANSMITTER connection to the SMSC. May be the same as receive-port. Use value 0 to

port (m) port-number

disable this I/O thread.

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

transceiver-mode bool

connection.

The port number for the RECEIVER connection to the SMSC. May be the same as port. Use value 0 to disable this I/O

receive-port port-number

thread.

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

smsc-username (m) string

drivers use the same name.

The password matching the "smsc-username" your

smsc-password (m) string

teleoperator provided you with.

Usually you can get away with "VMA" which stands for Voice

system-type (m) string

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

interface-version number

v3.3 set to "33".

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,

address-range (m) string

though.

Specicy the outgoing IP address for connections from a multi-homed machine. If this is not deﬁned the default device of

our-host string

the machine will be used.

Optional smsc short number. Should be set if smsc sends a

my-number number

different one.

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

enquire-link-interval number

is 30 seconds.

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

max-pending-submits number

at any time.

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

reconnect-delay number

seconds.

Optional, source address TON setting for the link. (Defaults to

source-addr-ton number

0).

Optional, source address NPI setting for the link. (Defaults to

source-addr-npi number

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 boolean

Optional, destination address TON setting for the link.

dest-addr-ton number

(Defaults to 0).

Optional, destination address NPI setting for the link. (Defaults

dest-addr-npi number

to 1).

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

msg-id-type number

using the conﬁg directive.

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

alt-charset string

directive.

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

smsc_nua (m) X121 smsc address

an X.28 connection.

The address of a radio PAD implementing Sema SMS2000

home_nua (m) X121 radio pad address

using X.28 connection.

Report indicator used by the Sema SMS2000 protocol.

wait_report 0 (false)/1 (true)

Optional.

group = smsc smsc = ois host = 103.102.101.100 port = 10000 receive-port = 10000 ois-debug-level = 0

Variable Value Description

host (m) ip SMSC Host name or IP

port (m) port number SMSC Port number

The port in which the SMSC

receive-port (m) port number

will contact

extra debug, optional, see

ois-debug-level number 0 to 8

smsc_ois.c

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 (m) hostname

(host.foobar.com)

The port number for the

port (m) port-number

connection to the SMSC.

The ’username’ of the Messaging Entity connecting to

smsc-username (m) string

the SMSC.

The password matching the "smsc-username" your

smsc-password (m) string

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

reconnect-delay number

is 10 seconds.

Optional, source address TON setting for the link. (Defaults to

source-addr-ton number

1).

Optional, source address NPI setting for the link. (Defaults to

source-addr-npi number

1).

Optional, destination address TON setting for the link.

dest-addr-ton number

(Defaults to 1).

Optional, destination address NPI setting for the link. (Defaults

dest-addr-npi number

to 1).

Optional, sets the default priority of messages transmitted over this smsc link. (Defaults to

priority number

0, which is the highest priority)

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

modemtype string

used.

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

pin string

usually a four digit number.

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

validityperiod integer

24 hours.

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

alt-dcs boolean

true.

Modem Type Modems

wavecom Wavecom

premicell Nokia Premicell

Siemens M20 (this modem have

siemens

siemens-tc35 Siemens TC35

falcom Falcom

some bugs)

Chapter 5. Setting up a SMS Gateway

Modem Type Modems

Nokia 6210, 7110, 8210 (tested).

Probably other Nokia phones

nokiaphone

ericsson Ericsson

too.

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

modemtype string

device (m) device-name

speed serial speed in bps

pin string

Premicell).

The device the modem is 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.

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.

Chapter 5. Setting up a SMS Gateway

Variable Value Description

9.2.3.12. Default is 167, meaning

validityperiod integer

24 hours.

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

retry boolean

error ocur.

Kannel would "ping" the modem for this many seconds. If the probe fails, try to reconnect to it.

keepalive seconds

my-number number Optional phone number.

sms-center 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

sim-buffering boolean

Siemens M20.

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

id string

from AT2

The name of this modem

name string

conﬁguration. Used in logs

String to use when trying to detect the modem. See

detect-string string

detect-string2

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 string

detect-strign2 "M20"

Optional initialization string. Defaults to

init-string string

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

Serial port hint speed to use. Optional. Defaults to smsc group

speed number

speed or autodetect

Optional AT command to enable hardware handshake. Defaults to

enable-hwhs string

"AT+IFC=2,2"

Optional. Defaults to false. Some modems needs to sleep after opening the serial port and

need-sleep boolean

before ﬁrst command

Optional. Defaults to false. If the modem doesn’t support the PIN

no-pin boolean

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

no-smsc boolean

receiving)

Chapter 5. Setting up a SMS Gateway

Variable Value Description

Optional, defaults to 100 miliseconds. The sleep time after

sendline-sleep number (miliseconds)

sending a AT command.

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

keepalive-cmd string

27007.

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

message-storage string

used (usually "SM").

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

enable-mms boolean

sending the messages.

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

host (m) hostname

hostname (their.machine.here)

Port number in smsc host

port (m) port-number

machine

If set, only connections from

connect-allow-ip IP-list

these IP addresses are accepted.

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

system-type (m) string

supported.

Location to send MT messages. This URL is expanded by used

send-url (m) url

system, if need to.

Do not add variable sender to

no-sender boolean

the send-url.

Do not add variable coding to

no-coding boolean

the send-url.

Represent udh and text as a numeric string containing the hexdump. For instance, text=%2b123 is represented as

no-sep boolean

text=2b313233.

Chapter 5. Setting up a SMS Gateway

Variable Value Description

Port number in which Kannel listens to (MO) messages from

port (m) port-number

other gateway

IPs allowed to use this interface. If not set, "127.0.0.1" (localhost) is the only host allowed to

connect-allow-ip IP-list

connect.

Username associated to connection, if needed. ’kannel’ requires this, and it is the same as

smsc-username string

send-sms username at other end.

Password for username, if

smsc-password string

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

cimd2

Can use DLR

n y? n n y y? n n n n n n

Can set DCSa

? ? ? ? y ? ? ? ? y ? ?

Can set Alt-DCS

emi

emi_ip

emi2

sema ois at at2 http fake

smpp

Chapter 5. Setting up a SMS Gateway

Featurecimd

cimd2

emi

emi_ip

emi2

smpp

n n n n y n n n n y n n

Can set Validity

? ? ? ? y ? ? ? ? y ? ?

Can set Deferred

? ? ? ? y ? ? ? ? n ? ?

Can set PID

n n n n y y n n n y n n

Can set RPI

n n n n y y n n n n n n

Can send Unicode

? ? ? ? y ? ? ? ? y ? ?

Can send 8 bits

? ? ? ? y ? ? ? ? y ? ?

Correctly send GSM alphabet

? ? ? ? y ? ? ? ? ? ? ?

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

sema ois at at2 http fake

Table 5-3. SMSC driver internal features

Featurecimd

cimd2

emi

emi2

emi_ip

Can keep idle connections alive

n y? n n y y? ? ? y ? ? ?

Can send octet data without UDH

n y? y? y? y n n y? y? ? n y?a

Can send octet data with UDH

N y? y? y? y y? n ? y? ? y? y?a

Can send text messages with UDH

n y? y? y? y n n ? y? ? n y?

Can receive octet data without UDH

n y? n n y n y?b y? y? ? n n

Can receive unicode messages

n n n n n n n n n ? n n

Can receive octet data with UDH

n y? n n y n n N y? ? y? y?

Can receive text messages with UDH

n y? n n y n n N y? ? n n

sema ois at2 at http fake

smpp

Chapter 5. Setting up a SMS Gateway

Featurecimd

cimd2

Correctly encodes @ when sending

y? y? ? ? y y? ? y? y? ? y? y?

Correctly encodes ä when sending

y? y? ? ? y y? ? y? y? ? y? y?

Correctly encodes { when sending

n y? ? ? y y? ? n Nc ? y? y?

Can receive @ in text messages

y? y? ? ? y y? ? y? y? ? y? y?

Can receive ä in text messages

y? y? ? ? y y? ? y? y? ? y? y?

Can receive { in text messages

n y? ? ? y y? ? n y? ? y? y?

Can shut down idle connections

n n n n y n ? ? ? ? ? ?

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

emi

emi_ip

emi2

sema ois at2 at http fake

smpp

Symbol Meaning

? not yet investigated

y driver has this feature, and it has been tested

y? driver probably has this feature, has not been

tested

n driver does not have this feature

N 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-host (m) hostname

bearerbox is.

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

smsbox-id (o) string

EMI proxying boxes.

The port in which any sendsms HTTP requests are done. As with other ports in Kannel, can be set

sendsms-port (c) port-number

as anything desired.

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

sendsms-port-ssl (o) bool

group. Defaults to "no".

URL locating the sendsms service. Defaults to

sendsms-url (o) url

/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

sendsms-chars string

"0123456789 +-" is used.

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

global-sender phone-number

set as the number of SMSC

As with the bearerbox ’core’

log-file ﬁlename

log-level number 0..5

group. Access-log is used to store information about MO and send-sms requests. Can be named same as the ’main’

access-log ﬁlename

access-log (in ’core’ group).

white-list URL

black-list URL

reply-couldnotfetch string

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.

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

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

reply-couldnotrepresent string

as an SMS message..

If set, replaces the SMS message sent back when kannel could not contact http service. Defaults to

reply-requestfailed string

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

mo-recode boolean

iso-8859-1.

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

http-request-retry integer

is done.

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

http-queue-delay integer

a non-zero value.

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

smsbox-id (m) string

apply.

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

smsc-ids word-list

an smsbox instance.

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

shortcuts number-list

to an smsbox instance.

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:password@host.domain: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

keyword (m) word

message contains.

If the service has aliases, they are listed as a list with each entry

aliases word-list

separated with a semicolon (’;’)

Optional name to identify the service in logs. If unset,

name string

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

get-url (c) URL

plain ’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

post-url (c) URL

otherwhere.

Requested URL. As above, but request is done as XML POST. Always matches the keyword, regardless of pattern matching. See notes on POST otherwhere

post-xml (c) URL

and XML Post

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

file (c) ﬁ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

text (c) string

usable here, too.

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

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’

accepted-smsc id-list

or ’SON’

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

allowed-prefix prefix-list

denied list.

A list of phone number preﬁxes of the sender number which are NOT accepted to be sent through

denied-prefix prefix-list

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-receiver-prefix prefix-list

allowed to this service.

A list of phone number preﬁxes of the receiver number which are NOT accepted to be sent through

denied-receiver-prefix prefix-list

this SMSC.

Catch keyword regardless of

catch-all bool

’%s’ parameters in pattern.

Used only with POST. If set to true, number of the handset is

send-sender bool

set, otherwise not.

Used only with POST. Remove matched keyword from message

strip-keyword bool

text before sending it onward.

This number is set as sender. Most SMS centers ignore this, and use their ﬁxed number instead. This option overrides all

faked-sender phone-number

other sender setting methods.

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

max-messages number

messages.

Request reply can include special X-Kannel headers but these are only accepted if this variable is set to true. See

accept-x-kannel-headers bool

Extended 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

assume-plain-text bool

expected.

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

split-chars string

included in the previous part.

If the message is split into several ones, this string is appended to each message except

split-suffix string

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

omit-empty bool

at all in such a case.

If speciﬁed, this string is automatically added to each SMS sent with this service. If the message is split, it is added to

header string

each part.

As header, but not inserted into

footer string

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.

prefix string

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.

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

white-list URL

ﬁle.

As white-list, but SMS messages from these numbers are

black-list URL

automatically discarded

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)

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

in the SMS message)

%s 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’)

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

when user enters a URL) and URL encoding isn’t done (all others do URL encode)

%r 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"

%a all words of the SMS message, including the ﬁrst

one, with spaces squeezed to one

%b the original SMS message, in a binary form

%t the time the message was sent, formatted as

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

%p the phone number of the sender of the SMS

message

Chapter 5. Setting up a SMS Gateway

%P the phone number of the receiver of the SMS

message

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

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

%i the smsc-id of the connection that received the

message

%d the delivery report value

%A the delivery report SMSC reply, if any

%n the sendsms-user or sms-service name

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

bits) or 3 (unicode)

%C 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"

%u 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 Processed like HTML.

text/xml 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

username X-Kannel-Username

password X-Kannel-Password

from X-Kannel-From

to X-Kannel-To

text request body

charset charset as in Content-Type: text/html;

charset=ISO-8859-1

udh X-Kannel-UDH

smsc X-Kannel-SMSC

flash X-Kannel-Flash (deprecated, see

X-Kannel-MClass

mclass X-Kannel-MClass

mwi 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 X-Kannel-Validity

deferred X-Kannel-Deferred

dlrmask X-Kannel-DLR-Mask

dlrurl X-Kannel-DLR-Url

account X-Kannel-Account

pid X-Kannel-PID

alt-dcs X-Kannel-Alt-DCS

Kannel POST

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

Table 5-9. X-Kannel Post Headers

Chapter 5. Setting up a SMS Gateway

Parameter (escape code)

X-Kannel Header Notes

equivalent

%p (from) X-Kannel-From Only sent if send-sender is

true

%P (to) X-Kannel-To

%t (time) X-Kannel-Time

%u (udh) X-Kannel-UDH in hex format:

06050415820000

%i (smsc) X-Kannel-SMSC

- (mclass) X-Kannel-MClass

- (pid) X-Kannel-PID

- (alt-dcs) X-Kannel-Alt-DCS

- (mwi) X-Kannel-MWI

%c (coding) X-Kannel-Coding 1=7 Bits, 2=8 Bits, 3=UCS2

- (compress) X-Kannel-Compress

- (validity) X-Kannel-Validity

- (deferred) X-Kannel-Deferred

%n (service name) X-Kannel-Service

%a or %r (text) request body kannel send all words (%a)

unless strip-keyword is true

%C (charset) present in Content-Type HTTP Example: Content-Type:

text/plain;

charset=ISO-8859-1

XML Post

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

<?xml version="1.0"?> <!DOCTYPE ...> <message>

<da><number>destination number (to)</number></da> <oa><number>originating number (from)</number></oa> <ud>user data (text)</text> <udh>user data header (udh)</udh> <dcs>

<mclass>mclass</mclass> <coding>coding</coding> <mwi>mwi</mwi> <compress>compress</compress>

Chapter 5. Setting up a SMS Gateway

<alt-dcs>alt-dcs</alt-dcs> </dcs> <pid>pid</pid> <statusrequest>

<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>smsc-id</to> <from>smsc-id</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) sendsms-user This is a mandatory variable

username (m) string Name for the user/account.

Password for the user (see

password (m) string

name string As in ’sms-service’ groups.

user-deny-ip IP-list

user-allow-IP IP-list

HTTP interface, below)

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.

Force SMSC ID as a ’string’ (linked to SMS routing, see

forced-smsc string

’smsc’ groups)

If no SMSC ID is given with the send-sms request (see below), use this one. No idea to use with

default-smsc string

forced-smsc.

This number is set as sender if not set by from get/post

default-sender phone-number

faked-sender phone-number As in ’sms-service’ groups

max-messages number

concatenation bool

split-chars string

split-suffix string

omit-empty bool

header string

footer string

parameter

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-prefix prefix-list

allowed or not in denied list.

A list of phone number preﬁxes which are NOT accepted to be

denied-prefix prefix-list

sent using this username.

white-list URL

numhash.h header ﬁle.

As white-list, but SMS messages from these numbers are

black-list URL

automatically rejected.

URL to be fetched if a dlrmask

dlr-url URL

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"

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

table (m) string

field-smsc (m) string

non-alphabet characters.

The name of the table that is used to store the DLR information.

The table ﬁeld that is used for the smsc data.

Chapter 5. Setting up a SMS Gateway

Variable Value Description

The table ﬁeld that is used for

field-timestamp (m) string

the timestamp data.

The table ﬁeld that is used for

field-destination (m) string

the destination number data.

The table ﬁeld that is used for

field-service (m) string

the service username data.

The table ﬁeld that is used for the DLR URL which is triggered when the DLR for this message

field-url (m) string

arrives from the SMSC.

The table ﬁeld that is used for the DLR mask that has been set

field-mask (m) string

for a message.

The table ﬁeld that is used to reﬂect the status of the DLR for a

field-status (m) string

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

id (m) string

host (m) hostname or IP

mysql-username (m) username

mysql-password (m) password

database (m) string

characters.

Hostname or IP of a server running a MySQL database to connect to.

User name for connecting to MySQL database.

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 URL

service string Description of the service

http://wap.company.com

IP address of your WAP gateway

ipaddress IP

Phone number used to establish

phonenumber phone-number

the PPP connection

Connection speed: 9600 or

speed number

14400. Defaults to 9600.

Bearer type: data or sms.

bearer string

Defaults to data.

Call type: isdn or analog.

calltype string

Defaults to isdn.

Connection type: cont or temp. Cont uses TCP port 9201 and Temp uses UDP port 9200.

connection string

Defaults to cont.

Enable CHAP authentication if

pppsecurity on or off

set to on, PAP otherwise

normal or secure. Indicates wether WTLS should be used or

authentication

secret string Login password

not. Defaults to normal.

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 login = wapusr 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

name string Description of the service

http://wap.company.com

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 user) string

Username or account name. Must be username of the one ’sendsms-user’ group in the Kannel conﬁguration, or results in ’Authorization failed’ reply.

password (or pass) string

from string

to phone number list

text string

charset string

udh string

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.

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.

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

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

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.

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

smsc string

flash number Deprecated. See mclass.

not set otherwise.

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

mclass number

Toolkit.

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

mwi number

option. a

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,

coding number

which sets coding to 8bits.

validity number (minutes)

deferred number (minutes)

dlrmask number (bit mask)

dlrurl string (url)

pid byte

alt-dcs number

rpi number

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.

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.

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.

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

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.

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

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.

accounting.

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

otaid string

username string

password string

to number

from string

smsc string

text XML document

type string

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 sended to the phone.

Username of the ’sendsms-user’ group in Kannel conﬁguration, that has been conﬁgured to send OTA messages.

Password associated with given

username. Must match

corresponding ﬁeld in ’sendsms-user’ group in Kannel conﬁguration, or ’Authorization failed’ is returned.

Number of the phone that is to receive the OTA conﬁguration message.

An URL encoded XML document, containing either settings or bookmarks.

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 Value Description

Mandatory value. Tells that we

group ppg

ppg-port number

ppg-ssl-port (o) number

ssl-server-cert-file string

are conﬁguring the PPG group.

The port PPG is listening at. Default 8080.

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.

Mandatory value for PPG HTTPS support. The ﬁle containing server’s ssl certiﬁcate.

Chapter 7. Setting up Push Proxy Gateway

Variable Value Description

Mandatory value for PPG HTTPS support. The ﬁle containing server’s ssl private

ssl-server-key-file string

key.

URL locating PPG services.

ppg-url url

Default /wappush .

Sender phone number required

global-sender string

by some protocols.

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

users number

1024.

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

trusted-pi boolean

be present).

PPG will not accept pushes from these IPs. Wildcards are allowed. If this attribute is missing, no IP

ppg-deny-ip ip-list

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

ppg-allow-ip ip-list

mentioned are denied, too.

If no SMSC ID is given with the wappush HTTP request (see below), use this one as default

default-smsc string

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

group wap-push-user

are conﬁguring the users group.

(More) human readable name of

wap-push-user string

ppg-username string Username for this user.

ppg-password string Password for this user.

an user.

Phone number preﬁxes allowed in pushes coming from this pi. These preﬁxes must conform international phone number

allowed-prefix number-list

format.

Phone number preﬁxes denied in pushes coming from this pi. These preﬁxes must conform international phone number

denied-prefix number-list

format.

Deﬁnes an url wherefrom the whitelist can be fetched. White list itself contains list of phone numbers accepting pushes from

white-list url

this pi.

Deﬁnes an url wherefrom the blacklist can be fetched. Blacklist itself contains list of phone number not accepting

black-list url

pushes from this pi.

Deﬁnes ips wherefrom this pi can do pushes. Adding this list means that ips not mentioned are

allow-ip ip-list

denied.

Variable Value Description

deny-ip ip-list

default-smsc string

forced-smsc string

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.

Chapter 7. Setting up Push Proxy Gateway

Deﬁnes ips wherefrom this pi cannot do pushes. Ips not mentioned in either list are denied, too.

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.

Allow only routing to a deﬁned SMSC ID for this speciﬁc push user.

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

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:

Chapter 7. Setting up Push Proxy Gateway

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="9fjeo39jf084@pi.com">

</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 devel@kannel.3glab.org. To subscribe, send mail to devel-subscribe@kannel.3glab.org (mailto:devel-subscribe@kannel.3glab.org). This is currently the best location for asking help and reporting bugs. Please include conﬁguration ﬁle and version number.

Nokia WAP and SMS gateway User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Table of Contents

List of Tables

Chapter 1. Introduction

Overview of WAP

Overview of WAP Push

Overview of SMS

Features

Requirements

Chapter 2. Installing the gateway

Getting the source code

Finding the documentation

Compiling the gateway

Installing the gateway

Installing Kannel from RPM packages

Installing Kannel from DEB packages

Chapter 3. Using the gateway

Running Kannel

Starting the gateway

Command line options

Kannel statuses

HTTP administration

Chapter 4. Setting up a WAP gateway

Running WAP gateway

Checking whether the WAP gateway is alive

Chapter 5. Setting up a SMS Gateway

Required components

SMS centers

Nokia CIMD 1.37 and 2.0

CMG UCP/EMI 4.0

SMPP 3.4

Sema Group SMS2000 OIS 4.0 and 5.0

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

GSM modem

GSM modem 2

Fake SMSC

Using multiple SMS centers

Feature checklist

Smsbox routing inside bearerbox

Extended headers

Kannel POST

XML Post

External delivery report (DLR) storage

Internal DLR storage

MySQL DLR storage

LibSDB DLR storage

Setting up more complex services

Redirected replies

Running SMS gateway

Using the HTTP interface to send SMS messages

GET method for the OTA HTTP interface

Chapter 7. Setting up Push Proxy Gateway

Running a push proxy gateway

An example using HTTP SMSC

An example push (tokenised SI) document

Default network and bearer used by push proxy gateway

Chapter 8. Using SSL for HTTP

Using SSL client support

Using SSL server support for the administration HTTP interface

Using SSL server support for the sendsms HTTP interface

Using SSL server support for PPG HTTPS interface

Chapter 9. Delivery Reports

Chapter 10. Getting help and reporting bugs