userguide.xml

The Kannel Open Source WAP and SMS gateway works as both an SMS gateway, for implementing keyword b

    </row>
	 <row><entry><literal>ssl-trusted-ca-file</literal></entry>
     <entry>filename</entry>
     <entry valign="bottom">
     This file contains the certificates Kannel is willing to trust when
     working as a HTTPS client. If this option is not set, certificates
     are not validated and those the identity of the server is not proven.
	  </entry>
    </row>

    <row><entry><literal>dlr-storage</literal></entry>
     <entry>type</entry>
     <entry valign="bottom">
        Defines the way DLRs are stored. If you have build-in external 
		  DLR storage support, i.e. using MySQL you may define here the
		  alternative storage type like 'mysql'. Supported types are:
		  internal, mysql, oracle. By default this is set to 'internal'.
     </entry></row>

     <row><entry><literal>maximum-queue-length</literal></entry>
	  <entry>number of messages</entry>
     <entry valign="bottom">
   	 (deprecated, see <literal>sms-incoming-queue-limit</literal>).
     </entry></row>

     <row><entry><literal>sms-incoming-queue-limit</literal></entry>
     <entry>number of messages</entry>
     <entry valign="bottom">
        Set maximum size of incoming message queue. After number of messages
        has hit this value, Kannel began to discard them.
        Value 0 means giving strict priority to outgoing messages. -1,
        default, means that the queue of infinite length is accepted. (This
        works with any normal input, use this variable only when Kannel message
        queues grow very long).
     </entry></row>

     <row><entry><literal>white-list-regex</literal></entry>
        <entry>POSIX regular expression</entry>
        <entry valign="bottom">
        A regular expression defining the set of accepted senders. See section on regular 
        expressions for details.
        </entry>   
     </row>
     <row><entry><literal>black-list-regex</literal></entry>
        <entry>POSIX regular expression</entry>
        <entry valign="bottom">
        A regular expression defining the set of rejected senders. See section on regular 
        expressions for details.
        </entry>   
     </row>

     <row><entry><literal>smsbox-max-pending</literal></entry>
        <entry>number of messages</entry>
        <entry valign="bottom">
        Maximum number of pending messages on the line to smsbox compatible boxes.
        </entry>   
     </row>
  
  </tbody>
  </tgroup>
 </table>

  <para>A sample more complex 'core' group could be something like
  this:

<programlisting>
group = core
admin-port = 13000
admin-password = f00bar
status-password = sTat
admin-deny-ip = "*.*.*.*"
admin-allow-ip = "127.0.0.1;200.100.0.*"
smsbox-port = 13003
wapbox-port = 13004
box-deny-ip = "*.*.*.*"
box-allow-ip = "127.0.0.1;200.100.0.*"
wdp-interface-name = "*"
log-file = "kannel.log"
log-level = 1
access-log = "kannel.access"
unified-prefix = "+358,00358,0;+,00"
white-list = "http://localhost/whitelist.txt"
</programlisting>
  
    </para>

</sect2>

</sect1>

<sect1>
<title>Running Kannel</title>

	<para>To start the gateway, you need to start each box you need.
	You always need the bearer box, and depending on whether you want
	WAP and SMS gateways you need to start the WAP and SMS boxes. If
	you want, you can run several of them, but we'll explain the
	simple case of only running one each.</para>


