Kannel 1.1.5 User's Guide

This chapter introduces WAP and SMS in general terms, and explains the role of the gateway in WAP and SMS, outlining their duties and features. It also explains why the Kannel project was started in the first place, and why it is open source.

With hundreds of millions of mobile phones in use all over the world, the market for services targeted at mobile users is mind-bogglingly immense. Even simple services find plenty of users, as long as they're useful or fun. Being able to get news, send e-mail or just be entertained wherever you are is extremely attractive to many.

The hottest technology for implementing mobile services is WAP, short for Wireless Application Protocol. It lets the phone act as a simple web browser, but optimizes the markup language, scripting language, and the transmission protocols for wireless use. The optimized protocols are translated to plain old HTTP by a WAP gateway.

Kannel is an open source WAP gateway. It attempts to provide this essential part of the WAP infrastructure freely to everyone so that the market potential for WAP services, both from wireless operators and specialized service providers, will be realized as efficiently as possible.

Kannel also works as an SMS gateway for GSM networks. Almost all GSM phones can send and receive SMS messages, so this is a way to serve many more clients than just those using a new WAP phone.

Open Source is a way to formalize the principle of openness by placing the source code of a product under a Open Source compliant software license. The BSD license was chosen over other Open Source licenses by the merit of placing the least amount of limitations on what a third party is able to do with the source code. In practice this means that Kannel is going to be a fully-featured WAP implementation and compatible with the maximum number of bearers with special emphasis on SMSC compatibility. The Kannel project was founded by Wapit Ltd. in June, 1999.

Overview of WAP

WAP, short for Wireless Application Protocol, is a collection of various languages and tools and an infrastructure for implementing services for mobile phones. Traditionally such services have worked via normal phone calls or short textual messages (e.g., SMS messages in GSM networks). Neither are very efficient to use, nor very user friendly. WAP makes it possible to implement services similar to the World Wide Web.

Unlike marketers claim, WAP does not bring the existing content of the Internet directly to the phone. There are too many technical and other problems for this to ever work properly. The main problem is that Internet content is mainly in the form of HTML pages, and they are written in such way that they require fast connections, fast processors, large memories, big screens, audio output and often also fairly efficient input mechanisms. That's OK, since they hopefully work better for traditional computers and networks that way. However, portable phones have very slow processors, very little memory, abysmal and intermittent bandwidth, and extremely awkward input mechanisms. Most existing HTML pages do not work on mobiles phones, and never will.

WAP defines a completely new markup language, the Wireless Markup Language (WML), which is simpler and much more strictly defined than HTML. It also defines a scripting language, WMLScript, which all browsers are required to support. To make things even simpler for the phones, it even defines its own bitmap format (Wireless Bitmap, or WBMP).

HTTP is also too inefficient for wireless use. However, by using a semantically similar binary and compressed format it is possible to reduce the protocol overhead to a few bytes per request, instead of the usual hundreds of bytes. Thus, WAP defines a new protocol stack to be used. However, to make things simpler also for the people actually implementing the services, WAP introduces a gateway between the phones and the servers providing content to the phones.

Figure 1-1. Logical position of WAP gateway 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 SMS

SMS, short messaging service, is a way to send short (160 character) messages from one GSM phone to another. It can also be used to send operator logos, ringing tones, business cards and phone configurations.

SMS services are content services initiated by SMS message to certain (usually short) phone number, which then answers with requested content, if available.

When SMS services are used, the client (mobile terminal) sends an SMS message to certain number, usually a very short specialized number, which points to specific SMS center responsible for that number (plus possibly many others). This SMS center then sends the message onward to specified receiver in intra- or Internet, using an SMS center specific protocol. For example, a Nokia SMS center uses CIMD protocol.

As practically every different kind of SMS center uses different protocol, an SMS gateway is used to handle connections with SMS centers and to relay them onward in an unified form.

Figure 1-2. Logical position of SMS gateway between a phone and a content server.

An SMS gateway can also be used to relay SMS messages from one GSM network to another, if the networks do not roam messages normally.

Kannel works as an SMS gateway, talking with many different kind of SMS centers, and relaying the messages onward to content providers, as HTTP queries. Content providers then answer to this HTTP query and the answer is sent back to mobile terminal, with appropriate SMS center connection using SMS center specific protocol.

In addition to serving mobile originated (MO) SMS messages Kannel also works as an SMS push gateway - content providers can request Kannel to send SMS messages to terminals. Kannel then determines the correct SMS center to relay the SMS message and sends the SMS message to that SMS center, again using SMS center specific protocol. This way the content provider does not need to know any SMS center specific protocol, just unified Kannel SMS sending interface.

Features

This section needs to be written.

Requirements

Kannel is being developed on Linux systems (Red Hat 6.1 and Debian potato), 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.
The Gnome XML library (known as gnome-xml and libxml), version 2.2.0 or newer. See http://xmlsoft.org/xml.html.
GNU Make.
Posix threads (pthread.h).
GNU Bison 1.28 if you modify the WMLScript compiler.
DocBook markup language tools (jade, jadetex, DocBook stylesheets, etc; see README.docbook), if you want to format the documentation (pre-formatted versions are available).

Hardware requirements are fluffier. We haven't benchmarked Kannel yet, so there are no hard numbers, but a reasonably fast PC workstation (400 MHz Pentium II, 128 MB RAM) should serve several concurrent users or tens of SMS messages per second without problems.

Chapter 2. Installing the gateway

This chapter explains how the gateway can be installed, either from a source code package or by using a pre-compiled binary version. The goal of this chapter is to get the gateway compiled and all the files in the correct places; the next chapter will explain how the gateway is configured.

Getting the source code

The source code to Kannel is available for download at http://www.kannel.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:

