Kannel 1.3.1 User’s Guide Open Source WAP and SMS gateway Lars Wirzenius Gateway architect Wapit Ltd liw@wapit.com http://www.wapit.com http://www.kannel.org Kalle Marjola Manager Wapit Ltd rpr@wapit.com http://www.wapit.com http://www.kannel.org Andreas Fink Chairman & CTO Global Networks Inc.
andreas@fink.org http://www.smsrelay.com http://www.gni.ch Bruno Rodrigues bruno.rodrigues@litux.org http://litux.org/bruno Stipe Tolj CTO & CIO Wapme Systems AG tolj@wapme-systems.de http://www.wapme.de http://www.kannel.org Aarno Syvänen Chief MMS Developer Global Networks Inc. as@gni.ch http://www.gni.
Kannel 1.3.1 User’s Guide: Open Source WAP and SMS gateway by Lars Wirzenius, Kalle Marjola, Andreas Fink, Bruno Rodrigues, Stipe Tolj, and Aarno Syvänen Abstract This document describes how to install and use Kannel, the Open Source WAP and SMS Gateway originally developed by Wapit Ltd (now out of business) and now being developed further by the open source community, namely the Kannel Group. Revision History Revision 1.3.1 2006.07.
Table of Contents 1. Introduction............................................................................................................................................1 Overview of WAP ..............................................................................................................................1 Overview of WAP Push......................................................................................................................2 Overview of SMS......................................
Smsbox configuration.............................................................................................................51 Smsbox routing inside bearerbox ...........................................................................................55 SMS-service configurations....................................................................................................56 How sms-service interprets the HTTP response.....................................................................
Running Kannel with fakesmsc connections ...................................................................................94 Starting fake SMS center........................................................................................................94 Fake messages...............................................................................................................95 Fakesmsc command line options ..................................................................................95 C.
List of Tables 3-1. Core Group Variables .........................................................................................................................14 3-2. Kannel Command Line Options.........................................................................................................20 3-3. Kannel HTTP Administration Commands .........................................................................................22 4-1. Wapbox Group Variables...............................................
Chapter 1. Introduction This chapter introduces WAP and SMS in general terms, and explains the role of the gateway in WAP and SMS, outlining their duties and features. It also explains why the Kannel project was started in the first place, and why it is open source. With hundreds of millions of mobile phones in use all over the world, the market for services targeted at mobile users is mind-bogglingly immense. Even simple services find plenty of users, as long as they’re useful or fun.
Chapter 1. Introduction intermittent bandwidth, and extremely awkward input mechanisms. Most existing HTML pages do not work on mobiles phones, and never will. WAP defines a completely new markup language, the Wireless Markup Language (WML), which is simpler and much more strictly defined than HTML. It also defines a scripting language, WMLScript, which all browsers are required to support. To make things even simpler for the phones, it even defines its own bitmap format (Wireless Bitmap, or WBMP).
Chapter 1. Introduction instance, when it must send a mail notification or a stock quote. For this purpose Wapforum defined WAP Push. Push is an application level service, sitting on the top of existing WAP stack. It defines two protocols, OTA and PAP. OTA is a ligthweigth protocol speaking with WAP stack (to be more specific, with WSP), PAP speaks with the push initiator.
Chapter 1. Introduction Figure 1-2. Logical position of SMS gateway between a phone and a content server. An SMS gateway can also be used to relay SMS messages from one GSM network to another, if the networks do not roam messages normally. Kannel works as an SMS gateway, talking with many different kind of SMS centers, and relaying the messages onward to content providers, as HTTP queries.
Chapter 1. Introduction • The Gnome XML library (known as gnome-xml and libxml), version 2.2.5 or newer. See http://xmlsoft.org/xml.html. • GNU Make. • Posix threads (pthread.h). • GNU Bison 1.28 if you modify the WMLScript compiler. • DocBook markup language tools (jade, jadetex, DocBook stylesheets, etc; see README.docbook), if you want to format the documentation (pre-formatted versions are available). Hardware requirements are fluffier.
Chapter 2. Installing the gateway This chapter explains how the gateway can be installed, either from a source code package or by using a pre-compiled binary version. The goal of this chapter is to get the gateway compiled and all the files in the correct places; the next chapter will explain how the gateway is configured. Getting the source code The source code to Kannel is available for download at http://www.kannel.3glab.org/download.shtml.
Chapter 2. Installing the gateway • GNU autoconf, if you want to modify the configuration script. Compiling the gateway If you are using Kannel on a supported platform, or one that is similar enough to one, compiling Kannel is trivial. After you have unpacked the source package of your choosing, or after you have checked out the source code from CVS, enter the following commands: .
Chapter 2. Installing the gateway You may need to add compilations flags to configure: CFLAGS=’-pthread’ ./configure The above, for instance, seems to be required on FreeBSD. If you want to develop Kannel, you probably want to add CFLAGS that make your compiler use warning messages. For example, for GCC: CFLAGS=’-Wall -O2 -g’ ./configure (You may, at your preference, use even stricter checking options.
Chapter 2. Installing the gateway Installing Kannel 1. Download the binary RPM packet from the Kannel web site. 2. Log in as root: su - 3. Install the RPM package: rpm -ivh kannel-VERSION.i386.rpm Upgrading Kannel 1. Download the binary RPM packet from the Kannel web site. 2. Log in as root 3. Upgrade the RPM package: rpm -Uvh kannel-VERSION.i386.rpm Removing Kannel 1. Log in as root: 2.
Chapter 2. Installing the gateway 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 the same directory there is an example file called smskannel.conf. It has 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.
Chapter 2. Installing the gateway 3. Install or upgrade the DEB package: dpkg -i kannel-VERSION .deb Removing Kannel 1. Log in as root: 2. Remove the package keeping configuration files: dpkg --remove kannel 3. Remove the package completely: 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. /etc/init.
Chapter 2. Installing the gateway The documentation will be installed at /usr/share/doc/kannel/. In the Kannel documentation directory there is a html file called control.html. It is an example file that shows how to use the Kannel http administration interface. It also has a template for sending SMS messages. Aditionally to kannel-VERSION.deb, there’s now an optional kannel-docs-VERSION.deb with documentation (userguide et al) and a kannel-extras-VERSION.deb with contrib and test stuff.
Chapter 3. Using the gateway This chapter explains how the gateway core, bearerbox, is configured and used. It covers the configuration file, keeping an eye on the gateway while it is running, and using the HTTP interface to control the gateway. After this chapter there is distinct chapter for each kind of gateway use: WAP gateway, SMS gateway and combined gateway. These chapters explain the configuration and other aspects of gateway of that type.
Chapter 3. Using the gateway Lines 1 and 6 are comment lines. Line 5 separates the two groups. The remaining lines define variables. The group type is defined by the group variable value. The various variables that are understood in each type of configuration group are explained below. Some variable values are marked as ’bool’. The value for variable can be like true, false, yes, no, on, off, 0 or 1.
Chapter 3. Using the gateway Core configuration Configuration for Kannel MUST always include a group for general bearerbox configuration. This group is named as ’core’ in configuration file, and should be the first group in the configuration file. As its simplest form, ’core’ group looks like this: group = core admin-port = 13000 admin-password = f00bar Naturally this is not sufficient for any real use, as you want to use Kannel as an SMS gateway, or WAP gateway, or both.
Chapter 3. Using the gateway Variable admin-deny-ip Value Description IP-list These lists can be used to prevent connection from given IP addresses. Each list can have several addresses, separated with semicolons (’;’). An asterisk (’*’) can be used as a wildcard in a place of any ONE number, so *.*.*.* matches any IP. admin-allow-ip smsbox-port (c) smsbox-port-ssl (o) wapbox-port (c) wapbox-port-ssl (o) port-number This is the port number to which the smsboxes, if any, connect.
Chapter 3. Using the gateway Variable box-deny-ip Value Description IP-list These lists can be used to prevent box connections from given IP addresses. Each list can have several addresses, separated with semicolons (’;’). An asterisk (’*’) can be used as a wildcard in place of any ONE number, so *.*.*.* matches any IP. IP-list These lists can be used to prevent UDP packets from given IP addresses, thus preventing unwanted use of the WAP gateway. Used the same way as box-deny-ip and box-allow-ip.
Chapter 3. Using the gateway Variable unified-prefix white-list black-list Value Description prefix-list String to unify received phone numbers, for SMSC routing and to ensure that SMS centers can handle them properly. This is applied to ’sender’ number when receiving SMS messages from SMS Center and for ’receiver’ number when receiving messages from SMSbox (either sendsms message or reply to original message).
Chapter 3. Using the gateway Variable Value Description filename A file in which any received SMS messages are stored until they are successfully handled. By using this variable, no SMS messages are lost in Kannel, but theoretically some messages can duplicate when system is taken down violently. http-proxy-host hostname Enable the use of an HTTP proxy for all HTTP requests.
Chapter 3. Using the gateway Variable ssl-trusted-ca-file dlr-storage maximum-queue-length Value Description filename This file contains the certificates Kannel is willing to trust when working as a HTTPS client. If this option is not set, certificates are not validated and those the identity of the server is not proven. type Defines the way DLRs are stored. If you have build-in external DLR storage support, i.e. using MySQL you may define here the alternative storage type like ’mysql’.
Chapter 3. Using the gateway Running Kannel To start the gateway, you need to start each box you need. You always need the bearer box, and depending on whether you want WAP and SMS gateways you need to start the WAP and SMS boxes. If you want, you can run several of them, but we’ll explain the simple case of only running one each.
Chapter 3. Using the gateway --verbosity Set debug-places for ’debug’ level output. -D --debug -F Log to file named file-name, too. Does not overrun or affect any logfile defined in configuration file. --logfile -V --fileverbosity -S Set verbosity level for that extra logfile (default 0, which means ’debug’). Does not affect verbosity level of the logfile defined in configuration file, not verbosity level of the stdout output.
Chapter 3. Using the gateway The state can be changed via HTTP administration interface (see below), and shutdown can also be initiated via TERM or INT signal from terminal. In addition, the bearerbox can be started already in suspended or isolated state with -S or -I command line option, see above. HTTP administration Kannel can be controlled via an HTTP administration interface.
Chapter 3. Using the gateway shutdown Bring down the gateway, by setting state to ’shutdown’. After a shutdown is initiated, there is no other chance to resume normal operation. However, ’status’ command still works. Password required. If shutdown is sent for a second time, the gateway is forced down, even if it has still messages in queue. flush-dlr If Kannel state is ’suspended’ this will flush all queued DLR messages in the current storage space. Password required.
Chapter 4. Setting up a WAP gateway This chapter tells you how to set Kannel up as a WAP gateway. WAP gateway configuration To set up a WAP Kannel, you have to edit the ’core’ group in the configuration file, and define the ’wapbox’ group. You must set following variables for the ’core’ group: wapbox-port and wdp-interface-name. See previous chapter about details of these variables. With standard distribution, a sample configuration file wapkannel.conf is supplied.
Chapter 4. Setting up a WAP gateway Variable map-url Value Description URL-pair The pair is separated with space. Adds a single mapping for the left side URL to the given destination. If you append an asterisk ‘*’ to the left side URL, its prefix Is matched against the incoming URL. Whenever the prefix matches, the URL will be replaced completely by the right side.
Chapter 4. Setting up a WAP gateway Variable Value log-file filename log-level number 0..5 Description As with bearerbox ’core’ group. syslog-level force-sar smart-errorsr number Messages of this log level or higher will also be sent to syslog, the UNIX system log daemon. The wapbox logs under the ’daemon’ category. The default is not to use syslog, and you can set that explicitly by setting syslog-level to ’none’.
Chapter 5. Setting up a SMS Gateway This chapter is a more detailed guide on how to set up Kannel as an SMS gateway. Required components To set up an SMS gateway, you need, in addition to a machine running Kannel, access to (an operator’s) SMS center, or possibly to multiple ones. The list of supported SMS centers and their configuration variables is below. If you do not have such access, you can still use Kannel as an SMS gateway via phone-as-SMSC feature, by using a GSM phone as a virtual SMS center.
Chapter 5. Setting up a SMS Gateway Variable Value Description group (m) smsc This is a mandatory variable smsc (m) string Identifies the SMS center type. See below for a complete list. string An optional name or id for the smsc. Any string is acceptable, but semicolon ’;’ may cause problems, so avoid it and any other special non-alphabet characters. This ’id’ is written into log files and can be used to route SMS messages, and to specify the used SMS-service. Several SMSCs can have the same id.
Chapter 5. Setting up a SMS Gateway Variable allowed-prefix denied-prefix preferred-prefix Value Description prefix-list A list of phone number prefixes which are accepted to be sent through this SMSC. Multiple entries are separated with semicolon (’;’). For example, "040;050" prevents sending of any SMS message with prefix of 040 or 050 through this SMSC. If denied-prefix is unset, only this numbers are allowed. If set, number are allowed if present in allowed or not in denied list.
Chapter 5. Setting up a SMS Gateway Variable unified-prefix alt-charset Value Description prefix-list String to unify received phone numbers, for SMSC routing and to ensure that SMS centers can handle them properly. This is applied to ’sender’ number when receiving SMS messages from SMS Center and for ’receiver’ number when receiving messages from SMSbox (either sendsms message or reply to original message).
Chapter 5. Setting up a SMS Gateway group = smsc smsc = cimd host = 100.101.102.103 port = 600 smsc-username = foo smsc-password = bar The driver for CIMD2 is a "receiving SME" and expects the SMSC to be configured for that. It also expects the SMSC to automatically send stored messages as soon as Kannel logs in (this is the normal configuration). group = smsc smsc = cimd2 host = 100.101.102.
Chapter 5. Setting up a SMS Gateway Variable Value sender-prefix string Description The number that the SMSC will add in front of the sender number of all messages sent from Kannel. If Kannel is asked to send a message, it will remove this prefix from the sender number so that the SMSC will add it again. If the prefix was not present, Kannel will log a warning and will not send the sender number.
Chapter 5. Setting up a SMS Gateway Variable Value Description host (c) hostname port (c) port-number alt-host hostname alt-port port-number smsc-username string Machine that runs SMSC. As IP (100.100.100.100) or hostname (their.machine.here) Port number in the SMSC host machine Optional alternate Machine that runs SMSC. As IP (100.100.100.100) or hostname (their.machine.
Chapter 5. Setting up a SMS Gateway Variable Value connect-allow-ip IP-list Description If set, only connections from these IP addresses are accepted to receive-port. TCP/IP connection only. idle-timeout number (seconds) keepalive number (seconds) If this option is set to a value larger than 0, then the connection will be closed after the configured amount of seconds without activity. This option interacts with the keepalive configuration option.
Chapter 5. Setting up a SMS Gateway Variable Value wait-ack-expire number flow-control number Description Defines what kind of action should be taken if the the ack of a message expires. The options for this value are: 0x00 disconnect/reconnect, (default) 0x01 - as is now, requeue, but this could potentially result in the msg arriving twice 0x02 - just carry on waiting (given that the wait-ack should never expire this is the mst accurate) This SMSC can support two types of flow control.
Chapter 5. Setting up a SMS Gateway Variable Value my-number number alt-charset number Description If the large account number is different from the short number, assign it with this variable. For example, if short number is 12345 and large account is 0100100100101234 (IP+port), set my-number to 12345 and every message received will have that receiver. Defines which character conversion kludge may be used for this specific link. Currently implemented alternative charsets are defined in "alt_charsets.
Chapter 5. Setting up a SMS Gateway Variable Value transceiver-mode bool receive-port port-number smsc-username (m) string smsc-password (m) string system-type (m) string Description Attempt to use a TRANSCEIVER mode connection to the SM-SC. It uses the standard transmit ’port’, there is no need to set ’receive-port’. This is a SMPP 3.4 only feature and will not work on an earlier SM-SC.
Chapter 5. Setting up a SMS Gateway Variable Value interface-version number Description Change the "interface version" parameter sent from Kannel to a value other then 0x34 (for SMPP v3.4). the value entered here should be the hexadecimal representation of the interface version parameter. for example, the default (if not set) is "34" which stands for 0x34. for SMPP v3.3 set to "33". string According to the SMPP 3.4 spec this is supposed to affect which MS’s can send messages to this account.
Chapter 5. Setting up a SMS Gateway Variable Value reconnect-delay number source-addr-ton number source-addr-npi number source-addr-autodetect boolean dest-addr-ton number dest-addr-npi number Description Optional the time between attemps to connect an ESME to an SMSC having failed to connect initating or during an SMPP session. The default is 10 seconds. Optional, source address TON setting for the link. (Defaults to 0). Optional, source address NPI setting for the link. (Defaults to 1).
Chapter 5. Setting up a SMS Gateway Variable Value msg-id-type number Description Optional, specifies which number base the SMSC is using for the message ID numbers in the corresponding submit_sm_resp and deliver_sm PDUs. This is required to make delivery reports (DLR) work on SMSC that behave differently. The number is a combined set of bit 1 and bit 2 that indicate as follows: bit 1: type for submit_sm_resp, bit 2: type for deliver_sm.
Chapter 5. Setting up a SMS Gateway you find out the more exact meaning, please send a report. The 5.0 implementation uses X.25 access gateway.
Chapter 5. Setting up a SMS Gateway smsc-username = foo smsc-password = foo Variable Value Description host (m) hostname Machine that runs SMSC. As IP (10.11.12.13) or hostname (host.foobar.com) port (m) port-number smsc-username (m) string smsc-password (m) string reconnect-delay number source-addr-ton number source-addr-npi number dest-addr-ton number dest-addr-npi number priority number The port number for the connection to the SMSC.
Chapter 5. Setting up a SMS Gateway pin = 2345 Variable Value Description modemtype string Modems from different manufacturers have slightly different behaviour. We need to know what type of modem is used. device (m) device-name pin string validityperiod integer alt-dcs boolean Modem Type Modems wavecom siemens-tc35 Wavecom Nokia Premicell Siemens M20 (this modem have some bugs) Siemens TC35 falcom Falcom premicell siemens The device the modem is connected to, like /dev/ttyS0.
Chapter 5. Setting up a SMS Gateway Modem Type nokiaphone ericsson Modems Nokia 6210, 7110, 8210 (tested). Probably other Nokia phones too. Ericsson GSM modem 2 This new driver is replacing the old GSM Modem driver from Kannel.
Chapter 5. Setting up a SMS Gateway Variable Value validityperiod integer retry boolean Description How long the message will be valid, i.e., how long the SMS center (the real one, not the phone acting as one for Kannel) will try to send the message to the recipient. Encoded as per the GSM 03.40 standard, section 9.2.3.12. Default is 167, meaning 24 hours.
Chapter 5. Setting up a SMS Gateway Modem definitions are now multiple groups present in kannel.conf, either directly or, for example, by including the example modems.conf. (See Inclusion of configuration files) Variable Value Description group modems id string name string This is a mandatory variable This is the the id that should be used in modemtype variable from AT2 The name of this modem configuration. Used in logs String to use when trying to detect the modem.
Chapter 5. Setting up a SMS Gateway Variable Value sendline-sleep number (miliseconds) keepalive-cmd string message-storage string enable-mms boolean Description Optional, defaults to 100 miliseconds. The sleep time after sending a AT command. Optional, defaults to "AT". If keepalive is activated in AT2 group, this is the command to be sent.
Chapter 5. Setting up a SMS Gateway group = smsc smsc = fake port = 10000 connect-allow-ip = 127.0.0.1 Variable Value Description host (m) hostname Machine that runs the SMSC. As IP (100.100.100.100) or hostname (their.machine.here) port (m) port-number connect-allow-ip IP-list Port number in smsc host machine If set, only connections from these IP addresses are accepted.
Chapter 5. Setting up a SMS Gateway Variable Value port (m) port-number connect-allow-ip IP-list Description Port number in which Kannel listens to (MO) messages from other gateway IPs allowed to use this interface. If not set, "127.0.0.1" (localhost) is the only host allowed to connect. smsc-username string Username associated to connection, if needed. ’kannel’ requires this, and it is the same as send-sms username at other end. smsc-password string Password for username, if needed.
Chapter 5.
Chapter 5.
Chapter 5. Setting up a SMS Gateway SMSBox inherits from core the following fields: smsbox-port http-proxy-port http-proxy-host http-proxy-username http-proxy-password http-proxy-exceptions ssl-certkey-file Table 5-4. Smsbox Group Variables Variable Value Description group (m) smsbox This is a mandatory variable bearerbox-host (m) hostname The machine in which the bearerbox is. string Optional smsbox instance identifier.
Chapter 5. Setting up a SMS Gateway Variable sendsms-chars global-sender Value Description string Only these characters are allowed in ’to’ field when send-SMS service is requested via HTTP. Naturally, you should allow at least 0123456789. The space character (’ ’) has special meaning: it is used to separate multiple phone numbers from each other in multi-send. To disable this feature, do not have it as an accepted character. If this variable is not set, the default set "0123456789 +-" is used.
Chapter 5. Setting up a SMS Gateway Variable Value Description If set, replaces the SMS message sent back when kannel could not represent the result as a SMS message. Defaults to Result reply-couldnotrepresent reply-requestfailed string could not be represented as an SMS message.. string If set, replaces the SMS message sent back when kannel could not contact http service. Defaults to Request Failed. If set, replaces the SMS message sent back when message is empty.
Chapter 5. Setting up a SMS Gateway log-level = 0 Smsbox routing inside bearerbox 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 determinated route for inbound messages. The smsbox routing solves this for the inbound direction.
Chapter 5. Setting up a SMS Gateway Variable smsc-ids shortcuts Value Description word-list If set, specifies from which smsc-ids all inbound messages should be routed to this smsbox instance. List contains smsc-ids seperated by semilon (";"). This rule may be used to pull any smsc specific message stream to an smsbox instance. number-list If set, specifies which receiver numbers for inbound messages should be routed to this smsbox instance. List contains numbers seperated by semilon (";").
Chapter 5. Setting up a SMS Gateway Variable keyword (m) aliases name get-url (c) post-url (c) post-xml (c) file (c) Value Description word Services are identified by the first word in the SMS Each ‘%s’ in the URL corresponds to one word in the SMS message. Words are separated with spaces. A keyword is matched only if the number of words in the SMS message is the same as the number of ‘%s’ fields in the URL.
Chapter 5. Setting up a SMS Gateway Variable text (c) Value Description string Predefined text answer. Only if there is neither url nor file set. Escape codes (parameters) are usable here, too. Executes the given shell command as the current UID of the running smsbox user and returns the output to stdout as reply. Escape codes (parameters) are usable here, too.
Chapter 5. Setting up a SMS Gateway Variable Value Description prefix-list A list of phone number prefixes of the receiver number which are accepted to be received by this service. This may be used to allow only inbound SMS to certain shortcut numbers to be allowed to this service. denied-receiver-prefix prefix-list A list of phone number prefixes of the receiver number which are NOT accepted to be sent through this SMSC. catch-all bool Catch keyword regardless of ’%s’ parameters in pattern.
Chapter 5. Setting up a SMS Gateway Variable assume-plain-text Value Description bool If client does not set Content-Type for reply, it is normally application/octet-stream which is then handled as data in kannel. This can be forced to be plain/text to allow backward compatibility, when data was not expected. Long messages can be sent as independent SMS messages with concatenation = false or as concatenated messages with concatenation = true.
Chapter 5. Setting up a SMS Gateway Variable Value suffix string white-list black-list Description URL Load a list of accepted senders of SMS messages. If a sender of an SMS message is not in this list, any message received from the SMSC is rejected, unless a black-list service is defined. See notes of phone number format from numhash.h header file. URL As white-list, but SMS messages from these numbers are automatically discarded Notes: a.
Chapter 5.
Chapter 5. Setting up a SMS Gateway text/html text/vnd.wap.wml text/xml application/octet-stream Tags are removed, rest is chopped to fit an SMS message. Processed like HTML. Processed as a POST-XML. See XML Post The body will be transmitted as the SMS message, as 8-bit data. This can be avoided by setting assume-plain-text variable on for the SMS-service. Extended headers Kannel uses and accepts several X-Kannel headers to be used with SMS-services. Table 5-8.
Chapter 5. Setting up a SMS Gateway Kannel POST Kannel can do POST if service is contains a post-url="...". Table 5-9.
Chapter 5. Setting up a SMS Gateway alt-dcs pid dlr-mask dlr-url username username password password account smsc-id smsc-id service-name There could be several da entries for sendsms-user to enable multi-recipient messages.
Chapter 5. Setting up a SMS Gateway SendSMS-user configurations To enable an SMS push, you must set sendsms-port into the ’smsbox’ group and define one or more ’sendsms-user’ groups. Each of these groups define one account, which can be used for the SMS push, via HTTP interface (see below) Table 5-10. SendSMS-User Group Variables Variable Value Description group (m) sendsms-user This is a mandatory variable username (m) string Name for the user/account.
Chapter 5. Setting up a SMS Gateway Variable allowed-prefix denied-prefix white-list black-list dlr-url Value Description prefix-list A list of phone number prefixes which are accepted to be sent using this username. Multiple entries are separated with semicolon (’;’). For example, "040;050" prevents sending of any SMS message with prefix of 040 or 050 through this SMSC. If denied-prefix is unset, only this numbers are allowed. If set, number are allowed if present in allowed or not in denied list.
Chapter 5. Setting up a SMS Gateway External delivery report (DLR) storage Delivery reports are supported by default internaly, which means all DLRs are stored in the memory of the bearerbox process. This is problematic if bearerbox crashes or you take the process down in a controlled way, but there are still DLRs open. Therefore you may use external DLR storage places, i.e. a MySQL database.
Chapter 5. Setting up a SMS Gateway In addition to that you must have a dlr-db group defined that specifies the table field names that are used to the DLR attributes and a sdb-connection group that defines the LibSDB ressource itself. Here is the example configuration from doc/examples/dlr-sdb.
Chapter 5. Setting up a SMS Gateway Variable Value Description field-timestamp (m) string The table field that is used for the timestamp data. field-destination (m) string The table field that is used for the destination number data. field-service (m) string The table field that is used for the service username data. string The table field that is used for the DLR URL which is triggered when the DLR for this message arrives from the SMSC.
Chapter 5. Setting up a SMS Gateway MySQL connection configuration For several reasons external storage may be required to handle dynamical issues, i.e. DLRs, sms-service, sendsms-user, ota-setting, ota-bookmark definitions and so on. To define a MySQL database connection you simple need to specify a mysql-connection group as follows: Table 5-12.
Chapter 5. Setting up a SMS Gateway phone as a XML document, but this method is perhaps more suitable for continous provisioning. If you want to send multiple OTA configurations through the smsbox and you do not want to send XML documents, you will have to declare a ota-id string to the different ota-setting groups. Table 5-13. OTA Setting Group Variables Variable Value Description group ota-setting This is a mandatory variable string An optional name or id for the ota-setting.
Chapter 5. Setting up a SMS Gateway phonenumber = 013456789 bearer = data calltype = analog connection = cont pppsecurity = off authentication = normal login = wapusr secret = thepasswd And a ’sendsms-user’ to use with it. With concatenation enabled: group = sendsms-user username = otauser password = foo max-messages = 2 concatenation = 1 Table 5-14.
Chapter 5. Setting up a SMS Gateway Redirected replies The basic service system always sends the answer back to original requester, but sometimes the content server needs to send something to other terminals or delay the answer. To create such systems, an SMS push is used. The idea is to get the initial request, but then send no reply. Instead, the reply (if any) is sent via HTTP sendsms-interface as SMS Push.
Chapter 5. Setting up a SMS Gateway accepted-smsc = B get-url = "..." As can be seen, the smsc-id is used to identify the SMS center from which the message came. Then, the denied-smsc-id variable is used to prevent messages originally from the other SMS center from being sent through the other one. Finally ’sms-service’ groups are defined with accepted-smsc so that they only accept messages from certain SMS center.
Chapter 5. Setting up a SMS Gateway Password associated with given username. Must match password (or pass) from to string corresponding field in the ’sendsms-user’ group of the Kannel configuration, or ’Authorization failed’ is returned. string Phone number of the sender. This field is usually overridden by the SMS Center, or it can be overridden by faked-sender variable in the sendsms-user group. If this variable is not set, smsbox global-sender is used.
Chapter 5. Setting up a SMS Gateway smsc string Optional virtual smsc-id from which the message is supposed to have arrived. This is used for routing purposes, if any denied or preferred SMS centers are set up in SMS center configuration. This variable can be overridden with a forced-smsc configuration variable. Likewise, the default-smsc variable can be used to set the SMSC if it is not set otherwise. flash number Deprecated. See mclass. number Optional. Sets the Message Class in DCS Field.
Chapter 5. Setting up a SMS Gateway validity deferred dlrmask dlrurl number (minutes) Optional. If given, kannel will inform SMS Center that it should only try to send the message for this many minutes. If the destination mobile is off other situation that it cannot receive the sms, the smsc discards the message. Note: you must have your kannel box time syncronized with the SMS Center. number (minutes) Optional.
Chapter 5. Setting up a SMS Gateway account string Account name or number to carry forward for billing purposes. This field is logged as ACT in the log file so it allows you to do some accounting on it if your front end uses the same username for all services but wants to distinguish them in the log. In the case of a HTTP SMSC type the account name is prepended with the servicename (username) and a colon (:) and forwarded to the next insta ce of kannel. This allows hierarchical accounting. Notes: a.
Chapter 5. Setting up a SMS Gateway You can send either settings or bookmark, set CGI variable type accordingly. Default for this variable is settings. Here is an example XML document (this one contains CSD settings for logging in to a mobile service; note that you must store DTD locally): PAGE 89Chapter 5. Setting up a SMS Gateway otaid username string Name or ID of the ’ota-setting’ group in Kannel configuration that should be sent to the phone. This variable is optional. If it is not given the first ’ota-setting’ group is sent. This is unnecessary when a XML document is sended to the phone. string Username of the ’sendsms-user’ group in Kannel configuration, that has been configured to send OTA messages. Password associated with given username.
Chapter 6. Setting up a SMS&WAP gateway This chapter tells you how to set Kannel up as a combined WAP and SMS gateway. SMS&WAP gateway configuration Configuration is done as explained in previous chapters, you simply have to include all the data from both chapters into the configuration file. Running SMS&WAP gateway There are no special tricks to this, just launch both the smsbox and the wapbox in addition to the bearerbox, using multiple hosts if needed.
Chapter 7. Setting up Push Proxy Gateway This chapter explains how to set up a push proxy gateway (PPG). An example configuration file are given. A working push proxy gateway is described. Configuring ppg core group, for push initiator (PI) interface PPG configuration group defines gateway’s service interface. Configuring a PPG working with a trusted PI is easiest. Actually, you need no configuration at all: in this case a PPG with default values will be set up.
Chapter 7. Setting up Push Proxy Gateway Variable Value Description ssl-server-key-file string Mandatory value for PPG HTTPS support. The file containing server’s ssl private key. ppg-url url URL locating PPG services. Default /wappush . global-sender string Sender phone number required by some protocols. Number of concurrent pushes expected. Note that PPG does work even value is too low; it will only be slower. Default 100.
Chapter 7. Setting up Push Proxy Gateway variables are elaborated in table 7.2. As an example, let us see how to configure a ppg user (a pi, named here ’picom’) allowed to send pushes only from a specified ip. group = wap-push-user wap-push-user = picom ppg-username = foo ppg-password = bar allow-ip = 62.254.217.163 It goes without saying that in real systems you must use more complex passwords than bar. Table 7-2.
Chapter 7. Setting up Push Proxy Gateway Variable deny-ip default-smsc forced-smsc Value Description ip-list Defines ips wherefrom this pi cannot do pushes. Ips not mentioned in either list are denied, too. string If no SMSC ID is given with the wappush HTTP request (see below), use this one as default route for this specific push user. string Allow only routing to a defined SMSC ID for this specific push user.
Chapter 7. Setting up Push Proxy Gateway smsc = http smsc-id = HTTP port = 10000 system-type = kannel smsc-username = foo smsc-password = bar no-sender = true no-coding = true send-url = http://host:port/path To set up smsbox. This group will eventually disappear, use here only necessary configuration variables. group = smsbox bearerbox-host = localhost Kannel sources contain a sample push configuration file gw/pushkannel.conf.
Chapter 7. Setting up Push Proxy Gateway Default network and bearer used by push proxy gateway If network and bearer attributes of the pap control document are missing or set any, Kannel uses address type for routing purposes: if the address type is a phone number (TYPE=PLMN), network defaults to GSM and bearer to SMS; if it is a IP-address (TYPE=IPv4), network defaults to GSM and bearer to CSD. So following minimal pap document works:
Chapter 8. Using SSL for HTTP This chapter explains how you can use SSL to ensure secure HTTP communication on both, client and server side. Beware that the gateway, is acting in both roles of the HTTP model: 1. as HTTP client, i.e. for requesting URLs while acting as WAP gateway and while fetching information for the SMS services. 2. as HTTP server, i.e. for the administration HTTP interface, the PPG and for the sendsms HTTP interface.
Chapter 8. Using SSL for HTTP Using SSL server support for the sendsms HTTP interface To use the SSL-enabled HTTP server please use the following configuration directive within the core and smsbox groups group = core ... ssl-server-cert-file = "filename" ssl-server-key-file = "filenane" group = smsbox ... sendsms-port-ssl = true Using SSL server support for PPG HTTPS interface If you want use PAP over HTTPS, (it is, a https scheme) add following directives to the ppg core group: group = ppg ...
Chapter 9. Delivery Reports This chapter explains how to set up kannel to deliver delivery reports. Delivery reports are a method to tell your system if the message has arrived on the destination phone. There are different things which can happen to a message on the way to the phone which are: • Message gets rejected by the SMSC (unknown subscriber, invalid destination number etc). • Message gets accepted by the SMSC but the phone rejects the message.
Chapter 10. Getting help and reporting bugs This chapter explains where to find help with problems related to the gateway, and the preferred procedure for reporting bugs and sending corrections to them. The Kannel development mailing list is devel@kannel.3glab.org. To subscribe, send mail to devel-subscribe@kannel.3glab.org (mailto:devel-subscribe@kannel.3glab.org). This is currently the best location for asking help and reporting bugs. Please include configuration file and version number.
Appendix A. Using the fake WAP sender This appendix explains how to use the fake WAP sender to test the gateway.
Appendix B. Using the fake SMS center Fakesmsc is a simple testing tool to test out Kannel and its SMS services. It cannot be used to send messages to mobile terminals, it is just a simulated SMS center with no connection to real terminals. Setting up fakesmsc This section sums up needed steps to set up system for fakesmsc use. Compiling fakesmsc The fake SMS center should compile at the same time as main Kannel compiles. The outcoming binary, fakesmsc, is in test directory.
Appendix B. Using the fake SMS center Options and messages are explained below, but as a quick example, a typical startup can go like this: test/fakesmsc -i 0.1 -m 100 "100 200 text nop" "100 300 text echo this" This tells fakesmsc to connect to bearerbox at localhost:10000 (default) and send a hundred messages with an interval of 0.1 seconds. Each message is from number 100, and is either to number 200 with message ’nop’ or to 300 with message ’echo this’.
Appendix B. Using the fake SMS center Switch -m Value Description max Send a maximum of max messages. Value -1 means that an unlimited number of messages is sent. Default -1. Using 0 can be useful to listen for messages sent via other channels. In addition, fakesmsc accepts all common Kannel Command line options like --verbosity.
Appendix C. Setting up a test environment for Push Proxy Gateway This appendix explains how to set a test environment for PPG. This contains a simulated SMSC, for instance a http server simulation (this is used as example, because it is simplest) and a simulated push initiator. Between them, there is the push proxy gateway to be tested. This means that you must configure HTTP SMSC.
Appendix C. Setting up a test environment for Push Proxy Gateway si-expires="2002-06-30T00:00:00Z"> Want to test a fetch? Note that the date value of the si-expires attribute contains trailing zeroes. They are OK here, because SI tokenizer removes them. But phones does not accept them in the final SMS data message. You should probably use action="signal-high" for testing purposes, for it causes an immediate presentation of the push message. Production usage is a quite another matter.
Appendix C. Setting up a test environment for Push Proxy Gateway second one pap control document. (For command line options, see Table C.1.). For example doing one push(you can simplify push url by setting a ppg configuration variable, see "Setting up push proxy gateway"; q flag here prevents dumping of test_ppg program debugging information): test/test_ppg -q http://ppg-host-name:ppg-port/ppg-url [content_file] [control_file] This presumes that you have set trusted-pi true.
Appendix C. Setting up a test environment for Push Proxy Gateway Using Nokia Toolkit as a part of a developing environment This chapter describes a developing environment using Nokia Toolkit instead of test_http_server program. You cannot use a real phone for testing a push server. Sending random messages to a phone does not work, because its only feedback (if it works properly) in error situations is dropping the offending message.
Appendix C. Setting up a test environment for Push Proxy Gateway group = test-ppg retries = 2 pi-ssl = yes ssl-client-certkey-file = /home/aarno/kannelcvs/gateway/gw/certkey.pem group = configuration push-url = https://localhost:8900/wappush pap-file = /home/aarno/test/ipnoqos.txt content-file = /home/aarno/test/si.txt username = foo password = bar With a configuration file, you can do a push by typing: test/test_ppg -q [configuration_file] Table C-2.
Appendix C. Setting up a test environment for Push Proxy Gateway Directive content-file username password Value Description filename Mandatory value. File containing pap request’s content document. string Mandatory value. PPG service user’s username. string Mandatory value. PPG service user’s password.
Appendix D. Setting up a dial-up line This appendix explains how to set up a dial-up line in Linux for use with the Kannel WAP gateway. In order for it to work you need a Linux kernel with PPP capabilities. Most distributions provides PPP kernel support by default. For more information how to compile PPP support into the kernel please read the "Linux Kernel HOWTO" at http://www.linuxdoc.org/. Analog modem This section explains how to set up a dial-up line with an analog modem.
Appendix D. Setting up a dial-up line In /etc/ppp/pap-secrets add the username and password for the ppp account. The IP address is the one assigned to the phone. wapuser * wappswd 192.168.0.20 Configure your phone (this example is for Nokia 7110) homepage http:/yourhost/hello.
Appendix E. Log files This appendix describes the log file format. Bearerbox Access Log 2001-01-01 12:00:00 Sent SMS [SMSC:smsc] [SVC:sms] [from:12345] [to:67890] [flags:0:1:0:0:0] [msg:11:Hello World] [udh:0] Variable Value Description Date 2001-01-01 12:00:00 Result Sent SMS Date Result: Send, failed, DLR (deliver report), Received, etc.
Appendix E.
Glossary M MO Mobile Originated - a SMS from mobile to application MT Mobile Terminated - a SMS from application to mobile MWI Message Waiting Indicator (See [BIBLIO-3GPP-23038]) MClass Message Class (See [BIBLIO-3GPP-23038]) Coding Message Coding (See [BIBLIO-3GPP-23038]) 108
Bibliography RFC 2616 - Hypertext Transfer Protocol -- HTTP/1.1, http://www.w3.org/Protocols/rfc2616/rfc2616.html, Request for Comments: 2616, The Internet Society, 1999. 3GPP 23.038, http://www.3gpp.org/ftp/Specs/latest/Rel-5/23_series/23038-500.zip, ..., 3GPP, ?. 3GPP 23.040, http://www.3gpp.org/ftp/Specs/latest/Rel-5/23_series/23040-530.zip, ..., 3GPP, ?.
