README

README for Kannel: Open Source WAP and SMS Gateway


Abstract

	This README describes Kannel, the Open Source WAP and SMS gateway,
	and how it can be used and installed.

Introduction

	The Kannel Open Source WAP and SMS gateway works as both an SMS
	gateway, for implementing keyword based services via GSM text
	messages, and a WAP gateway, via UDP. The SMS part is fairly
	mature, the WAP part is early in its development. In this release,
	the GET request for WML pages and WMLScript files via HTTP works,
	including compilation for WML and WMLScript to binary forms. Only
	the data call bearer (UDP) is supported, not SMS.
	
Requirements

	You need a Unix-like operating system that supports POSIX threads
	(pthreads.h). We use RedHat Linux and Debian GNU/Linux systems.

	There is also support for the Cygwin 1.3 POSIX emulation layer
	for the Win32 platforms.
	
	You need GNU make, other make's tend not to work. For example,
	the FreeBSD and Solaris versions of make do not work. Check the
	version of your make with "make --version"; if it does not reply
	with "GNU Make version x.y.z", then it is not GNU make.
	
	On Solaris, you probably want to install gcc, GNU make and GNU
	binutils from www.sunfreeware.com.
	
	On MacOS X, you may have problems in compiling the latest libxml
	(2.4.23). There may be linking errors for those library. A work-
	arround is either using an older version of libxml (2.3.9 for 
	example) or to build it as static library without the dynamic one 
	being built.

Documentation

	The user manual is in the doc/userguide directory and although it
	is not complete, explain almost all parts of Kannel. Developer
	documentation (currently very outdated) is in the doc/arch
	directory.
	
	In order to convert the documentation from DocBook (a markup
	language) to HTML and PostScript, you need some tools. 
	
    On a Debian GNU/Linux system, you need to install the following
	packages via: 
	
           $ sudo apt-get install graphicsmagick-imagemagick-compat \
                  docbook-dsssl jadetex transfig openjade
    
    On a Red Hat Linux (RHEL) system, you need to install the following
	packages, in order:
	
		sgml-common
		psgml
		docbook
		stylesheets
		jade
		jadetex
		transfig

	See http://www.rpmfind.net to find the packages.
    	
    On a Fedora Core system, you need to install the following packages:
    
        $ sudo yum install openjade jadetex docbook-style-dsssl \
        	texlive-dvips transfig ImageMagick

    On a Gentoo system, the following should do:

	    $ sudo emerge transfig jadetex docbook-dsssl-stylesheets

    On a Mandrakelinux system, the following should do:
		
		$ urpmi transfig jadetex docbook-style-dsssl

	Then apply this change to /usr/share/texmf/web2c/texmf.cnf:
	
		hash_extra.jadetex = 15000
		hash_extra.pdfjadetex = 15000
		pool_size.jadetex = 500000
		pool_size.pdfjadetex = 500000
		string_vacancies.jadetex = 45000
		string_vacancies.pdfjadetex = 45000
		max_strings.jadetex = 55000
		max_strings.pdfjadetex = 55000
		pool_free.jadetex = 47500
		pool_free.pdfjadetex = 47500
		nest_size.jadetex = 500
		nest_size.pdfjadetex = 500
		param_size.jadetex = 1500
		param_size.pdfjadetex = 1500
		save_size.jadetex = 5000
		save_size.pdfjadetex = 5000
		stack_size.jadetex = 1500
		stack_size.pdfjadetex = 1500
	
	On other systems, you'll have to figure it out yourself.
	
Getting the gateway sources

	You can download the sources from
	http://www.kannel.org/download.shtml.
	
	Note that you also need the Gnome-xml library from
	http://xmlsoft.org/xml.html. That one probably requires zlib,
	depending on how it is configured. You need at least version
	2.2.0

