///Build a Push Proxy Gateway on Linux

Build a Push Proxy Gateway on Linux

Introduction

This article continues where the developerWorks’ article Build a WAP gateway on Linux left off. In that article, I described how to install and configure the open source Kannel gateway and make it act as a Wireless Application Protocol (WAP) gateway. In this article, I discuss how to make the Kannel gateway serve as a push proxy gateway (PPG). I discuss the PPG core group settings and the push initiator (PI) interface settings in the Kannel configuration file. I also discuss how to run the PPG and how to set up a test environment for it.

Basic overview of push

A push mechanism is the delivery of unsolicited information to a mobile device. The process does not require user interaction. The WAP push system consists of a push initiator on the Internet that serves as the source of the information. The PI communicates with the PPG using a special protocol called Push Access Protocol (PAP) over HTTP. On the other side, the PPG communicates with the mobile device using another protocol called Over-The-Air (OTA). OTA can work on top of the Wireless Session Protocol (WSP) (in WAP 1.x) or WHTTP (in WAP 2.0). The PPG and the WAP gateway can be separate or combined into a single component.

The OTA protocol can support a number of bearers. They can be SMS, circuit switched, or packet switched.

Before continuing, let’s quickly discuss push contents. The information conveyed by push is actually contained in an XML file that consist of three different entities:

  • Control entity: This part of the push contains the basic information and fields. The fields can include recipient address, expiry time, bearer type, delivery attempt time, and a URL to which a response is to be sent if delivery confirmation is requested by the push initiator.
  • Content entity: This is the actual data that is received by the mobile device. The various content types are Service Indication (SI), Service Load (SL) and Cache Operation (CO).
  • Capability entity: This entity determines the type of mobile device that is to be served. This is determined by WAP user agent profiling. The sender can indicate the hardware vendor and browser version and type of the intended recipients. This capability entity is then matched at the PPG to see which devices are compatible with the requested capability. If there is a match, the content is delivered by the PPG to that specific device.

A sample push control entity, my_uncnfpap.xml, is illustrated in Listing 1. A sample push content entity, si.xml, is illustrated in Listing 2. (You can download both of these files from the Resources section below.)

Listing 1. Sample push control entity



<?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"
deliver-before-timestamp="2001-09-28T06:45:00Z"
deliver-after-timestamp="2001-02-28T06:45:00Z"
progress-notes-requested="false">
<address address-value="WAPPUSH=+358408676001/TYPE=PLMN@ppg.carrier.com"/>
<quality-of-service
priority="low"
delivery-method="unconfirmed"
network-required="true"
network="GSM"
bearer-required="true"
bearer="CSD"/>
</push-message>
</pap>

Listing 2. Sample push content entity



<?xml version="1.0"?>
<!DOCTYPE si PUBLIC "-//WAPFORUM//DTD SI 1.0//EN"
"http://www.wapforum.org/DTD/si.dtd">
<si>
<indication href="http://wap.yahoo.com"
si-id="you@yourdomain.com" action="signal-high"
created="2002-01-13T01:33:09Z"
si-expires="2005-05-31T00:00:00Z"
>
You have got mail.
</indication>
</si>

Configuring the gateway for PPG

In the previous article in this series, you downloaded and installed the gateway; if you haven’t already done this, refer back to that article for instructions. In this section, I describe how to start configuring the gateway for PPG. I use two components: the PPG core group and the PPG user group. The PPG core group is used to configure the PI interface.

Configuring the PPG core group (PI interface)
In the main Kannel configuration file (kannel.conf), you must add one more group (like wapbox and bearerbox) with the name ppg and set up the corresponding values. My sample configuration file for this group is shown in Listing 3.

Listing 3. Sample configuration file for ppg group



group = ppg
ppg-url = /wappush
ppg-port = 8080
concurrent-pushes = 50
users = 52
ppg-allow-ip = 192.168.1.35;127.0.0.1
trusted-pi = false

