background image

Chapter 3. Using the gateway

Variable

Value

Description

unified-prefix

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). Format is that first
comes the unified prefix, then all
prefixes which are replaced by
the unified prefix, separated with
comma (’,’). For example, for
Finland an unified-prefix
"+358,00358,0;+,00" should do
the trick. If there are several
unified prefixes, separate their
rules with semicolon (’;’), like
"+35850,050;+35840,040".

Note

that prefix routing is next to

useless now that there are SMSC

ID entries. To remove prefixes,

use like

"-,+35850,050;-,+35840,040".

white-list

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 SMS Center is discarded. See
notes of phone number format
from numhash.h header file.
NOTE: the system has only a
precision of last 9 or 18 digits of
phone numbers, so beware!

black-list

URL

As white-list, but SMS messages

to these numbers are
automatically discarded

18

Summary of Contents for WAP and SMS gateway

Page 1: ...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 And...

Page 2: ...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...

Page 3: ...gues 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...

Page 4: ...files 13 Core configuration 13 Running Kannel 20 Starting the gateway 20 Command line options 20 Kannel statuses 21 HTTP administration 22 4 Setting up a WAP gateway 24 WAP gateway configuration 24 W...

Page 5: ...s 79 GET method for the OTA HTTP interface 79 6 Setting up a SMS WAP gateway 82 SMS WAP gateway configuration 82 Running SMS WAP gateway 82 7 Setting up Push Proxy Gateway 83 Configuring ppg core grou...

Page 6: ...Proxy Gateway 97 Creating push content and control document for testing 97 Starting necessary programs 98 Using Nokia Toolkit as a part of a developing environment 100 Testing PAP protocol over HTTPS...

Page 7: ...cape Codes 61 5 8 X Kannel Headers 63 5 9 X Kannel Post Headers 64 5 10 SendSMS User Group Variables 66 5 11 DLR Database Field Configuration Group Variables 69 5 12 MySQL Connection Group Variables 7...

Page 8: ...WAP service and have many interesting applications Usually servers know whether some data is new not the users Open Source http www opensource org is a way to formalize the principle of openness by p...

Page 9: ...oviding content to the phones Figure 1 1 Logical position of WAP gateway and PPG between a phone and a content server The WAP gateway talks to the phone using the WAP protocol stack and translates the...

Page 10: ...by the phone over IP bearer for instance CSD or GPRS Because Push Proxy Gateway tokenises SI and SL documents it may fit one SMS message if not it is segmented for transfer Using two bearers seems to...

Page 11: ...serving mobile originated MO SMS messages Kannel also works as an SMS push gateway content providers can request Kannel to send SMS messages to terminals Kannel then determines the correct SMS center...

Page 12: ...Book 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 We ha...

Page 13: ...Kannel consists of three parts 1 User s Guide i e the one you re reading at the moment 2 Architecture and Design in doc arch or at http www kannel 3glab org arch shtml http www kannel 3glab org arch...

Page 14: ...ditional options with defaults type Set defaults for the other options type is either speed or debug The default is debug enable docs default Build documentation b e converting the User Guide and the...

Page 15: ...ource directory gw bearerbox gw smsbox gw wapbox The version number of the gateway is added to the file names during installation This makes it easier to have several versions installed and makes it e...

Page 16: ...ckages you x 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 rc d init d kannel start To stop the gateway just run the same script...

Page 17: ...r share doc kannel VERSION or usr doc kannel VERSION depending on if you used the RedHat 7 x or 6 x package In the Kannel documentation directory there is a html file called control html It is an exam...

Page 18: ...restart parameter etc init d kannel restart If you don t want Kannel to run as a daemon run update rc d f kannel remove If you want to restore Kannel runing as a daemon you need to add a symbolic link...

Page 19: ...ample 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...

Page 20: ...x part is in the next chapter and smsbox smsc SMS center sms service and sendsms user groups are in the SMS Kannel chapter Configuration file syntax A configuration file consists of groups of configur...