<sect2>
<title>Starting the gateway</title>

  <para>After you have compiled Kannel and edited configuration file
  for your taste, you can either run Kannel from command line or use
  supplied <literal>start-stop-daemon</literal> and
  <literal>run_kannel_box</literal> programs to use it as a daemon
  service (more documentation about that later).</para>

  <para>If you cannot or do not know how to set up daemon systems or
  just want to test Kannel, you probably want to start it from
  command line. This means that you probably want to have one terminal
  window for each box you want to start (xterm or screen will do
  fine). To start the bearerbox, give the following command:

	<screen><userinput>
	./bearerbox -v 1 [config-file]
	</userinput></screen>

  The <option>-v 1</option> sets the logging level to
  <literal>INFO</literal>. This way, you won't see a large amount of
  debugging output (the default is <literal>DEBUG</literal>). Full
  explanation of Kannel command line arguments is below.</para>

  <para><emphasis>[config-file]</emphasis> is the name of the
  configuration file you are using with Kannel. The basic distribution
  packet comes with two sample configuration files,
  <literal>smskannel.conf</literal> and
  <literal>wapkannel.conf</literal> (in <literal>gw</literal>
  subdirectory), of which the first one is for
  testing out SMS Kannel and the second one for setting up a WAP
  Kannel. Feel free to edit those configuration files to set up your
  own specialized system.</para>

  <para>After the bearer box, you can start the WAP box:

	<screen><userinput>
	./wapbox -v 1 [config-file]
	</userinput></screen>

  or the SMS box:

	<screen><userinput>
	./smsbox -v 1 [config-file]
	</userinput></screen>

  or both, of course. The order does not matter, except that you need
  to start the bearer box before the other boxes. Without the bearer
  box, the other boxes won't even start.</para>

</sect2>

<sect2 id="arguments">
<title id="arguments.title">Command line options</title>

 <para>Bearerbox, smsbox and wapbox each accept certain command line options
   and arguments when they are launched. These arguments are:</para>

 <table frame="none">
  <title>Kannel Command Line Options</title>
  <tgroup cols="2">
  <tbody>
   <row><entry><literal>-v &lt;level&gt;</literal></entry>
        <entry morerows="1" valign="bottom">
             Set verbosity level for stdout (screen) logging. Default is 0,
             which means 'debug'. 1 is 'info, 2 'warning', 3
             'error' and 4 'panic'
        </entry></row>
   <row><entry><literal>--verbosity &lt;level&gt;</literal></entry></row>

   <row><entry><literal>-D &lt;places&gt;</literal></entry>
        <entry morerows="1" valign="bottom">
             Set debug-places for 'debug' level output.
        </entry></row>
   <row><entry><literal>--debug &lt;places&gt;</literal></entry></row>

   <row><entry><literal>-F &lt;file-name&gt;</literal></entry>
        <entry morerows="1" valign="bottom">
              Log to file named file-name, too. Does not overrun or
              affect any log-file defined in configuration file.
        </entry></row>
   <row><entry><literal>--logfile &lt;file-name&gt;</literal></entry></row>

   <row><entry><literal>-V &lt;level&gt;</literal></entry>
        <entry morerows="1" valign="bottom">
            Set verbosity level for that extra log-file (default 0,
            which means 'debug'). Does not affect verbosity level of
            the log-file defined in configuration file, not verbosity
            level of the <literal>stdout</literal> output.
        </entry></row>
   <row><entry><literal>--fileverbosity &lt;level&gt;</literal></entry></row>

   <row><entry><literal>-S</literal></entry>
        <entry morerows="1" valign="bottom">
             Start the system initially at SUSPENDED state (see below,
              bearerbox only)
        </entry></row>
   <row><entry><literal>--suspended</literal></entry></row>

   <row><entry><literal>-I</literal></entry>
        <entry morerows="1" valign="bottom">
             Start the system initially at ISOLATED state (see below,
              bearerbox only)
        </entry></row>
   <row><entry><literal>--isolated</literal></entry></row>

   <row><entry><literal>-H</literal></entry>
        <entry morerows="1" valign="bottom">
             Only try to open HTTP sendsms interface; if it
             fails, only warn about that, do not exit. (smsbox only)
        </entry></row>
   <row><entry><literal>--tryhttp</literal></entry></row>

   <row><entry><literal>-g</literal></entry>
        <entry morerows="1" valign="bottom">
             Dump all known config groups and config keys to stdout
             and exit.
        </entry></row>
   <row><entry><literal>--generate</literal></entry></row>

   <row><entry><literal>-u &lt;username&gt;</literal></entry>
        <entry morerows="1" valign="bottom">
             Change process user-id to the given.
        </entry></row>
   <row><entry><literal>--user &lt;username&gt;</literal></entry></row>

   <row><entry><literal>-p &lt;filename&gt;</literal></entry>
        <entry morerows="1" valign="bottom">
             Write process PID to the given file.
        </entry></row>
   <row><entry><literal>--pid-file &lt;filename&gt;</literal></entry></row>

   <row><entry><literal>-d</literal></entry>
        <entry morerows="1" valign="bottom">
             Start process as daemon (detached from a current shell session).
             Note: Process will change CWD (Current working directory) to <literal>/</literal>,
                   therefore you should ensure that all paths to binary/config/config-includes are
                   absolute instead of relative.
        </entry></row>
   <row><entry><literal>--daemonize</literal></entry></row>

   <row><entry><literal>-P</literal></entry>
        <entry morerows="1" valign="bottom">
             Start watcher process. This process watch a child process and if child process
             crashed will restart them automatically.
        </entry></row>
   <row><entry><literal>--parachute</literal></entry></row>

   <row><entry><literal>-X &lt;scriptname&gt;</literal></entry>
        <entry morerows="1" valign="bottom">
             Execute a given shell script or binary when child process crash detected. This option
             is usable only with <literal>--parachute/-P</literal>.
             Script will be executed with 2 arguments:
                 scriptname 'processname' 'respawn-count'.
        </entry></row>
   <row><entry><literal>--panic-script &lt;scriptname&gt;</literal></entry></row>

 </tbody>
 </tgroup>
 </table>

