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 benchmarking 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 bug tracker.

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-mssql[=DIR] Enable using FreeTDS libraries for DBPool and DLR support on MS-SQL and Sybase. Optional DIR specifies where to look for FreeTDS libraries and include files (defaults to /usr/local).

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

group = smsc
smsc = sema
device = /dev/tty0
smsc_nua = (X121 smsc address)
home_nua = (x121 radio pad address)
wait_report = 0/1 (0 means false, 1 means true)

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

group = smsc
smsc = oisd
host = 103.102.101.100
port = 10000
keepalive = 25
my-number = 12345
validityperiod = 30

group = smsc
smsc = smasi
host = 10.11.12.13
port = 23456
smsc-username = foo
smsc-password = foo

group = smsc
smsc = at
modemtype = auto
device = /dev/ttyS0
speed = 9600
pin = 2345

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

group = smsc
smsc = http
system-type = kannel
smsc-username = nork
smsc-password = z0rK
port = 13015
send-url = "http://localhost:20022"

group = smsc
smsc = http
system-type = generic
port = 13015
send-url = "http://www.foobar.com/mt.php?from=%P&to=%p&text=%b"
status-success-regex = "ok"
status-permfail-regex = "failure"
status-tempfail-regex = "retry later"
generic-foreign-id-regex = "<id>(.+)</id>"
generic-param-from = "phoneNumber"
generic-param-to = "shortCode"
generic-message-sent = "Message sent with ID: %I"
generic-status-sent = 200
generic-status-error = 404

group = smsc
smsc = loopback
smsc-id = loop1
reroute-smsc-id = my_id

External delivery report (DLR) storage

Delivery reports are supported by default internally, which means all DLRs are stored in the memory of the bearerbox process. This is problematic if bearerbox crashes or you take the process down in a controlled way, but there are still DLRs open. Therefore you may use external DLR storage places, i.e. a MySQL database.

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

group = mysql-connection
id = mydlr
host = localhost
username = foo
password = bar
database = dlr
max-connections = 1

group = dlr-db
id = mydlr
table = dlr
field-smsc = smsc
field-timestamp = ts
field-destination = destination
field-source = source
field-service = service
field-url = url
field-mask = mask
field-status = status
field-boxc-id = boxc

group = mysql-connection
id = dlr-db
host = localhost
username = foo
password = bar
database = dlr
max-connections = 1

group = sdb-connection
id = pgdlr
url = "postgres:host=localhost:db=myapp:port=1234"
max-connections = 1

group = dlr-db
id = pgdlr
table = dlr
field-smsc = smsc
field-timestamp = ts
field-destination = destination
field-source = source
field-service = service
field-url = url
field-mask = mask
field-status = status
field-boxc-id = boxc

group = oracle-connection
id = mydlr
username = foo
password = bar
tnsname = dlr
max-connections = 1

group = dlr-db
id = mydlr
table = dlr
field-smsc = smsc
field-timestamp = ts
field-destination = destination
field-source = source
field-service = service
field-url = url
field-mask = mask
field-status = status
field-boxc-id = boxc

group = pgsql-connection
id = mydlr
host = myhost.com
username = foo
password = bar
database = dlr
max-connections = 1

group = dlr-db
id = mydlr
table = dlr
field-smsc = smsc
field-timestamp = ts
field-destination = destination
field-source = source
field-service = service
field-url = url
field-mask = mask
field-status = status
field-boxc-id = boxc

group = mssql-connection
id = msdlr
server = myservername
username = foo
password = bar
database = dlr
max-connections = 1

group = dlr-db
id = msdlr
table = dlr
field-smsc = smsc
field-timestamp = ts
field-destination = destination
field-source = source
field-service = service
field-url = url
field-mask = mask
field-status = status
field-boxc-id = boxc

group = dlr-db
id = dlr-db
table = dlr
field-smsc = smsc
field-timestamp = ts
field-source = source
field-destination = destination
field-service = service
field-url = url
field-mask = mask
field-status = status
field-boxc-id = boxc

SMSBox configuration

group = smsbox
bearerbox-host = localhost

smsbox-port
http-proxy-port
http-proxy-host
http-proxy-username
http-proxy-password
http-proxy-exceptions
http-proxy-exceptions-regex
ssl-certkey-file

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

