userguide.xml

mms client

	<para>This chapter explains how the gateway can be installed,
	either from a source code package or by using a pre-compiled
	binary version. The goal of this chapter is to get the gateway
	compiled and all the files in the correct places; the next
	chapter will explain how the gateway is configured.</para>

<sect1>
<title>Getting the source code</title>

	<para>The source code to
	Kannel is available for download at <ulink
	url="http://www.kannel.3glab.org/download.shtml">http://www.kannel.3glab.org/download.shtml</ulink>.
	It is available in various formats and you can choose to download
	either the latest release version or the daily snapshot of the
	development source tree for the next release version, depending
	on whether you want to use Kannel for production use or to
	participate in the development.</para>
	
	<para>If you're serious about development, you probably want to
	use CVS, the version control system used by the Kannel project.
	This allows you to participate in Kannel development much
	more easily than by downloading the current daily snapshot and
	integrating any changes you've made every day. CVS does that
	for you. (See the Kannel web site for more information on how
	to use CVS.)</para>

</sect1>


<sect1>
<title>Finding the documentation</title>

	<para>The documentation for Kannel consists of three parts:
	
	<orderedlist>
	<listitem><para><citetitle>User's Guide</citetitle>, i.e., the one
		you're reading at the moment.</para></listitem>
	<listitem><para><citetitle>Architecture and 
		Design</citetitle>, in <filename>doc/arch</filename> or
		at <ulink url="http://www.kannel.3glab.org/arch.shtml">
		http://www.kannel.3glab.org/arch.shtml</ulink></para></listitem>
	<listitem><para>The <filename>README</filename> and various other
		text files in the source tree.</para></listitem>
	</orderedlist>
	
	We intend to cover everything you need to install and use Kannel
	is in <citetitle>User's Guide</citetitle>, but the guide is still incomplete in this respect. Similarly, the <citetitle>Architecture and
	Design</citetitle> document should tell you everything you need
	to know to dive into the sources and quickly make your own modifications. It's not a replacement for actually
	reading the source code, but it should work as a map to the
	source code.  The <filename>README</filename> is not supposed
	to be very important, nor contain much information. Instead,
	it will just point at the other documentation.
	</para>
	
	<para>You need the following tools to compile Kannel:
	
	<itemizedlist>

	<listitem><para>C compiler and libraries for ANSI C, with normal
	Unix extensions such as BSD sockets.</para></listitem>

	<listitem><para>An implementation of POSIX threads
	(<filename>pthread.h</filename>).</para></listitem>

	<listitem><para>GNU Bison 1.28, if you want to modify the WMLScript
	compiler (a pre-generated parser is included for those who just
	want to compile Kannel).</para></listitem>

	<listitem><para>DocBook processing tools: DocBook stylesheets,
	jade, jadetex, etc; see <filename>README.docbook</filename> for
	more information (pre-formatted versions of the documentation
	are available, and you can compile Kannel itself even without
	the documentation tools).</para></listitem>
	
	<listitem><para>GNU autoconf, if you want to modify the
	configuration script.</para></listitem>

	</itemizedlist>
	
	</para>

</sect1>