Page 21: ...o have more control in larger setups Here is an example that illustrates the include statement group core admin port 13000 wapbox port 13002 admin password bar wdp interface name log file var log bear...

Page 22: ...Core Group Variables Variable Value Description group m core This is a mandatory variable admin port m port number The port number in which the bearerbox listens to HTTP administration commands It is...

Page 23: ...module will be SSL enabled Your smsboxes will have to connect using SSL to the bearerbox then This is used to secure communication between bearerbox and smsboxes in case they are in seperate networks...

Page 24: ...allow ip wdp interface name c IP or If this is set Kannel listens to WAP UDP packets incoming to ports 9200 9208 bound to given IP If no specific IP is needed use just an asterisk If UDP messages are...

Page 25: ...or example for Finland an unified prefix 358 00358 0 00 should do the trick If there are several unified prefixes separate their rules with semicolon like 35850 050 35840 040 Note that prefix routing...

Page 26: ...es that require this http proxy password URL list Password for authenticating proxy use for proxies that require this ssl client certkey file c filename A PEM encoded SSL certificate and private key f...

Page 27: ...of messages Set maximum size of incoming message queue After number of messages has hit this value Kannel began to discard them Value 0 means giving strict priority to outgoing messages 1 default mea...

Page 28: ...sets the logging level to INFO This way you won t see a large amount of debugging output the default is DEBUG Full explanation of Kannel command line arguments is below conffile is the name of the con...

Page 29: ...ere are four states for the program which currently directly only apply to bearerbox a Running The gateway accepts proceeds and relies messages normally This is the default state for the bearerbox b S...

Page 30: ...ious suspend commands never arrive nor can you restart it via WAP anymore Table 3 3 Kannel HTTP Administration Commands status or status txt Get the current status of the gateway in a text version Tel...

Page 31: ...me 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 start...

Page 32: ...wapkannel conf is supplied You may want to take a look at that when setting up a WAP Kannel Wapbox configuration If you have set wapbox port variable in the core configuration group you MUST supply a...

Page 33: ...on and an incoming URL of http source some path the result will be http destination some path map url max number If you need more than one mapping set this to the highest number mapping you need The d...

Page 34: ...ss WTP SAR connections even while Kannel does not support this feature now Some real phones seem to break connection if fallback to non SAR communication is being tried by the gateway smart errorsr bo...

Page 35: ...s possibly one or more sendsms user groups For the core group you must set the following variable smsbox port In addition you may be interested to set unified prefix white list and or black list varia...

Page 36: ...ction has an assigned SMSC ID it does NOT automatically mean that messages with identical SMSC ID are routed to it instead configuration variables denied smsc id allowed smsc id and preferred smsc id...

Page 37: ...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 denied prefix prefix list A list of phone number prefixes which are N...

Page 38: ...ere are SMSC ID entries To remove prefixes use like 35850 050 35840 040 alt charset number As some SMS Centers do not follow the standards in character coding an alt charset character conversion is pr...

Page 39: ...prefix 12345 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 Port number in the smsc host machine smsc us...

Page 40: ...er prefix to the empty string CMG UCP EMI 4 0 Kannel supports two types of connections with CMG SMS centers direct TCP IP connections emi_ip or emi2 and ISDN modem X 25 over D channel ISDN is called X...

Page 41: ...ssword string Password in the SMSC machine needed to contact SMSC device c device name The device the modem is connected to like dev ttyS0 ISDN connection only phone c string Phone number to dial to w...

Page 42: ...e and those this option has no effect If keepalive is larger than idle timeout than keepalive reopens the connection This allows one to poll for pending mobile originated Short Messages at the SMSC ke...

Page 43: ...r commands shall be sent before the a response is received Any command that is sent before the reception of the response will be discarded The second type of flow control is windowing when this parame...

Page 44: ...mplemented alternative charsets are defined in alt_charsets h and new ones can be added SMPP 3 4 This implements Short Message Peer to Peer SMPP Protocol 3 4 in a manner that should also be compatible...

