gmelitauri/kannel

Kannel SMS Gateway - Technical Documentation

Project Overview

Containerized Kannel SMS Gateway deployed on Kubernetes for SMPP_USERedit Bank Georgia, providing SMS messaging capabilities through SMPP connections to smpp mobile operator.

Implementation Steps

Step 1: Create Bootstrap Script

Create bootstrap file for SQLBox compilation:

bash
#!/bin/sh
set -e
set -x

# Detect automake version
amver=$(automake --version | head -1 | awk '{print $NF}')
case "$amver" in
  ''|[0-1].[0-4]*) echo "$0: automake version 1.5 or later required"; exit 1 ;;
esac

# Detect libtoolize
if command -v glibtoolize >/dev/null 2>&1; then
  libtoolize="glibtoolize"
elif command -v libtoolize >/dev/null 2>&1; then
  libtoolize="libtoolize"
else
  echo "$0: libtoolize not found"
  exit 1
fi

# Clean old files
rm -f aclocal.m4 configure config.guess config.log config.sub config.cache \
      config.h.in config.h compile libtool.m4 ltoptions.m4 ltsugar.m4 \
      ltversion.m4 ltmain.sh libtool ltconfig missing mkinstalldirs \
      depcomp install-sh
rm -rf autom4te.cache
mkdir -p autotools

# Bootstrap
$libtoolize --copy --force
test -f ltmain.sh && mv ltmain.sh autotools/

aclocal -I autotools
autoconf
autoheader
automake --add-missing --copy

Step 2: Create Dockerfile

dockerfile
FROM ubuntu:latest

# Set noninteractive mode for apt
ENV DEBIAN_FRONTEND=noninteractive

SHELL ["/bin/bash", "-c"]

# Install dependencies
RUN apt-get update && \
    apt-get upgrade -y && \
    apt-get -y remove ntpdate && \
    apt-get install -y \
        build-essential subversion ntp nano wget cvs curl git unzip \
        autoconf automake libtool flex debhelper pkg-config libpam0g-dev \
        intltool checkinstall docbook docbook-xsl libpcre3 libpcre3-dev \
        libc6-dev g++ gcc autotools-dev bison libncurses5-dev m4 \
        tex-common texi2html texinfo libxml2-dev openssl libssl-dev \
        locales libmysqlclient-dev libmysql++-dev supervisor libtool-bin ca-certificates net-tools && \
    locale-gen en_US.UTF-8 && \
    mkdir -p /usr/local/src/kannel && \
    cd /usr/local/src/kannel && \
    svn checkout --non-interactive --trust-server-cert-failures=unknown-ca https://svn.kannel.org/gateway/trunk && \
    mv trunk gateway && \
    cd gateway && \
	libtoolize --force && \
	aclocal && \
    autoheader && \
	autoreconf --install --force && \
	automake --add-missing --copy && \
    ./configure --prefix=/usr/local/kannel \
                --with-mysql \
                --with-mysql-dir=/usr/lib/mysql/ \
                --enable-debug \
                --enable-assertions \
                --with-defaults=speed \
                --enable-localtime \
                --enable-start-stop-daemon \
                --enable-pam && \
    make && \
    make bindir=/usr/local/kannel install

# Copy bootstrap script into correct location
COPY bootstrap /usr/local/src/kannel/gateway/addons/sqlbox/bootstrap

# Set working directory explicitly before running bootstrap
WORKDIR /usr/local/src/kannel/gateway/addons/sqlbox

# Make it executable and run it
RUN chmod +x bootstrap && \
    ./bootstrap && \
    ./configure --prefix=/usr/local/kannel \
                --with-kannel-dir=/usr/local/kannel && \
    make && \
    make bindir=/usr/local/kannel/sqlbox install && \
    cd ../opensmppbox && \
    ./configure --prefix=/usr/local/kannel \
                --with-kannel-dir=/usr/local/kannel && \
    make && \
    make bindir=/usr/local/kannel/smppbox install && \
    mkdir -p /etc/kannel \
             /var/log/kannel/gateway \
             /var/log/kannel/smsbox \
             /var/log/kannel/wapbox \
             /var/log/kannel/smsc \
             /var/log/kannel/sqlbox \
             /var/log/kannel/smppbox \
             /var/spool/kannel && \
    chmod -R 755 /var/spool/kannel /var/log/kannel && \
    cp /usr/local/src/kannel/gateway/gw/smskannel.conf /etc/kannel/kannel.conf && \
    cp /usr/local/src/kannel/gateway/debian/kannel.default /etc/default/kannel && \
    cp /usr/local/src/kannel/gateway/addons/sqlbox/example/sqlbox.conf.example /etc/kannel/sqlbox.conf && \
    cp /usr/local/src/kannel/gateway/addons/opensmppbox/example/opensmppbox.conf.example /etc/kannel/opensmppbox.conf && \
    cp /usr/local/src/kannel/gateway/addons/opensmppbox/example/smpplogins.txt.example  /etc/kannel/smpplogins.txt && \
    rm -rf /usr/local/src/kannel/gateway && \
    apt-get clean