</sect2>

<sect2>
<title>Kannel statuses</title>

    <para>In Kannel, there are four states for the program (which
    currently directly only apply to bearerbox):</para>

    <orderedlist numeration="loweralpha">
     <listitem><para>
       Running. The gateway accepts, proceeds and relies 
       messages normally. This is the default state for the bearerbox.
     </para></listitem>
     <listitem><para>
 Suspended. The gateway does not accept any new messages from SMS
   centers nor from UDP ports. Neither does it accept new sms and wapbox
   connections nor sends any messages already in the system
   onward.

     </para></listitem>
     <listitem><para>
 Isolated. In this state, the gateway does not accept any messages
   from external message providers, which means SMS Centers and UDP
   ports. It still processes any messages in the system and can
   accept new messages from sendsms interface in smsbox.
     </para></listitem>

     <listitem><para>
   Full. Gateway does not accept any messages from SMS centers, because 
   <literal>maximum-queue-length</literal> is achieved.
     </para></listitem>

     <listitem><para>
   Shutdown. When the gateway is brought down, it does not accept any
   new messages from SMS centers and UDP ports, but processes all
   systems already in the system. As soon as any queues are emptied,
   the system exits

   </para></listitem>
    </orderedlist>
 
  <para>
The state can be changed via HTTP administration interface (see below),
and shutdown can also be initiated via TERM or INT signal from
terminal. In addition, the bearerbox can be started already in
suspended or isolated state with -S or -I command line option, see
above.
</para>

</sect2>

<sect2>
<title>HTTP administration</title>

<para>Kannel can be controlled via an HTTP administration interface. All
commands are done as normal HTTP queries, so they can be easily done
from command line like this:

	<screen><userinput>
	lynx -dump "http://localhost:12345/shutdown?password=bar"
	</userinput></screen>

...in which the '12345' is the configured admin-port in Kannel
configuration file (see above). For most commands, admin-password is required as a
argument as shown above. In addition, HTTP administration can
be denied from certain IP addresses, as explained in configuration
chapter.</para>

<para>Note that you can use these commands with WAP terminal, too, but
if you use it through the same Kannel, replies to various suspend
commands never arrive nor can you restart it via WAP anymore.</para>

 <table frame="none">
  <title>Kannel HTTP Administration Commands</title>
  <tgroup cols="2">
  <tbody>
   <row><entry><literal>status or status.txt</literal></entry>
   <entry valign="bottom">
        Get the current status of the gateway in a text version. Tells the current 
	state (see above) and total number of messages relied and queuing 
	in the system right now. Also lists the total number of smsbox
        and wapbox connections. No password required, unless
        <literal>status-password</literal> set, in which case either
        that or main admin password must be supplied.
   </entry></row>
   <row><entry><literal>status.html</literal></entry>
   <entry valign="bott