Page 45: ...Use value 0 to disable this I O thread smsc username m string The username of the Messaging Entity connecting to the SM SC If the SM SC operator reports that the TELEPATH SYSTEM MANAGER TERMINAL view...

Page 46: ...s for connections from a multi homed machine If this is not defined the default device of the machine will be used my number number Optional smsc short number Should be set if smsc sends a different o...

Page 47: ...Defaults to 0 source addr npi number Optional source address NPI setting for the link Defaults to 1 source addr autodetect boolean Optional if defined tries to scan the source address and set TON and...

Page 48: ...x00 deliver_sm decimal submit_sm_resp decimal 0x01 deliver_sm decimal submit_sm_resp hex 0x02 deliver_sm hex submit_sm_resp decimal 0x03 deliver_sm hex submit_sm_resp hex In accordance to the SMPP v3...

Page 49: ...lementing Sema SMS2000 using X 28 connection wait_report 0 false 1 true Report indicator used by the Sema SMS2000 protocol Optional group smsc smsc ois host 103 102 101 100 port 10000 receive port 100...

Page 50: ...ct to an SMSC having failed to connect initating or during an session The default is 10 seconds source addr ton number Optional source address TON setting for the link Defaults to 1 source addr npi nu...

Page 51: ...idityperiod integer 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...

Page 52: ...ve slightly different behaviour We need to know what type of modem is used Use auto or omit parameter to have kannel detect the modem type automatically some types should not be autodetected like the...

Page 53: ...t my number number Optional phone number sms center number SMS Center to send messages sim buffering boolean Whether to enable the so called SIM buffering behaviour of the GSM module if assigned a tru...

Page 54: ...IEMENS MODEM M20 detect string could be SIEMENS and detect strign2 M20 init string string Optional initialization string Defaults to AT CNMI 1 2 0 1 0 speed number Serial port hint speed to use Option...

Page 55: ...the modem s default message storage will be used usually SM enable mms boolean Optional defaults to false If enabled kannel would send an AT CMMS 2 if it have more than one message on queue and hopefu...

Page 56: ...teways and various other relay services when direct SMSC is not available group smsc smsc http system type kannel smsc username nork smsc password z0rK port 13015 send url http localhost 20022 Variabl...

Page 57: ...MS centers and the other is much faster and cheaper to use To set up routing systems first give an unique ID for each SMS center or if you want to treat multiple ones completely identical give them id...

Page 58: ...mpress fields Table 5 3 SMSC driver internal features Feature cimd cimd2 emi emi_ip emi2 smpp sema ois at2 at http fake Can keep idle connections alive n y n n y y y Can send octet data without UDH n...

Page 59: ...ta b However it looks like the sema driver can t receive text data c Miscalculates message length Symbol Meaning not yet investigated y driver has this feature and it has been tested y driver probably...

Page 60: ...pecific routing inside bearerbox So if you you own boxes that do pass messages into bearerbox for delivery you may want that answers to those are routed back to your specific smsbox instance i e SMPP...

Page 61: ...rs you cannot set the sender number but it is automatically set as the number of SMSC log file filename As with the bearerbox core group Access log is used to store information about MO and send sms r...

Page 62: ...ll try to convert UCS2 messages received to ISO 8859 1 If it s possible the message will have coding equal to 7 bits and charset equal to iso 8859 1 http request retry integer If set specifies how man...

Page 63: ...ation to your EMSEs and if an client send a submit_sm PDU smppbox would transform the message into Kannel message representation and inject the message to bearerbox as if it would be an smsbox As you...

Page 64: ...ge and by the number of arguments accepted by the service configuration unless catch all configuration variable is used By adding a username and password in the URL in the following manner http luser...

Page 65: ...on name string Optional name to identify the service in logs If unset keyword is used get url c URL Requested URL The url can include a list of parameters which are parsed before the url is fetched Se...

Page 66: ...nisms for security reasons accepted smsc id list Accept ONLY SMS messages arriving from SMSC with matching ID a Separate multiple entries with For example if accepted smsc is RL SON accept messages wh...