# Copy configuration files
COPY supervisord.conf /etc/supervisor/conf.d/supervisord.conf
COPY kannel.conf /etc/kannel/kannel.conf
COPY opensmppbox.conf /etc/kannel/opensmppbox.conf

# Expose ports
EXPOSE 13000 13013 13015 2346

# Declare volumes
VOLUME ["/var/spool/kannel", "/etc/kannel", "/var/log/kannel"]

# Start supervisord
CMD ["/usr/bin/supervisord"]

Step 3: Create Kannel Configuration

kannel.conf:

conf
#
# THIS IS A SAMPLE CONFIGURATION FOR SMS KANNEL
#
# This basic version is used for system testing. It expects 'fakesmsc' to
# send messages which are replied with simple fixed text message.
# It is run like this:
#
#  1% gw/bearerbox gw/smskannel.conf
#  2% gw/smsbox gw/smskannel.conf
#  3% test/fakesmsc -i 0.1 -m 100 "123 345 text nop"
#
# ..all 3 commands in separate shells (or screen sessions)
# Note that you can run them in different machines but have to
# add certain command line argument and configuration variables then
#
#
# For any modifications to this file, see Kannel User Guide 
# If that does not help, see Kannel web page (http://www.kannel.org) and
# various online help and mailing list archives
#
# Notes on those who base their configuration on this:
#  1) check security issues! (allowed IPs, passwords and ports)
#  2) groups cannot have empty rows inside them!
#  3) read the user guide
#
# Kalle Marjola for Kannel project 2001, 2004

#---------------------------------------------
# CORE
#
# There is only one core group and it sets all basic settings
# of the bearerbox (and system). You should take extra notes on
# configuration variables like 'store-file' (or 'store-dir'),
# 'admin-allow-ip' and 'access.log'


group = core
admin-port = 13000
smsbox-port = 13001
admin-password = bar
#status-password = foo
#admin-deny-ip = ""
#admin-allow-ip = ""
log-file = "/var/log/kannel/gateway/kannel.log"
log-level = 0
box-deny-ip = "*.*.*.*"
box-allow-ip = "127.0.0.1"
#unified-prefix = "+358,00358,0;+,00"
#access-log = "/tmp/access.log"
#store-file = "kannel.store"
#ssl-server-cert-file = "cert.pem"
#ssl-server-key-file = "key.pem"
#ssl-certkey-file = "mycertandprivkeyfile.pem"

#---------------------------------------------
# SMSC CONNECTIONS
#
# SMSC connections are created in bearerbox and they handle SMSC specific
# protocol and message relying. You need these to actually receive and send
# messages to handset, but can use GSM modems as virtual SMSCs


# This is a fake smsc connection, _only_ used to test the system and services.
# It really cannot relay messages to actual handsets!

#group = smsc
#smsc = fake
#smsc-id = FAKE
#port = 20000
#connect-allow-ip = 127.0.0.1

include = "/etc/kannel/smsc.d/smpp1.conf"
include = "/etc/kannel/smsc.d/smpp2.conf"
include = "/etc/kannel/smsc.d/smpp3.conf"
include = "/etc/kannel/smsc.d/smpp4.conf"
include = "/etc/kannel/smsc.d/smpp5.conf"

#---------------------------------------------
# SMSBOX SETUP
#
# Smsbox(es) do higher-level SMS handling after they have been received from
# SMS centers by bearerbox, or before they are given to bearerbox for delivery

group = smsbox
bearerbox-host = 127.0.0.1
sendsms-port = 13013
global-sender = 13013
#sendsms-chars = "0123456789 +-"
log-file = "/var/log/kannel/smsbox/smsbox.log"
log-level = 0
#access-log = "/tmp/access.log"

#---------------------------------------------
# SEND-SMS USERS
#
# These users are used when Kannel smsbox sendsms interface is used to
# send PUSH sms messages, i.e. calling URL like
# http://kannel.machine:13013/cgi-bin/sendsms?username=tester&password=foobar...

group = sendsms-user
username = tester
password = foobar
concatenation = yes
max-messages = 16
#user-deny-ip = ""
#user-allow-ip = ""

#---------------------------------------------
# SERVICES
#
# These are 'responses' to sms PULL messages, i.e. messages arriving from
# handsets. The response is based on message content. Only one sms-service is
# applied, using the first one to match.

group = sms-service
keyword = nop
text = "You asked nothing and I did it!"

# There should be always a 'default' service. This service is used when no
# other 'sms-service' is applied.

group = sms-service
keyword = default
text = "No service specified"

Step 4: Create OpenSMPPBox Configuration

opensmppbox.conf:

conf
# sample opensmppbox.conf

group = core
dlr-storage = internal

# this group defines your opensmppbox
group = opensmppbox
# our boxc type
opensmppbox-id = abcd
# the port to listen on for smpp connections
opensmppbox-port = 2346
# we connect to the following host as a box
bearerbox-host = localhost
bearerbox-port = 13000
log-level = 0
log-file = /dev/stdout
our-system-id = chim1
route-to-smsc = fake # fake smsc in kannel.conf
# see sample smpplogins.txt
smpp-logins = "/etc/kannel/smpplogins.txt"

Step 5: Create Supervisor Configuration

supervisord.conf:

conf
[supervisord]
nodaemon=true

[program:bearerbox]
command=/usr/local/kannel/sbin/bearerbox -v 2 /etc/kannel/kannel.conf
redirect_stderr=true
stdout_logfile=/dev/fd/1
stdout_logfile_maxbytes=0
priority=1

[program:smsbox]
command=/usr/local/kannel/sbin/smsbox -v 2 /etc/kannel/kannel.conf
redirect_stderr=true
stdout_logfile=/dev/fd/1
stdout_logfile_maxbytes=0
priority=2

#[program:wapbox]
#command=/usr/local/kannel/sbin/wapbox -v 2 /etc/kannel/kannel.conf
#redirect_stderr=true
#stdout_logfile=/dev/fd/1
#stdout_logfile_maxbytes=0
#priority=2

#[program:sqlbox]
#command=/usr/local/kannel/sbin/sqlbox -v 2 /etc/kannel/kannel.conf
#redirect_stderr=true
#stdout_logfile=/dev/fd/1
#stdout_logfile_maxbytes=0
#priority=3

[program:smppbox]
command=/usr/local/kannel/sbin/opensmppbox -v 2 /etc/kannel/opensmppbox.conf
redirect_stderr=true
stdout_logfile=/dev/fd/1
stdout_logfile_maxbytes=0
priority=3

Step 6: Build and Push Docker Image

bash
# Build the Docker image
docker build -t gmelitauri/kannel:latest .

# Push to Docker Hub
docker push gmelitauri/kannel:latest

Step 7: Create Kubernetes Deployment

kannel-deployment.yaml:

yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: kannel-smsc-configs
  namespace: default
data:
  smpp1.conf: |
    group = smsc
    smsc = smpp
    smsc-id = smpp1
    host = SMPP_HOST
    port = 9090
    smsc-username = SMPP_USER
    smsc-password = SMPP_PASSW
    connect-allow-ip = 127.0.0.1
    system-type = smpp
    transceiver-mode = 1
    source-addr-ton = 0
    source-addr-npi = 1
    dest-addr-ton = 0
    dest-addr-npi = 1
    interface-version = 34
    throughput = 30
    max-pending-submits = 5
    esm-class = 0

  smpp2.conf: |
    group = smsc
    smsc = smpp
    smsc-id = smpp2
    host = SMPP_HOST
    port = 9090
    smsc-username = SMPP_USER
    smsc-password = SMPP_PASSW
    connect-allow-ip = 127.0.0.1
    system-type = smpp
    transceiver-mode = 1
    source-addr-ton = 0
    source-addr-npi = 1
    dest-addr-ton = 0
    dest-addr-npi = 1
    interface-version = 34
    throughput = 30
    max-pending-submits = 5
    esm-class = 0

  smpp3.conf: |
    group = smsc
    smsc = smpp
    smsc-id = smpp3
    host = SMPP_HOST
    port = 9090
    smsc-username = SMPP_USER
    smsc-password = SMPP_PASSW
    connect-allow-ip = 127.0.0.1
    system-type = smpp
    transceiver-mode = 1
    source-addr-ton = 0
    source-addr-npi = 1
    dest-addr-ton = 0
    dest-addr-npi = 1
    interface-version = 34
    throughput = 30
    max-pending-submits = 5
    esm-class = 0
	
  smpp4.conf: |
    group = smsc
    smsc = smpp
    smsc-id = smpp-international
    host = SMPP_HOST
    port = 9090
    smsc-username = SMPP_USER
    smsc-password = SMPP_PASSW
    connect-allow-ip = 127.0.0.1
    system-type = smpp
    transceiver-mode = 1
    source-addr-ton = 0
    source-addr-npi = 1
    dest-addr-ton = 0
    dest-addr-npi = 1
    interface-version = 34
    throughput = 30
    max-pending-submits = 5
    esm-class = 0

  smpp5.conf: |
    group = smsc
    smsc = smpp
    smsc-id = smpp-test
    host = SMPP_HOST
    port = 9092
    smsc-username = SMPP_USER
    smsc-password = SMPP_PASSW
    connect-allow-ip = 127.0.0.1
    system-type = smpp
    transceiver-mode = 1
    source-addr-ton = 0
    source-addr-npi = 1
    dest-addr-ton = 0
    dest-addr-npi = 1
    interface-version = 34
    throughput = 30
    max-pending-submits = 5
    esm-class = 0

---

apiVersion: v1
kind: Service
metadata:
  name: kannel
  namespace: default
spec:
  selector:
    app: kannel
  ports:
  - name: admin
    port: 13000
    targetPort: 13000
  - name: sendsms
    port: 13013
    targetPort: 13013
  - name: smpp
    port: 2346
    targetPort: 2346
    protocol: TCP

---


apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: kannel
  namespace: default
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod-dns
    traefik.ingress.kubernetes.io/router.entrypoints: websecure
    traefik.ingress.kubernetes.io/router.tls: "true"
spec:
  ingressClassName: traefik-internal
  tls:
  - hosts:
    - kannel.yourdomain.xyz
    secretName: kannel-tls
  rules:
  - host: kannel.yourdomain.xyz
    http:
      paths:
      - path: /cgi-bin
        pathType: Prefix
        backend:
          service:
            name: kannel
            port:
              number: 13013
      - path: /
        pathType: Prefix
        backend:
          service:
            name: kannel
            port:
              number: 13000
			  
---			  


apiVersion: apps/v1
kind: Deployment
metadata:
  name: kannel
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: kannel
  template:
    metadata:
      labels:
        app: kannel
    spec:
      containers:
      - name: kannel
        image: gmelitauri/kannel:latest
        ports:
        - containerPort: 13000
        - containerPort: 13013
        volumeMounts:
        - name: smsc-configs
          mountPath: /etc/kannel/smsc.d
      volumes:
      - name: smsc-configs
        configMap:
          name: kannel-smsc-configs

Step 8: Deploy to Kubernetes

bash
# Apply the Kubernetes manifest
kubectl apply -f kannel-deployment.yaml

# Verify deployment
kubectl get deployments -n default
kubectl get pods -n default
kubectl get services -n default
kubectl get ingress -n default

Project Structure

kannel-project/
├── bootstrap                    # Autotools setup script for SQLBox
├── Dockerfile                  # Container build file
├── kannel.conf                # Main Kannel configuration
├── opensmppbox.conf           # OpenSMPPBox configuration
├── supervisord.conf           # Process supervisor configuration
└── kannel-deployment.yaml     # Kubernetes deployment manifest

Access Points

• Admin Interface: [***]
  • Username: admin
  • Password: bar
• SMS Sending API: [***]
  • Username: tester
  • Password: foobar
• SMPP Server: Port 2346 (if exposed externally)

SMSC Connections

Monitoring

Check Status

bash
# Port forward to access admin interface
kubectl port-forward deployment/kannel 13000:13000

# Check status
curl http://localhost:13000/status?password=bar

View Logs

bash
# View all logs
kubectl logs deployment/kannel

# Follow logs
kubectl logs -f deployment/kannel

# View specific container process logs
kubectl exec deployment/kannel -- tail -f /var/log/kannel/gateway/kannel.log

Troubleshooting

Common Commands

bash
# Restart deployment
kubectl rollout restart deployment/kannel

# Check pod status
kubectl describe pod -l app=kannel

# Execute into container
kubectl exec -it deployment/kannel -- bash

# Update ConfigMap
kubectl edit configmap kannel-smsc-configs

Test SMS Sending

bash
curl "https://kannel.yourdomain.xyz/cgi-bin/sendsms?username=tester&password=foobar&to=995555123456&text=Test+message&smsc=smpp1"

Notes

• Single replica deployment (*** scaling for HA)
• Logs are output to stdout for container logging
• TLS certificates managed by cert-manager
• Traefik used as ingress controller
• All SMSC passwords are stored in plain text (*** using Kubernetes Secrets)