However, you can add your own fields and configure the settings to your own needs. Table 1 defines some of the variables that can be set. (To familiarize yourself with setting and using these variables, see the first article of this series.) Note that Tables 1 and 2 include information about ways to route push messages through a SMS gateway, but those features are beyond the scope of this article.

Table 1. PPG core group configuration variables

Variable Value Description
group ppg Mandatory value. Indicates that you are configuring the PPG group.
ppg-port number The port at which PPG is listening. The default is 8080.
ppg-ssl-port(o) number Mandatory value for PPG HTTPS support. The port at which PPG listens for HTTPS requests. There are no defaults; you must set the value separately.
ssl-server-cert-file string Mandatory value for PPG HTTPS support. This file contains the server’s SSL certificate.
ssl-server-key-file string Mandatory value for PPG HTTPS support. This file contains the server’s SSL private key.
ppg-url URL Location of PPG services. The default is /wappush.
global-sender string The sender phone number. This is required by some protocols.
concurrent-pushes number The number of concurrent pushes expected. Note that PPG works even if the value is too low; it will only be slower. The default is 100.
users number Number of actually configured user accounts. Note that PPG works even value is too low; it will only be slower. The default is 1,024.
trusted-pi boolean If true, PI does authentication for PPG. Obviously, both must reside inside the same firewall. The default is true. If this variable is true, all security variables are ignored (even though they might be present).
ppg-deny-ip ip-list PPG does not accept pushes from these IP addresses. Wildcards are allowed. If this attribute is missing, no IP address is denied by this list.
ppg-allow-ip ip-list PPG accepts pushes from these, and only these, IP addresses. Wildcards are allowed. If you add this list, IP addresses not mentioned are denied.
default-smsc string If no SMSC ID is given with the wappush HTTP request (see below), this one is used as the default route for all push messages.
default-dlr string If no DLR-URL is given with the wappush HTTP request (see below), this one is used as the default route for all push messages.
ppg-smsbox-id string All PPG delivery reports are handled by this smsbox. This routes all DLR messages inside bearerbox to the specified smsbox for processing the HTTP requests to the DLR-URL.
service-name string This is the SMS service name used by smsbox for WAP push.
default-dlr string If no DLR-URL is given with the wappush HTTP request (see below), this one is used as the default route for all push messages.
ppg-smsbox-id string All PPG delivery reports are handled by this smsbox.
service-name string This is the SMS service name used by smsbox for WAP push. The default is on. You normally do not need to set this value.
max-messages integer Maximum number of SMS messages generated. The default is 10. You only need to set this variable when your push documents are very long.

Configuring the PPG user group
You also need to configure the PPG user group values in the configuration file. Table 2 describes the details of the variables and values.

Table 2. PPG User group configuration variables

Variable Value Description
wap-push-user string (More) human readable name of a user.
ppg-username string Username for this user.
ppg-password string Password for this user.
allowed-prefix number-list Phone number prefixes allowed in pushes coming from this PI. These prefixes must conform to the standard international phone number format.
denied-prefix number-list Phone number prefixes denied in pushes coming from this PI. These prefixes must conform to the international phone number format.
white-list url Defines a URL from which the whitelist can be fetched. The whitelist itself contains list of phone numbers accepting pushes from this PI.
black-list url Defines a URL from which the blacklist can be fetched. The blacklist itself contains list of phone number not accepting pushes from this PI.
allow-ip ip-list Defines IP addresses from which this PI can do pushes. Adding this list means that addresses not mentioned are denied.
deny-ip ip-list Defines IP addresses from which this PI cannot do pushes. Addresses not mentioned in either list are denied, too.
default-smsc string If no SMSC ID is given with the wappush HTTP request (see below), this one is used as the default route for this specific push user. The forced-smsc string allows only routing to a defined SMSC ID for this specific push user.
dlr-url string If no dlr is given with the wappush HTTP request (see below), this one is used as default route for this specific push user.
smsbox-id string smsbox handles delivery reports from this user.
forced-smsc string Allows only routing to a defined SMSC ID for this specific push user.
white-list-regex POSIX regular expression Defines the set of phone numbers accepting pushes from this PI.
black-list-regex POSIX regular expression Defines the set of phone-numbers rejecting pushes from this PI.