group = smsbox
...
smsbox-id = mysmsc
...

group = smsbox-route
smsbox-id = mysmsc
shortcode = "1111;2222;3333"

group = smsbox
...
smsbox-id = mysmsc
...

group = smsbox-route
smsbox-id = mysmsc
smsc-id = "A;B;C"
shortcode = "1111;2222"

group = sms-service
keyword = www
get-url = "http://%S"

group = sms-service
keyword = nop
text = "You asked nothing and I did it!"
catch-all = true

group = sms-service
keyword = complex
get-url = "http://host/service?sender=%p&text=%r"
accept-x-kannel-headers = true
max-messages = 3
concatenation = true

group = sms-service
keyword = default
text = "No action specified"

<?xml version="1.0"?>
<!DOCTYPE ...>
<message>
  <submit>
    <da><number>destination number (to)</number></da>
    <oa><number>originating number (from)</number></oa>
    <ud>user data (text)</ud>
    <udh>user data header (udh)</udh>
    <meta-data>meta-data</meta-data>
    <dcs>
      <mclass>mclass</mclass>
      <coding>coding</coding>
      <mwi>mwi</mwi>
      <compress>compress</compress>
      <alt-dcs>alt-dcs</alt-dcs>
    </dcs>
    <pid>pid</pid>
    <rpi>rpi</rpi>
    <vp>
      <delay>validity time in minutes</delay>
    </vp>
    <timing>
      <delay>deferred time in minutes</delay>
    </timing>
    <statusrequest>
      <dlr-mask>dlr-mask</dlr-mask>
      <dlr-url>dlr-url</dlr-url>
    </statusrequest>

    <!-- request from application to Kannel -->
    <from>
      <user>username</user>
      <username>username</username> 
      <pass>password</pass>
      <password>password</password>
      <account>account</account>
    </from>
    <to>smsc-id</to>

    <!-- request from Kannel to application -->
    <from>smsc-id</from>
    <to>service-name</to>

  </submit>
</message>

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

group = ota-setting
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

group = sendsms-user
username = otauser
password = foo
max-messages = 2
concatenation = 1

group = ota-bookmark
ota-id = wap-link
url = "http://wap.company.com"
service = "Our company's WAP site"

group = sms-service
keyword = talk
get-url = "http://my.applet.machine/Servlet/talk?sender=%p&text=%r"
max-messages = 0

group = sms-service
keyword = weather
accepted-smsc = SOL
get-url = "http://my.applet.machine/Servlet/weather?sender=%p&operator=SOL&text=%r"

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

group = sendsms-user
username = operator_A
password = foo
forced-smsc = A

group = sendsms-user
username = operator_B
password = bar
forced-smsc = B

Running SMS gateway

http://smsbox.host.name:13013/cgi-bin/sendsms?
username=foo&password=bar&to=0123456&text=Hello+world

<?xml version="1.0"?>
<!DOCTYPE CHARACTERISTIC-LIST SYSTEM "file:///gw/settings.dtd">
<CHARACTERISTIC-LIST>

  <CHARACTERISTIC TYPE="ADDRESS">
    <PARM NAME="BEARER" VALUE="GSM/CSD"/>
    <PARM NAME="PROXY" VALUE="10.11.12.13"/>
    <PARM NAME="PORT" VALUE="9201"/>
    <PARM NAME="CSD_DIALSTRING" VALUE="+12345678"/>
    <PARM NAME="PPP_AUTHTYPE" VALUE="PAP"/>
    <PARM NAME="PPP_AUTHNAME" VALUE="yourusername"/>
    <PARM NAME="PPP_AUTHSECRET" VALUE="yourauthsecret"/>
    <PARM NAME="CSD_CALLTYPE" VALUE="ISDN"/>
    <PARM NAME="CSD_CALLSPEED" VALUE="9600"/>
  </CHARACTERISTIC>

  <CHARACTERISTIC TYPE="URL" 
                  VALUE="http://wap.company.com/"/>

  <CHARACTERISTIC TYPE="NAME">
    <PARM NAME="NAME" VALUE="Your WAP Company"/>
  </CHARACTERISTIC>

</CHARACTERISTIC-LIST>