User's Guide, i.e., the one you're reading at the moment.
Architecture and Design, in doc/arch or at http://www.kannel.org/arch.shtml
The README and various other text files in the source tree.

We intend to cover everything you need to install and use Kannel is in User's Guide, but the guide is still incomplete in this respect. Similarly, the Architecture and Design document should tell you everything you need to know to dive into the sources and quickly make your own modifications. It's not a replacement for actually reading the source code, but it should work as a map to the source code. The README is not supposed to be very important, nor contain much information. Instead, it will just point at the other documentation.

You need the following tools to compile Kannel:

C compiler and libraries for ANSI C, with normal Unix extensions such as BSD sockets.
An implementation of POSIX threads (pthread.h).
GNU Bison 1.28, if you want to modify the WMLScript compiler (a pre-generated parser is included for those who just want to compile Kannel).
DocBook processing tools: DocBook stylesheets, jade, jadetex, etc; see README.docbook for more information (pre-formatted versions of the documentation are available, and you can compile Kannel itself even without the documentation tools).
GNU autoconf, if you want to modify the configuration script.

Compiling the gateway

If you are using Kannel on a supported platform, or one that is similar enough to one, compiling Kannel is trivial. After you have unpacked the source package of your choosing, or after you have checked out the source code from CVS, enter the following commands:

./configure
make

The configure script investigates various things on your computer for the Kannel compilation needs, and writes out the Makefile used to compile Kannel. make then runs the commands to actually compile Kannel.

If either command writes out an error message and stops before it finishes its job, you have a problem, and you either need to fix it yourself, if you can, or report the problem to the Kannel project. See Chapter 7 for details.

For detailed instruction on using the configuration script, see file INSTALL. That file is a generic documentation for configure. Kannel defines a few additional options:

--with-defaults=type Set defaults for the other options. type is either speed or debug. The default is debug.
--enable-docs 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-debug Enable non-reentrant development time debugging of WMLScript compiler.
--enable-localtime Write log file time stamps in local time, not GMT.
--disable-assertions Turn off runtime assertion checking. This makes Kannel faster, but gives less information if it crashes.
--with-malloc=type Select memory allocation module to use: type is native, checking (the default), or slow. For production use you probably want native. The slow module is more thorough than checking, but much slower.
--enable-mutex-stats Produce information about lock contention.
--enable-start-stop-daemon Compile the start-stop-daemon program.
--enable-pam Enable using PAM for authentication of sendsms users for smsbox.

You may need to add compilations flags to configure:

CFLAGS='-pthread' ./configure

The above, for instance, seems to be required on FreeBSD. If you want to develop Kannel, you probably want to add CFLAGS that make your compiler use warning messages. For example, for GCC:

CFLAGS='-Wall -O2 -g' ./configure

(You may, at your preference, use even stricter checking options.)

Installing the gateway

After you have compiled Kannel, you need to install certain programs in a suitable place. This is most easily done by using make again:

make bindir=/path/to/directory install

Replace /path/to/directory with the pathname of the actual directory where the programs should be installed. The programs that are installed are (as filenames from the root of the source directory):

gw/bearerbox

gw/smsbox

gw/wapbox

The version number of the gateway is added to the file names during installation. This makes it easier to have several versions installed, and makes it easy to go back to an older version if the new version proves problematic.

Kannel consists of three programs called boxes: the bearer box is the interface towards the phones. It accepts WAP and SMS messages from the phones and sends them to the other boxes. The SMS box handles SMS gateway functionality, and the WAP box handles WAP gateway functionality. There can be several SMS boxes and several WAP boxes running and they don't have to run on the same host. This makes it possible to handle much larger loads.

Using pre-compiled binary packages

Installing Kannel from RPM packages

This chapter explains how to install, upgrade and remove Kannel binary RPM packages.

Before you install Kannel, check that you have libxml2 installed on your system:

rpm -q libxml2

Installing Kannel

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

2. Log in as root:

su -

3. Install the RPM package:

rpm -ivh kannel-VERSION.i386.rpm

Upgrading Kannel

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

2. Log in as root

3. Upgrade the RPM package:

rpm -Uvh kannel-VERSION.i386.rpm

Removing Kannel

1. Log in as root:

2. Remove the RPM package:

rpm -e kannel

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

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

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

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

If Kannel is already running and you just want to quickly stop and start the gateway,e.g.to set a new configuration option, run the script with the restart parameter.

	/etc/rc.d/init.d/kannel restart

If you want Kannel to run as a daemon, you need to add a symbolic link to the Kannel script from the runlevel you want Kannel to run in. E.g. to run Kannel in runlevel 5 add symbolic links to /etc/rc.d/rc5.d/.

	cd /etc/rc.d/rc5.d/

	ln -s ../init.d/kannel S91kannel

	ln -s ../init.d/kannel K91kannel

To run Kannel as a SMS gateway you need to edit the configuration file which is at /etc/kannel/kannel.conf. In the same directory there is an example file called smskannel.conf. It has some basic examples of the configuration groups needed to run Kannel as a SMS gateway. For more detailed information please read the section "SMS gateway configuration" later in this same document.

The logging is disabled by default and you can enable it from the kannel.conf file. Just add the log-file option to the group of which box you want to log.

The documentation will be installed at /usr/share/doc/kannel-VERSION/ or /usr/doc/kannel-VERSION/ depending on if you used the RedHat 7.x or 6.x package.

In the Kannel documentation directory there is a html file called control.html. It is an example file that shows how to use the Kannel http administration interface. It also has a template for sending SMS messages.

Chapter 3. Using the gateway

This chapter explains how the gateway core, bearerbox, is configured and used. It covers the configuration file, keeping an eye on the gateway while it is running, and using the HTTP interface to control the gateway.

After this chapter there is distinct chapter for each kind of gateway use: WAP gateway, SMS gateway and combined gateway. These chapters explain the configuration and other aspects of gateway of that type.

