WAP: Part 2 - Send SMS from Kannel
While there is Kannel documentation, I found it was unclear to me since I wanted to hone in on one thing: sending a URL to my phone. So in this article I'll cover setting up Kannel to send a standard SMS text message to a mobile phone.
I use Gentoo on my box at work. Yes, it can be both powerful and cumbersome, but it also had the best amd64 support when the processors were first available. So I will be covering Kannel installation in Gentoo/AMD64, but other distributions and architectures will probably be similar. The latest version in portage for the amd64 platform (at time of writing) was Kannel 1.4.1:
Once the software is compiled and installed, we'll make a simple Kannel configuration file.
/etc/kannel/kannel.conf
A few notes on the configuration file... The configuration blocks always start with a "group" directive. Also, there should not be any blank lines within a group, but there must be a blank line before the next group. A comment is a non-blank line. Kannel is pretty picky about it's configuration file setup, so it probably won't start if you got it wrong. You can see what all of these configuration directives do by reading the Kannel user guide. You can also look at a good Kannel WAP article from IBM.
Basically, in this configuration Kannel's core daemon will run on port 13000. All of the administration is done via http requests through this port. You'll need to use the specified admin and status passwords for certain operations. Also, I added a wapbox-port and wdp-interface directives. We're not actually going to start the wapbox executable yet, but we need to have one additional group for Kannel to start... so this is just the minimum we need, and these are the two directives required for wapbox. Then we need the wapbox group, and it's required bearerbox-host directive.
There are additional directives for allowing/blocking access to Kannel based on IP etc. I am behind a firewall and I'm not concerned with these settings, but you may choose to use them to protect yourself. Please see the aforementioned guides for this information.
So now let's start Kannel. The init.d startup scripts for Gentoo are terribly broken. Rather than fixing them, I just created a simple script to start up Kannel, specifically the bearerbox executable. We'll revisit this file later to add the other components.
start_kannel.sh
Once it's up and running, you can check the status using your web browser or via the command-line using curl, etc.:
Check the status (requires status password)
Shutdown Kannel (requires admin password)
Now that bearerbox is confirmed to be working (and we shut it back down), let's add smsbox to the mix:
/etc/kannel/kannel.conf
The gsm_modem smsc-id and modems group are configurations that Kannel uses to communicate with my Mutitech USB GPRS modem that I covered in a previous article. The smsbox group specifies that it's running on localhost port 13013 and the "from" phone number we want to show up on all messages is in the global-sender directive. The sendsms-user group defines what username and password we'll need to supply when sending SMS messages. Lastly the sms-service group is used for SMS messages received by Kannel. In this case we're just going to ignore them. Let's add smsbox to the startup file:
start_kannel.sh
The sleep is in there to give bearerbox sufficient time to start and open it's communication ports before the others start and try to connect.
To test the SMS service, we'll connect directly to the sendsms CGI using CURL. The username and password parameters should be the same as user/pass in the sendsms-user group. The number should be a standard US 10-digit mobile phone number, and the text should be URL encoded. I added double quotes to the call to avoid the shell from interpreting the ampersands as background commands.
You should shortly have an SMS message on your mobile. If not, I suggest grepping the /var/log/kannel directory for your area code to see what issues you may have. Things I've run into include bad usernames / passwords and a deactivated SIM card that yielded a "CMS ERROR: 512" from the modem.
WAP: Part 1 - MultiTech USB GPRS Modem in Linux
WAP: Part 2 - Send SMS from Kannel
WAP: Part 3 - WAP Push with Kannel & PHP
WAP: Part 4 - Send SMS from PHP
WAP: Part 5 - Customizing content with WURFL
WAP: Part 6 - Microbrowser content in WML / XHTML MP
Compilation and Installation
I use Gentoo on my box at work. Yes, it can be both powerful and cumbersome, but it also had the best amd64 support when the processors were first available. So I will be covering Kannel installation in Gentoo/AMD64, but other distributions and architectures will probably be similar. The latest version in portage for the amd64 platform (at time of writing) was Kannel 1.4.1:
~ # emerge -av kannel
These are the packages that would be merged, in order:
Calculating dependencies ... done!
[ebuild R ] app-mobilephone/kannel-1.4.1 USE="doc mysql pam pcre sqlite sqlite3 ssl -debug -postgres" 0 kB
Total: 1 package (1 reinstall), Size of downloads: 0 kB
kannel.conf configuration file
Once the software is compiled and installed, we'll make a simple Kannel configuration file.
/etc/kannel/kannel.conf
# CORE BEARERBOX/KANNEL CONFIG
group = core
admin-port = 13000
admin-password = admin_pass
status-password = status_pass
log-file = "/var/log/kannel/kannel.log"
# 0 = 'debug', 1 = 'info', 2 = 'warning', 3 = 'error', 4 = 'panic'
log-level = 4
access-log = "/var/log/kannel/core_access.log"
# Wapbox related
wapbox-port = 13002
wdp-interface-name = "*"
# Smsbox related
#smsbox-port = 13001
# BASE WAPBOX CONFIG
group = wapbox
bearerbox-host = localhost
A few notes on the configuration file... The configuration blocks always start with a "group" directive. Also, there should not be any blank lines within a group, but there must be a blank line before the next group. A comment is a non-blank line. Kannel is pretty picky about it's configuration file setup, so it probably won't start if you got it wrong. You can see what all of these configuration directives do by reading the Kannel user guide. You can also look at a good Kannel WAP article from IBM.
Basically, in this configuration Kannel's core daemon will run on port 13000. All of the administration is done via http requests through this port. You'll need to use the specified admin and status passwords for certain operations. Also, I added a wapbox-port and wdp-interface directives. We're not actually going to start the wapbox executable yet, but we need to have one additional group for Kannel to start... so this is just the minimum we need, and these are the two directives required for wapbox. Then we need the wapbox group, and it's required bearerbox-host directive.
There are additional directives for allowing/blocking access to Kannel based on IP etc. I am behind a firewall and I'm not concerned with these settings, but you may choose to use them to protect yourself. Please see the aforementioned guides for this information.
Starting Kannel
So now let's start Kannel. The init.d startup scripts for Gentoo are terribly broken. Rather than fixing them, I just created a simple script to start up Kannel, specifically the bearerbox executable. We'll revisit this file later to add the other components.
start_kannel.sh
#!/bin/sh
rm /var/log/kannel/*
bearerbox --verbosity 4 --logfile /var/log/kannel/bearerbox.log /etc/kannel/kannel.conf &
Kannel Administration
Once it's up and running, you can check the status using your web browser or via the command-line using curl, etc.:
Check the status (requires status password)
~ # curl http://localhost:13000/status?password=status_pass
Shutdown Kannel (requires admin password)
~ # curl http://localhost:13000/shutdown?password=admin_pass
Sending SMS Messages
Now that bearerbox is confirmed to be working (and we shut it back down), let's add smsbox to the mix:
/etc/kannel/kannel.conf
# CORE BEARERBOX/KANNEL CONFIG
group = core
admin-port = 13000
admin-password = admin_pass
status-password = status_pass
log-file = "/var/log/kannel/kannel.log"
# 0 = 'debug', 1 = 'info', 2 = 'warning', 3 = 'error', 4 = 'panic'
log-level = 4
access-log = "/var/log/kannel/core_access.log"
# Wapbox related
wapbox-port = 13002
wdp-interface-name = "*"
# Smsbox related
smsbox-port = 13001
# BASE WAPBOX CONFIG
group = wapbox
bearerbox-host = localhost
# GSM DEVICE FILE INFO
group = smsc
smsc = at
smsc-id = gsm_modem
modemtype = wavecom
device = /dev/ttyUSB0
keepalive = 30
max-error-count = 5
sim-buffering = true
# MODEM CONFIGURATION
group = modems
id = wavecom
name = Wavecom
detect-string = "WAVECOM"
speed = 115200
reset-string = "ATZ"
init-string = "AT+CNMI=1,2,0,1,0;+CMEE=1"
# trying this to see if it resolves errors when the
# modem erroneously returns ERROR to the AT+CPIN? command
no-pin = true
# SMSBOX SETUP
group = smsbox
bearerbox-host = localhost
sendsms-port = 13013
global-sender = 8005551212
log-file = "/var/log/kannel/smsbox.log"
log-level = 4
access-log = "/var/log/kannel/smsbox_access.log"
# SEND-SMS USERS
group = sendsms-user
username = sms_user
password = sms_pass
forced-smsc = gsm_modem
# SMS SERVICES
# there should be default always
group = sms-service
keyword = default
text = "No service specified"
max-messages = 0
catch-all = true
The gsm_modem smsc-id and modems group are configurations that Kannel uses to communicate with my Mutitech USB GPRS modem that I covered in a previous article. The smsbox group specifies that it's running on localhost port 13013 and the "from" phone number we want to show up on all messages is in the global-sender directive. The sendsms-user group defines what username and password we'll need to supply when sending SMS messages. Lastly the sms-service group is used for SMS messages received by Kannel. In this case we're just going to ignore them. Let's add smsbox to the startup file:
start_kannel.sh
#!/bin/sh
rm /var/log/kannel/*
bearerbox --verbosity 4 --logfile /var/log/kannel/bearerbox.log /etc/kannel/kannel.conf &
sleep 10
smsbox --verbosity 4 --logfile /var/log/kannel/smsbox.log /etc/kannel/kannel.conf &
The sleep is in there to give bearerbox sufficient time to start and open it's communication ports before the others start and try to connect.
To test the SMS service, we'll connect directly to the sendsms CGI using CURL. The username and password parameters should be the same as user/pass in the sendsms-user group. The number should be a standard US 10-digit mobile phone number, and the text should be URL encoded. I added double quotes to the call to avoid the shell from interpreting the ampersands as background commands.
~ # curl "http://localhost:13013/cgi-bin/sendsms?username=sms_user&password=sms_pass&to=7025551212&text=Hello+world"
0: Accepted for delivery
You should shortly have an SMS message on your mobile. If not, I suggest grepping the /var/log/kannel directory for your area code to see what issues you may have. Things I've run into include bad usernames / passwords and a deactivated SIM card that yielded a "CMS ERROR: 512" from the modem.
Articles In This Series:
WAP: Part 1 - MultiTech USB GPRS Modem in Linux
WAP: Part 2 - Send SMS from Kannel
WAP: Part 3 - WAP Push with Kannel & PHP
WAP: Part 4 - Send SMS from PHP
WAP: Part 5 - Customizing content with WURFL
WAP: Part 6 - Microbrowser content in WML / XHTML MP