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