There is only one configuration file for all parts of Kannel, although when Kannel is distributed to several hosts some lines from the configuration file can be removed in some hosts.

Configuring the gateway

The configuration file can be divided into three parts: bearerbox configurations, smsbox configurations and wapbox configurations. Bearerbox part has one 'core' group and any used SMS center groups, while wapbox part has only one wapbox group. In smsbox part there is one smsbox group and then number of sms-service and sendsms-user groups.

Details of each part are in an appropriate section of this documentation. The 'core' group used by the bearerbox is explained in this chapter, while 'wapbox' part is in the next chapter and 'smsbox', 'smsc' (SMS center), 'sms-service' and 'sendsms-user' groups are in the SMS Kannel chapter.

Configuration file syntax

A configuration file consists of groups of configuration variables. Groups are separated by empty lines, and each variable is defined on its own line. Each group in Kannel configuration is distinguished with a group variable. Comments are lines that begin with a number sign (#) and are ignored (they don't, for example, separate groups of variables).

A variable definition line has the name of the variable, and equals sign (=) and the value of the variable. The name of the variable can contain any characters except whitespace and equals. The value of the variable is a string, with or without quotation marks () around it. Quotation marks are needed if the variable needs to begin or end with whitespace or contain special characters. Normal C escape character syntax works inside quotation marks.

Perhaps an example will make things easier to comprehend:

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

The above snippet defines the keyword nop for an SMS service, and a default action for situation when the keyword in the SMS message does not match any defined service.

Lines 1 and 6 are comment lines. Line 5 separates the two groups. The remaining lines define variables. The group type is defined by the group variable value.

The various variables that are understood in each type of configuration group are explained below.

Some variable values are marked as 'bool'. The value for variable can be like true, false, yes, no, on, off, 0 or 1. Other values are treated as 'true' while if the variable is not present at all, it is treated as being 'false'.

Core configuration

Configuration for Kannel MUST always include a group for general bearerbox configuration. This group is named as 'core' in configuration file, and should be the first group in the configuration file.

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

group = core
admin-port = 13000
admin-password = f00bar

Naturally this is not sufficient for any real use, as you want to use Kannel as an SMS gateway, or WAP gateway, or both. Thus, one or more of the optional configuration variables are used. In following list (as in any other similar lists), all mandatory variables are marked with (m), while conditionally mandatory (variables which must be set in certain cases) are marked with (c).

Table 3-1. Core Group Variables

Variable	Value	Description
`group (m)`	`core`	This is a mandatory variable
`admin-port (m)`	port-number	The port number in which the bearerbox listens to HTTP administration commands. It is NOT the same as the HTTP port of the local www server, just invent any port, but it must be over 1023 unless you are running Kannel as a root process (not recommended)
`admin-password (m)`	string	Password for HTTP administration commands (see below)
`status-password`	string	Password to request Kannel status. If not set, no password is required, and if set, either this or `admin-password` can be used
`admin-deny-ip`	IP-list	These lists can be used to prevent connection from given IP addresses. Each list can have several addresses, separated with semicolons (';'). An asterisk ('') can be used as a wildcard in a place of any ONE number, so ...* matches any IP.
`admin-allow-ip`	IP-list
`smsbox-port (c)`	port-number	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 traffic.
`wapbox-port (c)`	port-number	Like smsbox-port, but for wapbox-connections. If not set, Kannel cannot handle WAP traffic
`box-deny-ip`	IP-list	These lists can be used to prevent box connections from given IP addresses. Each list can have several addresses, separated with semicolons (';'). An asterisk ('') can be used as a wildcard in place of any ONE number, so ...* matches any IP.
`box-allow-ip`	IP-list
`udp-deny-ip`	IP-list	These lists can be used to prevent UDP packets from given IP addresses, thus preventing unwanted use of the WAP gateway. Used the same way as `box-deny-ip` and `box-allow-ip`.
`udp-allow-ip`	IP-list
`wdp-interface-name (c)`	IP or '*'	If this is set, Kannel listens to WAP UDP packets incoming to ports 9200-9208, bound to given IP. If no specific IP is needed, use just an asterisk ('*'). If UDP messages are listened to, wapbox-port variable MUST be set.
`log-file`	filename	A file in which to write a log. This in addition to `stdout` and any log file defined in command line. Log-file in 'core' group is only used by the bearerbox.
`log-level`	number 0..5	Minimum level of logfile events logged. 0 is for 'debug', 1 'info', 2 'warning, 3 'error' and 4 'panic' (see Command Line Options)
`access-log`	filename	A file in which information about received/sent SMS messages is stored. Access-log in 'core' group is only used by the bearerbox.
`unified-prefix`	prefix-list	String to unify received phone numbers, for SMSC routing and to ensure that SMS centers can handle them properly. This is applied to 'sender' number when receiving SMS messages from SMS Center and for 'receiver' number when receiving messages from SMSbox (either sendsms message or reply to original message). Format is that first comes the unified prefix, then all prefixes which are replaced by the unified prefix, separated with comma (','). For example, for Finland an unified-prefix "+358,00358,0;+,00" should do the trick. If there are several unified prefixes, separate their rules with semicolon (';'), like "+35850,050;+35840,040". Note that prefix routing is next to useless now that there are SMSC ID entries
`white-list`	URL	Load a list of accepted senders of SMS messages. If a sender of an SMS message is not in this list, any message received from the SMS Center is discarded. See notes of phone number format from numhash.h header file. NOTE: the system has only a precision of last 9 or 18 digits of phone numbers, so beware!
`black-list`	URL	As white-list, but SMS messages from these numbers are automatically discarded
`store-file`	filename	A file in which any received SMS messages are stored until they are successfully handled. By using this variable, no SMS messages are lost in Kannel, but theoretically some messages can duplicate when system is taken down violently. Does not support sendsms messages yet!
`http-proxy-host`	hostname	Enable the use of an HTTP proxy for all HTTP requests.
`http-proxy-port`	port-number	Enable the use of an HTTP proxy for all HTTP requests.
`http-proxy-exceptions`	URL-list	A list of excluded hosts from being used via a proxy. Separate each entry with space.
`http-proxy-username`	username	Username for authenticating proxy use, for proxies that require this.
`http-proxy-password`	URL-list	Password for authenticating proxy use, for proxies that require this.
`ssl-certkey-file`	ssl-certkey-file	A PEM encoded SSL certificate and private key file to be used with SSL connections.

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 configuration file for your taste, you can either run Kannel from command line or use supplied start-stop-daemon and run_kannel_box programs to use it as a daemon service (more documentation about that later).

If you cannot or do not know how to set up daemon systems or just want to test Kannel, you probably want to start it from command line. This means that you probably want to have one terminal window for each box you want to start (xterm or screen will do fine). To start the bearerbox, give the following command:

./bearerbox -v 1 [conffile]

The -v 1 sets the logging level to INFO. This way, you won't see a large amount of debugging output (the default is DEBUG). Full explanation of Kannel command line arguments is below.

[conffile] is the name of the configuration file you are using with Kannel. The basic distribution packet comes with two sample configuration files, smskannel.conf and wapkannel.conf (in gw subdirectory), of which the first one is for testing out SMS Kannel and the second one for setting up a WAP Kannel. Feel free to edit those configuration files to set up your own specialized system.

After the bearer box, you can start the WAP box:

./wapbox -v 1 [conffile]

or the SMS box:

./smsbox -v 1 [conffile]

or both, of course. The order does not matter, except that you need to start the bearer box before the other boxes. Without the bearer box, the other boxes won't even start.

Command line options

Bearerbox, smsbox and wapbox each accept certain command line options and arguments when they are launched. These arguments are:

Table 3-2. Kannel Command Line Options

`-v <level>`	Set verbosity level for stdout (screen) logging. Default is 0, which means 'debug'. 1 is 'info, 2 'warning', 3 'error' and 4 'panic'
`--verbosity <level>`
`-D <places>`	Set debug-places for 'debug' level output.
`--debug <places>`
`-F <file-name>`	Log to file named file-name, too. Does not overrun or affect any logfile defined in configuration file.
`--logfile <file-name>`
`-V <level>`	Set verbosity level for that extra logfile (default 0, which means 'debug'). Does not affect verbosity level of the logfile defined in configuration file, not verbosity level of the `stdout` output.
`--fileverbosity <level>`
`-S`	Start the system initially at SUSPENDED state (see below, bearerbox only)
`--suspended`
`-I`	Start the system initially at ISOLATED state (see below, bearerbox only)
`--isolated`
`-H`	Only try to open HTTP sendsms interface; if it fails, only warn about that, do not exit. (smsbox only)
`--tryhttp`

Kannel statuses

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

Running. The gateway accepts, proceeds and relies messages normally. This is the default state for the bearerbox.
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.
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.
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

The state can be changed via HTTP administration interface (see below), and shutdown can also be initiated via TERM or INT signal from terminal. In addition, the bearerbox can be started already in suspended or isolated state with -S or -I command line option, see above.

HTTP administration

Kannel can be controlled via an HTTP administration interface. All commands are done as normal HTTP queries, so they can be easily done from command line like this:

% lynx -dump "http://localhost:12345/shutdown?password=bar"

...in which the '12345' is the configured admin-port in Kannel configuration file (see above). For most commands, admin-password is required as a argument as shown above. In addition, HTTP administration can be denied from certain IP addresses, as explained in configuration chapter.

Note that you can use these commands with WAP terminal, too, but if you use it through the same Kannel, replies to various suspend commands never arrive nor can you restart it via WAP anymore.

Table 3-3. Kannel HTTP Administration Commands

`status`	Get the current status of the gateway. 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 supplied.
`suspend`	Set Kannel state as 'suspended' (see above). Password required.
`isolate`	Set Kannel state as 'isolated' (see above). Password required.
`resume`	Set Kannel state as 'running' if it is suspended or isolated. Password required.
`shutdown`	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.

Chapter 4. Setting up a WAP gateway

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

WAP gateway configuration

To set up a WAP Kannel, you have to edit the 'core' group in the configuration file, and define 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 configuration file wapkannel.conf is supplied. You may want to take a look at that when setting up a WAP Kannel.

Wapbox configuration

If you have set wapbox-port variable in the 'core' configuration 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
`bearerbox-host (m)`	`hostname`	The machine in which the bearerbox is.
`timer-freq`	value-in-seconds	The frequency of how often timers are checked out. Default is 1
`map-url`	URL-pair	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 prefix Is matched against the incoming URL. Whenever the prefix 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 prefix, 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 "http://destination/some/path"
`map-url-max`	number	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-0`	URL-pair	Adds a mapping for the left side URL to the given destination URL. Repeat these lines, with 0 replaced by a number up to map-url-max, if you need several mappings.
`device-home`	URL	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* http://some.where/*"
`log-file`	filename	As with bearerbox 'core' group.
`log-level`	number 0..5	As with bearerbox 'core' group.
`syslog-level`	number	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` to 'none'.

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 configuration 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 configuration

To set up a SMS Kannel, you have to edit the 'core' group in the configuration file, and define 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 configuration file 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 configuration file. This group must include all the data needed to connect that SMS center. You may also want to define an ID (identification) 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-define sms-services nor routing systems if the IP of the SMS Center is changed, for example.

Common 'smsc' group variables are defined in the following table. The first two (group and smsc) are mandatory, but rest can be used if needed.

Table 5-1. SMSC Group Variables

Variable	Value	Description
`group (m)`	`smsc`	This is a mandatory variable
`smsc (m)`	`string`	Identifies the SMS center type. See below for a complete list.
`smsc-id`	`string`	An optional name or id for the smsc. Any string is acceptable, but semicolon ';' may cause problems, so avoid it and any other special non-alphabet characters. This 'id' is written into log files 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 configuration variables `denied-smsc-id`, `allowed-smsc-id` and `preferred-smsc-id` is used for that.
`denied-smsc-id`	`id-list`	SMS messages with SMSC ID equal to any of the IDs in this list are never routed to this SMSC. Multiple entries are separated with semicolons (';')
`allowed-smsc-id`	`id-list`	This list is opposite to previous: only SMS messages with SMSC ID in this list are ever routed to this SMSC. Multiple entries are separated with semicolons (';')
`preferred-smsc-id`	`id-list`	SMS messages with SMSC ID from this list are sent to this SMSC instead than to SMSC without that ID as preferred. Multiple entries are separated with semicolons (';')
`denied-prefix`	`prefix-list`	A list of phone number prefixes which are NOT accepted to be sent through this SMSC. Multiple entries are separated with semicolon (';'). For example, "040;050" prevents sending of any SMS message with prefix of 040 or 050 through this SMSC
`preferred-prefix`	`prefix-list`	As `denied-prefix`, but SMS messages with receiver starting with any of these prefixes is preferably sent through this SMSC. In a case of multiple preferences, one is selected at random (also if there are preferences, SMSC is selected randomly)
`alt-charset`	`number`	As some SMS Centers do not follow the standards in character coding, an `alt-charset` kludge is presented. Currently implemented alternative charsets are defined in "alt_charsets.h" and new ones can be added to appropriate smsc-code.

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 configuration group for each. Note that many of them use variables with same name, but most also have some specific variables.

NOTE: SMS center configuration 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.

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 configured for that. It also expects the SMSC to automatically send stored messages as soon as Kannel logs in (this is the normal configuration).

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
`host (m)`	`hostname`	Machine that runs the SMSC. As IP (100.100.100.100) or hostname (their.machine.here)
`port (m)`	`port-number`	Port number in the smsc host machine
`smsc-username (m)`	`string`	Username in the SMSC machine/connection account
`smsc-password (m)`	`string`	Password in the SMSC machine needed to contact SMSC
`keepalive`	`number`	SMSC connection will not be left idle for longer than this many minutes. The right value to use depends on how eager the SMSC is to close idle connections. 5 minutes is a good guess. If you see many unexplained reconnects, try lowering this value. Set it to 0 to disable this feature.
`sender-prefix`	`string`	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 prefix from the sender number so that the SMSC will add it again. If the prefix was not present, Kannel will log a warning and will not send the sender number. If `sender-prefix` is not set, or is set to `"never"`, then Kannel will not send the sender number to the SMSC at all. If you want Kannel to pass all sender numbers to the SMSC unchanged, then just set `sender-prefix` to the empty string `""`.

CMG UCP/EMI 3.5

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 configurations 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
our-port = 600 (optional bind in our end)
receive-port = 700 (the port in which the SMSC will contact)

group = smsc
smsc = emi
host = 100.102.100.102
phone = ...
device = /dev/tty0
smsc-username = foo
smsc-password = bar

Variable	Value	Description
`host (c)`	`hostname`	Machine that runs SMSC. As IP (100.100.100.100) or hostname (their.machine.here)
`port (c)`	`port-number`	Port number in the SMSC host machine
`smsc-username (m)`	`string`	Username in the SMSC machine/connection account
`smsc-password (m)`	`string`	Password in the SMSC machine needed to contact SMSC
`device (c)`	`device-name`	The device the modem is connected to, like `/dev/ttyS0`. ISDN connection only.
`phone (c)`	`string`	Phone number to dial to, when connecting over a modem to an SMS center.
`our-port`	`port-number`	Optional port number in which to bind the connection in our end. TCP/IP connection only.
`receive-port`	`port-number`	The port number we have to listen to and to which the SMS center connects when it has messages to send. TCP/IP connection only.
`connect-allow-ip`	`IP-list`	If set, only connections from these IP addresses are accepted to receive-port. TCP/IP connection only.

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 configuration:

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
`host (m)`	`hostname`	Machine that runs SMSC. As IP (100.100.100.100) or hostname (their.machine.here)
`port (m)`	`port-number`	The port number for the TRANSMITTER connection to the SM-SC. May be the same as receive-port.
`receive-port`	`port-number`	The port number for the RECEIVER connection to the SM-SC. May be the same as port.
`smsc-username (m)`	`string`	The 'username' of the Messaging Entity connecting to the SM-SC. If the SM-SC operator reports that the "TELEPATH SYSTEM MANAGER TERMINAL" view "Control.Apps.View" value "Name:" is "SMPP_ZAPVMA_T" for the transmitter and "SMPP_ZAPVMA_R" for the receiver the smsc-username value is accordingly "SMPP_ZAP". Note that this used to be called system-id (the name in SMPP documentation) and has been changed to smsc-username to make all Kannel SMS center drivers use the same name.
`smsc-password (m)`	`string`	The password matching the "smsc-username" your teleoperator provided you with.
`system-type (m)`	`string`	Usually you can get away with "VMA" which stands for Voice Mail Activation.
`address-range (m)`	`string`	According to the SMPP 3.4 spec this is supposed to affect which MS's can send messages to this account. Doesn't seem to work, though.

Sema Group SMS2000 OIS 4.0 and 5.0

The 4.0 implementation is over Radio PAD (X.28). Following configuration variables are needed, and if you find 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)
 #       The address of an SMSC for Sema SMS2000 protocols using an X.28 
 #       connection.
