Knowledge Training

on Kannel
Parichaya Bimlendu Thakur
The document describes a detail information on how
kannel is setup in any linux system, its configuration and its
monitoring to get the actual information with SMSC
gateway.

Celestial Digital Solutions Pvt

Ltd

+91-8800889959

16-Nov-17
KANNEL DOCUMENT CONFIGURATION
STEPS
Table of Contents
Kannel Installation ........................................................................................................................................ 4
Installing Kannel from RPM Packages ....................................................................................................... 4
Installing Kannel .................................................................................................................................... 4
Upgrading Kannel .................................................................................................................................. 4
Removing Kannel .................................................................................................................................. 4
Installing Kannel from DEB Packages ........................................................................................................ 5
Installing or upgrading Kannel from Debian or Kannel repository ....................................................... 5
Installing or upgrading Kannel from a file ............................................................................................. 5
Removing Kannel .................................................................................................................................. 5
Kannel Information ....................................................................................................................................... 7
Access Logs: .............................................................................................................................................. 7
BIND REQ:.............................................................................................................................................. 7
HANDSHAKE RESPONSE FROM SMSC GATEWAY:................................................................................. 7
SMS NOT DELIVERED TO CUSTOMER:................................................................................................... 7
SMS DELIVERED TO CUSTOMER:........................................................................................................... 7
Details on Request-Response Parameters ................................................................................................ 8
Kannel Logs ............................................................................................................................................... 9
Sample Kannel Log: ............................................................................................................................... 9
DLR Responses List .................................................................................................................................. 10
Kannel Configurations ................................................................................................................................. 11
Basic Structure of a Kannel: A Logical Structure ..................................................................................... 11
GSM SMS CALL FLOW MO/MT................................................................................................................ 11
Sample Configuration file............................................................................................................................ 12
Running and Stopping Kannel ..................................................................................................................... 16
Start a Kannel .......................................................................................................................................... 16
Bearer-Box .......................................................................................................................................... 16
 SMS-Box .............................................................................................................................................. 16
Path of Scripts to Run/Stop Kannel ..................................................................................................... 16
Stop a Kannel .......................................................................................................................................... 16
Kill all instances at one glance ............................................................................................................ 16
Kill Single instance............................................................................................................................... 17
Glossary & References: ............................................................................................................................... 18
Kannel Installation

Kannel installation can be done in 2 ways;

a) Installing Kannel from RPM packages

b) Installing Kannel from DEB packages

Installing Kannel from RPM Packages

Before you install Kannel, check that you have libxml2 installed on your system:
rpm -q libxml2

Installing Kannel
1. Download the binary RPM packet from the Kannel web site.
2. Install the RPM package:
Command Used: rpm -ivh kannel-VERSION.i386.rpm

Upgrading Kannel
1. Download the binary RPM packet from the Kannel web site.
2. Upgrade the RPM package:
Command Used: rpm -Uvh kannel-VERSION.i386.rpm

Removing Kannel
1. Remove the RPM package:
Command Used: rpm -e kannel

After you have installed Kannel from the RPM packages you should now be able to run the Kannel init.d
script that will start Kannel as a WAP gateway. Run the script as root.
Command Used: /etc/rc.d/init.d/kannel start

To stop the gateway just run the same script with the stop parameter.
Command Used: /etc/rc.d/init.d/kannel stop

If Kannel is already running and you just want to quickly stop and start the gateway,e.g.to set a new
configuration option, run the script with the restart parameter.
Command Used: /etc/rc.d/init.d/kannel restart
If you want Kannel to run as a daemon, you need to add a symbolic link to the Kannel script from the run
level you want Kannel to run in. E.g. to run Kannel in runlevel 5 add symbolic links to /etc/rc.d/rc5.d/.
Command Used:
cd /etc/rc.d/rc5.d/
ln -s ../init.d/kannel S91kannel
ln -s ../init.d/kannel K91kannel

To run Kannel as a SMS gateway you need to edit the configuration file which is at
/etc/kannel/kannel.conf. In Kannel's documentation directory (/usr/share/doc/kannel) there is an
example file called examples/smskannel.conf. It has some basic examples of the configuration groups
needed to run Kannel as a SMS gateway. For more detailed information please see
examples/kannel.conf in the same directory for a commented complete example, and read the section
"SMS gateway configuration" later in this same document.