<sect1>
<title>Compiling the gateway</title>

	<para>If you are using Kannel on a supported platform, or one
	that is similar enough to one, compiling Kannel is trivial.
	After you have unpacked the source package of your choosing,
	or after you have checked out the source code from CVS, enter
	the following commands:
	
	<screen><userinput>
        ./configure
        make
	</userinput></screen>
	
	The <filename>configure</filename> script investigates various
	things on your computer for the Kannel compilation needs, and
	writes out the <filename>Makefile</filename> used to compile
	Kannel. <command>make</command> then runs the commands to actually
	compile Kannel.</para>
	
	<para>If either command writes out an error message and stops
	before it finishes its job, you have a problem, and you either
	need to fix it yourself, if you can, or report the
	problem to the Kannel project. See <xref linkend="bug-reporting">
	for details.</para>
	
	<para>For detailed instruction on using the configuration
	script, see file <filename>INSTALL</filename>. That file is
	a generic documentation for <command>configure</command>. Kannel
	defines a few additional options:
	
    	<itemizedlist>

        <listitem><para><literal>--with-defaults=</literal><replaceable>type</replaceable>

	    Set defaults for the other options.
	    <replaceable>type</replaceable> is either <literal>speed</literal>
	    or <literal>debug</literal>.  The default is
            <literal>debug</literal>.
	    </para></listitem>

	<listitem><para><literal>--enable-docs (default)</literal>

	    Build documentation, b.e., converting the User Guide and
	    the Architecture Guide from the DocBook markup language to
	    PostScript and HTML.</para></listitem>

	<listitem><para><literal>--disable-docs</literal>

	    Don't build documentation.</para></listitem>

	<listitem><para><literal>--enable-drafts</literal>

	    When building documentation, include the sections marked as
	    <literal>draft</literal>.</para></listitem>

	<listitem><para><literal>--disable-drafts (default)</literal>

	    When building documentation, don't include the sections marked 
	    as <literal>draft</literal>.</para></listitem>

	<listitem><para><literal>--enable-debug</literal>

	    Enable non-reentrant development time
	    debugging of WMLScript compiler.</para></listitem>

	<listitem><para><literal>--enable-localtime</literal>

	    Write log file time stamps in local time, not
	    GMT.</para></listitem>

	<listitem><para><literal>--disable-assertions</literal>

	    Turn off runtime assertion checking.  This makes
	    Kannel faster, but gives less information if it crashes.
	    </para></listitem>

	<listitem><para><literal>--with-malloc=</literal><replaceable>type</replaceable>

	    Select memory allocation module to use:
	    <replaceable>type</replaceable> is <literal>native</literal>,
            <literal>checking</literal> (the default), or
            <literal>slow</literal>.  For production use you probably
	    want <literal>native</literal>.  The <literal>slow</literal>
            module is more thorough than <literal>checking</literal>,
	    but much slower.</para></listitem>

	<listitem><para><literal>--enable-mutex-stats</literal>

	    Produce information about lock contention.</para></listitem>

	<listitem><para><literal>--enable-start-stop-daemon</literal>

	    Compile the start-stop-daemon program.</para></listitem>

	<listitem><para><literal>--enable-pam</literal>

	    Enable using PAM for authentication of sendsms users for
	    smsbox.</para></listitem>

	</itemizedlist>
	</para>
	
	<para>You may need to add compilations flags to configure:

	<screen><userinput>
	CFLAGS='-pthread' ./configure
	</userinput></screen>

	The above, for instance, seems to be required on FreeBSD. If you
	want to develop Kannel, you probably want to add CFLAGS that make
	your compiler use warning messages. For example, for GCC:
	
	<screen><userinput>
	CFLAGS='-Wall -O2 -g' ./configure
	</userinput></screen>
	
	(You may, at your preference, use even stricter checking options.)
	</para>

</sect1>

<sect1>
<title>Installing the gateway</title>

	<para>After you have compiled Kannel, you need to install
	certain programs in a suitable place. This is most easily
	done by using <command>make</command> again:
	
	<screen><userinput>
	make bindir=<replaceable>/path/to/directory</replaceable> install
	</userinput></screen>

	Replace <replaceable>/path/to/directory</replaceable> with the
	pathname of the actual directory where the programs should be
	installed. The programs that are installed are (as filenames
	from the root of the source directory):
	
	<simplelist>
	<member><filename>gw/bearerbox</filename></member>
	<member><filename>gw/smsbox</filename></member>
	<member><filename>gw/wapbox</filename></member>
	</simplelist>
	
	The version number of the gateway is added to the file names
	during installation. This makes it easier to have several
	versions installed, and makes it easy to go back to an older
	version if the new version proves problematic.</para>
	
	<para>Kannel consists of three programs called boxes: the
	bearer box is the interface towards the phones. It accepts
	WAP and SMS messages from the phones and sends them to the
	other boxes. The SMS box handles SMS gateway functionality,
	and the WAP box handles WAP gateway functionality. There can
	be several SMS boxes and several WAP boxes running and they
	don't have to run on the same host. This makes it possible
	to handle much larger loads.</para>

</sect1>

<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. Log in as root:</para>

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

	<para>3. Install the RPM package:

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

	<para>Upgrading Kannel</para>

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

	<para>2. Log in as root</para>
	
	<para>3. Upgrade the RPM package:

        <screen><userinput>
	rpm -Uvh kannel-VERSION.i386.rpm
	</userinput></screen>
        </para>
	
	<para>Removing Kannel</para>
	
	<para>1. Log in as root:</para>

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

	<para>After you have installed Kannel from the RPM packages you
x	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 the same directory there is an example file called
	smskannel.conf. It has 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 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/share/doc/kannel-VERSION/ or /usr/doc/kannel-VERSION/
	depending on if you used the RedHat 7.x or 6.x 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>Before you install Kannel, check that you have libxml2
	installed on your system:</para>