Kannel: Open Source SMS Gateway

It’s been quite a while since my last blog. This time i’m coming with a bunch of topics to write, starting with Kannel. After moving to my new role, the first task i got was to set up an SMPP server with one of our carriers. After digging sometime in internet i found one project kannel, which is a perfect game player for me. So in this blog, i’ll be explaining on how to setup an SMPP SMS gateway locally.

Installing Kannel

Download the latest source code from kannel site.

$ wget http://www.kannel.org/download/kannel-snapshot.tar.gz -O /opt/

$ cd /opt && tar xvzf kannel-snapshot.tar.gz && cd kannel-snapshot

$ apt-get install -y libxml2-dev libxml2 openssl libssl-dev build-essential      # installing dependencies

$ ./configure --prefix=/usr/local/kannel/

$ make && make install

$ adduser --system --home /usr/local/kannel/lib/kannel/ --no-create-home --gecos "Kannel" kannel

$ mkdir /var/log/kannel && mkdir /var/run/kannel

$ chown -c kannel.root /var/log/kannel && chown -c kannel.root /var/run/kannel 

Now we have the kannel installed on our custom prefix folder. Let’s go ahead setting the Kannel application.

Setting up Kannel

Kannel comprises of two processes, smsbox and bearerbox. Bearerbox service is the one which is in contact with the carrier gateways, responsible for sending and receiving SMS. smsbox is the service which interacts between our application and bearerbox. ie, it receives incoming sms from our bearer box and sends it our application and vice versa. The kannel config consists of multiple parts, which are explained below.

1) Basic configuration: We define the basic details like, bindip, log file path, adminUI port, adminUI password, whitelist ip for accessing admin ui, smsbox port etc..

# sample configuration
group = core
admin-port = 13000
smsbox-port = 13001
admin-password = changeme
admin-deny-ip = "*.*.*.*"
admin-allow-ip = ""
wdp-interface-name = "*"
log-file = "/var/log/kannel/bearerbox.log"
access-log = "/var/log/kannel/access.log"
box-deny-ip = "*.*.*.*"
box-allow-ip = ""

2) SMSC configuration:  We define the smmp details of our carrier's. which includes carrier's smpp ip, smpp port, auth credentials etc..

# sample configuration
group = smsc            # Default group name, no need to modify
smsc = smpp         
host = x.x.x.x
port = yyyy
smsc-id = fake-carrier          # Unique name for this connection
smsc-username = xxxxxxxx
smsc-password = yyyyyyyy

3) smsbox configuration: We define the configurations for the smsbox which includes bindip, a unique id for the smsbox etc..

# sample configuration
group = smsbox
bearerbox-host = localhost
sendsms-interface =
smsbox-id = mysmpp
sendsms-port = 10200                     # Applications make HTTP request to this port
log-file = "/var/log/kannel/smsbox.log"

4) Kannel gateway configuration: We define the user name, password, ratelimit etc for the messages from the smsbox

# sample configuration
group=sendsms-user      # default group name, no need to change
max-messages=3          # sms rate limit

5) SMS service configuration: We define settings for incoming sms from the bearer box, which includes to which URL our application URL to which the SMS details has to be forwarded.

# sample configuration
group = sms-service                 # Default group name
keyword = default
post-url = http://localhost:5000/incoming # When a message is received from SMS center this URL is called. Refer manual for wildcards details.
catch-all = 1
max-messages = 0
omit-empty = true
send-sender = true

Add all the above configurations according to the requirement on to the kannel.conf file. A sample init script for Debian/Ubuntu is available here

Once the SMPP service is started, check the bearebox logs for the connectivity with the carrier’s smpp gateway. Once the connection is up, we can start to send/receive sms. For incoming sms, smsbox will make an HTTP request based on our configuration. For example, if we are using a POST method, the sms details like From, To can be retrieved from the POST HEADERS and the sms text from the request data. Below are some of the headers that come along with the POST requests.

X-Kannel-From   => sender id
X-Kannel-To     => recepient id

Similarly for outbound sms, our application makes a HTTP GET request to the smsbox url and smsbox will carry it over to the bearerbox which then carry over to the carrier for delivery.