userguide.xml

mms client

	<screen><userinput>
	dpkg -l libxml2
	</userinput></screen>
	
	<para>Installing or upgrading Kannel using APT</para>

	<para>1. Log in as root:</para>

	<screen><userinput>
	su -
	</userinput></screen>

	<para>3. Install or upgrade the package:

	<screen><userinput>
	apt-get install kannel
	</userinput></screen>
	</para>

	<para>See http://kannel.org/download.shtml#debian_repository for 
	informations about kannel repository sources.list</para>

	<para>Installing or upgrading Kannel from a file</para>

	<para>1. Download the binary DEB packet from the Kannel
	web site.</para>
	
	<para>2. Log in as root:</para>

	<screen><userinput>
	su -
	</userinput></screen>

	<para>3. Install or upgrade the DEB package:</para>
	<screen><userinput>
	dpkg -i kannel-<replaceable>VERSION</replaceable>.deb
	</userinput></screen>

	<para>Removing Kannel</para>
	
	<para>1. Log in as root:</para>

	<para>2. Remove the package keeping configuration files:</para>
	<screen><userinput>
	dpkg --remove kannel
	</userinput></screen>

	<para>3. Remove the package completely:</para>
	<screen><userinput>
	dpkg --purge kannel
	</userinput></screen>

	<para>After you have installed Kannel from the DEB packages you
	should now be able to run the Kannel init.d script that will
	start Kannel as a WAP gateway. Run the script as root.</para>

	<screen><userinput>
	/etc/init.d/kannel start
	</userinput></screen>

	<para>To stop the gateway just run the same script with the
	stop parameter.</para>

	<screen><userinput>
	/etc/init.d/kannel stop
	</userinput></screen>
	
	<para>If Kannel is already running and you just want to quickly
	stop and start the gateway,e.g.to set a new configuration option,
	run the script with the restart parameter.</para>

	<screen><userinput>
	/etc/init.d/kannel restart
	</userinput></screen>
	
	<para>If you don't want Kannel to run as a daemon, 
	run: </para>
	
	<screen><userinput>
	update-rc.d -f kannel remove
	</userinput></screen>

	<para>If you want to restore Kannel runing as a daemon, you 
	need to add a
	symbolic link to the Kannel script from the runlevel you want
	Kannel to run in. E.g. to run Kannel in default runlevel, 
	just run: </para>
	
	<screen><userinput>
	update-rc.d kannel defaults
	</userinput></screen>
	
	<para>Kannel package starts by default with a wapbox daemon.
	To activate smsbox or select which box you want to start, 
	edit /etc/default/kannel and comment/uncomment START_xxxBOX.
	</para>

	<para>To run Kannel as a SMS gateway you need to edit the
	configuration file which is at /etc/kannel/kannel.conf.
	In /usr/share/docs/kannel/examples/ there are example files. 
	They have some basic examples of the configuration groups 
	needed to run Kannel as a SMS gateway. For
	more detailed information please read the section "SMS gateway
	configuration" later in this same document.</para>

	<para>The documentation will be installed at 
	/usr/share/doc/kannel/.</para>

	<para>In the Kannel documentation directory there is a html
	file called control.html. It is an example file that shows
	how to use the Kannel http administration interface. It
	also has a template for sending SMS messages.</para>

	<para>Aditionally to kannel-VERSION.deb, there's now an optional
	kannel-docs-VERSION.deb with documentation (userguide et al) and
	a kannel-extras-VERSION.deb with contrib and test stuff.</para>

	<para>If you want to test development version, use the packages
	called kannel-devel-*.deb.</para>

</sect2>

</sect1>

</chapter>









<chapter>
<title>Using the gateway</title>

	<para>This chapter explains how the gateway core, bearerbox,
        is configured and used.
	It covers the configuration file, keeping an eye on the gateway
	while it is running, and using the HTTP interface to control
	the gateway.</para>

        <para>After this chapter there is distinct chapter for each
        kind of gateway use: WAP gateway, SMS gateway and combined
        gateway. These chapters explain the configuration and other
        aspects of gateway of that type.</para>

	<para>There is only one configuration file for all parts of
	Kannel, although when Kannel is distributed to several hosts
	some lines from the configuration file can be removed in some
	hosts.</para>

<sect1>
<title>Configuring the gateway</title>

	<para>The configuration file can be divided into three parts:
	bearerbox configurations, smsbox configurations and
	wapbox configurations. Bearerbox part has one 'core' group
	and any used SMS center groups, while wapbox part has only
	one wapbox group. In smsbox part there is one smsbox group and
	then number of sms-service and sendsms-user groups.</para>

	<para>Details of each part are in an appropriate section of this
        documentation. The 'core' group used by the bearerbox is
        explained in this chapter, while 'wapbox' part is in the next
        chapter and 'smsbox', 'smsc' (SMS center), 'sms-service' and
        'sendsms-user' groups are in the SMS Kannel chapter.</para>

  

<sect2>
<title>Configuration file syntax</title>

	<para>A configuration file consists of groups of configuration variables. Groups are
	separated by empty lines, and each variable is defined on its
	own line. Each group in Kannel configuration is distinguished
	with a group variable. Comments are lines that begin with a number sign
	(<literal>#</literal>) and are ignored (they don't, for example,
	separate groups of variables).</para>
	
	<para>A variable definition line has the name of the variable,
	and equals sign (<literal>=</literal>) and the value of the
	variable. The name of the variable can contain any characters
	except whitespace and equals. The value of the variable is a
	string, with or without quotation marks (<literal></literal>)
	around it. Quotation marks are needed if the variable needs to
	begin or end with whitespace or contain special
	characters. Normal C 	escape character syntax works inside 
	quotation marks.</para>

	<para>Perhaps an example will make things easier to comprehend:

<programlisting>
1    # A do-nothing service.
2    group = sms-service
3    keyword = nop
4    text = "You asked nothing and I did it!"
5
6    # Default service.
7    group = sms-service
8    keyword = default
9    text = "No services defined"
</programlisting>

	The above snippet defines the keyword <literal>nop</literal>
	for an SMS service, and a default action for situation when
	the keyword in the SMS message does not match any defined
	service.</para>
	
	<para>Lines 1 and 6 are comment lines. Line 5 separates the
	two groups. The remaining lines define variables. The
	group type is defined by the group variable value.</para>
	
	<para>The various variables that are understood in each type
	of configuration group are explained below.</para>

	<para>Some variable values are marked as
	<literal>'bool'</literal>. The value for variable can be like
	true, false, yes, no, on, off, 0 or 1. Other values are
	treated as 'true' while if the variable is not present at all,
	it is treated as being 'false'.</para>
	
</sect2>

<sect2 id="includes">
<title id="includes.title">Inclusion of configuration files</title>

	<para>A configuration file may contain a special directive 
	called <literal>include</literal> to include other 
	file or a directory with files to the configuration 
	processing.</para>
 
	<para>This allows to segment the specific configuration groups
	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 www 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 unsecure plain HTTP 
		  server. To access the administration pacges 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 wildcard in a place of any ONE number, so *.*.*.*
        matches any IP.