userguide.xml

mms client

     </entry></row>
    <row><entry><literal>admin-allow-ip</literal></entry></row>


    <row><entry><literal>smsbox-port (c)</literal></entry>
     <entry>port-number</entry>
     <entry valign="bottom">
        This is the port number to which the smsboxes, if any, connect.
        As with admin-port, this can be anything you want. Must be set
        if you want to handle any SMS traffic.
     </entry></row>
	  
	 <row><entry><literal>smsbox-port-ssl (o)</literal></entry>
     <entry>bool</entry>
     <entry valign="bottom">
	     If set to true, the smsbox connection module will be SSL-enabled.
		  Your smsboxes will have to connect using SSL to the bearerbox
		  then. This is used to secure communication between bearerbox
		  and smsboxes in case they are in seperate networks operated and
		  the TCP communication is not secured on a lower network layer.
		  Defaults to "no".
     </entry></row>

    <row><entry><literal>wapbox-port (c)</literal></entry>
     <entry>port-number</entry>
     <entry valign="bottom">
        Like smsbox-port, but for wapbox-connections. If not set,
        Kannel cannot handle WAP traffic
     </entry></row>

	 <row><entry><literal>wapbox-port-ssl (o)</literal></entry>
     <entry>bool</entry>
     <entry valign="bottom">
	     If set to true, the wapbox connection module will be SSL-enabled.
		  Your wapboxes will have to connect using SSL to the bearerbox
		  then. This is used to secure communication between bearerbox
		  and wapboxes in case they are in seperate networks operated and
		  the TCP communication is not secured on a lower network layer.
		  Defaults to "no".
     </entry></row>

    <row><entry><literal>box-deny-ip</literal></entry>
     <entry morerows="1">IP-list</entry>
     <entry morerows="1" valign="bottom">
        These lists can be used to prevent box connections from given IP 
        addresses. Each list can have several addresses, 
        separated with semicolons (';'). An asterisk ('*') can be used
        as a wildcard in place of any ONE number, so *.*.*.*
        matches any IP.
     </entry></row>
    <row><entry><literal>box-allow-ip</literal></entry></row>

    <row><entry><literal>udp-deny-ip</literal></entry>
     <entry morerows="1">IP-list</entry>
     <entry morerows="1" valign="bottom">
        These lists can be used to prevent UDP packets from given IP 
        addresses, thus preventing unwanted use of the WAP gateway.
	Used the same way as <literal>box-deny-ip</literal> and
	<literal>box-allow-ip</literal>.
     </entry></row>
    <row><entry><literal>udp-allow-ip</literal></entry></row>

    <row><entry><literal>wdp-interface-name (c)</literal></entry>
     <entry>IP or '*'</entry>
     <entry valign="bottom">
        If this is set, Kannel listens to WAP UDP packets incoming to
        ports 9200-9208, bound to given IP. If no specific IP is
        needed, use just an asterisk ('*'). If UDP messages are
        listened to, wapbox-port variable MUST be set.
     </entry></row>

    <row><entry><literal>log-file</literal></entry>
     <entry>filename</entry>
     <entry valign="bottom">
        A file in which to write a log. This in addition to <literal>stdout</literal>
        and any log file defined in command line. Log-file in 'core'
        group is only used by the bearerbox.
     </entry></row>

    <row><entry><literal>log-level</literal></entry>
     <entry>number 0..5</entry>
     <entry valign="bottom">
        Minimum level of logfile events logged. 0 is for 'debug', 1
        'info', 2 'warning, 3 'error' and 4 'panic' (see Command Line
        Options)
     </entry></row>

    <row><entry><literal>access-log</literal></entry>
     <entry>filename</entry>
     <entry valign="bottom">
        A file in which information about received/sent SMS messages 
        is stored. Access-log in 'core' group is only used by the
        bearerbox.

     </entry></row>

    <row><entry><literal>unified-prefix</literal></entry>
     <entry>prefix-list</entry>
     <entry valign="bottom">
        String to unify received phone numbers, for SMSC routing and
        to ensure that SMS centers can handle them properly. 
        This is applied to 'sender' number when receiving SMS
        messages from SMS Center and for 'receiver' number when
        receiving messages from SMSbox (either sendsms message or
         reply to original message). Format is that first comes the
        unified prefix, then all prefixes which are replaced by the
        unified prefix, separated with comma (','). For example,
        for Finland an unified-prefix "+358,00358,0;+,00" should do the trick. 
        If there are several unified prefixes, separate their rules with
        semicolon (';'), like "+35850,050;+35840,040". <emphasis>Note
        that prefix routing is next to useless now that there are
        SMSC ID entries. To remove prefixes, use like 
	"-,+35850,050;-,+35840,040".
	</emphasis>

     </entry></row>

    <row><entry><literal>white-list</literal></entry>
     <entry>URL</entry>
     <entry valign="bottom">
        Load a list of accepted senders of SMS messages. If a sender
        of an SMS message is not in this list, any message received
        from the SMS Center is discarded. See notes of phone number
        format from numhash.h header file. NOTE: the system has only
        a precision of last 9 or 18 digits of phone numbers, so
        beware!
     </entry></row>

    <row><entry><literal>black-list</literal></entry>
     <entry>URL</entry>
     <entry valign="bottom">
        As white-list, but SMS messages to these numbers are
        automatically discarded
     </entry></row>

    <row><entry><literal>store-file</literal></entry>
     <entry>filename</entry>
     <entry valign="bottom">
        A file in which any received SMS messages are stored until
        they are successfully handled. By using this variable, no SMS
        messages are lost in Kannel, but theoretically some messages
        can duplicate when system is taken down violently. 
     </entry></row>

    <row><entry><literal>http-proxy-host</literal></entry>
     <entry>hostname</entry>
     <entry morerows="1" valign="bottom">
        Enable the use of an HTTP proxy for all HTTP requests.
     </entry></row>
    <row><entry><literal>http-proxy-port</literal></entry>
     <entry>port-number</entry></row>

    <row><entry><literal>http-proxy-exceptions</literal></entry>
     <entry>URL-list</entry>
     <entry valign="bottom">
         A list of excluded hosts from being used via a
         proxy. Separate each entry with space.
     </entry></row>
    
    <row><entry><literal>http-proxy-username</literal></entry>
     <entry>username</entry>
     <entry valign="bottom">
         Username for authenticating proxy use, for proxies that
	 require this.
     </entry></row>
    
    <row><entry><literal>http-proxy-password</literal></entry>
     <entry>URL-list</entry>
     <entry valign="bottom">
         Password for authenticating proxy use, for proxies that
	 require this.
     </entry></row>
    
    <row><entry><literal>ssl-client-certkey-file (c)</literal></entry>
     <entry>filename</entry>
     <entry valign="bottom">
      A PEM encoded SSL certificate and private key file to be used
      with SSL client connections. This certificate is used for
  	   the HTTPS client side only, i.e. for SMS service requests to 
		SSL-enabed HTTP servers. 
     </entry>
    </row>
  
	 <row><entry><literal>ssl-server-cert-file (c)</literal></entry>
     <entry>filename</entry>
     <entry valign="bottom">
      A PEM encoded SSL certificate file to be used with SSL server
		connections. This certificate is used for the HTTPS server
		side only, i.e. for the administration HTTP server and the
		HTTP interface to send SMS messages.
	  </entry>
    </row>

	 <row><entry><literal>ssl-server-key-file (c)</literal></entry>
     <entry>filename</entry>
     <entry valign="bottom">
      A PEM encoded SSL private key file to be used with SSL server
		connections. This key is associated to the specified 
		certificate and is used for the HTTPS server side only.
	  </entry>
    </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. 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">
        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>

  </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 [conffile]
	</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>[conffile]</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 [conffile]
	</userinput></screen>

  or the SMS box:

	<screen><userinput>
	./smsbox -v 1 [conffile]
	</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 logfile 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 logfile (default 0,
            which means 'debug'). Does not affect verbosity level of
            the logfile 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>