Testing with a handset simulator

I’ll illustrate these points by giving you an example. My sample push content consists of the two XML documents I described earlier. One document, my_uncnfpap.xml, is the control entity. The other document, si.xml, is a content entity and actually contains the push content; its name indicates that this push content is of the Service Indication (SI) type. For testing purposes, you should start by using the files I’ve provided; after you’ve gotten comfortable with the configurations, you can tweak them to your needs. You can download the files from Resources.

Starting the gateway
Before you begin with PPG, you need to start the gateway. To do this, you first need to configure it by editing the kannel.conf file. (You can learn how in the "Configuring the gateway" section of the first article in this series.)

After you’ve configured the gateway, starting it involves two steps. First, start the bearerbox with the following command:

Listing 4. Starting the bearerbox



./bearerbox -v 1 <conf_file>

The -v 1 sets the logging level to INFO. With this option, you won’t see a large amount of debugging output (the default is DEBUG <conf_file>). <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 that configuration file to set up your own specialized system.

After starting the bearerbox, you need to start the wapbox by typing the following command:

Listing 5. Starting the wapbox



./wapbox -v 1 <conf_file>

For more command-line options, review the Kannel User Guide.

Setting up the test environment
I’ll set up the test environment by configuring the PPG as well as the client-side mobile handset simulator.

You can download a handset simulator from Nokia (see Resources for a link). Install it and, in the settings, change the gateway IP address to that of the machine where your PPG will be running. You can use an IP address on your internal LAN if you want. You might need to restart the simulator.

Now, to set up the PPG, you must put my_unconfpap.xml and si.xml into the gw/test directory. Then, find the test_ppg executable file, which is the test program for behaving as a push initiator.

Sending push information to the simulator
In tmy_uncnfpap.xml, check to make sure that deliver-before-timestamp and deliver-after-timestamp are set to appropriate values; otherwise, the push might not be delivered to the client. The WAPPUSH value must be set to the simulator’s client IP address. The TYPE has to be set to IPv4@ppg.carrier.com. Have a look: the bearer value should be set to CSD.

In si.xml, set the created and si-expires values to the correct timestamp values. If you don’t, the push message will be invalid and won’t be delivered. Similarly, if you want to work with SL or CO push documents, you need to write your own corresponding XML file.

You are now ready to send a sample push message to the mobile simulator. Just check to make sure that you are in the gw/test directory. To make a push request to the client, type the command shown in Listing 6:

Listing 6. Make a push request to the client




./test_ppg -q http://ppg-host-name:ppg-port/ppg-url<content_file> <control_file>

In my example, <content_file> is the SI document (si.xml) and <control_file> is the PAP document (my_uncnfpap.xml). The ppg-host-name is the hostname of the system running the PPG, and the ppg-port is the PPG port number as set in the kannel.conf file. In the command shown in Listing 6, the -q option is given to run the test program in quiet mode. For various other command-line options, please refer to the Kannel User Guide.

You should see an indication on the simulator saying "push message received." If you want to retrieve this document, then you are redirected to the site that is indicated in the href tag of the si.xml document.

Avenues for further testing
You can try creating your own SI-, SL-, or CO-type documents and testing them in a real-life fashion with a mobile simulator. Push content developers and WAP application developers can benefit from this. You can also use my_cnfpap.xml to send the push request in a confirmed manner; simply change the delivery-method to confirmed in the quality-of-service tag.

Conclusion
In this article, I described how to set up a low-cost push proxy gateway, and how this gateway can help you develop push content and test out applications. Because it uses Linux and standard hardware, this method is easy, has a low cost, is highly configurable, and can help you get started in developing push applications and content.

Resources

Download

Name Size Download method
wi-proxysource.zip FTP
2010-05-26T10:54:42+00:00 June 15th, 2005|Linux|0 Comments

About the Author:

The author is a software engineer at ConvergeLabs, and has been working in Linux for several years. His primary interests are C, wireless and Linux. He can be contacted at manasb@convergelabs.com.

Leave A Comment