Page 67: ...mber of the handset is set otherwise not strip keyword bool Used only with POST Remove matched keyword from message text before sending it onward faked sender phone number This number is set as sender...

Page 68: ...ssage is split from last or which is included in the previous part split suffix string If the message is split into several ones this string is appended to each message except the last one omit empty...

Page 69: ...way there could be several services with the same keyword and different results Table 5 7 Parameters Escape Codes k the keyword in the SMS request i e the first word in the SMS message s next word fr...

Page 70: ...nary coding 2 or UTF16 BE coding 3 If the message was sucessfully recoded from unicode it will be ISO 8859 1 u udh of incoming message Some sample sms service groups group sms service keyword nop text...

Page 71: ...X Kannel Header username X Kannel Username password X Kannel Password from X Kannel From to X Kannel To text request body charset charset as in Content Type text html charset ISO 8859 1 udh X Kannel U...

Page 72: ...g X Kannel Coding 1 7 Bits 2 8 Bits compress X Kannel Compress validity X Kannel Validity deferred X Kannel Deferred n service name X Kannel Service a or r text request body kannel send all wo unless...

Page 73: ...same format as X Kannel UDH Example udh 06050415820000 udh On kannel application from is the smsc id that message arrives and to is the service name On application kannel from contains the credentials...

Page 74: ...in sms service groups user deny ip IP list As other deny allow IP lists but for this user i e this user is not allowed to do the SMS push HTTP request from other IPs than allowed ones If not set ther...

Page 75: ...accepted destinations of SMS messages If a destination of an SMS message is not in this list any message received from the HTTP interface is rejected See notes of phone number format from numhash h h...

Page 76: ...e To store DLR information into a MySQL database you may use the dlr storage mysql configuration directive in the core group In addition to that you must have a dlr db group defined that specifies the...

Page 77: ...build in your LibSDB installation when trying to use a specific DB type within the URL DLR database field configuration For external database storage of DLR information in relational database managem...

Page 78: ...he status of the DLR for a specific message field boxc id m string The table field that is used to store the smsbox connection id that has passed the message for delivery This is required in cases you...

Page 79: ...m hostname or IP Hostname or IP of a server running a MySQL database to connect to mysql username m username User name for connecting to MySQL database mysql password m password Password for connectin...

Page 80: ...our WAP services i e http wap company com service string Description of the service ipaddress IP IP address of your WAP gateway phonenumber phone number Phone number used to establish the PPP connecti...

Page 81: ...Any string is acceptable but semicolon may cause problems so avoid it and any other special non alphabet characters url URL The address of the HTTP server for your WAP services i e http wap company co...

Page 82: ...ax messages 0 Setting up operator specific services Those running Kannel with several SMS centers might need to define services according to the relying SMS center To achieve this first you need to gi...

Page 83: ...te that if your SMS centers do not set the sender phone number but rely on number transmitted you should set faked sender to all sendsms user groups Running SMS gateway Using the HTTP interface to sen...

Page 84: ...is used to phone number list Phone number of the receiver To send to multiple receivers separate each entry with space url encoded but note that this can be deactivated via sendsms chars in the smsbo...

Page 85: ...ass in DCS Field Accepts values between 1 and 4 for Message Class 0 to 3 A value of 1 sends the message directly to display mclass 2 sends to mobile 3 do SIM and 4 to SIM Toolkit mwi number Optional S...

Page 86: ...t mask Optional Request for delivery reports with the state of the sent message The value is a bit mask composed of 1 Delivered to phone 2 Non Delivered to Phone 4 Queued on SMSC 8 Delivered to SMSC 1...

Page 87: ...ges can be sent to mobile phones or devices to auto configure the settings for WAP They are actually complex SMS messages with UDH and sent as concatenated messages if too long and compiled if necessa...

Page 88: ...ME PPP_AUTHNAME VALUE yourusername PARM NAME PPP_AUTHSECRET VALUE yourauthsecret PARM NAME CSD_CALLTYPE VALUE ISDN PARM NAME CSD_CALLSPEED VALUE 9600 CHARACTERISTIC CHARACTERISTIC TYPE URL VALUE http...