home_nua = (x121 radio pad address)
 #       The address of a radio PAD implementing Sema SMS2000 using X.28 
 #       connection.
 #
wait_report = 0/1 (0 means false, 1 means true)
 #       Report indicator used by the Sema SMS2000 protocol. Optional.

group = smsc
smsc = ois
host = 103.102.101.100
port = 10000
receive-port = 10000 (the port in which the SMSC will contact)
ois-debug-level = number 0 to 8  (extra debug, optional, see smsc_ois.c)

GSM modem

Kannel can use a GSM modem as an SMS center.

group = smsc
smsc = at
modemtype = wavecom
device = /dev/ttyS0
pin = 2345

Variable	Value	Description
`modemtype`	`string`	Modems from different manufacturers have slightly different behaviour. We need to know what type of modem is used. Supported types are: `wavecom`, `premicell`, `siemens`.
`device (m)`	`device-name`	The device the modem is connected to, like `/dev/ttyS0`.
`pin`	`string`	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.
`validityperiod`	`integer`	How long the message will be valid, i.e., how long the SMS center (the real one, not the phone acting as one for Kannel) will try to send the message to the recipient. Encoded as per the GSM 03.40 standard, section 9.2.3.12. Default is 167, meaning 24 hours.

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.

group = smsc
smsc = fake
port = 10000
connect-allow-ip = 127.0.0.1

