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.

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 byte-code format. Latest WAP specifications defines some additional conversions that Kannel is starting to implement, like multipart/form-data, multipart/mixed or MMS content conversion.

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 initiates 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 notification or a stock quote. For this purpose WAP Forum defined WAP Push.

Push is an application level service, sitting on the top of existing WAP stack. It defines two protocols, OTA and PAP. OTA is a ligthweigth protocol speaking with WAP stack (to be more specific, with WSP), PAP speaks with the push initiator. It defines three kind of XML documents, one for the push data itself and another for protocol purposes (these are called pap document or push control documents).

The server does not simply send push content to the phone, the user would surely not accept, for instance, interrupting of a voice call. Instead it sends a specific XML document, either Service Indication or Service Loading. These inform the user about the content become 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 send ed to the phones over SMS, but the content is fetched by the phone over IP bearer, for instance CSD or GPRS. Because Push Proxy Gateway tokenises SI and SL documents, it may fit one SMS message (if not, it is segmented for transfer).

Using two bearers seems to be an unnecessary complication. But quite simply, phones currently operate this way. Push over GPRS can only simplify matters.

Overview of SMS

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 regular text as well as advanced content like 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. Kannel's biggest feature is to abstract each SMSC protocol to a well-known HTTP protocol, simplifying services deployment.

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

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, although it should be working without major problems on Windows (through Cygwin), Solaris and FreeBSD.

Kannel requires the following software environment:

• C compiler and libraries for ANSI C, with normal Unix extensions such as BSD sockets and related tools. (GNU's GCC tool-chain is recommended)

• The Gnome XML library (known as gnome-xml and libxml), version 2.2.5 or newer. See http://xmlsoft.org/xml.html.

  If you are installing it from your distribution's packages, you'll need libxml2-dev in addition to run-time libxml2 package libraries.

• GNU Make.

• 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 style-sheets, jade, jadetex, etc; see README, section `Documentation', 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.

Hardware requirements are fluffier. Some informal benchmarkings have shown that with a reasonably fast PC architecture (e.g. 400MHz Pentium II with 128MB RAM), SMS performance's bottleneck is always on the SMSC side, even for example with multiple connections summing a pipeline with 400 msg/sec. We haven't benchmarked Kannel yet on WAP side, so there are no hard numbers.

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:

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.org/arch.shtml

3. The README and various other text files in the source tree.

You can also find general information on Kannel's website and information about existing problems at our bugtracker.

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.

Compiling the gateway

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

        ./configure
        make
	

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

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 speed. speed options is equivalent to --with-malloc=native --disable-assertions, while debug is --with-malloc=checking --enable-assertions.

• --disable-docs (default is --enable-docs) Use this option if you don't have DocBook installed and/or you want to save some time and CPU cycles. Pre-generated documentation is available on Kannel's site. Default behavior is to build documentation, b.e., converting the User Guide and the Architecture Guide from the DocBook markup language to PostScript and HTML if DocBook is available.

• --enable-drafts (default is --disable-drafts) When building documentation, include the sections marked as draft.

• --enable-debug (default is --disable-debug) Enable non-reentrant development time debugging of WMLScript compiler.

• --disable-localtime (default is --enable-localtime) Write log file time stamps in GMT, not in local time.

• --enable-assertions / --disable-assertions Turn on or off runtime assertion checking. enable makes Kannel faster, but gives less information if it crashes. Default value is dependent on --with-defaults.

• --with-malloc=type Select memory allocation module to use: type is native, checking, or slow. For production use you probably want native. The slow module is more thorough than checking, but much slower. Default value is dependent on --with-defaults.

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

• --with-mysql Enable using MySQL libraries for DBPool and DLR support.

• --with-mysql-dir=DIR Where to look for MySQL libs and header files. DIR points to the installation of MySQL.

• --with-sdb Enable using LibSDB libraries for dlr support.

• --with-oracle Enable using Oracle OCI-Libraries for Oracle 8i/9i DBPool and DLR support.

• --with-oracle-includes=DIR Where to look for Oracle OCI-Header files.

• --with-oracle-libs=DIR Where to look for Oracle OCI-Library files.

You may need to add compilations flags to configure:

	CFLAGS='-pthread' ./configure
	

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

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
	

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

	rpm -q libxml2
	

	rpm -ivh kannel-VERSION.i386.rpm
	

	rpm -Uvh kannel-VERSION.i386.rpm
	

	rpm -e kannel
	

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

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

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

	cd /etc/rc.d/rc5.d/
	ln -s ../init.d/kannel S91kannel
	ln -s ../init.d/kannel K91kannel
	

	dpkg -l libxml2
	

	apt-get install kannel
	

	su -
	

	dpkg -i kannel-VERSION.deb
	

	dpkg --remove kannel
	

	dpkg --purge kannel
	

	/etc/init.d/kannel start
	

	/etc/init.d/kannel stop
	

	/etc/init.d/kannel restart
	

	update-rc.d -f kannel remove
	

	update-rc.d kannel defaults
	

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.

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"

1    # A group with a wrapped alias line
2    group = sms-service
3    keyword = hello
4    aliases = hallo;haalloo;\
5      heelloo;haelloo;healloo
5    text = "Hello world!"

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"

group = wapbox
bearerbox-host = localhost
log-file = "/var/log/wapbox.log"
log-level = 0
syslog-level = none

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

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.

	./bearerbox -v 1 [config-file]
	

	./wapbox -v 1 [config-file]
	

	./smsbox -v 1 [config-file]
	

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

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.

group = wapbox
bearerbox-host = localhost

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.

RADIUS accounting proxy configuration

To set up the RADIUS accounting proxy thread inside Kannel you have to define a 'radius-acct' group.

group = radius-acct
our-port = 1646
secret-nas = radius

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.

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.

group = smsc
smsc = cimd
host = 100.101.102.103
port = 600
smsc-username = foo
smsc-password = bar

group = smsc
smsc = cimd2
host = 100.101.102.103
port = 600
smsc-username = foo
smsc-password = bar
keepalive = 5 
my-number = "12345"

group = smsc
smsc = emi
host = 103.102.101.100
port = 6000
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_x25
phone = ...
device = /dev/tty0
smsc-username = foo
smsc-password = bar

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