<?xml version="1.0"?>
<!DOCTYPE CHARACTERISTIC_LIST SYSTEM "file:///gw/settings.dtd">
<CHARACTERISTIC-LIST>
  <CHARACTERISTIC TYPE="BOOKMARK">
    <PARM NAME="NAME" VALUE="WAP Company"/>
    <PARM NAME="URL" VALUE="http://wap.company.com/"/>
  </CHARACTERISTIC>
</CHARACTERISTIC-LIST>

<SyncSettings>
<Version>1.0</Version>
<HostAddr>http://syncml.server.com</HostAddr>
<RemoteDB>
  <CTType>text/x-vcard</CTType>
  <CTVer>2.1</CTVer>
  <URI>contact</URI>
  <Name>Address Book</Name>
</RemoteDB>
<Name>Synchonization</Name>
<Auth>
  <AuthLevel>1</AuthLevel>
  <AuthScheme>1</AuthScheme>
  <Username>yourusername</Username>
  <Cred>passwordbase64encoded</Cred>
</Auth>
</SyncSettings>

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

	http://smsbox.host.name:13013/cgi-bin/sendota?
	    username=foo&password=bar&to=0123456&
	    text=MyURLEncodedXMLdocument&type=settings
	

Configuring ppg core group, for push initiator (PI) interface

PPG configuration group defines gateway's service interface. Configuring a PPG working with a trusted PI is easiest. Actually, you need no configuration at all: in this case a PPG with default values will be set up. Do not rely on this, default values may change. For PPG core configuration variables, see table 7.1.

An example of a core configuration for PPG working only with specific addresses follows. Note that ppg-deny-ip-list is not actually necessary, but does make configuring simpler: IPs here are always denied, even when they are mentioned in the allowed IPs list.

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

group = ppg
ppg-url = /wappush
ppg-port = 8080
concurrent-pushes = 100
users = 1024
ppg-allow-ip = 194.100.32.125;127.0.0.1
ppg-deny-ip = 194.100.32.89;194.100.32.103
trusted-pi = false

Configuring PPG user group variables

In addition of pi lists similar to the core group, ppg configuration specific to a certain user contains variables used for authentication and enforcing restrictions to phone numbers pi may contact. All variables are elaborated in table 7.2.

As an example, let us see how to configure a ppg user (a pi, named here 'picom') allowed to send pushes only from a specified ip.

group = wap-push-user
wap-push-user = picom
ppg-username = foo
ppg-password = bar
allow-ip = 62.254.217.163

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

Finishing ppg configuration

PPG uses SMS for sending SI to the phone and an IP bearer to fetch content specified by it (see chapter Overview of WAP Push). This means both wapbox and bearer smsc connections are in use. So your push proxy gateway configuration file must contain groups core, wapbox, smsc and smsbox. These are configured normal way, only smsc group may have push-specific variables. Note that following configurations are only an example, you may need more complex ones.

Bearerbox setup does not require any new variables:

group = core
admin-port = 13000
smsbox-port = 13001
wapbox-port = 13002
admin-password = b
wdp-interface-name = "*"
log-file = "filename"
log-level = 1
box-deny-ip = "*.*.*.*"
box-allow-ip = "127.0.0.1"
unified-prefix = "00358,0"

You must set up wapbox, for pulling (fetching) the wap data, and of course starting the push itself. No new variables here, either.

group = wapbox
bearerbox-host = localhost
log-file = "filename"
log-level = 0
syslog-level = none

To set up smsc connections, for pushing SI or SL over SMS. Here HTTP SMSC is used as an example. Variables no-sender and no-coding simplify HTTP request generated by Kannel. Send-url specifies content gateway, or sendsms service.

group = smsc
smsc = http
smsc-id = HTTP
port = 10000
system-type = kannel
smsc-username = foo
smsc-password = bar
no-sender = true
no-coding = true
send-url = http://host:port/path

To set up smsbox. This is used for ppg delivery reports, see later.

group = smsbox
bearerbox-host = localhost
smsbox-id = dlrbox

Kannel sources contain a sample push configuration file gw/pushkannel.conf.

Running a push proxy gateway

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

	gw/bearerbox [config-file]
	gw/wapbox [config-file]
	