Variable	Value	Description
`host (m)`	`hostname`	Machine that runs the SMSC. As IP (100.100.100.100) or hostname (their.machine.here)
`port (m)`	`port-number`	Port number in smsc host machine
`connect-allow-ip`	`IP-list`	If set, only connections from 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
username = nork
password = z0rK
port = 13015
send-url = "http://localhost:20022"

Variable	Value	Description
`system-type (m)`	`string`	Type of HTTP connection. 'kannel' is only system currently supported.
`send-url (m)`	`url`	Location to send MT messages. This URL is expanded by used system, if need to.
`port (m)`	`port-number`	Port number in which Kannel listens to (MO) messages from other gateway
`connect-allow-ip`	`IP-list`	IPs allowed to use this interface. If not set, "127.0.0.1" (localhost) is the only host allowed to connect.
`username`	`string`	Username associated to connection, if needed. 'kannel' requires this, and it is the same as send-sms username at other end.
`password`	`string`	Password for username, if needed.

Using multiple SMS centers

If you have several SMS center connections (multiple operators or a number of GSM modems) you need to configure one smsc group per SMS center (or GSM modem). When doing this, you might want to use routing systems to rout messages to specific centers - for example, you have 2 operator SMS centers, and the other is much faster and cheaper to use.

To set up routing systems, first 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.

