userguide.xml

mms client

   <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>

 </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 queueing 
	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="bottom">
        HTML version of status
   </entry></row>
   <row><entry><literal>status.xml</literal></entry>
   <entry valign="bottom">
        XML version of status
   </entry></row>
   <row><entry><literal>status.wml</literal></entry>
   <entry valign="bottom">
        WML version of status
   </entry></row>

   <row><entry><literal>store-status or store-status.txt</literal></entry>
   <entry valign="bottom">
        Get the current content of the store queue of the gateway 
		  in a text version. 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>store-status.html</literal></entry>
   <entry valign="bottom">
        HTML version of store-status
   </entry></row>
   <row><entry><literal>store-status.xml</literal></entry>
   <entry valign="bottom">
        XML version of store-status
   </entry></row>

   <row><entry><literal>suspend</literal></entry>
   <entry valign="bottom">
        Set Kannel state as 'suspended' (see above). Password
        required.
   </entry></row>

   <row><entry><literal>isolate</literal></entry>
   <entry valign="bottom">
        Set Kannel state as 'isolated' (see above). Password required.
   </entry></row>

   <row><entry><literal>resume</literal></entry>
   <entry valign="bottom">
        Set Kannel state as 'running' if it is suspended or isolated.
        Password required.
   </entry></row>

   <row><entry><literal>shutdown</literal></entry>
   <entry valign="bottom">
        Bring down the gateway, by setting state to 'shutdown'. After
        a shutdown is initiated, there is no other chance to resume
        normal operation. However, 'status' command still works.
        Password required. If shutdown is sent for a second time, the
        gateway is forced down, even if it has still messages in
        queue.
   </entry></row>

	<row><entry><literal>flush-dlr</literal></entry>
   <entry valign="bottom">
        If Kannel state is 'suspended' this will flush all queued DLR
		  messages in the current storage space. Password required.
   </entry></row>

	<row><entry><literal>start-smsc</literal></entry>
   <entry valign="bottom">
        Re-start a single SMSC link. Password required. Additionally
		  the <literal>smsc</literal> parameter must be given to identify
 		  which <literal>smsc-id</literal> should be re-started.
   </entry></row>

  	<row><entry><literal>stop-smsc</literal></entry>
   <entry valign="bottom">
        Shutdown a single SMSC link. Password required. Additionally
		  the <literal>smsc</literal> parameter must be given (see above).
   </entry></row>

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

</sect2>
  
</sect1>
</chapter>






<chapter id="wap-gateway">
<title>Setting up a WAP gateway</title>

    <para>This chapter tells you how to set Kannel up as a WAP
    gateway.</para>

<sect1>
<title>WAP gateway configuration</title>

  <para>To set up a WAP Kannel, you have to edit the 'core' group in the
  configuration file, and define the 'wapbox' group.</para>

  <para>You must set following variables for the 'core' group:  
    <literal>wapbox-port</literal> and
    <literal>wdp-interface-name</literal>. See previous chapter about
    details of these variables.</para>

  <para>With standard distribution, a sample configuration file
  <literal>wapkannel.conf</literal> is supplied. You may want to take
  a look at that when setting up a WAP Kannel.</para>

<sect2>
<title>Wapbox configuration</title>

  <para>If you have set <literal>wapbox-port</literal> variable in the
  'core' configuration group, you <emphasis>MUST</emphasis> supply
  a 'wapbox' group.</para>

  <para>The simplest working 'wapbox' group looks like this:
<programlisting>
group = wapbox
bearerbox-host = localhost
</programlisting>

   There is, however, multiple optional variables for the 'wapbox'
   group.</para>

 <table frame="none">
  <title>Wapbox Group Variables</title>
  <tgroup cols="3">
  <thead>
   <row>
     <entry>Variable</entry>
     <entry>Value</entry>
     <entry>Description</entry>
   </row>
  </thead>
  <tbody>
   <row><entry><literal>group (m)</literal></entry>
     <entry><literal>wapbox</literal></entry>
     <entry valign="bottom">
       This is mandatory variable
     </entry></row>

   <row><entry><literal>bearerbox-host (m)</literal></entry>
     <entry><literal>hostname</literal></entry>
     <entry valign="bottom">
        The machine in which the bearerbox is. 
     </entry></row>

    <row><entry><literal>timer-freq</literal></entry>
     <entry>value-in-seconds</entry>
     <entry valign="bottom">
         The frequency of how often timers are checked out. Default is 1 
     </entry></row>

    <row><entry><literal>map-url</literal></entry>
     <entry>URL-pair</entry>
     <entry valign="bottom">
        The pair is separated with space.
        Adds a single mapping for the left side URL to the given destination.
        If you append an asterisk `*' to the left side URL, its prefix
        Is matched against the incoming URL. Whenever the prefix matches,
        the URL will be replaced completely by the right side. In addition, if 	  if you append an asterisk to the right side URL, the part
        of the incoming URL coming after the prefix, will be appended
        to the right side URL. Thus, for a line:
                map-url = "http://source/* http://destination/*"
        and an incoming URL of "http://source/some/path", the result
        will be "http://destination/some/path"
     </entry></row>

    <row><entry><literal>map-url-max</literal></entry>
     <entry>number</entry>
     <entry valign="bottom">
        If you need more than one mapping, set this to the highest number
        mapping you need. The default gives you 10 mappings, numbered
        from 0 to 9. Default: 9
     </entry></row>

    <row><entry><literal>map-url-0</literal></entry>
     <entry>URL-pair</entry>
     <entry valign="bottom">
        Adds a mapping for the left side URL to the given destination URL.
        Repeat these lines, with 0 replaced by a number up to map-url-max,
        if you need several mappings.
     </entry></row>

    <row><entry><literal>device-home</literal></entry>
     <entry>URL</entry>
     <entry valign="bottom">
        Adds a mapping for the URL DEVICE:home (as sent by Phone.com browsers)
        to the given destination URL. There is no default mapping.
        NOTE: the mapping is added with both asterisks, as described above
        for the "map-url" setting. Thus, the above example line is
        equivalent to writing
                map-url = "DEVICE:home* http://some.where/*"

     </entry></row>

    <row><entry><literal>log-file</literal></entry>
     <entry>filename</entry>
     <entry morerows="1" valign="bottom">
       As with bearerbox 'core' group. 
     </entry></row>

    <row><entry><literal>log-level</literal></entry>
     <entry>number 0..5</entry></row>

    <row><entry><literal>syslog-level</literal></entry>
     <entry>number</entry>
     <entry valign="bottom">
	 Messages of this log level or higher will also be
	 sent to syslog, the UNIX system log daemon.  The wapbox
	 logs under the 'daemon' category.
	 The default is not to use syslog, and you can set that
	 explicitly by setting <literal>syslog-level</literal>
	 to 'none'.
     </entry></row>

    <row><entry><literal>force-sar</literal></entry>
     <entry>bool</entry>
     <entry valign="bottom">
	 If set wapbox will force to process WTP-SAR connections
	 even while Kannel does not support this feature now. Some
	 real phones seem to break connection if fallback to non
	 SAR communication is being tried by the gateway.
     </entry></row>

	 <row><entry><literal>smart-errorsr</literal></entry>
     <entry>bool</entry>
     <entry valign="bottom">
	 If set wapbox will return a valid WML deck describing the 
	 eror that occured while processing an WSP request. This may
	 be used to have a smarter gateway and let the user know what
	 happend actually.
	 </entry></row>

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


<programlisting>
</programlisting>
</sect2>
  
</sect1>

<sect1>
<title>Running WAP gateway</title>

 <para>WAP Gateway is ran as explained in previous chapter.</para>

</sect1>


<sect1>
<title>Checking whether the WAP gateway is alive</title>

    <para>You can check whether the WAP gateway (both the
    bearerbox and the wapbox) is alive by f