I recently had the oppportunity (necessity) to set up a web application that interacted with many of the users through SMS messages in addition to the more traditional HTML interface. While there are a number of possible software solutions for GSM modems on Windows, on Unix-like platforms the most commonly used one is Kannel. It also has the advantage of being open source and thus very, very free.

However, setting, configuring, and using Kannel tends to be a bit tricky. I’m writing this article (almost a HOWTO) in an attempt to help out anybody who’s undertaking the process themselves and might be able to get some tips and tricks from this. I expect this to not be a terribly popular article, but if I ever need to set this stuff up myself in the future, then I’ll have it written down somewhere at least!

Most of the instructions here will work on any Unix platform, such as Linux, FreeBSD, or Mac OS X. It’s worth noting that I got nearly everything working with OS X, only to be thwarted at the very end because Mac’s no longer have serial ports to use GSM modems. You could, however, easily use some of the more advaned HTTP based SMS services on a Mac server of some sort.

The Scenario

The web site written was a discounting service oriented around cell phones. Users would send the site a message, and then receive a discount at local venues. They could go to the site on the intarwebs to see their total savings and learn about more venues.

The usage pattern was always:

• User sends us a message.
• We might send them a reply after processing it.
• We might also periodically need to be able to send the user a message for other purporses, such as party invitations, etc (based on their preferences).

Downloading and Compiling

Kannel is trivially easy to download and compile. You visit the Kannel.org website and download the latest and greatest gateway-1.X.Y.tar.gz file.

From there:

# mkdir src
# cd src
# tar xfz ../downloads/gateway-1.4.1.tar.gz
# cd gateway-1.4.1
# configure --prefix=/usr/local/kannel

I chose to install to /usr/local/kannel just because I’m that kind of guy who likes to keep everything reasonably separated and organised. You’re free to put it anywhere.

Compile and install.

# make
# sudo make install
password: **************

Configuration Files

You can be forgiven for thinking Kannel is trivially easy thus far—it really is that easy to download, compile, and install. Unfortunately, here is where things get tricky.

You now need to set up a configuration file. This file has a zillion options to support all of the possible and powerful ways in which Kannel can be used. I will be showing strictly how I set it up for the GSM modem we had in the office (It’s a Siemens GSM modem connected to a serial port, and works quite well).

The basic smskannel.conf (in the gw/ directory) has much of the information we want, but we’ll need to add a few things for our GSM modems and to interact with our web server correctly.

Configuration is divided into a few key groups, each representing the key parts of the kannel system, including the server that handles sending and receving the actual SMSes (bearerbox) and the system that handles the final dispatching to your scripts (smsbox).

The core Group

The first part of the file is the “core” group, and the default is pretty close to what we want:

group = core
admin-port = 13000
smsbox-port = 13001
admin-password = bar
#log-file = "/tmp/kannel.log"
#log-level = 0
box-deny-ip = "*.*.*.*"
box-allow-ip = "127.0.0.1"

You’ll want to change the password of course, but everything else is nearly standard. We are assuming that all communication to the kannel server will come from the same physical computer (127.0.0.1). You can set a log file if you are going to be running kannel as a service on your server, or you can just redirect stdout to some file.

Be aware that kannel has various log levels, ranging from 0, which displays information that is only of interest when you’re in the development and debugging phases, to 4, which only displays critical errors and problems. I tend to develop at level 0 and run live servers at level 1. Disk space is cheap.

The smsc Group

Kannel supports a pretty insane number of ways of sending and receiving SMSes, ranging from SMS services over HTTP, to a fake SMS centre for testing/development purposes, to GSM modems, which is what I have used and is the smsc module. These modems use AT-style modem commands and typically hook up over the serial port. To get this going, I set up the smsc group in the smskannel.conf file:

group = smsc
smsc = at
modemtype = auto
device=/dev/ttyS0
my-number = 123123123123
connect-allow-ip = 127.0.0.1
log-level = 0

The my-number field contains the number of your GSM modem’s SIM chip. Again, I only allow connections from my local server, and the Ubuntu Linux serial port is on /dev/ttyS0.

The smsbox Group

The smsbox group helps configure the part of the system that dispatches SMSes received by the core SMS or receives SMSes before they’re sent out. I honestly don’t fully understand what this group really does, but it’s necessary, and pretty trivial to set up.

group = smsbox
bearerbox-host = 127.0.0.1
sendsms-port = 13013
global-sender = 123123123123
log-level = 0

The global-sender field is the outgoing-number of your GSM modem, which for me is the same as the my-number field above.

The Sendsms Group

This group is what allows your web applications to send SMS messages using Kannel. They do this via simple HTTP requests, and configuration here basically requires a user name and password:

group = sendsms-user
username = kanneluser
password = df89asj89I23hvcxSDasdf3298jvkjc839
concatenation= true
max-messages = 10

Since the password is semi-plain and unprotected here, I tend to use one that is complicated and nearly impossible to remember, but quite different from any other passwords that I actualy use for login accounts and the like.

Getting the Messages to your application

The sms-service group configures how Kannel gets messages to your web application. You are allowed to specify a number of these groups, each of which can “catch” incoming messages based on various criteria. My application had all messages go to one processing script, so I just set up one group that caught all incoming messages.

group = sms-service
keyword =
keyword-regex = .*
catch-all = yes
max-messages = 0
get-url = "http://localhost/sms?phone=%p&text=%a"

This particular configuration has Kannel set up to use an HTTP GET request to send the message to my application. The param phone contains the phone number of the sender and the text parameter contains their entire message.

NOTE: The max-messages value was particularly tricky and critical for me: When I first set up Kannel and tested sending messages, I would always get back '<Empty reply from service provider>'. Setting max-messages to 0 tells Kannel to never send a reply directly from the incoming message (you can, of course, initiate your own response later, of course).

Finally, Setting up the modems

Kannel and smsc tends to be pretty good at figuring out everything about your modem by yourself, but you can help them out by including modems.conf in your smskannel.conf file as I did:

include = "/usr/local/kannel/modems.conf"

Running the Server

The hard part is done; all we have to do now is copy over the config files and start the service up:

# cd /usr/local/kannel
# cp ~/src/gateway-1.4.1/smskannel.conf .
# cp ~/src/gateway-1.4.1/gw/modems.conf .
# sbin/bearerbox -v 0 smskannel.conf &
# sbin/smsbox -v 0 smskannel.conf &

I tend to run the last two commands in two separate shell windows when developing/debugging so that I can see the output from the two programs clearly and use the information to help me figure out what’s going on (level 0 really tells you a lot).

Receiving Messages

Kannel will simply call the URL you told it to in the sms-service group and you can process this with whatever HTTP server environment you want. We’re using LAMP right now, but, again, any will do. The incoming phone number and message are in GET parameters. You can, if you want, configure the sms-service to send them as POST messages as well.

Sending Messages through Kannel

The final part our puzzle is to send outgoing SMS messages through Kannel, and has only one little twist. It is also done via an HTTP interface. It requires you to be a little careful about the character set you use. I found I had the most success by using the UCS-2 character set. In PHP5, you can easily use the iconv function to do this for you.

Since I send both English and Chinese messages, my PHP scripts and langugage string files are all UTF-8. Here is the code I use to send messages:

 function sendSmsMessage($in_phoneNumber, $in_msg)
 {
   $url = '/cgi-bin/sendsms?username=' . CONFIG_KANNEL_USER_NAME
          . '&password=' . CONFIG_KANNEL_PASSWORD
          . '&charset=UCS-2&coding=2'
          . "&to={$in_phoneNumber}"
          . '&text=' . urlencode(iconv('utf-8', 'ucs-2', $in_msg));

   $results = file('http://'
                   . CONFIG_KANNEL_HOST . ':'
                   . CONFIG_KANNEL_PORT . $url);
 }

To make this work, of course, you need to have allow_url_fopen set to On.

That’s It

That’s pretty much it. This has been a pretty dry article, but it does contain everything you need to get Kannel up and running and operational. The manual actually does contain everything you could possibly want to know, so keep digging in there if you’re stuck. Finally, there are mailing lists at kannel.org which tend to be quite helpful as well.

Good luck!