Some of the items are not really features, but rather the absence of specific bugs that seem to show up often.

Table 5-2. SMSC driver features

Feature	cimd	cimd2	emi	emi_ip	emi2	smpp	sema	ois	at	http	fake
Can send octet data without UDH
	n	y?	y?	y?	y?	n	n	y?	y?	n	y?[a]
Can send unicode messages
	n	n	n	n	n	n	n	n	n	n	n
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
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	N[c]	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 keep idle connections alive
	n	y?	n	n	?	y?	?	?	?	?	?
Can shut down idle connections
	n	n	n	n	?	n	?	?	?	?	?
Can set validity period
	n	n	n	n	n	n	n	n	y?	n	n
Can set arbitrary data coding scheme
	n	n	n	n	n	n	n	n	n	n	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

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 configuration

You must define an 'smsbox' group into the configuration file 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 define 'sendsms-port' to be able to use SMS push.

Table 5-3. Smsbox Group Variables

Variable	Value	Description
`group (m)`	`smsbox`	This is a mandatory variable
`bearerbox-host (m)`	`hostname`	The machine in which the bearerbox is.
`sendsms-port (c)`	port-number	The port in which any sendsms HTTP requests are done. As with other ports in Kannel, can be set as anything desired.
`sendsms-chars`	string	Only these characters are allowed in 'to' field when send-SMS service is requested via HTTP. Naturally, you should allow at least `0123456789`. The space character (' ') has special meaning: it is used to separate multiple phone numbers from each other in multi-send. To disable this feature, do not have it as an accepted character. If this variable is not set, the default set `"0123456789 +-"` is used.
`global-sender`	phone-number	If set, all sendsms originators are set as these before proceeding. Note that in a case of most SMS centers you cannot set the sender number, but it is automatically set as the number of SMSC
`log-file`	filename	As with the bearerbox 'core' group. Access-log is used to store information about MO and send-sms requests. Can be named same as the 'main' access-log (in 'core' group).
`log-level`	number 0..5
`access-log`	filename

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"
log-level = 0

SMS-service configurations

Now that you have an SMS center connection to send and receive SMS messages you need to define services for incoming messages. This is done via 'sms-service' configuration groups.