An example using HTTP SMSC

An easy way to test and implement push services is to put ppg in the front of an existing sendsms service capable to send SMS data messages and to understand HTTP requests generated by HTTP SMSC. (See next chapter.) Then you need only configure SMSC configuration send-url to point to sendsms service.

An example of minimum SI document

Service indication (SI) should work with all types of phones, service loading does not. URL to be loaded is the main content of the document in both cases, however. Here an example (this is a minimum si document, not usable for testing, probably, but you want PPG to generate only one one SM per SI, if at all possible):

<?xml version="1.0"?>
<!DOCTYPE si PUBLIC "-//WAPFORUM//DTD SI 1.0//EN"
"http://www.wapforum.org/DTD/si.dtd">
<si>
    <indication href="http://www.gni.ch"
        si-id="1@gni.ch">
            You have 4 new emails
    </indication>
</si>

Note following points: a) Every SI must have different si-id. If there are none, href is used as an (very unsatisfactory) id. b) this si should not interrupt the phone's current action.

An example push (tokenized SI) document

HTTP SMSC generates a HTTP get request when it get a send-message event, expressed in Unicode. The content gateway, or the sendsms service must, of course, understand this URL. So here is an example, cgi variable text contains the url escaped form of a SI document. It is usable for testing prototype phones.

	http://matrix:8080/phplib/kannelgw.php?user=*deleted*&
	pass=*deleted*=to=%2B358408676001&text=3D%02%06%17%AE%96localhost
	%3A8080%00%AF%80%8D%CF%B4%80%02%05j%00E%C6%0C%03wap.iobox.fi%00%11%03
	1%40wiral.com%00%07%0A%C3%07%19%99%06%25%15%23%15%10%C3%04+%02%060%01
	%03Want+to+test+a+fetch%3F%00%01%01&udh=%06%05%04%0B%84%23%F0
	

Default network and bearer used by push proxy gateway

If network and bearer attributes of the pap control document are missing or set any, Kannel uses address type for routing purposes: if the address type is a phone number (TYPE=PLMN), network defaults to GSM and bearer to SMS; if it is a IP-address (TYPE=IPv4), network defaults to GSM and bearer to CSD. So following minimal pap document works:

<?xml version="1.0"?>
<!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP//EN"
          "http://www.wapforum.org/DTD/pap_1.0.dtd">
<pap>
  <push-message push-id="9fjeo39jf084@pi.com">
    <address address-value="WAPPUSH=+358408676001/TYPE=PLMN@ppg.carrier.com"/>
  </push-message>
</pap>

Push related Kannel headers

This chapter recapitulates Kannel headers used by ppg.

PPG uses many Kannel headers. These are very similar as ones used by smsbox. (Both send sms to to the phone, after all.)

Requesting SMS level delivery reports for WAP pushes

Push content is a normal binary SM, so you can ask delivery reports for them. These are useful for testing purposes (did the phone get the content at all, or did it just reject it.) Another use is create fall-back services for phones not supporting displaying a specific push content. (MMS one being perhaps currently most obvious.) Generally speaking, this service is very similar to smsbox one. See chapter Delivery Reports for details.

For ppg sms delivery reports you will need a fully working smsbox. Add configuration variable smsbox-id to smsbox group (it is necessary, because there is no MT from any smsbox corresponding the delivery report bearerbox is receiving):

       group = smsbox
       smsbox-id = dlrbox
       bearerbox-host = localhost
       log-file = "/var/log/kannel/smsbox-core.log"
       log-level = 0
       access-log = "/var/log/kannel/smsbox-access.log"

Start smsbox normal way after updating the configuration file.

You must add to PPG configuration file two less obvious variables: ppg-smsbox-id and service-name. Ppg-smsbox-id defines smsbox through which you want to route delivery reports, service-name makes possible for smsbox to handle wap pushes as a separate sms service.

Setting ppg-smsbox-id will route all ppg messages through same smsbox. You can route delivery reports of separate user through separate smsboxes, by using configuration variable smsbox-id in group wap push user. Or you can use X-Kannel-Smsbox-Id . This means routing every message separately.

You can supply dlr url and dlr mask as kannel header, or as a configuration variable in ppg user or ppg core group. (This is order of precedence, too.) First one is valid for only one message, second for a specific user, and third for every ppg user.

