userguide.xml

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

<sect1>
<title>Using pre-compiled binary packages</title>

<sect2>
<title>Installing Kannel from RPM packages</title>

	<para>This chapter explains how to install, upgrade and remove
	Kannel binary RPM packages.</para>
		
	<para>Before you install Kannel, check that you have libxml2
	installed on your system:</para>

	<screen><userinput>
	rpm -q libxml2
	</userinput></screen>
	
	<para>Installing Kannel</para>

	<para>1. Download the binary RPM packet from the Kannel
	web site.</para>
	
	<para>2. Install the RPM package:

	<screen><userinput>
	rpm -ivh kannel-<replaceable>VERSION</replaceable>.<replaceable>i386</replaceable>.rpm
	</userinput></screen>
	</para>

	<para>Upgrading Kannel</para>

	<para>1. Download the binary RPM packet from the Kannel
        web site.</para>

	<para>2. Upgrade the RPM package:

        <screen><userinput>
	rpm -Uvh kannel-<replaceable>VERSION</replaceable>.<replaceable>i386</replaceable>.rpm
	</userinput></screen>
        </para>
	
	<para>Removing Kannel</para>

	<para>1. Remove the RPM package:
	
	<screen><userinput>
	rpm -e kannel
	</userinput></screen>
	</para>

	<para>After you have installed Kannel from the RPM 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/rc.d/init.d/kannel start
	</userinput></screen>

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

	<screen><userinput>
	/etc/rc.d/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/rc.d/init.d/kannel restart
	</userinput></screen>
	
	<para>If you want Kannel to run 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 runlevel 5 add symbolic
	links to /etc/rc.d/rc5.d/.</para>

	<screen><userinput>
	cd /etc/rc.d/rc5.d/
	ln -s ../init.d/kannel S91kannel
	ln -s ../init.d/kannel K91kannel
	</userinput></screen>

	<para>To run Kannel as a SMS gateway you need to edit the
	configuration file which is at /etc/kannel/kannel.conf.
	In kannel's documentation directory 
	(<filename>/usr/share/doc/kannel</filename>) 
	there is an example file called examples/smskannel.conf. 
	It has some basic examples of the configuration groups needed 
	to run Kannel as a SMS gateway. For more detailed information 
	please see <filename>examples/kannel.conf</filename> in the
	same directory for a commented complete example, and read the 
	section "SMS gateway configuration" later in this same 
	document.</para>

	<para>The logging is disabled by default and you can enable
	it from the kannel.conf file. Just add the log-file option
	to the group of which box you want to log.</para>  
	
	<para>The documentation will be installed at 
	/usr/doc/kannel-VERSION/ or /usr/share/doc/kannel-VERSION/
	depending on if you used the RedHat 6.x or a 7.x or newer 
	package.</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>

</sect2>

<sect2>
<title>Installing Kannel from DEB packages</title>

	<para>This chapter explains how to install, upgrade and remove
	Kannel binary DEB packages.</para>

	<para>Kannel's packages are available on main Debian repository 
	(<ulink url="http://packages.debian.org/kannel">http://packages.debian.org/kannel</ulink>)
	although that version may be out-of-sync with latest Kannel version.
	</para>
	<!-- XXX DAVI add kannel packages and my repository here -->
		
	<para>Before you install Kannel, check that you have libxml2
	installed on your system:</para>

	<screen><userinput>
	dpkg -l libxml2
	</userinput></screen>
	
	<para>Installing or upgrading Kannel from Debian or Kannel repository</para>

	<para>1. 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 running 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>Additionally 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 WAP Push
        proxy. These chapters explain the configuration and other
        aspects of gateway of that type.</para>
	
	<para>You can configure your Kannel to be only a WAP or a SMS
	gateway, or to be both at the same time. You just need to read
	each chapter and combine all configurations.</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