These groups define SMS services in the smsbox, so they are only used by the smsbox. Each service is recognized from the first word in an SMS message and by the number of arguments accepted by the service configuration (unless catch-all configuration 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 first 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 fit 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 define default service.

Table 5-4. SMS-Service Group Variables

Variable	Value	Description
`group (m)`	`sms-service`	This is a mandatory variable
`keyword (m)`	word	Services are identified by the first 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' fields in the URL. This allows you to configure the gateway to use different URLs for the same keyword depending on the number of words the SMS message contains.
`aliases`	word-list	If the service has aliases, they are listed as a list with each entry separated with a semicolon (';')
`get-url (c)`	URL	Requested URL. The url can include a list of parameters, which are parsed before the url is fetched. See below for these parameters. Also works with plain 'url'
`post-url (c)`	URL	Requested URL. As above, but request is done as POST, not GET. Always matches the keyword, regardless of pattern matching. See notes on POST otherwhere.
`file (c)`	filename	File read from a local disc. Use this variable only if no `url` is set. All escape codes (parameters) in `url` are supported in filename. The last character of the file (usually linefeed) is removed.
`text (c)`	string	Predefined text answer. Only if there is neither `url` nor `file` set. Escape codes (parameters) are usable here, too.
`accepted-smsc`	id-list	Accept ONLY SMS messages arriving from SMSC with matching ID. Separate multiple entries with ';'. For example, if `accepted-smsc` is "RL;SON", accept messages which originate from SMSC with ID set as 'RL' or 'SON'
`catch-all`	bool	Catch keyword regardless of '%s' parameters in pattern.
`send-sender`	bool	Used only with POST. If set to true, number of the handset is set, otherwise not.
`strip-keyword`	bool	Used only with POST. Remove matched keyword from message text before sending it onward.
`faked-sender`	phone-number	This number is set as sender. Most SMS centers ignore this, and use their fixed number instead. This option overrides all other sender setting methods.
`max-messages`	number	If the message to be sent is longer than maximum length of an SMS it will be split into several parts. `max-messages` lets you specify a maximum number of individual SMS messages that can be used. If `max-messages` is set to 0, no reply is sent, except for error messages.
`accept-x-kannel-headers`	bool	Request reply can include special X-Kannel headers but these are only accepted if this variable is set to true. See Extended headers.
`assume-plain-text`	bool	If client does not set Content-Type for reply, it is normally application/octet-stream which is then handled as data in kannel. This can be forced to be plain/text to allow backward compatibility, when data was not expected.
`concatenation`	bool	Long messages can be sent as independent SMS messages with `concatenation = false` or as concatenated messages with `concatenation = true`. Concatenated messages are reassembled into one long message by the receiving device.
`split-chars`	string	Allowed characters to split the message into several messages. So, with "#!" the message is split from last '#' or '!', which is included in the previous part.
`split-suffix`	string	If the message is split into several ones, this string is appended to each message except the last one.
`omit-empty`	bool	Normally, Kannel sends a warning to the user if there was an empty reply from the service provider. If `omit-empty` is set to 'true', Kannel will send nothing at all in such a case.
`header`	string	If specified, this string is automatically added to each SMS sent with this service. If the message is split, it is added to each part.
`footer`	string	As header, but not inserted into head but appended to end.
`prefix`	string	Stuff in answer that is cut away, only things between prefix and suffix is left. Not case sensitive. Matches the first prefix and then the first suffix. These are only used for `url` type services, and only if both are specified.
`suffix`	string

Table 5-5. Parameters (Escape Codes)

`%k`	the keyword in the SMS request (i.e., the first word in the SMS message)
`%s`	next word from the SMS message, starting with the second one (i.e., the first 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 first 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
`%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

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://my.applet.machine/Servlet/kludge2?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 fit an SMS message.
`text/html`	Tags are removed, rest is chopped to fit an SMS message.
`text/vnd.wap.wml`	Processed like HTML.
`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` varaible on for the SMS-service.

Extended headers

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

SendSMS-user configurations

To enable an SMS push, you must set sendsms-port into the 'smsbox' group and define one or more 'sendsms-user' groups. Each of these groups define one account, which can be used for the SMS push, via HTTP interface (see below)

Table 5-6. 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 (m)`	string	Password for the user (see HTTP interface, below)
`user-deny-ip`	IP-list	As other deny/allow IP lists, but for this user (i.e. this user is not allowed to do the SMS push HTTP request from other IPs than allowed ones). If not set, there is no limitations.
`user-allow-IP`	IP-list
`forced-smsc`	string	Force SMSC ID as a 'string' (linked to SMS routing, see 'smsc' groups)
`default-smsc`	string	If no SMSC ID is given with the send-sms request (see below), use this one. No idea to use with forced-smsc.
`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

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.

Over-The-Air configurations

To enable Over-The-Air configuration of phones or other client devices that support the protocol you need to configure a otaconfig group and a sendsms-user.

If you want to send multiple OTA configurations through the smsbox you will have to declare a ota-id string to the different otaconfig groups.

Table 5-7. OTA Config Group Variables

Variable	Value	Description
`group`	`otaconfig`	This is a mandatory variable
`ota-id`	`string`	An optional name or id for the otaconfig. Any string is acceptable, but semicolon ';' may cause problems, so avoid it and any other special non-alphabet characters.
`location`	`URL`	The address of the server for your WAP services. http://your.wap.site
`service`	`string`	Description of the service
`ipaddress`	`IP`	IP address of your server
`phonenumber`	`phone-number`	Phone number used to establish the PPP connection
`speed`	`number`	Connection speed: 9600 or 14400. Defaults to 9600.
`bearer`	`string`	Bearer type: data or sms. Defaults to data.
`calltype`	`string`	Call type: isdn or analog. Defaults to isdn.
`connection`	`string`	Connection type: cont or temp. Defaults to cont.
`pppsecurity`	`on or off`	Enable CHAP authentication if set to on, PAP otherwise
`authentication`	`string`	normal or secure. Defaults to normal.
`login`	`string`	Login name.
`secret`		Login password

A sample 'otaconfig' group:

group = otaconfig
location = http://wap.company.com
service = "Our company's WAP site"
ipaddress = 10.11.12.13
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

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.

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 specific services

Those running Kannel with several SMS centers might need to define services according to the relying SMS center. To achieve this, first you need to give an ID name for SMS center connections (see above). Then use the accepted-smsc variable to define 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 configuration, 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
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 defined 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 defined 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 configured 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-8. SMS Push (send-sms) CGI Variables

`username` (or `user`)	Username or account name. Must be `username` of the one 'sendsms-user' group in the Kannel configuration, or results in 'Authorization failed' reply.
`password` (or `pass`)	Password associated with given `username`. Must match corresponding field in the 'sendsms-user' group of the Kannel configuration, or 'Authorization failed' is returned.
`from`	Phone number of the sender. This field 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.
`to`	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.
`text`	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.
`udh`	Optional User Data Header (UDH) part of the message. Must be URL encoded.
`smsc`	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 configuration. This variable can be overridden with a `forced-smsc` configuration variable. Likewise, the `default-smsc` variable can be used to set the SMSC if it is not set otherwise.

Using the HTTP interface to send OTA configuration messages

OTA messages can be sent to mobile phones or devices to auto-configure the settings for WAP. They are actually complex SMS messages with UDH and sent as concatenated messages if too long. An example URL is like this:

http://smsbox.host.name:13013/cgi-bin/sendota?otaid=myconfig&username=foo&password=bar&phonenumber=0123456

Table 5-9. OTA CGI Variables

`otaid`	Name or id of the 'otaconfig' group in Kannel configuration that should be sent to the phone. This variable is optional. If it is not given the first 'otaconfig' group is sent.
`username`	Username of the 'sendsms-user' group in Kannel configuration, that has been configured to send OTA messages.
`password`	Password associated with given `username`. Must match corresponding field in 'sendsms-user' group in Kannel configuration, or 'Authorization failed' is returned.
`phonenumber`	Number of the phone that is to receive the OTA configuration message.
`from`	Phone number of the sender. This field 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.

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 configuration

Configuration is done as explained in previous chapters, you simply have to include all the data from both chapters into the configuration file.

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. Getting help and reporting bugs

This chapter explains where to find 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.org. To subscribe, send mail to devel-subscribe@kannel.org. This is currently the best location for asking help and reporting bugs. Please include configuration file and version number.

Appendix A. Using the fake WAP sender

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

Appendix B. Using the fake SMS center

Fakesmsc is a simple testing tool to test out Kannel and its SMS services. It cannot be used to send messages to mobile terminals, it is just a simulated SMS center with no connection to real terminals.

group = smsc
smsc = fake
port = 10000

The fakesmsc configuration group accepts all common 'smsc' configuration group variables, like smsc-id, preferred-smsc-id or denied-smsc-id, which can be used to test out routing systems and diverted services, before setting up real SMS center connections. If you include a fakesmsc group when bearerbox is connected to real SMS centers, you should add the connect-allow-ip variable to prevent unauthorized use.

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

Running Kannel with fakesmsc connections

After configuring Kannel, you can start testing it. The bearerbox will listen for fakesmsc client connections to the port(s) specified in the configuration file.

Starting fake SMS center

Each fakesmsc is started from command line, with all sent messages after command name. If any options are used (see below), they are put between the command and the messages. The usage is as follows:

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

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

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

This tells fakesmsc to connect to bearerbox at localhost:10000 (default) and send a hundred messages with an interval of 0.1 seconds. Each message is from number 100, and is either to number 200 with message 'nop' or to 300 with message 'echo this'.

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

Fake messages

Each message consists of four or five parts: sender number, receiver number, type, udh (if present) and main message itself. Sender and receiver numbers do not mean anything except for log files and number-based routing in Kannel.

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

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

test/fakesmsc -i 0.01 -v 1 -m 1000 "100 300 text echo this message"
test/fakesmsc -i 0.01 -m 1000 "100 300 data echo+these+chars%03%04%7f"
test/fakesmsc -m 1 "100 500 udh %0eudh+stuff+here main+message"

For "text", the rest of the argument is taken as the literal message. For "data", the next part must be the urlcoded version of the message. Space is coded as '+'. For "udh", the next 2 parts are the UDH and main message. Both must be in urlcoded form.

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

Fakesmsc command line options

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

Table B-1. Fakesmsc command line options

Switch	Value	Description
`-H`	host	Use host host instead of default `localhost`.
`-p`	port	Use port number port instead of default 10000.
`-i`	interval	Use message interval interval (in seconds, fractions accepted) instead of default interval 1.0 seconds.
`-m`	max	Send a maximum of max messages. Value -1 means that an unlimited number of messages is sent. Default -1. Using 0 can be useful to listen for messages sent via other channels.

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

Appendix C. Setting up a dial-up line

This appendix explains how to set up a dial-up line in Linux for use with the Kannel WAP gateway. In order for it to work you need a Linux kernel with PPP capabilities. Most distributions provides PPP kernel support by default. For more information how to compile PPP support into the kernel please read the "Linux Kernel HOWTO" at http://www.linuxdoc.org/.

Analog modem

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

Download and install the mgetty package.

	rpm -ivh mgetty-VERSION-rpm

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

Read man inittab for more detailed information. In this example we assume your modem is connected to the serial port ttyS0 (COM 1).

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

We need to start the pppd automatically when mgetty receives an AutoPPP request. Add the next line to /etc/mgetty+sendfax/login.config

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

In /etc/mgetty+sendfax/mgetty.config you might need to change the connect speed between the computer and the modem. Note: this is not the connect speed between the WAP client and the server modem. If you are e.g. going to use a Nokia 7110 as the server side modem you need to change the speed to 19200. Usually you can just leave the speed to the default value (38400).

	speed 38400

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

	refuse-chap
	require-pap
	lock
	modem
	crtscts
	passive
	192.168.1.10:192.168.1.20
	debug

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

	wapuser * wappswd 192.168.0.20

Configure your phone (this example is for Nokia 7110)

	homepage http:/yourhost/hello.wml
	connection type continuous
	connection security off
	bearer data
	dial up number (your phone number)
	ip address (IP of host running bearerbox)
	auth type normal
	data call type analogue
	data call speed 9600
	username wapuser
	password wappswd

ISDN terminal

This section needs to be written