So following is a minimum ppg core group for sms delivery reports:

group = ppg
ppg-url = /wappush
ppg-port = 8080
concurrent-pushes = 100
trusted-pi = true
users = 1024
service-name = ppg
ppg-smsbox-id = dlrbox

And you can add Kannel headers to http post request. Here an example code snippet (C using Kannel gwlib; this example asks for all possible delivery reports).

http_header_add(push_headers, "X-Kannel-SMSC", "link0");
http_header_add(push_headers, "X-Kannel-DLR-Url",
                "http://193.53.0.56:8001/notification-dlr?smsc-id=%i"
                "&status=%d&answer=%A&to=%P&from=%p&ts=%t");
http_header_add(push_headers, "X-Kannel-DLR-Mask",
                octstr_get_cstr(dos = octstr_format("%d", 31)));
http_header_add(push_headers, "X-Kannel-Smsbox-Id", "dlrbox"));

Here status=%d tells the type of the delivery report and answer=%A the delivery report itself (sms content of it). Other ones are needed to map delivery report to original wap push.

With these you can use with following http post request

       http://193.53.0.56:8080/phplib/kannelgw.php?user=*deleted*&
       pass=*deleted*=to=%2B358408676001&text=3D%02%06%17%AE%96localhost
       %3A8080%00%AF%80%8D%CF%B4%80%02%05j%00E%C6%0C%03wap.iobox.fi%00%11%03
       1%40wiral.com%00%07%0A%C3%07%19%99%06%25%15%23%15%10%C3%04+%02%060%01
       %03Want+to+test+a+fetch%3F%00%01%01&udh=%06%05%04%0B%84%23%F0

Note that you can use all sms service escapes in dlrurl, see Parameters (Escape Codes) for details.

If you want to set dlr url for a specific user, you must set configuration variable dlr-urlin wap-push-user, if for entire ppg, default-dlr-url in group ppg. Value must naturally match with one used in group smsc.

Routing WAP pushes to a specific smsc

This chapter explains how to route wap push to a specific smsc.

Smsc routing for wap pushes is similar to sms pushes. So, firstly you must define configuration variable smsc-id in smsc group (or groups) in question. Say you used value link0. You can send this as a Kannel header:

http_header_add(push_headers, "X-Kannel-SMSC", "link0");

Then you can issue a request:

       http://193.53.0.56:8080/phplib/kannelgw.php?user=*deleted*&
       pass=*deleted*=to=%2B358408676001&text=3D%02%06%17%AE%96localhost
       %3A8080%00%AF%80%8D%CF%B4%80%02%05j%00E%C6%0C%03wap.iobox.fi%00%11%03
       1%40wiral.com%00%07%0A%C3%07%19%99%06%25%15%23%15%10%C3%04+%02%060%01
       %03Want+to+test+a+fetch%3F%00%01%01&udh=%06%05%04%0B%84%23%F0

You can use configuration variables to route all messages of a specific user or all ppg messages. Set default-smsc in group wap-push-user or in group ppg.

Again precedence of various methods of setting the smsc is kannel header, then configuration variable in group wap push user and then in group ppg.

Using SSL client support

To use the client support please use the following configuration directive within the core group

group = core
...
ssl-client-certkey-file = "filename"

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

Using SSL server support for the administration HTTP interface

To use the SSL-enabled HTTP server please use the following configuration directive within the core group

group = core
...
admin-port-ssl = true
...
ssl-server-cert-file = "filename"
ssl-server-key-file = "filename"

Using SSL server support for the sendsms HTTP interface

To use the SSL-enabled HTTP server please use the following configuration directive within the core and smsbox groups

group = core
...
ssl-server-cert-file = "filename"
ssl-server-key-file = "filename"

group = smsbox
...
sendsms-port-ssl = true

Using SSL server support for PPG HTTPS interface

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

group = ppg
...
ppg-ssl-port = 8090
ssl-server-cert-file = "/etc/kannel/cert1.pem"
ssl-server-key-file = "/etc/kannel/key1.pem"

PPG uses a separate port for HTTPS traffic, so so you must define it. This means that you can use both HTTP and HTTPS, when needed.