The logging is disabled by default and you can enable it from the kannel.conf file. Just add the log-file
option to the group of which box you want to log.

Installing Kannel from DEB Packages

Before you install Kannel, check that you have libxml2 installed on your system:
Command Used: dpkg -l libxml2

Installing or upgrading Kannel from Debian or Kannel repository

1. Install or upgrade the package:
Command Used: apt-get install kannel

Installing or upgrading Kannel from a file

1. Download the binary DEB packet from the Kannel web site.
2. Log in as root:
Command Used: su -
3. Install or upgrade the DEB package:
Command Used: dpkg -i kannel-VERSION.deb

Removing Kannel
1. Log in as root:
2. Remove the package keeping configuration files:
Command Used: dpkg --remove kannel
3. Remove the package completely:
Command Used: dpkg --purge kannel
After you have installed Kannel from the DEB packages you should now be able to run the Kannel init.d
script that will start Kannel as a WAP gateway. Run the script as root.

Command Used: /etc/init.d/kannel start

To stop the gateway just run the same script with the stop parameter.
Command Used: /etc/init.d/kannel stop

If Kannel is already running and you just want to quickly stop and start the gateway,e.g.to set a new
configuration option, run the script with the restart parameter.
Command Used: /etc/init.d/kannel restart

If you don't want Kannel to run as a daemon, run:

Command Used: update-rc.d -f kannel remove

If you want to restore Kannel running as a daemon, you need to add a symbolic link to the Kannel script
from the runlevel you want Kannel to run in. E.g. to run Kannel in default runlevel, just run:
Command Used: update-rc.d kannel defaults

Kannel package starts by default with a wapbox daemon. To activate smsbox or select which box you
want to start, edit /etc/default/kannel and comment/uncomment START_xxxBOX.

To run Kannel as a SMS gateway you need to edit the configuration file which is at
/etc/kannel/kannel.conf. In /usr/share/docs/kannel/examples/ there are example files. They have some
basic examples of the configuration groups needed to run Kannel as a SMS gateway. For more detailed
information please read the section "SMS gateway configuration" later in this same document.
Kannel Information

In the Kannel configuration file, mapping of paths like where the log files needs to be kept is also
mentioned. One can customize these paths depending upon the required. We have kept log path for
kannel as in below path;

Path:

a) Access Log Path: /usr/local/log/access_<servicename>.log

b) Log file for kannel: /usr/local/log/kannel_<servicename>.log

Note: servicename: This signifies name of the service associated with the service that is configured. Eg:
access_gamezone.log, kannel_gamezone.log

Below are snippets of sample log format and individual logs of both access and kannel logs.

Example:

Access Logs:
BIND REQ:
2017-02-10 14:41:41 Sent SMS [SMSC:smsc3] [SVC:tester] [ACT:] [BINF:] [FID:2300267715]
[META:?smpp?PARTNER+ROLE+ID=103&PRICEPOINT=340645&PRODUCT=745&?smpp_resp?]
[from:92070] [to:96896733976] [flags:-1:0:-1:-1:15] [msg:101:You have succesfully subscribed to Games
Zone at 1 OMR/Week. To unsubscribe, send UNSUB VGZ to 92070.] [udh:0:]

HANDSHAKE RESPONSE FROM SMSC GATEWAY:

2017-02-10 14:41:41 Receive DLR [SMSC:smsc3] [SVC:tester] [ACT:] [BINF:] [FID:2300267715]
[META:?smpp?PARTNER+ROLE+ID=103&PRICEPOINT=340645&PRODUCT=745&?smpp_resp?]
[from:92070] [to:96896733976] [flags:-1:-1:-1:-1:8] [msg:4:ACK/] [udh:0:]

SMS NOT DELIVERED TO CUSTOMER:

2017-02-10 14:41:48 Receive DLR [SMSC:smsc3] [SVC:tester] [ACT:103] [BINF:] [FID:2300267715]
[META:?smpp?dlr_err=%03%00%00&] [from:92070] [to:96896733976] [flags:-1:-1:-1:-1:2]
[msg:120:id:2300267715 sub:001 dlvrd:001 submit date:1702101311 done date:1702101311
stat:UNDELIV err:0 text:You have succesfully] [udh:0:]

SMS DELIVERED TO CUSTOMER:

2017-02-10 15:48:41 Receive DLR [SMSC:smsc3] [SVC:tester] [ACT:103] [BINF:] [FID:2301346205]
[META:?smpp?dlr_err=%03%00%00&] [from:92070] [to:96897407079] [flags:-1:-1:-1:-1:1]
[msg:120:id:2301346205 sub:001 dlvrd:001 submit date:1702101418 done date:1702101418
stat:DELIVRD err:0 text:You have succesfully] [udh:0:]
Details on Request-Response Parameters

Color Color Meaning Type Present in Note

Yellow Date & Time Request & Response This is first field of any request
Green Request Type Request & Response For Request Sent SMS
For Response Receive DLR
Blue Instance Name configured Request & Response It differentiates individual instances
in Kannel Configuration file of kannel configuration.
Pink Kannel User Name Request & Response It states username used during
configuration and setup of kannel
Navy Blue Bind Info type Type of SMSC Request This signifies what type of request or
response is sent/receive from/to
kannel from SMSC gateway.
RED Unique ID Request & Response This is unique ID for each request.
Grey META body Info Request & Response Information share or receive in Meta
body
Magenta Source Address Request & Response From which MSISDN or Short-code
request is initiated.
Dark Destination Address Request & Response To which MSISDN or Short-code
Green request is to be sent.
Dark Pink Mapping of Response Type Request & Response AT&T responses on request sent to
SMSC
Maroon Message needs to Sent Request & Response Message needs to be sent to
Customer configured at CP end
Dull Any other parameters to Request & Response To send any extra parameter over
Green send in UDP protocol UDP protocol
 Kannel Logs
Sample Kannel Log:

PDU Log
2017-11-07 17:00:30 [26805] [6] DEBUG: SMPP PDU 0x7f4614000a10 dump:
2017-11-07 17:00:30 [26805] [6] DEBUG: type_name: submit_sm
2017-11-07 17:00:30 [26805] [6] DEBUG: command_id: 4 = 0x00000004
2017-11-07 17:00:30 [26805] [6] DEBUG: command_status: 0 = 0x00000000
2017-11-07 17:00:30 [26805] [6] DEBUG: sequence_number: 144 = 0x00000090
2017-11-07 17:00:30 [26805] [6] DEBUG: service_type: NULL
2017-11-07 17:00:30 [26805] [6] DEBUG: source_addr_ton: 1 = 0x00000001
2017-11-07 17:00:30 [26805] [6] DEBUG: source_addr_npi: 0 = 0x00000000
2017-11-07 17:00:30 [26805] [6] DEBUG: source_addr: "92070"
2017-11-07 17:00:30 [26805] [6] DEBUG: dest_addr_ton: 1 = 0x00000001
2017-11-07 17:00:30 [26805] [6] DEBUG: dest_addr_npi: 0 = 0x00000000
2017-11-07 17:00:30 [26805] [6] DEBUG: destination_addr: "96893136666"
2017-11-07 17:00:30 [26805] [6] DEBUG: esm_class: 3 = 0x00000003
2017-11-07 17:00:30 [26805] [6] DEBUG: protocol_id: 0 = 0x00000000
2017-11-07 17:00:30 [26805] [6] DEBUG: priority_flag: 0 = 0x00000000
2017-11-07 17:00:30 [26805] [6] DEBUG: schedule_delivery_time: NULL
2017-11-07 17:00:30 [26805] [6] DEBUG: validity_period: NULL
2017-11-07 17:00:30 [26805] [6] DEBUG: registered_delivery: 1 = 0x00000001
2017-11-07 17:00:30 [26805] [6] DEBUG: replace_if_present_flag: 0 = 0x00000000
2017-11-07 17:00:30 [26805] [6] DEBUG: data_coding: 241 = 0x000000f1
2017-11-07 17:00:30 [26805] [6] DEBUG: sm_default_msg_id: 0 = 0x00000000
2017-11-07 17:00:30 [26805] [6] DEBUG: sm_length: 104 = 0x00000068
2017-11-07 17:00:30 [26805] [6] DEBUG: short_message:
2017-11-07 17:00:30 [26805] [6] DEBUG: Octet string at 0x7f4614001190:
2017-11-07 17:00:30 [26805] [6] DEBUG: len: 104
2017-11-07 17:00:30 [26805] [6] DEBUG: size: 105
2017-11-07 17:00:30 [26805] [6] DEBUG: immutable: 0
2017-11-07 17:00:30 [26805] [6] DEBUG: data: 59 6f 75 72 20 73 75 62 73 63 72 69 70 74 69 6f Your subscriptio
2017-11-07 17:00:30 [26805] [6] DEBUG: data: 6e 20 74 6f 20 47 61 6d 65 73 20 5a 6f 6e 65 20 n to Games Zone
2017-11-07 17:00:30 [26805] [6] DEBUG: data: 68 61 73 20 62 65 65 6e 20 72 65 6e 65 77 65 64 has been renewed
2017-11-07 17:00:30 [26805] [6] DEBUG: data: 20 61 74 20 31 20 4f 4d 52 2f 57 65 65 6b 2e 20 at 1 OMR/Week.
2017-11-07 17:00:30 [26805] [6] DEBUG: data: 54 6f 20 75 6e 73 75 62 73 63 72 69 62 65 2c 20 To unsubscribe,
2017-11-07 17:00:30 [26805] [6] DEBUG: data: 73 65 6e 64 20 55 4e 53 55 42 20 56 47 5a 20 74 send UNSUB VGZ t
2017-11-07 17:00:30 [26805] [6] DEBUG: data: 6f 20 39 32 30 37 30 2e o 92070.
2017-11-07 17:00:30 [26805] [6] DEBUG: Octet string dump ends.
2017-11-07 17:00:30 [26805] [6] DEBUG: PARTNER ROLE ID: "103"
2017-11-07 17:00:30 [26805] [6] DEBUG: PRICEPOINT: "340645"
2017-11-07 17:00:30 [26805] [6] DEBUG: PRODUCT: "745"
2017-11-07 17:00:30 [26805] [6] DEBUG: SMPP PDU dump ends.
DLR Responses List

Type of DLR DLR Response Meaning Note

1 Delivered to mobile device This is used to send notification
to SMSC to send only those
response which are delivered
to Mobile Devices
2 Not delivered to mobile device If Not Delivered to Mobile
device this response is sent
from SMSC to client
4 Queued on SMSC If numbers of request are
queued at SMSC, SMSC sends
this response.
8 Delivered to SMSC This response states that
request is successfully
submitted to SMSC.
16 Not Delivered to SMSC This response states that
request is not submitted to
SMSC.
Kannel Configurations

Basic Structure of a Kannel: A Logical Structure

Figure 1: Logical Structure of Kannel

GSM SMS CALL FLOW MO/MT

Figure 2: GSM Call Flow MO/MT

Sample Configuration file

Sample Kannel file looks very much similar to below configuration block. It comprises of few important
key-value parameters configuration steps and details of these are shared as we move along further
ahead. Without these below groups your Kannel will not work properly.

Sample Configuration file:

group = core
admin-port = 13000
wapbox-port = 13002
admin-password = bar
wdp-interface-name = "*"
log-file = "/var/log/bearerbox.log"
log-level = 1
box-deny-ip = "*.*.*.*"
box-allow-ip = "127.0.0.1"
………………………………
Example: Sample Kannel Configuration

Details of each key-value pair: (OMAN CONFIGURATION FILE)

group = core
admin-port = 15096
smsbox-port = 15098
admin-password = bar
log-file = "/usr/local/log/kannel_gamezone.log" Note 1: Core Group
box-deny-ip = "*.*.*.*"
box-allow-ip = "127.0.0.1"
access-log = "/usr/local/log/access_gamezone.log"
group = smsc
smsc = smpp
host = 185.127.160.2
port = 15529
transceiver-mode = 1
access-log = "/usr/local/log/access_gamezone.log"
unified-prefix= "-,+;-,+"
smsc-username = "103"
smsc-password = "V1e6C"
system-type = ""
address-range = ""
smsc-id=smsc3
max-pending-submits = 10
system-type = smpp
interface-version = 34 Note 2: SMSC Group
throughput = 60
smsc-id = smsc3
keepalive = 30
wait-ack = 30
alt-charset = utf-8
alt-addr-charset = "GSM"
wait-ack-expire=0x03
msg-id-type = 0x00
source-addr-ton = 0x01
source-addr-npi = 0x00
dest-addr-ton = 0x01
dest-addr-npi = 0x00
max-pending-submits = 10
alt-dcs=yes
group = smsbox
bearerbox-host = 127.0.0.1
sendsms-port = 15097
Note 3: SMSBOX Group
sms-length = 500
smsbox-id = mysmsc
mo-recode = true

group = sendsms-user
username = tester
password = foobar
max-messages=6
Note 4: SENDSMS-USER
concatenation = trueaccess-log = "/usr/local/log/access_gamezone.log"
unified-prefix= "-,+;-,+"
dlr-url =
"http://205.147.98.6/async/omanTimweBillCb?id=%F&reportValue=%d&reply=%A
&mdn=%p&shortcode=%P"

group = smsbox-route
smsbox-id = mysmsc
smsc-id = smsc3
Note 5: SMS-ROUTE
shortcode = 92070

group = sms-service
keyword-regex = .*
catch-all = yes
omit-empty = true Note 6: SMS-SERVICE
max-messages = 0
get-url =
"http://205.147.98.6/async/omanTimweMO?Origin=%p&Text=%a&shortcode=%P"
group = smpp-tlv
name = PRICEPOINT
tag = 0x1400
Note 7: SMPP-TLV
type = integer
length = 4
smsc-id=smsc3

group = smpp-tlv
name = (TLV NAME)
tag = 0x1401 Note 8:If any more SMPP-
type = integer TLV are required
length = 4
smsc-id=smsc3
Running and Stopping Kannel

Start a Kannel
Kannel instance can be started post running the smsbox and bearbox scripts and by passing your kannel
configuration file as parameter in these scripts.

Once a kannel is installed in the system there are two major script files which are used to start/stop any
kannel.

Bearer-Box
The communication link between bearerbox and smsbox has been designed for the purpose of load-
balancing via random assignment. Which means, bearerbox holds all smsc connections and passes
inbound message to one of the connected smsboxes. So you have a determined route for outbound
messages, but no determined route for inbound messages.The bearer box is the engine that handles all
the donkey work. It establishes connections listens for smsc etc.

SMS-Box
The SMS box handles sending and receiving sms. It is like your hands. There's another box called the wap
box which deals with wap etc.

Path of Scripts to Run/Stop Kannel

/usr/local/sbin/bearbox /etc/<kannelconfigurationfile>.conf

/usr/local/sbin/smsbox /etc/<kannelconfigurationfile>.conf

Stop a Kannel
Below are commands which are used to kill all or single instances of any kannel.

Kill all instances at one glance

Commands:
killall smsbox
killall bearerbox
Kill Single instance
Commands:

1) ps -ef| grep kannel

a. This will help to list down all instances of kannel.
i. Example: [root@e2e-11-6 kannel_92070_log]# ps -ef| grep kannel

root 420 1 0 Nov08 ? 00:12:34 /usr/local/sbin/bearerbox

kannel_hutchison.conf

root 524 1 0 Nov08 ? 00:00:12 /usr/local/sbin/smsbox

kannel_hutchison.conf

2) Kill -9 <pid>
a. This command will kill the instance which you need to kill.
b. To kill any instance of any kannel, you need to kill both smsbox and bearerbox instances.
Glossary & References:

 http://www.kannel.org/download/1.4.4/userguide-1.4.4/userguide.html
Acronyms
 MO
o Mobile Originated - a SMS from mobile to application
 MT
o Mobile Terminated - a SMS from application to mobile