1<?xml version="1.0" encoding="UTF-8"?> 2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 3 "http://docbook.org/xml/4.2/docbookx.dtd" [ 4<!ENTITY figtype "#FIGTYPE#"> 5<!ENTITY timestamp "#DATE#"> 6<!ENTITY version "#VERSION#"> 7<!ENTITY % draft "#DRAFTS#"> 8]> 9 10<!-- Embbeb your block with these to set it to "draft" 11<![%draft;[ <your block> ]]> 12--> 13 14<book> 15 16<bookinfo> 17 <title>Kannel &version; User's Guide</title> 18 <subtitle>Open Source WAP and SMS gateway</subtitle> 19 20<authorgroup> 21 <author> 22 <firstname>Andreas</firstname> 23 <surname>Fink</surname> 24 <affiliation> 25 <jobtitle>Chairman & CTO</jobtitle> 26 <orgname>Global Networks Inc.</orgname> 27 <address> <email>andreas@fink.org</email> 28 <otheraddr>http://www.smsrelay.com/</otheraddr> 29 <otheraddr>http://www.gni.ch/</otheraddr> 30 </address> 31 </affiliation> 32 </author> 33 <author> 34 <firstname>Bruno</firstname> 35 <surname>Rodrigues</surname> 36 <affiliation> 37 <address> 38 <email>bruno.rodrigues@litux.org</email> 39 <otheraddr>http://litux.org/bruno</otheraddr> 40 </address> 41 </affiliation> 42 </author> 43 <author> 44 <firstname>Stipe</firstname> 45 <surname>Tolj</surname> 46 <affiliation> 47 <jobtitle>System Architect</jobtitle> 48 <orgname>Tolj System Architecture</orgname> 49 <address> 50 <email>stolj@kannel.org</email> 51 <otheraddr>http://www.tolj.org/</otheraddr> 52 </address> 53 </affiliation> 54 </author> 55 <author> 56 <firstname>Aarno</firstname> 57 <surname>Syvänen</surname> 58 <affiliation> 59 <jobtitle>Chief MMS Developer</jobtitle> 60 <orgname>Global Networks Inc.</orgname> 61 <address> 62 <email>as@gni.ch</email> 63 <otheraddr>http://www.gni.ch/</otheraddr> 64 </address> 65 </affiliation> 66 </author> 67 <author> 68 <firstname>Alexander</firstname> 69 <surname>Malysh</surname> 70 <affiliation> 71 <jobtitle>Senior Software Engineer</jobtitle> 72 <orgname>GTX Ltd.</orgname> 73 <address> 74 <email>amalysh at kannel.org</email> 75 <otheraddr>http://www.gtx-messaging.com/</otheraddr> 76 </address> 77 </affiliation> 78 </author> 79 <author> 80 <firstname>Alejandro</firstname> 81 <surname>Guerrieri</surname> 82 <affiliation> 83 <jobtitle>Senior System Architect</jobtitle> 84 <orgname>3Cinteractive, L.L.C.</orgname> 85 <address> 86 <email>aguerrieri@kannel.org</email> 87 <otheraddr>http://www.3cinteractive.com/</otheraddr> 88 </address> 89 </affiliation> 90 </author> 91 <author> 92 <firstname>Lars</firstname> 93 <surname>Wirzenius</surname> 94 <affiliation> 95 <jobtitle>Gateway architect</jobtitle> 96 <orgname>former Wapit Ltd</orgname> 97 <!--<address> <email>liw@wapit.com</email> 98 <otheraddr>http://www.wapit.com</otheraddr> 99 </address>--> 100 </affiliation> 101 </author> 102 <author> 103 <firstname>Kalle</firstname> 104 <surname>Marjola</surname> 105 <affiliation> 106 <jobtitle>Senior Software Engineer</jobtitle> 107 <orgname>Enpocket</orgname> 108 <address> 109 <email>marjola@enpocket.com</email> 110 <otheraddr>http://www.enpocket.com</otheraddr> 111 </address> 112 </affiliation> 113 </author> 114 115</authorgroup> 116 117 <abstract> 118 <title>Abstract</title> 119 <para> 120 This document describes how 121 to install and use Kannel, the Open Source WAP and SMS Gateway 122 originally developed by Wapit Ltd (now out of business) and now 123 being developed further by the open source community, namely the 124 Kannel Group. 125 </para> 126 </abstract> 127 128 <revhistory> 129 <revision> 130 <revnumber>&version;</revnumber> 131 <date>×tamp;</date> 132 </revision> 133 </revhistory> 134 135</bookinfo> 136 137 138<chapter> 139<title>Introduction</title> 140 141 <highlights> 142 <para>This chapter introduces WAP and SMS in general terms, and explains the 143 role of the gateway in WAP and SMS, outlining their duties and features. It 144 also explains why the Kannel project was started in the first place, 145 and why it is open source.</para> 146 </highlights> 147 148 <para>With hundreds of millions of mobile phones in use all over the 149 world, the market for services targeted at mobile users 150 is mind-bogglingly immense. Even simple services find plenty of users, 151 as long as they're useful or fun. Being able to get news, send e-mail 152 or just be entertained wherever you are is extremely attractive to 153 many.</para> 154 155 <para>The hottest technology for implementing mobile services is WAP, 156 short for Wireless Application Protocol. It lets the phone act 157 as a simple web browser, but optimizes the markup language, 158 scripting language, and the transmission protocols for wireless 159 use. The optimized protocols are translated to plain old HTTP by 160 a <emphasis>WAP gateway</emphasis>.</para> 161 162 <para>Kannel is an open source WAP gateway. It attempts to 163 provide this essential part of the WAP infrastructure freely 164 to everyone so that the market potential for WAP services, 165 both from wireless operators and specialized service providers, 166 will be realized as efficiently as possible.</para> 167 168 <para>Kannel also works as an SMS gateway for GSM networks. Almost 169 all GSM phones can send and receive SMS messages, so this is 170 a way to serve many more clients than just those using a new 171 WAP phone.</para> 172 173 <para>In addition, Kannel operates as <emphasis>Push Proxy Gateway 174 </emphasis>, or <emphasis>PPG</emphasis>, making possible for content 175 servers to send data to the phones. This is a new type of WAP service, 176 and have many interesting applications. Usually servers know whether 177 some data is new, not the users. </para> 178 179 <para>Kannel's quality has been recognized on March 7, 2001 when it 180 was <ulink url="http://www.kannel.org/oldnews.shtml#wapcert">certified</ulink> 181 by <ulink url="http://www.wapforum.org">WAP Forum</ulink> 182 as the first WAP 1.1 gateway in the world.</para> 183 184 <para>Greater quality recognition are the quantity of companies 185 using Kannel to successful connect to a variety of SMSC protocols 186 in lots of countries.</para> 187 188 <para><ulink url="http://www.opensource.org">Open Source</ulink> 189 is a way to formalize the principle of openness by placing the 190 source code of a product under a Open Source compliant software 191 license. The BSD license was chosen over other Open Source 192 licenses by the merit of placing the least amount of limitations 193 on what a third party is able to do with the source code. In 194 practice this means that Kannel is going to be a fully-featured 195 WAP implementation and compatible with the maximum number of 196 bearers with special emphasis on SMSC compatibility. 197 The Kannel project was founded by Wapit Ltd in June, 1999.</para> 198 199 200<sect1> 201<title>Overview of WAP</title> 202 203 <para>WAP, short for Wireless Application Protocol, is a 204 collection of various languages and tools and an infrastructure for 205 implementing services for mobile phones. Traditionally such 206 services have worked via normal phone calls or short textual 207 messages (e.g., SMS messages in GSM networks). Neither are very 208 efficient to use, nor very user friendly. WAP makes it possible 209 to implement services similar to the World Wide Web.</para> 210 211 <para>Unlike marketers claim, WAP does not bring the existing 212 content of the Internet directly to the phone. There are too many 213 technical and other problems for this to ever work properly. The 214 main problem is that Internet content is mainly in the form of 215 HTML pages, and they are written in such way that they require 216 fast connections, fast processors, large memories, big screens, 217 audio output and often also fairly efficient input mechanisms. 218 That's OK, since they hopefully work better for traditional 219 computers and networks that way. However, portable phones have 220 very slow processors, very little memory, abysmal and intermittent 221 bandwidth, and extremely awkward input mechanisms. Most existing 222 HTML pages do not work on mobiles phones, and never will.</para> 223 224 <para>WAP defines a completely new markup language, the Wireless 225 Markup Language (WML), which is simpler and much more strictly 226 defined than HTML. It also defines a scripting language, 227 WMLScript, which all browsers are required to support. To make 228 things even simpler for the phones, it even defines its own 229 bitmap format (Wireless Bitmap, or WBMP).</para> 230 231 <para>HTTP is also too inefficient for wireless use. However, by using 232 a semantically similar binary and compressed format it 233 is possible to reduce the protocol overhead to a few bytes per 234 request, instead of the usual hundreds of bytes. Thus, WAP defines a 235 new protocol stack to be used. However, to make things simpler 236 also for the people actually implementing the services, WAP 237 introduces a gateway between the phones and the servers providing 238 content to the phones.</para> 239 240 <figure> 241 <title>Logical position of WAP gateway (and PPG) between a phone and a 242 content server.</title> 243 <graphic fileref="wap-gateway&figtype;"></graphic> 244 </figure> 245 246 <para>The WAP gateway talks to the phone using the WAP protocol 247 stack, and translates the requests it receives to normal 248 HTTP. Thus content providers can use any HTTP servers and 249 utilize existing know-how about HTTP service implementation 250 and administration.</para> 251 252 <para>In addition to protocol translations, the gateway 253 also compresses the WML pages into a more compact form, to 254 save on-the-air bandwidth and to further reduce the phone's 255 processing requirements. It also compiles WMLScript programs 256 into a byte-code format. Latest WAP specifications defines some 257 additional conversions that Kannel is starting to implement, like 258 multipart/form-data, multipart/mixed or MMS content conversion.</para> 259 260 <para>Kannel is not just a WAP gateway. It also works as an 261 SMS gateway. Although WAP is the hot and technically superior 262 technology, SMS phones exist in huge numbers and SMS services are 263 thus quite useful. Therefore, Kannel functions simultaneously 264 as both a WAP and an SMS gateway.</para> 265 266</sect1> 267 268<sect1> 269<title>Overview of WAP Push</title> 270 <para>Previous chapter explained pull mode of operation: the phone 271 initiates the transaction. There is, however, situations when the 272 server (called in this context a push initiator) should be the 273 initiator, for instance, when it must send a mail notification or a 274 stock quote. For this purpose WAP Forum defined WAP Push.</para> 275 276 <para>Push is an application level service, sitting on the top of 277 existing WAP stack. It defines two protocols, OTA and PAP. OTA is 278 a ligthweigth protocol speaking with WAP stack (to be more specific, 279 with WSP), PAP speaks with the push initiator. It defines three kind 280 of XML documents, one for the push data itself and another for 281 protocol purposes (these are called pap document or push control 282 documents). </para> 283 284 <para>The server does not simply send push content to the phone, the 285 user would surely not accept, for instance, interrupting of a voice 286 call. Instead it sends a specific XML document, either Service 287 Indication or Service Loading. These inform the user about the content 288 become available, and it is displayed only when it is not interrupting 289 anything. It contains an URL specifying the service and a text for user 290 describing the content. Then the user can decide does he accept push or not. 291 </para> 292 293 <para>The push content is send ed to the phones over SMS, but the 294 content is fetched by the phone over IP bearer, for instance CSD 295 or GPRS. Because Push Proxy Gateway tokenises SI and SL documents, it 296 may fit one SMS message (if not, it is segmented for transfer). </para> 297 298 <para>Using two bearers seems to be an unnecessary complication. But 299 quite simply, phones currently operate this way. Push over GPRS can 300 only simplify matters.</para> 301</sect1> 302 303<sect1> 304<title>Overview of SMS</title> 305 306 <para>SMS, short messaging service, is a way to send short (160 307 character) messages from one GSM phone to another. It can also 308 be used to send regular text as well as advanced content like 309 operator logos, ringing tones, business cards 310 and phone configurations.</para> 311 312 <para><emphasis>SMS services</emphasis> are content services 313 initiated by SMS message to certain (usually short) phone 314 number, which then answers with requested content, if available.</para> 315 316 <para>When SMS services are used, the client (mobile terminal) 317 sends an SMS 318 message to certain number, usually a very short specialized 319 number, which points to specific SMS center responsible 320 for that number (plus possibly many others). This SMS center 321 then sends the message onward to specified receiver in intra- or 322 Internet, using an SMS center specific protocol. For example, a 323 Nokia SMS center uses CIMD protocol.</para> 324 325 <para>As practically every different kind of SMS center uses different 326 protocol, an <emphasis>SMS gateway</emphasis> is used to handle 327 connections with SMS centers and to relay them onward in an 328 unified form. Kannel's biggest feature is to abstract each SMSC protocol 329 to a well-known HTTP protocol, simplifying services deployment.</para> 330 331 <figure> 332 <title>Logical position of SMS gateway between a phone and a content server.</title> 333 <graphic fileref="sms-gateway&figtype;"></graphic> 334 </figure> 335 336 <para>An SMS gateway can also be used to relay SMS messages from 337 one GSM network to another, if the networks do not roam messages 338 normally.</para> 339 340 <para>Kannel works as an SMS gateway, talking with many 341 different kind of SMS centers, and relaying the messages onward 342 to content providers, as HTTP queries. Content providers then 343 answer to this HTTP query and the answer is sent back to mobile 344 terminal, with appropriate SMS center connection using SMS center 345 specific protocol.</para> 346 347 <para>In addition to serving mobile originated (MO) SMS messages 348 Kannel also works as an SMS push gateway - content providers can 349 request Kannel to send SMS messages to terminals. Kannel then 350 determines the correct SMS center to relay the SMS message and 351 sends the SMS message to that SMS center, again using SMS center 352 specific protocol. This way the content provider does not need 353 to know any SMS center specific protocol, just unified Kannel 354 SMS sending interface.</para> 355 356</sect1> 357 358 359<sect1> 360<title>Features</title> 361 362 <sect2> 363 <title>WAP</title> 364 <para> 365 <itemizedlist> 366 <listitem><para>Fully compliant with WAP 1.1 specification</para></listitem> 367 <listitem><para>Already implements some WAP 1.2 and even WAP 2.0 features.</para></listitem> 368 </itemizedlist> 369 </para> 370 </sect2> 371 <sect2> 372 <title>WAP Push</title> 373 <para> 374 <itemizedlist> 375 <listitem><para>Supports WAP Push SI and SL</para></listitem> 376 <listitem><para>...</para></listitem> 377 </itemizedlist> 378 </para> 379 </sect2> 380 <sect2> 381 <title>SMS</title> 382 <para> 383 <itemizedlist> 384 <listitem><para>Supports a variety of SMSC protocols, namely:</para> 385 <itemizedlist> 386 <listitem><para>CMG's UCP/EMI 4.0 and 3.5</para></listitem> 387 <listitem><para>...</para></listitem> 388 </itemizedlist> 389 </listitem> 390 <listitem><para>Full support for MO and MT messages</para></listitem> 391 </itemizedlist> 392 </para> 393 </sect2> 394</sect1> 395 396<sect1> 397<title>Requirements</title> 398 399 <para>Kannel is being developed on Linux systems, 400 and should be fairly easy to export to other Unix-like 401 systems. However, we don't yet support other platforms, due to lack 402 of time, although it should be working without major problems on 403 Windows (through Cygwin), Solaris and FreeBSD. 404 </para> 405 406 <para>Kannel requires the following software environment: 407 408 <itemizedlist> 409 410 <listitem><para>C compiler and libraries for ANSI C, with normal 411 Unix extensions such as BSD sockets and related tools. 412 (GNU's GCC tool-chain is recommended)</para></listitem> 413 414 <listitem><para>The Gnome XML library (known as 415 gnome-xml and libxml), version 2.2.5 or newer. See <ulink 416 url="http://xmlsoft.org/xml.html">http://xmlsoft.org/xml.html</ulink>. 417 </para> 418 <para>If you are installing it from your distribution's packages, you'll need 419 <literal>libxml2-dev</literal> in addition to run-time <literal>libxml2</literal> package 420 libraries.</para></listitem> 421 422 <listitem><para>GNU Make.</para></listitem> 423 424 <listitem><para>An implementation of POSIX threads 425 (<filename>pthread.h</filename>).</para></listitem> 426 427 <listitem><para>GNU Bison 1.28, if you want to modify the WMLScript 428 compiler (a pre-generated parser is included for those who just 429 want to compile Kannel).</para></listitem> 430 431 <listitem><para>DocBook processing tools: DocBook style-sheets, 432 jade, jadetex, etc; see <filename>README</filename>, section 433 `Documentation', for more information (pre-formatted versions 434 of the documentation are available, and you can compile Kannel 435 itself even without the documentation tools).</para></listitem> 436 437 <listitem><para>GNU autoconf, if you want to modify the 438 configuration script.</para></listitem> 439 440 </itemizedlist> 441 </para> 442 443 <para>Hardware requirements are fluffier. Some informal benchmarking 444 have shown that with a reasonably fast PC architecture (e.g. 400MHz 445 Pentium II with 128MB RAM), SMS performance's bottleneck is always on the 446 SMSC side, even for example with multiple connections summing a pipeline with 447 400 msg/sec. We haven't benchmarked Kannel yet on WAP side, so there are 448 no hard numbers.</para> 449 450</sect1> 451 452</chapter> 453 454<chapter> 455<title>Installing the gateway</title> 456 457 <para>This chapter explains how the gateway can be installed, 458 either from a source code package or by using a pre-compiled 459 binary version. The goal of this chapter is to get the gateway 460 compiled and all the files in the correct places; the next 461 chapter will explain how the gateway is configured.</para> 462 463 <note><para>If you are upgrading from a previous version, please look at 464 <xref linkend="upgrading-notes"/> for any important information.</para></note> 465 466<sect1> 467<title>Getting the source code</title> 468 469 <para>The source code to 470 Kannel is available for download at <ulink 471 url="http://www.kannel.org/download.shtml">http://www.kannel.org/download.shtml</ulink>. 472 It is available in various formats and you can choose to download 473 either the latest release version or the daily snapshot of the 474 development source tree for the next release version, depending 475 on whether you want to use Kannel for production use or to 476 participate in the development.</para> 477 478 <para>If you're serious about development, you probably want to 479 use CVS, the version control system used by the Kannel project. 480 This allows you to participate in Kannel development much 481 more easily than by downloading the current daily snapshot and 482 integrating any changes you've made every day. CVS does that 483 for you. (See the Kannel web site for more information on how 484 to use CVS.)</para> 485 486</sect1> 487 488 489<sect1> 490<title>Finding the documentation</title> 491 492 <para>The documentation for Kannel consists of three parts: 493 494 <orderedlist> 495 <listitem><para><citetitle>User's Guide</citetitle>, i.e., the one 496 you're reading at the moment.</para></listitem> 497 <listitem><para><citetitle>Architecture and 498 Design</citetitle>, in <filename>doc/arch</filename> or 499 at <ulink url="http://www.kannel.org/arch.shtml"> 500 http://www.kannel.org/arch.shtml</ulink></para></listitem> 501 <listitem><para>The <filename>README</filename> and various other 502 text files in the source tree.</para></listitem> 503 504 </orderedlist> 505 </para> 506 507 <para>You can also find general information on Kannel's 508 <ulink url="http://www.kannel.org">website</ulink> and 509 information about existing problems at 510 <ulink url="http://bugs.kannel.org">our bug tracker</ulink>. 511 </para> 512 513 <para> 514 We intend to cover everything you need to install and use Kannel 515 is in <citetitle>User's Guide</citetitle>, but the guide is still 516 incomplete in this respect. Similarly, the <citetitle>Architecture and 517 Design</citetitle> document should tell you everything you need 518 to know to dive into the sources and quickly make your own modifications. 519 It's not a replacement for actually 520 reading the source code, but it should work as a map to the 521 source code. The <filename>README</filename> is not supposed 522 to be very important, nor contain much information. Instead, 523 it will just point at the other documentation. 524 </para> 525 526</sect1> 527 528<sect1> 529<title>Compiling the gateway</title> 530 531 <para>If you are using Kannel on a supported platform, or one 532 that is similar enough to one, compiling Kannel should be trivial. 533 After you have unpacked the source package of your choose, 534 or after you have checked out the source code from CVS, enter 535 the following commands: 536 537 <screen><userinput> 538 ./configure 539 make 540 </userinput></screen> 541 542 The <filename>configure</filename> script investigates various 543 things on your computer for the Kannel compilation needs, and 544 writes out the <filename>Makefile</filename> used to compile 545 Kannel. <command>make</command> then runs the commands to actually 546 compile Kannel.</para> 547 548 <para>If either command writes out an error message and stops 549 before it finishes its job, you have a problem, and you either 550 need to fix it yourself, if you can, or report the 551 problem to the Kannel project. See <xref linkend="bug-reporting"/> 552 for details.</para> 553 554 <para>For detailed instruction on using the configuration 555 script, see file <filename>INSTALL</filename>. That file is 556 a generic documentation for <command>configure</command>. Kannel 557 defines a few additional options: 558 559 <itemizedlist> 560 561 <listitem><para><literal>--with-defaults=</literal><replaceable>type</replaceable> 562 563 Set defaults for the other options. 564 <replaceable>type</replaceable> is either <literal>speed</literal> 565 or <literal>debug</literal>. The default is 566 <literal>speed</literal>. <literal>speed</literal> options is equivalent to 567 <literal>--with-malloc=native --disable-assertions</literal>, while 568 <literal>debug</literal> is <literal>--with-malloc=checking --enable-assertions</literal>. 569 570 </para></listitem> 571 572 <listitem><para><literal>--disable-docs (default is --enable-docs)</literal> 573 574 Use this option if you don't have DocBook installed and/or 575 you want to save some time and CPU cycles. 576 Pre-generated documentation is available on Kannel's site. 577 Default behavior is to build documentation, b.e., converting the User Guide and 578 the Architecture Guide from the DocBook markup language to 579 PostScript and HTML if DocBook is available. 580 </para></listitem> 581 582 <listitem><para><literal>--enable-drafts (default is --disable-drafts)</literal> 583 584 When building documentation, include the sections marked as 585 <literal>draft</literal>.</para></listitem> 586 587 <listitem><para><literal>--enable-debug (default is --disable-debug)</literal> 588 589 Enable non-reentrant development time 590 debugging of WMLScript compiler.</para></listitem> 591 592 <listitem><para><literal>--disable-localtime (default is --enable-localtime)</literal> 593 594 Write log file time stamps in GMT, not in local time. 595 </para></listitem> 596 597 <listitem><para><literal>--enable-assertions / --disable-assertions</literal> 598 599 Turn on or off runtime assertion checking. <literal>enable</literal> makes 600 Kannel faster, but gives less information if it crashes. 601 Default value is dependent on <literal>--with-defaults</literal>. 602 </para></listitem> 603 604 <listitem><para><literal>--with-malloc=</literal><replaceable>type</replaceable> 605 606 Select memory allocation module to use: 607 <replaceable>type</replaceable> is <literal>native</literal>, 608 <literal>checking</literal>, or 609 <literal>slow</literal>. For production use you probably 610 want <literal>native</literal>. The <literal>slow</literal> 611 module is more thorough than <literal>checking</literal>, 612 but much slower. 613 Default value is dependent on <literal>--with-defaults</literal>. 614 </para></listitem> 615 616 <listitem><para><literal>--enable-mutex-stats</literal> 617 618 Produce information about lock contention.</para></listitem> 619 620 <listitem><para><literal>--enable-start-stop-daemon</literal> 621 622 Compile the start-stop-daemon program.</para></listitem> 623 624 <listitem><para><literal>--enable-pam</literal> 625 626 Enable using PAM for authentication of sendsms users for 627 smsbox.</para></listitem> 628 629 <listitem><para><literal>--with-mssql<replaceable>[=DIR]</replaceable></literal> 630 631 Enable using FreeTDS libraries for DBPool and 632 DLR support on MS-SQL and Sybase. Optional DIR specifies where to look for 633 FreeTDS libraries and include files (defaults to /usr/local).</para></listitem> 634 635 <listitem><para><literal>--with-mysql</literal> 636 637 Enable using MySQL libraries for DBPool and 638 DLR support.</para></listitem> 639 640 <listitem><para><literal>--with-mysql-dir=</literal><replaceable>DIR</replaceable> 641 642 Where to look for MySQL libs and header files. 643 DIR points to the installation of MySQL.</para></listitem> 644 645 <listitem><para><literal>--with-sdb</literal> 646 647 Enable using LibSDB libraries for dlr support. 648 </para></listitem> 649 650 <listitem><para><literal>--with-oracle</literal> 651 652 Enable using Oracle OCI-Libraries for Oracle 8i/9i DBPool and 653 DLR support.</para></listitem> 654 655 <listitem><para><literal>--with-oracle-includes=</literal><replaceable>DIR</replaceable> 656 657 Where to look for Oracle OCI-Header files.</para></listitem> 658 659 <listitem><para><literal>--with-oracle-libs=</literal><replaceable>DIR</replaceable> 660 661 Where to look for Oracle OCI-Library files.</para></listitem> 662 663 <listitem><para><literal>--with-redis</literal> 664 665 Enable using Redis for DBPool and DLR support. Requires the hiredis library.</para></listitem> 666 667 <listitem><para><literal>--with-redis-dir=</literal><replaceable>DIR</replaceable> 668 669 Where to look for the hiredis library and header files.</para></listitem> 670 671 <!-- XXX DAVI add openssl and others in here --> 672 673 </itemizedlist> 674 </para> 675 676 <para>You may need to add compilations flags to configure: 677 678 <screen><userinput> 679 CFLAGS='-pthread' ./configure 680 </userinput></screen> 681 682 The above, for instance, seems to be required on FreeBSD. If you 683 want to develop Kannel, you probably want to add CFLAGS that make 684 your compiler use warning messages. For example, for GCC: 685 686 <screen><userinput> 687 CFLAGS='-Wall -O2 -g' ./configure 688 </userinput></screen> 689 690 (You may, at your preference, use even stricter checking options.) 691 </para> 692 693</sect1> 694 695<sect1> 696<title>Installing the gateway</title> 697 698 <para>After you have compiled Kannel, you need to install 699 certain programs in a suitable place. This is most easily 700 done by using <command>make</command> again: 701 702 <screen><userinput> 703 make bindir=<replaceable>/path/to/directory</replaceable> install 704 </userinput></screen> 705 706 Replace <replaceable>/path/to/directory</replaceable> with the 707 pathname of the actual directory where the programs should be 708 installed. The programs that are installed are (as filenames 709 from the root of the source directory): 710 711 <simplelist> 712 <member><filename>gw/bearerbox</filename></member> 713 <member><filename>gw/smsbox</filename></member> 714 <member><filename>gw/wapbox</filename></member> 715 </simplelist> 716 717 The version number of the gateway is added to the file names 718 during installation. This makes it easier to have several 719 versions installed, and makes it easy to go back to an older 720 version if the new version proves problematic.</para> 721 722 <para>Kannel consists of three programs called boxes: the 723 bearer box is the interface towards the phones. It accepts 724 WAP and SMS messages from the phones and sends them to the 725 other boxes. The SMS box handles SMS gateway functionality, 726 and the WAP box handles WAP gateway functionality. There can 727 be several SMS boxes and several WAP boxes running and they 728 don't have to run on the same host. This makes it possible 729 to handle much larger loads.</para> 730 731</sect1> 732 733<sect1> 734<title>Using pre-compiled binary packages</title> 735 736<sect2> 737<title>Installing Kannel from RPM packages</title> 738 739 <para>This chapter explains how to install, upgrade and remove 740 Kannel binary RPM packages.</para> 741 742 <para>Before you install Kannel, check that you have libxml2 743 installed on your system:</para> 744 745 <screen><userinput> 746 rpm -q libxml2 747 </userinput></screen> 748 749 <para>Installing Kannel</para> 750 751 <para>1. Download the binary RPM packet from the Kannel 752 web site.</para> 753 754 <para>2. Install the RPM package: 755 756 <screen><userinput> 757 rpm -ivh kannel-<replaceable>VERSION</replaceable>.<replaceable>i386</replaceable>.rpm 758 </userinput></screen> 759 </para> 760 761 <para>Upgrading Kannel</para> 762 763 <para>1. Download the binary RPM packet from the Kannel 764 web site.</para> 765 766 <para>2. Upgrade the RPM package: 767 768 <screen><userinput> 769 rpm -Uvh kannel-<replaceable>VERSION</replaceable>.<replaceable>i386</replaceable>.rpm 770 </userinput></screen> 771 </para> 772 773 <para>Removing Kannel</para> 774 775 <para>1. Remove the RPM package: 776 777 <screen><userinput> 778 rpm -e kannel 779 </userinput></screen> 780 </para> 781 782 <para>After you have installed Kannel from the RPM packages you 783 should now be able to run the Kannel init.d script that will 784 start Kannel as a WAP gateway. Run the script as root.</para> 785 786 <screen><userinput> 787 /etc/rc.d/init.d/kannel start 788 </userinput></screen> 789 790 <para>To stop the gateway just run the same script with the 791 stop parameter.</para> 792 793 <screen><userinput> 794 /etc/rc.d/init.d/kannel stop 795 </userinput></screen> 796 797 <para>If Kannel is already running and you just want to quickly 798 stop and start the gateway,e.g.to set a new configuration option, 799 run the script with the restart parameter.</para> 800 801 <screen><userinput> 802 /etc/rc.d/init.d/kannel restart 803 </userinput></screen> 804 805 <para>If you want Kannel to run as a daemon, you need to add a 806 symbolic link to the Kannel script from the runlevel you want 807 Kannel to run in. E.g. to run Kannel in runlevel 5 add symbolic 808 links to /etc/rc.d/rc5.d/.</para> 809 810 <screen><userinput> 811 cd /etc/rc.d/rc5.d/ 812 ln -s ../init.d/kannel S91kannel 813 ln -s ../init.d/kannel K91kannel 814 </userinput></screen> 815 816 <para>To run Kannel as a SMS gateway you need to edit the 817 configuration file which is at /etc/kannel/kannel.conf. 818 In Kannel's documentation directory 819 (<filename>/usr/share/doc/kannel</filename>) 820 there is an example file called examples/smskannel.conf. 821 It has some basic examples of the configuration groups needed 822 to run Kannel as a SMS gateway. For more detailed information 823 please see <filename>examples/kannel.conf</filename> in the 824 same directory for a commented complete example, and read the 825 section "SMS gateway configuration" later in this same 826 document.</para> 827 828 <para>The logging is disabled by default and you can enable 829 it from the kannel.conf file. Just add the log-file option 830 to the group of which box you want to log.</para> 831 832 <para>The documentation will be installed at 833 /usr/doc/kannel-VERSION/ or /usr/share/doc/kannel-VERSION/ 834 depending on if you used the RedHat 6.x or a 7.x or newer 835 package.</para> 836 837 <para>In the Kannel documentation directory there is a HTML 838 file called control.html. It is an example file that shows 839 how to use the Kannel HTTP administration interface. It 840 also has a template for sending SMS messages.</para> 841 842</sect2> 843 844<sect2> 845<title>Installing Kannel from DEB packages</title> 846 847 <para>This chapter explains how to install, upgrade and remove 848 Kannel binary DEB packages.</para> 849 850 <para>Kannel's packages are available on main Debian repository 851 (<ulink url="http://packages.debian.org/kannel">http://packages.debian.org/kannel</ulink>) 852 although that version may be out-of-sync with latest Kannel version. 853 </para> 854 <!-- XXX DAVI add kannel packages and my repository here --> 855 856 <para>Before you install Kannel, check that you have libxml2 857 installed on your system:</para> 858 859 <screen><userinput> 860 dpkg -l libxml2 861 </userinput></screen> 862 863 <para>Installing or upgrading Kannel from Debian or Kannel repository</para> 864 865 <para>1. Install or upgrade the package: 866 867 <screen><userinput> 868 apt-get install kannel 869 </userinput></screen> 870 </para> 871 872 <para>See http://kannel.org/download.shtml#debian_repository for 873 information about kannel repository sources.list</para> 874 875 <para>Installing or upgrading Kannel from a file</para> 876 877 <para>1. Download the binary DEB packet from the Kannel 878 web site.</para> 879 880 <para>2. Log in as root:</para> 881 882 <screen><userinput> 883 su - 884 </userinput></screen> 885 886 <para>3. Install or upgrade the DEB package:</para> 887 <screen><userinput> 888 dpkg -i kannel-<replaceable>VERSION</replaceable>.deb 889 </userinput></screen> 890 891 <para>Removing Kannel</para> 892 893 <para>1. Log in as root:</para> 894 895 <para>2. Remove the package keeping configuration files:</para> 896 <screen><userinput> 897 dpkg --remove kannel 898 </userinput></screen> 899 900 <para>3. Remove the package completely:</para> 901 <screen><userinput> 902 dpkg --purge kannel 903 </userinput></screen> 904 905 <para>After you have installed Kannel from the DEB packages you 906 should now be able to run the Kannel init.d script that will 907 start Kannel as a WAP gateway. Run the script as root.</para> 908 909 <screen><userinput> 910 /etc/init.d/kannel start 911 </userinput></screen> 912 913 <para>To stop the gateway just run the same script with the 914 stop parameter.</para> 915 916 <screen><userinput> 917 /etc/init.d/kannel stop 918 </userinput></screen> 919 920 <para>If Kannel is already running and you just want to quickly 921 stop and start the gateway,e.g.to set a new configuration option, 922 run the script with the restart parameter.</para> 923 924 <screen><userinput> 925 /etc/init.d/kannel restart 926 </userinput></screen> 927 928 <para>If you don't want Kannel to run as a daemon, 929 run: </para> 930 931 <screen><userinput> 932 update-rc.d -f kannel remove 933 </userinput></screen> 934 935 <para>If you want to restore Kannel running as a daemon, you 936 need to add a 937 symbolic link to the Kannel script from the runlevel you want 938 Kannel to run in. E.g. to run Kannel in default runlevel, 939 just run: </para> 940 941 <screen><userinput> 942 update-rc.d kannel defaults 943 </userinput></screen> 944 945 <para>Kannel package starts by default with a wapbox daemon. 946 To activate smsbox or select which box you want to start, 947 edit /etc/default/kannel and comment/uncomment START_xxxBOX. 948 </para> 949 950 <para>To run Kannel as a SMS gateway you need to edit the 951 configuration file which is at /etc/kannel/kannel.conf. 952 In /usr/share/docs/kannel/examples/ there are example files. 953 They have some basic examples of the configuration groups 954 needed to run Kannel as a SMS gateway. For 955 more detailed information please read the section "SMS gateway 956 configuration" later in this same document.</para> 957 958 <para>The documentation will be installed at 959 /usr/share/doc/kannel/.</para> 960 961 <para>In the Kannel documentation directory there is a html 962 file called control.html. It is an example file that shows 963 how to use the Kannel HTTP administration interface. It 964 also has a template for sending SMS messages.</para> 965 966 <para>Additionally to kannel-VERSION.deb, there's now an optional 967 kannel-docs-VERSION.deb with documentation (userguide et al) and 968 a kannel-extras-VERSION.deb with contrib and test stuff.</para> 969 970 <para>If you want to test development version, use the packages 971 called kannel-devel-*.deb.</para> 972 973</sect2> 974 975</sect1> 976 977</chapter> 978 979 980<chapter> 981<title>Using the gateway</title> 982 983 <para>This chapter explains how the gateway core, bearerbox, 984 is configured and used. 985 It covers the configuration file, keeping an eye on the gateway 986 while it is running, and using the HTTP interface to control 987 the gateway.</para> 988 989 <para>After this chapter there is distinct chapter for each 990 kind of gateway use: WAP gateway, SMS gateway and WAP Push 991 proxy. These chapters explain the configuration and other 992 aspects of gateway of that type.</para> 993 994 <para>You can configure your Kannel to be only a WAP or a SMS 995 gateway, or to be both at the same time. You just need to read 996 each chapter and combine all configurations.</para> 997 998 <para>There is only one configuration file for all parts of 999 Kannel, although when Kannel is distributed to several hosts 1000 some lines from the configuration file can be removed in some 1001 hosts.</para> 1002 1003<sect1> 1004<title>Configuring the gateway</title> 1005 1006 <para>The configuration file can be divided into three parts: 1007 bearerbox configurations, smsbox configurations and 1008 wapbox configurations. Bearerbox part has one 'core' group 1009 and any used SMS center groups, while wapbox part has only 1010 one wapbox group. In smsbox part there is one smsbox group and 1011 then number of sms-service and sendsms-user groups.</para> 1012 1013 <para>Details of each part are in an appropriate section of this 1014 documentation. The 'core' group used by the bearerbox is 1015 explained in this chapter, while 'wapbox' part is in the next 1016 chapter and 'smsbox', 'smsc' (SMS center), 'sms-service' and 1017 'sendsms-user' groups are in the SMS Kannel chapter.</para> 1018 1019 1020 1021<sect2> 1022<title>Configuration file syntax</title> 1023 1024 <para>A configuration file consists of groups of configuration variables. Groups are 1025 separated by empty lines, and each variable is defined on its 1026 own line. Each group in Kannel configuration is distinguished 1027 with a group variable. Comments are lines that begin with a number sign 1028 (<literal>#</literal>) and are ignored (they don't, for example, 1029 separate groups of variables).</para> 1030 1031 <para>A variable definition line has the name of the variable, 1032 and equals sign (<literal>=</literal>) and the value of the 1033 variable. The name of the variable can contain any characters 1034 except white space and equals. The value of the variable is a 1035 string, with or without quotation marks (<literal></literal>) 1036 around it. Quotation marks are needed if the variable needs to 1037 begin or end with white space or contain special 1038 characters. Normal C escape character syntax works inside 1039 quotation marks.</para> 1040 1041 <para>Perhaps an example will make things easier to comprehend: 1042 1043<programlisting> 10441 # A do-nothing service. 10452 group = sms-service 10463 keyword = nop 10474 text = "You asked nothing and I did it!" 10485 10496 # Default service. 10507 group = sms-service 10518 keyword = default 10529 text = "No services defined" 1053</programlisting> 1054 1055 The above snippet defines the keyword <literal>nop</literal> 1056 for an SMS service, and a default action for situation when 1057 the keyword in the SMS message does not match any defined 1058 service.</para> 1059 1060 <para>Lines 1 and 6 are comment lines. Line 5 separates the 1061 two groups. The remaining lines define variables. The 1062 group type is defined by the group variable value.</para> 1063 1064 <para>The various variables that are understood in each type 1065 of configuration group are explained below.</para> 1066 1067 <para>Some variable values are marked as 1068 <literal>'bool'</literal>. The value for variable can be like 1069 true, false, yes, no, on, off, 0 or 1. Other values are 1070 treated as 'true' while if the variable is not present at all, 1071 it is treated as being 'false'.</para> 1072 1073 <para>In order to make some configuration lines more readable 1074 you may use the delimiter '\' at the end of a line to wrap 1075 and concatenate the next line up to the current line. Here is 1076 an example: 1077 1078<programlisting> 10791 # A group with a wrapped alias line 10802 group = sms-service 10813 keyword = hello 10824 aliases = hallo;haalloo;\ 10835 heelloo;haelloo;healloo 10845 text = "Hello world!" 1085</programlisting> 1086 1087 The above example shows how a list for various alias keywords 1088 is wrapped to two lines using the line wrap delimiter. In order 1089 to use the delimiter '\' itself, you need to escape it via a 1090 prefixed '\' itself. So this is '\\' to escape the wrapping 1091 function and use the character in the string.</para> 1092 1093</sect2> 1094 1095<sect2 id="includes"> 1096<title id="includes.title">Inclusion of configuration files</title> 1097 1098 <para>A configuration file may contain a special directive 1099 called <literal>include</literal> to include other 1100 file or a directory with files to the configuration 1101 processing.</para> 1102 1103 <para>This allows to segment the specific configuration groups 1104 required for several services and boxes to different files and 1105 hence to have more control in larger setups.</para> 1106 1107 <para>Here is an example that illustrates the <literal>include 1108 </literal> statement : 1109 1110<programlisting> 1111group = core 1112admin-port = 13000 1113wapbox-port = 13002 1114admin-password = bar 1115wdp-interface-name = "*" 1116log-file = "/var/log/bearerbox.log" 1117log-level = 1 1118box-deny-ip = "*.*.*.*" 1119box-allow-ip = "127.0.0.1" 1120 1121include = "wapbox.conf" 1122 1123include = "configurations" 1124</programlisting> 1125 1126 Above is the main <literal>kannel.conf</literal> configuration 1127 file that includes the following <literal>wapbox.conf</literal> 1128 file with all required directives for the specific box, and a 1129 <literal>configurations</literal> directory which may include 1130 more files to include. 1131 1132<programlisting> 1133group = wapbox 1134bearerbox-host = localhost 1135log-file = "/var/log/wapbox.log" 1136log-level = 0 1137syslog-level = none 1138</programlisting> 1139 1140 1141 The above <literal>include</literal> statement may be defined 1142 at any point in the configuration file and at any inclusion 1143 depth. Hence you can cascade numerous inclusions if necessary. 1144 </para> 1145 1146 <para>At process start time inclusion of configuration files 1147 breaks if either the included file can not be opened and 1148 processed or the included file has been processed already in 1149 the stack and a recursive cycling has been detected.</para> 1150 1151</sect2> 1152 1153<sect2> 1154<title>Core configuration</title> 1155 1156 <para>Configuration for Kannel <emphasis>MUST</emphasis> always 1157 include a group for general bearerbox configuration. This group is 1158 named as 'core' in configuration file, and should be the first group 1159 in the configuration file.</para> 1160 1161 <para>As its simplest form, 'core' group looks like this: 1162 1163<programlisting> 1164group = core 1165admin-port = 13000 1166admin-password = f00bar 1167</programlisting> 1168 1169 Naturally this is not sufficient for any real use, as you want to 1170 use Kannel as an SMS gateway, or WAP gateway, or both. Thus, one or 1171 more of the optional configuration variables are used. In following 1172 list (as in any other similar lists), all mandatory variables are 1173 marked with <literal>(m)</literal>, while conditionally mandatory 1174 (variables which must be set in certain cases) are marked with 1175 <literal>(c)</literal>.</para> 1176 1177 1178 <table frame="none"> 1179 <title>Core Group Variables</title> 1180 <tgroup cols="3"> 1181 <thead> 1182 <row> 1183 <entry>Variable</entry> 1184 <entry>Value</entry> 1185 <entry>Description</entry> 1186 </row> 1187 </thead> 1188 <tbody> 1189 <row><entry><literal>group (m)</literal></entry> 1190 <entry><literal>core</literal></entry> 1191 <entry valign="bottom"> 1192 This is a mandatory variable 1193 </entry></row> 1194 1195 <row><entry><literal>admin-port (m)</literal></entry> 1196 <entry>port-number</entry> 1197 <entry valign="bottom"> 1198 The port number in which the bearerbox listens to HTTP 1199 administration commands. It is NOT the same as the HTTP 1200 port of the local HTTP server, just invent any port, but 1201 it must be over 1023 unless you are running Kannel as a 1202 root process (not recommended) 1203 </entry></row> 1204 1205 <row><entry><literal>admin-port-ssl (o)</literal></entry> 1206 <entry>bool</entry> 1207 <entry valign="bottom"> 1208 If set to true a SSL-enabled administration HTTP server 1209 will be used instead of the default insecure plain HTTP 1210 server. To access the administration pages you will have 1211 to use a HTTP client that is capable of talking to such 1212 a server. Use the "https://" scheme to access the 1213 secured HTTP server. Defaults to "no". 1214 </entry></row> 1215 1216 <row><entry><literal>admin-password (m)</literal></entry> 1217 <entry>string</entry> 1218 <entry valign="bottom"> 1219 Password for HTTP administration commands (see below) 1220 </entry></row> 1221 1222 <row><entry><literal>status-password</literal></entry> 1223 <entry>string</entry> 1224 <entry valign="bottom"> 1225 Password to request Kannel status. If not set, no password is 1226 required, and if set, either this or 1227 <literal>admin-password</literal> can be used 1228 </entry></row> 1229 1230 <row><entry><literal>admin-deny-ip</literal></entry> 1231 <entry morerows="1">IP-list</entry> 1232 <entry morerows="1" valign="bottom"> 1233 These lists can be used to prevent connection from given IP 1234 addresses. Each list can have several addresses, separated with 1235 semicolons (';'). An asterisk ('*') can be used 1236 as a wild-card in a place of any ONE number, so *.*.*.* 1237 matches any IP. 1238 </entry></row> 1239 <row><entry><literal>admin-allow-ip</literal></entry></row> 1240 1241 <row><entry><literal>smsbox-interface (o)</literal></entry> 1242 <entry>string</entry> 1243 <entry valign="bottom"> 1244 If this is set, the smsbox listener will only bind 1245 to a specified address. For example: "127.0.0.1". 1246 </entry></row> 1247 1248 <row><entry><literal>smsbox-port (c)</literal></entry> 1249 <entry>port-number</entry> 1250 <entry valign="bottom"> 1251 This is the port number to which the smsboxes, if any, connect. 1252 As with admin-port, this can be anything you want. Must be set 1253 if you want to handle any SMS traffic. 1254 </entry></row> 1255 1256 <row><entry><literal>smsbox-port-ssl (o)</literal></entry> 1257 <entry>bool</entry> 1258 <entry valign="bottom"> 1259 If set to true, the smsbox connection module will be SSL-enabled. 1260 Your smsboxes will have to connect using SSL to the bearerbox 1261 then. This is used to secure communication between bearerbox 1262 and smsboxes in case they are in separate networks operated and 1263 the TCP communication is not secured on a lower network layer. 1264 Defaults to "no". 1265 </entry></row> 1266 1267 <row><entry><literal>wapbox-port (c)</literal></entry> 1268 <entry>port-number</entry> 1269 <entry valign="bottom"> 1270 Like smsbox-port, but for wapbox-connections. If not set, 1271 Kannel cannot handle WAP traffic 1272 </entry></row> 1273 1274 <row><entry><literal>wapbox-port-ssl (o)</literal></entry> 1275 <entry>bool</entry> 1276 <entry valign="bottom"> 1277 If set to true, the wapbox connection module will be SSL-enabled. 1278 Your wapboxes will have to connect using SSL to the bearerbox 1279 then. This is used to secure communication between bearerbox 1280 and wapboxes in case they are in separate networks operated and 1281 the TCP communication is not secured on a lower network layer. 1282 Defaults to "no". 1283 </entry></row> 1284 1285 <row><entry><literal>box-deny-ip</literal></entry> 1286 <entry morerows="1">IP-list</entry> 1287 <entry morerows="1" valign="bottom"> 1288 These lists can be used to prevent box connections from given IP 1289 addresses. Each list can have several addresses, 1290 separated with semicolons (';'). An asterisk ('*') can be used 1291 as a wild-card in place of any ONE number, so *.*.*.* 1292 matches any IP. 1293 </entry></row> 1294 <row><entry><literal>box-allow-ip</literal></entry></row> 1295 1296 <row><entry><literal>udp-deny-ip</literal></entry> 1297 <entry morerows="1">IP-list</entry> 1298 <entry morerows="1" valign="bottom"> 1299 These lists can be used to prevent UDP packets from given IP 1300 addresses, thus preventing unwanted use of the WAP gateway. 1301 Used the same way as <literal>box-deny-ip</literal> and 1302 <literal>box-allow-ip</literal>. 1303 </entry></row> 1304 <row><entry><literal>udp-allow-ip</literal></entry></row> 1305 1306 <row><entry><literal>wdp-interface-name (c)</literal></entry> 1307 <entry>IP or '*'</entry> 1308 <entry valign="bottom"> 1309 If this is set, Kannel listens to WAP UDP packets incoming to 1310 ports 9200-9208, bound to given IP. If no specific IP is 1311 needed, use just an asterisk ('*'). If UDP messages are 1312 listened to, wapbox-port variable MUST be set. 1313 </entry></row> 1314 1315 <row><entry><literal>log-file</literal></entry> 1316 <entry>filename</entry> 1317 <entry valign="bottom"> 1318 A file in which to write a log. This in addition to <literal>stdout</literal> 1319 and any log file defined in command line. Log-file in 'core' 1320 group is only used by the bearerbox. 1321 </entry></row> 1322 1323 <row><entry><literal>log-level</literal></entry> 1324 <entry>number 0..5</entry> 1325 <entry valign="bottom"> 1326 Minimum level of log-file events logged. 0 is for 'debug', 1 1327 'info', 2 'warning, 3 'error' and 4 'panic' (see Command Line 1328 Options) 1329 </entry></row> 1330 1331 <row><entry><literal>access-log</literal></entry> 1332 <entry>filename</entry> 1333 <entry valign="bottom"> 1334 A file in which information about received/sent SMS messages 1335 is stored. Access-log in 'core' group is only used by the 1336 bearerbox. 1337 </entry></row> 1338 1339 <row><entry><literal>access-log-clean</literal></entry> 1340 <entry>boolean</entry> 1341 <entry valign="bottom"> 1342 Indicates if <literal>access-log</literal> will contain standard 'markers', 1343 which means the 'Log begins', 'Log ends' markers and the prefixed 1344 timestamp. This config directive should be set to 'true' if a custom 1345 logging format is desired without a prefixed default timestamp. 1346 </entry></row> 1347 1348 <row><entry><literal>access-log-format</literal></entry> 1349 <entry>string</entry> 1350 <entry valign="bottom"> 1351 String defining a custom log file line format. May use escape codes as defined 1352 later on to substitute values of the messages into the log entry. If no 1353 custom log format is used the standard format will be: 1354 <literal>"%t %l [SMSC:%i] [SVC:%n] [ACT:%A] [BINF:%B] [FID:%F] [META:%D] [from:%p] [to:%P] 1355 [flags:%m:%c:%M:%C:%d] [msg:%L:%b] [udh:%U:%u]"</literal> 1356 </entry></row> 1357 1358 <row><entry><literal>syslog-level</literal></entry> 1359 <entry>number</entry> 1360 <entry valign="bottom"> 1361 Messages of this log level or higher will also be 1362 sent to syslog, the UNIX system log daemon. If not explicitly 1363 set with <literal>syslog-facility</literal>, it logs under the 1364 'daemon' category. The default is not to use syslog, and you can 1365 set that explicitly by setting <literal>syslog-level</literal> 1366 to 'none'. 1367 </entry></row> 1368 1369 <row><entry><literal>syslog-facility</literal></entry> 1370 <entry>string</entry> 1371 <entry valign="bottom"> 1372 The syslog facility to send the syslog entries to. The 1373 default is 'daemon'. 1374 </entry></row> 1375 1376 <row><entry><literal>unified-prefix</literal></entry> 1377 <entry>prefix-list</entry> 1378 <entry valign="bottom"> 1379 String to unify received phone numbers, for SMSC routing and 1380 to ensure that SMS centers can handle them properly. 1381 This is applied to 'sender' number when receiving SMS 1382 messages from SMS Center and for 'receiver' number when 1383 receiving messages from smsbox (either sendsms message or 1384 reply to original message). Format is that first comes the 1385 unified prefix, then all prefixes which are replaced by the 1386 unified prefix, separated with comma (','). For example, 1387 for Finland an unified-prefix "+358,00358,0;+,00" should do the trick. 1388 If there are several unified prefixes, separate their rules with 1389 semicolon (';'), like "+35850,050;+35840,040". <emphasis>Note 1390 that prefix routing is next to useless now that there are 1391 SMSC ID entries. To remove prefixes, use like 1392 "-,+35850,050;-,+35840,040". 1393 </emphasis> 1394 1395 </entry></row> 1396 1397 <row><entry><literal>white-list</literal></entry> 1398 <entry>URL</entry> 1399 <entry valign="bottom"> 1400 Load a list of accepted senders of SMS messages. If a sender 1401 of an SMS message is not in this list, any message received 1402 from the SMS Center is discarded. See notes of phone number 1403 format from numhash.h header file. NOTE: the system has only 1404 a precision of last 9 or 18 digits of phone numbers, so 1405 beware! 1406 </entry></row> 1407 1408 <row><entry><literal>black-list</literal></entry> 1409 <entry>URL</entry> 1410 <entry valign="bottom"> 1411 As white-list, but SMS messages to these numbers are 1412 automatically discarded 1413 </entry></row> 1414 1415 <row><entry><literal>store-type</literal></entry> 1416 <entry>filename</entry> 1417 <entry valign="bottom"> 1418 Kannel can use store subsystem that means storing messages 1419 on hard disk until they are successfully handled. By using 1420 this subsystem, no SMS messages are lost in Kannel even by 1421 crash, but theoretically some messages can duplicate when 1422 system is taken down violently. 1423 This variable defines a type of backend used for store 1424 subsystem. Now two types are supported: 1425 a) file: writes store into one single file 1426 b) spool: writes store into spool directory (one file for each message) 1427 </entry></row> 1428 1429 <row><entry><literal>store-location</literal></entry> 1430 <entry>filename</entry> 1431 <entry valign="bottom"> 1432 Depends on <literal>store-type</literal> option used, it is ether file or spool directory. 1433 </entry></row> 1434 1435 <row><entry><literal>store-dump-freq</literal></entry> 1436 <entry>seconds</entry> 1437 <entry valign="bottom"> 1438 Approximated frequency how often the memory dump of current 1439 pending messages are stored to store-file, providing something 1440 has happened. Defaults to 10 seconds if not set. 1441 </entry></row> 1442 1443 <row><entry><literal>http-proxy-host</literal></entry> 1444 <entry>hostname</entry> 1445 <entry morerows="1" valign="bottom"> 1446 Enable the use of an HTTP proxy for all HTTP requests. 1447 </entry></row> 1448 <row><entry><literal>http-proxy-port</literal></entry> 1449 <entry>port-number</entry></row> 1450 1451 <row><entry><literal>http-proxy-exceptions</literal></entry> 1452 <entry>URL-list</entry> 1453 <entry valign="bottom"> 1454 A list of excluded hosts from being used via a 1455 proxy. Separate each entry with space. 1456 </entry></row> 1457 1458 <row><entry><literal>http-proxy-exceptions-regex</literal></entry> 1459 <entry>UNIX regular expression</entry> 1460 <entry valign="bottom"> 1461 Same as http-proxy-exceptions but match against UNIX regular expression. 1462 </entry></row> 1463 1464 <row><entry><literal>http-proxy-username</literal></entry> 1465 <entry>username</entry> 1466 <entry valign="bottom"> 1467 Username for authenticating proxy use, for proxies that 1468 require this. 1469 </entry></row> 1470 1471 <row><entry><literal>http-proxy-password</literal></entry> 1472 <entry>URL-list</entry> 1473 <entry valign="bottom"> 1474 Password for authenticating proxy use, for proxies that 1475 require this. 1476 </entry></row> 1477 1478 <row><entry><literal>ssl-client-certkey-file (c)</literal></entry> 1479 <entry>filename</entry> 1480 <entry valign="bottom"> 1481 A PEM encoded SSL certificate and private key file to be used 1482 with SSL client connections. This certificate is used for 1483 the HTTPS client side only, i.e. for SMS service requests to 1484 SSL-enabled HTTP servers. 1485 </entry> 1486 </row> 1487 1488 <row><entry><literal>ssl-server-cert-file (c)</literal></entry> 1489 <entry>filename</entry> 1490 <entry valign="bottom"> 1491 A PEM encoded SSL certificate file to be used with SSL server 1492 connections. This certificate is used for the HTTPS server 1493 side only, i.e. for the administration HTTP server and the 1494 HTTP interface to send SMS messages. 1495 </entry> 1496 </row> 1497 1498 <row><entry><literal>ssl-server-key-file (c)</literal></entry> 1499 <entry>filename</entry> 1500 <entry valign="bottom"> 1501 A PEM encoded SSL private key file to be used with SSL server 1502 connections. This key is associated to the specified 1503 certificate and is used for the HTTPS server side only. 1504 </entry> 1505 </row> 1506 <row><entry><literal>ssl-trusted-ca-file</literal></entry> 1507 <entry>filename</entry> 1508 <entry valign="bottom"> 1509 This file contains the certificates Kannel is willing to trust when 1510 working as a HTTPS client. If this option is not set, certificates 1511 are not validated and those the identity of the server is not proven. 1512 </entry> 1513 </row> 1514 1515 <row><entry><literal>dlr-storage</literal></entry> 1516 <entry>type</entry> 1517 <entry valign="bottom"> 1518 Defines the way DLRs are stored. Natively in-memory storage is 1519 supported, which is very fast, but has no persistancy. This means 1520 you will loose all your temporary DLR information on bearebox 1521 re-start. In addition a spool directory approach is natively 1522 supported, which garantees persistancy with a reasonable 1523 performance, depending on your disk IO performance. 1524 If you have build-in external DLR storage support, i.e. using 1525 MySQL you may define here the alternative storage type like 1526 <literal>mysql</literal>. 1527 Supported types are: 1528 <literal>internal</literal>, 1529 <literal>spool</literal>, 1530 <literal>mysql</literal>, 1531 <literal>pgsql</literal>, 1532 <literal>sdb</literal>, 1533 <literal>mssql</literal>, 1534 <literal>sqlite3</literal>, 1535 <literal>oracle</literal> and 1536 <literal>redis</literal>. 1537 By default this is set to <literal>internal</literal>. 1538 </entry></row> 1539 1540 <row><entry><literal>dlr-spool</literal></entry> 1541 <entry>filename</entry> 1542 <entry valign="bottom"> 1543 Depends on <literal>dlr-storage = spool</literal> option used, it 1544 is the spool directory to use for DLR storage data. 1545 </entry></row> 1546 1547 <row><entry><literal>maximum-queue-length</literal></entry> 1548 <entry>number of messages</entry> 1549 <entry valign="bottom"> 1550 (deprecated, see <literal>sms-incoming-queue-limit</literal>). 1551 </entry></row> 1552 1553 <row><entry><literal>sms-incoming-queue-limit</literal></entry> 1554 <entry>number of messages</entry> 1555 <entry valign="bottom"> 1556 Set maximum size of incoming message queue. After number of messages 1557 has hit this value, Kannel began to discard them. 1558 Value 0 means giving strict priority to outgoing messages. -1, 1559 default, means that the queue of infinite length is accepted. (This 1560 works with any normal input, use this variable only when Kannel message 1561 queues grow very long). 1562 </entry></row> 1563 1564 <row><entry><literal>sms-outgoing-queue-limit</literal></entry> 1565 <entry>number of messages</entry> 1566 <entry valign="bottom"> 1567 Set maximum size of outgoing message queue. After number of messages 1568 has hit this value, Kannel began to discard them. 1569 The default value, 1 million, works for most installations. 1570 </entry></row> 1571 1572 <row><entry><literal>white-list-regex</literal></entry> 1573 <entry>POSIX regular expression</entry> 1574 <entry valign="bottom"> 1575 A regular expression defining the set of accepted senders. 1576 See section on <xref linkend="regular-expressions"/> for details. 1577 </entry> 1578 </row> 1579 <row><entry><literal>black-list-regex</literal></entry> 1580 <entry>POSIX regular expression</entry> 1581 <entry valign="bottom"> 1582 A regular expression defining the set of rejected senders. 1583 See section on <xref linkend="regular-expressions"/> for details. 1584 </entry> 1585 </row> 1586 1587 <row><entry><literal>smsbox-max-pending</literal></entry> 1588 <entry>number of messages</entry> 1589 <entry valign="bottom"> 1590 Maximum number of pending messages on the line to smsbox compatible boxes. 1591 </entry> 1592 </row> 1593 1594 <row><entry><literal>sms-resend-freq</literal></entry> 1595 <entry>seconds</entry> 1596 <entry valign="bottom"> 1597 Frequency for the SMS resend thread in which temporarily failed or queued messages will be resent. 1598 Defaults to 60 seconds. 1599 </entry> 1600 </row> 1601 1602 <row><entry><literal>sms-resend-retry</literal></entry> 1603 <entry>number</entry> 1604 <entry valign="bottom"> 1605 Maximum retry attempts for the temporarily failed messages. 1606 Defaults to -1, means: unlimited. 1607 </entry> 1608 </row> 1609 1610 <row><entry><literal>sms-combine-concatenated-mo</literal></entry> 1611 <entry>boolean</entry> 1612 <entry valign="bottom"> 1613 Whether Kannel should attempt to combine concatenated MO SMS 1614 prior to passing them over to smsbox. Default is true 1615 </entry> 1616 </row> 1617 1618 <row><entry><literal>sms-combine-concatenated-mo-timeout</literal></entry> 1619 <entry>seconds</entry> 1620 <entry valign="bottom"> 1621 How long to wait for all concatenated message parts to arrive before timeouting. 1622 Default 1800 seconds. 1623 </entry> 1624 </row> 1625 1626 <row><entry><literal>http-timeout</literal></entry> 1627 <entry>seconds</entry> 1628 <entry valign="bottom"> 1629 Sets socket timeout in seconds for outgoing client http 1630 connections. Optional. Defaults to 240 seconds. 1631 </entry></row> 1632 1633 </tbody> 1634 </tgroup> 1635 </table> 1636 1637 <para>A sample more complex 'core' group could be something like 1638 this: 1639 1640<programlisting> 1641group = core 1642admin-port = 13000 1643admin-password = f00bar 1644status-password = sTat 1645admin-deny-ip = "*.*.*.*" 1646admin-allow-ip = "127.0.0.1;200.100.0.*" 1647smsbox-port = 13003 1648wapbox-port = 13004 1649box-deny-ip = "*.*.*.*" 1650box-allow-ip = "127.0.0.1;200.100.0.*" 1651wdp-interface-name = "*" 1652log-file = "kannel.log" 1653log-level = 1 1654access-log = "kannel.access" 1655unified-prefix = "+358,00358,0;+,00" 1656white-list = "http://localhost/whitelist.txt" 1657</programlisting> 1658 1659 </para> 1660 1661</sect2> 1662 1663</sect1> 1664 1665<sect1> 1666<title>Running Kannel</title> 1667 1668 <para>To start the gateway, you need to start each box you need. 1669 You always need the bearer box, and depending on whether you want 1670 WAP and SMS gateways you need to start the WAP and SMS boxes. If 1671 you want, you can run several of them, but we'll explain the 1672 simple case of only running one each.</para> 1673 1674 1675<sect2> 1676<title>Starting the gateway</title> 1677 1678 <para>After you have compiled Kannel and edited configuration file 1679 for your taste, you can either run Kannel from command line or use 1680 supplied <literal>start-stop-daemon</literal> and 1681 <literal>run_kannel_box</literal> programs to use it as a daemon 1682 service (more documentation about that later).</para> 1683 1684 <para>If you cannot or do not know how to set up daemon systems or 1685 just want to test Kannel, you probably want to start it from 1686 command line. This means that you probably want to have one terminal 1687 window for each box you want to start (xterm or screen will do 1688 fine). To start the bearerbox, give the following command: 1689 1690 <screen><userinput> 1691 ./bearerbox -v 1 [config-file] 1692 </userinput></screen> 1693 1694 The <option>-v 1</option> sets the logging level to 1695 <literal>INFO</literal>. This way, you won't see a large amount of 1696 debugging output (the default is <literal>DEBUG</literal>). Full 1697 explanation of Kannel command line arguments is below.</para> 1698 1699 <para><emphasis>[config-file]</emphasis> is the name of the 1700 configuration file you are using with Kannel. The basic distribution 1701 packet comes with two sample configuration files, 1702 <literal>smskannel.conf</literal> and 1703 <literal>wapkannel.conf</literal> (in <literal>gw</literal> 1704 sub directory), of which the first one is for 1705 testing out SMS Kannel and the second one for setting up a WAP 1706 Kannel. Feel free to edit those configuration files to set up your 1707 own specialized system.</para> 1708 1709 <para>After the bearer box, you can start the WAP box: 1710 1711 <screen><userinput> 1712 ./wapbox -v 1 [config-file] 1713 </userinput></screen> 1714 1715 or the SMS box: 1716 1717 <screen><userinput> 1718 ./smsbox -v 1 [config-file] 1719 </userinput></screen> 1720 1721 or both, of course. The order does not matter, except that you need 1722 to start the bearer box before the other boxes. Without the bearer 1723 box, the other boxes won't even start.</para> 1724 1725</sect2> 1726 1727<sect2 id="arguments"> 1728<title id="arguments.title">Command line options</title> 1729 1730 <para>Bearerbox, smsbox and wapbox each accept certain command line options 1731 and arguments when they are launched. These arguments are:</para> 1732 1733 <table frame="none"> 1734 <title>Kannel Command Line Options</title> 1735 <tgroup cols="2"> 1736 <tbody> 1737 <row><entry><literal></literal></entry> 1738 <entry morerows="1" valign="bottom"> 1739 Print the version of the Kannel binary. 1740 </entry></row> 1741 <row><entry><literal>--version</literal></entry></row> 1742 1743 <row><entry><literal>-v <level></literal></entry> 1744 <entry morerows="1" valign="bottom"> 1745 Set verbosity level for stdout (screen) logging. Default is 0, 1746 which means 'debug'. 1 is 'info, 2 'warning', 3 1747 'error' and 4 'panic' 1748 </entry></row> 1749 <row><entry><literal>--verbosity <level></literal></entry></row> 1750 1751 <row><entry><literal>-D <places></literal></entry> 1752 <entry morerows="1" valign="bottom"> 1753 Set debug-places for 'debug' level output. 1754 </entry></row> 1755 <row><entry><literal>--debug <places></literal></entry></row> 1756 1757 <row><entry><literal>-F <file-name></literal></entry> 1758 <entry morerows="1" valign="bottom"> 1759 Log to file named file-name, too. Does not overrun or 1760 affect any log-file defined in configuration file. 1761 </entry></row> 1762 <row><entry><literal>--logfile <file-name></literal></entry></row> 1763 1764 <row><entry><literal>-V <level></literal></entry> 1765 <entry morerows="1" valign="bottom"> 1766 Set verbosity level for that extra log-file (default 0, 1767 which means 'debug'). Does not affect verbosity level of 1768 the log-file defined in configuration file, not verbosity 1769 level of the <literal>stdout</literal> output. 1770 </entry></row> 1771 <row><entry><literal>--fileverbosity <level></literal></entry></row> 1772 1773 <row><entry><literal>-S</literal></entry> 1774 <entry morerows="1" valign="bottom"> 1775 Start the system initially at SUSPENDED state (see below, 1776 bearerbox only) 1777 </entry></row> 1778 <row><entry><literal>--suspended</literal></entry></row> 1779 1780 <row><entry><literal>-I</literal></entry> 1781 <entry morerows="1" valign="bottom"> 1782 Start the system initially at ISOLATED state (see below, 1783 bearerbox only) 1784 </entry></row> 1785 <row><entry><literal>--isolated</literal></entry></row> 1786 1787 <row><entry><literal>-H</literal></entry> 1788 <entry morerows="1" valign="bottom"> 1789 Only try to open HTTP sendsms interface; if it 1790 fails, only warn about that, do not exit. (smsbox only) 1791 </entry></row> 1792 <row><entry><literal>--tryhttp</literal></entry></row> 1793 1794 <row><entry><literal>-g</literal></entry> 1795 <entry morerows="1" valign="bottom"> 1796 Dump all known config groups and config keys to stdout 1797 and exit. 1798 </entry></row> 1799 <row><entry><literal>--generate</literal></entry></row> 1800 1801 <row><entry><literal>-u <username></literal></entry> 1802 <entry morerows="1" valign="bottom"> 1803 Change process user-id to the given. 1804 </entry></row> 1805 <row><entry><literal>--user <username></literal></entry></row> 1806 1807 <row><entry><literal>-p <filename></literal></entry> 1808 <entry morerows="1" valign="bottom"> 1809 Write process PID to the given file. 1810 </entry></row> 1811 <row><entry><literal>--pid-file <filename></literal></entry></row> 1812 1813 <row><entry><literal>-d</literal></entry> 1814 <entry morerows="1" valign="bottom"> 1815 Start process as daemon (detached from a current shell session). 1816 Note: Process will change CWD (Current working directory) to <literal>/</literal>, 1817 therefore you should ensure that all paths to binary/config/config-includes are 1818 absolute instead of relative. 1819 </entry></row> 1820 <row><entry><literal>--daemonize</literal></entry></row> 1821 1822 <row><entry><literal>-P</literal></entry> 1823 <entry morerows="1" valign="bottom"> 1824 Start watcher process. This process watch a child process and if child process 1825 crashed will restart them automatically. 1826 </entry></row> 1827 <row><entry><literal>--parachute</literal></entry></row> 1828 1829 <row><entry><literal>-X <scriptname></literal></entry> 1830 <entry morerows="1" valign="bottom"> 1831 Execute a given shell script or binary when child process crash detected. This option 1832 is usable only with <literal>--parachute/-P</literal>. 1833 Script will be executed with 2 arguments: 1834 scriptname 'processname' 'respawn-count'. 1835 </entry></row> 1836 <row><entry><literal>--panic-script <scriptname></literal></entry></row> 1837 1838 </tbody> 1839 </tgroup> 1840 </table> 1841 1842</sect2> 1843 1844<sect2> 1845<title>Kannel statuses</title> 1846 1847 <para>In Kannel, there are four states for the program (which 1848 currently directly only apply to bearerbox):</para> 1849 1850 <orderedlist numeration="loweralpha"> 1851 <listitem><para> 1852 Running. The gateway accepts, proceeds and relies 1853 messages normally. This is the default state for the bearerbox. 1854 </para></listitem> 1855 <listitem><para> 1856 Suspended. The gateway does not accept any new messages from SMS 1857 centers nor from UDP ports. Neither does it accept new sms and wapbox 1858 connections nor sends any messages already in the system 1859 onward. 1860 1861 </para></listitem> 1862 <listitem><para> 1863 Isolated. In this state, the gateway does not accept any messages 1864 from external message providers, which means SMS Centers and UDP 1865 ports. It still processes any messages in the system and can 1866 accept new messages from sendsms interface in smsbox. 1867 </para></listitem> 1868 1869 <listitem><para> 1870 Full. Gateway does not accept any messages from SMS centers, because 1871 <literal>maximum-queue-length</literal> is achieved. 1872 </para></listitem> 1873 1874 <listitem><para> 1875 Shutdown. When the gateway is brought down, it does not accept any 1876 new messages from SMS centers and UDP ports, but processes all 1877 systems already in the system. As soon as any queues are emptied, 1878 the system exits 1879 1880 </para></listitem> 1881 </orderedlist> 1882 1883 <para> 1884The state can be changed via HTTP administration interface (see below), 1885and shutdown can also be initiated via TERM or INT signal from 1886terminal. In addition, the bearerbox can be started already in 1887suspended or isolated state with -S or -I command line option, see 1888above. 1889</para> 1890 1891</sect2> 1892 1893<sect2> 1894<title>HTTP administration</title> 1895 1896<para>Kannel can be controlled via an HTTP administration interface. All 1897commands are done as normal HTTP queries, so they can be easily done 1898from command line like this: 1899 1900 <screen><userinput> 1901 lynx -dump "http://localhost:12345/shutdown?password=bar" 1902 </userinput></screen> 1903 1904...in which the '12345' is the configured admin-port in Kannel 1905configuration file (see above). For most commands, admin-password is required as a 1906argument as shown above. In addition, HTTP administration can 1907be denied from certain IP addresses, as explained in configuration 1908chapter.</para> 1909 1910<para>Note that you can use these commands with WAP terminal, too, but 1911if you use it through the same Kannel, replies to various suspend 1912commands never arrive nor can you restart it via WAP anymore.</para> 1913 1914 <table frame="none"> 1915 <title>Kannel HTTP Administration Commands</title> 1916 <tgroup cols="2"> 1917 <tbody> 1918 <row><entry><literal>status or status.txt</literal></entry> 1919 <entry valign="bottom"> 1920 Get the current status of the gateway in a text version. Tells the current 1921 state (see above) and total number of messages relied and queuing 1922 in the system right now. Also lists the total number of smsbox 1923 and wapbox connections. No password required, unless 1924 <literal>status-password</literal> set, in which case either 1925 that or main admin password must be supplied. 1926 </entry></row> 1927 <row><entry><literal>status.html</literal></entry> 1928 <entry valign="bottom"> 1929 HTML version of status 1930 </entry></row> 1931 <row><entry><literal>status.xml</literal></entry> 1932 <entry valign="bottom"> 1933 XML version of status 1934 </entry></row> 1935 <row><entry><literal>status.wml</literal></entry> 1936 <entry valign="bottom"> 1937 WML version of status 1938 </entry></row> 1939 1940 <row><entry><literal>store-status or store-status.txt</literal></entry> 1941 <entry valign="bottom"> 1942 Get the current content of the store queue of the gateway 1943 in a text version. No password required, unless 1944 <literal>status-password</literal> set, in which case either 1945 that or main admin password must be supplied. 1946 </entry></row> 1947 <row><entry><literal>store-status.html</literal></entry> 1948 <entry valign="bottom"> 1949 HTML version of store-status 1950 </entry></row> 1951 <row><entry><literal>store-status.xml</literal></entry> 1952 <entry valign="bottom"> 1953 XML version of store-status 1954 </entry></row> 1955 1956 <row><entry><literal>suspend</literal></entry> 1957 <entry valign="bottom"> 1958 Set Kannel state as 'suspended' (see above). Password 1959 required. 1960 </entry></row> 1961 1962 <row><entry><literal>isolate</literal></entry> 1963 <entry valign="bottom"> 1964 Set Kannel state as 'isolated' (see above). Password required. 1965 </entry></row> 1966 1967 <row><entry><literal>resume</literal></entry> 1968 <entry valign="bottom"> 1969 Set Kannel state as 'running' if it is suspended or isolated. 1970 Password required. 1971 </entry></row> 1972 1973 <row><entry><literal>shutdown</literal></entry> 1974 <entry valign="bottom"> 1975 Bring down the gateway, by setting state to 'shutdown'. After 1976 a shutdown is initiated, there is no other chance to resume 1977 normal operation. However, 'status' command still works. 1978 Password required. If shutdown is sent for a second time, the 1979 gateway is forced down, even if it has still messages in 1980 queue. 1981 </entry></row> 1982 1983 <row><entry><literal>flush-dlr</literal></entry> 1984 <entry valign="bottom"> 1985 If Kannel state is 'suspended' this will flush all queued DLR 1986 messages in the current storage space. Password required. 1987 </entry></row> 1988 1989 <row><entry><literal>start-smsc</literal></entry> 1990 <entry valign="bottom"> 1991 Re-start a single SMSC link. Password required. Additionally 1992 the <literal>smsc</literal> parameter must be given to identify 1993 which <literal>smsc-admin-id</literal> should be re-started. 1994 The configuration for the SMSC link is re-read from disk before 1995 the action is performed. 1996 </entry></row> 1997 1998 <row><entry><literal>stop-smsc</literal></entry> 1999 <entry valign="bottom"> 2000 Shutdown a single SMSC link. Password required. Additionally 2001 the <literal>smsc</literal> parameter must be given (see above). 2002 </entry></row> 2003 2004 <row><entry><literal>add-smsc</literal></entry> 2005 <entry valign="bottom"> 2006 Adds an SMSC link previously removed or created after the service was 2007 started. Password required. Additionally the <literal>smsc</literal> 2008 parameter must be given (see above). 2009 </entry></row> 2010 2011 <row><entry><literal>remove-smsc</literal></entry> 2012 <entry valign="bottom"> 2013 Removes an existing SMSC link. Password required. Additionally the 2014 <literal>smsc</literal> parameter must be given (see above). If you 2015 want a permanent removal, you should also remove the entry from the 2016 configuration file or it will be recreated after a service restart. 2017 </entry></row> 2018 2019 <row><entry><literal>restart</literal></entry> 2020 <entry valign="bottom"> 2021 Re-start whole bearerbox, hence all SMSC links. Password required. 2022 Beware that you loose the smsbox connections in such a case. 2023 </entry></row> 2024 2025 <row><entry><literal>log-level</literal></entry> 2026 <entry valign="bottom"> 2027 Set Kannel log-level of log-files while running. This allows 2028 you to change the current log-level of the log-files on the fly. 2029 This includes the main event log and the SMSC specific logs, if 2030 any exist. 2031 </entry></row> 2032 2033 <row><entry><literal>reload-lists</literal></entry> 2034 <entry valign="bottom"> 2035 Re-loads the 'white-list' and 'black-list' URLs provided in the 2036 core group. This allows Kannel to keep running while the remote 2037 lists change and signal bearerbox to re-load them on the fly. 2038 </entry></row> 2039 2040 <row><entry><literal>remove-message</literal></entry> 2041 <entry valign="bottom"> 2042 Removes the message with the give <literal>id</literal> (an UUID) 2043 from the local storage subsystem. 2044 </entry></row> 2045 2046 </tbody> 2047 </tgroup> 2048 </table> 2049 2050</sect2> 2051 2052</sect1> 2053</chapter> 2054 2055 2056 2057<chapter id="wap-gateway"> 2058<title>Setting up a WAP gateway</title> 2059 2060 <para>This chapter tells you how to set Kannel up as a WAP 2061 gateway.</para> 2062 2063<sect1> 2064<title>WAP gateway configuration</title> 2065 2066 <para>To set up a WAP Kannel, you have to edit the 'core' group in the 2067 configuration file, and define the 'wapbox' group.</para> 2068 2069 <para>You must set following variables for the 'core' group: 2070 <literal>wapbox-port</literal> and 2071 <literal>wdp-interface-name</literal>. See previous chapter about 2072 details of these variables.</para> 2073 2074 <para>With standard distribution, a sample configuration file 2075 <literal>wapkannel.conf</literal> is supplied. You may want to take 2076 a look at that when setting up a WAP Kannel.</para> 2077 2078<sect2> 2079<title>Wapbox group</title> 2080 2081 <para>If you have set <literal>wapbox-port</literal> variable in the 2082 'core' configuration group, you <emphasis>MUST</emphasis> supply 2083 a 'wapbox' group.</para> 2084 2085 <para>The simplest working 'wapbox' group looks like this: 2086<programlisting> 2087group = wapbox 2088bearerbox-host = localhost 2089</programlisting> 2090 2091 There is, however, multiple optional variables for the 'wapbox' 2092 group.</para> 2093 2094 <table frame="none"> 2095 <title>Wapbox Group Variables</title> 2096 <tgroup cols="3"> 2097 <thead> 2098 <row> 2099 <entry>Variable</entry> 2100 <entry>Value</entry> 2101 <entry>Description</entry> 2102 </row> 2103 </thead> 2104 <tbody> 2105 <row><entry><literal>group (m)</literal></entry> 2106 <entry><literal>wapbox</literal></entry> 2107 <entry valign="bottom"> 2108 This is mandatory variable 2109 </entry></row> 2110 2111 <row><entry><literal>bearerbox-host (m)</literal></entry> 2112 <entry><literal>hostname</literal></entry> 2113 <entry valign="bottom"> 2114 The machine in which the bearerbox is. 2115 </entry></row> 2116 2117 <row><entry><literal>timer-freq</literal></entry> 2118 <entry>value-in-seconds</entry> 2119 <entry valign="bottom"> 2120 The frequency of how often timers are checked out. Default is 1 2121 </entry></row> 2122 2123 <row><entry><literal>http-interface-name</literal></entry> 2124 <entry>IP address</entry> 2125 <entry valign="bottom"> 2126 If this is set then Kannel do outgoing HTTP requests 2127 using this interface. 2128 </entry></row> 2129 2130 <row><entry><literal>map-url</literal></entry> 2131 <entry>URL-pair</entry> 2132 <entry valign="bottom"> 2133 The pair is separated with space. 2134 Adds a single mapping for the left side URL to the given destination. 2135 If you append an asterisk `*' to the left side URL, its prefix 2136 Is matched against the incoming URL. Whenever the prefix matches, 2137 the URL will be replaced completely by the right side. In addition, if if you append an asterisk to the right side URL, the part 2138 of the incoming URL coming after the prefix, will be appended 2139 to the right side URL. Thus, for a line: 2140 map-url = "http://source/* http://destination/*" 2141 and an incoming URL of "http://source/some/path", the result 2142 will be "http://destination/some/path" 2143 </entry></row> 2144 2145 <row><entry><literal>map-url-max</literal></entry> 2146 <entry>number</entry> 2147 <entry valign="bottom"> 2148 If you need more than one mapping, set this to the highest number 2149 mapping you need. The default gives you 10 mappings, numbered 2150 from 0 to 9. Default: 9 2151 </entry></row> 2152 2153 <row><entry><literal>map-url-0</literal></entry> 2154 <entry>URL-pair</entry> 2155 <entry valign="bottom"> 2156 Adds a mapping for the left side URL to the given destination URL. 2157 Repeat these lines, with 0 replaced by a number up to map-url-max, 2158 if you need several mappings. 2159 </entry></row> 2160 2161 <row><entry><literal>device-home</literal></entry> 2162 <entry>URL</entry> 2163 <entry valign="bottom"> 2164 Adds a mapping for the URL DEVICE:home (as sent by Phone.com browsers) 2165 to the given destination URL. There is no default mapping. 2166 NOTE: the mapping is added with both asterisks, as described above 2167 for the "map-url" setting. Thus, the above example line is 2168 equivalent to writing 2169 map-url = "DEVICE:home* http://some.where/*" 2170 2171 </entry></row> 2172 2173 <row><entry><literal>log-file</literal></entry> 2174 <entry>filename</entry> 2175 <entry morerows="1" valign="bottom"> 2176 As with bearerbox 'core' group. 2177 </entry></row> 2178 2179 <row><entry><literal>log-level</literal></entry> 2180 <entry>number 0..5</entry></row> 2181 2182 <row><entry><literal>access-log</literal></entry> 2183 <entry>filename</entry> 2184 <entry valign="bottom"> 2185 A file containing all requested URLs from clients while wapbox operation, 2186 including client IP, HTTP server User-Agent string, HTTP response code, 2187 size of reply. 2188 </entry></row> 2189 2190 <row><entry><literal>access-log-clean</literal></entry> 2191 <entry>boolean</entry> 2192 <entry valign="bottom"> 2193 Indicates if <literal>access-log</literal> will contain standard 'markers', 2194 which means the 'Log begins', 'Log ends' markers and the prefixed 2195 timestamp. This config directive should be set to 'true' if a custom 2196 logging format is desired without a prefixed default timestamp. 2197 </entry></row> 2198 2199 <row><entry><literal>access-log-time</literal></entry> 2200 <entry>string</entry> 2201 <entry valign="bottom"> 2202 Determine which timezone we use for access logging. Use 'gmt' for GMT time, 2203 anything else will use local time. Default is local time. 2204 </entry></row> 2205 2206 <row><entry><literal>syslog-level</literal></entry> 2207 <entry>number</entry> 2208 <entry valign="bottom"> 2209 Messages of this log level or higher will also be 2210 sent to syslog, the UNIX system log daemon. If not explicitly 2211 set with <literal>syslog-facility</literal>, it logs under the 2212 'daemon' category. The default is not to use syslog, and you can 2213 set that explicitly by setting <literal>syslog-level</literal> 2214 to 'none'. 2215 </entry></row> 2216 2217 <row><entry><literal>syslog-facility</literal></entry> 2218 <entry>string</entry> 2219 <entry valign="bottom"> 2220 The syslog facility to send the syslog entries to. The 2221 default is 'daemon'. 2222 </entry></row> 2223 2224 <row><entry><literal>smart-errors</literal></entry> 2225 <entry>bool</entry> 2226 <entry valign="bottom"> 2227 If set wapbox will return a valid WML deck describing the 2228 error that occurred while processing an WSP request. This may 2229 be used to have a smarter gateway and let the user know what 2230 happened actually. 2231 </entry></row> 2232 2233 <row><entry><literal>wml-strict</literal></entry> 2234 <entry>bool</entry> 2235 <entry valign="bottom"> 2236 If set wapbox will use a strict policy in XML parsing the WML 2237 deck. If not set it will be more relaxing and let the XML parser 2238 recover from parsing errors. This has mainly impacts in how smart 2239 the WML deck and it's character set encoding can be adopted, even 2240 while you used an encoding that does not fit the XML preamble. 2241 BEWARE: This may be a vulnerability in your wapbox for large bogus 2242 WML input. Therefore this defaults to 'yes', strict parsing. 2243 is assumed. 2244 </entry></row> 2245 2246 <row><entry><literal>http-timeout</literal></entry> 2247 <entry>seconds</entry> 2248 <entry valign="bottom"> 2249 Sets socket timeout in seconds for outgoing client http 2250 connections. Optional. Defaults to 240 seconds. 2251 </entry></row> 2252 </tbody> 2253 </tgroup> 2254 </table> 2255 2256<programlisting> 2257</programlisting> 2258</sect2> 2259 2260</sect1> 2261 2262<sect1> 2263<title>Running WAP gateway</title> 2264 2265 <para>WAP Gateway is ran as explained in previous chapter.</para> 2266 2267</sect1> 2268 2269 2270<sect1> 2271<title>Checking whether the WAP gateway is alive</title> 2272 2273 <para>You can check whether the WAP gateway (both the 2274 bearerbox and the wapbox) is alive by fetching the URL 2275 <literal>kannel:alive</literal>.</para> 2276 2277</sect1> 2278 2279</chapter> 2280 2281 2282<chapter id="wtls"> 2283<title>Setting up wtls security</title> 2284 2285 <para>This chapter tells you how to set Kannel up to handle wtls traffic. 2286 </para> 2287 2288 <para><literal>wtls</literal> group is optional and single. The prerequisites for this group 2289 are to have defined a wapbox group, and a pair of SSL certificates 2290 available. Instructions on how to create self-signed 1024-bit RSA 2291 certificates are in <xref linkend="certificates"/>. 2292 </para> 2293 <para>Current imlementation provides for the following functionality:</para> 2294 <para> 2295 <orderedlist numeration="upperalpha"> 2296 <listitem><para>Supported MACs:</para> 2297 <itemizedlist> 2298 <listitem><para>SHA_0</para></listitem> 2299 <listitem><para>SHA_40</para></listitem> 2300 <listitem><para>SHA_80</para></listitem> 2301 <listitem><para>SHA_NOLIMIT</para></listitem> 2302 <listitem><para>MD5_40</para></listitem> 2303 <listitem><para>MD5_80</para></listitem> 2304 <listitem><para>MD5_NOLIMIT</para></listitem> 2305 </itemizedlist> 2306 <para>Missing:</para> 2307 <itemizedlist> 2308 <listitem><para>SHA_XOR_40</para></listitem> 2309 </itemizedlist> 2310 </listitem> 2311 <listitem><para>Supported Ciphers:</para> 2312 <itemizedlist> 2313 <listitem><para>RC5_CBC_40</para></listitem> 2314 <listitem><para>RC5_CBC_56</para></listitem> 2315 <listitem><para>RC5_CBC</para></listitem> 2316 <listitem><para>DES_CBC</para></listitem> 2317 <listitem><para>DES_CBC_40</para></listitem> 2318 </itemizedlist> 2319 <para>Missing:</para> 2320 <itemizedlist> 2321 <listitem><para>NULL_bulk</para></listitem> 2322 <listitem><para>TRIPLE_DES_CBC_EDE</para></listitem> 2323 <listitem><para>IDEA_CBC_40</para></listitem> 2324 <listitem><para>IDEA_CBC_56</para></listitem> 2325 <listitem><para>IDEA_CBC</para></listitem> 2326 </itemizedlist> 2327 </listitem> 2328 <listitem><para>Supported Keys:</para> 2329 <itemizedlist> 2330 <listitem><para>RSA_anon</para></listitem> 2331 </itemizedlist> 2332 <para>Missing:</para> 2333 <itemizedlist> 2334 <listitem><para>RSA_anon_512</para></listitem> 2335 <listitem><para>RSA_anon_768</para></listitem> 2336 <listitem><para>RSA_NOLIMIT</para></listitem> 2337 <listitem><para>RSA_512</para></listitem> 2338 <listitem><para>RSA_768</para></listitem> 2339 <listitem><para>ECDH_anon</para></listitem> 2340 <listitem><para>ECDH_anon_113</para></listitem> 2341 <listitem><para>ECDH_anon_131</para></listitem> 2342 <listitem><para>ECDH_ECDSA_NOLIMIT</para></listitem> 2343 </itemizedlist> 2344 <para>Keys might seem a shortcoming, but all mobiles support 2345 RSA_anon. Some of the other RSA_anon keys (i.e. RSA_anon_512, 2346 RSA_anon_768) are propably supported as well, just haven't been 2347 tested yet.</para> 2348 </listitem> 2349 <listitem><para>All wtls states except:</para> 2350 <itemizedlist> 2351 <listitem><para>Suspend/Resume wtls session</para></listitem> 2352 <listitem><para>Cipher change when already connected. In practice 2353 this is handled through another client hello, while 2354 already connected to the same client</para></listitem> 2355 </itemizedlist> 2356 </listitem> 2357 </orderedlist></para> 2358 2359 <para>The simplest working <literal>wtls</literal> group looks like this: 2360<programlisting> 2361group = wtls 2362certificate-file = /etc/kannel/server.crt 2363privatekey-file = /etc/kannel/server.key 2364</programlisting> 2365 2366 Can also be the same single combined pem file with both certificate and 2367 privatekey parts. The complete variable list for the <literal>wtls</literal> group is:</para> 2368 2369<sect1> 2370<title>Wtls configuration</title> 2371 <table frame="none"> 2372 <title>Wtls Group Variables</title> 2373 <tgroup cols="3"> 2374 <thead> 2375 <row> 2376 <entry>Variable</entry> 2377 <entry>Value</entry> 2378 <entry>Description</entry> 2379 </row> 2380 </thead> 2381 <tbody> 2382 <row><entry><literal>group (m)</literal></entry> 2383 <entry><literal>wtls</literal></entry> 2384 <entry valign="bottom"> 2385 This is mandatory variable 2386 </entry></row> 2387 2388 <row><entry><literal>certificate-file (m)</literal></entry> 2389 <entry><literal>filename</literal></entry> 2390 <entry valign="bottom"> 2391 Public key SSL certificate. 2392 </entry></row> 2393 2394 <row><entry><literal>privatekey-file (m)</literal></entry> 2395 <entry><literal>filename</literal></entry> 2396 <entry valign="bottom"> 2397 Private key SSL certificate. 2398 </entry></row> 2399 2400 <row><entry><literal>privatekey-password (o)</literal></entry> 2401 <entry><literal>Phrase</literal></entry> 2402 <entry valign="bottom"> 2403 Optional. Needed only if private key was created with a passphrase. 2404 </entry></row> 2405 </tbody> 2406 </tgroup> 2407 </table> 2408</sect1> 2409</chapter> 2410 2411<chapter id="msisdn-provisioning"> 2412<title>Setting up MSISDN provisioning for WAP gateway</title> 2413 2414 <para>This chapter tells you how to set Kannel up to deliver the MSISDN 2415 number of the WAP device using the WAP gateway.</para> 2416 2417 <para>Mostly this feature is interested because the WAP protocol stack 2418 itself does not provide such a protocol layer bridging of information. 2419 In case you want to know which unique MSISDN is used by the WAP device 2420 your HTTP application is currently interacting, then you can pick this 2421 information from a RADIUS server that is used by a NAS (network access 2422 server) for authentication and accounting purposes. 2423 </para> 2424 2425 <para>Kannel provides a RADIUS accounting proxy thread inside wapbox 2426 which holds a mapping table for the dynamically assigned (DHCP) IP 2427 addresses of the WAP clients and their MSISDN numbers provided to the 2428 NAS device. 2429 </para> 2430 2431 <para>Beware that you <emphasis>HAVE TO</emphasis> to be in control of 2432 the NAS to configure it to use Kannel's wapbox as RADIUS accounting 2433 server. You can not use 2434 MSISDN provisioning via Kannel's RADIUS accounting proxy if you can 2435 not forward the accounting packets to Kannel's accounting proxy thread. 2436 So obviously this feature is for operators and people who have dedicated 2437 dial-in servers (NAS). 2438 </para> 2439 2440<sect1> 2441<title>RADIUS accounting proxy configuration</title> 2442 2443 <para>To set up the RADIUS accounting proxy thread inside Kannel you 2444 have to define a 'radius-acct' group.</para> 2445 2446<sect2> 2447<title>RADIUS-Acct configuration</title> 2448 2449 <para>The simplest working 'radius-acct' group looks like this: 2450<programlisting> 2451group = radius-acct 2452our-port = 1646 2453secret-nas = radius 2454</programlisting> 2455 2456 This example does not forward any accounting packets to a remote 2457 RADIUS server. There is, however, multiple optional variables for 2458 the 'radius-acct' group.</para> 2459 2460 <table frame="none"> 2461 <title>RADIUS-Acct Group Variables</title> 2462 <tgroup cols="3"> 2463 <thead> 2464 <row> 2465 <entry>Variable</entry> 2466 <entry>Value</entry> 2467 <entry>Description</entry> 2468 </row> 2469 </thead> 2470 <tbody> 2471 <row><entry><literal>group (m)</literal></entry> 2472 <entry><literal>radius-acct</literal></entry> 2473 <entry valign="bottom"> 2474 This is mandatory variable if you want to have Kannel's 2475 RADIUS accounting proxy thread to be active inside wapbox. 2476 </entry></row> 2477 2478 <row><entry><literal>secret-nas (m)</literal></entry> 2479 <entry><literal>string</literal></entry> 2480 <entry valign="bottom"> 2481 Specifies the shared secret between NAS and our RADIUS accounting proxy. 2482 </entry></row> 2483 2484 <row><entry><literal>secret-radius</literal></entry> 2485 <entry><literal>string</literal></entry> 2486 <entry valign="bottom"> 2487 Specifies the shared secret between our RADIUS accounting proxy and the 2488 remote RADIUS server itself in case we are forwarding packets. 2489 </entry></row> 2490 2491 <row><entry><literal>our-host</literal></entry> 2492 <entry><literal>IP address</literal></entry> 2493 <entry valign="bottom"> 2494 Specifies the local interface where our-port value will bind 2495 to. (defaults to 0.0.0.0) 2496 </entry></row> 2497 2498 <row><entry><literal>remote-host</literal></entry> 2499 <entry><literal>FQDN or IP address</literal></entry> 2500 <entry valign="bottom"> 2501 Specifies the remote RADIUS server to which we forward the 2502 accounting packets. If none is given, then no forwarding of 2503 accounting packets is performed. 2504 </entry></row> 2505 2506 <row><entry><literal>our-port</literal></entry> 2507 <entry><literal>number</literal></entry> 2508 <entry valign="bottom"> 2509 Specifies the port to which our RADIUS accounting proxy thread 2510 will listen to. (defaults according to RFC2866 to 1813) 2511 </entry></row> 2512 2513 <row><entry><literal>remote-port</literal></entry> 2514 <entry><literal>number</literal></entry> 2515 <entry valign="bottom"> 2516 Specifies the port to which our RADIUS accounting proxy thread 2517 will forward any packets to the remote-host. 2518 (defaults according to RFC2866 to 1813) 2519 </entry></row> 2520 2521 <row><entry><literal>remote-timeout</literal></entry> 2522 <entry><literal>number</literal></entry> 2523 <entry valign="bottom"> 2524 Specifies the timeout value in milliseconds for waiting on a 2525 response from the remote RADIUS server. 2526 (defaults to 40 msecs.) 2527 </entry></row> 2528 2529 <row><entry><literal>nas-ports</literal></entry> 2530 <entry><literal>number</literal></entry> 2531 <entry valign="bottom"> 2532 Specifies how many possible clients can connect simultaneously 2533 to the NAS. This value is used to initialize the mapping hash table. 2534 If does not require to be exact, because the table grows automatically 2535 if required. (defaults to 30) 2536 </entry></row> 2537 2538 <row><entry><literal>unified-prefix</literal></entry> 2539 <entry>prefix-list</entry> 2540 <entry valign="bottom"> 2541 String to unify provided phone numbers from NAS. 2542 Format is that first comes the 2543 unified prefix, then all prefixes which are replaced by the 2544 unified prefix, separated with comma (','). For example, 2545 for Finland an unified-prefix "+358,00358,0;+,00" should do the trick. 2546 If there are several unified prefixes, separate their rules with 2547 semicolon (';'), like "+35850,050;+35840,040". 2548 </entry></row> 2549 2550 </tbody> 2551 </tgroup> 2552 </table> 2553<programlisting> 2554</programlisting> 2555 2556</sect2> 2557<sect2> 2558<title>Using the MSISDN provisioning on HTTP server side</title> 2559 2560 <para>Kannel's wapbox will include a specific HTTP header in the HTTP 2561 request issued to the URL provided by the WAP client. That HTTP header 2562 is <literal>X-WAP-Network-Client-MSISDN</literal>. It will carry as value 2563 the MSISDN of the WAP client if the RADIUS accounting proxy has received 2564 a valid accounting packet from the NAS that provided the client IP. 2565 </para> 2566 2567</sect2> 2568</sect1> 2569</chapter> 2570 2571 2572 2573<chapter id="sms-gateway"> 2574<title>Setting up a SMS Gateway</title> 2575 2576 <para>This chapter is a more detailed guide on how to set up Kannel as an 2577 SMS gateway.</para> 2578 2579<sect1> 2580<title>Required components</title> 2581 2582 <para>To set up an SMS gateway, you need, in addition to a machine 2583 running Kannel, access to (an operator's) SMS center, or possibly 2584 to multiple ones. The list of supported SMS centers and their 2585 configuration variables is below.</para> 2586 2587 <para>If you do not have such access, you can still 2588 use Kannel as an SMS gateway via <emphasis>phone-as-SMSC</emphasis> 2589 feature, by using a GSM phone as a virtual SMS center.</para> 2590 2591 <para>In addition to an SMS center (real or virtual), you need some 2592 server to handle any SMS requests received. This server then has 2593 simple or more complex cgi-bins, programs or scripts to serve HTTP 2594 requests generated by Kannel in response to received SMS 2595 messages. These services can also initiate SMS push via Kannel 2596 smsbox HTTP sendsms interface.</para> 2597 2598</sect1> 2599 2600<sect1> 2601<title>SMS gateway configuration</title> 2602 2603 <para>To set up a SMS Kannel, you have to edit the 'core' group in the 2604 configuration file, and define an 'smsbox' group plus one or more 2605 'sms-service' groups, plus possibly one or more 'sendsms-user' groups.</para> 2606 2607 <para>For the 'core' group, you must set the following variable: 2608 <literal>smsbox-port</literal>. In addition, you may be interested 2609 to set <literal>unified-prefix</literal>, 2610 <literal>white-list</literal> and/or <literal>black-list</literal> 2611 variables. See above for details of these variables.</para> 2612 2613 <para> A sample configuration file <literal>smskannel.conf</literal> 2614 is supplied with the standard distribution. You may want to take 2615 a look at that when setting up an SMS Kannel.</para> 2616</sect1> 2617 2618<sect1> 2619<title>SMS centers</title> 2620 2621 <para>To set up the SMS center at Kannel, you have to add a 'smsc' 2622 group into configuration file. 2623 This group must include all the data needed to connect 2624 that SMS center. You may also want to define an ID 2625 (identification) name for the SMSC, for logging and routing 2626 purposes.</para> 2627 2628 <para>SMSC ID is an abstract name for the connection. It can be 2629 anything you like, but you should avoid any special 2630 characters. You do not need to use ID, but rely on SMS center IP 2631 address and other information. However, if you use the ID, you do 2632 not need to re-define sms-services nor routing systems if the IP 2633 of the SMS Center is changed, for example.</para> 2634 2635 <para>Common 'smsc' group variables are defined in the following 2636 table. The first two (<literal>group</literal> and 2637 <literal>smsc</literal>) are mandatory, but rest can be used if 2638 needed.</para> 2639 2640 <table frame="none"> 2641 <title>SMSC Group Variables</title> 2642 <tgroup cols="3"> 2643 <thead> 2644 <row> 2645 <entry>Variable</entry> 2646 <entry>Value</entry> 2647 <entry>Description</entry> 2648 </row> 2649 </thead> 2650 <tbody> 2651 <row><entry><literal>group (m)</literal></entry> 2652 <entry><literal>smsc</literal></entry> 2653 <entry valign="bottom"> 2654 This is a mandatory variable 2655 </entry></row> 2656 2657 <row><entry><literal>smsc (m)</literal></entry> 2658 <entry><literal>string</literal></entry> 2659 <entry valign="bottom"> 2660 Identifies the SMS center type. See below 2661 for a complete list. 2662 </entry></row> 2663 2664 2665 <row><entry><literal>smsc-id</literal></entry> 2666 <entry><literal>string</literal></entry> 2667 <entry valign="bottom"> 2668 An optional name or id for the smsc. Any string is 2669 acceptable, but semicolon ';' may cause problems, so avoid 2670 it and any other special non-alphabet characters. 2671 This 'id' is written into log files and can be used to 2672 route SMS messages, and to specify the used SMS-service. 2673 Several SMSCs can have the same id. The name is 2674 case-insensitive. Note that if SMS Center connection has an 2675 assigned SMSC ID, it does NOT automatically mean that messages 2676 with identical SMSC ID are routed to it; instead configuration 2677 variables <literal>denied-smsc-id</literal>, 2678 <literal>allowed-smsc-id</literal> and 2679 <literal>preferred-smsc-id</literal> is used for that. 2680 If you want to use Delivery Reports, you must define this. 2681 2682 </entry></row> 2683 2684 <row><entry><literal>smsc-admin-id</literal></entry> 2685 <entry><literal>string</literal></entry> 2686 <entry valign="bottom"> 2687 An optional id for the smsc to be used on administrative 2688 commands. This allows commands targeted to individual binds 2689 even if they share the same <literal>smsc-id</literal> 2690 (for load balancing scenarios, for example). Any string is 2691 acceptable, but semicolon ';' may cause problems, so avoid 2692 it and any other special non-alphabet characters. 2693 Several SMSCs can have the same admin-id, though it's not 2694 recommended. The name is case-insensitive. 2695 </entry></row> 2696 2697 <row><entry><literal>throughput</literal></entry> 2698 <entry><literal>float (messages/sec)</literal></entry> 2699 <entry valign="bottom"> 2700 If SMSC requires that Kannel limits the number of messages per second, 2701 use this variable. This is considered as active throttling. (optional) 2702 </entry></row> 2703 2704 <row><entry><literal>denied-smsc-id</literal></entry> 2705 <entry><literal>id-list</literal></entry> 2706 <entry valign="bottom"> 2707 SMS messages with SMSC ID equal to any of the IDs in this list 2708 are never routed to this SMSC. Multiple entries are separated 2709 with semicolons (';') 2710 </entry></row> 2711 2712 <row><entry><literal>allowed-smsc-id</literal></entry> 2713 <entry><literal>id-list</literal></entry> 2714 <entry valign="bottom"> 2715 This list is opposite to previous: only SMS messages with SMSC 2716 ID in this list are ever routed to this SMSC. 2717 Multiple entries are separated with semicolons (';') 2718 </entry></row> 2719 2720 <row><entry><literal>preferred-smsc-id</literal></entry> 2721 <entry><literal>id-list</literal></entry> 2722 <entry valign="bottom"> 2723 SMS messages with SMSC ID from this list are sent to this SMSC 2724 instead than to SMSC without that ID as preferred. Multiple 2725 entries are separated with semicolons (';') 2726 </entry></row> 2727 2728 <row><entry><literal>allowed-prefix</literal></entry> 2729 <entry><literal>prefix-list</literal></entry> 2730 <entry valign="bottom"> 2731 A list of phone number prefixes which are accepted to be 2732 sent through this SMSC. Multiple entries are separated with 2733 semicolon (';'). For example, "040;050" prevents sending of 2734 any SMS message with prefix of 040 or 050 through this SMSC. 2735 If denied-prefix is unset, only these numbers are allowed. If 2736 set, number are allowed if present in allowed or not in 2737 denied list. 2738 </entry></row> 2739 2740 <row><entry><literal>denied-prefix</literal></entry> 2741 <entry><literal>prefix-list</literal></entry> 2742 <entry valign="bottom"> 2743 A list of phone number prefixes which are NOT accepted to be 2744 sent through this SMSC. 2745 </entry></row> 2746 2747 <row><entry><literal>preferred-prefix</literal></entry> 2748 <entry><literal>prefix-list</literal></entry> 2749 <entry valign="bottom"> 2750 As <literal>denied-prefix</literal>, but SMS messages with receiver starting 2751 with any of these prefixes are preferably sent through this 2752 SMSC. In a case of multiple preferences, one is selected at random 2753 (also if there are preferences, SMSC is selected randomly) 2754 2755 </entry></row> 2756 2757 <row><entry><literal>unified-prefix</literal></entry> 2758 <entry>prefix-list</entry> 2759 <entry valign="bottom"> 2760 String to unify received phone numbers, for SMSC routing and 2761 to ensure that SMS centers can handle them properly. 2762 This is applied to 'sender' number when receiving SMS 2763 messages from SMS Center and for 'receiver' number when 2764 receiving messages from smsbox (either sendsms message or 2765 reply to original message). Format is that first comes the 2766 unified prefix, then all prefixes which are replaced by the 2767 unified prefix, separated with comma (','). For example, 2768 for Finland an unified-prefix "+358,00358,0;+,00" should do the trick. 2769 If there are several unified prefixes, separate their rules with 2770 semicolon (';'), like "+35850,050;+35840,040". <emphasis>Note 2771 that prefix routing is next to useless now that there are 2772 SMSC ID entries. To remove prefixes, use like 2773 "-,+35850,050;-,+35840,040". 2774 </emphasis> 2775 </entry></row> 2776 2777 <row><entry><literal>alt-charset</literal></entry> 2778 <entry><literal>number</literal></entry> 2779 <entry valign="bottom"> 2780 As some SMS Centers do not follow the standards in character 2781 coding, an <literal>alt-charset</literal> character conversion is 2782 presented. This directive acts different for specific SMSC types. 2783 Please see your SMSC module type you want to use for more details. 2784 </entry></row> 2785 2786 <row><entry><literal>alt-dcs</literal></entry> 2787 <entry><literal>boolean</literal></entry> 2788 <entry valign="bottom"> 2789 Optional data coding scheme value usage. Sets the 'alt-dcs' value 2790 for the sendsms HTTP interface to a fixed value for each SMS sent 2791 via this SMSC connection. 2792 If equals to yes, uses FX. If equals to no (default), uses 0X. 2793 </entry></row> 2794 2795 <row><entry><literal>our-host</literal></entry> 2796 <entry><literal>hostname</literal></entry> 2797 <entry valign="bottom"> 2798 Optional hostname or IP address in which to bind the connection in our 2799 end. TCP/IP connection only. 2800 </entry></row> 2801 2802 <row><entry><literal>log-file</literal></entry> 2803 <entry>filename</entry> 2804 <entry valign="bottom"> 2805 A file in which to write a log of the given smsc output. Hence 2806 this allows to log smsc specific entries to a separate file. 2807 </entry></row> 2808 2809 <row><entry><literal>log-level</literal></entry> 2810 <entry>number 0..5</entry> 2811 <entry valign="bottom"> 2812 Minimum level of log-file events logged. 0 is for 'debug', 1 2813 'info', 2 'warning, 3 'error' and 4 'panic' (see Command Line 2814 Options) 2815 </entry></row> 2816 2817 <row><entry><literal>reconnect-delay</literal></entry> 2818 <entry><literal>number</literal></entry> 2819 <entry valign="bottom"> 2820 Number of seconds to wait between single re-connection attempts. 2821 Hence all SMSC modules should use this value for their 2822 re-connect behavior. (Defaults to '10' seconds). 2823 </entry></row> 2824 2825 <row><entry><literal>reroute</literal></entry> 2826 <entry><literal>boolean</literal></entry> 2827 <entry valign="bottom"> 2828 If set for a smsc group, all inbound messages coming from this smsc 2829 connection are passed internally to the outbound routing functions. 2830 Hence this messages is not delivered to any connected box for 2831 processing. It is passed to the bearerbox routing as if it would 2832 have originated from an externally connected smsbox. 2833 (Defaults to 'no'). 2834 </entry></row> 2835 2836 <row><entry><literal>reroute-smsc-id</literal></entry> 2837 <entry><literal>string</literal></entry> 2838 <entry valign="bottom"> 2839 Similar to 'reroute'. Defines the explicit smsc-id 2840 the MO message should be passed to for MT traffic. Hence all 2841 messages coming from the the configuration group smsc are passed 2842 to the outbound queue of the specified smsc-id. This allows 2843 direct proxying of messages between 2 smsc connections without 2844 injecting them to the general routing procedure in bearerbox. 2845 </entry></row> 2846 2847 <row><entry><literal>reroute-receiver</literal></entry> 2848 <entry><literal>string</literal></entry> 2849 <entry valign="bottom"> 2850 Similar to 'reroute'. Defines the explicit smsc-id routes 2851 for specific receiver numbers of messages that are coming from this 2852 smsc connection. 2853 Format is that first comes the smsc-id to route the message to, then 2854 all receiver numbers that should be routed, separated with comma (','). 2855 For example, route receivers 111 and 222 to smsc-id A and 333 and 444 2856 to smsc-id B would look like: "A,111,222; B,333,444". 2857 </entry></row> 2858 2859 <row><entry><literal>reroute-dlr</literal></entry> 2860 <entry><literal>boolean</literal></entry> 2861 <entry valign="bottom"> 2862 Indicate whether DLR's should be re-routed too, if one of above reroute 2863 rules are enabled. Please note, that SMSC-Module should support DLR sending. 2864 At time of writing none of SMSC-Module supports DLR sending. 2865 </entry></row> 2866 2867 <row><entry><literal>allowed-smsc-id-regex</literal></entry> 2868 <entry>POSIX regular expression</entry> 2869 <entry valign="bottom"> 2870 SMS messages with SMSC ID equal to any of the IDs in this set of SMSC IDs 2871 are always routed to this SMSC. 2872 See section on <xref linkend="regular-expressions"/> for details. 2873 </entry> 2874 </row> 2875 2876 <row><entry><literal>denied-smsc-id-regex</literal></entry> 2877 <entry>POSIX regular expression</entry> 2878 <entry valign="bottom"> 2879 SMS messages with SMSC ID equal to any of the IDs in this set of SMSC IDs 2880 are never routed to this SMSC. 2881 See section on <xref linkend="regular-expressions"/> for details. 2882 </entry> 2883 </row> 2884 2885 <row><entry><literal>preferred-smsc-id-regex</literal></entry> 2886 <entry>POSIX regular expression</entry> 2887 <entry valign="bottom"> 2888 SMS messages with SMSC ID in this set of SMSC IDs are sent to this SMSC 2889 as preferred. 2890 See section on <xref linkend="regular-expressions"/> for details. 2891 </entry> 2892 </row> 2893 2894 <row><entry><literal>allowed-prefix-regex</literal></entry> 2895 <entry>POSIX regular expression</entry> 2896 <entry valign="bottom"> 2897 A set of phone number prefixes which are accepted to be 2898 sent through this SMSC. 2899 See section on <xref linkend="regular-expressions"/> for details. 2900 </entry> 2901 </row> 2902 2903 <row><entry><literal>denied-prefix-regex</literal></entry> 2904 <entry>POSIX regular expression</entry> 2905 <entry valign="bottom"> 2906 A set of phone number prefixes which may not be 2907 sent through this SMSC. 2908 See section on <xref linkend="regular-expressions"/> for details. 2909 </entry> 2910 </row> 2911 2912 <row><entry><literal>preferred-prefix-regex</literal></entry> 2913 <entry>POSIX regular expression</entry> 2914 <entry valign="bottom"> 2915 As <literal>denied-prefix-regex</literal>, but SMS messages with receiver matching 2916 any of these prefixes are preferably sent through this 2917 SMSC. In a case of multiple preferences, one is selected at random. 2918 See section on <xref linkend="regular-expressions"/> for details. 2919 </entry> 2920 </row> 2921 2922 <row><entry><literal>max-sms-octets</literal></entry> 2923 <entry>number</entry> 2924 <entry valign="bottom"> 2925 Maximum allowed octets for this SMSC. If this maximum exceeds Kannel will split 2926 SMS into multiparts. 2927 Default: 140 2928 </entry> 2929 </row> 2930 2931 <row><entry><literal>dead-start</literal></entry> 2932 <entry><literal>boolean</literal></entry> 2933 <entry valign="bottom"> 2934 Optional, defines if the SMSC connection type is started in disconnected mode (dead). 2935 This allows SMSC to be connected at a later time with the add-smsc HTTP administration command. 2936 If set to 'true' the connection will start as 'dead' and will require a start-smsc command 2937 to activate it. Defaults to 'false' if not present.</entry> 2938 </row> 2939 2940 </tbody> 2941 </tgroup> 2942 </table> 2943 2944 <para>In addition to these common variables there are several 2945 variables used by certain SMS center connections. Each currently 2946 supported SMS center type is explained below, with configuration 2947 group for each. Note that many of them use variables with same 2948 name, but most also have some specific variables.</para> 2949 2950 <para><emphasis>NOTE: SMS center configuration variables are a bit 2951 incomplete, and will be updated as soon as people responsible for 2952 the protocols are contacted. Meanwhile, please have 2953 patience.</emphasis></para> 2954 2955 2956<sect2> 2957<title>Nokia CIMD 1.37 and 2.0</title> 2958 2959<para>Support for CIMD 1.37 is quite old and will be removed in a 2960future version of Kannel. Please let us know if you still need it.</para> 2961 2962<programlisting> 2963group = smsc 2964smsc = cimd 2965host = 100.101.102.103 2966port = 600 2967smsc-username = foo 2968smsc-password = bar 2969</programlisting> 2970 2971<para>The driver for CIMD2 is a "receiving SME" and expects the SMSC 2972to be configured for that. It also expects the SMSC to automatically 2973send stored messages as soon as Kannel logs in (this is the normal 2974configuration).</para> 2975 2976<programlisting> 2977group = smsc 2978smsc = cimd2 2979host = 100.101.102.103 2980port = 600 2981smsc-username = foo 2982smsc-password = bar 2983keepalive = 5 2984my-number = "12345" 2985</programlisting> 2986 2987 <informaltable frame="none"> 2988 <tgroup cols="3"><thead><row> 2989 <entry>Variable</entry> 2990 <entry>Value</entry> 2991 <entry>Description</entry> 2992 </row></thead><tbody> 2993 2994 <row><entry><literal>host (m)</literal></entry> 2995 <entry><literal>hostname</literal></entry> 2996 <entry valign="bottom"> 2997 Machine that runs the SMSC. As IP (100.100.100.100) 2998 or hostname (their.machine.here) 2999 </entry></row> 3000 3001 <row><entry><literal>port (m)</literal></entry> 3002 <entry><literal>port-number</literal></entry> 3003 <entry valign="bottom"> 3004 Port number in the smsc host machine 3005 </entry></row> 3006 3007 <row><entry><literal>smsc-username (m)</literal></entry> 3008 <entry><literal>string</literal></entry> 3009 <entry valign="bottom"> 3010 Username in the SMSC machine/connection account 3011 </entry></row> 3012 3013 <row><entry><literal>smsc-password (m)</literal></entry> 3014 <entry><literal>string</literal></entry> 3015 <entry valign="bottom"> 3016 Password in the SMSC machine needed to contact SMSC 3017 </entry></row> 3018 3019 <row><entry><literal>keepalive</literal></entry> 3020 <entry><literal>number</literal></entry> 3021 <entry valign="bottom"> 3022 SMSC connection will not be left idle for longer than this many 3023 seconds. The right value to use depends on how eager the SMSC 3024 is to close idle connections. If you see many unexplained 3025 reconnects, try lowering this value. 3026 Set it to 0 to disable this feature. 3027 </entry></row> 3028 3029 <row><entry><literal>no-dlr</literal></entry> 3030 <entry><literal>boolean</literal></entry> 3031 <entry valign="bottom"> 3032 Optional. If defined, status delivery report requests (DLR) won't be 3033 requested at all. Some CIMD2 SMSC have prohibited these reports so 3034 if you are getting error like "Incorrect status report request parameter 3035 usage", this option is for you. Defaults to "false". 3036 </entry></row> 3037 3038 <row><entry><literal>my-number</literal></entry> 3039 <entry><literal>string</literal></entry> 3040 <entry valign="bottom"> 3041 The number that the SMSC will add in front of the sender number 3042 of all messages sent from Kannel. If Kannel is asked to send 3043 a message, it will remove this prefix from the sender number 3044 so that the SMSC will add it again. If the prefix was not present, 3045 Kannel will log a warning and will not send the sender number. 3046 If <literal>my-number</literal> is not set, or is set 3047 to <literal>"never"</literal>, then Kannel will not send the 3048 sender number to the SMSC at all. 3049 If you want Kannel to pass all sender numbers to the SMSC 3050 unchanged, then just set <literal>sender-prefix</literal> to the 3051 empty string <literal>""</literal>. 3052 </entry></row> 3053 3054 <row><entry><literal>our-port</literal></entry> 3055 <entry><literal>port-number</literal></entry> 3056 <entry valign="bottom"> 3057 Optional port number in which to bind the connection in our 3058 end. 3059 </entry></row> 3060 3061 </tbody></tgroup></informaltable> 3062 3063</sect2> 3064 3065<sect2> 3066<title>CMG UCP/EMI 4.0 and 3.5</title> 3067 3068 <warning><para>See <xref linkend="upgrading-notes"/> for changes.</para></warning> 3069 <para>Kannel supports two types of connections with CMG SMS centers: 3070 direct TCP/IP connections ( <literal>emi</literal>) and ISDN/modem 3071 (X.25) connection (<literal>emi_x25</literal>).</para> 3072 <note><para><literal>emi_x25</literal> is an old implementation and supports less 3073 features than it's IP counterpart. If you still need this module, please tell 3074 us to <literal>devel@kannel.org</literal> so we can fix it.</para></note> 3075 <para>Sample configurations for these are:</para> 3076 3077<programlisting> 3078group = smsc 3079smsc = emi 3080host = 103.102.101.100 3081port = 6000 3082smsc-username = foo 3083smsc-password = bar 3084keepalive = 55 3085our-port = 600 (optional bind in our end) 3086receive-port = 700 (the port in which the SMSC will contact) 3087idle-timeout = 30 3088 3089group = smsc 3090smsc = emi_x25 3091phone = ... 3092device = /dev/tty0 3093smsc-username = foo 3094smsc-password = bar 3095</programlisting> 3096 3097 <informaltable frame="none"> 3098 <tgroup cols="3"><thead><row> 3099 <entry>Variable</entry> 3100 <entry>Value</entry> 3101 <entry>Description</entry> 3102 </row></thead><tbody> 3103 3104 <row><entry><literal>host (c)</literal></entry> 3105 <entry><literal>hostname</literal></entry> 3106 <entry valign="bottom"> 3107 Machine that runs SMSC. As IP (100.100.100.100) 3108 or hostname (their.machine.here) 3109 </entry></row> 3110 3111 <row><entry><literal>port (c)</literal></entry> 3112 <entry><literal>port-number</literal></entry> 3113 <entry valign="bottom"> 3114 Port number in the SMSC host machine 3115 </entry></row> 3116 3117 <row><entry><literal>alt-host</literal></entry> 3118 <entry><literal>hostname</literal></entry> 3119 <entry valign="bottom"> 3120 Optional alternate Machine that runs SMSC. 3121 As IP (100.100.100.100) or hostname (their.machine.here) 3122 (If undef but exists alt-port, emi2 would try host:alt-port) 3123 </entry></row> 3124 3125 <row><entry><literal>alt-port</literal></entry> 3126 <entry><literal>port-number</literal></entry> 3127 <entry valign="bottom"> 3128 Optional alternate Port number in the SMSC host machine 3129 (If undef but exists alt-host, emi2 would try alt-host:port) 3130 </entry></row> 3131 3132 <row><entry><literal>smsc-username</literal></entry> 3133 <entry><literal>string</literal></entry> 3134 <entry valign="bottom"> 3135 Username in the SMSC machine/connection account 3136 </entry></row> 3137 3138 <row><entry><literal>smsc-password</literal></entry> 3139 <entry><literal>string</literal></entry> 3140 <entry valign="bottom"> 3141 Password in the SMSC machine needed to contact SMSC 3142 </entry></row> 3143 3144 <row><entry><literal>device (c)</literal></entry> 3145 <entry><literal>device-name</literal></entry> 3146 <entry valign="bottom"> 3147 The device the modem is connected to, like <literal>/dev/ttyS0</literal>. 3148 ISDN connection only. 3149 </entry></row> 3150 3151 <row><entry><literal>phone (c)</literal></entry> 3152 <entry><literal>string</literal></entry> 3153 <entry valign="bottom"> 3154 Phone number to dial to, when connecting over a modem to an 3155 SMS center. 3156 </entry></row> 3157 3158 <row><entry><literal>our-port</literal></entry> 3159 <entry><literal>port-number</literal></entry> 3160 <entry valign="bottom"> 3161 Optional port number in which to bind the connection in our 3162 end. TCP/IP connection only. 3163 </entry></row> 3164 3165 <row><entry><literal>our-receiver-port</literal></entry> 3166 <entry><literal>port-number</literal></entry> 3167 <entry valign="bottom"> 3168 Optional port number allowing to specify our port when connecting 3169 an SMSC. TCP/IP connection only. 3170 </entry></row> 3171 3172 <row><entry><literal>receive-port</literal></entry> 3173 <entry><literal>port-number</literal></entry> 3174 <entry valign="bottom"> 3175 Optional port number we listen to and to which the SMS center 3176 connects when it has messages to send. Required if SMS center 3177 needs one connection to send and other to receive. 3178 TCP/IP connection only. 3179 </entry></row> 3180 3181 <row><entry><literal>appname</literal></entry> 3182 <entry><literal>string</literal></entry> 3183 <entry valign="bottom"> 3184 Name of a "Send only" service. Defaults to <literal>send</literal>. 3185 All outgoing messages are routed through this service. 3186 </entry></row> 3187 3188 <row><entry><literal>connect-allow-ip</literal></entry> 3189 <entry><literal>IP-list</literal></entry> 3190 <entry valign="bottom"> 3191 If set, only connections from these IP addresses are accepted 3192 to receive-port. TCP/IP connection only. 3193 </entry></row> 3194 3195 <row><entry><literal>idle-timeout</literal></entry> 3196 <entry><literal>number (seconds)</literal></entry> 3197 <entry valign="bottom"> 3198 If this option is set to a value larger than 0, then the connection will 3199 be closed after the configured amount of seconds without activity. This 3200 option interacts with the <literal>keepalive</literal> configuration option. 3201 If <literal>keepalive</literal> is smaller than <literal>idle-timeout</literal>, 3202 then the connection will never be idle and those this option has no effect. 3203 If <literal>keepalive</literal> is larger than <literal>idle-timeout</literal>, 3204 than <literal>keepalive</literal> reopens the connection. This allows one to poll 3205 for pending mobile originated Short Messages at the SMSC. 3206 </entry></row> 3207 3208 <row><entry><literal>keepalive</literal></entry> 3209 <entry><literal>number (seconds)</literal></entry> 3210 <entry valign="bottom"> 3211 A keepalive command will be 3212 sent to the SMSC connection this many seconds after the last 3213 message. The right value to use depends on how eager the SMSC is 3214 to close idle connections. 50 seconds is a good guess. If you 3215 see many unexplained reconnects, try lowering this value. Set it 3216 to 0 to disable this feature. 3217 Requires username or my-number to be set. 3218 </entry></row> 3219 3220 <row><entry><literal>wait-ack</literal></entry> 3221 <entry><literal>number (seconds)</literal></entry> 3222 <entry valign="bottom"> 3223 A message is resent if the acknowledge from SMSC takes more than 3224 this time. Defaults to 60 seconds. 3225 </entry></row> 3226 3227 <row><entry><literal>wait-ack-expire</literal></entry> 3228 <entry><literal>number</literal></entry> 3229 <entry valign="bottom"> 3230 Defines what kind of action should be taken if the the ack of 3231 a message expires. The options for this value are: 3232 0x00 - disconnect/reconnect, (default) 0x01 - as is now, re-queue, 3233 but this could potentially result in the msg arriving twice 3234 0x02 - just carry on waiting (given that the wait-ack should never 3235 expire this is the must accurate) 3236 </entry></row> 3237 3238 <row><entry><literal>flow-control</literal></entry> 3239 <entry><literal>number</literal></entry> 3240 <entry valign="bottom"> 3241 This SMSC can support two types of flow control. The first type 3242 of flow control is a <literal>stop-and-wait</literal> protocol, 3243 when this parameter equals to '1'. During the handling of commands, 3244 no other commands shall be sent before the a response is received. 3245 Any command that is sent before the reception of the response will 3246 be discarded. 3247 The second type of flow control is <literal>windowing</literal>, 3248 when this parameter is unset or equals '0'. In this case a maximum 3249 of n commands can be sent before a response is received. 3250 </entry></row> 3251 3252 <row><entry><literal>window</literal></entry> 3253 <entry><literal>number (messages)</literal></entry> 3254 <entry valign="bottom"> 3255 When using <literal>flow-control=0</literal>, emi works in windowed 3256 flow control mode. This variable defines the size of the window used 3257 to send messages. (optional, defaults to the maximum - 100) 3258 </entry></row> 3259 3260 <row><entry><literal>my-number</literal></entry> 3261 <entry><literal>number</literal></entry> 3262 <entry valign="bottom"> 3263 If the large account number is different from the short number, assign 3264 it with this variable. For example, if short number is 12345 and large account 3265 is 0100100100101234 (IP+port), set my-number to 12345 and 3266 every message received will have that receiver. In addition, if you are bound 3267 to the SMSC without an explicit login, use this configuration directive to 3268 enable keep-alive (OP/31) operations. 3269 </entry></row> 3270 3271 <row><entry><literal>alt-charset</literal></entry> 3272 <entry><literal>number</literal></entry> 3273 <entry valign="bottom"> 3274 Defines which character conversion kludge may be used for this 3275 specific link. Currently implemented alternative charsets are 3276 defined in "alt_charsets.h" and new ones can be added. 3277 </entry></row> 3278 3279 <row><entry><literal>notification-pid</literal></entry> 3280 <entry><literal>4 num char.</literal></entry> 3281 <entry valign="bottom"> 3282 Notification PID value. See below for a complete list and other notes. 3283 Example: 0539 3284 <footnote id="notification-pid-note"><para>If you set 3285 <literal>notification-pid</literal>, you should also set 3286 <literal>notification-addr</literal>.</para></footnote> 3287 </entry></row> 3288 3289 <row><entry><literal>notification-addr</literal></entry> 3290 <entry><literal>string (max 16)</literal></entry> 3291 <entry valign="bottom"> 3292 Notification Address. Example: 0100110120131234. 3293 <footnote id="notification-addr-note"><para>If you set 3294 <literal>notification-addr</literal>, you should also set 3295 <literal>notification-pid</literal>.</para></footnote> 3296 </entry></row> 3297 3298 </tbody></tgroup></informaltable> 3299 3300 <para> 3301 You should use <literal>notification-pid</literal> and 3302 <literal>notification-addr</literal> if you need to inform 3303 your exact "address" to your smsc. For example, if you have a 3304 <literal>Multiple-Address (MA)</literal> account with several 3305 connections to the same <literal>short number</literal>, you may 3306 need to tell your smsc to send delivery reports to the exact instance 3307 that sent the message. This is required because if you send a message 3308 with instance 1, your instance 2 wouldn't know about it, unless you 3309 use a shared DB store for delivery reports. 3310 </para> 3311 3312 <informaltable frame="none"> 3313 <tgroup cols="2"><thead><row> 3314 <entry>Notification PID Value</entry> 3315 <entry>Description</entry> 3316 </row></thead><tbody> 3317 3318 <row><entry>0100</entry><entry>Mobile Station</entry></row> 3319 <row><entry>0122</entry><entry>Fax Group 3</entry></row> 3320 <row><entry>0131</entry><entry>X.400</entry></row> 3321 <row><entry>0138</entry><entry>Menu over PSTN</entry></row> 3322 <row><entry>0139</entry><entry>PC appl. over PSTN (E.164)</entry></row> 3323 <row><entry>0339</entry><entry>PC appl. over X.25 (X.121)</entry></row> 3324 <row><entry>0439</entry><entry>PC appl. over ISDN (E.164)</entry></row> 3325 <row><entry>0539</entry><entry>PC appl. over TCP/IP</entry></row> 3326 3327 </tbody></tgroup></informaltable> 3328 3329 3330 3331 3332</sect2> 3333 3334<sect2> 3335<title>SMPP 3.3, 3.4 and 5.0</title> 3336 3337 <para>This implements Short Message Peer to Peer (SMPP) Protocol 3338 5.0, with most used support for 3.4 and full support for 3.3. Sample 3339 configuration:</para> 3340 3341<programlisting> 3342group = smsc 3343smsc = smpp 3344host = 123.123.123.123 3345port = 600 3346smsc-username = "STT" 3347smsc-password = foo 3348system-type = "VMA" 3349address-range = "" 3350</programlisting> 3351 3352<informaltable frame="none"> 3353 <tgroup cols="3"><thead><row> 3354 <entry>Variable</entry> 3355 <entry>Value</entry> 3356 <entry>Description</entry> 3357 </row></thead><tbody> 3358 3359 <row><entry><literal>host (m)</literal></entry> 3360 <entry><literal>hostname</literal></entry> 3361 <entry valign="bottom"> 3362 Machine that runs SMSC. As IP (100.100.100.100) 3363 or hostname (their.machine.here) 3364 </entry></row> 3365 3366 <row><entry><literal>port (m)</literal></entry> 3367 <entry><literal>port-number</literal></entry> 3368 <entry valign="bottom"> 3369 The port number for the TRANSMITTER connection to the SMSC. 3370 If set, receive-port must be ommited or set to 0. 3371 </entry></row> 3372 3373 <row><entry><literal>use-ssl</literal></entry> 3374 <entry><literal>bool</literal></entry> 3375 <entry valign="bottom"> 3376 Defines whether we should try to bind with SSL enabled connection. 3377 </entry></row> 3378 3379 <row><entry><literal>ssl-client-certkey-file (c)</literal></entry> 3380 <entry>filename</entry> 3381 <entry valign="bottom"> 3382 A PEM encoded SSL certificate and private key file to be used 3383 for SSL connections. This option is used together with use-ssl 3384 for client certificate validation with SMPP SMSCs requiring it. 3385 </entry></row> 3386 3387 <row><entry><literal>transceiver-mode</literal></entry> 3388 <entry>bool</entry> 3389 <entry valign="bottom"> 3390 Use a TRANSCEIVER mode connection to the SMSC. 3391 It uses the standard transmit 'port' to define the port 3392 to connect to. 3393 This is a SMPP 3.4 and 5.0 feature and will not work 3394 on an earlier SMSC using SMPP 3.3. 3395 This will do a bind_transceiver only and will not attempt 3396 to fall back to doing transmit and receive on the same connection. 3397 </entry></row> 3398 3399 <row><entry><literal>receive-port</literal></entry> 3400 <entry><literal>port-number</literal></entry> 3401 <entry valign="bottom"> 3402 The port number for the RECEIVER connection to the SMSC. 3403 If set, port must be ommited or set to 0. 3404 </entry></row> 3405 3406 <row><entry><literal>smsc-username (m)</literal></entry> 3407 <entry><literal>string</literal></entry> 3408 <entry valign="bottom"> 3409 The 'username' of the Messaging Entity connecting to the 3410 SMSC. If the SMSC operator reports that the "TELEPATH 3411 SYSTEM MANAGER TERMINAL" view "Control.Apps.View" value 3412 "Name:" is "SMPP_ZAPVMA_T" for the transmitter and 3413 "SMPP_ZAPVMA_R" for the receiver the smsc-username value 3414 is accordingly "SMPP_ZAP". Note that this used to be called 3415 system-id (the name in SMPP documentation) and has been 3416 changed to smsc-username to make all Kannel SMS center 3417 drivers use the same name. 3418 </entry></row> 3419 3420 <row><entry><literal>smsc-password (m)</literal></entry> 3421 <entry><literal>string</literal></entry> 3422 <entry valign="bottom"> 3423 The password matching the "smsc-username" your teleoperator 3424 provided you with. 3425 </entry></row> 3426 3427 3428 <row><entry><literal>system-type (m)</literal></entry> 3429 <entry><literal>string</literal></entry> 3430 <entry valign="bottom"> 3431 Optional; used to categorize the type of ESME that is binding 3432 to the SMSC. Examples include "VMS" (voice mail system) and "OTA" 3433 (over-the-air activation system). If not set, defaults to 3434 "VMA" (voice mail alerting). 3435 </entry></row> 3436 3437 <row><entry><literal>service-type</literal></entry> 3438 <entry><literal>string</literal></entry> 3439 <entry valign="bottom"> 3440 Optional; if specified, sets the service type for the SMSC. If 3441 unset, the default service type is used. This may be used to 3442 influence SMS routing (for example). The SMSC operator may 3443 also refer to this as the "profile ID". The maximum length of the 3444 service type is 6, according to the SMPP specification v3.4. 3445 Defined values are: "CMT" (cellular messaging), "CPT" (cellular 3446 paging), "VMN" (voice mail notification), "VMA" (voice mail 3447 alerting), "WAP" (wireless application protocol), "USSD" 3448 (unstructured supplementary services data), "CBS" (cell broadcast 3449 service) and "GUTS" (generic UDP transport service). Other values 3450 may be defined mutually between the SMSC and the ESME application. 3451 </entry></row> 3452 3453 <row><entry><literal>interface-version</literal></entry> 3454 <entry><literal>number</literal></entry> 3455 <entry valign="bottom"> 3456 Change the "interface version" parameter sent from Kannel to 3457 a value other then 0x34 (for SMPP v3.4). The value entered here 3458 should be the hexadecimal representation of the interface version 3459 parameter. For example, the default (if not set) is "34" which stands 3460 for 0x34. For SMPP v3.3 set to "33". For SMPP v5.0 set to "50". 3461 </entry></row> 3462 3463 <row><entry><literal>address-range (m)</literal></entry> 3464 <entry><literal>string</literal></entry> 3465 <entry valign="bottom"> 3466 According to the SMPP 3.4 spec this is supposed to 3467 affect which MS's can send messages to this account. 3468 Doesn't seem to work, though. 3469 </entry></row> 3470 3471 <row><entry><literal>my-number</literal></entry> 3472 <entry><literal>number</literal></entry> 3473 <entry valign="bottom"> 3474 Optional smsc short number. Should be set if smsc sends 3475 a different one. 3476 </entry></row> 3477 3478 <row><entry><literal>enquire-link-interval</literal></entry> 3479 <entry><literal>number</literal></entry> 3480 <entry valign="bottom"> 3481 Optional the time lapse allowed between operations after which 3482 an SMPP entity should interrogate whether it's peer still has an 3483 active session. The default is 30 seconds. 3484 </entry></row> 3485 3486 <row><entry><literal>max-pending-submits</literal></entry> 3487 <entry><literal>number</literal></entry> 3488 <entry valign="bottom"> 3489 Optional the maximum number of outstanding (i.e. acknowledged) 3490 SMPP operations between an ESME and SMSC. This number 3491 is not specified explicitly in the SMPP Protocol Specification 3492 and will be governed by the SMPP implementation on the SMSC. 3493 As a guideline it is recommended that no more than 10 (default) 3494 SMPP messages are outstanding at any time. 3495 </entry></row> 3496 3497 <row><entry><literal>reconnect-delay</literal></entry> 3498 <entry><literal>number</literal></entry> 3499 <entry valign="bottom"> 3500 Optional the time between attempts to connect an ESME to an SMSC 3501 having failed to connect initiating or during an SMPP session. 3502 The default is 10 seconds. 3503 </entry></row> 3504 3505 <row><entry><literal>source-addr-ton</literal></entry> 3506 <entry><literal>number</literal></entry> 3507 <entry valign="bottom"> 3508 Optional, source address TON setting for the link. 3509 (Defaults to 2). 3510 </entry></row> 3511 3512 <row><entry><literal>source-addr-npi</literal></entry> 3513 <entry><literal>number</literal></entry> 3514 <entry valign="bottom"> 3515 Optional, source address NPI setting for the link. 3516 (Defaults to 1). 3517 </entry></row> 3518 3519 <row><entry><literal>source-addr-autodetect</literal></entry> 3520 <entry><literal>boolean</literal></entry> 3521 <entry valign="bottom"> 3522 Optional, if defined tries to scan the source address and 3523 set TON and NPI settings accordingly. If you don't want to autodetect 3524 the source address, turn this off, by setting it to no. 3525 (Defaults to yes). 3526 </entry></row> 3527 3528 <row><entry><literal>dest-addr-ton</literal></entry> 3529 <entry><literal>number</literal></entry> 3530 <entry valign="bottom"> 3531 Optional, destination address TON setting for the link. 3532 (Defaults to 2). 3533 </entry></row> 3534 3535 <row><entry><literal>dest-addr-npi</literal></entry> 3536 <entry><literal>number</literal></entry> 3537 <entry valign="bottom"> 3538 Optional, destination address NPI setting for the link. 3539 (Defaults to 1). 3540 </entry></row> 3541 3542 <row><entry><literal>bind-addr-ton</literal></entry> 3543 <entry><literal>number</literal></entry> 3544 <entry valign="bottom"> 3545 Optional, bind address TON setting for the link. 3546 (Defaults to 0). 3547 </entry></row> 3548 3549 <row><entry><literal>bind-addr-npi</literal></entry> 3550 <entry><literal>number</literal></entry> 3551 <entry valign="bottom"> 3552 Optional, bind address NPI setting for the link. 3553 (Defaults to 0). 3554 </entry></row> 3555 3556 <row><entry><literal>msg-id-type</literal></entry> 3557 <entry><literal>number</literal></entry> 3558 <entry valign="bottom"> 3559 Optional, specifies which number base the SMSC is using for the 3560 message ID numbers in the corresponding <literal>submit_sm_resp</literal> 3561 and <literal>deliver_sm</literal> PDUs. This is required to make 3562 delivery reports (DLR) work on SMSC that behave differently. The number 3563 is a combined set of bit 1 and bit 2 that indicate as follows: 3564 bit 1: type for <literal>submit_sm_resp</literal>, bit 2: type for 3565 <literal>deliver_sm</literal>. If the bit is set then the value is 3566 in hex otherwise in decimal number base. Which means the following 3567 combinations are possible and valid: 3568 0x00 <literal>deliver_sm</literal> decimal, 3569 <literal>submit_sm_resp</literal> decimal; 3570 0x01 <literal>deliver_sm</literal> decimal, 3571 <literal>submit_sm_resp</literal> hex; 3572 0x02 <literal>deliver_sm</literal> hex, 3573 <literal>submit_sm_resp</literal> decimal; 3574 0x03 <literal>deliver_sm</literal> hex, 3575 <literal>submit_sm_resp</literal> hex. 3576 In accordance to the SMPP v3.4 specs the default will be a C string 3577 literal if no of the above values is explicitly indicated using the 3578 config directive. 3579 </entry></row> 3580 3581 <row><entry><literal>alt-charset</literal></entry> 3582 <entry><literal>string</literal></entry> 3583 <entry valign="bottom"> 3584 Defines which character encoding is used for this specific smsc link. 3585 Uses <literal>iconv()</literal> routines to convert from and to that 3586 specific character set encoding. See your local iconv_open(3) manual 3587 page for the supported character encodings and the type strings that 3588 should be presented for this directive. 3589 </entry></row> 3590 3591 <row><entry><literal>alt-addr-charset</literal></entry> 3592 <entry><literal>string</literal></entry> 3593 <entry valign="bottom"> 3594 Defines which character encoding is used for alphanumeric addresses. 3595 When set to <literal>GSM</literal>, addresses are converted into the 3596 GSM 03.38 charset (Since @ is translated into 0x00 which will break 3597 the SMPP PDU, @ replaced with ?). If set to another value, 3598 <literal>iconv()</literal> is used. 3599 (Defaults to windows-1252) 3600 </entry></row> 3601 3602 <row><entry><literal>connection-timeout</literal></entry> 3603 <entry><literal>number (seconds)</literal></entry> 3604 <entry valign="bottom"> 3605 This timer specifies the maximum time lapse allowed 3606 between transactions , after which period of inactivity, an SMPP driver may 3607 assume that the session is no longer active and does reconnect. 3608 Defaults to 300 seconds, to disable set it to 0. 3609 </entry></row> 3610 3611 <row><entry><literal>wait-ack</literal></entry> 3612 <entry><literal>number (seconds)</literal></entry> 3613 <entry valign="bottom"> 3614 A message is resent if the acknowledge from SMSC takes more than 3615 this time. Defaults to 60 seconds. 3616 </entry></row> 3617 3618 <row><entry><literal>wait-ack-expire</literal></entry> 3619 <entry><literal>number</literal></entry> 3620 <entry valign="bottom"> 3621 Defines what kind of action should be taken if the ack of 3622 a message expires. The options for this value are: 3623 0x00 - disconnect/reconnect, (default) 0x01 - as is now, re-queue, 3624 but this could potentially result in the msg arriving twice 3625 0x02 - just carry on waiting (given that the wait-ack should never 3626 expire this is the must accurate) 3627 </entry></row> 3628 3629 <row><entry><literal>validityperiod</literal></entry> 3630 <entry><literal>integer</literal></entry> 3631 <entry valign="bottom"> 3632 How long the message will be valid, i.e., how long the SMSC will try 3633 try to send the message to the recipient. Defined in minutes. 3634 </entry></row> 3635 3636 <row><entry><literal>esm-class</literal></entry> 3637 <entry><literal>number</literal></entry> 3638 <entry valign="bottom"> 3639 Change the "esm_class" parameter sent from Kannel. 3640 Accepted values are 0 (Default SMSC Mode) and 3 (Store and Forward). 3641 Defaults to 3. 3642 </entry></row> 3643 3644 </tbody></tgroup></informaltable> 3645 3646</sect2> 3647 3648<sect2> 3649<title>Sema Group SMS2000 OIS 4.0, 5.0 and 5.8</title> 3650 3651 <para>The 4.0 implementation is over Radio PAD (X.28). Following 3652 configuration variables are needed, and if you find out the more 3653 exact meaning, please send a report.</para> 3654 3655 <para>The 5.0 implementation uses X.25 access gateway.</para> 3656 3657 <para>The 5.8 implementation uses direct TCP/IP access interface.</para> 3658 3659<programlisting> 3660group = smsc 3661smsc = sema 3662device = /dev/tty0 3663smsc_nua = (X121 smsc address) 3664home_nua = (x121 radio pad address) 3665wait_report = 0/1 (0 means false, 1 means true) 3666</programlisting> 3667 3668<informaltable frame="none"> 3669 <tgroup cols="3"><thead><row> 3670 <entry>Variable</entry> 3671 <entry>Value</entry> 3672 <entry>Description</entry> 3673 </row></thead><tbody> 3674 3675 <row><entry><literal>device (m)</literal></entry> 3676 <entry><literal>device</literal></entry> 3677 <entry valign="bottom"> 3678 ex: /dev/tty0 3679 </entry></row> 3680 3681 <row><entry><literal>smsc_nua (m)</literal></entry> 3682 <entry><literal>X121 smsc address</literal></entry> 3683 <entry valign="bottom"> 3684 The address of an SMSC for SEMA SMS2000 protocols using an 3685 X.28 connection. 3686 </entry></row> 3687 3688 <row><entry><literal>home_nua (m)</literal></entry> 3689 <entry><literal>X121 radio pad address</literal></entry> 3690 <entry valign="bottom"> 3691 The address of a radio PAD implementing Sema SMS2000 using 3692 X.28 connection. 3693 </entry></row> 3694 3695 <row><entry><literal>wait_report</literal></entry> 3696 <entry><literal>0 (false)/1 (true)</literal></entry> 3697 <entry valign="bottom"> 3698 Report indicator used by the Sema SMS2000 protocol. Optional. 3699 </entry></row> 3700 </tbody></tgroup></informaltable> 3701 3702<programlisting> 3703group = smsc 3704smsc = ois 3705host = 103.102.101.100 3706port = 10000 3707receive-port = 10000 3708ois-debug-level = 0 3709</programlisting> 3710 3711<informaltable frame="none"> 3712 <tgroup cols="3"><thead><row> 3713 <entry>Variable</entry> 3714 <entry>Value</entry> 3715 <entry>Description</entry> 3716 </row></thead><tbody> 3717 3718 <row><entry><literal>host (m)</literal></entry> 3719 <entry><literal>ip</literal></entry> 3720 <entry valign="bottom"> 3721 SMSC Host name or IP 3722 </entry></row> 3723 3724 <row><entry><literal>port (m)</literal></entry> 3725 <entry><literal>port number</literal></entry> 3726 <entry valign="bottom"> 3727 SMSC Port number 3728 </entry></row> 3729 3730 <row><entry><literal>receive-port (m)</literal></entry> 3731 <entry><literal>port number</literal></entry> 3732 <entry valign="bottom"> 3733 The port in which the SMSC will contact 3734 </entry></row> 3735 3736 <row><entry><literal>ois-debug-level</literal></entry> 3737 <entry><literal>number 0 to 8</literal></entry> 3738 <entry valign="bottom"> 3739 extra debug, optional, see smsc_ois.c 3740 </entry></row> 3741 3742 </tbody></tgroup></informaltable> 3743 3744<programlisting> 3745group = smsc 3746smsc = oisd 3747host = 103.102.101.100 3748port = 10000 3749keepalive = 25 3750my-number = 12345 3751validityperiod = 30 3752</programlisting> 3753 3754<informaltable frame="none"> 3755 <tgroup cols="3"><thead><row> 3756 <entry>Variable</entry> 3757 <entry>Value</entry> 3758 <entry>Description</entry> 3759 </row></thead><tbody> 3760 3761 <row><entry><literal>host (m)</literal></entry> 3762 <entry><literal>ip</literal></entry> 3763 <entry valign="bottom"> 3764 SMSC Host name or IP 3765 </entry></row> 3766 3767 <row><entry><literal>port (m)</literal></entry> 3768 <entry><literal>port number</literal></entry> 3769 <entry valign="bottom"> 3770 SMSC Port number 3771 </entry></row> 3772 3773 <row><entry><literal>keepalive</literal></entry> 3774 <entry><literal>number</literal></entry> 3775 <entry valign="bottom"> 3776 SMSC connection will not be left idle for longer than this many 3777 seconds. The right value to use depends on how eager the SMSC 3778 is to close idle connections. If you see many unexplained 3779 reconnects, try lowering this value. 3780 Set it to 0 to disable this feature. 3781 </entry></row> 3782 3783 <row><entry><literal>my-number</literal></entry> 3784 <entry><literal>string</literal></entry> 3785 <entry valign="bottom"> 3786 Any valid SME number acceptable by SMSC. This number is used only in keepalive request. 3787 </entry></row> 3788 3789 <row><entry><literal>validityperiod</literal></entry> 3790 <entry><literal>integer</literal></entry> 3791 <entry valign="bottom"> 3792 How long the message will be valid, i.e., how long the SMS 3793 center (the real one, not the phone acting as one for Kannel) 3794 will try to send the message to the recipient. Defined in minutes. 3795 </entry></row> 3796 3797 </tbody></tgroup></informaltable> 3798</sect2> 3799 3800 3801<sect2> 3802<title>SM/ASI (for CriticalPath InVoke SMS Center 4.x)</title> 3803 3804 <para>This implements Short Message/Advanced Service Interface 3805 (SM/ASI) Protocol for the use of connecting to a CriticalPath 3806 InVoke SMS Center. Sample 3807 configuration:</para> 3808 3809<programlisting> 3810group = smsc 3811smsc = smasi 3812host = 10.11.12.13 3813port = 23456 3814smsc-username = foo 3815smsc-password = foo 3816</programlisting> 3817 3818<informaltable frame="none"> 3819 <tgroup cols="3"><thead><row> 3820 <entry>Variable</entry> 3821 <entry>Value</entry> 3822 <entry>Description</entry> 3823 </row></thead><tbody> 3824 3825 <row><entry><literal>host (m)</literal></entry> 3826 <entry><literal>hostname</literal></entry> 3827 <entry valign="bottom"> 3828 Machine that runs SMSC. As IP (10.11.12.13) 3829 or hostname (host.foobar.com) 3830 </entry></row> 3831 3832 <row><entry><literal>port (m)</literal></entry> 3833 <entry><literal>port-number</literal></entry> 3834 <entry valign="bottom"> 3835 The port number for the connection to the SMSC. 3836 </entry></row> 3837 3838 <row><entry><literal>smsc-username (m)</literal></entry> 3839 <entry><literal>string</literal></entry> 3840 <entry valign="bottom"> 3841 The 'username' of the Messaging Entity connecting to the 3842 SMSC. 3843 </entry></row> 3844 3845 <row><entry><literal>smsc-password (m)</literal></entry> 3846 <entry><literal>string</literal></entry> 3847 <entry valign="bottom"> 3848 The password matching the "smsc-username" your teleoperator 3849 provided you with. 3850 </entry></row> 3851 3852 <row><entry><literal>reconnect-delay</literal></entry> 3853 <entry><literal>number</literal></entry> 3854 <entry valign="bottom"> 3855 Optional, the time between attempts to connect to an SMSC 3856 having failed to connect initiating or during an session. 3857 The default is 10 seconds. 3858 </entry></row> 3859 3860 <row><entry><literal>source-addr-ton</literal></entry> 3861 <entry><literal>number</literal></entry> 3862 <entry valign="bottom"> 3863 Optional, source address TON setting for the link. 3864 (Defaults to 1). 3865 </entry></row> 3866 3867 <row><entry><literal>source-addr-npi</literal></entry> 3868 <entry><literal>number</literal></entry> 3869 <entry valign="bottom"> 3870 Optional, source address NPI setting for the link. 3871 (Defaults to 1). 3872 </entry></row> 3873 3874 <row><entry><literal>dest-addr-ton</literal></entry> 3875 <entry><literal>number</literal></entry> 3876 <entry valign="bottom"> 3877 Optional, destination address TON setting for the link. 3878 (Defaults to 1). 3879 </entry></row> 3880 3881 <row><entry><literal>dest-addr-npi</literal></entry> 3882 <entry><literal>number</literal></entry> 3883 <entry valign="bottom"> 3884 Optional, destination address NPI setting for the link. 3885 (Defaults to 1). 3886 </entry></row> 3887 3888 <row><entry><literal>priority</literal></entry> 3889 <entry><literal>number</literal></entry> 3890 <entry valign="bottom"> 3891 Optional, sets the default priority of messages transmitted 3892 over this smsc link. 3893 (Defaults to 0, which is the lowest priority). 3894 </entry></row> 3895 3896 </tbody></tgroup></informaltable> 3897</sect2> 3898 3899 3900<sect2> 3901<title>GSM modem</title> 3902 3903 <warning><para>See <xref linkend="upgrading-notes"/> for changes.</para></warning> 3904 3905 <para>This driver allows a GSM Modem or Phone to be connected to Kannel 3906 and work as a virtual SMSC</para> 3907 3908<programlisting> 3909group = smsc 3910smsc = at 3911modemtype = auto 3912device = /dev/ttyS0 3913speed = 9600 3914pin = 2345 3915</programlisting> 3916 3917 <informaltable frame="none"> 3918 <tgroup cols="3"><thead><row> 3919 <entry>Variable</entry> 3920 <entry>Value</entry> 3921 <entry>Description</entry> 3922 </row></thead><tbody> 3923 3924 <row><entry><literal>modemtype</literal></entry> 3925 <entry><literal>string</literal></entry> 3926 <entry valign="bottom"> 3927 Modems from different manufacturers have slightly different 3928 behavior. We need to know what type of modem is used. Use "auto" 3929 or omit parameter to have Kannel detect the modem type automatically. 3930 (some types should not be auto-detected like the Nokia Premicell). 3931 </entry></row> 3932 3933 <row><entry><literal>device (m)</literal></entry> 3934 <entry><literal>device-name</literal></entry> 3935 <entry valign="bottom"> 3936 The device the modem is connected to, like <literal>/dev/ttyS0</literal>. 3937 When the device name is set to <literal>rawtcp</literal> or 3938 <literal>telnet</literal> two other 3939 variables are required in the configuration: <literal>host</literal> 3940 and <literal>port</literal>. See the note below. 3941 </entry></row> 3942 3943 <row><entry><literal>speed</literal></entry> 3944 <entry><literal>serial speed in bps</literal></entry> 3945 <entry valign="bottom"> 3946 The speed in bits per second. Default value 0 means to try to use 3947 speed from modem definition, or if it fails, try to autodetect. 3948 </entry></row> 3949 3950 <row><entry><literal>pin</literal></entry> 3951 <entry><literal>string</literal></entry> 3952 <entry valign="bottom"> 3953 This is the PIN number of the SIM card in the GSM modem. You can specify 3954 this option if your SIM has never been used before and needs to have 3955 the PIN number entered. The PIN is usually a four digit number. 3956 </entry></row> 3957 3958 <row><entry><literal>validityperiod</literal></entry> 3959 <entry><literal>integer</literal></entry> 3960 <entry valign="bottom"> 3961 How long the message will be valid, i.e., how long the SMS 3962 center (the real one, not the phone acting as one for Kannel) 3963 will try to send the message to the recipient. Encoded as per 3964 the GSM 03.40 standard, section 9.2.3.12. Default is 3965 167, meaning 24 hours. 3966 </entry></row> 3967 3968 <row><entry><literal>keepalive</literal></entry> 3969 <entry><literal>seconds</literal></entry> 3970 <entry valign="bottom"> 3971 Kannel would "ping" the modem for this many seconds. If the probe fails, 3972 try to reconnect to it. 3973 </entry></row> 3974 3975 <row><entry><literal>my-number</literal></entry> 3976 <entry><literal>number</literal></entry> 3977 <entry valign="bottom"> 3978 Optional phone number. 3979 </entry></row> 3980 3981 <row><entry><literal>sms-center</literal></entry> 3982 <entry><literal>number</literal></entry> 3983 <entry valign="bottom"> 3984 SMS Center to send messages. 3985 </entry></row> 3986 3987 <row><entry><literal>sim-buffering</literal></entry> 3988 <entry><literal>boolean</literal></entry> 3989 <entry valign="bottom"> 3990 Whether to enable the so-called "SIM buffering behavior" of the GSM module. 3991 if assigned a true value, the module will query the message storage memory 3992 of the modem and will process and delete any messages found there. this does 3993 not alter normal behavior, but only add the capability of reading messages that 3994 were stored in the memory for some reason. The type of memory to use can be 3995 selected using the 'message-storage' parameter of the modem configuration. 3996 Polling the memory is done at the same interval as keepalive (if set) or 60 seconds 3997 (if not set). 3998 NOTE: This behavior is known to cause minor or major hiccups for a few buggy modems. 3999 Modems known to work with this setting are Wavecom WM02/M1200 and the Siemens M20. 4000 </entry></row> 4001 4002 <row><entry><literal>max-error-count</literal></entry> 4003 <entry><literal>integer</literal></entry> 4004 <entry valign="bottom"> 4005 Maximal error count for opening modem device or initializing of the modem before 4006 <literal>reset-string</literal> will be executed. This is useful when modem crashed and needs 4007 hard reset. Default disabled. 4008 </entry></row> 4009 4010 <row><entry><literal>host</literal></entry> 4011 <entry><literal>IP address</literal></entry> 4012 <entry valign="bottom"> 4013 Hostname or IP address to connect in <literal>rawtcp</literal> mode. 4014 Required if <literal>device</literal> is set to <literal>rawtcp</literal>. 4015 </entry></row> 4016 4017 <row><entry><literal>port</literal></entry> 4018 <entry><literal>integer</literal></entry> 4019 <entry valign="bottom"> 4020 TCP port to connect to on <literal>rawtcp-host</literal>. 4021 Required if <literal>device</literal> is set to <literal>rawtcp</literal>. 4022 </entry></row> 4023 4024 <row><entry><literal>smsc-username</literal></entry> 4025 <entry><literal>string</literal></entry> 4026 <entry valign="bottom"> 4027 Username to use on a Login: or User: prompt prior to be connected 4028 to the modem. Useful if modem is connected to a terminal server 4029 and <literal>rawtcp</literal> mode or <literal>telnet</literal> mode 4030 are used. 4031 </entry></row> 4032 4033 <row><entry><literal>smsc-password</literal></entry> 4034 <entry><literal>string</literal></entry> 4035 <entry valign="bottom"> 4036 Username to use on a Password prompt prior to be connected 4037 to the modem. Useful if modem is connected to a terminal server 4038 and <literal>rawtcp</literal> mode or <literal>telnet</literal> mode 4039 are used. <literal>smsc-password</literal> can be used alone 4040 without <literal>smsc-username</literal> for devices only asking for 4041 a password. 4042 </entry></row> 4043 4044 <row><entry><literal>login-prompt</literal></entry> 4045 <entry><literal>string</literal></entry> 4046 <entry valign="bottom"> 4047 An alternative string to be used instead of Login: or Username: 4048 </entry></row> 4049 4050 <row><entry><literal>password-prompt</literal></entry> 4051 <entry><literal>string</literal></entry> 4052 <entry valign="bottom"> 4053 An alternative string to be used instead of Password: 4054 </entry></row> 4055 4056 </tbody></tgroup></informaltable> 4057 4058 <para>Modem definitions are now multiple groups present in kannel.conf, 4059 either directly or, for example, by including the example 4060 modems.conf. (See <xref linkend="includes" endterm="includes.title"/>) 4061 </para> 4062 4063 <informaltable frame="none"> 4064 <tgroup cols="3"><thead><row> 4065 <entry>Variable</entry> 4066 <entry>Value</entry> 4067 <entry>Description</entry> 4068 </row></thead><tbody> 4069 4070 <row><entry><literal>group</literal></entry> 4071 <entry><literal>modems</literal></entry> 4072 <entry valign="bottom"> 4073 This is a mandatory variable 4074 </entry></row> 4075 4076 <row><entry><literal>id</literal></entry> 4077 <entry><literal>string</literal></entry> 4078 <entry valign="bottom"> 4079 This is the the id that should be used in 4080 <literal>modemtype</literal> variable from AT2 4081 </entry></row> 4082 4083 <row><entry><literal>name</literal></entry> 4084 <entry><literal>string</literal></entry> 4085 <entry valign="bottom"> 4086 The name of this modem configuration. Used in 4087 logs 4088 </entry></row> 4089 4090 <row><entry><literal>detect-string</literal></entry> 4091 <entry><literal>string</literal></entry> 4092 <entry valign="bottom"> 4093 String to use when trying to detect the modem. 4094 See <literal>detect-string2</literal> 4095 </entry></row> 4096 4097 <row><entry><literal>detect-string2</literal></entry> 4098 <entry><literal>string</literal></entry> 4099 <entry valign="bottom"> 4100 Second string to use to detect the modem. For example, 4101 if the modem replies with "SIEMENS MODEM M20", 4102 <literal>detect-string</literal> could be "SIEMENS" 4103 and <literal>detect-string2</literal> "M20" 4104 </entry></row> 4105 4106 <row><entry><literal>init-string</literal></entry> 4107 <entry><literal>string</literal></entry> 4108 <entry valign="bottom"> 4109 Optional initialization string. Defaults to 4110 "AT+CNMI=1,2,0,1,0" 4111 </entry></row> 4112 4113 <row><entry><literal>speed</literal></entry> 4114 <entry><literal>number</literal></entry> 4115 <entry valign="bottom"> 4116 Serial port hint speed to use. Optional. 4117 Defaults to smsc group speed or autodetect 4118 </entry></row> 4119 4120 <row><entry><literal>enable-hwhs</literal></entry> 4121 <entry><literal>string</literal></entry> 4122 <entry valign="bottom"> 4123 Optional AT command to enable hardware handshake. 4124 Defaults to "AT+IFC=2,2" 4125 </entry></row> 4126 4127 <row><entry><literal>hardware-flow-control</literal></entry> 4128 <entry><literal>boolean</literal></entry> 4129 <entry valign="bottom"> 4130 Optionally disable hardware handshake on the computer side by setting it to false. 4131 Defaults to true. 4132 </entry></row> 4133 4134 <row><entry><literal>need-sleep</literal></entry> 4135 <entry><literal>boolean</literal></entry> 4136 <entry valign="bottom"> 4137 Optional. Defaults to false. Some modems needs 4138 to sleep after opening the serial port and before 4139 first command 4140 </entry></row> 4141 4142 <row><entry><literal>no-pin</literal></entry> 4143 <entry><literal>boolean</literal></entry> 4144 <entry valign="bottom"> 4145 Optional. Defaults to false. If the modem doesn't 4146 support the PIN command, enable this 4147 </entry></row> 4148 4149 <row><entry><literal>no-smsc</literal></entry> 4150 <entry><literal>boolean</literal></entry> 4151 <entry valign="bottom"> 4152 Optional. Defaults to false. If the modem doesn't 4153 support setting the SMSC directly on the PDU, enable 4154 this. (Default is to include a "00" at the beginning 4155 of the PDU to say it's the default smsc, and remove 4156 the "00" when receiving) 4157 </entry></row> 4158 4159 <row><entry><literal>sendline-sleep</literal></entry> 4160 <entry><literal>number (milliseconds)</literal></entry> 4161 <entry valign="bottom"> 4162 Optional, defaults to 100 milliseconds. The sleep time 4163 after sending a AT command. 4164 </entry></row> 4165 4166 <row><entry><literal>keepalive-cmd</literal></entry> 4167 <entry><literal>string</literal></entry> 4168 <entry valign="bottom"> 4169 Optional, defaults to "AT". If keepalive is activated 4170 in AT2 group, this is the command to be sent. If your 4171 modem supports it, for example, use "AT+CBC;+CSQ", and 4172 see in logs the reply "+CBC: 0,64" (0=On battery, 64% 4173 full) and "+CSQ: 14,99" (0-31, 0-7: signal strength and 4174 channel bit error rate; 99 for unknown). See 3GPP 27007. 4175 </entry></row> 4176 4177 <row><entry><literal>message-storage</literal></entry> 4178 <entry><literal>string</literal></entry> 4179 <entry valign="bottom"> 4180 Message storage memory type to enable for "SIM buffering". 4181 Possible values are: "SM" - SIM card memory or "ME" - 4182 Mobile equipment memory (may not be supported by your 4183 modem). check your modem's manual for more types. 4184 By default, if the option is not set, no message storage command 4185 will be sent to the modem and the modem's default message 4186 storage will be used (usually "SM"). 4187 </entry></row> 4188 4189 <row><entry><literal>message-start</literal></entry> 4190 <entry><literal>string</literal></entry> 4191 <entry valign="bottom"> 4192 Optional integer, defaults to 1. Specifies starting index in 4193 SIM buffer for new SMS. Most modems start numbering from 1, 4194 however a few like the UMG181 start numbering from 0. This 4195 parameter ensures that all SMS are fetched when using 4196 "SIM buffering". 4197 </entry></row> 4198 4199 <row><entry><literal>enable-mms</literal></entry> 4200 <entry><literal>boolean</literal></entry> 4201 <entry valign="bottom"> 4202 Optional, defaults to false. If enabled, Kannel 4203 would send an AT+CMMS=2 if it have more than one 4204 message on queue and hopefully will be quicker 4205 sending the messages. 4206 </entry></row> 4207 4208 <row><entry><literal>reset-string</literal></entry> 4209 <entry><literal>string</literal></entry> 4210 <entry valign="bottom"> 4211 Which reset string to execute when <literal>max-error-count</literal> reached. 4212 Example for Falcom: AT+CFUN=1 4213 </entry></row> 4214 4215 4216 </tbody></tgroup></informaltable> 4217 4218 <para><emphasis>A note about delivery reports and GSM modems:</emphasis> 4219 while it is possible (and supported) to receive delivery reports on GSM 4220 modems, it may not work for you. if you encounter problems, check that your 4221 modem's init string (if not the default) is set to correctly allow the modem 4222 to send delivery reports using unsolicited notification (check your modem's 4223 manual). If the init-string is not set as si, some modems will store delivery 4224 reports to SIM memory, to get at which you will need to enable sim-buffering. 4225 finally your GSM network provider may not support delivery reports to mobile 4226 units.</para> 4227 4228 <para><emphasis>About <literal>rawtcp</literal> mode:</emphasis> 4229 This mode allows you to use a GSM modem connected to a remote terminal server, 4230 such as Perle IOLAN DS1 or a Cisco router with reverse telnet. The teminal 4231 server should support raw TCP mode. The driver is not tested in telnet mode. 4232 It is recommended to use <literal>keepalive</literal> variable, in order to 4233 automatically reconnect in case of network connectivity problems.</para> 4234 4235 <sect3> 4236 <title>Modem initialization</title> 4237 <para>This question has been asked frequently in the users mailing list. 4238 It usually comes in two forms: 4239 4240 <orderedlist> 4241 <listitem><para>Modem doesn't receive or transmit SMS.</para> 4242 <para>In its current implementation, the at driver will panic if it 4243 cannot find the modem device and bearerbox won't start. This 4244 can happen either because the wrong modem device is configured 4245 or the device has no write access for kannel's user.</para> 4246 <para> In the first case use system logs to discover where is your 4247 modem assigned to:</para> 4248 <para>grep tty /var/log/messages</para> 4249 <para>Then verify that this is indeed your GSM modem device by 4250 connecting to it with minicom or wvdial and issuing a few AT 4251 commands. Wvdial is preferrable, since it can also give you a 4252 working <literal>init-string</literal></para> 4253 <para>In the second case you need to give write access to kannel 4254 user. This is no problem if you run kannel as root, but it is 4255 not recommended to do so. In Ubuntu linux you just need to 4256 assign kannel user to group "dial". In other systems you can 4257 either:</para> 4258 <programlisting>chmod 666 /dev/modem</programlisting> 4259 <para>or preferably:</para> 4260 <programlisting> 4261chmod 664 /dev/modem 4262chgrp <emphasis>group</emphasis> /dev/modem 4263usermod -G <emphasis>group</emphasis> <emphasis>kannel-user</emphasis> 4264 </programlisting> 4265 </listitem> 4266 <listitem><para>Modem doesn't receive DLRs or SMS.</para> 4267 <para>By default the modem doesn't know how to treat incoming 4268 messages. To tell it to send it to kannel you have to 4269 configure <literal>init-string</literal> with the <emphasis> 4270 +CNMI=x,x,x,x,x</emphasis> command. X's are decimal numbers 4271 and CNMI stands for Command New Message Indication. There is 4272 no hard rule about its values. They are model and manufacturer 4273 specific. Best to consult modem manual or manufacturer's web 4274 site. Failing that, wvdialconf might give a working CNMI. 4275 Finally see modems.conf for examples and try out different 4276 values. Some Nokia phones do not support this command, but 4277 are ready to transmit incoming messages from the start.</para> 4278 <para>Since this setting is modem specific, kannel cannot understand 4279 what it means from its value, and if using unconventional 4280 values you should tell kannel through <literal>sim-buffering 4281 </literal> and <literal> message-storage</literal>. In any 4282 case it is useful to add +CMEE = 1 or 2 in the <literal> 4283 init-string</literal> in order to make the modem more verbose 4284 in its responses.</para> 4285 <programlisting> 4286group = modems 4287init-string = "AT+CNMI=2,3,0,1,0;+CMEE=1" 4288message-storage = ME or SM Depending on your modem, you may need to adjust it 4289... 4290 4291group = smsc 4292smsc = at 4293sim-buffering = true This will tell kannel to search for messages in 4294... the modem (either memory or its SIM) 4295 </programlisting> 4296 </listitem> 4297 </orderedlist> 4298 </para> 4299 </sect3> 4300</sect2> 4301 4302 4303<sect2> 4304<title>GSMA OneAPI v1.0 ParlayX SMS SOAP</title> 4305 4306 <para>This implements the GSMA OneAPI v1.0 ParlayX SMS SOAP/XML interface 4307 in two flavors, the Ericsson SDP (service delivery platform) ParlayX and 4308 the GSMA OneAPI v1.0 SOAP interfaces.</para> 4309 4310 <para>Example configuration for the Ericsson SDP variant:</para> 4311 4312<programlisting> 4313group = smsc 4314smsc = parlayx 4315system-type = ericsson-sdp 4316port = 10000 4317connect-allow-ip = 10.11.12.13 4318send-url = http://host/location 4319dlr-url = http://our-host:10000/dlr-location 4320smsc-username = tester 4321smsc-password = foobar 4322</programlisting> 4323 4324 <informaltable frame="none"> 4325 <tgroup cols="3"><thead><row> 4326 <entry>Variable</entry> 4327 <entry>Value</entry> 4328 <entry>Description</entry> 4329 </row></thead><tbody> 4330 4331 <row><entry><literal>system-type (m)</literal></entry> 4332 <entry><literal>string</literal></entry> 4333 <entry valign="bottom"> 4334 Type of ParlayX connection. Currently supported are: 4335 'oneapi-v1', 'ericsson-sdp'. 4336 The variants have the same ParlayX SOAP XML PDUs, but differ in the 4337 authentication scheme they use, where 'ericsson-sdp' uses WS-Security 4338 via wsse and 'oneapi-v1' uses plain HTTP basic authentication. 4339 </entry></row> 4340 4341 <row><entry><literal>port (m)</literal></entry> 4342 <entry><literal>port-number</literal></entry> 4343 <entry valign="bottom"> 4344 Port number in which Kannel listens to (MO and DLR) messages 4345 from other SOAP service side. 4346 </entry></row> 4347 4348 <row><entry><literal>send-url (m)</literal></entry> 4349 <entry><literal>url</literal></entry> 4350 <entry valign="bottom"> 4351 Location of the SOAP service to send MT messages. 4352 </entry></row> 4353 4354 <row><entry><literal>dlr-url (m)</literal></entry> 4355 <entry><literal>url</literal></entry> 4356 <entry valign="bottom"> 4357 Location of our side SOAP service for DLR notifications. 4358 </entry></row> 4359 4360 <row><entry><literal>smsc-username (m)</literal></entry> 4361 <entry><literal>string</literal></entry> 4362 <entry valign="bottom"> 4363 Username associated for the SOAP service connection. 4364 </entry></row> 4365 4366 <row><entry><literal>smsc-password (m)</literal></entry> 4367 <entry><literal>string</literal></entry> 4368 <entry valign="bottom"> 4369 Password associated for the SOAP service username. 4370 </entry></row> 4371 4372 <row><entry><literal>use-ssl</literal></entry> 4373 <entry><literal>boolean</literal></entry> 4374 <entry valign="bottom"> 4375 Defines whether listen port should use SSL. 4376 </entry></row> 4377 4378 <row><entry><literal>connect-allow-ip</literal></entry> 4379 <entry><literal>IP-list</literal></entry> 4380 <entry valign="bottom"> 4381 IPs allowed to use this SOAP service interface. If not set, 4382 "127.0.0.1" (localhost) is the only host allowed to connect. 4383 Typically you will allow the IP of the other side SOAP service 4384 here. 4385 </entry></row> 4386 4387 <row><entry><literal>window</literal></entry> 4388 <entry><literal>boolean</literal></entry> 4389 <entry valign="bottom"> 4390 Number of concurrent sending threads. If not set, 4391 one thread is used. 4392 </entry></row> 4393 4394 </tbody></tgroup></informaltable> 4395 4396</sect2> 4397 4398 4399<sect2> 4400<title>Fake SMSC</title> 4401 4402 <para>Fake SMSC is a simple protocol to test out Kannel. It is not 4403 a real SMS center, and cannot be used to send or receive SMS 4404 messages from real phones. So, it is ONLY used for testing purposes. 4405 </para> 4406 4407<programlisting> 4408group = smsc 4409smsc = fake 4410port = 10000 4411connect-allow-ip = 127.0.0.1 4412</programlisting> 4413 4414 <informaltable frame="none"> 4415 <tgroup cols="3"><thead><row> 4416 <entry>Variable</entry> 4417 <entry>Value</entry> 4418 <entry>Description</entry> 4419 </row></thead><tbody> 4420 4421 <row><entry><literal>host (m)</literal></entry> 4422 <entry><literal>hostname</literal></entry> 4423 <entry valign="bottom"> 4424 Machine that runs the SMSC. As IP (100.100.100.100) 4425 or hostname (their.machine.here) 4426 </entry></row> 4427 4428 <row><entry><literal>port (m)</literal></entry> 4429 <entry><literal>port-number</literal></entry> 4430 <entry valign="bottom"> 4431 Port number in smsc host machine 4432 </entry></row> 4433 4434 <row><entry><literal>connect-allow-ip</literal></entry> 4435 <entry><literal>IP-list</literal></entry> 4436 <entry valign="bottom"> 4437 If set, only connections from these IP addresses are accepted. 4438 </entry></row> 4439 4440 </tbody></tgroup></informaltable> 4441 4442</sect2> 4443 4444 4445<sect2> 4446<title>HTTP-based relay and content gateways</title> 4447 4448 <para>This special "SMSC" is used for HTTP based connections with 4449 other gateways and various other relay services, when direct SMSC 4450 is not available.</para> 4451 4452<programlisting> 4453group = smsc 4454smsc = http 4455system-type = kannel 4456smsc-username = nork 4457smsc-password = z0rK 4458port = 13015 4459send-url = "http://localhost:20022" 4460</programlisting> 4461 4462 4463 <informaltable frame="none"> 4464 <tgroup cols="3"><thead><row> 4465 <entry>Variable</entry> 4466 <entry>Value</entry> 4467 <entry>Description</entry> 4468 </row></thead><tbody> 4469 4470 <row><entry><literal>system-type (m)</literal></entry> 4471 <entry><literal>string</literal></entry> 4472 <entry valign="bottom"> 4473 Type of HTTP connection. Currently supported are: 'kannel', 4474 'brunet', 'xidris', 'wapme', 'clickatell' and 'generic'. 4475 </entry></row> 4476 4477 <row><entry><literal>send-url (m)</literal></entry> 4478 <entry><literal>url</literal></entry> 4479 <entry valign="bottom"> 4480 Location to send MT messages. This URL is expanded by used 4481 system, if need to. 4482 </entry></row> 4483 4484 <row><entry><literal>no-sender</literal></entry> 4485 <entry><literal>boolean</literal></entry> 4486 <entry valign="bottom"> 4487 Do not add variable sender to the send-url. 4488 </entry></row> 4489 4490 <row><entry><literal>no-coding</literal></entry> 4491 <entry><literal>boolean</literal></entry> 4492 <entry valign="bottom"> 4493 Do not add variable coding to the send-url. 4494 </entry></row> 4495 4496 <row><entry><literal>no-sep</literal></entry> 4497 <entry><literal>boolean</literal></entry> 4498 <entry valign="bottom"> 4499 Represent udh and text as a numeric string containing the hex-dump. For 4500 instance, text=%2b123 is represented as text=2b313233. 4501 </entry></row> 4502 4503 <row><entry><literal>port (m)</literal></entry> 4504 <entry><literal>port-number</literal></entry> 4505 <entry valign="bottom"> 4506 Port number in which Kannel listens to (MO) messages from other 4507 gateway 4508 </entry></row> 4509 4510 <row><entry><literal>use-ssl</literal></entry> 4511 <entry><literal>boolean</literal></entry> 4512 <entry valign="bottom"> 4513 Defines whether listen port should use SSL. 4514 </entry></row> 4515 4516 <row><entry><literal>connect-allow-ip</literal></entry> 4517 <entry><literal>IP-list</literal></entry> 4518 <entry valign="bottom"> 4519 IPs allowed to use this interface. If not set, "127.0.0.1" 4520 (localhost) is the only host allowed to connect. 4521 </entry></row> 4522 4523 <row><entry><literal>smsc-username</literal></entry> 4524 <entry><literal>string</literal></entry> 4525 <entry valign="bottom"> 4526 Username associated to connection, if needed. Kannel requires 4527 this, and it is the same as send-sms username at other end. 4528 </entry></row> 4529 4530 <row><entry><literal>smsc-password</literal></entry> 4531 <entry><literal>string</literal></entry> 4532 <entry valign="bottom"> 4533 Password for username, if needed. 4534 </entry></row> 4535 4536 <row><entry><literal>max-pending-submits</literal></entry> 4537 <entry><literal>number</literal></entry> 4538 <entry valign="bottom"> 4539 Optional the maximum number of outstanding (i.e. acknowledged) 4540 requests. As a guideline it is recommended that no more than 4541 10 (default) requests are outstanding at any time. 4542 </entry></row> 4543 </tbody></tgroup></informaltable> 4544 4545<sect3> 4546<title>The "generic" system-type</title> 4547 4548 <para>For a generic HTTP-based relay, the system-type 'generic' can be used. 4549 It can use the escape codes known from sms-service's get-url config 4550 directives in the send-url string to indicate the HTTP API calling style of 4551 the remote HTTP server, and the 3 HTTP body response parsing regular 4552 expressions 'status-success-regex' for successfull acknowledge, 4553 'status-permfail-regex' for permanent failure and 'status-tempfail-regex' 4554 for temporary failure. It can also accomodate the incoming parameters and response 4555 codes and text. This system-type has a lot of extra parameters that gives it a lot 4556 of flexibility: 4557 </para> 4558 4559 4560 <informaltable frame="none"> 4561 <tgroup cols="3"><thead><row> 4562 <entry>Variable</entry> 4563 <entry>Value</entry> 4564 <entry>Description</entry> 4565 </row></thead><tbody> 4566 4567 <row><entry><literal>status-success-regex (o)</literal></entry> 4568 <entry><literal>POSIX regular expression</literal></entry> 4569 <entry valign="bottom"> 4570 Regular expression to match against HTTP 4571 response body content, indicating a successful submission. 4572 </entry></row> 4573 4574 <row><entry><literal>status-permfail-regex (o)</literal></entry> 4575 <entry><literal>POSIX regular expression</literal></entry> 4576 <entry valign="bottom"> 4577 Regular expression to match against HTTP 4578 response body content, indicating a permanent failure. 4579 </entry></row> 4580 4581 <row><entry><literal>status-tempfail-regex (o)</literal></entry> 4582 <entry><literal>POSIX regular expression</literal></entry> 4583 <entry valign="bottom"> 4584 Regular expression to match against HTTP 4585 response body content, indicating a temporary failure. 4586 </entry></row> 4587 4588 <row><entry><literal>generic-foreign-id-regex (o)</literal></entry> 4589 <entry><literal>POSIX regular expression</literal></entry> 4590 <entry valign="bottom"> 4591 Regular expression to match against HTTP 4592 response body content to get the foreign message id 4593 in case of successful submission. 4594 </entry></row> 4595 4596 <row><entry><literal>generic-param-username (o)</literal></entry> 4597 <entry><literal>string</literal></entry> 4598 <entry valign="bottom"> 4599 Overrides the default parameter for the 'username' 4600 field used on incoming requests. 4601 </entry></row> 4602 4603 <row><entry><literal>generic-param-password (o)</literal></entry> 4604 <entry><literal>string</literal></entry> 4605 <entry valign="bottom"> 4606 Overrides the default parameter for the 'password' 4607 field used on incoming requests. 4608 </entry></row> 4609 4610 <row><entry><literal>generic-param-from (o)</literal></entry> 4611 <entry><literal>string</literal></entry> 4612 <entry valign="bottom"> 4613 Overrides the default parameter for the 'from' field 4614 used on incoming requests. 4615 </entry></row> 4616 4617 <row><entry><literal>generic-param-to (o)</literal></entry> 4618 <entry><literal>string</literal></entry> 4619 <entry valign="bottom"> 4620 Overrides the default parameter for the 'to' field 4621 used on incoming requests. 4622 </entry></row> 4623 4624 <row><entry><literal>generic-param-text (o)</literal></entry> 4625 <entry><literal>string</literal></entry> 4626 <entry valign="bottom"> 4627 Overrides the default parameter for the 'text' field 4628 used on incoming requests. 4629 </entry></row> 4630 4631 <row><entry><literal>generic-param-udh (o)</literal></entry> 4632 <entry><literal>string</literal></entry> 4633 <entry valign="bottom"> 4634 Overrides the default parameter for the 'udh' field 4635 used on incoming requests. 4636 </entry></row> 4637 4638 <row><entry><literal>generic-param-service (o)</literal></entry> 4639 <entry><literal>string</literal></entry> 4640 <entry valign="bottom"> 4641 Overrides the default parameter for the 'service' field 4642 used on incoming requests. 4643 </entry></row> 4644 4645 <row><entry><literal>generic-param-account (o)</literal></entry> 4646 <entry><literal>string</literal></entry> 4647 <entry valign="bottom"> 4648 Overrides the default parameter for the 'account' field 4649 used on incoming requests. 4650 </entry></row> 4651 4652 <row><entry><literal>generic-param-binfo (o)</literal></entry> 4653 <entry><literal>string</literal></entry> 4654 <entry valign="bottom"> 4655 Overrides the default parameter for the 'binfo' field 4656 used on incoming requests. 4657 </entry></row> 4658 4659 <row><entry><literal>generic-param-dlr-mask (o)</literal></entry> 4660 <entry><literal>string</literal></entry> 4661 <entry valign="bottom"> 4662 Overrides the default parameter for the 'dlr-mask' field 4663 used on incoming requests. 4664 </entry></row> 4665 4666 <row><entry><literal>generic-param-dlr-err (o)</literal></entry> 4667 <entry><literal>string</literal></entry> 4668 <entry valign="bottom"> 4669 Overrides the default parameter for the 'dlr-err' field 4670 used on incoming requests. 4671 </entry></row> 4672 4673 <row><entry><literal>generic-param-dlr-url (o)</literal></entry> 4674 <entry><literal>string</literal></entry> 4675 <entry valign="bottom"> 4676 Overrides the default parameter for the 'dlr-url' field 4677 used on incoming requests. 4678 </entry></row> 4679 4680 <row><entry><literal>generic-param-dlr-mid (o)</literal></entry> 4681 <entry><literal>string</literal></entry> 4682 <entry valign="bottom"> 4683 Overrides the default parameter for the 'dlr-mid' field 4684 used on incoming requests. 4685 </entry></row> 4686 4687 <row><entry><literal>generic-param-flash (o)</literal></entry> 4688 <entry><literal>string</literal></entry> 4689 <entry valign="bottom"> 4690 Overrides the default parameter for the 'flash' field 4691 used on incoming requests. 4692 </entry></row> 4693 4694 <row><entry><literal>generic-param-mclass (o)</literal></entry> 4695 <entry><literal>string</literal></entry> 4696 <entry valign="bottom"> 4697 Overrides the default parameter for the 'mclass' field 4698 used on incoming requests. 4699 </entry></row> 4700 4701 <row><entry><literal>generic-param-mwi (o)</literal></entry> 4702 <entry><literal>string</literal></entry> 4703 <entry valign="bottom"> 4704 Overrides the default parameter for the 'mwi' field 4705 used on incoming requests. 4706 </entry></row> 4707 4708 <row><entry><literal>generic-param-coding (o)</literal></entry> 4709 <entry><literal>string</literal></entry> 4710 <entry valign="bottom"> 4711 Overrides the default parameter for the 'coding' field 4712 used on incoming requests. 4713 </entry></row> 4714 4715 <row><entry><literal>generic-param-validity (o)</literal></entry> 4716 <entry><literal>string</literal></entry> 4717 <entry valign="bottom"> 4718 Overrides the default parameter for the 'validity' field 4719 used on incoming requests. 4720 </entry></row> 4721 4722 <row><entry><literal>generic-param-deferred (o)</literal></entry> 4723 <entry><literal>string</literal></entry> 4724 <entry valign="bottom"> 4725 Overrides the default parameter for the 'deferred' field 4726 used on incoming requests. 4727 </entry></row> 4728 4729 <row><entry><literal>generic-param-foreign-id (o)</literal></entry> 4730 <entry><literal>string</literal></entry> 4731 <entry valign="bottom"> 4732 Overrides the default parameter for the 'foreign-id' field 4733 used on incoming requests. 4734 </entry></row> 4735 4736 <row><entry><literal>generic-param-meta-data (o)</literal></entry> 4737 <entry><literal>string</literal></entry> 4738 <entry valign="bottom"> 4739 Overrides the default parameter for the 'meta-data' field 4740 used on incoming requests. 4741 </entry></row> 4742 4743 <row><entry><literal>generic-message-sent (o)</literal></entry> 4744 <entry><literal>string</literal></entry> 4745 <entry valign="bottom"> 4746 It allows you to set the text returned when a succesful request is made. 4747 If not set, defaults to 'Sent.'. Note that you can use all sms service escapes 4748 here, see <xref linkend="escapecodes" endterm="escapecodes.title"/> for details. 4749 </entry></row> 4750 4751 <row><entry><literal>generic-status-sent (o)</literal></entry> 4752 <entry><literal>string</literal></entry> 4753 <entry valign="bottom"> 4754 Overrides the HTTP status code returned when a successful 4755 request is made. If not set, defaults to 202 (HTTP_ACCEPTED). 4756 </entry></row> 4757 4758 <row><entry><literal>generic-status-error (o)</literal></entry> 4759 <entry><literal>string</literal></entry> 4760 <entry valign="bottom"> 4761 Overrides the HTTP status code returned when a request is 4762 rejected for any reason. If not set, defaults to 202 (HTTP_ACCEPTED). 4763 </entry></row> 4764 4765 </tbody></tgroup></informaltable> 4766 4767 <para>An example for a 'generic' group looks like this:</para> 4768 4769<programlisting> 4770group = smsc 4771smsc = http 4772system-type = generic 4773port = 13015 4774send-url = "http://www.foobar.com/mt.php?from=%P&to=%p&text=%b" 4775status-success-regex = "ok" 4776status-permfail-regex = "failure" 4777status-tempfail-regex = "retry later" 4778generic-foreign-id-regex = "<id>(.+)</id>" 4779generic-param-from = "phoneNumber" 4780generic-param-to = "shortCode" 4781generic-message-sent = "Message sent with ID: %I" 4782generic-status-sent = 200 4783generic-status-error = 404 4784</programlisting> 4785</sect3> 4786</sect2> 4787 4788 4789<sect2> 4790<title>Loopback SMSC (MT to MO direction switching)</title> 4791 4792 <para>This special "SMSC" type can be used to route MT messages in 4793 bearerbox internally as MO input messages again. Therefore this 4794 tyoe is the MT wise counterpart of the 'reroute' functionality 4795 of the smsc group when MOs are re-routed as MTs.</para> 4796 4797<programlisting> 4798group = smsc 4799smsc = loopback 4800smsc-id = loop1 4801reroute-smsc-id = my_id 4802</programlisting> 4803 4804 <informaltable frame="none"> 4805 <tgroup cols="3"><thead><row> 4806 <entry>Variable</entry> 4807 <entry>Value</entry> 4808 <entry>Description</entry> 4809 </row></thead><tbody> 4810 4811 <row><entry><literal>reroute-smsc-id (o)</literal></entry> 4812 <entry><literal>string</literal></entry> 4813 <entry valign="bottom"> 4814 Tag the rerouted MO with the given value for smsc-id 4815 instead of the canonical smsc-id value of the smsc group 4816 itself. 4817 </entry></row> 4818 4819 </tbody></tgroup></informaltable> 4820</sect2> 4821 4822 4823<sect2> 4824<title>Using multiple SMS centers</title> 4825 4826 <para>If you have several SMS center connections (multiple 4827 operators or a number of GSM modems) you need to configure one smsc 4828 group per SMS center (or GSM modem). When doing this, you might 4829 want to use routing systems to rout messages to specific centers - 4830 for example, you have 2 operator SMS centers, and the other is 4831 much faster and cheaper to use.</para> 4832 4833 <para>To set up routing systems, first give an unique ID for each 4834 SMS center - or if you want to treat multiple ones completely 4835 identical, give them identical ID. Then use 4836 <literal>preferred-smsc-id</literal> and 4837 <literal>denied-smsc-id</literal> to set up the routing to your 4838 taste. See also SMS PUSH settings ('sendsms-user' groups), below.</para> 4839</sect2> 4840 4841<sect2> 4842<title>Feature checklist</title> 4843 4844<para>Not all of Kannel's SMSC drivers support the same set of features. 4845This is because they were written at different times, and new features 4846are often only added to drivers that the feature author can test.</para> 4847 4848<para>The table in this section is an attempt to show exactly what 4849features to expect from a driver, and to help identify areas where 4850drivers need to be updated. Currently most of the entries are 4851marked as "not tested" because the table is still new.</para> 4852 4853<table> 4854 <title>SMSC driver features</title> 4855 <tgroup cols="13" align="center"> 4856 <colspec colname="first" colnum="1" align="center"/> 4857 <colspec colname="last" colnum="13"/> 4858 <spanspec spanname="feature" namest="first" nameend="last"/> 4859 <thead> 4860 <row> 4861 <entry>Feature</entry> 4862 <entry>cimd</entry> 4863 <entry>cimd2</entry> 4864 <entry>emi</entry> 4865 <entry>emi_x25</entry> 4866 <entry>smpp</entry> 4867 <entry>sema</entry> 4868 <entry>ois</entry> 4869 <entry>oisd</entry> 4870 <entry>at</entry> 4871 <entry>http</entry> 4872 <entry>fake</entry> 4873 <entry>smasi</entry> 4874 </row> 4875 </thead> 4876 <tbody> 4877 <row> 4878 <entry spanname="feature">Can use DLR</entry> 4879 </row> 4880 <row> 4881 <entry></entry> 4882 <entry>n</entry> 4883 <entry>y?</entry> 4884 <entry>y</entry> 4885 <entry>n</entry> 4886 <entry>y?</entry> 4887 <entry>n</entry> 4888 <entry>n</entry> 4889 <entry>y</entry> 4890 <entry>n</entry> 4891 <entry>n</entry> 4892 <entry>y</entry> 4893 <entry>y</entry> 4894 </row> 4895 <row> 4896 <entry spanname="feature">Can set DCS<footnote id="fields-to-dcs"><para>To use 4897 <literal>mclass</literal>, <literal>mwi</literal>, <literal>coding</literal> 4898 and <literal>compress</literal> fields.</para></footnote></entry> 4899 </row> 4900 <row> 4901 <entry></entry> 4902 <entry>?</entry> 4903 <entry>?</entry> 4904 <entry>y</entry> 4905 <entry>?</entry> 4906 <entry>?</entry> 4907 <entry>?</entry> 4908 <entry>?</entry> 4909 <entry>y</entry> 4910 <entry>y</entry> 4911 <entry>?</entry> 4912 <entry>?</entry> 4913 <entry>?</entry> 4914 </row> 4915 <row> 4916 <entry spanname="feature">Can set Alt-DCS</entry> 4917 </row> 4918 <row> 4919 <entry></entry> 4920 <entry>n</entry> 4921 <entry>n</entry> 4922 <entry>y</entry> 4923 <entry>n</entry> 4924 <entry>n</entry> 4925 <entry>n</entry> 4926 <entry>n</entry> 4927 <entry>n</entry> 4928 <entry>y</entry> 4929 <entry>n</entry> 4930 <entry>n</entry> 4931 <entry>?</entry> 4932 </row> 4933 4934 <row> 4935 <entry spanname="feature">Can set Validity</entry> 4936 </row> 4937 <row> 4938 <entry></entry> 4939 <entry>?</entry> 4940 <entry>?</entry> 4941 <entry>y</entry> 4942 <entry>?</entry> 4943 <entry>?</entry> 4944 <entry>?</entry> 4945 <entry>?</entry> 4946 <entry>y</entry> 4947 <entry>y</entry> 4948 <entry>?</entry> 4949 <entry>?</entry> 4950 <entry>?</entry> 4951 </row> 4952 4953 <row> 4954 <entry spanname="feature">Can set Deferred</entry> 4955 </row> 4956 <row> 4957 <entry></entry> 4958 <entry>?</entry> 4959 <entry>?</entry> 4960 <entry>y</entry> 4961 <entry>?</entry> 4962 <entry>?</entry> 4963 <entry>?</entry> 4964 <entry>?</entry> 4965 <entry>n</entry> 4966 <entry>n</entry> 4967 <entry>?</entry> 4968 <entry>?</entry> 4969 <entry>?</entry> 4970 </row> 4971 4972 <row> 4973 <entry spanname="feature">Can set PID</entry> 4974 </row> 4975 <row> 4976 <entry></entry> 4977 <entry>n</entry> 4978 <entry>y</entry> 4979 <entry>y</entry> 4980 <entry>n</entry> 4981 <entry>y</entry> 4982 <entry>n</entry> 4983 <entry>n</entry> 4984 <entry>n</entry> 4985 <entry>y</entry> 4986 <entry>n</entry> 4987 <entry>n</entry> 4988 <entry>?</entry> 4989 </row> 4990 4991 <row> 4992 <entry spanname="feature">Can set RPI</entry> 4993 </row> 4994 <row> 4995 <entry></entry> 4996 <entry>n</entry> 4997 <entry>y</entry> 4998 <entry>y</entry> 4999 <entry>n</entry> 5000 <entry>y</entry> 5001 <entry>n</entry> 5002 <entry>n</entry> 5003 <entry>n</entry> 5004 <entry>n</entry> 5005 <entry>n</entry> 5006 <entry>n</entry> 5007 <entry>?</entry> 5008 </row> 5009 5010 <row> 5011 <entry spanname="feature">Can send Unicode</entry> 5012 </row> 5013 <row> 5014 <entry></entry> 5015 <entry>?</entry> 5016 <entry>?</entry> 5017 <entry>y</entry> 5018 <entry>?</entry> 5019 <entry>?</entry> 5020 <entry>?</entry> 5021 <entry>?</entry> 5022 <entry>y</entry> 5023 <entry>y</entry> 5024 <entry>?</entry> 5025 <entry>?</entry> 5026 <entry>?</entry> 5027 </row> 5028 5029 <row> 5030 <entry spanname="feature">Can send 8 bits</entry> 5031 </row> 5032 <row> 5033 <entry></entry> 5034 <entry>?</entry> 5035 <entry>?</entry> 5036 <entry>y</entry> 5037 <entry>?</entry> 5038 <entry>?</entry> 5039 <entry>?</entry> 5040 <entry>?</entry> 5041 <entry>y</entry> 5042 <entry>y</entry> 5043 <entry>?</entry> 5044 <entry>?</entry> 5045 <entry>y</entry> 5046 </row> 5047 5048 <row> 5049 <entry spanname="feature">Correctly send GSM alphabet</entry> 5050 </row> 5051 <row> 5052 <entry></entry> 5053 <entry>?</entry> 5054 <entry>?</entry> 5055 <entry>y</entry> 5056 <entry>?</entry> 5057 <entry>?</entry> 5058 <entry>?</entry> 5059 <entry>?</entry> 5060 <entry>y</entry> 5061 <entry>?</entry> 5062 <entry>?</entry> 5063 <entry>?</entry> 5064 <entry>?</entry> 5065 </row> 5066 5067 <row> 5068 <entry spanname="feature">Can set binfo / tariff class</entry> 5069 </row> 5070 <row> 5071 <entry></entry> 5072 <entry>?</entry> 5073 <entry>y</entry> 5074 <entry>?</entry> 5075 <entry>?</entry> 5076 <entry>?</entry> 5077 <entry>?</entry> 5078 <entry>?</entry> 5079 <entry>n</entry> 5080 <entry>?</entry> 5081 <entry>?</entry> 5082 <entry>?</entry> 5083 <entry>?</entry> 5084 </row> 5085 5086 <row> 5087 <entry spanname="feature">Can use throttling</entry> 5088 </row> 5089 <row> 5090 <entry></entry> 5091 <entry>n</entry> 5092 <entry>n</entry> 5093 <entry>y</entry> 5094 <entry>n</entry> 5095 <entry>y</entry> 5096 <entry>n</entry> 5097 <entry>n</entry> 5098 <entry>n</entry> 5099 <entry>n</entry> 5100 <entry>y</entry> 5101 <entry>y</entry> 5102 <entry>y</entry> 5103 </row> 5104 5105 </tbody> 5106 </tgroup> 5107</table> 5108 5109<table> 5110 <title>SMSC driver internal features</title> 5111 <tgroup cols="13" align="center"> 5112 <colspec colname="first" colnum="1" align="center"/> 5113 <colspec colname="last" colnum="13"/> 5114 <spanspec spanname="feature" namest="first" nameend="last"/> 5115 <thead> 5116 <row> 5117 <entry>Feature</entry> 5118 <entry>cimd</entry> 5119 <entry>cimd2</entry> 5120 <entry>emi2</entry> 5121 <entry>emi_x25</entry> 5122 <entry>smpp</entry> 5123 <entry>sema</entry> 5124 <entry>ois</entry> 5125 <entry>oisd</entry> 5126 <entry>at</entry> 5127 <entry>http</entry> 5128 <entry>fake</entry> 5129 <entry>smasi</entry> 5130 </row> 5131 </thead> 5132 <tbody> 5133 5134 <row> 5135 <entry spanname="feature">Can keep idle connections alive</entry> 5136 </row> 5137 <row> 5138 <entry></entry> 5139 <entry>n</entry> 5140 <entry>y?</entry> 5141 <entry>y</entry> 5142 <entry>n</entry> 5143 <entry>y?</entry> 5144 <entry>?</entry> 5145 <entry>?</entry> 5146 <entry>y</entry> 5147 <entry>y</entry> 5148 <entry>?</entry> 5149 <entry>?</entry> 5150 <entry>y</entry> 5151 </row> 5152 5153 <!-- Lets clean the rest of the table --> 5154 5155 <row> 5156 <entry spanname="feature">Can send octet data without UDH</entry> 5157 </row> 5158 <row> 5159 <entry></entry> 5160 <entry>n</entry> 5161 <entry>y?</entry> 5162 <entry>y</entry> 5163 <entry>y?</entry> 5164 <entry>n</entry> 5165 <entry>n</entry> 5166 <entry>y?</entry> 5167 <entry>y</entry> 5168 <entry>y</entry> 5169 <entry>n</entry> 5170 <entry>y?<footnote id="nomarkod"><para>Does not mark it as octet data</para></footnote></entry> 5171 <entry>?</entry> 5172 </row> 5173 5174 <row> 5175 <entry spanname="feature">Can send octet data with UDH</entry> 5176 </row> 5177 <row> 5178 <entry></entry> 5179 <entry>N</entry> 5180 <entry>y?</entry> 5181 <entry>y</entry> 5182 <entry>y?</entry> 5183 <entry>y?</entry> 5184 <entry>n</entry> 5185 <entry>?</entry> 5186 <entry>y</entry> 5187 <entry>y</entry> 5188 <entry>y?</entry> 5189 <entry>y?<footnoteref linkend="nomarkod"/></entry> 5190 <entry>?</entry> 5191 </row> 5192 5193 <row> 5194 <entry spanname="feature">Can send text messages with UDH</entry> 5195 </row> 5196 <row> 5197 <entry></entry> 5198 <entry>n</entry> 5199 <entry>y?</entry> 5200 <entry>y</entry> 5201 <entry>y?</entry> 5202 <entry>n</entry> 5203 <entry>n</entry> 5204 <entry>?</entry> 5205 <entry>y</entry> 5206 <entry>y</entry> 5207 <entry>n</entry> 5208 <entry>y?</entry> 5209 <entry>?</entry> 5210 </row> 5211 5212 <row> 5213 <entry spanname="feature">Can receive octet data without UDH</entry> 5214 </row> 5215 <row> 5216 <entry></entry> 5217 <entry>n</entry> 5218 <entry>y?</entry> 5219 <entry>y</entry> 5220 <entry>n</entry> 5221 <entry>n</entry> 5222 <entry>y?<footnote><para>However, it looks like the <literal>sema</literal> driver can't receive <emphasis>text</emphasis> data.</para></footnote></entry> 5223 <entry>y?</entry> 5224 <entry>y</entry> 5225 <entry>y</entry> 5226 <entry>n</entry> 5227 <entry>n</entry> 5228 <entry>?</entry> 5229 </row> 5230 5231 <row> 5232 <entry spanname="feature">Can receive Unicode messages</entry> 5233 </row> 5234 <row> 5235 <entry></entry> 5236 <entry>n</entry> 5237 <entry>n</entry> 5238 <entry>y</entry> 5239 <entry>n</entry> 5240 <entry>n</entry> 5241 <entry>n</entry> 5242 <entry>n</entry> 5243 <entry>y</entry> 5244 <entry>y</entry> 5245 <entry>n</entry> 5246 <entry>n</entry> 5247 <entry>?</entry> 5248 </row> 5249 5250 <row> 5251 <entry spanname="feature">Can receive octet data with UDH</entry> 5252 </row> 5253 <row> 5254 <entry></entry> 5255 <entry>n</entry> 5256 <entry>y?</entry> 5257 <entry>y</entry> 5258 <entry>n</entry> 5259 <entry>n</entry> 5260 <entry>n</entry> 5261 <entry>N</entry> 5262 <entry>y</entry> 5263 <entry>y</entry> 5264 <entry>y?</entry> 5265 <entry>y?</entry> 5266 <entry>?</entry> 5267 </row> 5268 5269 <row> 5270 <entry spanname="feature">Can receive text messages with UDH</entry> 5271 </row> 5272 <row> 5273 <entry></entry> 5274 <entry>n</entry> 5275 <entry>y?</entry> 5276 <entry>y</entry> 5277 <entry>n</entry> 5278 <entry>n</entry> 5279 <entry>n</entry> 5280 <entry>N</entry> 5281 <entry>y</entry> 5282 <entry>y</entry> 5283 <entry>n</entry> 5284 <entry>n</entry> 5285 <entry>?</entry> 5286 </row> 5287 5288 <row> 5289 <entry spanname="feature">Correctly encodes <literal>@</literal> when sending</entry> 5290 </row> 5291 <row> 5292 <entry></entry> 5293 <entry>y?</entry> 5294 <entry>y?</entry> 5295 <entry>y</entry> 5296 <entry>?</entry> 5297 <entry>y?</entry> 5298 <entry>?</entry> 5299 <entry>y?</entry> 5300 <entry>y</entry> 5301 <entry>y</entry> 5302 <entry>y?</entry> 5303 <entry>y?</entry> 5304 <entry>?</entry> 5305 </row> 5306 5307 <row> 5308 <entry spanname="feature">Correctly encodes <literal>ä</literal> when sending</entry> 5309 </row> 5310 <row> 5311 <entry></entry> 5312 <entry>y?</entry> 5313 <entry>y?</entry> 5314 <entry>y</entry> 5315 <entry>?</entry> 5316 <entry>y?</entry> 5317 <entry>?</entry> 5318 <entry>y?</entry> 5319 <entry>y</entry> 5320 <entry>y</entry> 5321 <entry>y?</entry> 5322 <entry>y?</entry> 5323 <entry>?</entry> 5324 </row> 5325 5326 <row> 5327 <entry spanname="feature">Correctly encodes <literal>{</literal> when sending</entry> 5328 </row> 5329 <row> 5330 <entry></entry> 5331 <entry>n</entry> 5332 <entry>y?</entry> 5333 <entry>y</entry> 5334 <entry>?</entry> 5335 <entry>y?</entry> 5336 <entry>?</entry> 5337 <entry>n</entry> 5338 <entry>y</entry> 5339 <entry>N<footnote><para>Miscalculates message length</para></footnote></entry> 5340 <entry>y?</entry> 5341 <entry>y?</entry> 5342 <entry>?</entry> 5343 </row> 5344 5345 <row> 5346 <entry spanname="feature">Can receive <literal>@</literal> in text messages</entry> 5347 </row> 5348 <row> 5349 <entry></entry> 5350 <entry>y?</entry> 5351 <entry>y?</entry> 5352 <entry>y</entry> 5353 <entry>?</entry> 5354 <entry>y?</entry> 5355 <entry>?</entry> 5356 <entry>y?</entry> 5357 <entry>y</entry> 5358 <entry>y</entry> 5359 <entry>y?</entry> 5360 <entry>y?</entry> 5361 <entry>?</entry> 5362 </row> 5363 5364 <row> 5365 <entry spanname="feature">Can receive <literal>ä</literal> in text messages</entry> 5366 </row> 5367 <row> 5368 <entry></entry> 5369 <entry>y?</entry> 5370 <entry>y?</entry> 5371 <entry>y</entry> 5372 <entry>?</entry> 5373 <entry>y?</entry> 5374 <entry>?</entry> 5375 <entry>y?</entry> 5376 <entry>y</entry> 5377 <entry>y?</entry> 5378 <entry>y?</entry> 5379 <entry>y?</entry> 5380 <entry>?</entry> 5381 </row> 5382 5383 <row> 5384 <entry spanname="feature">Can receive <literal>{</literal> in text messages</entry> 5385 </row> 5386 <row> 5387 <entry></entry> 5388 <entry>n</entry> 5389 <entry>y?</entry> 5390 <entry>y</entry> 5391 <entry>?</entry> 5392 <entry>y?</entry> 5393 <entry>?</entry> 5394 <entry>n</entry> 5395 <entry>y</entry> 5396 <entry>y?</entry> 5397 <entry>y?</entry> 5398 <entry>y?</entry> 5399 <entry>?</entry> 5400 </row> 5401 5402 <row> 5403 <entry spanname="feature">Can shut down idle connections</entry> 5404 </row> 5405 <row> 5406 <entry></entry> 5407 <entry>n</entry> 5408 <entry>n</entry> 5409 <entry>y</entry> 5410 <entry>n</entry> 5411 <entry>n</entry> 5412 <entry>?</entry> 5413 <entry>?</entry> 5414 <entry>n</entry> 5415 <entry>?</entry> 5416 <entry>?</entry> 5417 <entry>?</entry> 5418 <entry>?</entry> 5419 </row> 5420 5421 </tbody> 5422 </tgroup> 5423</table> 5424 5425<informaltable frame="none"> 5426 <tgroup cols="2"> 5427 <colspec colnum="1" align="left"/> 5428 <thead> 5429 <row><entry>Symbol</entry><entry>Meaning</entry></row> 5430 </thead> 5431 5432 <tbody> 5433 5434 <row> 5435 <entry>?</entry> 5436 <entry>not yet investigated</entry> 5437 </row> 5438 5439 <row> 5440 <entry>y</entry> 5441 <entry>driver has this feature, and it has been tested</entry> 5442 </row> 5443 5444 <row> 5445 <entry>y?</entry> 5446 <entry>driver probably has this feature, has not been tested</entry> 5447 </row> 5448 5449 <row> 5450 <entry>n</entry> 5451 <entry>driver does not have this feature</entry> 5452 </row> 5453 5454 <row> 5455 <entry>N</entry> 5456 <entry>driver claims to have this feature but it doesn't work</entry> 5457 </row> 5458 5459 <row> 5460 <entry>-</entry> 5461 <entry>feature is not applicable for this driver</entry> 5462 </row> 5463 5464 </tbody> 5465 5466 </tgroup> 5467</informaltable> 5468 5469</sect2> 5470</sect1> 5471 5472 5473<sect1> 5474<title>External delivery report (DLR) storage</title> 5475 5476 <para>Delivery reports are supported by default internally, which 5477 means all DLRs are stored in the memory of the bearerbox process. 5478 This is problematic if bearerbox crashes or you take the process 5479 down in a controlled way, but there are still DLRs open. Therefore 5480 you may use external DLR storage places, i.e. a MySQL database. 5481 </para> 5482 <para>Following are the supported DLR storage types and how to use 5483 them:</para> 5484 5485 <sect2> 5486 <title>Internal DLR storage</title> 5487 5488 <para>This is the default way in handling DLRs and does not 5489 require any special configuration. In order to configure bearerbox 5490 to use internal DLR storage use <literal>dlr-storage = internal</literal> 5491 in the <literal>core</literal> group. 5492 </para> 5493 5494 </sect2> 5495 5496 <sect2> 5497 <title>MySQL DLR storage</title> 5498 <para>To store DLR information into a MySQL database you may use the 5499 <literal>dlr-storage = mysql</literal> configuration directive in the 5500 <literal>core</literal> group. 5501 </para> 5502 <para>In addition to that you must have a <literal>dlr-db</literal> 5503 group defined that specifies the table field names that are used to the 5504 DLR attributes and a <literal>mysql-connection</literal> group that 5505 defines the connection to the MySQL server itself. 5506 </para> 5507 <para>Here is the example configuration from 5508 <literal>doc/examples/dlr-mysql.conf</literal>: 5509 5510<programlisting> 5511group = mysql-connection 5512id = mydlr 5513host = localhost 5514username = foo 5515password = bar 5516database = dlr 5517max-connections = 1 5518 5519group = dlr-db 5520id = mydlr 5521table = dlr 5522field-smsc = smsc 5523field-timestamp = ts 5524field-destination = destination 5525field-source = source 5526field-service = service 5527field-url = url 5528field-mask = mask 5529field-status = status 5530field-boxc-id = boxc 5531</programlisting> 5532 5533 </para> 5534 5535<sect3> 5536<title>MySQL connection configuration</title> 5537 5538 <para>For several reasons external storage may be required to 5539 handle dynamical issues, i.e. DLRs, sms-service, sendsms-user, 5540 ota-setting, ota-bookmark definitions and so on. To define a 5541 MySQL database connection you simple need to specify a 5542 <literal>mysql-connection</literal> group as follows: 5543 </para> 5544 5545 <table frame="none"> 5546 <title>MySQL Connection Group Variables</title> 5547 <tgroup cols="3"> 5548 <thead> 5549 <row> 5550 <entry>Variable</entry> 5551 <entry>Value</entry> 5552 <entry>Description</entry> 5553 </row> 5554 </thead> 5555 <tbody> 5556 <row><entry><literal>group</literal></entry> 5557 <entry><literal>mysql-connection</literal></entry> 5558 <entry valign="bottom"> 5559 This is a mandatory variable 5560 </entry></row> 5561 5562 <row><entry><literal>id (m)</literal></entry> 5563 <entry><literal>string</literal></entry> 5564 <entry valign="bottom"> 5565 An optional name or id to identify this MySQL connection 5566 for internal reference with other MySQL related configuration 5567 groups. Any string is acceptable, but semicolon ';' may cause 5568 problems, so avoid it and any other special non-alphabet characters. 5569 </entry></row> 5570 5571 <row><entry><literal>host (m)</literal></entry> 5572 <entry>hostname or IP</entry> 5573 <entry valign="bottom"> 5574 Hostname or IP of a server running a MySQL database to connect to. 5575 </entry></row> 5576 5577 <row><entry><literal>username (m)</literal></entry> 5578 <entry>username</entry> 5579 <entry valign="bottom"> 5580 User name for connecting to MySQL database. 5581 </entry></row> 5582 5583 <row><entry><literal>password (m)</literal></entry> 5584 <entry>password</entry> 5585 <entry valign="bottom"> 5586 Password for connecting to MySQL database. 5587 </entry></row> 5588 5589 <row><entry><literal>database (m)</literal></entry> 5590 <entry>string</entry> 5591 <entry valign="bottom"> 5592 Name of database in MySQL database server to connect to. 5593 </entry></row> 5594 5595 <row><entry><literal>max-connections</literal></entry> 5596 <entry>integer</entry> 5597 <entry valign="bottom"> 5598 How many connections should be opened to the given database. 5599 This is used for database pool. 5600 </entry></row> 5601 5602 </tbody> 5603 </tgroup> 5604 </table> 5605 5606 <para>A sample 'mysql-connection' group: 5607 5608<programlisting> 5609group = mysql-connection 5610id = dlr-db 5611host = localhost 5612username = foo 5613password = bar 5614database = dlr 5615max-connections = 1 5616</programlisting> 5617 5618 </para> 5619 <para>In case you use different MySQL connections for several storage 5620 issues, i.e. one for DLR and another different one for sms-service you 5621 may use the <literal>include</literal> configuration statement to extract 5622 the MySQL related configuration groups to a separate <literal>mysql.conf 5623 </literal> file. 5624 </para> 5625 5626</sect3> 5627 </sect2> 5628 5629 <sect2> 5630 <title>LibSDB DLR storage</title> 5631 <para>To store DLR information into a LibSDB resource (which is an 5632 abstraction of a real database) you may use the 5633 <literal>dlr-storage = sdb</literal> configuration directive in the 5634 <literal>core</literal> group. 5635 </para> 5636 <para>In addition to that you must have a <literal>dlr-db</literal> 5637 group defined that specifies the table field names that are used to the 5638 DLR attributes and a <literal>sdb-connection</literal> group that 5639 defines the LibSDB resource itself. 5640 </para> 5641 <para>Here is the example configuration from 5642 <literal>doc/examples/dlr-sdb.conf</literal> using a PostgreSQL resource: 5643 5644<programlisting> 5645group = sdb-connection 5646id = pgdlr 5647url = "postgres:host=localhost:db=myapp:port=1234" 5648max-connections = 1 5649 5650group = dlr-db 5651id = pgdlr 5652table = dlr 5653field-smsc = smsc 5654field-timestamp = ts 5655field-destination = destination 5656field-source = source 5657field-service = service 5658field-url = url 5659field-mask = mask 5660field-status = status 5661field-boxc-id = boxc 5662</programlisting> 5663 5664 </para> 5665 <para>Beware that you have the DB support build in your LibSDB 5666 installation when trying to use a specific DB type within the URL. 5667 </para> 5668 5669 </sect2> 5670 5671 <sect2> 5672 <title>Oracle 8i/9i DLR storage</title> 5673 <para>To store DLR information into a Oracle database you may use the 5674 <literal>dlr-storage = oracle</literal> configuration directive in the 5675 <literal>core</literal> group. 5676 </para> 5677 <para>In addition to that you must have a <literal>dlr-db</literal> 5678 group defined that specifies the table field names that are used to the 5679 DLR attributes and a <literal>oracle-connection</literal> group that 5680 defines the connection to the Oracle server itself. 5681 </para> 5682 <para>Here is the example configuration from 5683 <literal>doc/examples/dlr-oracle.conf</literal>: 5684 5685<programlisting> 5686group = oracle-connection 5687id = mydlr 5688username = foo 5689password = bar 5690tnsname = dlr 5691max-connections = 1 5692 5693group = dlr-db 5694id = mydlr 5695table = dlr 5696field-smsc = smsc 5697field-timestamp = ts 5698field-destination = destination 5699field-source = source 5700field-service = service 5701field-url = url 5702field-mask = mask 5703field-status = status 5704field-boxc-id = boxc 5705</programlisting> 5706 5707 </para> 5708 5709 </sect2> 5710 5711 <sect2> 5712 <title>PostgreSQL DLR storage</title> 5713 <para>To store DLR information into a PostgreSQL database you may use the 5714 <literal>dlr-storage = pgsql</literal> configuration directive in the 5715 <literal>core</literal> group. 5716 </para> 5717 <para>In addition to that you must have a <literal>dlr-db</literal> 5718 group defined that specifies the table field names that are used to the 5719 DLR attributes and a <literal>pgsql-connection</literal> group that 5720 defines the connection to the PostgreSQL server itself. 5721 </para> 5722 <para>Here is the example configuration: 5723 5724<programlisting> 5725group = pgsql-connection 5726id = mydlr 5727host = myhost.com 5728username = foo 5729password = bar 5730database = dlr 5731max-connections = 1 5732 5733group = dlr-db 5734id = mydlr 5735table = dlr 5736field-smsc = smsc 5737field-timestamp = ts 5738field-destination = destination 5739field-source = source 5740field-service = service 5741field-url = url 5742field-mask = mask 5743field-status = status 5744field-boxc-id = boxc 5745</programlisting> 5746 5747 </para> 5748 5749 </sect2> 5750 5751 <sect2> 5752 <title>MS-SQL/Sybase DLR storage</title> 5753 <para>To store DLR information into a MS-SQL or Sybase (via FreeTDS) 5754 database you may use the <literal>dlr-storage = mssql</literal> 5755 configuration directive in the <literal>core</literal> group. 5756 </para> 5757 <para>In addition to that you must have a <literal>dlr-db</literal> 5758 group defined that specifies the table field names that are used to the 5759 DLR attributes and a <literal>mssql-connection</literal> group that 5760 defines the connection to the MS-SQL or Sybase server itself. 5761 </para> 5762 <para>Please note that the <literal>server</literal> configuration directive 5763 must match the corresponding <literal>[section]</literal> on 5764 <literal>freetds.conf</literal></para> 5765 <para>Here is the example configuration: 5766 5767<programlisting> 5768group = mssql-connection 5769id = msdlr 5770server = myservername 5771username = foo 5772password = bar 5773database = dlr 5774max-connections = 1 5775 5776group = dlr-db 5777id = msdlr 5778table = dlr 5779field-smsc = smsc 5780field-timestamp = ts 5781field-destination = destination 5782field-source = source 5783field-service = service 5784field-url = url 5785field-mask = mask 5786field-status = status 5787field-boxc-id = boxc 5788</programlisting> 5789 5790 </para> 5791 5792 </sect2> 5793 5794 <sect2> 5795 <title>SQLite3 DLR storage</title> 5796 <para>To store DLR information into a SQLite3 database you may use the 5797 <literal>dlr-storage = sqlite3</literal> configuration directive in the 5798 <literal>core</literal> group. 5799 </para> 5800 <para>In addition to that you must have a <literal>dlr-db</literal> 5801 group defined that specifies the table field names that are used to the 5802 DLR attributes and a <literal>sqlite3-connection</literal> group that 5803 defines the connection to the SQLite3 database itself. 5804 </para> 5805 <para>Here is the example configuration: 5806 5807<programlisting> 5808group = sqlite3-connection 5809id = mydlr 5810database = /path/to/file 5811max-connections = 1 5812 5813group = dlr-db 5814id = mydlr 5815table = dlr 5816field-smsc = smsc 5817field-timestamp = ts 5818field-destination = destination 5819field-source = source 5820field-service = service 5821field-url = url 5822field-mask = mask 5823field-status = status 5824field-boxc-id = boxc 5825</programlisting> 5826 5827 </para> 5828 5829 </sect2> 5830 5831 <sect2> 5832 <title>Redis DLR storage</title> 5833 <para>To store DLR information using the Redis (http://www.redis.io) keystore, you should set the 5834 <literal>dlr-storage = redis</literal> configuration directive in the 5835 <literal>core</literal> group. 5836 </para> 5837 <para>In addition, you must have a <literal>dlr-db</literal> group defined that specifies 5838 the key and hash field names that are used to store the DLR attributes and a 5839 <literal>redis-connection</literal> group that defines the connection to the Redis server. 5840 </para> 5841 <para> 5842 Since Redis is a keystore and not a SQL database, keys and not tables are used to store 5843 DLR attributes. For ease of configuration, the same configuration parameters in the <literal>dlr-db</literal> 5844 group that are used to define SQL tables in other DLR storage engines are used to configure 5845 key names in Redis. DLRs are stored as Redis hash keys with a separate key 5846 for each DLR. Key names are in the format 5847 <literal><table>:<smsc>:<timestamp></literal>. Some SMSCs also append the 5848 destination to the DLR keyname resulting DLR keynames in the format 5849 <literal><table>:<smsc>:<timestamp>:<destination></literal>. You can 5850 specify the <literal><table></literal> portion of the keyname by specifying the 5851 <literal>table</literal> value in the <literal>dlr-db</literal> group.</para> 5852 <para> 5853 In addition to one key per DLR, an additional key with a name in the format 5854 <literal><table>:Count</literal> is created to maintain a count of the total 5855 number of outstanding DLRs. 5856 </para> 5857 5858 <para>Here is the example configuration from 5859 <literal>doc/examples/dlr-redis.conf</literal>: 5860 5861 <programlisting> 5862 group = redis-connection 5863 id = mydlr 5864 host = localhost 5865 port = 6379 5866 #password = foo 5867 database = 2 5868 idle-timeout = 3600 5869 max-connections = 1 5870 5871 group = dlr-db 5872 id = mydlr 5873 ttl = 604800 5874 table = dlr 5875 field-smsc = smsc 5876 field-timestamp = ts 5877 field-destination = destination 5878 field-source = source 5879 field-service = service 5880 field-url = url 5881 field-mask = mask 5882 field-status = status 5883 field-boxc-id = boxc 5884 </programlisting> 5885 5886 </para> 5887 5888 <sect3> 5889 <title>Redis connection configuration</title> 5890 5891 <para>To define a Redis connection you need to specify a 5892 <literal>redis-connection</literal> group as follows: 5893 </para> 5894 5895 <table frame="none"> 5896 <title>Redis Connection Group Variables</title> 5897 <tgroup cols="3"> 5898 <thead> 5899 <row> 5900 <entry>Variable</entry> 5901 <entry>Value</entry> 5902 <entry>Description</entry> 5903 </row> 5904 </thead> 5905 <tbody> 5906 <row><entry><literal>group</literal></entry> 5907 <entry><literal>redis-connection</literal></entry> 5908 <entry valign="bottom"> 5909 This is a mandatory variable 5910 </entry></row> 5911 5912 <row><entry><literal>id (m)</literal></entry> 5913 <entry><literal>string</literal></entry> 5914 <entry valign="bottom"> 5915 An optional name or id to identify this Redis connection 5916 for internal reference with other Redis related configuration 5917 groups. Any string is acceptable, but semicolon ';' may cause 5918 problems, so avoid it and any other special non-alphabet characters. 5919 </entry></row> 5920 5921 <row><entry><literal>host (m)</literal></entry> 5922 <entry>hostname or IP</entry> 5923 <entry valign="bottom"> 5924 Hostname or IP of a server running Redis to connect to. 5925 </entry></row> 5926 5927 <row><entry><literal>password</literal></entry> 5928 <entry>password</entry> 5929 <entry valign="bottom"> 5930 If the Redis server is secured with a password in redis.conf, it must be 5931 specified here. By default, Redis servers are unsecured and in that case, 5932 this parameter may be ommitted.</entry></row> 5933 5934 <row><entry><literal>database</literal></entry> 5935 <entry>integer</entry> 5936 <entry valign="bottom"> 5937 The numeric ID (0-15) of the Redis database to use. Ideally this database 5938 should be dedicated to storing Redis DLRs since a separate key wil be created 5939 for each DLR. If this variable is ommitted, the default database (0) will be used. 5940 </entry></row> 5941 5942 <row><entry><literal>idle-timeout</literal></entry> 5943 <entry>integer</entry> 5944 <entry valign="bottom"> 5945 The number of seconds that Redis should hold the connection open without any 5946 traffic. Some Redis servers are configured to disconnect idle clients very 5947 quickly, and if this is the case you should set this value to something more 5948 reasonable. If ommitted, the Redis server-wide timeout from redis.conf will 5949 apply. 5950 </entry></row> 5951 5952 <row><entry><literal>max-connections</literal></entry> 5953 <entry>integer</entry> 5954 <entry valign="bottom"> 5955 How many connections should be opened to the Redis server. 5956 </entry></row> 5957 5958 </tbody> 5959 </tgroup> 5960 </table> 5961 </sect3> 5962 </sect2> 5963 5964 <sect2> 5965 <title>DLR database field configuration</title> 5966 <para>For external database storage of DLR information in relational 5967 database management systems (RDBMS) you will have to specify which table 5968 field are used to represent the stored data. This is done via the 5969 <literal>dlr-db</literal> group as follows: 5970 </para> 5971 5972 <table frame="none"> 5973 <title>DLR Database Field Configuration Group Variables</title> 5974 <tgroup cols="3"> 5975 <thead> 5976 <row> 5977 <entry>Variable</entry> 5978 <entry>Value</entry> 5979 <entry>Description</entry> 5980 </row> 5981 </thead> 5982 <tbody> 5983 <row><entry><literal>group</literal></entry> 5984 <entry><literal>dlr-db</literal></entry> 5985 <entry valign="bottom"> 5986 This is a mandatory variable 5987 </entry></row> 5988 5989 <row><entry><literal>id (m)</literal></entry> 5990 <entry><literal>string</literal></entry> 5991 <entry valign="bottom"> 5992 An id to identify which external connection should be used for 5993 DLR storage. Any string is acceptable, but semicolon ';' may cause 5994 problems, so avoid it and any other special non-alphabet characters. 5995 </entry></row> 5996 5997 <row><entry><literal>table (m)</literal></entry> 5998 <entry>string</entry> 5999 <entry valign="bottom"> 6000 The name of the table that is used to store the DLR information. 6001 </entry></row> 6002 6003 <row><entry><literal>field-smsc (m)</literal></entry> 6004 <entry>string</entry> 6005 <entry valign="bottom"> 6006 The table field that is used for the smsc data. 6007 </entry></row> 6008 6009 <row><entry><literal>field-timestamp (m)</literal></entry> 6010 <entry>string</entry> 6011 <entry valign="bottom"> 6012 The table field that is used for the timestamp data. 6013 </entry></row> 6014 6015 <row><entry><literal>field-destination (m)</literal></entry> 6016 <entry>string</entry> 6017 <entry valign="bottom"> 6018 The table field that is used for the destination number data. 6019 </entry></row> 6020 6021 <row><entry><literal>field-source (m)</literal></entry> 6022 <entry>string</entry> 6023 <entry valign="bottom"> 6024 The table field that is used for the source number data. 6025 </entry></row> 6026 6027 <row><entry><literal>field-service (m)</literal></entry> 6028 <entry>string</entry> 6029 <entry valign="bottom"> 6030 The table field that is used for the service username data. 6031 </entry></row> 6032 6033 <row><entry><literal>field-url (m)</literal></entry> 6034 <entry>string</entry> 6035 <entry valign="bottom"> 6036 The table field that is used for the DLR URL which is triggered 6037 when the DLR for this message arrives from the SMSC. 6038 </entry></row> 6039 6040 <row><entry><literal>field-mask (m)</literal></entry> 6041 <entry>string</entry> 6042 <entry valign="bottom"> 6043 The table field that is used for the DLR mask that has been set 6044 for a message. 6045 </entry></row> 6046 6047 <row><entry><literal>field-status (m)</literal></entry> 6048 <entry>string</entry> 6049 <entry valign="bottom"> 6050 The table field that is used to reflect the status of the DLR 6051 for a specific message. 6052 </entry></row> 6053 6054 <row><entry><literal>field-boxc-id (m)</literal></entry> 6055 <entry>string</entry> 6056 <entry valign="bottom"> 6057 The table field that is used to store the smsbox connection id 6058 that has passed the message for delivery. This is required in 6059 cases you want to guarantee that DLR messages are routed back to 6060 the same smsbox conn instance. This is done via the smsbox routing. 6061 If you don't use smsbox routing simply add this field to your 6062 database table and keep it empty. 6063 </entry></row> 6064 6065 </tbody> 6066 </tgroup> 6067 </table> 6068 6069 <para>A sample 'dlr-db' group: 6070 6071<programlisting> 6072group = dlr-db 6073id = dlr-db 6074table = dlr 6075field-smsc = smsc 6076field-timestamp = ts 6077field-source = source 6078field-destination = destination 6079field-service = service 6080field-url = url 6081field-mask = mask 6082field-status = status 6083field-boxc-id = boxc 6084</programlisting> 6085 6086 </para> 6087 <para>Beware that all variables in this group are mandatory, so you 6088 have to specify all fields to enable bearerbox to know how to store 6089 and retrieve the DLR information from the external storage spaces. 6090 </para> 6091 6092 </sect2> 6093 6094</sect1> 6095 6096 6097 6098<sect1> 6099<title>SMSBox configuration</title> 6100 6101<sect2> 6102<title>Smsbox group</title> 6103 6104 <para>You must define an 'smsbox' group into the configuration file to be 6105 able to use SMS Kannel. The simplest working 'smsbox' group looks 6106 like this: 6107 6108<programlisting> 6109group = smsbox 6110bearerbox-host = localhost 6111</programlisting> 6112 6113 ...but you would most probably want to define 'sendsms-port' to be 6114 able to use SMS push.</para> 6115 6116 <para>SMSBox inherits from core the following fields: 6117<programlisting> 6118smsbox-port 6119http-proxy-port 6120http-proxy-host 6121http-proxy-username 6122http-proxy-password 6123http-proxy-exceptions 6124http-proxy-exceptions-regex 6125ssl-certkey-file 6126</programlisting> 6127 </para> 6128 6129 <table frame="none"> 6130 <title>Smsbox Group Variables</title> 6131 <tgroup cols="3"> 6132 <thead> 6133 <row> 6134 <entry>Variable</entry> 6135 <entry>Value</entry> 6136 <entry>Description</entry> 6137 </row> 6138 </thead> 6139 <tbody> 6140 <row><entry><literal>group (m)</literal></entry> 6141 <entry><literal>smsbox</literal></entry> 6142 <entry valign="bottom"> 6143 This is a mandatory variable 6144 </entry></row> 6145 6146 <row><entry><literal>bearerbox-host (m)</literal></entry> 6147 <entry><literal>hostname</literal></entry> 6148 <entry valign="bottom"> 6149 The machine in which the bearerbox is. 6150 </entry></row> 6151 6152 <row><entry><literal>bearerbox-port (o)</literal></entry> 6153 <entry>port-number</entry> 6154 <entry valign="bottom"> 6155 This is the port number to which smsbox will connect bearerbox. 6156 If not given <literal>smsbox-port</literal> from core group used. 6157 </entry></row> 6158 6159 <row><entry><literal>bearerbox-port-ssl (o)</literal></entry> 6160 <entry>bool</entry> 6161 <entry valign="bottom"> 6162 If set to true, the smsbox connection will be SSL-enabled. 6163 Your smsbox will connect using SSL to the bearerbox 6164 then. This is used to secure communication between bearerbox 6165 and smsboxes in case they are in separate networks operated and 6166 the TCP communication is not secured on a lower network layer. 6167 If not given <literal>smsbox-port-ssl</literal> from core group used. 6168 </entry></row> 6169 6170 <row><entry><literal>smsbox-id (o)</literal></entry> 6171 <entry>string</entry> 6172 <entry valign="bottom"> 6173 Optional smsbox instance identifier. This is used to 6174 identify an smsbox connected to an bearerbox for the purpose 6175 of having smsbox specific routing inside bearerbox. So if you 6176 you own boxes that do pass messages into bearerbox for delivery 6177 you may want that answers to those are routed back to your 6178 specific smsbox instance, i.e. SMPP or EMI proxying boxes. 6179 </entry></row> 6180 6181 <row><entry><literal>sendsms-interface (o)</literal></entry> 6182 <entry>string</entry> 6183 <entry valign="bottom"> 6184 If this is set, the sendsms HTTP interface will only bind 6185 to a specified address. For example: "127.0.0.1". 6186 </entry></row> 6187 6188 <row><entry><literal>sendsms-port (c)</literal></entry> 6189 <entry>port-number</entry> 6190 <entry valign="bottom"> 6191 The port in which any sendsms HTTP requests are done. As with 6192 other ports in Kannel, can be set as anything desired. 6193 </entry></row> 6194 6195 <row><entry><literal>sendsms-port-ssl (o)</literal></entry> 6196 <entry>bool</entry> 6197 <entry valign="bottom"> 6198 If set to true, the sendsms HTTP interface will use a 6199 SSL-enabled HTTP server with the specified 6200 ssl-server-cert-file and ssl-server-key-file from the 6201 core group. Defaults to "no". 6202 </entry></row> 6203 6204 <row><entry><literal>sendsms-url (o)</literal></entry> 6205 <entry>url</entry> 6206 <entry valign="bottom"> 6207 URL locating the sendsms service. Defaults to <literal> 6208 /cgi-bin/sendsms</literal>. 6209 </entry></row> 6210 6211 <row><entry><literal>sendota-url (o)</literal></entry> 6212 <entry>url</entry> 6213 <entry valign="bottom"> 6214 URL locating the sendota service. Defaults to <literal> 6215 /cgi-bin/sendota</literal>. 6216 </entry></row> 6217 6218 <row><entry><literal>immediate-sendsms-reply (o)</literal></entry> 6219 <entry>boolean</entry> 6220 <entry valign="bottom"> 6221 This is a backward compatibility flag: when set, Kannel will 6222 immediately answer to any sendsms requests, without knowing if 6223 the bearerbox will ever accept the message. If set to false 6224 (default), smsbox will not reply to HTTP request until the bearerbox 6225 has received the message. 6226 </entry></row> 6227 6228 <row><entry><literal>sendsms-chars</literal></entry> 6229 <entry>string</entry> 6230 <entry valign="bottom"> 6231 Only these characters are allowed in 'to' field when send-SMS 6232 service is requested via HTTP. Naturally, you should allow 6233 at least <literal>0123456789</literal>. The 6234 <emphasis>space</emphasis> character (' ') has special 6235 meaning: it is used to separate multiple phone numbers from 6236 each other in multi-send. To disable this feature, do not have 6237 it as an accepted character. If this variable is 6238 not set, the default set <literal>"0123456789 +-"</literal> is used. 6239 </entry></row> 6240 6241 <row><entry><literal>global-sender</literal></entry> 6242 <entry>phone-number</entry> 6243 <entry valign="bottom"> 6244 If set, all sendsms originators are set as these before 6245 proceeding. Note that in a case of most SMS centers you 6246 cannot set the sender number, but it is automatically set 6247 as the number of SMSC 6248 </entry></row> 6249 6250 <row><entry><literal>log-file</literal></entry> 6251 <entry>filename</entry> 6252 <entry morerows="2" valign="bottom"> 6253 As with the bearerbox 'core' group. Access-log is used to store 6254 information about MO and send-sms requests. Can be named same as the 6255 'main' access-log (in 'core' group). 6256 </entry></row> 6257 6258 <row><entry><literal>log-level</literal></entry> 6259 <entry>number 0..5</entry></row> 6260 6261 <row><entry><literal>access-log</literal></entry> 6262 <entry>filename</entry></row> 6263 6264 <row><entry><literal>syslog-level</literal></entry> 6265 <entry>number</entry> 6266 <entry valign="bottom"> 6267 Messages of this log level or higher will also be 6268 sent to syslog, the UNIX system log daemon. If not explicitly 6269 set with <literal>syslog-facility</literal>, it logs under the 6270 'daemon' category. The default is not to use syslog, and you can 6271 set that explicitly by setting <literal>syslog-level</literal> 6272 to 'none'. 6273 </entry></row> 6274 6275 <row><entry><literal>syslog-facility</literal></entry> 6276 <entry>string</entry> 6277 <entry valign="bottom"> 6278 The syslog facility to send the syslog entries to. The 6279 default is 'daemon'. 6280 </entry></row> 6281 6282 <row><entry><literal>white-list</literal></entry> 6283 <entry>URL</entry> 6284 <entry valign="bottom"> 6285 Load a list of accepted destinations of SMS messages. If a 6286 destination of an SMS message is not in this list, any message 6287 received from the HTTP interface is rejected. See notes of phone 6288 number format from numhash.h header file. 6289 </entry></row> 6290 6291 <row><entry><literal>black-list</literal></entry> 6292 <entry>URL</entry> 6293 <entry valign="bottom"> 6294 As white-list, but SMS messages to these numbers are 6295 automatically discarded 6296 </entry></row> 6297 6298 <row><entry><literal>reply-couldnotfetch</literal></entry> 6299 <entry>string</entry> 6300 <entry valign="bottom"> 6301 If set, replaces the SMS message sent back to user when Kannel 6302 could not fetch content. 6303 Defaults to <literal>Could not fetch content, sorry.</literal>. 6304 </entry></row> 6305 6306 <row><entry><literal>reply-couldnotrepresent</literal></entry> 6307 <entry>string</entry> 6308 <entry valign="bottom"> 6309 If set, replaces the SMS message sent back when Kannel could not 6310 represent the result as a SMS message. 6311 Defaults to <literal>Result could not be represented as an 6312 SMS message.</literal>. 6313 </entry></row> 6314 6315 <row><entry><literal>reply-requestfailed</literal></entry> 6316 <entry>string</entry> 6317 <entry valign="bottom"> 6318 If set, replaces the SMS message sent back when Kannel could not 6319 contact http service. 6320 Defaults to <literal>Request Failed</literal>. 6321 </entry></row> 6322 6323 <row><entry><literal>reply-emptymessage</literal></entry> 6324 <entry>string</entry> 6325 <entry valign="bottom"> 6326 If set, replaces the SMS message sent back when message is 6327 empty. Set to "" to enable empty messages. 6328 Defaults to <literal><Empty reply from service provider></literal>. 6329 </entry></row> 6330 6331 <row><entry><literal>mo-recode</literal></entry> 6332 <entry>boolean</entry> 6333 <entry valign="bottom"> 6334 If enabled, Kannel will try to convert received messages with UCS-2 charset 6335 to WINDOWS-1252 or to UTF-8, simplifying external servers jobs. If Kannel is 6336 able to recode message, it will also change <literal>coding</literal> to 6337 <literal>7 bits</literal> and <literal>charset</literal> to 6338 <literal>windows-1252</literal> or to <literal>utf-8</literal>. 6339 </entry></row> 6340 6341 <row><entry><literal>http-request-retry</literal></entry> 6342 <entry>integer</entry> 6343 <entry valign="bottom"> 6344 If set, specifies how many retries should be performed for failing 6345 HTTP requests of sms-services. Defaults to 0, which means no retries 6346 should be performed and hence no HTTP request queuing is done. 6347 </entry></row> 6348 6349 <row><entry><literal>http-queue-delay</literal></entry> 6350 <entry>integer</entry> 6351 <entry valign="bottom"> 6352 If set, specifies how many seconds should pass within the HTTP queuing 6353 thread for retrying a failed HTTP request. Defaults to 10 sec. and is 6354 only obeyed if <literal>http-request-retry</literal> is set to a 6355 non-zero value. 6356 </entry></row> 6357 6358 <row><entry><literal>white-list-regex</literal></entry> 6359 <entry>POSIX regular expression</entry> 6360 <entry valign="bottom"> 6361 Defines the set of accepted destinations of SMS messages. If a 6362 destination of an SMS message is not in this set, any message 6363 received from the HTTP interface is rejected. 6364 See section on <xref linkend="regular-expressions"/> for details. 6365 </entry> 6366 </row> 6367 <row><entry><literal>black-list-regex</literal></entry> 6368 <entry>POSIX regular expression</entry> 6369 <entry valign="bottom"> 6370 As white-list-regex, but SMS messages to numbers within in this set are 6371 automatically discarded. 6372 See section on <xref linkend="regular-expressions"/> for details. 6373 </entry> 6374 </row> 6375 <row><entry><literal>max-pending-requests</literal></entry> 6376 <entry>number of messages</entry> 6377 <entry valign="bottom"> 6378 Maximum number of pending MO or DLR messages that are handled in parallel. 6379 (Default: 512) 6380 </entry> 6381 </row> 6382 6383 <row><entry><literal>http-timeout</literal></entry> 6384 <entry>seconds</entry> 6385 <entry valign="bottom"> 6386 Sets socket timeout in seconds for outgoing client http 6387 connections. Optional. Defaults to 240 seconds. 6388 </entry></row> 6389 6390 <row><entry><literal>sms-length</literal></entry> 6391 <entry>number</entry> 6392 <entry valign="bottom"> 6393 Maximum allowed number of characters for a single SMS in smsbox. 6394 If this maximum exceeds Kannel will split SMS into multiparts. 6395 Default: 140 6396 </entry></row> 6397 6398 </tbody> 6399 </tgroup> 6400 </table> 6401 6402 <para>A typical 'smsbox' group could be something like this: 6403 6404<programlisting> 6405group = smsbox 6406bearerbox-host = localhost 6407sendsms-port = 13131 6408sendsms-chars = "0123456789 " 6409global-sender = 123456 6410access-log = "kannel.access" 6411log-file = "smsbox.log" 6412log-level = 0 6413</programlisting> 6414 </para> 6415 6416 6417</sect2> 6418 6419<sect2> 6420<title>Smsbox routing inside bearerbox</title> 6421 6422 <para>The communication link between bearerbox and smsbox has been 6423 designed for the purpose of load-balancing via random assignment. 6424 Which means, bearerbox holds all smsc connections and passes inbound 6425 message to one of the connected smsboxes. So you have a determined route 6426 for outbound messages, but no determined route for inbound messages. 6427 </para> 6428 6429 <para>The smsbox routing solves this for the inbound direction. In 6430 certain scenarios you want that bearerbox to know to which smsbox 6431 instance it should pass messages. I.e. if you implement own boxes 6432 that pass messages to bearerbox and expect to receive messages defined 6433 on certain rules, like receiver number or smsc-id. This is the case 6434 for EMI/UCP and SMPP proxies that can be written easily using smsbox 6435 routing facility. 6436 </para> 6437 6438 <para>If you box handles the SMPP server specific communication to your 6439 EMSEs, and if an client send a submit_sm PDU, the box would transform 6440 the message into Kannel message representation and inject the message to 6441 bearerbox as if it would be an smsbox. As you want to assign your clients 6442 shortcodes for certain networks or route any inbound traffic from a certain 6443 smsc link connected to bearerbox, you need to separate in the scope of 6444 bearerbox where the inbound message will be going to. An example may 6445 look like this: 6446 6447<programlisting> 6448group = smsbox 6449... 6450smsbox-id = mysmsc 6451... 6452 6453group = smsbox-route 6454smsbox-id = mysmsc 6455shortcode = "1111;2222;3333" 6456</programlisting> 6457 6458 Which means any inbound message with receiver number 1111, 2222 or 3333 6459 will be delivered to the smsbox instance that has identified itself 6460 via the id "mysmsc" to bearerbox. Using this routing the smsbox instance 6461 (which may be an EMI/UCP or SMPP proxy) is able to send a deliver_sm PDU. 6462 Another example showing the combination use of criteria smsc-id and 6463 shortcode looks like this: 6464 6465<programlisting> 6466group = smsbox 6467... 6468smsbox-id = mysmsc 6469... 6470 6471group = smsbox-route 6472smsbox-id = mysmsc 6473smsc-id = "A;B;C" 6474shortcode = "1111;2222" 6475</programlisting> 6476 6477 Which means any inbound message with receiver number 1111 or 2222 that have 6478 been originating from the smsc-id connections A, B or C will be delivered 6479 to the via the id "mysmsc" to bearerbox. 6480 </para> 6481 6482 <para>smsbox-route inherits from core the following fields: 6483 </para> 6484 6485 <table frame="none"> 6486 <title>Smsbox-route Group Variables</title> 6487 <tgroup cols="3"> 6488 <thead> 6489 <row> 6490 <entry>Variable</entry> 6491 <entry>Value</entry> 6492 <entry>Description</entry> 6493 </row> 6494 </thead> 6495 <tbody> 6496 <row><entry><literal>group (m)</literal></entry> 6497 <entry><literal>smsbox-route</literal></entry> 6498 <entry valign="bottom"> 6499 This is a mandatory variable 6500 </entry></row> 6501 6502 <row><entry><literal>smsbox-id (m)</literal></entry> 6503 <entry><literal>string</literal></entry> 6504 <entry valign="bottom"> 6505 Defines for which smsbox instance the routing rules do apply. 6506 </entry></row> 6507 6508 <row><entry><literal>smsc-id</literal></entry> 6509 <entry>word-list</entry> 6510 <entry valign="bottom"> 6511 If set, specifies from which smsc-ids all inbound messages should 6512 be routed to this smsbox instance. List contains smsc-ids separated 6513 by semicolon (";"). This rule may be used to pull any smsc specific 6514 message stream to an smsbox instance. If used in combination with 6515 config directive shortcode, then this is another matching criteria 6516 for the routing decission. 6517 </entry></row> 6518 6519 <row><entry><literal>shortcode</literal></entry> 6520 <entry>number-list</entry> 6521 <entry valign="bottom"> 6522 If set, specifies which receiver numbers for inbound messages should 6523 be routed to this smsbox instance. List contains numbers separated 6524 by semicolon (";"). This rule may be used to pull receiver number 6525 specific message streams to an smsbox instance. If used in combination 6526 with config directive smsc-id, then only messages originating from 6527 the connections in the smsc-id are matched against the shortcode list. 6528 </entry></row> 6529 6530 </tbody> 6531 </tgroup> 6532 </table> 6533 6534</sect2> 6535 6536<sect2> 6537<title>SMS-service configurations</title> 6538 6539 <para>Now that you have an SMS center connection to send and 6540 receive SMS messages you need to define services for incoming 6541 messages. This is done via 'sms-service' configuration 6542 groups.</para> 6543 6544 <para>These groups define SMS services in the smsbox, so they are only 6545 used by the smsbox. Each service is recognized from the first word 6546 in an SMS message and by the number of arguments accepted by the 6547 service configuration (unless <literal>catch-all</literal> 6548 configuration variable is used). By adding a username and password in the URL 6549 in the following manner 6550 "http://luser:password@host.domain:port/path?query" we can perform 6551 HTTP Basic authentication.</para> 6552 6553 <para>The simplest service group looks like this: 6554 6555<programlisting> 6556group = sms-service 6557keyword = www 6558get-url = "http://%S" 6559</programlisting> 6560 6561 This service grabs any SMS with two words and 'www' as the first 6562 word, and then does an HTTP request to an URL which is taken from 6563 the rest of the message. Any result is sent back to the phone 6564 (or requester), but is truncated to the 160 characters that will 6565 fit into an SMS message, naturally.</para> 6566 6567 <para>Service group <literal>default</literal> has a special 6568 meaning: if the incoming message is not routed to any other 6569 service, <literal>default</literal> 'sms-service' group is used. 6570 You should always define <literal>default</literal> service.</para> 6571 6572 <para>Service group <literal>black-list</literal> has a special 6573 meaning: if the incoming message is in service's black-list, this 6574 service is used to reply to user. If unset, message will be 6575 discarded.</para> 6576 6577 <table frame="none"> 6578 <title>SMS-Service Group Variables</title> 6579 <tgroup cols="3"> 6580 <thead> 6581 <row> 6582 <entry>Variable</entry> 6583 <entry>Value</entry> 6584 <entry>Description</entry> 6585 </row> 6586 </thead> 6587 <tbody> 6588 <row><entry><literal>group (m)</literal></entry> 6589 <entry><literal>sms-service</literal></entry> 6590 <entry valign="bottom"> 6591 This is a mandatory variable 6592 </entry></row> 6593 6594 <row><entry><literal>keyword (m)</literal></entry> 6595 <entry>word</entry> 6596 <entry valign="bottom"> 6597 Services are identified by the first word in the SMS. Each 6598 `%s' in the URL corresponds to one word in the SMS message. 6599 Words are separated with spaces. A keyword is matched only if 6600 the number of words in the SMS message is the same as the 6601 number of `%s' fields in the URL. This allows you to 6602 configure the gateway to use different URLs for the same 6603 keyword depending on the number of words the SMS message 6604 contains. The keyword is case insensitive, which means you don't 6605 have to use aliases to handle different cased versions of your keyword. 6606 </entry></row> 6607 6608 <row><entry><literal>keyword-regex</literal></entry> 6609 <entry>POSIX regular expression</entry> 6610 <entry valign="bottom"> 6611 This field may be used to enable service-selection based on a regular expression. 6612 You can define either keyword or keyword-regex in configuration, but not both in 6613 the same sms-service. keyword-regex is case sensitive. 6614 See section on <xref linkend="regular-expressions"/> for details. 6615 </entry></row> 6616 6617 <row><entry><literal>aliases</literal></entry> 6618 <entry>word-list</entry> 6619 <entry valign="bottom"> 6620 If the service has aliases, they are listed as a list with 6621 each entry separated with a semicolon (';'). Aliases are case 6622 insensitive just like keyword. 6623 6624 </entry></row> 6625 6626 <row><entry><literal>name</literal></entry> 6627 <entry>string</entry> 6628 <entry valign="bottom"> 6629 Optional name to identify the service in logs. If unset, 6630 <literal>keyword</literal> is used. 6631 </entry></row> 6632 6633 <row><entry><literal>get-url (c)</literal></entry> 6634 <entry>URL</entry> 6635 <entry valign="bottom"> 6636 Requested URL. The url can include a list of parameters, which are 6637 parsed before the url is fetched. See below for these 6638 parameters. Also works with plain 'url' 6639 6640 </entry></row> 6641 6642 <row><entry><literal>post-url (c)</literal></entry> 6643 <entry>URL</entry> 6644 <entry valign="bottom"> 6645 Requested URL. As above, but request is done as POST, not GET. 6646 Always matches the keyword, regardless of pattern matching. 6647 See notes on POST other where. 6648 6649 </entry></row> 6650 6651 6652 <row><entry><literal>post-xml (c)</literal></entry> 6653 <entry>URL</entry> 6654 <entry valign="bottom"> 6655 Requested URL. As above, but request is done as XML POST. 6656 Always matches the keyword, regardless of pattern matching. 6657 See notes on POST other where and <xref 6658 linkend="postxml" endterm="postxml.title"/> 6659 </entry></row> 6660 6661 <row><entry><literal>file (c)</literal></entry> 6662 <entry>filename</entry> 6663 <entry valign="bottom"> 6664 File read from a local disc. Use this variable only if no 6665 <literal>url</literal> is set. All escape codes (parameters) 6666 in <literal>url</literal> are supported in filename. 6667 The last character of the file (usually linefeed) is removed. 6668 6669 </entry></row> 6670 6671 <row><entry><literal>text (c)</literal></entry> 6672 <entry>string</entry> 6673 <entry valign="bottom"> 6674 Predefined text answer. Only if there is neither <literal>url</literal> nor 6675 <literal>file</literal> set. Escape codes (parameters) are 6676 usable here, too. 6677 6678 </entry></row> 6679 6680 <row><entry><literal>exec (c)</literal></entry> 6681 <entry>string</entry> 6682 <entry valign="bottom"> 6683 Executes the given shell command as the current UID of the 6684 running smsbox user and returns the output to 6685 <literal>stdout</literal> as reply. 6686 Escape codes (parameters) are 6687 usable here, too. BEWARE: You may harm your system if you use 6688 this sms-service type without serious caution! Make sure anyone 6689 who is allowed to use these kind of services is checked using 6690 white/black-list mechanisms for security reasons. 6691 </entry></row> 6692 6693 <row><entry><literal>accepted-smsc</literal></entry> 6694 <entry>id-list</entry> 6695 <entry valign="bottom"> 6696 Accept ONLY SMS messages arriving from SMSC with matching ID. 6697 <footnote><para>Even if this service is denied, 6698 Kannel still searches for other service which accepts the message, 6699 or default service.</para></footnote> 6700 Separate multiple entries with ';'. For example, if 6701 <literal>accepted-smsc</literal> 6702 is "RL;SON", accept messages which originate from SMSC with 6703 ID set as 'RL' or 'SON' 6704 </entry></row> 6705 6706 <row><entry><literal>accepted-account</literal></entry> 6707 <entry>id-list</entry> 6708 <entry valign="bottom"> 6709 Accept ONLY SMS messages arriving with a matching ACCOUNT field. 6710 <footnote><para>Even if this service is denied, 6711 Kannel still searches for other service which accepts the message, 6712 or default service.</para></footnote> 6713 Separate multiple entries with ';'. For example, if 6714 <literal>accepted-account</literal> 6715 is "FOO;BAR", accept messages which originate with the ACCOUNT 6716 field set as 'FOO' or 'BAR' 6717 </entry></row> 6718 6719 <row><entry><literal>allowed-prefix</literal></entry> 6720 <entry><literal>prefix-list</literal></entry> 6721 <entry valign="bottom"> 6722 A list of phone number prefixes of the sender number which are 6723 accepted to be received by this service. 6724 <footnote><para>Like in accepted-smsc, 6725 Kannel still searches for other service which accepts the message. 6726 This way there could be several services with the same keyword and 6727 different results.</para></footnote> 6728 Multiple entries are separated with 6729 semicolon (';'). For example, "91;93" selects this service for 6730 these prefixes. 6731 If denied-prefix is unset, only this numbers are allowed. If 6732 denied is set, number are allowed if present in allowed or not 6733 in denied list. 6734 </entry></row> 6735 6736 <row><entry><literal>denied-prefix</literal></entry> 6737 <entry><literal>prefix-list</literal></entry> 6738 <entry valign="bottom"> 6739 A list of phone number prefixes of the sender number which are 6740 NOT accepted to be sent through this SMSC. 6741 </entry></row> 6742 6743 <row><entry><literal>allowed-receiver-prefix</literal></entry> 6744 <entry><literal>prefix-list</literal></entry> 6745 <entry valign="bottom"> 6746 A list of phone number prefixes of the receiver number which are 6747 accepted to be received by this service. This may be used to 6748 allow only inbound SMS to certain shortcut numbers to be allowed 6749 to this service. 6750 </entry></row> 6751 6752 <row><entry><literal>denied-receiver-prefix</literal></entry> 6753 <entry><literal>prefix-list</literal></entry> 6754 <entry valign="bottom"> 6755 A list of phone number prefixes of the receiver number which are 6756 NOT accepted to be sent through this SMSC. 6757 </entry></row> 6758 6759 6760 <row><entry><literal>catch-all</literal></entry> 6761 <entry>bool</entry> 6762 <entry valign="bottom"> 6763 Catch keyword regardless of '%s' parameters in pattern. 6764 6765 </entry></row> 6766 6767 <row><entry><literal>send-sender</literal></entry> 6768 <entry>bool</entry> 6769 <entry valign="bottom"> 6770 Used only with POST. If set to true, number of the handset is 6771 set, otherwise not. 6772 </entry></row> 6773 6774 <row><entry><literal>strip-keyword</literal></entry> 6775 <entry>bool</entry> 6776 <entry valign="bottom"> 6777 Used only with POST. Remove matched keyword from message text 6778 before sending it onward. 6779 </entry></row> 6780 6781 <row><entry><literal>faked-sender</literal></entry> 6782 <entry>phone-number</entry> 6783 <entry valign="bottom"> 6784 This number is set as sender. Most SMS centers ignore this, 6785 and use their fixed number instead. This option 6786 overrides all other sender setting methods. 6787 </entry></row> 6788 6789 <row><entry><literal>max-messages</literal></entry> 6790 <entry>number</entry> 6791 <entry valign="bottom"> 6792 If the message to be sent is longer than maximum length of an SMS 6793 it will be split into several parts. <literal>max-messages</literal> 6794 lets you specify a maximum number of individual SMS messages that 6795 can be used. If 6796 <literal>max-messages</literal> is set to 0, no reply is sent, 6797 except for error messages. 6798 </entry></row> 6799 6800 <row><entry><literal>accept-x-kannel-headers</literal></entry> 6801 <entry>bool</entry> 6802 <entry valign="bottom"> 6803 Request reply can include special X-Kannel headers but these 6804 are only accepted if this variable is set to true. See 6805 <xref linkend="xkannel" endterm="xkannel.title"/>. 6806 </entry></row> 6807 6808 <row><entry><literal>assume-plain-text</literal></entry> 6809 <entry>bool</entry> 6810 <entry valign="bottom"> 6811 If client does not set Content-Type for reply, it is normally 6812 application/octet-stream which is then handled as data in 6813 Kannel. This can be forced to be plain/text to allow backward 6814 compatibility, when data was not expected. 6815 </entry></row> 6816 6817 <row><entry><literal>concatenation</literal></entry> 6818 <entry>bool</entry> 6819 <entry valign="bottom"> 6820 Long messages can be sent as independent SMS messages with 6821 <literal>concatenation = false</literal> or as concatenated messages 6822 with <literal>concatenation = true</literal>. Concatenated messages 6823 are reassembled into one long message by the receiving device. 6824 </entry></row> 6825 6826 <row><entry><literal>split-chars</literal></entry> 6827 <entry>string</entry> 6828 <entry valign="bottom"> 6829 Allowed characters to split the message into several messages. 6830 So, with "#!" the message is split from last '#' or '!', which is 6831 included in the previous part. 6832 6833 </entry></row> 6834 6835 <row><entry><literal>split-suffix</literal></entry> 6836 <entry>string</entry> 6837 <entry valign="bottom"> 6838 If the message is split into several ones, this string is appended to 6839 each message except the last one. 6840 </entry></row> 6841 6842 <row><entry><literal>omit-empty</literal></entry> 6843 <entry>bool</entry> 6844 <entry valign="bottom"> 6845 Normally, Kannel sends a warning to the user if there was an 6846 empty reply from the service provider. If 6847 <literal>omit-empty</literal> is set to 'true', Kannel will send 6848 nothing at all in such a case. 6849 6850 </entry></row> 6851 6852 <row><entry><literal>header</literal></entry> 6853 <entry>string</entry> 6854 <entry valign="bottom"> 6855 If specified, this string is automatically added to each SMS sent with 6856 this service. If the message is split, it is added to each part. 6857 6858 </entry></row> 6859 6860 <row><entry><literal>footer</literal></entry> 6861 <entry>string</entry> 6862 <entry valign="bottom"> 6863 As header, but not inserted into head but appended to end. 6864 6865 </entry></row> 6866 6867 <row><entry><literal>prefix</literal></entry> 6868 <entry>string</entry> 6869 <entry morerows="1" valign="bottom"> 6870 Stuff in answer that is cut away, only things between prefix 6871 and suffix is left. Not case sensitive. Matches the first prefix 6872 and then the first suffix. These are only used for 6873 <literal>url</literal> type services, and only if both are 6874 specified. 6875 </entry></row> 6876 6877 <row><entry><literal>suffix</literal></entry> 6878 <entry>string</entry></row> 6879 6880 <row><entry><literal>white-list</literal></entry> 6881 <entry>URL</entry> 6882 <entry valign="bottom"> 6883 Load a list of accepted senders of SMS messages. If a 6884 sender of an SMS message is not in this list, any message 6885 received from the SMSC is rejected, unless a <literal> 6886 black-list</literal> service is defined. See notes of phone 6887 number format from numhash.h header file. 6888 </entry></row> 6889 6890 <row><entry><literal>black-list</literal></entry> 6891 <entry>URL</entry> 6892 <entry valign="bottom"> 6893 As white-list, but SMS messages from these numbers are 6894 automatically discarded 6895 </entry></row> 6896 6897 <row><entry><literal>accepted-smsc-regex</literal></entry> 6898 <entry>POSIX regular expression</entry> 6899 <entry valign="bottom"> 6900 Accept only SMS messages arriving from SMSCs with a matching ID. 6901 <footnote><para>Even if this service is denied, 6902 Kannel still searches for other service which accepts the message, 6903 or default service.</para></footnote> 6904 See section on <xref linkend="regular-expressions"/> for details. 6905 </entry> 6906 </row> 6907 6908 <row><entry><literal>accepted-account-regex</literal></entry> 6909 <entry>POSIX regular expression</entry> 6910 <entry valign="bottom"> 6911 Accept ONLY SMS messages arriving with a matching ACCOUNT field. 6912 <footnote><para>Even if this service is denied, 6913 Kannel still searches for other service which accepts the message, 6914 or default service.</para></footnote> 6915 See section on <xref linkend="regular-expressions"/> for details. 6916 </entry> 6917 </row> 6918 6919 <row><entry><literal>allowed-prefix-regex</literal></entry> 6920 <entry>POSIX regular expression</entry> 6921 <entry valign="bottom"> 6922 A set of phone number prefixes of sender-numbers accepted by this service. 6923 <footnote><para>Like in accepted-smsc-regex, 6924 Kannel still searches for another service which accepts the message. 6925 This way there could be several services with the same keyword and 6926 different results.</para></footnote> 6927 See section on <xref linkend="regular-expressions"/> for details. 6928 </entry> 6929 </row> 6930 6931 <row><entry><literal>denied-prefix-regex</literal></entry> 6932 <entry>POSIX regular expression</entry> 6933 <entry valign="bottom"> 6934 A set of phone number prefixes of sender-numbers which may 6935 not use this service. 6936 See section on <xref linkend="regular-expressions"/> for details. 6937 </entry> 6938 </row> 6939 6940 <row><entry><literal>allowed-receiver-prefix-regex</literal></entry> 6941 <entry>POSIX regular expression</entry> 6942 <entry valign="bottom"> 6943 A set of phone number prefixes of receiver-numbers which 6944 may receive data sent by this service. This can be used to 6945 allow only inbound SMS to certain shortcut numbers to be allowed 6946 to this service. 6947 See section on <xref linkend="regular-expressions"/> for details. 6948 </entry> 6949 </row> 6950 6951 <row><entry><literal>denied-receiver-prefix-regex</literal></entry> 6952 <entry>POSIX regular expression</entry> 6953 <entry valign="bottom"> 6954 A set of phone number prefixes of receiver-numbers which may not 6955 receive data sent by this service. 6956 See section on <xref linkend="regular-expressions"/> for details. 6957 </entry> 6958 </row> 6959 6960 <row><entry><literal>white-list-regex</literal></entry> 6961 <entry>POSIX regular expression</entry> 6962 <entry valign="bottom"> 6963 Defines a set of accepted senders of SMS messages. If a 6964 sender of an SMS message is not in this list, the message is rejected. 6965 See section on <xref linkend="regular-expressions"/> for details. 6966 </entry> 6967 </row> 6968 6969 <row><entry><literal>black-list-regex</literal></entry> 6970 <entry>POSIX regular expression</entry> 6971 <entry valign="bottom"> 6972 As white-list-regex, but SMS messages from these numbers are 6973 automatically discarded. 6974 See section on <xref linkend="regular-expressions"/> for details. 6975 </entry> 6976 </row> 6977 6978 <row><entry><literal>alt-charset</literal></entry> 6979 <entry>string</entry> 6980 <entry valign="bottom"> 6981 Defines which character encoding is used for the SMS message when 6982 passed to a remote HTTP application. This includes how the SMS message 6983 text is send in the HTTP GET parameter list and in the HTTP POST bidy. 6984 Uses <literal>iconv()</literal> routines to convert from and to that 6985 specific character set encoding. 6986 See your local <literal>iconv_open(3)</literal> manual page for the 6987 supported character encodings and the type strings that should be 6988 presented for this directive. 6989 </entry> 6990 </row> 6991 6992 <row><entry><literal>dlr-url</literal></entry> 6993 <entry>string (URL)</entry> 6994 <entry valign="bottom"> 6995 Optional Defines a default URL which is fetched for DLR event, if no 6996 specific X-Kannel HTTP header parameter is returned by the HTTP response. 6997 </entry> 6998 </row> 6999 7000 <row><entry><literal>dlr-mask</literal></entry> 7001 <entry>number (bit mask)</entry> 7002 <entry valign="bottom"> 7003 Optional. Defines a default DLR event bit mask which is used in 7004 combination with the <literal>dlr-url</literal> config directive, 7005 if no specific X-Kannel HTTP header parameter is returned by the 7006 HTTP response. 7007 </entry> 7008 </row> 7009 7010 </tbody> 7011 </tgroup> 7012 </table> 7013 7014 7015 7016 7017 7018 7019 <table frame="none" id="escapecodes"> 7020 <title id="escapecodes.title">Parameters (Escape Codes)</title> 7021 <tgroup cols="2"> 7022 <tbody> 7023 7024<row><entry><literal>%k</literal></entry><entry> 7025the keyword in the SMS request (i.e., the first word in the SMS message) 7026 7027</entry></row> 7028 7029<row><entry><literal>%s</literal></entry><entry> 7030next word from the SMS message, starting with 7031 the second one (i.e., the first word, the 7032 keyword, is not included); problematic characters 7033 for URLs are encoded (e.g., '+' becomes '%2B') 7034 7035</entry></row> 7036 7037<row><entry><literal>%S</literal></entry><entry> 7038same as %s, but '*' is converted to '~' (useful 7039 when user enters a URL) and URL encoding isn't done 7040 (all others do URL encode) 7041</entry></row> 7042 7043<row><entry><literal>%r</literal></entry><entry> 7044words not yet used by %s; e.g., if the message 7045 is "FOO BAR FOOBAR BAZ", and the has been one %s, 7046 %r will mean "FOOBAR BAZ" 7047</entry></row> 7048 7049<row><entry><literal>%a</literal></entry><entry> 7050all words of the SMS message, including the first one, with spaces 7051squeezed to one 7052</entry></row> 7053 7054<row><entry><literal>%b</literal></entry><entry> 7055the original SMS message, in a binary form 7056</entry></row> 7057 7058<row><entry><literal>%t</literal></entry><entry> 7059the time the message was sent, formatted as 7060 "YYYY-MM-DD HH:MM", e.g., "1999-09-21 14:18" 7061</entry></row> 7062 7063<row><entry><literal>%T</literal></entry><entry> 7064the time the message was sent, in UNIX epoch timestamp format 7065</entry></row> 7066 7067<row><entry><literal>%p</literal></entry><entry> 7068the phone number of the sender of the SMS message 7069</entry></row> 7070 7071<row><entry><literal>%P</literal></entry><entry> 7072the phone number of the receiver of the SMS message 7073</entry></row> 7074 7075<row><entry><literal>%q</literal></entry><entry> 7076like %p, but a leading `00' is replaced with `+' 7077</entry></row> 7078 7079<row><entry><literal>%Q</literal></entry><entry> 7080like %P, but a leading `00' is replaced with `+' 7081</entry></row> 7082 7083<row><entry><literal>%i</literal></entry><entry> 7084the smsc-id of the connection that received the message 7085</entry></row> 7086 7087<row><entry><literal>%I</literal></entry><entry> 7088the SMS ID of the internal message structure 7089</entry></row> 7090 7091<row><entry><literal>%d</literal></entry><entry> 7092the delivery report value 7093</entry></row> 7094 7095<row><entry><literal>%R</literal></entry><entry> 7096the delivery report URL value 7097</entry></row> 7098 7099<row><entry><literal>%D</literal></entry><entry> 7100meta-data from the SMSC. See <xref linkend="meta-data"/> for more into. 7101</entry></row> 7102 7103<row><entry><literal>%A</literal></entry><entry> 7104the delivery report SMSC reply, if any 7105</entry></row> 7106 7107<row><entry><literal>%F</literal></entry><entry> 7108the <literal>foreign</literal> (smsc-provided) message ID. Only 7109relevant on DLR url's. 7110</entry></row> 7111 7112<row><entry><literal>%n</literal></entry><entry> 7113the sendsms-user or sms-service name 7114</entry></row> 7115 7116<row><entry><literal>%c</literal></entry><entry> 7117message coding: 0 (default, 7 bits), 1 (8 bits) or 2 (Unicode) 7118</entry></row> 7119 7120<row><entry><literal>%m</literal></entry><entry> 7121message class bits of DCS: 0 (directly to display, flash), 71221 (to mobile), 2 (to SIM) or 3 (to SIM toolkit). 7123</entry></row> 7124 7125<row><entry><literal>%M</literal></entry><entry> 7126mwi (message waiting indicator) bits of DCS: 71270 (voice), 1, (fax), 2 (email) or 3 (other) for activation 7128and 4, 5, 6, 7 for deactivation respectively. 7129</entry></row> 7130 7131<row><entry><literal>%C</literal></entry><entry> 7132message charset: for a "normal" message, it will 7133be "GSM" (coding=0), "binary" (coding=1) or 7134"UTF-16BE" (coding=2). If the message was successfully 7135recoded from Unicode, it will be "WINDOWS-1252" 7136</entry></row> 7137 7138<row><entry><literal>%u</literal></entry><entry> 7139<literal>udh</literal> of incoming message 7140</entry></row> 7141 7142<row><entry><literal>%B</literal></entry><entry> 7143billing identifier/information of incoming message. The value 7144depends on the SMSC module and the associated billing semantics 7145of the specific SMSC providing the information. For EMI2 the value 7146is the XSer 0c field, for SMPP MO it is the service_type of the 7147deliver_sm PDU, and for SMPP DLR it is the DLR message err component. 7148(Note: This is used for proxying billing 7149information to external applications. There is no semantics 7150associated while processing these.) 7151</entry></row> 7152 7153<row><entry><literal>%o</literal></entry><entry> 7154account identifier/information of incoming message. The value 7155depends on the SMSC module and has been introduced to allow the 7156forwarding of an operator ID from aggregator SMSCs to the application 7157layer, hence the smsbox HTTP calling instance. 7158</entry></row> 7159 7160<row><entry><literal>%O</literal></entry><entry> 7161DCS (Data coding schema) value. 7162</entry></row> 7163 7164<row><entry><literal>%f</literal></entry><entry> 7165Originating SMSC of incoming message. The value is set if 7166the AT driver is used to receive a SMS on a gsm modem. 7167The value of %f will contain the number of the SMSC sending 7168the SMS to the SIM card. Other SMSC types than AT do not 7169set this field so it will be empty. 7170</entry></row> 7171 7172<row><entry><literal>%x</literal></entry><entry> 7173the smsbox-id of the message, identifying from which smsbox connection 7174the message is originating. (Only available withing the 7175<literal>access-log-format</literal> directive) 7176</entry></row> 7177 7178<row><entry><literal>%v</literal></entry><entry> 7179Validity period in minutes. Available only if SMSC supports 7180and sent this value. 7181</entry></row> 7182 7183<row><entry><literal>%V</literal></entry><entry> 7184Deferred in minutes. Available only if SMSC supports 7185and sent this value. 7186</entry></row> 7187 7188<row><entry><literal>%#</literal></entry><entry> 7189This allows to pass meta-data individual parameters into urls. 7190The syntax is as follows: <literal>%#group#parameter#</literal> 7191For example: <literal>%#smpp#my_param#</literal> would be replaced 7192with the value 'my_param' from the group 'smpp' coming inside the 7193meta_data field. 7194</entry></row> 7195 7196</tbody> 7197</tgroup> 7198</table> 7199 7200 7201 7202 <para>Some sample 'sms-service' groups: 7203 7204<programlisting> 7205group = sms-service 7206keyword = nop 7207text = "You asked nothing and I did it!" 7208catch-all = true 7209 7210group = sms-service 7211keyword = complex 7212get-url = "http://host/service?sender=%p&text=%r" 7213accept-x-kannel-headers = true 7214max-messages = 3 7215concatenation = true 7216 7217group = sms-service 7218keyword = default 7219text = "No action specified" 7220</programlisting> 7221</para> 7222 7223 7224</sect2> 7225 7226 7227<sect2> 7228<title>How sms-service interprets the HTTP response</title> 7229 7230 <para>When an <literal>sms-service</literal> requests a document 7231 via HTTP, it will accept one of four types of content types: 7232 7233 <informaltable frame="none"> 7234 <tgroup cols="2"> 7235 <tbody> 7236 7237 <row> 7238 <entry><literal>text/plain</literal></entry> 7239 <entry>Blanks are squeezed into one, rest is chopped to fit an 7240 SMS message.</entry> 7241 </row> 7242 7243 <row> 7244 <entry><literal>text/html</literal></entry> 7245 <entry>Tags are removed, rest is chopped to fit an 7246 SMS message.</entry> 7247 </row> 7248 7249 <row> 7250 <entry><literal>text/vnd.wap.wml</literal></entry> 7251 <entry>Processed like HTML.</entry> 7252 </row> 7253 7254 <row> 7255 <entry><literal>text/xml</literal></entry> 7256 <entry>Processed as a POST-XML. See <xref 7257 linkend="postxml" endterm="postxml.title"/></entry> 7258 </row> 7259 7260 <row> 7261 <entry><literal>application/octet-stream</literal></entry> 7262 <entry>The body will be transmitted as the SMS message, as 7263 8-bit data. This can be avoided by setting 7264 <literal>assume-plain-text</literal> variable on for the 7265 SMS-service.</entry> 7266 </row> 7267 7268 </tbody> 7269 </tgroup> 7270 </informaltable> 7271 7272 </para> 7273 7274 7275<sect3 id="xkannel"> 7276<title id="xkannel.title">Extended headers</title> 7277 7278 <para>Kannel uses and accepts several X-Kannel headers to be 7279 used with SMS-services, if option 7280 <literal>accept-x-kannel-headers</literal> was provided in the 7281 relevant 'sms-service' group.</para> 7282 7283 <table frame="none"> 7284 <title>X-Kannel Headers</title> 7285 <tgroup cols="2"> 7286 <thead> 7287 <row> 7288 <entry>SMSPush equivalent</entry> 7289 <entry>X-Kannel Header</entry> 7290 </row> 7291 </thead> 7292 <tbody> 7293 <row><entry><literal>username</literal></entry> 7294 <entry><literal>X-Kannel-Username</literal></entry></row> 7295 7296 <row><entry><literal>password</literal></entry> 7297 <entry><literal>X-Kannel-Password</literal></entry></row> 7298 7299 <row><entry><literal>from</literal></entry> 7300 <entry><literal>X-Kannel-From</literal></entry></row> 7301 7302 <row><entry><literal>to</literal></entry> 7303 <entry><literal>X-Kannel-To</literal></entry></row> 7304 7305 <row><entry><literal>text</literal></entry> 7306 <entry>request body</entry></row> 7307 7308 <row><entry><literal>charset</literal></entry> 7309 <entry>charset as in <literal>Content-Type: text/html; charset=ISO-8859-1</literal></entry></row> 7310 7311 <row><entry><literal>udh</literal></entry> 7312 <entry><literal>X-Kannel-UDH</literal></entry></row> 7313 7314 <row><entry><literal>smsc</literal></entry> 7315 <entry><literal>X-Kannel-SMSC</literal></entry></row> 7316 7317 <row><entry><literal>flash</literal></entry> 7318 <entry><literal>X-Kannel-Flash</literal> (deprecated, see <literal>X-Kannel-MClass</literal></entry></row> 7319 7320 <row><entry><literal>mclass</literal></entry> 7321 <entry><literal>X-Kannel-MClass</literal></entry></row> 7322 7323 <row><entry><literal>mwi</literal></entry> 7324 <entry><literal>X-Kannel-MWI</literal></entry></row> 7325 7326 <row><entry><literal>compress</literal></entry> 7327 <entry><literal>X-Kannel-Compress</literal></entry></row> 7328 7329 <row><entry><literal>coding</literal></entry> 7330 <entry><literal>X-Kannel-Coding</literal>. If unset, defaults to 0 7331 (7 bits) if <literal>Content-Type</literal> is <literal>text/plain 7332 </literal>, <literal>text/html</literal> or 7333 <literal>text/vnd.wap.wml</literal>. On 7334 <literal>application/octet-stream</literal>, defaults to 7335 8 bits (1). All other <literal>Content-Type</literal> values 7336 are rejected.</entry></row> 7337 7338 <row><entry><literal>validity</literal></entry> 7339 <entry><literal>X-Kannel-Validity</literal></entry></row> 7340 7341 <row><entry><literal>deferred</literal></entry> 7342 <entry><literal>X-Kannel-Deferred</literal></entry></row> 7343 7344 <row><entry><literal>dlr-mask</literal></entry> 7345 <entry><literal>X-Kannel-DLR-Mask</literal></entry></row> 7346 7347 <row><entry><literal>dlr-url</literal></entry> 7348 <entry><literal>X-Kannel-DLR-Url</literal></entry></row> 7349 7350 <row><entry><literal>account</literal></entry> 7351 <entry><literal>X-Kannel-Account</literal></entry></row> 7352 7353 <row><entry><literal>pid</literal></entry> 7354 <entry><literal>X-Kannel-PID</literal></entry></row> 7355 7356 <row><entry><literal>alt-dcs</literal></entry> 7357 <entry><literal>X-Kannel-Alt-DCS</literal></entry></row> 7358 7359 <row><entry><literal>binfo</literal></entry> 7360 <entry><literal>X-Kannel-BInfo</literal></entry></row> 7361 7362 <row><entry><literal>rpi</literal></entry> 7363 <entry><literal>X-Kannel-RPI</literal></entry></row> 7364 7365 <row><entry><literal>priority</literal></entry> 7366 <entry><literal>X-Kannel-Priority</literal></entry></row> 7367 7368 <row><entry><literal>meta-data</literal></entry> 7369 <entry><literal>X-Kannel-Meta-Data</literal></entry></row> 7370 7371 </tbody> 7372 </tgroup> 7373 </table> 7374 7375</sect3> 7376 7377 7378<sect3 id="kannelpost"> 7379<title id="kannelpost.title">Kannel POST</title> 7380 7381 <para>Kannel can do POST if <literal>service</literal> is 7382 contains a <literal>post-url="..."</literal>.</para> 7383 7384<table frame="none"> 7385 <title>X-Kannel Post Headers</title> 7386 <tgroup cols="2"> 7387 <thead> 7388 <row> 7389 <entry>Parameter (escape code) equivalent</entry> 7390 <entry>X-Kannel Header</entry> 7391 <entry>Notes</entry> 7392 </row> 7393 </thead> 7394 <tbody> 7395 <row><entry><literal>%p (from)</literal></entry> 7396 <entry><literal>X-Kannel-From</literal></entry> 7397 <entry>Only sent if <literal>send-sender</literal> is true</entry> </row> 7398 7399 <row><entry><literal>%P (to)</literal></entry> 7400 <entry><literal>X-Kannel-To</literal></entry> 7401 <entry></entry></row> 7402 7403 <row><entry><literal>%t (time)</literal></entry> 7404 <entry><literal>X-Kannel-Time</literal></entry> 7405 <entry></entry></row> 7406 7407 <row><entry><literal>%u (udh)</literal></entry> 7408 <entry><literal>X-Kannel-UDH</literal></entry> 7409 <entry>in hex format: <literal>06050415820000</literal></entry></row> 7410 7411 <row><entry><literal>%i (smsc)</literal></entry> 7412 <entry><literal>X-Kannel-SMSC</literal></entry> 7413 <entry></entry></row> 7414 7415 <row><entry><literal>- (mclass)</literal></entry> 7416 <entry><literal>X-Kannel-MClass</literal></entry> 7417 <entry></entry></row> 7418 7419 <row><entry><literal>- (pid)</literal></entry> 7420 <entry><literal>X-Kannel-PID</literal></entry> 7421 <entry></entry></row> 7422 7423 <row><entry><literal>- (alt-dcs)</literal></entry> 7424 <entry><literal>X-Kannel-Alt-DCS</literal></entry> 7425 <entry></entry></row> 7426 7427 <row><entry><literal>- (mwi)</literal></entry> 7428 <entry><literal>X-Kannel-MWI</literal></entry> 7429 <entry></entry></row> 7430 7431 <row><entry><literal>%c (coding)</literal></entry> 7432 <entry><literal>X-Kannel-Coding</literal></entry> 7433 <entry>0=7 Bits, 1=8 Bits, 2=UCS-2</entry></row> 7434 7435 <row><entry><literal>- (compress)</literal></entry> 7436 <entry><literal>X-Kannel-Compress</literal></entry> 7437 <entry></entry></row> 7438 7439 <row><entry><literal>- (validity)</literal></entry> 7440 <entry><literal>X-Kannel-Validity</literal></entry> 7441 <entry></entry></row> 7442 7443 <row><entry><literal>- (deferred)</literal></entry> 7444 <entry><literal>X-Kannel-Deferred</literal></entry> 7445 <entry></entry></row> 7446 7447 <row><entry><literal>%n (service name)</literal></entry> 7448 <entry><literal>X-Kannel-Service</literal></entry> 7449 <entry></entry></row> 7450 7451 <row><entry><literal>%D (meta-data)</literal></entry> 7452 <entry><literal>X-Kannel-Meta-Data</literal></entry> 7453 <entry>Meta-Data (Only SMPP TLV's supported at the moment)</entry></row> 7454 7455 <row><entry><literal>%a or %r (text)</literal></entry> 7456 <entry>request body</entry> 7457 <entry>Kannel send all words (%a) unless <literal>strip-keyword</literal> is true</entry></row> 7458 7459 <row><entry><literal>%C (charset)</literal></entry> 7460 <entry>present in <literal>Content-Type</literal> <literal>HTTP</literal></entry> 7461 <entry>Example: <literal>Content-Type: text/plain; charset=ISO-8859-1</literal></entry></row> 7462 7463 </tbody> 7464 </tgroup> 7465</table> 7466 7467</sect3> 7468 7469<sect3 id="postxml"> 7470<title id="postxml.title">XML Post</title> 7471 7472 <para>Kannel can send and receive XML POST with the following 7473 format:</para> 7474 7475<programlisting> 7476<?xml version="1.0"?> 7477<!DOCTYPE ...> 7478<message> 7479 <submit> 7480 <da><number>destination number (to)</number></da> 7481 <oa><number>originating number (from)</number></oa> 7482 <ud>user data (text)</ud> 7483 <udh>user data header (udh)</udh> 7484 <meta-data>meta-data</meta-data> 7485 <dcs> 7486 <mclass>mclass</mclass> 7487 <coding>coding</coding> 7488 <mwi>mwi</mwi> 7489 <compress>compress</compress> 7490 <alt-dcs>alt-dcs</alt-dcs> 7491 </dcs> 7492 <pid>pid</pid> 7493 <rpi>rpi</rpi> 7494 <vp> 7495 <delay>validity time in minutes</delay> 7496 </vp> 7497 <timing> 7498 <delay>deferred time in minutes</delay> 7499 </timing> 7500 <statusrequest> 7501 <dlr-mask>dlr-mask</dlr-mask> 7502 <dlr-url>dlr-url</dlr-url> 7503 </statusrequest> 7504 7505 <!-- request from application to Kannel --> 7506 <from> 7507 <user>username</user> 7508 <username>username</username> 7509 <pass>password</pass> 7510 <password>password</password> 7511 <account>account</account> 7512 </from> 7513 <to>smsc-id</to> 7514 7515 <!-- request from Kannel to application --> 7516 <from>smsc-id</from> 7517 <to>service-name</to> 7518 7519 </submit> 7520</message> 7521</programlisting> 7522 7523 <note><para>Don't forget to set POST Content-Type to 7524 <literal>text/xml</literal>!</para></note> 7525 7526 <para>There could be several <literal>da</literal> entries for <literal>sendsms-user 7527 </literal> to enable multi-recipient messages. <literal>da</literal> doesn't make 7528 sense in <literal>sms-service</literal>.</para> 7529 7530 <!-- 7531 <para><literal>ud</literal><note><para>DAVI: I still have to test binary and Unicode 7532 <ud> content</para></note></para> 7533 --> 7534 7535 <para><literal>udh</literal> is the same format as <literal>X-Kannel-UDH</literal>. 7536 Example: <udh>06050415820000</udh>.</para> 7537 7538 <para>On Kannel->application, <literal>from</literal> is the <literal>smsc-id</literal> 7539 that message arrives and <literal>to</literal> is the service name.</para> 7540 <para>On application->Kannel, <literal>from</literal> contains the credentials ( 7541 <literal>user/username</literal>, <literal>pass/password</literal> and <literal> 7542 account</literal> and <literal>to</literal> corresponds to the <literal>smsc-id 7543 </literal> to submit the message.</para> 7544 7545 <para><literal>user</literal> and <literal>username</literal> are equivalent and 7546 only one of them should be used. (same for <literal>pass</literal> and <literal> 7547 password</literal>.</para> 7548 7549 <para>When application POST in Kannel, as in GET, only <literal>user</literal>, <literal> 7550 pass</literal> and <literal>da</literal> are required. Everything else is optional. 7551 (<literal>oa</literal> could be needed too is there's no <literal>default-sender</literal> 7552 or <literal>forced-sender</literal>.</para> 7553 7554 <warning><para>This is experimental code. XML format could and should change to fully 7555 met IETF's sms-xml standard (yet in draft) and additional tags needed by Kannel should be 7556 pondered.</para></warning> 7557</sect3> 7558 7559</sect2> 7560 7561 7562<sect2> 7563<title>SendSMS-user configurations</title> 7564 7565 <para>To enable an SMS push, you must set 7566 <literal>sendsms-port</literal> into the 'smsbox' group and define one or 7567 more 'sendsms-user' groups. Each of these groups define one 7568 account, which can be used for the SMS push, via HTTP interface (see 7569 below)</para> 7570 7571 <table frame="none"> 7572 <title>SendSMS-User Group Variables</title> 7573 <tgroup cols="3"> 7574 <thead> 7575 <row> 7576 <entry>Variable</entry> 7577 <entry>Value</entry> 7578 <entry>Description</entry> 7579 </row> 7580 </thead> 7581 <tbody> 7582 <row><entry><literal>group (m)</literal></entry> 7583 <entry><literal>sendsms-user</literal></entry> 7584 <entry valign="bottom"> 7585 This is a mandatory variable 7586 </entry></row> 7587 7588 <row><entry><literal>username (m)</literal></entry> 7589 <entry>string</entry> 7590 <entry valign="bottom"> 7591 Name for the user/account. 7592 </entry></row> 7593 7594 <row><entry><literal>password (m)</literal></entry> 7595 <entry>string</entry> 7596 <entry valign="bottom"> 7597 Password for the user (see HTTP interface, below) 7598 </entry></row> 7599 7600 <row><entry><literal>name</literal></entry> 7601 <entry>string</entry> 7602 <entry valign="bottom"> 7603 As in 'sms-service' groups. 7604 </entry></row> 7605 7606 <row><entry><literal>user-deny-ip</literal></entry> 7607 <entry>IP-list</entry> 7608 <entry morerows="1" valign="bottom"> 7609 As other deny/allow IP lists, but for this user (i.e. this 7610 user is not allowed to do the SMS push HTTP request from 7611 other IPs than allowed ones). If not set, there is no 7612 limitations. 7613 </entry></row> 7614 <row><entry><literal>user-allow-IP</literal></entry> 7615 <entry>IP-list</entry></row> 7616 7617 <row><entry><literal>forced-smsc</literal></entry> 7618 <entry>string</entry> 7619 <entry valign="bottom"> 7620 Force SMSC ID as a 'string' (linked to SMS routing, see 'smsc' groups) 7621 </entry></row> 7622 7623 <row><entry><literal>default-smsc</literal></entry> 7624 <entry>string</entry> 7625 <entry valign="bottom"> 7626 If no SMSC ID is given with the send-sms request (see below), use 7627 this one. No idea to use with forced-smsc. 7628 </entry></row> 7629 7630 7631 <row><entry><literal>default-sender</literal></entry> 7632 <entry>phone-number</entry> 7633 <entry valign="bottom"> 7634 This number is set as sender if not set by <literal>from</literal> 7635 get/post parameter 7636 </entry></row> 7637 7638 <row><entry><literal>faked-sender</literal></entry> 7639 <entry>phone-number</entry> 7640 <entry valign="bottom"> 7641 As in 'sms-service' groups 7642 </entry></row> 7643 7644 <row><entry><literal>max-messages</literal></entry> 7645 <entry>number</entry></row> 7646 7647 <row><entry><literal>concatenation</literal></entry> 7648 <entry>bool</entry></row> 7649 7650 <row><entry><literal>split-chars</literal></entry> 7651 <entry>string</entry></row> 7652 7653 <row><entry><literal>split-suffix</literal></entry> 7654 <entry>string</entry></row> 7655 7656 <row><entry><literal>omit-empty</literal></entry> 7657 <entry>bool</entry></row> 7658 7659 <row><entry><literal>header</literal></entry> 7660 <entry>string</entry></row> 7661 7662 <row><entry><literal>footer</literal></entry> 7663 <entry>string</entry></row> 7664 7665 <row><entry><literal>allowed-prefix</literal></entry> 7666 <entry><literal>prefix-list</literal></entry> 7667 <entry valign="bottom"> 7668 A list of phone number prefixes which are accepted to be 7669 sent using this username. Multiple entries are separated with 7670 semicolon (';'). For example, "040;050" prevents sending of 7671 any SMS message with prefix of 040 or 050 through this SMSC. 7672 If denied-prefix is unset, only this numbers are allowed. If 7673 set, number are allowed if present in allowed or not in 7674 denied list. 7675 </entry></row> 7676 7677 <row><entry><literal>denied-prefix</literal></entry> 7678 <entry><literal>prefix-list</literal></entry> 7679 <entry valign="bottom"> 7680 A list of phone number prefixes which are NOT accepted to be 7681 sent using this username. 7682 </entry></row> 7683 7684 <row><entry><literal>white-list</literal></entry> 7685 <entry>URL</entry> 7686 <entry valign="bottom"> 7687 Load a list of accepted destinations of SMS messages. If a 7688 destination of an SMS message is not in this list, any message 7689 received from the HTTP interface is rejected. See notes of phone 7690 number format from numhash.h header file. 7691 </entry></row> 7692 7693 <row><entry><literal>black-list</literal></entry> 7694 <entry>URL</entry> 7695 <entry valign="bottom"> 7696 As white-list, but SMS messages from these numbers are 7697 automatically rejected. 7698 </entry></row> 7699 7700 <row><entry><literal>dlr-url</literal></entry> 7701 <entry>URL</entry> 7702 <entry valign="bottom"> 7703 URL to be fetched if a <literal>dlr-mask</literal> CGI 7704 parameter is present. 7705 </entry></row> 7706 7707 <row><entry><literal>allowed-prefix-regex</literal></entry> 7708 <entry>POSIX regular expression</entry> 7709 <entry valign="bottom"> 7710 A set of phone numbers which are accepted to be 7711 sent using this username. 7712 See section on <xref linkend="regular-expressions"/> for details. 7713 </entry> 7714 </row> 7715 7716 <row><entry><literal>denied-prefix-regex</literal></entry> 7717 <entry>POSIX regular expression</entry> 7718 <entry valign="bottom"> 7719 A set of phone numbers which may not 7720 send using this username. 7721 See section on <xref linkend="regular-expressions"/> for details. 7722 </entry> 7723 </row> 7724 7725 <row><entry><literal>white-list-regex</literal></entry> 7726 <entry>POSIX regular expression</entry> 7727 <entry valign="bottom"> 7728 Defines a set of accepted destinations of SMS messages. If a 7729 destination of an SMS message is not in this list, any message 7730 received from the HTTP interface is rejected. 7731 See section on <xref linkend="regular-expressions"/> for details. 7732 </entry> 7733 </row> 7734 7735 <row><entry><literal>black-list-regex</literal></entry> 7736 <entry>POSIX regular expression</entry> 7737 <entry valign="bottom"> 7738 As <literal>white-list-regex</literal>, but SMS messages originating from 7739 a number matching the pattern are discarded. 7740 See section on <xref linkend="regular-expressions"/> for details. 7741 </entry> 7742 </row> 7743 7744 </tbody> 7745 </tgroup> 7746 </table> 7747 7748 <para>Some sample 'sendsms-user' groups: 7749 7750<programlisting> 7751group = sendsms-user 7752username = simple 7753password = elpmis 7754 7755group = sendsms-user 7756username = complex 7757password = 76ftY 7758user-deny-ip = "*.*.*.*" 7759user-allow-ip = "123.234.123.234" 7760max-messages = 3 7761concatenation = true 7762forced-smsc = SOL 7763</programlisting> 7764 7765 The second one is very limited and only allows a user from IP 7766 "123.234.123.234". On the other hand, the user can send a longer 7767 message, up to 3 SMSes long, which is sent as concatenated 7768 SMS.</para> 7769 7770</sect2> 7771 7772<sect2> 7773<title>Over-The-Air configurations</title> 7774 7775 <para>To enable Over-The-Air configuration of phones or other client 7776 devices that support the protocol you need to configure a <literal> 7777 sendsms-user</literal>.<literal>ota-setting</literal> group is not 7778 necessary, you can send settings to the phone as a XML document, but 7779 this method is perhaps more suitable for continuous provisioning. 7780 </para> 7781 7782 <para>If you want to send multiple OTA configurations through the smsbox 7783 and you do not want to send XML documents, you will have to declare a 7784 <literal>ota-id</literal> string to the different <literal>ota-setting 7785 </literal> groups. 7786 </para> 7787 7788 <table frame="none"> 7789 <title>OTA Setting Group Variables</title> 7790 <tgroup cols="3"> 7791 <thead> 7792 <row> 7793 <entry>Variable</entry> 7794 <entry>Value</entry> 7795 <entry>Description</entry> 7796 </row> 7797 </thead> 7798 <tbody> 7799 <row><entry><literal>group</literal></entry> 7800 <entry><literal>ota-setting</literal></entry> 7801 <entry valign="bottom"> 7802 This is a mandatory variable 7803 </entry></row> 7804 7805 <row><entry><literal>ota-id</literal></entry> 7806 <entry><literal>string</literal></entry> 7807 <entry valign="bottom"> 7808 An optional name or id for the ota-setting. Any string is 7809 acceptable, but semicolon ';' may cause problems, so avoid 7810 it and any other special non-alphabet characters. 7811 </entry></row> 7812 7813 <row><entry><literal>location</literal></entry> 7814 <entry><literal>URL</literal></entry> 7815 <entry valign="bottom"> 7816 The address of the HTTP server for your WAP services, i.e. 7817 <literal>http://wap.company.com</literal> 7818 </entry></row> 7819 7820 <row><entry><literal>service</literal></entry> 7821 <entry><literal>string</literal></entry> 7822 <entry valign="bottom"> 7823 Description of the service 7824 </entry></row> 7825 7826 <row><entry><literal>ipaddress</literal></entry> 7827 <entry><literal>IP</literal></entry> 7828 <entry valign="bottom"> 7829 IP address of your WAP gateway 7830 </entry></row> 7831 7832 <row><entry><literal>phonenumber</literal></entry> 7833 <entry><literal>phone-number</literal></entry> 7834 <entry valign="bottom"> 7835 Phone number used to establish the PPP connection 7836 </entry></row> 7837 7838 <row><entry><literal>speed</literal></entry> 7839 <entry><literal>number</literal></entry> 7840 <entry valign="bottom"> 7841 Connection speed: 9600 or 14400. Defaults to 9600. 7842 </entry></row> 7843 7844 <row><entry><literal>bearer</literal></entry> 7845 <entry><literal>string</literal></entry> 7846 <entry valign="bottom"> 7847 Bearer type: data or sms. Defaults to data. 7848 </entry></row> 7849 7850 <row><entry><literal>calltype</literal></entry> 7851 <entry><literal>string</literal></entry> 7852 <entry valign="bottom"> 7853 Call type: isdn or analog. Defaults to isdn. 7854 </entry></row> 7855 7856 <row><entry><literal>connection</literal></entry> 7857 <entry><literal>string</literal></entry> 7858 <entry valign="bottom"> 7859 Connection type: cont or temp. Cont uses TCP port 9201 7860 and Temp uses UDP port 9200. Defaults to cont. 7861 </entry></row> 7862 7863 <row><entry><literal>pppsecurity</literal></entry> 7864 <entry><literal>on or off</literal></entry> 7865 <entry valign="bottom"> 7866 Enable CHAP authentication if set to on, PAP otherwise 7867 </entry></row> 7868 7869 <row><entry><literal>authentication</literal></entry> 7870 <entry><literal></literal></entry> 7871 <entry valign="bottom"> 7872 normal or secure. Indicates whether WTLS should be used 7873 or not. Defaults to normal. 7874 </entry></row> 7875 7876 <row><entry><literal>login</literal></entry> 7877 <entry><literal>string</literal></entry> 7878 <entry valign="bottom"> 7879 Login name. 7880 </entry></row> 7881 7882 <row><entry><literal>secret</literal></entry> 7883 <entry><literal>string</literal></entry> 7884 <entry valign="bottom"> 7885 Login password 7886 </entry></row> 7887 7888 </tbody> 7889 </tgroup> 7890 </table> 7891 7892 <para>A sample 'ota-setting' group: 7893 7894<programlisting> 7895group = ota-setting 7896location = http://wap.company.com 7897service = "Our company's WAP site" 7898ipaddress = 10.11.12.13 7899phonenumber = 013456789 7900bearer = data 7901calltype = analog 7902connection = cont 7903pppsecurity = off 7904authentication = normal 7905login = wapusr 7906secret = thepasswd 7907</programlisting> 7908 7909And a 'sendsms-user' to use with it. With concatenation enabled: 7910 7911<programlisting> 7912group = sendsms-user 7913username = otauser 7914password = foo 7915max-messages = 2 7916concatenation = 1 7917</programlisting> 7918 7919 </para> 7920 7921 <table frame="none"> 7922 <title>OTA Bookmark Group Variables</title> 7923 <tgroup cols="3"> 7924 <thead> 7925 <row> 7926 <entry>Variable</entry> 7927 <entry>Value</entry> 7928 <entry>Description</entry> 7929 </row> 7930 </thead> 7931 <tbody> 7932 <row><entry><literal>group</literal></entry> 7933 <entry><literal>ota-bookmark</literal></entry> 7934 <entry valign="bottom"> 7935 This is a mandatory variable 7936 </entry></row> 7937 7938 <row><entry><literal>ota-id</literal></entry> 7939 <entry><literal>string</literal></entry> 7940 <entry valign="bottom"> 7941 An optional name or id for the ota-bookmark. Any string is 7942 acceptable, but semicolon ';' may cause problems, so avoid 7943 it and any other special non-alphabet characters. 7944 </entry></row> 7945 7946 <row><entry><literal>url</literal></entry> 7947 <entry><literal>URL</literal></entry> 7948 <entry valign="bottom"> 7949 The address of the HTTP server for your WAP services, i.e. 7950 <literal>http://wap.company.com</literal> 7951 </entry></row> 7952 7953 <row><entry><literal>name</literal></entry> 7954 <entry><literal>string</literal></entry> 7955 <entry valign="bottom"> 7956 Description of the service 7957 </entry></row> 7958 7959 </tbody> 7960 </tgroup> 7961 </table> 7962 7963 <para>A sample 'ota-bookmark' group: 7964 7965<programlisting> 7966group = ota-bookmark 7967ota-id = wap-link 7968url = "http://wap.company.com" 7969service = "Our company's WAP site" 7970</programlisting> 7971 7972And a 'sendsms-user' to use with it, with the same conditions as for the 7973'ota-setting' group. 7974 7975 </para> 7976 7977 7978</sect2> 7979 7980<sect2> 7981<title>Setting up more complex services</title> 7982 7983 <para>The basic service system is very limited - it can only 7984 answer to original requester and it cannot send UDH data, for 7985 example. This chapter explains some more sophisticated and complex 7986 SMS service setups.</para> 7987 7988<sect3> 7989<title>Redirected replies</title> 7990 7991 <para>The basic service system always sends the answer back to 7992 original requester, but sometimes the content server needs to send 7993 something to other terminals or delay the answer. To create 7994 such systems, an SMS push is used.</para> 7995 7996 <para>The idea is to get the initial request, but then send no 7997 reply. Instead, the reply (if any) is sent via HTTP 7998 sendsms-interface as SMS Push. This way the service 7999 application has full control of the return content, and can do all 8000 needed formatting beforehand.</para> 8001 8002 <para>Note that when no reply is wanted, remember to set the variable 8003 <literal>max-messages</literal> to zero (0) so that no reply is sent, unless an 8004 error occurs. Simple sample:</para> 8005 8006<programlisting> 8007group = sms-service 8008keyword = talk 8009get-url = "http://my.applet.machine/Servlet/talk?sender=%p&text=%r" 8010max-messages = 0 8011</programlisting> 8012 8013 8014</sect3> 8015<sect3> 8016<title>Setting up operator specific services</title> 8017 8018 <para>Those running Kannel with several SMS centers might need to 8019 define services according to the relying SMS center. To achieve this, 8020 first you need to give an ID name for SMS center connections (see 8021 above). Then use the <literal>accepted-smsc</literal> variable to 8022 define which messages can use that service.</para> 8023 8024<programlisting> 8025group = sms-service 8026keyword = weather 8027accepted-smsc = SOL 8028get-url = "http://my.applet.machine/Servlet/weather?sender=%p&operator=SOL&text=%r" 8029</programlisting> 8030 8031</sect3> 8032<sect3> 8033<title>Setting up multi-operator Kannel</title> 8034 8035 <para>Sometimes there is a need for Kannel to listen to two (or 8036 more) distinct SMS centers, and messages must be routed to services 8037 according to where they came from, and replies likewise must return 8038 to same SMSC. This is done via <literal>smsc-id</literal> 8039 magic. Here is a shortened sample configuration, which handles to 8040 distinct SMS servers and services:</para> 8041 8042<programlisting> 8043group = smsc 8044smsc-id = A 8045denied-smsc-id = B 8046... 8047 8048group = smsc 8049smsc-id = B 8050denied-smsc-id = A 8051... 8052 8053group = sms-service 8054accepted-smsc = A 8055get-url = "..." 8056 8057group = sms-service 8058accepted-smsc = B 8059get-url = "..." 8060</programlisting> 8061 8062 <para>As can be seen, the <literal>smsc-id</literal> is used to 8063 identify the SMS center from which the message came. Then, the 8064 <literal>denied-smsc-id</literal> variable is used to prevent 8065 messages originally from the other SMS center from being sent 8066 through the other one. Finally 'sms-service' groups are defined 8067 with <literal>accepted-smsc</literal> so that they only accept 8068 messages from certain SMS center.</para> 8069 8070 <para>If you want to use SMS push services, requesters 8071 should then set the <literal>smsc</literal> request parameter, or 8072 'sendsms-user' groups should be defined like this:</para> 8073 8074<programlisting> 8075group = sendsms-user 8076username = operator_A 8077password = foo 8078forced-smsc = A 8079 8080group = sendsms-user 8081username = operator_B 8082password = bar 8083forced-smsc = B 8084</programlisting> 8085 8086 <para>Note that if your SMS centers do not set the sender phone 8087 number but rely on number transmitted, you should set 8088 <literal>faked-sender</literal> to all 'sendsms-user' 8089 groups.</para> 8090 8091</sect3> 8092 8093</sect2> 8094 8095</sect1> 8096 8097<sect1> 8098<title>Running SMS gateway</title> 8099 8100<sect2> 8101<title>Using the HTTP interface to send SMS messages</title> 8102 8103 <para>After you have configured Kannel to allow the sendsms 8104 service, you can send SMS messages via HTTP, e.g., using a 8105 WWW browser. The URL looks something like this: 8106 8107<programlisting> 8108http://smsbox.host.name:13013/cgi-bin/sendsms? 8109username=foo&password=bar&to=0123456&text=Hello+world 8110</programlisting> 8111 8112 Thus, technically, 8113 you make an HTTP GET request. This means that all the information 8114 is stuffed into the URL. If you want to use this often via a 8115 browser, you probably want to make an HTML form for this.</para> 8116 8117 <para> 8118 Kannel will answer to sendsms request with following codes and 8119 body texts:</para> 8120 8121 <table frame="none"> 8122 <title>SMS Push reply codes</title> 8123 <tgroup cols="3"><thead><row> 8124 <entry>Status</entry> 8125 <entry>Body</entry> 8126 <entry>Meaning</entry> 8127 </row></thead> 8128 <tbody> 8129 <row><entry><literal>202</literal></entry> 8130 <entry><literal>0: Accepted for delivery</literal></entry> 8131 <entry valign="bottom"> 8132 The message has been accepted and is delivered onward to a SMSC 8133 driver. Note that this status does not ensure that the 8134 intended recipient receives the message. 8135 </entry></row> 8136 <row><entry><literal>202</literal></entry> 8137 <entry><literal>3: Queued for later delivery</literal></entry> 8138 <entry valign="bottom"> 8139 The bearerbox accepted and stored the message, but there was 8140 temporarily no SMSC driver to accept the message so it was 8141 queued. However, it should be delivered later on. 8142 </entry></row> 8143 <row><entry><literal>4xx</literal></entry> 8144 <entry>(varies)</entry> 8145 <entry valign="bottom"> 8146 There was something wrong in the request or Kannel was so 8147 configured that the message cannot be in any circumstances 8148 delivered. Check the request and Kannel configuration. 8149 </entry></row> 8150 <row><entry><literal>503</literal></entry> 8151 <entry><literal>Temporal failure, try again later.</literal></entry> 8152 <entry valign="bottom"> 8153 There was temporal failure in Kannel. Try again later. 8154 </entry></row> 8155 8156 </tbody> 8157 </tgroup> 8158 </table> 8159 8160 8161 <table frame="none"> 8162 <title>SMS Push (send-sms) CGI Variables</title> 8163 <tgroup cols="3"> 8164 <tbody> 8165 <row><entry><literal>username</literal> (or <literal>user</literal>)</entry> 8166 <entry><literal>string</literal></entry> 8167 <entry valign="bottom"> 8168 Username or account name. Must be <literal>username</literal> of the one 8169 'sendsms-user' group in the Kannel configuration, 8170 or results in 'Authorization failed' reply. 8171 </entry></row> 8172 8173 <row><entry><literal>password</literal> (or <literal>pass</literal>)</entry> 8174 <entry><literal>string</literal></entry> 8175 <entry valign="bottom"> 8176 Password associated with given <literal>username</literal>. Must match 8177 corresponding field in the 'sendsms-user' group of 8178the Kannel configuration, or 'Authorization failed' is returned. 8179 </entry></row> 8180 8181 <row><entry><literal>from</literal></entry> 8182 <entry><literal>string</literal></entry> 8183 <entry valign="bottom"> 8184 Phone number of the sender. This field is usually overridden 8185 by the SMS Center, or it can be overridden by 8186 <literal>faked-sender</literal> variable in the 8187 <literal>sendsms-user</literal> group. If this variable is not 8188 set, smsbox <literal>global-sender</literal> is used. 8189 </entry></row> 8190 8191 <row><entry><literal>to</literal></entry> 8192 <entry><literal>phone number list</literal></entry> 8193 <entry valign="bottom"> 8194 Phone number of the receiver. To send to multiple receivers, 8195 separate each entry with <emphasis>space</emphasis> (' ', '+' 8196 url-encoded) - but note that this can be deactivated via 8197 <literal>sendsms-chars</literal> in the 'smsbox' group. 8198 </entry></row> 8199 8200 <row><entry><literal>text</literal></entry> 8201 <entry><literal>string</literal></entry> 8202 <entry valign="bottom"> 8203 Contents of the message, URL encoded as necessary. The content 8204 can be more than 160 characters, but then 8205 <literal>sendsms-user</literal> group must have 8206 <literal>max-messages</literal> set more than 1. 8207 </entry></row> 8208 8209 <row><entry><literal>charset</literal></entry> 8210 <entry><literal>string</literal></entry> 8211 <entry valign="bottom"> 8212 Charset of text message. Used to convert to a format suitable for 8213 7 bits or to UCS-2. Defaults to UTF-8 if coding is 7 bits and 8214 UTF-16BE if coding is UCS-2. 8215 </entry></row> 8216 8217 <row><entry><literal>udh</literal></entry> 8218 <entry><literal>string</literal></entry> 8219 <entry valign="bottom"> 8220 Optional User Data Header (UDH) part of the message. Must be 8221 URL encoded. 8222 </entry></row> 8223 8224 <row><entry><literal>smsc</literal></entry> 8225 <entry><literal>string</literal></entry> 8226 <entry valign="bottom"> 8227 Optional virtual smsc-id from which the message is supposed to 8228 have arrived. This is used for routing purposes, if any denied 8229 or preferred SMS centers are set up in SMS center 8230 configuration. This variable can be overridden with a 8231 <literal>forced-smsc</literal> configuration 8232 variable. Likewise, the <literal>default-smsc</literal> variable 8233 can be used to set the SMSC if it is not set otherwise. 8234 </entry></row> 8235 8236 <row><entry><literal>flash</literal></entry> 8237 <entry><literal>number</literal></entry> 8238 <entry valign="bottom"> 8239 Deprecated. See <literal>mclass</literal>. 8240 </entry></row> 8241 8242 <row><entry><literal>mclass</literal></entry> 8243 <entry><literal>number</literal></entry> 8244 <entry valign="bottom"> 8245 Optional. Sets the Message Class in DCS field. 8246 Accepts values between 0 and 3, for Message Class 0 to 3, 8247 A value of 0 sends the message directly to display, 1 sends 8248 to mobile, 2 to SIM and 3 to SIM toolkit. 8249 </entry></row> 8250 8251 <row><entry><literal>mwi</literal></entry> 8252 <entry><literal>number</literal></entry> 8253 <entry valign="bottom"> 8254 Optional. Sets Message Waiting Indicator bits in DCS field. 8255 If given, the message will be encoded as a Message Waiting 8256 Indicator. The accepted values are 0,1,2 and 3 for activating the 8257 voice, fax, email and other indicator, or 4,5,6,7 for deactivating, 8258 respectively. 8259 This option excludes the <literal>flash</literal> option. 8260 <footnote id="mwi-messages"><para>To set number of messages, use 8261 <literal>mwi=[0-3]&coding=0&udh=%04%01%02%<XX>%<YY></literal>, 8262 where YY are the number of messages, in HEX, and XX are <literal>mwi</literal> 8263 plus 0xC0 if <literal>text</literal> field is not empty.</para> </footnote> 8264 </entry></row> 8265 8266 <row><entry><literal>compress</literal></entry> 8267 <entry><literal>number</literal></entry> 8268 <entry valign="bottom"> 8269 Optional. Sets the Compression bit in DCS Field. 8270 </entry></row> 8271 8272 <row><entry><literal>coding</literal></entry> 8273 <entry><literal>number</literal></entry> 8274 <entry valign="bottom"> 8275 Optional. Sets the coding scheme bits in DCS field. 8276 Accepts values 0 to 2, for 7bit, 8bit or UCS-2. 8277 If unset, defaults to 7 bits unless a udh is defined, which sets 8278 coding to 8bits. 8279 </entry></row> 8280 8281 <row><entry><literal>validity</literal></entry> 8282 <entry><literal>number (minutes)</literal></entry> 8283 <entry valign="bottom"> 8284 Optional. If given, Kannel will inform SMS Center that it should only 8285 try to send the message for this many minutes. If the destination 8286 mobile is off other situation that it cannot receive the sms, the 8287 smsc discards the message. 8288 Note: you must have your Kannel box time synchronized with the SMS Center. 8289 </entry></row> 8290 8291 <row><entry><literal>deferred</literal></entry> 8292 <entry><literal>number (minutes)</literal></entry> 8293 <entry valign="bottom"> 8294 Optional. If given, the SMS center will postpone the message to be 8295 delivered at now plus this many minutes. 8296 Note: you must have your Kannel box time synchronized with the SMS Center. 8297 </entry></row> 8298 8299 <row><entry><literal>dlrmask</literal></entry> 8300 <entry><literal>number (bit mask)</literal></entry> 8301 <entry valign="bottom"> 8302 Deprecated. See <literal>dlr-mask</literal>. 8303 </entry></row> 8304 8305 <row><entry><literal>dlr-mask</literal></entry> 8306 <entry><literal>number (bit mask)</literal></entry> 8307 <entry valign="bottom"> 8308 Optional. Request for delivery reports with the state of the sent 8309 message. The value is a bit mask composed of: 1: Delivered to phone, 8310 2: Non-Delivered to Phone, 4: Queued on SMSC, 8: Delivered to SMSC, 8311 16: Non-Delivered to SMSC. Must set <literal>dlr-url</literal> on 8312 <literal>sendsms-user</literal> group or use the 8313 <literal>dlr-url</literal> CGI variable. 8314 </entry></row> 8315 8316 <row><entry><literal>dlrurl</literal></entry> 8317 <entry><literal>string (url)</literal></entry> 8318 <entry valign="bottom"> 8319 Deprecated. See <literal>dlr-url</literal>. 8320 </entry></row> 8321 8322 <row><entry><literal>dlr-url</literal></entry> 8323 <entry><literal>string (url)</literal></entry> 8324 <entry valign="bottom"> 8325 Optional. If <literal>dlr-mask</literal> is given, this is the url to 8326 be fetched. (Must be url-encoded) 8327 </entry></row> 8328 8329 <row><entry><literal>pid</literal></entry> 8330 <entry><literal>byte</literal></entry> 8331 <entry valign="bottom"> 8332 Optional. Sets the PID value. (See ETSI Documentation). 8333 Ex: SIM Toolkit messages would use something like 8334 <literal>&pid=127&coding=1&alt-dcs=1&mclass=3</literal> 8335 </entry></row> 8336 8337 <row><entry><literal>alt-dcs</literal></entry> 8338 <entry><literal>number</literal></entry> 8339 <entry valign="bottom"> 8340 Optional. If unset, Kannel uses the alt-dcs defined on smsc configuration, 8341 or 0X per default. If equals to 1, uses FX. If equals to 0, force 0X. 8342 </entry></row> 8343 8344 <row><entry><literal>rpi</literal></entry> 8345 <entry><literal>number</literal></entry> 8346 <entry valign="bottom"> 8347 Optional. Sets the Return Path Indicator (RPI) value. (See ETSI Documentation). 8348 </entry></row> 8349 8350 <row><entry><literal>account</literal></entry> 8351 <entry>string</entry> 8352 <entry valign="bottom"> 8353 Optional. Account name or number to carry forward for billing purposes. 8354 This field is logged as ACT in the log file so it allows you to do some 8355 accounting on it if your front end uses the same username for all services 8356 but wants to distinguish them in the log. In the case of a HTTP SMSC 8357 type the account name is prepended with the service-name (username) and a colon (:) 8358 and forwarded to the next instance of Kannel. This allows hierarchical accounting. 8359 </entry></row> 8360 8361 <row><entry><literal>binfo</literal></entry> 8362 <entry>string</entry> 8363 <entry valign="bottom"> 8364 Optional. Billing identifier/information proxy field used to pass arbitrary 8365 billing transaction IDs or information to the specific SMSC modules. For EMI2 this 8366 is encapsulated into the XSer 0c field, for SMPP this is encapsulated into the 8367 service_type of the submit_sm PDU. 8368 </entry></row> 8369 8370 <row><entry><literal>priority</literal></entry> 8371 <entry>number</entry> 8372 <entry valign="bottom"> 8373 Optional. Sets the Priority value (range 0-3 is allowed). 8374 (Defaults to 0, which is the lowest priority). 8375 </entry></row> 8376 8377 </tbody> 8378 </tgroup> 8379 </table> 8380 8381 8382</sect2> 8383 8384<sect2> 8385<title>Using the HTTP interface to send OTA configuration messages</title> 8386 8387 <para>OTA messages can be sent to mobile phones or devices to auto-configure the 8388 settings for WAP. They are actually complex SMS messages with UDH and sent as 8389 concatenated messages if too long (and compiled if necessary).</para> 8390 8391 <para>You may either pass an HTTP request as GET method or POST method to the 8392 HTTP interface.</para> 8393 8394 <para>If you want to send a configuration that is defined within Kannel's 8395 configuration file itself you have to pass a valid 8396 <literal>ota-id</literal> value otherwise the content of the request will 8397 be compiled to as OTA message.</para> 8398 8399<sect3> 8400<title>OTA settings and bookmark documents</title> 8401 8402 <para> 8403 Here is an example XML document (this one contains CSD settings for logging 8404 in to a mobile service; note that you must store DTD locally): 8405 8406<programlisting> 8407<?xml version="1.0"?> 8408<!DOCTYPE CHARACTERISTIC-LIST SYSTEM "file:///gw/settings.dtd"> 8409<CHARACTERISTIC-LIST> 8410 8411 <CHARACTERISTIC TYPE="ADDRESS"> 8412 <PARM NAME="BEARER" VALUE="GSM/CSD"/> 8413 <PARM NAME="PROXY" VALUE="10.11.12.13"/> 8414 <PARM NAME="PORT" VALUE="9201"/> 8415 <PARM NAME="CSD_DIALSTRING" VALUE="+12345678"/> 8416 <PARM NAME="PPP_AUTHTYPE" VALUE="PAP"/> 8417 <PARM NAME="PPP_AUTHNAME" VALUE="yourusername"/> 8418 <PARM NAME="PPP_AUTHSECRET" VALUE="yourauthsecret"/> 8419 <PARM NAME="CSD_CALLTYPE" VALUE="ISDN"/> 8420 <PARM NAME="CSD_CALLSPEED" VALUE="9600"/> 8421 </CHARACTERISTIC> 8422 8423 <CHARACTERISTIC TYPE="URL" 8424 VALUE="http://wap.company.com/"/> 8425 8426 <CHARACTERISTIC TYPE="NAME"> 8427 <PARM NAME="NAME" VALUE="Your WAP Company"/> 8428 </CHARACTERISTIC> 8429 8430</CHARACTERISTIC-LIST> 8431</programlisting> 8432 8433 A bookmark document looks like this: 8434 8435<programlisting> 8436<?xml version="1.0"?> 8437<!DOCTYPE CHARACTERISTIC_LIST SYSTEM "file:///gw/settings.dtd"> 8438<CHARACTERISTIC-LIST> 8439 <CHARACTERISTIC TYPE="BOOKMARK"> 8440 <PARM NAME="NAME" VALUE="WAP Company"/> 8441 <PARM NAME="URL" VALUE="http://wap.company.com/"/> 8442 </CHARACTERISTIC> 8443</CHARACTERISTIC-LIST> 8444</programlisting> 8445 8446 Document type definition (DTD) for these documents is not 8447 available from Internet, you must supply it as a file. Kannel 8448 gw directory contains an 8449 example, <literal>settings.dtd</literal>. 8450 8451 </para> 8452</sect3> 8453 8454<sect3> 8455<title>OTA syncsettings documents</title> 8456 8457 <para>Used for the provisioning of sync configuration to 8458 SyncMl enabled handsets. Best supported by sonyericcsson 8459 terminals. 8460 </para> 8461 8462 <para>Sample syncsettings documents to set contacts, connection data 8463 and authentication: 8464 8465<programlisting> 8466<SyncSettings> 8467<Version>1.0</Version> 8468<HostAddr>http://syncml.server.com</HostAddr> 8469<RemoteDB> 8470 <CTType>text/x-vcard</CTType> 8471 <CTVer>2.1</CTVer> 8472 <URI>contact</URI> 8473 <Name>Address Book</Name> 8474</RemoteDB> 8475<Name>Synchonization</Name> 8476<Auth> 8477 <AuthLevel>1</AuthLevel> 8478 <AuthScheme>1</AuthScheme> 8479 <Username>yourusername</Username> 8480 <Cred>passwordbase64encoded</Cred> 8481</Auth> 8482</SyncSettings> 8483</programlisting> 8484 8485</para> 8486 8487</sect3> 8488 8489<sect3> 8490<title>OMA provisioning content</title> 8491 8492 <para>OMA provisioning allows the configuration of a wider 8493 range of settings than previously available in OTA 8494 terminals. Refer to OMA-WAP-ProvCont-v1_1-20021112-C (at 8495 http://www.openmobilealliance.org/tech/docs/) for details. 8496 </para> 8497 8498 <para>A shared secret (i.e. a pin or the phone IMSI) can be 8499 used to authenticate the settings. Defaults are 'userpin' 8500 and '1234' a. See the cgi variables 'sec' and 'pin' for 8501 available authentication options. 8502 </para> 8503 8504</sect3> 8505<sect3> 8506<title>GET method for the OTA HTTP interface</title> 8507 8508 <para>An example URL (OTA configuration defined in the Kannel 8509 configuration file): 8510 8511 <screen><userinput> 8512 http://smsbox.host.name:13013/cgi-bin/sendota? 8513 otaid=myconfig&username=foo&password=bar&to=0123456 8514 </userinput></screen> 8515 8516 URL containing XML document looks like this (you must URL encode it before sending 8517 it over HTTP): 8518 8519 <screen><userinput> 8520 http://smsbox.host.name:13013/cgi-bin/sendota? 8521 username=foo&password=bar&to=0123456& 8522 text=MyURLEncodedXMLdocument&type=settings 8523 </userinput></screen> 8524 8525 You can send either settings, bookmark, syncsettings, or 8526 oma-settings, set CGI variable type accordingly. Default for 8527 this variable is settings. 8528 </para> 8529 8530 <table frame="none"> 8531 <title>OTA CGI Variables</title> 8532 <tgroup cols="3"> 8533 <tbody> 8534 <row><entry><literal>otaid</literal></entry> 8535 <entry><literal>string</literal></entry> 8536 <entry valign="bottom"> 8537 Name or ID of the 'ota-setting' group in Kannel configuration 8538 that should be sent to the phone. This variable is optional. 8539 If it is not given the first 'ota-setting' group is sent. This 8540 is unnecessary when a XML document is send to the phone. 8541 </entry></row> 8542 8543 <row><entry><literal>username</literal></entry> 8544 <entry><literal>string</literal></entry> 8545 <entry valign="bottom"> 8546 Username of the 'sendsms-user' group in Kannel configuration, that has 8547 been configured to send OTA messages. 8548 </entry></row> 8549 8550 <row><entry><literal>password</literal></entry> 8551 <entry><literal>string</literal></entry> 8552 <entry valign="bottom"> 8553 Password associated with given <literal>username</literal>. Must match 8554 corresponding field in 'sendsms-user' group in Kannel configuration, or 8555 'Authorization failed' is returned. 8556 </entry></row> 8557 8558 <row><entry><literal>to</literal></entry> 8559 <entry><literal>number</literal></entry> 8560 <entry valign="bottom"> 8561 Number of the phone that is to receive the OTA configuration message. 8562 </entry></row> 8563 8564 <row><entry><literal>from</literal></entry> 8565 <entry><literal>string</literal></entry> 8566 <entry valign="bottom"> 8567 Phone number of the sender. This field is usually overridden by 8568 the SMS Center, or it can be overridden by faked-sender 8569 variable in the sendsms-user group. If this variable is not 8570 set, smsbox global-sender is used. 8571 </entry></row> 8572 8573 <row><entry><literal>smsc</literal></entry> 8574 <entry><literal>string</literal></entry> 8575 <entry valign="bottom"> 8576 Optional virtual smsc-id from which the message is supposed to 8577 have arrived. This is used for routing purposes, if any denied 8578 or preferred SMS centers are set up in SMS center 8579 configuration. This variable can be overridden with a 8580 <literal>forced-smsc</literal> configuration 8581 variable. Likewise, the <literal>default-smsc</literal> variable 8582 can be used to set the SMSC if it is not set otherwise. 8583 </entry></row> 8584 8585 <row><entry><literal>text</literal></entry> 8586 <entry><literal>XML document</literal></entry> 8587 <entry valign="bottom"> 8588 An URL encoded XML document, containing either settings or bookmarks. 8589 </entry></row> 8590 8591 <row><entry><literal>type</literal></entry> 8592 <entry><literal>string</literal></entry> 8593 <entry valign="bottom"> 8594 Type of the XML document, supported values are "settings", 8595 "bookmarks", "syncsettings", and "oma-settings". Default is "settings". 8596 </entry></row> 8597 8598 <row><entry><literal>sec</literal></entry> 8599 <entry><literal>string</literal></entry> 8600 <entry valign="bottom"> 8601 Security model used to authenticate oma-settings. One of: 8602 "userpin", "netwpin", "usernetwpin", or "userpinmac". 8603 </entry></row> 8604 8605 <row><entry><literal>pin</literal></entry> 8606 <entry><literal>number</literal></entry> 8607 <entry valign="bottom"> 8608 Authentication token. 8609 </entry></row> 8610 8611 </tbody> 8612 </tgroup> 8613 </table> 8614 8615</sect3> 8616 8617</sect2> 8618 8619</sect1> 8620 8621</chapter> 8622 8623 8624 8625 8626<chapter id="ppg"> 8627<title>Setting up Push Proxy Gateway</title> 8628 <para>This chapter explains how to set up a push proxy gateway (PPG). 8629 An example configuration file are given. A working push proxy gateway 8630 is described. Routing wap pushes to a certain smsc and asking for 8631 <emphasis>SMS level</emphasis> delivery reports are described.</para> 8632<sect1> 8633<title>Configuring ppg core group, for push initiator (PI) interface</title> 8634 <para>PPG configuration group defines gateway's service interface. 8635 Configuring a PPG working with a trusted PI is easiest. Actually, 8636 you need no configuration at all: in this case a PPG with default 8637 values will be set up. Do not rely on this, default values may change. 8638 For PPG core configuration variables, see table 7.1. 8639 </para> 8640 8641 <para>An example of a core configuration for PPG working only with 8642 specific addresses follows. Note that ppg-deny-ip-list is not actually 8643 necessary, but does make configuring simpler: IPs here are always denied, 8644 even when they are mentioned in the allowed IPs list.</para> 8645 8646 <para>Ppg-url is a simple stamp, used for routing requests to the right 8647 service. You can change this stamp by setting <literal>push-url</literal> 8648 configuration variable. 8649 </para> 8650<programlisting> 8651group = ppg 8652ppg-url = /wappush 8653ppg-port = 8080 8654concurrent-pushes = 100 8655users = 1024 8656ppg-allow-ip = 194.100.32.125;127.0.0.1 8657ppg-deny-ip = 194.100.32.89;194.100.32.103 8658trusted-pi = false 8659</programlisting> 8660 <table frame="none"> 8661 <title>PPG core group configuration variables</title> 8662 <tgroup cols="3"><thead><row> 8663 <entry>Variable</entry> 8664 <entry>Value</entry> 8665 <entry>Description</entry> 8666 </row></thead> 8667 <tbody> 8668 <row><entry><literal>group</literal></entry> 8669 <entry><emphasis>ppg</emphasis></entry> 8670 <entry valign="bottom"> 8671 Mandatory value. Tells that we are configuring the PPG group. 8672 </entry></row> 8673 <row><entry><literal>ppg-port</literal></entry> 8674 <entry><emphasis>number</emphasis></entry> 8675 <entry valign="bottom"> 8676 The port PPG is listening at. Default 8080. 8677 </entry></row> 8678 <row><entry><literal>ppg-ssl-port (o)</literal></entry> 8679 <entry><emphasis>number</emphasis></entry> 8680 <entry valign="bottom"> 8681 Mandatory value for PPG HTTPS support. The port at which PPG listens 8682 for HTTPS requests. There are no defaults; you must set the value 8683 separately. 8684 </entry></row> 8685 <row><entry><literal>ssl-server-cert-file</literal></entry> 8686 <entry><emphasis>string</emphasis></entry> 8687 <entry valign="bottom"> 8688 Mandatory value for PPG HTTPS support. The file containing server's ssl 8689 certificate. 8690 </entry></row> 8691 <row><entry><literal>ssl-server-key-file</literal></entry> 8692 <entry><emphasis>string</emphasis></entry> 8693 <entry valign="bottom"> 8694 Mandatory value for PPG HTTPS support. The file containing server's ssl 8695 private key. 8696 </entry></row> 8697 <row><entry><literal>ppg-url</literal></entry> 8698 <entry><emphasis>url</emphasis></entry> 8699 <entry valign="bottom"> 8700 URL locating PPG services. Default <literal>/wappush 8701 </literal>. 8702 </entry></row> 8703 <row><entry><literal>global-sender</literal></entry> 8704 <entry><emphasis>string</emphasis></entry> 8705 <entry valign="bottom"> 8706 Sender phone number required by some protocols. 8707 </entry></row> 8708 <row><entry><literal>concurrent-pushes</literal></entry> 8709 <entry><emphasis>number</emphasis></entry> 8710 <entry valign="bottom"> 8711 Number of concurrent pushes expected. Note that PPG <emphasis> 8712 does</emphasis> work even value is too low; it will only be 8713 slower. Default 100. 8714 </entry></row> 8715 <row><entry><literal>users</literal></entry> 8716 <entry><emphasis>number</emphasis></entry> 8717 <entry valign="bottom"> 8718 Number of actually configured user accounts. Note that PPG 8719 <emphasis>does</emphasis> work even value is too low; it will 8720 only be slower. Default 1024. 8721 </entry></row> 8722 <row><entry><literal>trusted-pi</literal></entry> 8723 <entry><emphasis>boolean</emphasis></entry> 8724 <entry valign="bottom"> 8725 If true, PI does authentication for PPG. Obviously, both of them 8726 must reside inside same firewall. Default true. If this variable 8727 is true, all security variables are ignored (even though they 8728 may be present). 8729 </entry></row> 8730 <row><entry><literal>ppg-deny-ip</literal></entry> 8731 <entry><emphasis>ip-list</emphasis></entry> 8732 <entry valign="bottom"> 8733 PPG will not accept pushes from these IPs. Wild-cards are allowed. 8734 If this attribute is missing, no IP is denied <emphasis> by this 8735 list </emphasis>. 8736 </entry></row> 8737 <row><entry><literal>ppg-allow-ip</literal></entry> 8738 <entry><emphasis>ip-list</emphasis></entry> 8739 <entry valign="bottom"> 8740 PPG will accept pushes from these, and only these, IPs. Wild-cards 8741 are allowed. Adding this list means that IPs not mentioned are 8742 denied, too. 8743 </entry></row> 8744 <row><entry><literal>default-smsc</literal></entry> 8745 <entry><emphasis>string</emphasis></entry> 8746 <entry valign="bottom"> 8747 If no SMSC ID is given with the wappush HTTP request (see below), use 8748 this one as default route for all push messages. 8749 </entry></row> 8750 <row><entry><literal>default-dlr</literal></entry> 8751 <entry><emphasis>string</emphasis></entry> 8752 <entry valign="bottom"> 8753 If no dlr url is given with the wappush HTTP request (see below), use 8754 this one as default route for all push messages. 8755 </entry></row> 8756 <row><entry><literal>ppg-smsbox-id</literal></entry> 8757 <entry><emphasis>string</emphasis></entry> 8758 <entry valign="bottom"> 8759 All ppg delivery reports are handled by this smsbox. This routes all 8760 DLR messages inside beaerbox to the specified smsbox for processing 8761 the HTTP requests to the DLR-URL. 8762 </entry></row> 8763 <row><entry><literal>service-name</literal></entry> 8764 <entry><emphasis>string</emphasis></entry> 8765 <entry valign="bottom"> 8766 This is sms service name used by smsbox for wap push. 8767 </entry></row> 8768 <row><entry><literal>default-dlr</literal></entry> 8769 <entry><emphasis>string</emphasis></entry> 8770 <entry valign="bottom"> 8771 If no dlr url is given with the wappush HTTP request (see below), use 8772 this one as default route for all push messages. 8773 </entry></row> 8774 <row><entry><literal>service-name</literal></entry> 8775 <entry><emphasis>string</emphasis></entry> 8776 <entry valign="bottom"> 8777 This is sms service name used by smsbox for wap push.. 8778 </entry></row> 8779 <row><entry><literal>concatenation</literal></entry> 8780 <entry><emphasis>boolean</emphasis></entry> 8781 <entry valign="bottom"> 8782 Segment wap push binary sms. Default on. You need 8783 not normally set this value. 8784 </entry></row> 8785 <row><entry><literal>max-messages</literal></entry> 8786 <entry><emphasis>integer</emphasis></entry> 8787 <entry valign="bottom"> 8788 Maximum number of sm messages generated. Default 8789 10. You need not set this variable, expect when 8790 your push documents are <emphasis>very</emphasis> 8791 long. 8792 </entry></row> 8793 </tbody> 8794 </tgroup> 8795 </table> 8796</sect1> 8797<sect1> 8798<title>Configuring PPG user group variables</title> 8799 8800 <para>In addition of pi lists similar to the core group, ppg 8801 configuration specific to a certain user contains variables used for 8802 authentication and enforcing restrictions to phone numbers pi may 8803 contact. All variables are elaborated in table 7.2.</para> 8804 8805 <para>As an example, let us see how to configure a ppg user (a pi, 8806 named here 'picom') allowed to send pushes only from a specified ip. 8807 </para> 8808 8809<programlisting> 8810group = wap-push-user 8811wap-push-user = picom 8812ppg-username = foo 8813ppg-password = bar 8814allow-ip = 62.254.217.163 8815</programlisting> 8816 8817 <para>It goes without saying that in real systems you must use more 8818 complex passwords than bar.</para> 8819 8820 <table frame="none"> 8821 <title>PPG user group configuration variables</title> 8822 <tgroup cols="3"><thead><row> 8823 <entry>Variable</entry> 8824 <entry>Value</entry> 8825 <entry>Description</entry> 8826 </row></thead> 8827 <tbody> 8828 <row><entry><literal>group</literal></entry> 8829 <entry><emphasis>wap-push-user</emphasis></entry> 8830 <entry valign="bottom"> 8831 Mandatory value. Tells that we are configuring the users group. 8832 </entry></row> 8833 <row><entry><literal>wap-push-user</literal></entry> 8834 <entry><emphasis>string</emphasis></entry> 8835 <entry valign="bottom"> 8836 (More) human readable name of an user. 8837 </entry></row> 8838 <row><entry><literal>ppg-username</literal></entry> 8839 <entry><emphasis>string</emphasis></entry> 8840 <entry valign="bottom"> 8841 Username for this user. 8842 </entry></row> 8843 <row><entry><literal>ppg-password</literal></entry> 8844 <entry><emphasis>string</emphasis></entry> 8845 <entry valign="bottom"> 8846 Password for this user. 8847 </entry></row> 8848 <row><entry><literal>allowed-prefix</literal></entry> 8849 <entry><emphasis>number-list</emphasis></entry> 8850 <entry valign="bottom"> 8851 Phone number prefixes allowed in pushes coming from this pi. These 8852 prefixes must conform international phone number format. 8853 </entry></row> 8854 <row><entry><literal>denied-prefix</literal></entry> 8855 <entry><emphasis>number-list</emphasis></entry> 8856 <entry valign="bottom"> 8857 Phone number prefixes denied in pushes coming from this pi. These 8858 prefixes must conform international phone number format. 8859 </entry></row> 8860 <row><entry><literal>white-list</literal></entry> 8861 <entry><emphasis>url</emphasis></entry> 8862 <entry valign="bottom"> 8863 Defines an url where from the white-list can be fetched. White list 8864 itself contains list of phone numbers accepting pushes from this 8865 pi. 8866 </entry></row> 8867 <row><entry><literal>black-list</literal></entry> 8868 <entry><emphasis>url</emphasis></entry> 8869 <entry valign="bottom"> 8870 Defines an url where from the blacklist can be fetched. Blacklist 8871 itself contains list of phone number not accepting pushes from 8872 this pi. 8873 </entry></row> 8874 <row><entry><literal>allow-ip</literal></entry> 8875 <entry><emphasis>ip-list</emphasis></entry> 8876 <entry valign="bottom"> 8877 Defines IPs where from this pi can do pushes. Adding this list 8878 means that IPs not mentioned are denied. 8879 </entry></row> 8880 <row><entry><literal>deny-ip</literal></entry> 8881 <entry><emphasis>ip-list</emphasis></entry> 8882 <entry valign="bottom"> 8883 Defines IPs where from this pi cannot do pushes. IPs not mentioned 8884 in either list are denied, too. 8885 </entry></row> 8886 <row><entry><literal>default-smsc</literal></entry> 8887 <entry><emphasis>string</emphasis></entry> 8888 <entry valign="bottom"> 8889 If no SMSC ID is given with the wappush HTTP request (see below), use 8890 this one as default route for this specific push user. 8891 </entry></row> 8892 <row><entry><literal>forced-smsc</literal></entry> 8893 <entry><emphasis>string</emphasis></entry> 8894 <entry valign="bottom"> 8895 Allow only routing to a defined SMSC ID for this specific push user. 8896 </entry></row> 8897 <row><entry><literal>dlr-url</literal></entry> 8898 <entry><emphasis>string</emphasis></entry> 8899 <entry valign="bottom"> 8900 If no dlr is given with the wappush HTTP request (see below), use 8901 this one as default route for this specific push user. 8902 </entry></row> 8903 <row><entry><literal>smsbox-id</literal></entry> 8904 <entry><emphasis>string</emphasis></entry> 8905 <entry valign="bottom"> 8906 Smsbox handling delivery reports fro this user. 8907 </entry></row> 8908 <row><entry><literal>forced-smsc</literal></entry> 8909 <entry><emphasis>string</emphasis></entry> 8910 <entry valign="bottom"> 8911 Allow only routing to a defined SMSC ID for this specific push user. 8912 </entry></row> 8913 8914 <row><entry><literal>white-list-regex</literal></entry> 8915 <entry>POSIX regular expression</entry> 8916 <entry valign="bottom"> 8917 Defines the set of phone-numbers accepting pushes from this 8918 pi. 8919 See section on <xref linkend="regular-expressions"/> for details. 8920 </entry> 8921 </row> 8922 8923 <row><entry><literal>black-list-regex</literal></entry> 8924 <entry>POSIX regular expression</entry> 8925 <entry valign="bottom"> 8926 Defines the set of phone-numbers rejecting pushes from this 8927 pi. 8928 See section on <xref linkend="regular-expressions"/> for details. 8929 </entry> 8930 </row> 8931 8932 <row><entry><literal>allowed-prefix-regex</literal></entry> 8933 <entry>POSIX regular expression</entry> 8934 <entry valign="bottom"> 8935 Set of phone number prefixes allowed in pushes coming from this pi. 8936 See section on <xref linkend="regular-expressions"/> for details. 8937 </entry> 8938 </row> 8939 <row><entry><literal>denied-list-regex</literal></entry> 8940 <entry>POSIX regular expression</entry> 8941 <entry valign="bottom"> 8942 Set of phone number prefixes denied in pushes coming from this pi. 8943 See section on <xref linkend="regular-expressions"/> for details. 8944 </entry> 8945 </row> 8946 8947 </tbody> 8948 </tgroup> 8949 </table> 8950</sect1> 8951<sect1> 8952<title>Finishing ppg configuration</title> 8953 <para>PPG uses SMS for sending SI to the phone and an IP bearer to 8954 fetch content specified by it (see chapter Overview of WAP Push). This 8955 means both wapbox and bearer smsc connections are in use. So your push 8956 proxy gateway configuration file must contain groups core, wapbox, smsc 8957 and smsbox. These are configured normal way, only smsc group may have 8958 push-specific variables. Note that following configurations are only an 8959 example, you may need more complex ones. 8960 </para> 8961 <para>Bearerbox setup does not require any new variables:</para> 8962<programlisting> 8963group = core 8964admin-port = 13000 8965smsbox-port = 13001 8966wapbox-port = 13002 8967admin-password = b 8968wdp-interface-name = "*" 8969log-file = "filename" 8970log-level = 1 8971box-deny-ip = "*.*.*.*" 8972box-allow-ip = "127.0.0.1" 8973unified-prefix = "00358,0" 8974</programlisting> 8975 <para>You must set up wapbox, for pulling (fetching) the wap data, and 8976 of course starting the push itself. No new variables here, either. 8977 </para> 8978<programlisting> 8979group = wapbox 8980bearerbox-host = localhost 8981log-file = "filename" 8982log-level = 0 8983syslog-level = none 8984</programlisting> 8985 <para>To set up smsc connections, for pushing SI or SL over SMS. Here 8986 HTTP SMSC is used as an example. Variables no-sender and no-coding 8987 simplify HTTP request generated by Kannel. Send-url specifies content 8988 gateway, or sendsms service. 8989 </para> 8990<programlisting> 8991group = smsc 8992smsc = http 8993smsc-id = HTTP 8994port = 10000 8995system-type = kannel 8996smsc-username = foo 8997smsc-password = bar 8998no-sender = true 8999no-coding = true 9000send-url = http://host:port/path 9001</programlisting> 9002 <para>To set up smsbox. This is used for ppg delivery reports, 9003 see later.</para> 9004<programlisting> 9005group = smsbox 9006bearerbox-host = localhost 9007smsbox-id = dlrbox 9008</programlisting> 9009 <para>Kannel sources contain a sample push configuration file 9010 <literal>gw/pushkannel.conf</literal>.</para> 9011</sect1> 9012<sect1> 9013<title>Running a push proxy gateway</title> 9014 <para>Push proxy gateway is started by simply typing, using separate 9015 windows: 9016 <screen><userinput> 9017 gw/bearerbox [config-file] 9018 gw/wapbox [config-file] 9019 </userinput></screen> 9020 You can, of course, use more complex command line options.</para> 9021</sect1> 9022<sect1> 9023<title>An example using HTTP SMSC</title> 9024 <para>An easy way to test and implement push services is to put ppg 9025 in the front of an existing sendsms service capable to send SMS data 9026 messages and to understand HTTP requests generated by HTTP SMSC. 9027 (See next chapter.) Then you need only configure SMSC configuration 9028 send-url to point to sendsms service.</para> 9029</sect1> 9030<sect1> 9031<title>An example of minimum SI document</title> 9032 <para> Service indication (SI) should work with all types of 9033 phones, service loading does not. URL to be loaded is the 9034 main content of the document in both cases, however. Here an 9035 example (this is a minimum si document, not usable for testing, 9036 probably, but you want PPG to generate only one one SM per 9037 SI, if at all possible):</para> 9038<programlisting> 9039<?xml version="1.0"?> 9040<!DOCTYPE si PUBLIC "-//WAPFORUM//DTD SI 1.0//EN" 9041"http://www.wapforum.org/DTD/si.dtd"> 9042<si> 9043 <indication href="http://www.gni.ch" 9044 si-id="1@gni.ch"> 9045 You have 4 new emails 9046 </indication> 9047</si> 9048</programlisting> 9049 <para>Note following points: 9050 a) Every SI must have different si-id. If there are none, 9051 href is used as an (very unsatisfactory) id. 9052 b) this si should not interrupt the phone's current action. 9053 </para> 9054</sect1> 9055<sect1> 9056<title>An example push (tokenized SI) document</title> 9057 <para>HTTP SMSC generates a HTTP get request when it get a send-message 9058 event, expressed in Unicode. The content gateway, or the sendsms 9059 service must, of course, understand this URL. So here is an example, 9060 cgi variable text contains the url escaped form of a SI document. It is 9061 usable for testing prototype phones. 9062 </para> 9063 <screen><userinput> 9064 http://matrix:8080/phplib/kannelgw.php?user=*deleted*& 9065 pass=*deleted*=to=%2B358408676001&text=3D%02%06%17%AE%96localhost 9066 %3A8080%00%AF%80%8D%CF%B4%80%02%05j%00E%C6%0C%03wap.iobox.fi%00%11%03 9067 1%40wiral.com%00%07%0A%C3%07%19%99%06%25%15%23%15%10%C3%04+%02%060%01 9068 %03Want+to+test+a+fetch%3F%00%01%01&udh=%06%05%04%0B%84%23%F0 9069 </userinput></screen> 9070</sect1> 9071 9072<sect1> 9073<title>Default network and bearer used by push proxy gateway</title> 9074 <para> If network and bearer attributes of the pap control document are 9075 missing or set any, Kannel uses address type for routing purposes: if 9076 the address type is a phone number (TYPE=PLMN), network defaults to GSM 9077 and bearer to SMS; if it is a IP-address (TYPE=IPv4), network defaults 9078 to GSM and bearer to CSD. So following minimal pap document works: 9079<programlisting> 9080<?xml version="1.0"?> 9081<!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP//EN" 9082 "http://www.wapforum.org/DTD/pap_1.0.dtd"> 9083<pap> 9084 <push-message push-id="9fjeo39jf084@pi.com"> 9085 <address address-value="WAPPUSH=+358408676001/TYPE=PLMN@ppg.carrier.com"/> 9086 </push-message> 9087</pap> 9088</programlisting> 9089 </para> 9090</sect1> 9091 9092<sect1> 9093<title>Push related Kannel headers</title> 9094 <para>This chapter recapitulates Kannel headers used by ppg.</para> 9095 9096 <para>PPG uses many Kannel headers. These are very similar as ones 9097 used by smsbox. (Both send sms to to the phone, after all.)</para> 9098 9099 <table frame="none"> 9100 <title>Kannel headers used by PPG</title> 9101 <tgroup cols="3"> 9102 <thead><row><entry>Variable</entry> 9103 <entry>Value</entry> 9104 <entry>Description</entry></row></thead> 9105 <tbody> 9106 <row><entry><literal>X-Kannel-SMSC</literal></entry> 9107 <entry><emphasis>string</emphasis></entry> 9108 <entry valign="bottom">Name of smsc used to deliver this push. 9109 Smsc configuration must contain some of corresponding variables, 9110 see </entry></row> 9111 <row><entry><literal>X-Kannel-DLR-URL</literal></entry> 9112 <entry><emphasis>url</emphasis></entry> 9113 <entry valign="bottom">Url smsbox would call this url when doing 9114 the delivery report. Note that it can contain all Kannel escapes. 9115 See table 6.7 for details.</entry></row> 9116 <row><entry><literal>X-Kannel-DLR-Mask</literal></entry> 9117 <entry><emphasis>number</emphasis></entry> 9118 <entry valign="bottom">Mask telling smsbox when it should do 9119 the delivery reports. Values are same as used by smsbox, see 9120 chapter Delivery Reports for details.</entry></row> 9121 <row><entry><literal>X-Kannel-Smsbox-Id</literal></entry> 9122 <entry><emphasis>string</emphasis></entry> 9123 <entry valign="bottom">Tells which smsbox does the delivery 9124 report. Smsbox configuration must contain corresponding 9125 variable.</entry></row> 9126 </tbody> 9127 </tgroup> 9128 </table> 9129</sect1> 9130 9131<sect1> 9132<title>Requesting SMS level delivery reports for WAP pushes</title> 9133 <para>Push content is a normal binary SM, so you can ask delivery 9134 reports for them. These are useful for testing purposes (did the 9135 phone get the content at all, or did it just reject it.) Another 9136 use is create fall-back services for phones not supporting displaying 9137 a specific push content. (MMS one being perhaps currently most 9138 obvious.) Generally speaking, this service is very similar to 9139 smsbox one. See chapter Delivery Reports for details.</para> 9140 9141 <para> For ppg sms delivery reports you will need a fully working 9142 smsbox. Add configuration variable <literal>smsbox-id</literal> to 9143 <literal>smsbox</literal> group (it is necessary, because there 9144 is no MT from any smsbox corresponding the delivery report 9145 bearerbox is receiving):</para> 9146 9147<programlisting> 9148 group = smsbox 9149 smsbox-id = dlrbox 9150 bearerbox-host = localhost 9151 log-file = "/var/log/kannel/smsbox-core.log" 9152 log-level = 0 9153 access-log = "/var/log/kannel/smsbox-access.log" 9154</programlisting> 9155 9156 <para> Start smsbox normal way after updating the configuration 9157 file. </para> 9158 9159 <para> You must add to PPG configuration file two less obvious 9160 variables: <literal>ppg-smsbox-id</literal> and <literal> 9161 service-name</literal>. <literal>Ppg-smsbox-id</literal> 9162 defines smsbox through which you want to route delivery reports, 9163 <literal>service-name</literal> makes possible for smsbox to 9164 handle wap pushes as a separate sms service.</para> 9165 9166 <para>Setting <literal>ppg-smsbox-id</literal> will route all 9167 ppg messages through same smsbox. You can route delivery 9168 reports of separate user through separate smsboxes, by using 9169 configuration variable <literal>smsbox-id</literal> in group 9170 wap push user. Or you can use <literal>X-Kannel-Smsbox-Id 9171 </literal>. This means routing every message separately. </para> 9172 9173 <para> You can supply dlr url and dlr mask as kannel header, or 9174 as a configuration variable in ppg user or ppg core group. (This 9175 is order of precedence, too.) First one is valid for only one 9176 message, second for a specific user, and third for every ppg 9177 user. </para> 9178 9179 <para> So following is a minimum ppg core group for sms delivery 9180 reports:</para> 9181 9182<programlisting> 9183group = ppg 9184ppg-url = /wappush 9185ppg-port = 8080 9186concurrent-pushes = 100 9187trusted-pi = true 9188users = 1024 9189service-name = ppg 9190ppg-smsbox-id = dlrbox 9191</programlisting> 9192 9193 <para>And you can add Kannel headers to http post request. Here 9194 an example code snippet (C using Kannel gwlib; this example asks 9195 for all possible delivery reports).</para> 9196 9197<programlisting> 9198http_header_add(push_headers, "X-Kannel-SMSC", "link0"); 9199http_header_add(push_headers, "X-Kannel-DLR-Url", 9200 "http://193.53.0.56:8001/notification-dlr?smsc-id=%i" 9201 "&status=%d&answer=%A&to=%P&from=%p&ts=%t"); 9202http_header_add(push_headers, "X-Kannel-DLR-Mask", 9203 octstr_get_cstr(dos = octstr_format("%d", 31))); 9204http_header_add(push_headers, "X-Kannel-Smsbox-Id", "dlrbox")); 9205</programlisting> 9206 9207 <para>Here status=%d tells the type of the delivery report and 9208 answer=%A the delivery report itself (sms content of it). 9209 Other ones are needed to map delivery report to original wap 9210 push.</para> 9211 9212 <para>With these you can use with following http post request</para> 9213 9214<screen><userinput> 9215 http://193.53.0.56:8080/phplib/kannelgw.php?user=*deleted*& 9216 pass=*deleted*=to=%2B358408676001&text=3D%02%06%17%AE%96localhost 9217 %3A8080%00%AF%80%8D%CF%B4%80%02%05j%00E%C6%0C%03wap.iobox.fi%00%11%03 9218 1%40wiral.com%00%07%0A%C3%07%19%99%06%25%15%23%15%10%C3%04+%02%060%01 9219 %03Want+to+test+a+fetch%3F%00%01%01&udh=%06%05%04%0B%84%23%F0 9220</userinput></screen> 9221 9222 <para>Note that you can use all sms service escapes in dlrurl, see 9223 Parameters (Escape Codes) for details.</para> 9224 9225 <para> If you want to set dlr url for a specific user, you must set 9226 configuration variable <literal>dlr-url</literal>in <literal> 9227 wap-push-user</literal>, if for entire ppg, <literal>default-dlr-url 9228 </literal> in group <literal>ppg</literal>. Value must naturally match 9229 with one used in group smsc.</para> 9230</sect1> 9231 9232<sect1> 9233<title>Routing WAP pushes to a specific smsc</title> 9234 <para> This chapter explains how to route wap push to a specific 9235 smsc. </para> 9236 9237 <para> Smsc routing for wap pushes is similar to sms pushes. So, 9238 firstly you must define configuration variable <literal>smsc-id 9239 </literal> in smsc group (or groups) in question. Say you used 9240 value <literal>link0</literal>. You can send this as a Kannel 9241 header:</para> 9242 9243<programlisting> 9244http_header_add(push_headers, "X-Kannel-SMSC", "link0"); 9245</programlisting> 9246 9247 <para>Then you can issue a request:</para> 9248 9249<screen><userinput> 9250 http://193.53.0.56:8080/phplib/kannelgw.php?user=*deleted*& 9251 pass=*deleted*=to=%2B358408676001&text=3D%02%06%17%AE%96localhost 9252 %3A8080%00%AF%80%8D%CF%B4%80%02%05j%00E%C6%0C%03wap.iobox.fi%00%11%03 9253 1%40wiral.com%00%07%0A%C3%07%19%99%06%25%15%23%15%10%C3%04+%02%060%01 9254 %03Want+to+test+a+fetch%3F%00%01%01&udh=%06%05%04%0B%84%23%F0 9255</userinput></screen> 9256 9257 <para> You can use configuration variables to route all messages of a 9258 specific user or all ppg messages. Set <literal>default-smsc</literal> 9259 in group wap-push-user or in group ppg.</para> 9260 9261 <para>Again precedence of various methods of setting the smsc is 9262 kannel header, then configuration variable in group wap push user and 9263 then in group ppg.</para> 9264 9265</sect1> 9266 9267</chapter> 9268 9269 9270<chapter id="ssl-enabling"> 9271<title>Using SSL for HTTP</title> 9272 9273 <para>This chapter explains how you can use SSL to ensure 9274 secure HTTP communication on both, client and server side. 9275 </para> 9276 9277 <para>Beware that the gateway, is acting in both roles of 9278 the HTTP model: 9279 9280 <orderedlist> 9281 <listitem><para>as HTTP client, i.e. for requesting URLs 9282 while acting as WAP gateway and while fetching information 9283 for the SMS services.</para></listitem> 9284 <listitem><para>as HTTP server, i.e. for the administration HTTP 9285 interface, the PPG and for the sendsms HTTP interface. 9286 </para></listitem> 9287 </orderedlist> 9288 9289 That is why you can specify separate certification files within 9290 the core group to be used for the HTTP sides.</para> 9291 9292 <para>You can use one or both sides of the SSL support. There 9293 is no mandatory to use both if only one is desired.</para> 9294 9295 <sect1> 9296 <title>Using SSL client support</title> 9297 <para>To use the client support please use the following 9298 configuration directive within the core group</para> 9299<programlisting> 9300group = core 9301... 9302ssl-client-certkey-file = "filename" 9303</programlisting> 9304 <para>Now you are able to use https:// scheme URLs within 9305 your WML decks and SMS services.</para> 9306 </sect1> 9307 9308 <sect1> 9309 <title>Using SSL server support for the administration HTTP 9310 interface</title> 9311 <para>To use the SSL-enabled HTTP server please use the 9312 following configuration directive within the core group 9313 </para> 9314<programlisting> 9315group = core 9316... 9317admin-port-ssl = true 9318... 9319ssl-server-cert-file = "filename" 9320ssl-server-key-file = "filename" 9321</programlisting> 9322 </sect1> 9323 9324 <sect1> 9325 <title>Using SSL server support for the sendsms HTTP 9326 interface</title> 9327 <para>To use the SSL-enabled HTTP server please use the 9328 following configuration directive within the core and 9329 smsbox groups 9330 </para> 9331<programlisting> 9332group = core 9333... 9334ssl-server-cert-file = "filename" 9335ssl-server-key-file = "filename" 9336 9337group = smsbox 9338... 9339sendsms-port-ssl = true 9340</programlisting> 9341 </sect1> 9342 9343 <sect1> 9344 <title>Using SSL server support for PPG HTTPS interface</title> 9345 <para> 9346 If you want use PAP over HTTPS, (it is, a https scheme) add following 9347 directives to the ppg core group: 9348<programlisting> 9349group = ppg 9350... 9351ppg-ssl-port = 8090 9352ssl-server-cert-file = "/etc/kannel/cert1.pem" 9353ssl-server-key-file = "/etc/kannel/key1.pem" 9354</programlisting> 9355 </para> 9356 <para> 9357 PPG uses a separate port for HTTPS traffic, so so you must define it. This 9358 means that you can use both HTTP and HTTPS, when needed. 9359 </para> 9360 </sect1> 9361 9362</chapter> 9363 9364<chapter id="delivery-reports"> 9365<title>SMS Delivery Reports</title> 9366 9367 <para>This chapter explains how to set up Kannel to deliver delivery reports. 9368 </para> 9369 9370 <para>Delivery reports are a method to tell your system if the message 9371 has arrived on the destination phone. There are different things which can happen 9372 to a message on the way to the phone which are: 9373 </para> 9374 <para> 9375 <itemizedlist> 9376 <listitem><para>Message gets rejected by the SMSC (unknown subscriber, invalid destination number etc).</para></listitem> 9377 <listitem><para>Message gets accepted by the SMSC but the phone rejects the message.</para></listitem> 9378 <listitem><para>Message gets accepted by the SMSC but the phone is off or out of reach. 9379 The message gets buffered.</para></listitem> 9380 <listitem><para>Message gets successfully delivered.</para></listitem> 9381 </itemizedlist> 9382 </para> 9383 9384 <note> 9385 <para>If you want to use delivery reports, you must define a <literal>smsc-id</literal> for each smsc group.</para> 9386 </note> 9387 9388 <para>When you deliver SMS to Kannel you have to indicate what kind of delivery report messages you 9389 would like to receive back from the system. The delivery report types currently implemented are: 9390 <itemizedlist> 9391 <listitem><para>1: delivery success</para></listitem> 9392 <listitem><para>2: delivery failure</para></listitem> 9393 <listitem><para>4: message buffered</para></listitem> 9394 <listitem><para>8: smsc submit</para></listitem> 9395 <listitem><para>16: smsc reject</para></listitem> 9396 <listitem><para>32: smsc intermediate notifications</para></listitem> 9397 </itemizedlist> 9398 If you want multiple report types, you simply add the values together. For example if you want to get delivery success and/or failure 9399 you set the <literal>dlr-mask</literal> value to 1+2. and so on. If you specify <literal>dlr-mask</literal> on the URL you pass on to 9400 Kannel you also need to specify <literal>dlr-url</literal>. <literal>dlr-url</literal> should contain the URL to which 9401 Kannel should place a HTTP requests once the delivery report is ready to be delivered back to your system. 9402 </para> 9403 <para> 9404 An example transaction would work as following. 9405 <itemizedlist> 9406 <listitem><para>1. you send a message using dlr-mask=7 and dlr-url=http://www.xyz.com/cgi/dlr.php?myId=123456&type=%d</para></listitem> 9407 <listitem><para>2. Kannel forwards the message to the SMSC and keeps track of the message</para></listitem> 9408 <listitem><para>3. The SMSC can not reach the phone and thus returns a buffered message</para></listitem> 9409 <listitem><para>4. Kannel calls http://www.xyz.com/cgi/dlr.php?myId=123456&type=4 to indicate the message being buffered</para></listitem> 9410 <listitem><para>5. The phone is switched on and the SMS gets delivered from the SMSC. The SMSC reports this to Kannel</para></listitem> 9411 <listitem><para>6. Kannel calls http://www.xyz.com/cgi/dlr.php?myId=123456&type=1 to indicate the final success</para></listitem> 9412 </itemizedlist> 9413 <note> 9414 <para> 9415 If you put your own message ID in the dlr-url like in the example above, you can then use this ID to update your database 9416 with the message status. 9417 </para> 9418 </note> 9419 Depending on the SMSC type not all type of messages are supported. For example a CIMD SMSC does 9420 not support buffered messages. Also some SMSC drivers have not implemented all DLR types. 9421 </para> 9422</chapter> 9423 9424 9425<chapter id="bug-reporting"> 9426<title>Getting help and reporting bugs</title> 9427 9428 <para>This chapter explains where to find help with problems 9429 related to the gateway, and the preferred procedure for reporting 9430 bugs and sending corrections to them.</para> 9431 9432 <para>The Kannel development mailing list is devel@kannel.org. To subscribe, send mail to <ulink url="mailto:devel-subscribe@kannel.org">devel-subscribe@kannel.org</ulink>. 9433 This is currently the best location for asking help and reporting 9434 bugs. Please include configuration file and version number.</para> 9435 9436</chapter> 9437 9438<appendix id="upgrading-notes"> 9439<title>Upgrading notes</title> 9440 9441 <para>This appendix includes pertinent information about required 9442 changes on upgrades. 9443 </para> 9444 9445<sect1> 9446 <title>From 1.2.x or 1.3.1 to 1.3.2 and later</title> 9447 <para> 9448 <itemizedlist> 9449 <listitem><para>1. <literal>at</literal> module was dropped and <literal>at2</literal> module is now called <literal>at</literal></para></listitem> 9450 <listitem><para>2. <literal>emi</literal> module was renamed to <literal>emi_x25</literal>, <literal>emi_ip</literal> sub-module was dropped and <literal>emi2</literal> is now called <literal>emi</literal>.</para></listitem> 9451 </itemizedlist> 9452 </para> 9453</sect1> 9454 9455</appendix> 9456 9457<appendix id="certificates"> 9458<title>Certificate generation</title> 9459 9460 <para>This appendix includes pertinent information about required SSL 9461 certificate genaration, where needed. 9462 </para> 9463 9464<sect1> 9465 <title>Self-signed 1024-bit RSA SSL certificates using openssl</title> 9466 <para> 9467 <orderedlist numeration="arabic"> 9468 <listitem><para>Generate private key:</para> 9469 <para><literal>openssl genrsa -des3 -out server.key 1024</literal></para> 9470 <para>You will be asked for a passphrase.</para></listitem> 9471 9472 <listitem><para>Generate a certificate request:</para> 9473 <para><literal> 9474 openssl req -new -key server.key -out server.csr 9475 </literal></para> 9476 <para>Several questions follow. At the end you may send server.csr 9477 to a certificate authority, which in turn will sign it and 9478 generate the certificate for you, or you can sign it yourself. 9479 </para></listitem> 9480 9481 <listitem><para>Remove passphrase from key:</para> 9482 <para><literal>cp server.key server.key.org</literal> 9483 </para> 9484 <para><literal>openssl rsa -in server.key.org -out server.key 9485 </literal></para> 9486 <para><literal>rm server.key.org</literal></para> 9487 </listitem> 9488 9489 <listitem><para>Self-sign the certificate:</para> 9490 <para>If you chose not to send the request to a Certificate 9491 Authority, you will need to sign it yourself. This one is good 9492 for 1 year:</para> 9493 <para><literal>openssl x509 -req -days 365 -in server.csr -signkey 9494 server.key -out server.crt</literal></para> 9495 </listitem> 9496 9497 <listitem><para>Move keys to desired location:</para> 9498 <para><literal>mv server.crt /etc/kannel/public/server.crt</literal> 9499 </para> 9500 <para><literal>mv server.key /etc/kannel/private/server.key 9501 </literal></para> 9502 <para><literal>mv server.csr /etc/ianwap/private/ianwap.csr (key 9503 request)</literal></para> 9504 </listitem> 9505 </orderedlist> 9506 </para> 9507 <para>Update configuration accordingly</para> 9508</sect1> 9509 9510</appendix> 9511<appendix> 9512<title>Using the fake WAP sender</title> 9513 9514 <para>This appendix explains how to use the fake WAP sender 9515 to test the gateway.</para> 9516 9517</appendix> 9518 9519 9520<appendix> 9521<title>Using the fake SMS center</title> 9522 9523 <para>Fakesmsc is a simple testing tool to test out Kannel and 9524 its SMS services. It <emphasis>cannot</emphasis> be used to 9525 send messages to mobile terminals, it is just a simulated SMS 9526 center with no connection to real terminals.</para> 9527 9528<sect1> 9529<title>Setting up fakesmsc</title> 9530 9531 <para>This section sums up needed steps to set up system for 9532 fakesmsc use.</para> 9533 9534 9535<sect2> 9536<title>Compiling fakesmsc</title> 9537 9538 <para>The fake SMS center should compile at the same time as main 9539 Kannel compiles. The outcome binary, 9540 <literal>fakesmsc</literal>, is in <literal>test</literal> 9541 directory. The source code is quite simple and trivial, and is 9542 easily edited.</para> 9543 9544</sect2> 9545<sect2> 9546<title>Configuring Kannel</title> 9547 9548 <para>To use <literal>fakesmsc</literal> to test out Kannel, you 9549 have to add it to main configuration file (see above). The 9550 simplest form for this configuration group is like this:</para> 9551 9552<programlisting> 9553group = smsc 9554smsc = fake 9555port = 10000 9556</programlisting> 9557 9558 <para>The fakesmsc configuration group accepts all common 'smsc' 9559 configuration group variables, like <literal>smsc-id</literal>, 9560 <literal>preferred-smsc-id</literal> or 9561 <literal>denied-smsc-id</literal>, which can be used to test out 9562 routing systems and diverted services, before setting up real 9563 SMS center connections. If you include a fakesmsc group when 9564 bearerbox is connected to real SMS centers, you should add 9565 the <literal>connect-allow-ip</literal> variable to prevent 9566 unauthorized use.</para> 9567 9568 <para>To set up multiple fakesmsc'es, just add new 9569 groups. Remember to put a different port number to each one.</para> 9570 9571</sect2> 9572 9573</sect1> 9574<sect1> 9575<title>Running Kannel with fakesmsc connections</title> 9576 9577 <para>After configuring Kannel, you can start testing 9578 it. The bearerbox will listen for fakesmsc client connections 9579 to the port(s) specified in the configuration file.</para> 9580 9581<sect2> 9582<title>Starting fake SMS center</title> 9583 9584 <para>Each fakesmsc is started from command line, with all sent 9585 messages after command name. If any options are used (see below), 9586 they are put between the command and the messages. The usage is as 9587 follows:</para> 9588 9589<programlisting> 9590test/fakesmsc [options] <message1> [message2 ...] 9591</programlisting> 9592 9593 <para>Options and messages are explained below, but as a quick 9594 example, a typical startup can go like this:</para> 9595 9596<programlisting> 9597test/fakesmsc -i 0.1 -m 100 "100 200 text nop" "100 300 text echo this" 9598</programlisting> 9599 9600 <para>This tells fakesmsc to connect to bearerbox at localhost:10000 9601 (default) and send a hundred messages with an interval of 0.1 seconds. 9602 Each message is from number 100, and is either to number 200 with 9603 message 'nop' or to 300 with message 'echo this'.</para> 9604 9605 <para>Messages received from bearerbox are shown in the same format 9606 (described below).</para> 9607 9608<sect3> 9609<title>Fake messages</title> 9610 9611 <para>Each message consists of four or five parts: sender number, 9612 receiver number, type, udh (if present) and main message itself. 9613 Sender and receiver numbers do not mean anything except for log files 9614 and number-based routing in Kannel.</para> 9615 9616 <para>The parts of a message are separated with spaces. As each message is 9617 taken as one argument, it must be put in quotation marks.</para> 9618 9619 <para>Message type must be one of the following: "text", "data" and "udh". 9620 Here's an example of using each:</para> 9621 9622<programlisting> 9623test/fakesmsc -i 0.01 -v 1 -m 1000 "100 300 text echo this message" 9624test/fakesmsc -i 0.01 -m 1000 "100 300 data echo+these+chars%03%04%7f" 9625test/fakesmsc -m 1 "100 500 udh %0eudh+stuff+here main+message" 9626</programlisting> 9627 9628 <para>For "text", the rest of the argument is taken as the literal 9629 message. For "data", the next part must be the url-encoded version of 9630 the message. Space is coded as '+'. For "udh", the next 2 parts 9631 are the UDH and main message. Both must be in url-encoded form.</para> 9632 9633 <para>If multiple messages are given, fakesmsc randomly chooses 9634 one for each sending.</para> 9635 9636</sect3> 9637<sect3> 9638<title>Interactive mode</title> 9639 <para>If no messages are passed on the command line when starting fakesmsc, 9640 it runs on "interactive mode".</para> 9641 <para>When running on this mode, fakesmsc accept single messages typed on stdin 9642 (without quotation marks) and displays the responses on stdout. This allows 9643 for a more finely controlled interaction with the backend applications.</para> 9644</sect3> 9645<sect3> 9646<title>Fakesmsc command line options</title> 9647 9648 <para>Fake SMS center can be started with various optional command 9649 line arguments.</para> 9650 9651 <table frame="none"> 9652 <title>Fakesmsc command line options</title> 9653 <tgroup cols="3"> 9654 <thead> 9655 <row> 9656 <entry>Switch</entry> 9657 <entry>Value</entry> 9658 <entry>Description</entry> 9659 </row> 9660 </thead> 9661 <tbody> 9662 <row><entry><literal>-H</literal></entry> 9663 <entry><emphasis>host</emphasis></entry> 9664 <entry valign="bottom"> 9665 Use host <emphasis>host</emphasis> instead of default 9666 <literal>localhost</literal>. 9667 </entry></row> 9668 9669 <row><entry><literal>-r</literal></entry> 9670 <entry><emphasis>port</emphasis></entry> 9671 <entry valign="bottom"> 9672 Use port number <emphasis>port</emphasis> instead of default 9673 10000. 9674 </entry></row> 9675 9676 <row><entry><literal>-i</literal></entry> 9677 <entry><emphasis>interval</emphasis></entry> 9678 <entry valign="bottom"> 9679 Use message interval <emphasis>interval</emphasis> (in seconds, 9680 fractions accepted) instead of default interval 1.0 seconds. 9681 </entry></row> 9682 9683 <row><entry><literal>-m</literal></entry> 9684 <entry><emphasis>max</emphasis></entry> 9685 <entry valign="bottom"> 9686 Send a maximum of <emphasis>max</emphasis> messages. Value -1 9687 means that an unlimited number of messages is sent. Default -1. 9688 Using 0 can be useful to listen for messages sent via other 9689 channels. 9690 </entry></row> 9691 </tbody> 9692 </tgroup> 9693 </table> 9694 9695 <para>In addition, fakesmsc accepts all common Kannel <xref 9696 linkend="arguments" endterm="arguments.title"/> like 9697 <literal>--verbosity</literal>.</para> 9698 9699</sect3> 9700 9701</sect2> 9702</sect1> 9703 9704</appendix> 9705 9706<appendix> 9707<title>Setting up a test environment for Push Proxy Gateway</title> 9708 9709 <para>This appendix explains how to set a test environment for PPG. 9710 This contains a simulated SMSC, for instance a http server simulation 9711 (this is used as example, because it is simplest) and a simulated 9712 push initiator. Between them, there is the push proxy gateway to be 9713 tested. This means that you must configure HTTP SMSC. 9714 </para> 9715<sect1> 9716<title>Creating push content and control document for testing</title> 9717 <para> 9718 Here is an example of a push control document, which gives PPG 9719 instructions how to do the pushing. 9720 <programlisting> 9721<?xml version="1.0"?> 9722<!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP//EN" 9723 "http://www.wapforum.org/DTD/pap_1.0.dtd"> 9724<pap> 9725 <push-message push-id="9fjeo39jf084@pi.com" 9726 deliver-before-timestamp="2001-09-28T06:45:00Z" 9727 deliver-after-timestamp="2001-02-28T06:45:00Z" 9728 progress-notes-requested="false"> 9729 <address address-value="WAPPUSH=+358408676001/TYPE=PLMN@ppg.carrier.com"/> 9730 <quality-of-service priority="low" 9731 delivery-method="unconfirmed" 9732 network-required="true" 9733 network="GSM" 9734 bearer-required="true" 9735 bearer="SMS"/> 9736 </push-message> 9737</pap> 9738 </programlisting> 9739 Because the push content is send to the phone over SMS, right value for 9740 <literal>network-required</literal> and <literal>bearer-required 9741 </literal> is true, for <literal>network</literal> GSM and for <literal>bearer 9742 </literal> SMS. However, you can omit these values altogether, if you use 9743 a phone number as an address. Address value is international phone number and 9744 it must start with plus. It is used here as an unique identifier, SMSC, or 9745 sendsms script must transform it to an usable phone number. 9746 </para> 9747 <para> 9748 Here is an example of Service Indication, a type of push content. 9749 Essentially, the phone displays, when it receives this SI, the text 9750 "Want to test a fetch" and if the user wants, fetches the content 9751 located by URL <literal>http://wap.iobox.fi</literal>. 9752 <programlisting> 9753<?xml version="1.0"?> 9754<!DOCTYPE si PUBLIC "-//WAPFORUM//DTD SI 1.0//EN" 9755 "http://www.wapforum.org/DTD/si.dtd"> 9756<si> 9757 <indication href="http://wap.iobox.fi" 9758 si-id="1@wiral.com" 9759 action="signal-high" 9760 created="1999-06-25T15:23:15Z" 9761 si-expires="2002-06-30T00:00:00Z"> 9762 Want to test a fetch? 9763 </indication> 9764</si> 9765 </programlisting> 9766 Note that the date value of the si-expires attribute contains trailing 9767 zeroes. They are OK here, because SI tokenizer removes them. But phones 9768 does not accept them in the final SMS data message. You should probably 9769 use <literal>action="signal-high"</literal> for testing purposes, for 9770 it causes an immediate presentation of the push message. Production 9771 usage is a quite another matter. 9772 </para> 9773 9774 <para> 9775 Another example of push content is Service Loading. In principle, the phone 9776 should fetch immediately content from URL <literal>http://wap.iobox.fi 9777 </literal> when it receives this document. This sounds quite insecure, and 9778 indeed, user invention is probably required before fetching. 9779 9780 <programlisting> 9781<?xml version="1.0"?> 9782<!DOCTYPE sl PUBLIC "-//WAPFORUM//DTD SL 1.0//EN" 9783 "http://www.wapforum.org/DTD/sl.dtd"> 9784<sl href="http://wap.iobox.fi" 9785 action="execute-high"> 9786</sl> 9787 </programlisting> 9788 </para> 9789 9790</sect1> 9791<sect1> 9792<title>Starting necessary programs</title> 9793 <para>PPG test environment contains, in addition of wapbox and 9794 bearerbox, two test programs, <literal>test_ppg</literal> (simulating 9795 push initiator) and <literal>test_http_server</literal> (simulating 9796 a SMSC center accepting pushed content send over SMS. You can find 9797 both of these programs in <literal>test</literal> directory, and they 9798 both are short and easily editable. </para> 9799 9800 <para>To set up a test environment, you must first configure a push 9801 proxy gateway (setting flag trusted-pi true makes testing easier). 9802 This explained in Chapter "Setting up push proxy gateway". Then issue 9803 following commands, in Kannel's root directory and in separate windows: 9804 <screen><userinput> 9805 gw/bearerbox [config-file] 9806 gw/wapbox [config-file] 9807 </userinput></screen> 9808 Of course you can use more complicated wapbox and bearerbox command 9809 line options, if necessary.</para> 9810 9811 <para>To run a http smsc, start http server simulation: 9812 <screen><userinput> 9813 test/test_http_server -p port 9814 </userinput></screen> 9815 You can, of course, select the port at will. Remember, though, that 9816 PPG listens at the port defined in the ppg configuration file. Other 9817 <literal>test_http_server</literal> options are irrelevant here.</para> 9818 9819 <para>Lastly, start making push requests, for instance with a test 9820 program <literal> test_ppg</literal>. Its first argument is a URL 9821 specifying location of push services. Other arguments are two file 9822 names, first one push content and second one pap control document. 9823 (For command line options, see Table C.1.). For example doing one 9824 push(you can simplify push url by setting a ppg configuration variable, 9825 see "Setting up push proxy gateway"; q flag here prevents dumping of 9826 test_ppg program debugging information): 9827 </para> 9828 <screen><userinput> 9829 test/test_ppg -q http://ppg-host-name:ppg-port/ppg-url [content_file] 9830 [control_file] 9831 </userinput></screen> 9832 9833 <para> This presumes that you have set trusted-pi true. 9834 </para> 9835 9836 <para>If you want use authentication in a test environment, you can pass 9837 username and password either using headers (setting flag -b) or url (you 9838 must have set trusted-pi false and added wap-push-user configuration group): 9839 </para> 9840 9841 <screen><userinput> 9842 test/test_ppg -q http://ppg-host-name:ppg-port?username=ppg-username'&' 9843 password=ppg-password [content_file] [control_file] 9844 </userinput></screen> 9845 9846 <table frame="none"> 9847 <title>Test_ppg's command line options</title> 9848 <tgroup cols="3"><thead><row> 9849 <entry>Switch</entry> 9850 <entry>Value</entry> 9851 <entry>Description</entry> 9852 </row></thead> 9853 <tbody> 9854 <row><entry><literal>-c</literal></entry> 9855 <entry><emphasis>string</emphasis></entry> 9856 <entry valign="bottom"> 9857 Use content qualifier <emphasis>string</emphasis> instead of 9858 default <literal>si</literal> (service indication). Allowed 9859 values are wml, si, sl, sia, multipart, nil and scrap. Nil and 9860 scrap are used for debugging purposes. Wml does work with some 9861 older phone simulators. 9862 </entry></row> 9863 <row><entry><literal>-a</literal></entry> 9864 <entry><emphasis>string</emphasis></entry> 9865 <entry valign="bottom"> 9866 Use application id <emphasis>string</emphasis> instead of default 9867 <literal>any</literal>. Application identifies the application in 9868 the phone that should handle the push request. Sia, ua, mms, nil 9869 and scrap are accepted. Nil and scrap are used for debugging 9870 purposes. 9871 </entry></row> 9872 <row><entry><literal>-e</literal></entry> 9873 <entry><emphasis>string</emphasis></entry> 9874 <entry valign="bottom"> 9875 Use transfer encoding when sending a push content. Only base64 is 9876 currently supported. 9877 </entry></row> 9878 <row><entry><literal>-b</literal></entry> 9879 <entry><emphasis>boolean</emphasis></entry> 9880 <entry valign="bottom"> 9881 Use headers for authentication, instead of url. Default off. 9882 </entry></row> 9883 <row><entry><literal>-i</literal></entry> 9884 <entry><emphasis>number</emphasis></entry> 9885 <entry valign="bottom"> 9886 Wait interval <emphasis>number</emphasis> instead of default 9887 <literal>0</literal> between pushes. 9888 </entry></row> 9889 <row><entry><literal>-r</literal></entry> 9890 <entry><emphasis>number</emphasis></entry> 9891 <entry valign="bottom"> 9892 Do <emphasis>number</emphasis> requests instead of default 9893 <literal>1</literal>. 9894 </entry></row> 9895 <row><entry><literal>-t</literal></entry> 9896 <entry><emphasis>number</emphasis></entry> 9897 <entry valign="bottom"> 9898 Use <emphasis>number</emphasis> threads instead of default 9899 <literal>1</literal>. 9900 </entry></row> 9901 <row><entry><literal>-s</literal></entry> 9902 <entry><emphasis>string</emphasis></entry> 9903 <entry valign="bottom"> 9904 Use <literal>string</literal> as a X-WAP-Application-Id 9905 header (You must supply whole header). 9906 </entry></row> 9907 9908 <row><entry><literal>-I</literal></entry> 9909 <entry><emphasis>string</emphasis></entry> 9910 <entry valign="bottom"> 9911 Use <literal>string</literal> as a X-WAP-Initiator-URI 9912 header (You must supply whole header). 9913 </entry></row> 9914 9915 <row><entry><literal>-B</literal></entry> 9916 <entry><emphasis>boolean</emphasis></entry> 9917 <entry valign="bottom"> 9918 If set, accept binary content. Default is off. 9919 <literal>1</literal>. 9920 </entry></row> 9921 <row><entry><literal>-d</literal></entry> 9922 <entry><emphasis>enumerated string</emphasis></entry> 9923 <entry valign="bottom"> 9924 Set delimiter to be used. Acceptable values are crlf and 9925 lf. Default is <literal>crlf</literal>. 9926 </entry></row> 9927 <row><entry><literal>-p</literal></entry> 9928 <entry><emphasis>boolean</emphasis></entry> 9929 <entry valign="bottom"> 9930 If set, add an preamble (hard-coded one). Default 9931 is off. 9932 </entry></row> 9933 <row><entry><literal>-E</literal></entry> 9934 <entry><emphasis>boolean</emphasis></entry> 9935 <entry valign="bottom"> 9936 if set, add an epilogue (hard-coded). Default is off. 9937 </entry></row> 9938 </tbody> 9939 </tgroup> 9940 </table> 9941</sect1> 9942<sect1> 9943<title>Using Nokia Toolkit as a part of a developing environment</title> 9944 <para>This chapter describes a developing environment using Nokia 9945 Toolkit instead of <literal>test_http_server</literal> program. 9946 </para> 9947 <para>You cannot use a real phone for testing a push server. Sending 9948 random messages to a phone does not work, because its only feedback 9949 (if it works properly) in error situations is dropping the offending 9950 message.</para> 9951 <para>Nokia Toolkit, instead, displays push headers, decompiles 9952 tokenized documents and outputs debugging information. It is not, 9953 of course, a carbon copy of a real phone. But it is still useful 9954 for checking spec conformance of push servers.</para> 9955 <para>Toolkit runs on Windows, the first thing you must is to install 9956 a virtual machine (VMWare is one possibility) in the machine where 9957 Kannel runs. Then you must configure Toolkit for working with a push 9958 gateway.</para> 9959 <para>Then start <literal>bearerbox</literal> and <literal>wapbox 9960 </literal> similar way as told before. You must set the correct client 9961 address in the push document send by <literal>test_ppg</literal> 9962 program. Use IP address of our virtual machine (easiest way to get this 9963 is to ping your virtual machine name in the dos prompt window). Your 9964 bearer is in this case IP. An example pap document follows:</para> 9965 9966 <programlisting> 9967<?xml version="1.0"?> 9968<!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP//EN" 9969 "http://www.wapforum.org/DTD/pap_1.0.dtd"> 9970<pap> 9971 <push-message push-id="9fjeo39jf084@pi.com" 9972 deliver-before-timestamp="2001-09-28T06:45:00Z" 9973 deliver-after-timestamp="2001-02-28T06:45:00Z" 9974 progress-notes-requested="false"> 9975 <address address-value="WAPPUSH=192.168.214.1/TYPE=IPV4@ppg.carrier.com"/> 9976 <quality-of-service priority="low" 9977 delivery-method="unconfirmed" 9978 </quality-of-service> 9979 </push-message> 9980</pap> 9981 </programlisting> 9982 <para>Note address-value format. It is contains type and value, 9983 because PAP protocol supports different address formats.</para> 9984 <para>You must use <literal>test_ppg</literal>'s -a and -c flags 9985 when pushing messages to Toolkit. -A defines the client application 9986 handling pushes, right value for it is ua. -C defines the content 9987 type of your push message. SI works with all Toolkits, wml only 9988 with some older versions. </para> 9989</sect1> 9990 9991 <sect1> 9992 <title>Testing PAP protocol over HTTPS </title> 9993 <para> 9994 When testing HTTPS connection to PPG, you probably want use test_ppg's 9995 configuration file, because number of required parameters is quite 9996 high. Here is a example test_ppg configuration file: 9997 </para> 9998 9999<programlisting> 10000 group = test-ppg 10001 retries = 2 10002 pi-ssl = yes 10003 ssl-client-certkey-file = /etc/kannel/certkey.pem 10004 10005 group = configuration 10006 push-url = https://localhost:8900/wappush 10007 pap-file = /etc/kannel/ipnoqos.txt 10008 content-file = /etc/kannel/si.txt 10009 username = foo 10010 password = bar 10011</programlisting> 10012 10013 <para> 10014 With a configuration file, you can do a push by typing: 10015 </para> 10016 10017 <screen><userinput> 10018 test/test_ppg -q [configuration_file] 10019 </userinput></screen> 10020 10021 <table frame="none"> 10022 <title>Test_ppg's configuration file directives</title> 10023 <tgroup cols="3"><thead><row> 10024 <entry>Directive</entry> 10025 <entry>Value</entry> 10026 <entry>Description</entry> 10027 </row></thead> 10028 <tbody> 10029 <row><entry><literal>group</literal></entry> 10030 <entry><emphasis>test_ppg</emphasis></entry> 10031 <entry valign="bottom"> 10032 Mandatory parameter. Start of test_ppg's core group. 10033 </entry></row> 10034 <row><entry><literal>retries</literal></entry> 10035 <entry><emphasis>number</emphasis></entry> 10036 <entry valign="bottom"> 10037 The client tries to log in to PPG <emphasis>number</emphasis> times 10038 before discarding the push request. Default is 2. 10039 </entry></row> 10040 <row><entry><literal>pi-ssl</literal></entry> 10041 <entry><emphasis>boolean</emphasis></entry> 10042 <entry valign="bottom"> 10043 Mandatory parameter for HTTPS connection. Does the client use HTTPS 10044 connection. Default is no. 10045 </entry></row> 10046 <row><entry><literal>ssl-client-certkey-file</literal></entry> 10047 <entry><emphasis>filename</emphasis></entry> 10048 <entry valign="bottom"> 10049 Mandatory parameter for HTTPS connection. File containing the client's 10050 ssl certificate and private key. 10051 </entry></row> 10052 <row><entry><literal>ssl-trusted-ca-file</literal></entry> 10053 <entry>filename</entry> 10054 <entry valign="bottom"> 10055 Mandatory parameter for HTTPS connection.This file contains the 10056 certificates test_ppg is willing to trust. If this directive is not set, 10057 certificates are not validated and HTTPS would not be tested. 10058 </entry></row> 10059 <row><entry><literal>group</literal></entry> 10060 <entry><emphasis>configuration</emphasis></entry> 10061 <entry valign="bottom"> 10062 Mandatory parameter. Start of test_ppg's test group. 10063 </entry></row> 10064 <row><entry><literal>push-url</literal></entry> 10065 <entry><emphasis>url</emphasis></entry> 10066 <entry valign="bottom"> 10067 Mandatory value. URL locating PPG's services. 10068 </entry></row> 10069 <row><entry><literal>pap-file</literal></entry> 10070 <entry><emphasis>filename</emphasis></entry> 10071 <entry valign="bottom"> 10072 Mandatory value. File containing pap request's control document. 10073 </entry></row> 10074 <row><entry><literal>content-file</literal></entry> 10075 <entry><emphasis>filename</emphasis></entry> 10076 <entry valign="bottom"> 10077 Mandatory value. File containing pap request's content document. 10078 </entry></row> 10079 <row><entry><literal>username</literal></entry> 10080 <entry><emphasis>string</emphasis></entry> 10081 <entry valign="bottom"> 10082 Mandatory value. PPG service user's username. 10083 </entry></row> 10084 <row><entry><literal>password</literal></entry> 10085 <entry><emphasis>string</emphasis></entry> 10086 <entry valign="bottom"> 10087 Mandatory value. PPG service user's password. 10088 </entry></row> 10089 </tbody> 10090 </tgroup> 10091 </table> 10092 </sect1> 10093</appendix> 10094 10095<appendix> 10096<title>Setting up a dial-up line</title> 10097 10098 <para>This appendix explains how to set up a dial-up line in Linux 10099 for use with the Kannel WAP gateway. In order for it to work you need 10100 a Linux kernel with PPP capabilities. Most distributions provides PPP 10101 kernel support by default. For more information how to compile PPP 10102 support into the kernel please read the "Linux Kernel HOWTO" 10103 at http://www.linuxdoc.org/.</para> 10104 10105<sect1> 10106<title>Analog modem</title> 10107 10108 <para>This section explains how to set up a dial-up line with an 10109 analog modem.</para> 10110 10111 <para>Download and install the mgetty package.</para> 10112 10113 <screen><userinput> 10114 rpm -ivh mgetty-VERSION-rpm 10115 </userinput></screen> 10116 10117 <para>To run mgetty as a daemon, add the following line to 10118 /etc/inittab.</para> 10119 10120 <para>Read man inittab for more detailed information. In this 10121 example we assume your modem is connected to the serial port ttyS0 10122 (COM 1).</para> 10123 10124 <screen><userinput> 10125 S0:2345:respawn:/sbin/mgetty ttyS0 -x 6 -D /dev/ttyS0 10126 </userinput></screen> 10127 10128 <para>We need to start the pppd automatically when mgetty receives 10129 an AutoPPP request. Add the next line to /etc/mgetty+sendfax/login.config</para> 10130 10131 <screen><userinput> 10132 /AutoPPP/ - - /usr/sbin/pppd file /etc/ppp/options.server 10133 </userinput></screen> 10134 10135 <para>In /etc/mgetty+sendfax/mgetty.config you might need to change 10136 the connect speed between the computer and the modem. Note: this is 10137 not the connect speed between the WAP client and the server modem. 10138 If you are e.g. going to use a Nokia 7110 as the server side modem 10139 you need to change the speed to 19200. Usually you can just leave the 10140 speed to the default value (38400).</para> 10141 10142 <screen><userinput> 10143 speed 38400 10144 </userinput></screen> 10145 10146 <para>Add the following lines to /etc/ppp/options.server</para> 10147 10148 <screen><userinput> 10149 refuse-chap 10150 require-pap 10151 lock 10152 modem 10153 crtscts 10154 passive 10155 192.168.1.10:192.168.1.20 10156 debug 10157 </userinput></screen> 10158 10159 <para>In /etc/ppp/pap-secrets add the username and password for the 10160 ppp account. The IP address is the one assigned to the phone.</para> 10161 10162 <screen><userinput> 10163 wapuser * wappswd 192.168.0.20 10164 </userinput></screen> 10165 10166 <para>Configure your phone (this example is for Nokia 7110)</para> 10167 10168 <screen><userinput> 10169 homepage http:/yourhost/hello.wml 10170 connection type continuous 10171 connection security off 10172 bearer data 10173 dial up number (your phone number) 10174 ip address (IP of host running bearerbox) 10175 auth type normal 10176 data call type analogue 10177 data call speed 9600 10178 username wapuser 10179 password wappswd 10180 </userinput></screen> 10181</sect1> 10182 10183<sect1> 10184<title>ISDN terminal</title> 10185 10186 <para>This section needs to be written</para> 10187 10188</sect1> 10189 10190</appendix> 10191 10192<appendix id="regular-expressions" xreflabel="Regular Expressions"> 10193 <title>Regular Expressions</title> 10194 <para>Note: this is not intended to be an introduction to regular expressions (short: regex) but a 10195 description of their application within Kannel. For general information regarding regexes 10196 please refer to <xref linkend="Biblio-regexp"/>. 10197 </para> 10198 <sect1> 10199 <title>Syntax and semantics of the regex configuration parameter</title> 10200 <para>This section describes the regex-configuration parameters and their effects in combination with the 10201 respective non-regex-parameter, e.g. <literal>white-list</literal> and <literal>white-list-regex</literal>.</para> 10202 10203 <sect2> 10204 <title>How-to setup the regex-parameters</title> 10205 <para>examples, short syntax, what happens on errors 10206 Regex-parameters are configured just as every other parameter is configured. Regular expressions are 10207 supported as defined by POSIX Extended Regular Expressions. Suppose a configuration where only SMS messages 10208 originating from a sender using a number with a prefix of "040", "050", "070" or "090" are accepted. 10209 Without regexes the configuration would read 10210 <programlisting> 10211 allowed-prefix="040;050;070;090" 10212 </programlisting> 10213 Using regular expressions yields a more concise configuration 10214 <programlisting> 10215 allowed-prefix-regex=^0[4579]0 10216 </programlisting> 10217 The following table gives an overview over some regex-operators and their meaning, the POSIX Regular 10218 Expressions manual page (regex(7)). Once again, the extended regex-syntax is used and the table is 10219 just meant as a means to give a quick-start to regular expressions, the next section features some more 10220 complex examples. 10221 <informaltable> 10222 <tgroup cols="2"> 10223 <thead> 10224 <row> 10225 <entry>Operator</entry> 10226 <entry>Meaning</entry> 10227 </row> 10228 </thead> 10229 <tbody> 10230 <row> 10231 <entry><literal>|</literal></entry> 10232 <entry>or, for example "dog|hog" matches dog or hog.</entry> 10233 </row> 10234 <row> 10235 <entry><literal>{number,number}</literal></entry> 10236 <entry>repetition, for example "a{2,5}" matches - among others - 10237 "aa", "aaa" and "baaaaad"</entry> 10238 </row> 10239 <row> 10240 <entry><literal>*</literal></entry> 10241 <entry>shorthand for {0,}</entry> 10242 </row> 10243 <row> 10244 <entry><literal>?</literal></entry> 10245 <entry>shorthand for {0,1}</entry> 10246 </row> 10247 <row> 10248 <entry><literal>+</literal></entry> 10249 <entry>shorthand for {1,}</entry> 10250 </row> 10251 <row> 10252 <entry><literal>[]</literal></entry> 10253 <entry>bracket expression, defines a class of possible single character matches. 10254 For example "[hb]og" matches "hog" and "bog". If the expression starts with 10255 <literal>^</literal> then the class is negated, e.g. "[^hb]og" does not match 10256 "hog" and "bog" but matches for example "dog".</entry> 10257 </row> 10258 <row> 10259 <entry><literal>()</literal></entry> 10260 <entry>groups patterns, e.g. "[hb]o(g|ld)" matches "hog", "hold", "bog", "bold" 10261 </entry> 10262 </row> 10263 <row> 10264 <entry><literal>[:class:]</literal></entry> 10265 <entry>A character class such as digit, space etc. See wctype(3) for details. 10266 </entry> 10267 </row> 10268 <row> 10269 <entry><literal>^</literal></entry> 10270 <entry>Start of line anchor.</entry> 10271 </row> 10272 <row> 10273 <entry><literal>$</literal></entry> 10274 <entry>End of line anchor.</entry> 10275 </row> 10276 </tbody> 10277 </tgroup> 10278 </informaltable> 10279 10280 The advantages of regular expressions are at hand 10281 <itemizedlist> 10282 <listitem><para>Regexes are easier to understand, if one is fluent in POSIX Regular Expressions. 10283 Although simple expressions as shown above should be clear to everyone who has 10284 ever used a standard UN*X shell. 10285 </para></listitem> 10286 <listitem> 10287 <para>Regexes are easier to maintain. Suppose the example above needed to cope with 10288 dozens of different prefixes each with subtle differences, in such cases using a - carefully 10289 constructed - regular expression could help to keep things in apple pie order. 10290 Furthermore regexes help reducing redundancy within the configuration. 10291 </para> 10292 </listitem> 10293 <listitem> 10294 <para>Regexes more flexible than standard parameters. 10295 </para> 10296 </listitem> 10297 </itemizedlist> 10298 Nevertheless, it must be mentioned that - in addition to the overhead involved - complexity is an issue, 10299 too. Although the syntactic correctness of each used regular expression is ensured (see below) 10300 the semantic correctness cannot be automatically proofed. 10301 </para> 10302 <para> 10303 Expressions that are not compilable, which means they are not valid POSIX regexes, force Kannel 10304 to panic with a message like (note the missing "]") 10305 <screen><computeroutput> 10306 ERROR: gwlib/regex.c:106: gw_regex_comp_real: regex compilation `[hbo(g|ld)' failed: Invalid regular expression (Called from gw/urltrans.c:987:create_onetrans.) 10307 PANIC: Could not compile pattern '[hbo(g|ld)' 10308 </computeroutput></screen> 10309 As shown the erroneous pattern is reported in the error message. 10310 </para> 10311 </sect2> 10312 10313 <sect2> 10314 <title>Regex and non-regex-parameters</title> 10315 <para> 10316 Using the regex and non-regex version of a parameter at the same time should be done with caution. 10317 Both are combined in a boolean-or sense, for example 10318 <programlisting> 10319 white-list=01234 10320 white-list-regex=^5(23)?$ 10321 </programlisting> 10322 implies that a number is accepted either if it is "01234", "5" or "523" - note the use of anchors! 10323 The same goes for all the other parameters, thus both mechanisms can be used without problems in parallel, 10324 but care should be taken that the implications are understood and wanted. 10325 </para> 10326 </sect2> 10327 10328 <sect2> 10329 <title>Performance issues</title> 10330 <para>While there is some overhead involved, the actual performance degradation is negligible. 10331 At startup - e.g. when the configuration files are parsed - the regular expressions are pre-compiled 10332 and stored in the pre-compiled fashion, thus future comparisons involve executing the expression on 10333 some string only. To be on the sure side, before using regexes extensively some benchmarking should be 10334 performed, to verify that the loss of performance is acceptable. 10335 </para> 10336 </sect2> 10337 </sect1> 10338 <sect1> 10339 <title>Examples</title> 10340 <para>This section discusses some simple scenarios and potential solutions based on regexes. 10341 The examples are not meant to be comprehensive but rather informative.</para> 10342 <sect2> 10343 <title>Example 1: core-configuration</title> 10344 <para>The bearerbox must only accept SMS messages from three costumers. The first costumer uses numbers 10345 that always start with "0824" the second one uses numbers that start with either "0123" and end in 10346 "314" or start with "0882" and end in "666". The third costumer uses numbers starting with "0167" 10347 and ending in a number between "30" and "57".</para> 10348 <para> 10349 Important in this and in the following examples is the use of anchors, otherwise a "string contains" 10350 semantic instead of a "string is equal" semantic would be used. 10351 </para> 10352 <programlisting> 10353 group=core 10354 ... 10355 white-list-regex=^((0824[0-9]+)|(0123[0-9]+314)|(0882[0-9]+666)|(0167[0-9]+([34][0-9]|5[0-7])))$ 10356 ... 10357 </programlisting> 10358 </sect2> 10359 <sect2> 10360 <title>Example 3: smsc-configuration</title> 10361 <para>Only SMS messages originating from certain SMSCs (<literal>smsc-id</literal> is either 10362 "foo", "bar" or "blah") 10363 are preferably forwarded to this smsc. 10364 Furthermore all SMSCs with an id containing "vodafone" must never 10365 be forwarded to the smsc. Not the missing anchors around "vodafone".</para> 10366 <programlisting> 10367 group=smsc 10368 ... 10369 preferred-smsc-id-regex=^(foo|bar|blah)$ 10370 denied-prefix-regex=vodafone 10371 ... 10372 </programlisting> 10373 </sect2> 10374 <sect2> 10375 <title>Example 4: sms-service-configuration</title> 10376 <para>Please note that there are a mandatory <literal>keyword</literal> and an optional 10377 <literal>keyword-regex</literal> fields. 10378 That means that service selection can be simplified as in the following example. 10379 Suppose that some Web-content should be delivered to the mobile. Different costumers use the 10380 same service but they rely on different keywords. Whenever a sms-service is requested, Kannel 10381 first checks whether a regex has been defined, if not a literal match based on <literal>keyword</literal> 10382 is performed. If a regex is configured then the literal match is never tried. 10383 </para> 10384 <programlisting> 10385 group=sms-service 10386 ... 10387 keyword=web_service 10388 keyword-regex=^(data|www|text|net)$ 10389 get-url=http://someserver.net/getContent.jsp 10390 ... 10391 </programlisting> 10392 </sect2> 10393 </sect1> 10394</appendix> 10395 10396<appendix id="meta-data" xreflabel="Meta Data"> 10397 <title>Meta Data</title> 10398 <para>This appendix describes the elements and syntax required to access meta-data coming from and going to SMSC connections.</para> 10399 <sect1> 10400 <title>Overview</title> 10401 <para>Many SMSC services have means to exchange data that doesn't conform to the established format</para> 10402 <para>For example, the SMPP protocol defines the TLV (Tag, Length, Value) mechanism to allow adding arbitrary parameters 10403 to it's PDU's, thus extending it's functionality.</para> 10404 <para>To achieve this, a special group and parameters were added to abstract the meta-data into something that could be used disregarding 10405 the SMSC type.</para> 10406 <para>Currently only the SMPP module is implemented, but the format chosen allows for other modules to be added in the future.</para> 10407 </sect1> 10408 <sect1> 10409 <title>SMPP Implementation</title> 10410 <para>A special group type <literal>smpp-tlv</literal> is needed for each TLV. Each group defines the address, data type and length of the TLV</para> 10411 <para>Example configuration:</para> 10412<programlisting> 10413group = smpp-tlv 10414name = my_tlv_name 10415tag = 0x1601 10416type = octetstring 10417length = 20 10418smsc-id = a;b;c 10419</programlisting> 10420 10421<informaltable frame="none"> 10422 <tgroup cols="3"> 10423 <thead><row> 10424 <entry>Variable</entry> 10425 <entry>Data Type</entry> 10426 <entry>Description</entry> 10427 </row></thead><tbody> 10428 10429 <row><entry><literal>tag</literal></entry> 10430 <entry><literal>hex</literal></entry> 10431 <entry valign="bottom"> 10432 32-Bit HEX address for the given TLV. Must match SMPP specifications for the TLV (or be agreed with the SMSC operator). 10433 </entry></row> 10434 10435 <row><entry><literal>type</literal></entry> 10436 <entry><literal>string</literal></entry> 10437 <entry valign="bottom"> 10438 Accepted data type. Accepted values are <literal>integer</literal>, <literal>nulterminated</literal> and <literal>octetstring</literal>. 10439 Must match SMPP specifications for the TLV (or be agreed with the SMSC operator). 10440 </entry></row> 10441 10442 <row><entry><literal>length</literal></entry> 10443 <entry><literal>integer</literal></entry> 10444 <entry valign="bottom"> 10445 Maximum data length expected in bytes. Must match SMPP specifications for the TLV (or be agreed with the SMSC operator). 10446 </entry></row> 10447 10448 <row><entry><literal>smsc-id</literal></entry> 10449 <entry><literal>string</literal></entry> 10450 <entry valign="bottom"> 10451 An optional smsc-id for which this TLV is valid. If smsc-id is not given 10452 then this TLV is valid for all SMSCs. 10453 To define list of smsc-id, just use ; as split char. 10454 </entry></row> 10455 10456 </tbody> 10457 </tgroup> 10458</informaltable> 10459 <sect2> 10460 <title>MO Messages</title> 10461 <para>Meta Data coming from MO messages comes urlencoded into the <literal>%D</literal> parameter. Only TLV parameters defined on the configuration file are honored.</para> 10462 <sect3> 10463 <title>Example</title> 10464 <para><literal>http://localhost/myscript?...&meta-data=%D&...</literal></para> 10465 </sect3> 10466 </sect2> 10467 <sect2> 10468 <title>MT Messages</title> 10469 <para>To send into an MT messages the <literal>meta-data</literal> parameter should be used.</para> 10470 10471 <para>The format used to pass the data has 2 parts: The <literal>?smsc-type?</literal> (surrounded by question marks), 10472 which specify the kind of smsc receiving the data (at the moment only <literal>smpp</literal> is implemented) and then a set of key/value 10473 pairs with the data to be transmitted. Extra smsc-types can be added surrounded by question marks and followed by the key/value pairs.</para> 10474 10475 <para>In other words, the data should be coded using the following format, where URLENCODE() implies that the data between parentheses should 10476 be urlencoded:</para> 10477 10478 <para><literal>?URLENCODE(<smsc-type1>)?URLENCODE(key1)=URLENCODE(value1)&URLENCODE(key2)=URLENCODE(value2)&...</literal></para> 10479 <para><literal>?URLENCODE(<smsc-type2>)?URLENCODE(key1)=URLENCODE(value1)&...</literal></para> 10480 10481 <para>Only the parameters defined on the configuration file are honored.</para> 10482 10483 <para>Important: For the sendsms interface, you must URLENCODE the resulting string again to pass it as a single parameter on the URL.</para> 10484 10485 <sect3> 10486 <title>Examples</title> 10487 <para>If we want to send the parameter "my-data" with value "Hello World" to an SMSC over SMPP, we'd use:</para> 10488 <para>sendsms get-url:</para> 10489 <para><literal>http://localhost:13013/cgi-bin/sendsms?...&meta-data=%3Fsmpp%3Fmy-data%3DHello%2BWorld</literal></para> 10490 <para>sendsms post:</para> 10491 <para>Send <literal>?smpp?my-data=Hello+World</literal> on the <literal>X-Kannel-Meta-Data</literal> header</para> 10492 <para>XML:</para> 10493 <para><literal><meta-data>?smpp?my-data=Hello+World</meta-data></literal></para> 10494 </sect3> 10495 </sect2> 10496 </sect1> 10497</appendix> 10498 10499<appendix> 10500<title>Log files</title> 10501 10502 <para>This appendix describes the log file format.</para> 10503 10504<sect1> 10505<title>Bearerbox Access Log</title> 10506 10507 <screen><computeroutput> 10508 2001-01-01 12:00:00 Sent SMS [SMSC:smsc] [SVC:sms] [ACT:account] [BINFO:binfo] [FID:1234567890] [META:meta] 10509 [from:12345] [to:67890] [flags:0:1:0:0:0] [msg:11:Hello World] [udh:0] 10510 </computeroutput></screen> 10511 10512 <informaltable frame="none"> 10513 <tgroup cols="3"> 10514 <thead> 10515 <row> 10516 <entry>Variable</entry> 10517 <entry>Value</entry> 10518 <entry>Description</entry> 10519 </row> 10520 </thead> 10521 <tbody> 10522 <row><entry>Date</entry> 10523 <entry>2001-01-01 12:00:00</entry> 10524 <entry valign="bottom"> 10525 Date 10526 </entry></row> 10527 10528 <row><entry>Result</entry> 10529 <entry>Sent SMS</entry> 10530 <entry valign="bottom"> 10531 Result: Send, failed, DLR (deliver report), Received, etc. 10532 </entry></row> 10533 10534 <row><entry>SMSC</entry> 10535 <entry>smsc</entry> 10536 <entry valign="bottom"> 10537 Smsc id (<literal>smsc-id</literal>) defined in configuration 10538 group <literal>smsc</literal> 10539 </entry></row> 10540 10541 <row><entry>SVC</entry> 10542 <entry>sms</entry> 10543 <entry valign="bottom"> 10544 Service name (<literal>name</literal>) defined in configuration 10545 group <literal>sendsms-user</literal> 10546 </entry></row> 10547 10548 <row><entry>ACT</entry> 10549 <entry>account</entry> 10550 <entry valign="bottom"> 10551 Account name (<literal>name</literal>) defined in configuration 10552 group <literal>sendsms-user</literal> 10553 </entry></row> 10554 10555 <row><entry>BINF</entry> 10556 <entry>binfo</entry> 10557 <entry valign="bottom"> 10558 Billing information used to send this message. 10559 </entry></row> 10560 10561 <row><entry>Foreign ID</entry> 10562 <entry>1234567890</entry> 10563 <entry valign="bottom"> 10564 Foreign (SMSC-provided) Message ID (only available on MT messages) 10565 </entry></row> 10566 10567 <row><entry>META</entry> 10568 <entry>meta-data</entry> 10569 <entry valign="bottom"> 10570 Meta-data used to send this message. 10571 See <xref linkend="meta-data"/> for an explanation about meta-data. 10572 </entry></row> 10573 10574 <row><entry>from</entry> 10575 <entry>12345</entry> 10576 <entry valign="bottom"> 10577 Sender 10578 </entry></row> 10579 10580 <row><entry>to</entry> 10581 <entry>67890</entry> 10582 <entry valign="bottom"> 10583 Recipient 10584 </entry></row> 10585 10586 <row><entry>Flags</entry> 10587 <entry>0:1:0:0:0</entry> 10588 <entry valign="bottom"> 10589 Flags: MClass, Coding, MWI, Compress, DLRMask 10590 </entry></row> 10591 10592 <row><entry>Message Text</entry> 10593 <entry>11:Hello World</entry> 10594 <entry valign="bottom"> 10595 Size of message and message dump (in text or hex if it's binary) 10596 </entry></row> 10597 10598 <row><entry>User Data Header</entry> 10599 <entry>0:</entry> 10600 <entry valign="bottom"> 10601 Size of UDH and UDH Hex dump 10602 </entry></row> 10603 10604 </tbody> 10605 </tgroup> 10606 </informaltable> 10607 10608</sect1> 10609<sect1> 10610<title>Log rotation</title> 10611 10612 <para>If Kannel is configured so that the bearerbox, wapbox and/or smsbox 10613 log to file each of these log files will continue to grow unless administered 10614 in some way (this is specially true if access logs are created and/or the 10615 log level is set to debug). </para> 10616 10617 <para> 10618 A typical way of administering log files is to 'rotate' the logs on a regular 10619 basis using a tool such as logrotate. A sample logrotate script (to be added 10620 to /etc/logrotate.d) is shown below. In this example the Kannel log files found 10621 in /var/log/kannel are rotated and compressed daily over 365 days. See the 10622 documentation for logrotate for more details. Of particular note however is the 10623 postrotate command, this killall -HUP issues a HUP command to each Kannel 10624 box running. The HUP signal has the effect of reopening the log file, without this 10625 command Kannel will continue to write to the rotated log file. 10626 </para> 10627 10628 <screen><userinput> 10629 /var/log/kannel/*.log { 10630 daily 10631 missingok 10632 rotate 365 10633 compress 10634 delaycompress 10635 notifempty 10636 create 640 kannel adm 10637 sharedscripts 10638 postrotate 10639 killall -HUP bearerbox smsbox wapbox || true > /dev/null 2> /dev/null 10640 endscript 10641 } 10642 </userinput></screen> 10643</sect1> 10644 10645</appendix> 10646 10647 10648<glossary> 10649 <title>Glossary</title> 10650 10651 <glossdiv><title>M</title> 10652 <glossentry id="MO"><glossterm>MO</glossterm><glossdef> 10653 <para>Mobile Originated - a SMS from mobile to application</para> 10654 </glossdef></glossentry> 10655 <glossentry id="MT"><glossterm>MT</glossterm><glossdef> 10656 <para>Mobile Terminated - a SMS from application to mobile</para> 10657 </glossdef></glossentry> 10658 <glossentry id="MWI"><glossterm>MWI</glossterm><glossdef> 10659 <para>Message Waiting Indicator (See <xref linkend="Biblio-3GPP-23038"/>)</para> 10660 </glossdef></glossentry> 10661 <glossentry id="MCLASS"><glossterm>MClass</glossterm><glossdef> 10662 <para>Message Class (See <xref linkend="Biblio-3GPP-23038"/>)</para> 10663 </glossdef></glossentry> 10664 <glossentry id="CODING"><glossterm>Coding</glossterm><glossdef> 10665 <para>Message Coding (See <xref linkend="Biblio-3GPP-23038"/>)</para> 10666 </glossdef></glossentry> 10667 </glossdiv> 10668 10669</glossary> 10670 10671<bibliography> 10672 <title>Bibliography</title> 10673 10674 <biblioentry id="Biblio-RFC-2616"> 10675 <title>RFC 2616 - Hypertext Transfer Protocol -- HTTP/1.1</title> 10676 <issn><ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616.html">http://www.w3.org/Protocols/rfc2616/rfc2616.html</ulink></issn> 10677 <subtitle>Request for Comments: 2616</subtitle> 10678 <orgname>The Internet Society</orgname> 10679 <copyright><year>1999</year></copyright> 10680 </biblioentry> 10681 10682 <biblioentry id="Biblio-3GPP-23038"> 10683 <title>3GPP 23.038</title> 10684 <issn><ulink url="http://www.3gpp.org/ftp/Specs/latest/Rel-5/23_series/23038-500.zip">http://www.3gpp.org/ftp/Specs/latest/Rel-5/23_series/23038-500.zip</ulink></issn> 10685 <subtitle>...</subtitle> 10686 <orgname>3GPP</orgname> 10687 <copyright><year>?</year></copyright> 10688 </biblioentry> 10689 10690 <biblioentry id="Biblio-3GPP-23040"> 10691 <title>3GPP 23.040</title> 10692 <issn><ulink url="http://www.3gpp.org/ftp/Specs/latest/Rel-5/23_series/23040-530.zip">http://www.3gpp.org/ftp/Specs/latest/Rel-5/23_series/23040-530.zip</ulink></issn> 10693 <subtitle>...</subtitle> 10694 <orgname>3GPP</orgname> 10695 <copyright><year>?</year></copyright> 10696 </biblioentry> 10697 10698 <biblioentry id="Biblio-regexp"> 10699 <title>regex(7), GNU regex manual</title> 10700 <!-- <issn><ulink url="http://techpubs.sgi.com/library/tpl/cgi-bin/getdoc.cgi?coll=linux&db=man&fname=/usr/share/catman/man7/regex.7.html&srch=regex">http://techpubs.sgi.com/library/tpl/cgi-bin/getdoc.cgi?coll=linux&db=man&fname=/usr/share/catman/man7/regex.7.html&srch=regex</ulink></issn>--> 10701 <subtitle></subtitle> 10702 <orgname>GNU</orgname> 10703 <copyright><year>1998</year></copyright> 10704 </biblioentry> 10705 10706</bibliography> 10707 10708</book> 10709 10710