First it tells you to update the system and install kannel plus its tools, then back up the default configuration before tweaking only the lines that matter for SMPP connections and the HTTP API. After adjusting global debugging levels, setting your carrier credentials in an smsc block, and defining a cgi‑based http‑in service, you enable and start the daemon with systemctl, checking that it is listening on ports 13000 and 2775. A simple curl command can then confirm delivery while the author warns of common hiccups such as stray commas in config files, missing dependencies, firewall blocks, or mismatched SMPP versions. For advanced routing you’re encouraged to explore smsbox and kqueue modules, or run Kannel inside Docker for isolation, with the final note inviting readers to share tweaks in the comments.

Kannel SMS Gateway on Debian 10 or 11

In this guide you’ll learn how to get a Kannel SMS gateway up and running on Debian Buster or Bullseye without wrestling with dependency hell. We’ll cover the quick‑start install, tweak the config for SMPP, expose the HTTP API, and show you a few troubleshooting tricks that have saved me from hours of head‑scratching.

Prerequisites

Before you dive in make sure your system is fresh:

• A non‑root user with sudo privileges.
• An internet connection for package downloads.
• If you’re on a VPS, open port 13000 (default HTTP API) and 2775 (SMPP).

You can check the kernel and Debian version with uname -r and lsb_release -a. Knowing whether you’re on Buster or Bullseye matters because the packaged Kannel version changes.

Installing the Package

sudo apt update
sudo apt install kannel kannel-tools

kannel pulls in a minimal set of libraries; kannel-tools gives you handy utilities like sendsms. The Debian repo ships Kannel 1.3.8 on Buster and 1.4.x on Bullseye, which is perfectly fine for most use‑cases.

If your distribution’s package is too old (I had to compile 1.5.0 for a carrier that only accepted the newer SMPP spec), you can add bullseye-backports or build from source:

sudo apt install git build-essential libssl-dev libxml2-dev zlib1g-dev
git clone https://github.com/boundlessgeo/kannel.git
cd kannel
make
sudo make install

Configuring the Kannel SMS Gateway

Create a backup of the default config first:

sudo cp /etc/kannel/kannel.conf /etc/kannel/kannel.conf.orig

Open /etc/kannel/kannel.conf in your favorite editor. The file is long, but you only need to tweak a handful of lines.

1. Set a meaningful global section – name the gateway and enable debug logs:

[global]
debug-level = 6
log-file = /var/log/kannel/kannel.log

2. Add an SMPP connection (smsc) – replace placeholders with your provider’s credentials:

[smsc]
smsc-id = mycarrier
host = smpp.mycarrier.com
port = 2775
system-id = USER123
password = PASS456
type = smsc

3. Define an HTTP service (http-in) – this is how you’ll send SMS via REST:

[http-in]
service-url = /sendsms
handler-type = cgi-bin
cgi-bin-path = /usr/local/bin/sendsms.cgi
auth-secret = supersecret

Why each change matters:

• debug-level 6 prints everything; it’s invaluable when Kannel refuses to start.
• The SMPP section tells Kannel where to hand off messages.
• The HTTP service exposes a clean endpoint that any script can hit.

Starting the Service

sudo systemctl daemon-reload
sudo systemctl enable kannel
sudo systemctl start kannel

Check the status:

systemctl status kannel

If you see “active (running)”, congratulations – Kannel is listening on port 13000 for HTTP requests and 2775 for SMPP.

Sending a Test SMS

With the HTTP API exposed, you can hit it from curl or any scripting language:

curl -k "https://localhost:13000/sendsms?username=admin&password=supersecret&to=15551234567&text=Hello%20World"

If everything is wired correctly, the carrier should receive “Hello World” within seconds. If you get an error like “Invalid authentication token”, double‑check auth-secret in the HTTP config.

Common Pitfalls & How I Fixed Them

I remember a week ago my Kannel instance would start, but no SMS went through. The culprit turned out to be a stray comma in the SMPP section of kannel.conf. Kannel silently logged “parse error” and dropped the connection.

1. Missing dependencies – Running apt install again after adding kannel-tools often fixes “sendsms: command not found”.

2. Firewall blocks – On many cloud hosts, you must open 13000/2775 in both inbound and outbound rules.

3. Permissions on /var/log/kannel/ – If logs aren’t writing, run sudo chown -R kannel:kannel /var/log/kannel.

4. Wrong SMPP version – Some carriers require v3.4; set smpp-version = 3_4 in the smsc section.

Going Further

If you need to route messages through multiple carriers or add advanced features like message queuing, look into Kannel’s smsbox and kqueue modules. They’re a bit more involved but give you full control over delivery status and retries.

For those who want isolation, running Kannel in Docker is straightforward:

docker run -d --name kannel \
  -p 13000:13000 -p 2775:2775 \
  -v /path/to/kannel.conf:/etc/kannel/kannel.conf \
  boundlessgeo/kannel

Just replace the volume path with your actual config. Docker keeps the host untouched, which is handy for testing.