Basic steps for setting up a WAP gateway
The hottest technology for implementing mobile services is the Wireless Application Protocol (WAP). This article discusses the advantages of working with the open source gateway for WAP, which performs the protocol conversion between a Web server and a mobile phone.
The WAP gateway works by letting a telephone act as a simple Web browser with optimized markup language, scripting language, and the transmission protocols for wireless-over-the-air use. It talks to the phone using the WAP protocol stack and translates the requests it receives to normal HTTP. Therefore, content providers can use any HTTP server and utilize existing know-how about HTTP service implementation and administration.
In addition to protocol translations, the gateway also compresses the WML (Wireless Markup Language) pages into a more compact form, which saves bandwidth on the air and further reduces the phone’s processing requirements. It also compiles WMLScript programs into a bytecode format.
There are various commercial WAP gateways available on the market that are quite expensive. Kannel, on the other hand, is an open source gateway; you don’t need to pay for it, you can edit the source code yourself, and you can construct your own customized gateway. Because Kannel is being developed on Linux systems (RedHat and Debian), it can be smoothly ported to other UNIX-like operating systems. However, in this article, I illustrate building the gateway for these two Linux systems only.
Kannel gateway architecture
The gateway divides the processing load between the following two hosts:
- The bearer box, which connects to the SMS (Short Message Service) centers and CSD (Circuit Switched Data) routers, providing a unified interface to them for the wapbox. The bearer box does this by implementing the WDP (Wireless Datagram Protocol) layer of the WAP stack.
- The wapbox, which hosts the upper layers of the WAP stack. Each session and its transactions are handled by the same wapbox.
Working of the system
The bearer box receives UDP (User Datagram Protocol) packets from CSD routers, inspects them to see whether they are WAP packets, and then routes them to the WAP box. This simple design allows the bearer box to do a minimum of processing per packet. The bearer box also sends the UDP packets that the other boxes generate, which adds some more routing processing. The wapboxes implement the WTP (Wireless Transaction Protocol) and WSP (Wireless Session Protocol) layers. These take HTTP-like requests from the phones and make the actual HTTP requests to content servers, compress the responses, and send them back to the terminals. (Sessions are maintained to make as much use of the limited radio bandwidth as possible.)
Basic software and hardware requirements
Before constructing the gateway, you must have the following basic setup:
- C compiler (CC or GCC), development libraries, and related tools
- The Gnome XML library (known as gnome-xml and libxml), Version 2.2.5 or later (see Resources for a link)
- GNU Make
- Posix thread libraries (pthread.h)
Setting up the gateway
There are two ways to build the gateway. The first way is to get the source code, compile it yourself, and install it. The second way is to have the precompiled binary RPM (RedHat Package Manager) and get it installed. The RPM is a program designed to build and manage packages of software, including the source and binaries. It is also portable and can be run on different platforms. See Resources for more information on RPM.
First, you need to install the Kannel source code by downloading it from Kannel’s Web site (see Resources). Once the download is complete, compile the source code by entering the following commands from a command line:
Ideally, you should be able to compile the code without any problems. If all the libraries mentioned above are present, the code compiles easily. To install the gateway, enter the following command:
make bindir=/usr/local/bin install.
You can substitute the /usr/local/bin directory with any other path where the gateway should be installed. The gateway is now installed on your system. The executables can now be found in the /gw directory named bearerbox, wapbox.
Installing the pre-compiled binaries
Check that you have the libxml2 XML library installed in your system by typing the following command:
rpm -q libxml2.
This XML library is required to install and compile the gateway. Download the binary RPM file of Kannel from the site. Log in as root, and enter the following command to install it. If you have sufficient permission, you might not require the superuser mode.
rpm -ihv kannel_VERSION.i386.rpm
This completes the installation. The
_VERSION attribute is the version number of the Kannel binaries.
Working with the gateway
Now study the basic steps for using the gateway and testing it with a WAP-enabled mobile phone simulator. Essentially, you’ll be dealing with the bearerbox and the wapbox (the executables you’ve just created).
Configuring the gateway
The bearerbox and wapbox are the main working modules of the gateway, and must be configured before configuring the gateway. These two modules are controlled by a configuration file that has wapbox and bearerbox groups.
A configuration file consists of groups of configuration variables. Groups are separated by empty lines, with each variable defined on its own line (each group in Kannel configuration is distinguished with a group variable). Lines beginning with a hash mark (#) are comments and should be ignored.
A variable definition line has the name of the variable, the equal sign (=), and the value of the variable. The name of the variable can contain any character except white spaces and equal signs. The value of the variable is a string, with or without quotation marks around it. Quotation marks are needed if the variable begins or ends with a white space or contains special characters. A normal C escape character syntax works inside quotation marks.
Working with configuration files
I’m including an example of the configuration file that I used for this project; it is the basic file with which the gateway runs. There is, however, a list of other attributes available to control the gateway. You can learn about them by referring to the Kannel User Guide.
Understanding the various attributes given in the sample configuration file
A group contains the ID of the group to which it relates. If the ID is core, then it’s the bearerbox configuration; otherwise, a wapbox ID is for the wapbox configuration. The
admin-port identifies the port through which the HTTP administration is to be done. The various other attributes of the group bearerbox and wapbox are described in Tables 2 and 3. The mandatory fields are denoted by an m, o is optional, and c is conditional.
Table 1. Configuration file attributes for the bearerbox
|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 can reach any port and must be over 1023.|
|admin-port-ssl (o)||bool||If set to true, an SSL-enabled administration HTTP server is used instead of the default nonsecure plain HTTP server. Default is ‘no’.|
|admin-password (m)||string||Password for HTTP administration commands.|
|status-password||string||Password to request Kannel status. If not set, no password is required; if set, either this or admin-password can be used.|
|admin-deny-ip||IP-list||These lists can be used to prevent connection from the specified IP addresses.|
|admin-allow-ip||IP-list||Can be used as a wild card.|
|wapbox-port (c)||port-number||Port 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 the specified IP addresses.|
|box-allow-ip||IP-list||Same as admin. It allows IP.|
|udp-deny-ip||IP-list||Denying UDP packets from a given IP.|
|udp-allow-ip||IP-list||Allowing UDP packets from an IP.|
|wdp-interface-name(c)||IP or *||If this is set, Kannel listens to WAP UDP packets incoming to ports 9200 through 9208, bound to given IP. If no specific IP is needed, use just an asterisk (*).|
|log-file||filename||A file in which to write a log. This is in addition to stdout and any log file defined in the 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 for info, 2 for warning, 3 for error and 4 for panic.|
Table 2. Configuration file attributes for the wapbox
|group (m)||wapbox||This is a mandatory variable.|
|bearerbox-host (m)||hostname||The machine hosting the bearerbox.|
|timer-freq||value-in-seconds||The frequency with which timers are checked out. Default is 1.|
|log-file||filename||As with bearerbox "core" group.|
|log-level number||0 through 5||Meaning same as in bearerbox.|
Starting the gateway
Once you have compiled Kannel and edited the configuration file to your specifications, it is time for the final step. For basic work, you can copy and paste the text shown in Listing 1, save it with any name, and use it as your configuration file. In order to start the gateway, you must first start the bearerbox, followed by the wapbox. Because the bearerbox is the essential part of the gateway, it must be started first.
Start the bearerbox with the following command:
./bearerbox -v 1 <conf_file>.
-v 1 sets the logging level to INFO. In this option you won’t see a large amount of debugging output (the default is DEBUG <conf_file>), where conf_file is the name of the configuration file you are using with Kannel. The basic distribution packet comes with the sample configuration file wapkannel.conf (in the /gw subdirectory), which is for setting up WAP Kannel. You can edit those configuration files to set up your own specialized system. After the bearer box, the wapbox must be started. Start it by typing the following command:
./wapbox -v 1 <conf_file> .
For more command-line options, you must review the Kannel User Guide.
Administering the gateway through an HTTP interface
Kannel can be administered via an HTTP interface. All commands are given as normal HTTP queries, so they can easily be given from command lines like this one:
% lynx -dump http://localhost:12345/shutdown?password=bar
In the command above, "12345" is set as the admin-port in the configuration file. For most commands, an
admin-password is required as an argument as shown here. Shutdown is for shutting down the gateway. The other commands available are:
- Status, to get the current status of the gateway. No password is required if
status-passwordis not set.
- Suspend, to set Kannel as suspended. A password is required.
- Resume, to set the Kannel state as running. A password is required.
Testing with a WAP-enabled mobile phone simulator
I’ll provide you with some simple steps with which to test the gateway and access the WML pages from the Internet through a mobile phone simulator. You need two machines, one running a Windows® operating system, and the other the Linux gateway, preferably connected through a LAN. The Linux machine must be connected to the Internet, either directly or indirectly.
- You can use the Nokia 7210 Content Authoring SDK (see Resources), which is available for a Windows system.
- Install it in a Windows system.
- Do a little configuring and set the gateway address to the IP address of the Linux machine running the gateway.
- Now type any Web site address serving WML pages from the simulator and you are done!
You must be able to access the pages and navigate through the simulator.
This project describes the most inexpensive and easiest method for building a WAP gateway — one that can be customized to any extent.