Compiling and installing the gateway

	See the file INSTALL for generic installation instructions.
	The short form:
	
		./configure
		touch .depend
		make depend
		make
		make bindir=/somewhere/suitable install

	See the User Guide (doc/userguide/ or
	http://www.kannel.org/userguide.shtml) for Kannel specific
	options to configure.

For developers only: autoconf, configure, config.status, and Makefile

	We use the GNU autoconf tool to make it easier to adapt Kannel to
	each platform. The `autoconf' program reads the file configure.in,
	and generates a corresponding shell script called configure,
	which investigates the system it runs on to see what it supports
	and what it does not. configure then reads Makefile.in and
	config.h.in and writes out Makefile, config.h, and a shell
	script config.status.
	
	If you modify configure.in, you need to run autoconf.
	
	If you modify Makefile.in or config.h.in, you need to run
	config.status.
	
	If you modify any source files to add or change any header
	includes, you need to run "make depend".
	
	You always need to run "make" (which is the same as "make all").
	
	If you have trouble building things and suspect that there is a
	problem with the Makefile, run "make clean all". If that solves
	it, report it as a bug (see the end of this README).

For developers only: adding new SMS Center protocol support

	As Kannel does not support all the SMSC protocols that exists,
	it might become necessary to add new kind of protocols, 
	including support to use mobile phones as SMSCes.

	When doing this, read interface specification in gw/smscconn_p.h.
	Drivers should stick to these rules as good as they can.

For developers only: "make check"

	The Kannel Makefile contains a target called "check", which
	is used to run a series of automatic, non-interactive tests on
	various subsystems. 
	
	Each test program MUST stored in the `checks' subdirectory. Each
	test MUST be written either as a C program named `check_*.c'
	or a Bourne shell script named `check_*.sh'. The C programs are
	compiled by the Makefile, the shell scripts MUST be executable.

	The test programs MUST output nothing to stdout, and MUST use a
	zero exit code to indicate that the test was successful, and a
	non-zero exit code to indicate a failure of the test. This way,
	if one runs "make -s check", one can easily see which tests are
	run and which tests work.
	
	The test programs MUST output error messages to stderr and they
	MUST mention which test program and which subtest failed. In
	case of failure, they may leave log files or other auxiliary
	files, and these MUST be listed in the error messages to stderr,
	so that the user has a reasonable way to diagnose the error.
	The Makefile captures the stderr output to `check.log'.

	The tests SHOULD take a reasonable time, preferably less than
	fifteen seconds each. This way, one can run "make -s check"
	before each commit. If there is a need to run longer tests,
	then the tests need to be divided into fast and slow ones.
	
	These tests are meant to test whether subsystems mostly work,
	stress testing needs to be done separately, and tends to require
	testing against real applications.

For developers only: Source tree organization

	The source tree is organized as follows:
	
		gateway		root of source tree: some docs, no sources
		|-- contrib	contributed extra material
		|-- doc		documentation
		|-- gw		the gateway itself
		|-- gwlib	utility functions
		|-- test	programs for testing the gateway
		`-- utils	utility programs

For developers only: WMLScript references

	WMLScript Specification
		      Wireless Application Protocol WMLScript Language
		      Specification Version 1.1 http://www.wapforum.org/

	WMLScript Standard Libraries Specification
		      Wireless Aplication Protocol WMLScript
		      Standard Libraries Specification Version 1.1
		      http://www.wapforum.org/

	RFC-2279	UTF-8, a transformation format of ISO 10646

	rfc/iana/assignments/character-sets
		      The official names for character sets that may
		      be used in the Internet and may be referred to in
		      Internet Documentation.

	ANSI/IEEE Std 754-1985
		      IEEE Standard for Binary Floating-Point Arithmetic.
		      Institute of Electrical and Electronics Engineers,
		      New York (1985).

Configuring and running the gateway

	See the user guide in doc/userguide or on the web at
	http://www.kannel.org/doc.shtml.
	
	For test use, you can see sample configurations
	gw/smskannel.conf (SMS gateway) and gw/wapkannel.conf (WAP gateway).

Using the gateway with a Nokia 7110

	To configure a Nokia 7110 to use the gateway, fill in the
	following (note that you need to provide your own dialup
	line):
	
		Home page: http://www.kannel.org/wap/hello.wml
		(or any other WML page)
		Connection type: continuous
		Connection security: off
		Bearer: data
		Dial-up number: <your dialup line>
		IP address: <IP number of the host running bearer box>
		Authentication type: normal
		Data call type: <analog or isdn, depending on your line>
		Data call speed: 9600
		User name: <username for your dialup line>
		Password: <password for your dialup line>
		
	After you have modified the profile, activate it and load the
	home page. If you use the sample page above, you should see
	"hello, world" on the screen after a few moments.

Modifications to old Kannel (0.8 and older)

	After release 0.8 Kannel architecture has been modified
	considerably, resulting changes in basic running of the standard
	WAP or WAP gateway.

	In new design, there is only one configuration file (to be more
	exact, you can have several of them, one for each kind of box,
	but that is advanced feature, which is not very usable) for
	bearerbox, smsboxes and wapboxes. Details of that file is in
	doc/userguide/newconf.txt.  As a quick reference, you just put
	all your old configuration files into same file, remove some
	rows and add 'group = xxx' variables into it.

	Moreover, there is no internal smsbox in new Kannel. So, when
	running SMS services you MUST run separate smsbox. This is most
	easily done with Kannel as daemon, launched with init.d. See
	utils/ directory for any supplied systems.

Feedback and more information

	You may want to subscribe the announce and devel lists at
	www.kannel.org. If you need help or want to participate in the 
        development of Kannel. Send e-mail to
	
		announce-subscribe@kannel.org
		devel-subscribe@kannel.org

	(You'll get further instructions via automatic reply mails.)