userguide.xml

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

			<listitem><para>Fully compliant with WAP 1.1 specification</para></listitem>
			<listitem><para>Already implements some WAP 1.2 and even WAP 2.0 features.</para></listitem>
			</itemizedlist>
		</para>
	</sect2>
	<sect2>
	<title>WAP Push</title>
		<para>
			<itemizedlist>
			<listitem><para>Supports WAP Push SI and SL</para></listitem>
			<listitem><para>...</para></listitem>
			</itemizedlist>
		</para>
	</sect2>
	<sect2>
	<title>SMS</title>
		<para>
			<itemizedlist>
			<listitem><para>Supports a variety of SMSC protocols, namely:</para>
				<itemizedlist>
				<listitem><para>CMG's UCP/EMI 4.0 and 3.5</para></listitem>
				<listitem><para>...</para></listitem>
				</itemizedlist>
			</listitem>
			<listitem><para>Full support for MO and MT messages</para></listitem>
			</itemizedlist>
		</para>
	</sect2>
</sect1>

<sect1>
<title>Requirements</title>

	<para>Kannel is being developed on Linux systems,
	and should be fairly easy to export to other Unix-like
	systems. However, we don't yet support other platforms, due to lack
	of time, although it should be working without major problems on 
	Windows (through Cygwin), Solaris and FreeBSD.
	</para>
	
	<para>Kannel requires the following software environment:
	
	<itemizedlist>

	<listitem><para>C compiler and libraries for ANSI C, with normal
		Unix extensions such as BSD sockets and related tools. 
		(GNU's GCC tool-chain is recommended)</para></listitem>

	<listitem><para>The Gnome XML library (known as
		gnome-xml and libxml), version 2.2.5 or newer. See <ulink
		url="http://xmlsoft.org/xml.html">http://xmlsoft.org/xml.html</ulink>.
		</para>
		<para>If you are installing it from your distribution's packages, you'll need
		<literal>libxml2-dev</literal> in addition to run-time <literal>libxml2</literal> package
		libraries.</para></listitem>
	
	<listitem><para>GNU Make.</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 style-sheets,
		jade, jadetex, etc; see <filename>README</filename>, section
                `Documentation', 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>
	
	<para>Hardware requirements are fluffier. Some informal benchmarkings 
	have shown that with a reasonably fast PC architecture (e.g. 400MHz 
	Pentium II with 128MB RAM), SMS performance's bottleneck is always on the
	SMSC side, even for example with multiple connections summing a pipeline with 
	400 msg/sec.  We haven't benchmarked Kannel yet on WAP side, so there are 
	no hard numbers.</para>

</sect1>

</chapter>

<chapter>
<title>Installing the gateway</title>

	<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>

	<note><para>If you are upgrading from a previous version, please look at
	<xref linkend="upgrading-notes"> for any important information.</para></note>

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

	<para>The source code to
	Kannel is available for download at <ulink
	url="http://www.kannel.org/download.shtml">http://www.kannel.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.org/arch.shtml">
		http://www.kannel.org/arch.shtml</ulink></para></listitem>
	<listitem><para>The <filename>README</filename> and various other
		text files in the source tree.</para></listitem>
		
	</orderedlist>
	</para>
	
	<para>You can also find general information on Kannel's 
		<ulink url="http://www.kannel.org">website</ulink> and
		information about existing problems at 
		<ulink url="http://bugs.kannel.org">our bugtracker</ulink>.
	</para>

	<para>
	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>
	
</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 should be trivial.
	After you have unpacked the source package of your choose,
	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>speed</literal>. <literal>speed</literal> options is equivalent to 
	    <literal>--with-malloc=native --disable-assertions</literal>, while 
	    <literal>debug</literal> is <literal>--with-malloc=checking --enable-assertions</literal>.

	    </para></listitem>

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

	    Use this option if you don't have DocBook installed and/or 
	    you want to save some time and CPU cycles. 
	    Pre-generated documentation is available on Kannel's site.
	    Default behavior is to build documentation, b.e., converting the User Guide and
	    the Architecture Guide from the DocBook markup language to
	    PostScript and HTML if DocBook is available.
	    </para></listitem>

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

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

	<listitem><para><literal>--enable-debug (default is --disable-debug)</literal>

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

	<listitem><para><literal>--disable-localtime (default is --enable-localtime)</literal>

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

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

	    Turn on or off runtime assertion checking.  <literal>enable</literal> makes
	    Kannel faster, but gives less information if it crashes.
	    Default value is dependent on <literal>--with-defaults</literal>.
	    </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>, 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. 
	    Default value is dependent on <literal>--with-defaults</literal>.
	    </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>

        <listitem><para><literal>--with-mysql</literal>

            Enable using MySQL libraries for DBPool and
            DLR support.</para></listitem>

        <listitem><para><literal>--with-mysql-dir=</literal><replaceable>DIR</replaceable>

            Where to look for MySQL libs and header files.
            DIR points to the installation of MySQL.</para></listitem>

        <listitem><para><literal>--with-sdb</literal>

            Enable using LibSDB libraries for dlr support.
            </para></listitem>

        <listitem><para><literal>--with-oracle</literal>

            Enable using Oracle OCI-Libraries for Oracle 8i/9i DBPool and
            DLR support.</para></listitem>

        <listitem><para><literal>--with-oracle-includes=</literal><replaceable>DIR</replaceable>

            Where to look for Oracle OCI-Header files.</para></listitem>

        <listitem><para><literal>--with-oracle-libs=</literal><replaceable>DIR</replaceable>

            Where to look for Oracle OCI-Library files.</para></listitem>

	<!-- XXX DAVI add openssl and others in here -->

	</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>