userguide.xml

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

	required for several services and boxes to different files and
	hence to have more control in larger setups.</para>

	<para>Here is an example that illustrates the <literal>include
	</literal> statement :

<programlisting>
group = core
admin-port = 13000
wapbox-port = 13002
admin-password = bar
wdp-interface-name = "*"
log-file = "/var/log/bearerbox.log"
log-level = 1
box-deny-ip = "*.*.*.*"
box-allow-ip = "127.0.0.1"

include = "wapbox.conf"

include = "configurations"
</programlisting>

	Above is the main <literal>kannel.conf</literal> configuration
	file that includes the following <literal>wapbox.conf</literal>
	file with all required directives for the specific box, and a 
	<literal>configurations</literal> directory which may include 
	more files to include.

<programlisting>
group = wapbox
bearerbox-host = localhost
log-file = "/var/log/wapbox.log"
log-level = 0
syslog-level = none
</programlisting>


	The above <literal>include</literal> statement may be defined
	at any point in the configuration file and at any inclusion 
	depth. Hence you can cascade numerous inclusions if necessary.
	</para>

	<para>At process start time inclusion of configuration files 
	breaks if either the included file can not be opened and 
	processed or the included file has been processed already in 
	the stack and a recursive cycling has been detected.</para>

</sect2>

<sect2>
<title>Core configuration</title>

  <para>Configuration for Kannel <emphasis>MUST</emphasis> always
  include a group for general bearerbox configuration. This group is
  named as 'core' in configuration file, and should be the first group
  in the configuration file.</para>

  <para>As its simplest form, 'core' group looks like this:

<programlisting>
group = core
admin-port = 13000
admin-password = f00bar
</programlisting>

   Naturally this is not sufficient for any real use, as you want to
   use Kannel as an SMS gateway, or WAP gateway, or both. Thus, one or
   more of the optional configuration variables are used. In following
   list (as in any other similar lists), all mandatory variables are
   marked with <literal>(m)</literal>, while conditionally mandatory
   (variables which must be set in certain cases) are marked with
   <literal>(c)</literal>.</para>


 <table frame="none">
  <title>Core 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>core</literal></entry>
     <entry valign="bottom">
       This is a mandatory variable
     </entry></row>

    <row><entry><literal>admin-port (m)</literal></entry>
     <entry>port-number</entry>
     <entry valign="bottom">
        The port number in which the bearerbox listens to HTTP
        administration commands. It is NOT the same as the HTTP
        port of the local HTTP server, just invent any port, but
        it must be over 1023 unless you are running Kannel as a
        root process (not recommended)
     </entry></row>

	 <row><entry><literal>admin-port-ssl (o)</literal></entry>
     <entry>bool</entry>
     <entry valign="bottom">
        If set to true a SSL-enabled administration HTTP server
		  will be used instead of the default insecure plain HTTP
		  server. To access the administration pages you will have
		  to use a HTTP client that is capable of talking to such
		  a server. Use the "https://" scheme to access the
		  secured HTTP server. Defaults to "no".
     </entry></row>

    <row><entry><literal>admin-password (m)</literal></entry>
     <entry>string</entry>
     <entry valign="bottom">
         Password for HTTP administration commands (see below)
     </entry></row>

    <row><entry><literal>status-password</literal></entry>
     <entry>string</entry>
     <entry valign="bottom">
         Password to request Kannel status. If not set, no password is
	 required, and if set, either this or
	 <literal>admin-password</literal> can be used
     </entry></row>
   
    <row><entry><literal>admin-deny-ip</literal></entry>
     <entry morerows="1">IP-list</entry>
     <entry morerows="1" valign="bottom">
        These lists can be used to prevent connection from given IP 
  addresses. Each list can have several addresses, separated with    
  semicolons (';'). An asterisk ('*') can be used
        as a wild-card in a place of any ONE number, so *.*.*.*
        matches any IP.
     </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 separate 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 separate 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 wild-card 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 log-file 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>access-log-clean</literal></entry>
     <entry>boolean</entry>
     <entry valign="bottom">
        Indicates if <literal>access-log</literal> will contain standard 'markers', 
		  which means the 'Log begins', 'Log ends' markers and the prefixed
		  timestamp. This config directive should be set to 'true' if a custom 
		  logging format is desired without a prefixed default timestamp. 
     </entry></row>

    <row><entry><literal>access-log-format</literal></entry>
     <entry>string</entry>
     <entry valign="bottom">
		  String defining a custom log file line format. May use escape codes as defined
		  later on to substitute values of the messages into the log entry. If no
		  custom log format is used the standard format will be:
		  <literal>"%t %l [SMSC:%i] [SVC:%n] [ACT:%A] [BINF:%B] [from:%p] [to:%P] 
		           [flags:%m:%c:%M:%C:%d] [msg:%L:%b] [udh:%U:%u]"</literal>
     </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-enabled 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>