This post will guide you on how to install Kannel SMS gateway in Centos 5

Install Kannel SMS gateway in Centos 5 3

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:

  • A 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 purposes, such as party invitations, etc (based on their preferences).

Downloading and Compiling

Kannel is trivially easy to download and compile. You visit the 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 organized. 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 = ""

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 ( 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
my-number = 123123123123
connect-allow-ip =
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 =
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 which tend to be quite helpful as well.

Good luck!