Page 89: ...at is to receive the OTA configuration message from 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...

Page 90: ...eway 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 s...

Page 91: ...make configuring simpler IPs here are always denied even when they are mentioned in the allowed IPs list Ppg url is a simple stamp used for routing requests to the right service You can change this s...

Page 92: ...G Obviously both of them must reside inside same firewall Default true If this variable is true all security variables are ignored even though they may be present ppg deny ip ip list PPG will not acce...

Page 93: ...ppg username string Username for this user ppg password string Password for this user allowed prefix number list Phone number prefixes allowed in pushes coming from this pi These prefixes must confor...

Page 94: ...s core wapbox smsc and smsbox These are configured normal way only smsc group may have push specific variables Note that following configurations are only an example you may need more complex ones Bea...

Page 95: ...in the front of an existing sendsms service capable to send SMS data messages and to to understand HTTP requests generated by HTTP SMSC See next chapter Then you need only configure SMSC configuration...

Page 96: ...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...

Page 97: ...on files within the core group to be used for the HTTP sides You can use one or both sides of the SSL support There is no mandatory to use both if only one is desired Using SSL client support To use t...

Page 98: ...ane 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 ppg...

Page 99: ...mply add the values togeter For example if you want to get delivery success and or failure you set the dlrmask value to 1 2 and so on If you specify dlrmask on the URL you pass on to kannel you also n...

Page 100: ...dure 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...

Page 101: ...Appendix A Using the fake WAP sender This appendix explains how to use the fake WAP sender to test the gateway 94...

Page 102: ...onfiguration group accepts all common smsc configuration group variables like smsc id preferred smsc id or denied smsc id which can be used to test out routing systems and diverted services before set...

Page 103: ...as one argument it must be put in quotation marks Message type must be one of the following text data and udh Here s an example of using each test fakesmsc i 0 01 v 1 m 1000 100 300 text echo this mes...

Page 104: ...m 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 acc...

Page 105: ...8408676001 TYPE PLMN ppg carrier com quality of service priority low delivery method unconfirmed network required true network GSM bearer required true bearer SMS push message pap Because the push con...

Page 106: ...tains in addition of wapbox and bearerbox two test programs test_ppg simulating push initiator and test_http_server simulating a SMSC center accepting pushed content sended over SMS You can find both...

Page 107: ...me ppg username password ppg password content_file control_file Table C 1 Test_ppg s command line options Switch Value Description c string Use content qualifier string instead of default si service i...

Page 108: ...ram Use IP address of our virtual machine easiest way to get this is to ping your virtual machine name in the dos prompt window Your bearer is in this case IP An example pap document follows xml versi...

Page 109: ...he client tries to log in to PPG number times before discarding the push request Default is 2 pi ssl boolean Mandatory parameter for HTTPS connection Does the client use HTTPS connection Default is no...

Page 110: ...Proxy Gateway Directive Value Description content file filename Mandatory value File containing pap request s content document username string Mandatory value PPG service user s username password stri...

Page 111: ...information In this example we assume your modem is connected to the serial port ttyS0 COM 1 S0 2345 respawn sbin mgetty ttyS0 x 6 D dev ttyS0 We need to start the pppd automatically when mgetty rece...

Page 112: ...168 0 20 Configure your phone this example is for Nokia 7110 homepage http yourhost hello wml connection type continuous connection security off bearer data dial up number your phone number ip addres...

Page 113: ...ump Log rotation If Kannel is configured so that the bearerbox wapbox and or smsbox log to file each of these log files will continue to grow unless administered in some way this is especially true if...

Page 114: ...pendix E Log files daily missingok rotate 365 compress delaycompress notifempty create 640 kannel adm sharedscripts postrotate killall HUP bearerbox smsbox wapbox true dev null 2 dev null endscript 10...

Page 115: ...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 Co...

Page 116: ...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 3g...

Reviews: