Kannel SMS Gateway on Debian 10/11

Kannel:

Kannel is an open source WAP and SMS gateway for GSM networks. Moreover, Kannel can send/receive SMS using a Serial or USB GSM Modem. It is accessible via HTTP API and can be used in sending bulk SMS, OTP etc.

So, Kannel has three main programs called boxes: bearerbox, smsbox, wapbox.

• Bearerbox interfaces towards the phones. It accepts WAP and SMS messages from the phones and sends them to the other boxes.
• SMSbox handles SMS gateway functionality.
• WAPbox handles WAP gateway functionality.

It is possible to have several SMSboxes and several WAPboxes on different hosts which allow it to handle larger load.

Kannel also supports database integration and supports mysql, pgsql, sdb, mssql, sqlite3, oracle, redis and cassandra.

Kannel has a wide range of GSM Modem support; moreover any GSM Modem that is accessible via Serial or USB port with proper driver and supports AT command would be used with Kannel.

Prepare to install Kannel SMS Gateway:

Here we are going to install a Kannel SMS Gateway latest stable version 1.4.5 from source tar file on Debian 10 (buster). Here we will configure the core components: bearerbox and smsbox that that is used for SMS Gateway.

SMS-GW Host IP	192.168.10.38
Windows Client Host IP	192.168.10.31
Linux Client Host IP	192.168.10.37
GSM Modem Model	Huawei E303 3G/GSM USB Modem

Check the OS release

root@sms-gw:~# cat /etc/os-release

Output:

Connect the USB Modem with the Linux Host and Check if it detects the modem by issuing lsusb command

root@sms-gw:~# lsusb

Output:

The Modem has detected on Bus 2.

Now we have to find at which TTY the modem is connected

root@sms-gw:~# ls /dev/ttyUSB*

Output:

We see the modem is connected on /dev/ttyUSB0 and /dev/ttyUSB1.Usually those modems baud rate is 9600 or 115200.

There is a handy tool wvdial, to identify the USB TTY and baud rate for a Modem. wvdial is usually used as a command line PPP dialer to use Mobile Internet.

Install wvdial to find USB TTY and baud rate for the Modem.

root@sms-gw:~# apt-get update
root@sms-gw:~# apt-get install -y wvdial

Issue wvdialconf command to discover the Modem’s TTY and Baud rate

root@sms-gw:~# wvdialconf

Output:

From the output we find that the modem is connected on /dev/ttyUSB0 and baud rate id 9600. wvdialconf also writes basic modem configuration in /etc/wvdial.conf file.

Now install necessary dependencies for Kannel

root@sms-gw:~# apt-get install -y linux-headers-$(uname -r) build-essential make gcc cpp wget curl libxml2 libxml2-dev bison flex byacc zlib1g-dev libiconv-hook1 libtool

Installing Kannel SMS Gateway:

Download source tarball from https://kannel.org/download/1.4.5/gateway-1.4.5.tar.gz

root@sms-gw:~# wget --no-check-certificate https://kannel.org/download/1.4.5/gateway-1.4.5.tar.gz

Untar the file and enter the source directory

root@sms-gw:~# tar -zxf gateway-1.4.5.tar.gz
root@sms-gw:~# cd gateway-1.4.5/

Run configure file with kannel home directory prefix and start-stop-deamon, here we are using /usr/local/kannel  as kannel home directory

root@sms-gw:~/gateway-1.4.5# ./configure  --enable-start-stop-daemon --prefix=/usr/local/kannel

We can also disable the wapbox as we will not use it

root@sms-gw:~/gateway-1.4.5# ./configure  --enable-start-stop-daemon --prefix=/usr/local/kannel  --disable-wap

After successful completion of configure script run, compile the package

root@sms-gw:~/gateway-1.4.5# make

Install the programs with data files and documentation

root@sms-gw:~/gateway-1.4.5# make install

It will install necessary binaries, libraries and docs in different directories in /usr/local/kannel/ location.

Note: If encounter any problem while make we can clean or uninstall and start over. To clean run make clean, to uninstall run make uninstall command.

Now create etc, run and log directories

root@sms-gw:~# mkdir /usr/local/kannel/etc
root@sms-gw:~# mkdir /usr/local/kannel/run
root@sms-gw:~# mkdir /var/log/kannel/ 

Create kannel config file  /usr/local/kannel/etc/kannel.conf with below contents

##CORE
group = core
admin-port = 13000
smsbox-port = 13001
admin-password = sms-gw-admin-passwd
status-password = sms-gw-status-passwd
admin-deny-ip = "*.*.*.*"
admin-allow-ip = "*.*.*.*"
box-deny-ip = "*.*.*.*"
box-allow-ip = "*.*.*.*"
log-level = 0
log-file = "/var/log/kannel/kannel.log"
dlr-storage = internal
sms-resend-retry = 1

##SMSC
group = smsc
smsc = at
smsc-id = smsc01
allowed-smsc-id = smsc01
preferred-smsc-id = smsc01
modemtype = Huawei
device = /dev/ttyUSB0
speed = 9600
alt-charset = "GSM"
sim-buffering = true
log-file = /var/log/kannel/smsc01-gsm1.log
log-level = 0

##MODEMS
group = modems
id = Huawei
enable-mms = true
init-string = "ATQ0 V1 E1 S0=0 &C1 &D2 +FCLASS=0;+CNMI=1,3,2,2,1;+CMEE=1;+CPMS=\"SM\",\"SM\",\"SM\";+CMGF=0;+CSCS=GSM
speed = 9600
detect-string = "huawei"

##SMSBOX
group = smsbox
bearerbox-host = localhost
sendsms-port = 13013
global-sender = 13013
mo-recode = true
sendsms-chars = "0123456789 +-"
log-file = "/var/log/kannel/smsbox.log"
log-level = 0
access-log = "/var/log/kannel/access.log"

##SMS-USER
group = sendsms-user
user-deny-ip = "*.*.*.*"
user-allow-ip = "*.*.*.*"
username = kannel
password = kannelpasswd
default-smsc = smsc01
concatenation = 1
max-messages = 10

##SMS-SERVICE
group = sms-service
keyword = default
get-url = " "http://%S"
accept-x-kannel-headers = true
max-messages = 10
concatenation = true
catch-all = true
omit-empty = true

Note: get-url config directives in the sms-serice group indicate the HTTP API calling style of remote HTTP server. Example: for remote PlaySMS server

get-url = "http://PLAYSMS-SERVER-IP/playsms/plugin/gateway/kannel/geturl.php?t=%t&q=%q&a=%aQ=%Q&smsc=%i"

Create init script to start/stop the kannel boxes as /etc/init.d/kannel

#!/bin/bash
# Start/stop the Kannel boxes: One bearer box and one SMS box.

BOXPATH=/usr/local/kannel/sbin
PIDFILES=/usr/local/kannel/run
CONFDIR=/usr/local/kannel/etc
CONF=$CONFDIR/kannel.conf

USER=kannel
VERSION=""

RB=$BOXPATH/run_kannel_box$VERSION
BB=$BOXPATH/bearerbox$VERSION
WB=$BOXPATH/wapbox$VERSION
SB=$BOXPATH/smsbox$VERSION
SSD=$BOXPATH/start-stop-daemon$VERSION

PATH=$BOXPATH:$PATH

case "$1" in
  start)
    echo -n "Starting WAP gateway: bearerbox"
    $SSD --start --quiet --pidfile $PIDFILES/kannel_bearerbox.pid --exec $RB -- --pidfile $PIDFILES/kannel_bearerbox.pid $BB -- $CONF
    echo -n " smsbox"
    $SSD --start --quiet --pidfile $PIDFILES/kannel_smsbox.pid --exec $RB -- --pidfile $PIDFILES/kannel_smsbox.pid $SB -- $CONF
    sleep 3
    echo "."
    ;;

  stop)
    echo -n "Stopping WAP gateway: "
    echo -n " smsbox"
    $SSD --stop --quiet --pidfile $PIDFILES/kannel_smsbox.pid --exec $RB
    echo -n " bearerbox"
    $SSD --stop --quiet --pidfile $PIDFILES/kannel_bearerbox.pid --exec $RB
    echo "."
    ;;

  status)
    CORE_CONF=$(grep -r 'group[[:space:]]*=[[:space:]]*core' $CONFDIR | cut -d: -f1)
    ADMIN_PORT=$(grep '^admin-port' $CORE_CONF | sed "s/.*=[[:space:]]*//")
    ADMIN_PASS=$(grep '^admin-password' $CORE_CONF | sed "s/.*=[[:space:]]*//")
    STATUS_URL="http://127.0.0.1:${ADMIN_PORT}/status.txt?password=${ADMIN_PASS}"
    curl $STATUS_URL
    ;;

  reload)
    # We don't have support for this yet.
    exit 1
    ;;

  restart|force-reload)
    $0 stop
    sleep 3
    $0 start
    ;;

  *)
    echo "Usage: $0 {start|stop|status|reload|restart|force-reload}"
    exit 1

esac

exit 0

Note: Above script is a default init.d script for Kannel. This configuration is appropriate for a small site running Kannel on single machine. Please, make sure that the Kannel binaries can be found in $BOXPATH or somewhere else along $PATH.  run_kannel_box has to be in $BOXPATH.

Make the /etc/init.d/kannel file execuatable

root@sms-gw:~# chmod +x /etc/init.d/kannel

Start kannel

root@sms-gw:~# /etc/init.d/kannel start

Output:

Check kannel bearerbox and smsbox listening state

Check Kannel status from inside the Linux box

root@sms-gw:~# /etc/init.d/kannel status

Use http://192.168.10.38:13000/status?password=sms‑gw‑admin‑passwd URL from windows client machine browser to check status

Sending SMS using Kannel SMS Gateway:

We can send SMS from any client machine browser using URL. Example:

http://192.168.10.38:13013/cgi-bin/sendsms?username=kannel&password=kannelpasswd&to=01700000000&text=SMS+from+kannel+01

The webpage shows SMS Push reply code 0: Accepted for delivery, which indicates that Kannel has accepted the SMS for delivery to the recipient

Sending SMS from Linux box using curl

root@host1:~# curl "http://192.168.10.38:13013/cgi-bin/sendsms?username=kannel&password=kannelpasswd&to=01700000000&text=SMS+from+kannel+02"

Output:

Send SMS using SMS text from file using curl

root@host1:~# echo "SMS from file using curl" > smsfile.txt
root@host1:~# curl "http://192.168.10.38:13013/cgi-bin/sendsms?username=kannel&password=kannelpasswd&to=01700000000" -G --data-urlencode [email protected]

Sending SMS by piping output to curl

root@host1:~# printf "SMS from output" | curl "http://192.168.10.38:13013/cgi-bin/sendsms?username=kannel&password=kannelpasswd&to=01700000000" -G --data-urlencode text@-

SMS Received by the Mobile device

Note: There are few more SMS Push reply codes from Kannel

Status Code	Message Body	Meaning
202	0: Accepted for delivery	The SMS has been accepted and is delivered onward to a SMSC driver
202	3: Queued for later delivery	The bearerbox accepted and stored the message in a queue to deliver later
4xx	(varies)	There was something wrong in the request or Kannel configuration, check the request and Kannel configuration.
503	Temporal failure, try again later	There was a temporal failure, try again later.

Checking Logs:

 We will find Kannel core bearerbox logs in /var/log/kannel/kannel.log file.

/var/log/kannel/access.log file logs successful access requests from clients.

Example Log:

/var/log/kannel/smsbox.log logs client request and communications with bearerbox.

GSM Modem related logs will be found in /var/log/kannel/smsc01-gsm1.log file.

Log Severity levels:

log-level config directive in each config group in kannel.conf file defines Log Severity level for that group and log accordingly in log-file given in that group. Log Levels are:

0 > debug
1 > info
2 > warning
3 > error
4 > panic

Security Tips:

• admin-deny-ip and admin-allow-ip directives define list of IP address are allowed or banned to access kannel admin portal. Each list can have multiple address separated by “;” , “*” represents all numbers in an octet. Example: if we want to allow 192.168.10.31 and localhost can access the admin portal and all other IP address should be blocked then the config directives will be like below

admin-deny-ip = “*.*.*.*”
admin-allow-ip = “127.*.*.*; 192.168.10.31”

• Similarly box-deny-ip and box-allow-ip directives define list of IP address which are allowed to access bearerbox. It is useful when we use multiple smsbox. We will list the smsbox IP addresses in box‑allow‑ip to access bearerbox program.
• user-deny-ip and user-allow-ip are used to allow/deny user IP address.
• It is better to use deny directive then allow selective IP address for each type of access control.
• Use very secured username/password for all username/password options showed in the kannel.conf file.

References:

• https://www.kannel.org/download/kannel-userguide-snapshot/userguide.html