alligata.xml

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

</para>
				<para>WAP and SMS complement each other. SMS is simple to use and widely available, but limited in its capabilities. WAP offers richer functionality, but as a new technology it is not yet as widespread as SMS. By offering both SMS and WAP functionality, the Alligata Server is a bridge between established and emerging technologies.
</para>
				<para>The Alligata Server is based on the Kannel WAP and SMS gateway for Linux. Kannel is an open source software project; if you would like to know more about it or contribute to it, visit the Kannel Web site at <ulink url="http://www.kannel.org">www.kannel.org</ulink>.
</para>
			</section>
			<section>
				<title>3.2 The Alligata Server, WAP and SMS
</title>
				<para>This section will help you to understand where the Alligata Server fits into the architecture of WAP and SMS. Before you read it, we recommend you read <citetitle>Your Pocket Guide to the Mobile Internet</citetitle>, included in the Alligata Server package. There you will find definitions of the terminology used by the WAP standard, and a description of how the WAP components fit together.
</para>
				<para>Every WAP phone is configured by default to use a single WAP gateway to gain access to the Mobile Internet. This gateway can be hosted by an ISP, by the phone user&apos;s employer, or by any third party with access to the Mobile Internet. A phone can contain configurations for several gateways, but it can only use a single gateway for the duration of a session. If you want to change gateways, you have to close down your Mobile Internet session, switch your phone&apos;s settings to the new gateway, and reconnect to the Mobile Internet.
</para>
				<para>The conceptual model into which the Alligata Server fits is shown in Figure 3.1.
</para>
				<mediaobject>
					<imageobject>
						<imagedata fileref="wapdiagsmall&figtype;">
					</imageobject>
				</mediaobject>
				<para>A signal sent by a mobile device is picked up by one of a network operator&apos;s base stations. It is then routed through the mobile network to the Alligata Server using User Datagram Protocol (UDP). If it is an SMS message, it is first sent to the network&apos;s <emphasis role="bold">SMS Centre (SMSC)</emphasis>. The SMSC&apos;s main job is to hold pending SMS messages for recipients whose phones are turned off or otherwise inaccessible.
</para>
				<para>Once the Alligata Server has received a WAP data packet from a client and decompressed it, it uses Hypertext Transfer Protocol (HTTP) to retrieve data from the relevant content server on the Mobile Internet.
</para>
				<para>On receiving an SMS message, the Alligata Server scans it for keywords and parameters listed in its configuration file (see Section 13.1), then sends an automatic reply to the client device depending on which keyword and parameters it encountered. This reply can consist of static text, or it can be retrieved from a local file, a WAP site or a World Wide Web page.
</para>
				<para>The Alligata Server&apos;s reply to an SMS message is another SMS message. This means that, in principle, it has to be sent to the relevant network operator&apos;s SMSC in order to be routed to the recipient device (or stored if the recipient device is not accessible). Most network operators charge a fee for terrestrial access to their SMSCs, but the Alligata Server allows you to circumvent this if you own a GSM modem, or a mobile phone that includes a GSM modem such as the Nokia 7110 or 6210. The Alligata Server can use the modem to send SMS messages directly over the airwaves. This way, you will get charged the same rates as mobile phone users for sending SMS messages from your computer workstation. See Section 9.3.2 for details of how to send messages using a GSM modem.
</para>
			</section>
			<section>
				<title>3.3 Inside the Alligata Server
</title>
				<para>The Alligata Server is a collection of three programs: a Bearer Box, a WAP Box and an SMS Box. In fact, an implementation of the Alligata Server can include any number of WAP Boxes and SMS Boxes, all linked to a single Bearer Box.
</para>
				<para>All incoming messages pass through the Bearer Box. The Bearer Box performs preliminary operations on each message and forwards it on to a WAP or an SMS Box depending on whether it is a WAP or an SMS message.
</para>
				<para>A WAP Box implements the WAP protocol stack on incoming WAP messages (apart from Wireless Datagram Protocol (WDP), which is implemented by the Bearer Box). It decompresses the WAP data and forwards requests to Internet servers using HTTP (see the booklet <citetitle>Your Pocket Guide to the Mobile Internet</citetitle> for more details). It then handles the replies from the HTTP servers, compresses the replies, implements the Wireless Session Protocol (WSP) and Wireless Transaction Protocol (WTP) layers of the WAP protocol stack on them, and sends them on to the Bearer Box. The Bearer Box implements the WDP layer, and sends the replies to the client device.
</para>
				<para>An SMS Box scans incoming SMS messages for keywords listed in the Alligata Server configuration file. It carries out the function associated with the keyword - for example, retrieving a piece of text from a Web page - and sends a reply SMS message, via the Bearer Box, to the client device.
</para>
				<section>
					<title>3.3.1 Program States
</title>
					<para>At any given time, the Alligata Server can be in one of four states:
</para>
					<itemizedlist>
						<listitem>
							<para>Running. The Alligata Server accepts, processes and sends files and messages normally.
</para>
						</listitem>
						<listitem>
							<para>Suspended. The Alligata Server does not accept any new WAP requests or messages from SMSCs. The Bearer Box does not allow new WAP or SMS Boxes to connect to it. No messages or files are sent out.
</para>
						</listitem>
						<listitem>
							<para>Isolated. The Alligata Server does not accept any new WAP requests or messages from SMSCs. However, it continues processing messages already in its system, and accepts SMS messages sent via HTTP (see Section 13.2).
</para>
						</listitem>
						<listitem>
							<para>Shutdown. The Alligata Server performs the shutdown procedure. New WAP requests and SMS messages are refused. Requests already being processed are carried through. When all queues in the boxes have been processed, the Alligata Server closes down.
</para>
						</listitem>
					</itemizedlist>
					<para>You can change the state of the Alligata Server using HTTP administration commands. See Section 8.2.2.
</para>
					<para>There follows a more detailed look at the components of the Alligata Server. You do not need to know this information to use the Alligata Server, but you may find it of interest.
</para>
				</section>
				<section>
					<title>3.3.2 Bearer Box
</title>
					<para>The Bearer Box is the interface between the mobile telephone network and the rest of the Alligata Server. It receives data from mobile phones via network bearer services or SMSCs.
</para>
					<para>On receiving a WAP data packet from a mobile device, the Bearer Box implements the WDP layer of the WAP protocol stack on it, and sends it on to a WAP Box. If a session is already running between the Alligata Server and the client device, then the message is sent to the same WAP Box as previous messages from the device. If, on the other hand, the message is the first to be received from that client in the current session, then it is sent to a WAP box at random. A basic system of load balancing is used to avoid bottlenecks forming in any single WAP Box. Load balancing works as follows: at regular intervals, each WAP Box sends a &apos;heartbeat&apos; message (see Section 3.3.3) to the Bearer Box indicating its load - that is, how many sessions it is currently handling. If this load is significantly higher than the load of the least busy WAP box, then the Bearer Box stops sending requests from new clients to the busier WAP box. When the load of the busier WAP Box has fallen sufficiently, or the load of the other WAP Boxes has increased to near its own, the busier WAP Box starts to accept requests from new clients again.
</para>
					<para>Messages are distributed among the SMS Boxes in the same way as among as the WAP Boxes. That is, the Bearer Box sends all messages from a particular client to the same SMS Box; it assigns messages from new clients to an SMS Box at random; and it uses load balancing to prevent unnecessary congestion in any particular SMS Box.
</para>
					<para>Within the Alligata Server, the Bearer Box acts as a server to the WAP or SMS Boxes. Once running, it keeps a list of all the WAP and SMS Boxes connected to it. This list starts out empty, and is extended as boxes start up and announce their presence. The Bearer Box is in constant communication with the WAP and SMS Boxes via &apos;heartbeat&apos; messages (see Section 3.3.3), and dynamically updates its list of connected WAP and SMS Boxes as new boxes connect and old ones disconnect.
</para>
					<para>As well as receiving incoming messages, the Bearer Box processes all outgoing messages from the Alligata Server&apos;s WAP and SMS Boxes, adapting each message to the bearer service of the client&apos;s network. In the case of WAP messages, it also implements the WDP layer of the WAP protocol stack.
</para>
					<para>Since all incoming and outgoing messages pass through a single Bearer Box, there is a risk of bottlenecks arising when traffic becomes very heavy. The Alligata Server is designed so that the Bearer Box does as little processing on each data packet as possible, thereby reducing this risk (particularly if there are several WAP and SMS Boxes running on different computers).
</para>
				</section>
				<section>
					<title>3.3.3 Communication Between the Boxes
</title>
					<para>Data is exchanged between the Bearer Box and the WAP and SMS Boxes via Transmission Control Protocol (TCP) stream. TCP is a protocol suited for use in wide area networks (such as the Internet), and its incorporation into the Alligata Server means that the Bearer Box, WAP Boxes and SMS Boxes can be run on separate computers, if required. The advantages of this set-up are clear: it means that, outside the Bearer Box, groups of packets can be processed simultaneously, and therefore the Alligata Server can process high volumes of messages very quickly.
</para>
					<para>If the TCP stream between the Bearer Box and a WAP or SMS Box fails for any reason, the Bearer Box notices this and removes the disconnected box from its list of available boxes. Any packets from phones that were routed to this box are then treated as packets from new clients, and redirected by the Bearer Box to an alternative WAP Box. When a WAP Box receives a message from a new client that it identifies as being from the middle of a session, it sends an error message to the client device.
</para>
					<para>A WAP or SMS Box can also go &apos;catatonic&apos;: its TCP stream to the Bearer Box is still running, but it is not responding to any messages. So that the Bearer Box knows when this has happened, WAP and SMS Boxes send &apos;heartbeat&apos; packets at regular intervals, effectively telling the Bearer Box that they are running and functioning normally. If the Bearer Box stops receiving heartbeat messages from another box, it assumes there is a problem even though the TCP stream may still be running, and removes the box from its list. When the ailing box recovers and announces its presence, the Bearer Box reopens the connection.
</para>
				</section>
				<section>
					<title>3.3.4 WAP Box
</title>
					<para>A WAP Box receives data in WDP packets through its TCP connection with the Bearer Box. It implements the and WSP layers of the WAP protocol stack on the packets, and then decompresses them. 
</para>
					<para>Each incoming WDP packet is handled by a single program thread. This thread creates and manages a WTP state machine and, where necessary, a WSP state machine for the packet. The same WTP machine and WSP machine handle all packets from a given client session.
</para>
					<para>If a packet arrives in a WAP Box while the WTP machine for which it is destined is still processing the previous packet, then the WAP Box sets up a queue specific to that WTP machine. This is preferable to creating a new thread for waiting WDP packets, as it reduces the risk of the WAP Box&apos;s thread table becoming full when traffic is very heavy.
</para>
					<para>Once the WTP and WSP layers of the WAP protocol stack have been implemented on the incoming message, the WAP Box converts it into an HTTP request, and sends it to the relevant server on the Mobile Internet.
</para>
					<para>On receiving an HTTP reply from the Mobile Internet server, the WAP Box compresses the reply, implements the WSP and WTP layers of the WAP protocol stack on it, and sends it to the Bearer Box along the TCP connection.
</para>
				</section>
				<section>
					<title>3.3.5 SMS Box
</title>
					<para>The design of an SMS Box is straightforward. An SMS Box receives SMS messages from the Bearer Box via its TCP connection, parses each message in order to extract keywords and parameters from it, and then executes a service according to which keyword the message contains. The keyword is the first word in the message; any other words are interpreted as parameters. See Section 13.1 for more information.
</para>
					<para>If the SMS service in question has a url variable defined in the configuration file (see Section 9.3.3), then the SMS Box sends an HTTP request to the appropriate URL, retrieves the data, pulls out the content between the prefix and the suffix strings as specified in the configuration file, formats this content as an SMS message or messages, and sends the SMS message(s) to the Bearer Box via the TCP stream. The Bearer Box sends the message back to the client device via an SMSC.
</para>
					<para>Other services the SMS Box can provide include sending a fixed text message or the content of a local file in response to a keyword. For more information, see Sections 9.3 and 13.1.
</para>
					<para>The SMS Box also listens for SMS messages arriving via HTTP from computer workstations. It converts these messages from HTTP into true SMS format, and sends them on to the Bearer Box to be conveyed to mobile devices. See Section 13.2 for details of how to send SMS messages from a computer workstation.
</para>
				</section>
			</section>
		</chapter>
		<chapter>
			<title>4  Installation from a Graphical User Interface</title>
			<para>If your Linux or Solaris system includes a graphical user interface, the installation program automatically installs the Alligata Server using the graphical procedure described in this section.
</para>
<FormalPara>
<title>To install the Alligata Server from a Linux/Solaris graphical user interface:</title>
<Para>
			<orderedlist inheritnum="ignore" continuation="restarts">

				<listitem>
					<para>Place the Alligata Server CD-ROM in the CD-ROM drive.
</para>
					<para>If your version of Linux or Solaris automounts CD-ROMs, a file manager window will open, showing the contents of the directory into which the CD-ROM has been mounted. (In Linux this directory is usually <filename moreinfo="none">/mnt/cdrom</filename>, in Solaris it is usually <filename moreinfo="none">/cdrom/cdrom0</filename>.)
</para>
					<para>If you are running your Linux/Solaris session as <emphasis role="bold">root</emphasis>, you can continue by double-clicking the <guiicon moreinfo="none">install</guiicon> icon in the file manager window. This will take you straight to step 8.
</para>
				</listitem>
				<listitem>
					<para>Open a terminal window.
</para>
				</listitem>
				<listitem>
					<para>In the terminal window, type </para>
					<para>
						<userinput moreinfo="none">
							su
						</userinput>
					</para>
					<para> at the command prompt and press ENTER.
</para>
					<para>You will be prompted for the <emphasis role="bold">root</emphasis> password.
</para>
				</listitem>
				<listitem>
					<para>Type the password of the <emphasis role="bold">root</emphasis> user and press ENTER.
</para>
					<para>You will be returned to the command prompt.
</para>
				</listitem>
				<listitem>
					<para>At the command prompt, type
</para>
					<para>
						<userinput moreinfo="none">
							mount <replaceable>path_of_your_system&apos;s_CD-ROM_mount_point</replaceable>
						</userinput>
					</para>
					<para>(In Linux the path of the CD-ROM mount point is usually <filename moreinfo="none">/mnt/cdrom</filename>, in Solaris it is usually <filename moreinfo="none">/cdrom/cdrom0</filename> or something similar.) For example:
</para>
					<para>
						<userinput moreinfo="none">
							mount /mnt/cdrom
						</userinput>
					</para>
					<para>Press ENTER.
</para>
					<para>If your version of Linux or Solaris automounts CD-ROMs, you can ignore this step.
</para>
				</listitem>
				<listitem>
					<para>Change directory to your system&apos;s CD-ROM mount point. For example, Linux users should type </para>
					<para>
						<userinput moreinfo="none">
							cd /mnt/cdrom
						</userinput>
					</para>
					<para> and press ENTER.
</para>
				</listitem>
				<listitem>
					<para>Type </para>
					<para>
						<userinput moreinfo="none">./install</userinput>
					</para>
					<para> and press ENTER.
</para>
				</listitem>
				<listitem>
					<formalpara>
						<title> Solaris users</title>
						<para>The installation program requires Perl to be installed on your system. If Perl is not found (for example, if you are running the default Solaris 7 system), you will be prompted to install it:</para>
					</formalpara>
					<screen format="linespecific">Perl is not installed or is not in your command path.
  Do you want to install Perl now ? (y/N)
</screen>
					<para>Type Y, ENTER to install Perl or N, ENTER to abort installation.
</para>
				</listitem>
				<listitem>
					<para>A dialog box opens containing information on the licences used by the Alligata Server package (see Figure 4.1).</para>
					<mediaobject>
						<imageobject>
							<imagedata fileref="licences&figtype;">
						</imageobject>
						<caption>
							<para>Figure 4.1: Licence dialog box
</para>
						</caption>
					</mediaobject>
					<para>If you agree with the terms of the listed licence agreements, click &apos;I Agree&apos;.
</para>
				</listitem>
				<listitem>
					<para>The main installation dialog box appears (see Figure 4.2).
</para>
					<mediaobject>
						<imageobject>
							<imagedata fileref="maininst&figtype;">
						</imageobject>
						<caption>
							<para>Figure 4.2: Main Alligata Server installation dialog box
</para>
						</caption>
					</mediaobject>
					<para>
						<emphasis role="bold">
							<emphasis role="bold">Note:</emphasis>
						</emphasis> the Alligata Server installation program detects whether each item is <interface moreinfo="none">already</interface> installed on your system. Items already installed do not appear in the installation dialog box. For example, if your computer already contains an installation of the Apache server, the option &apos;Apache Web server&apos; will not appear in the dialog box.
</para>
					<para>In the dialog box, select the items you want to install. See Figure 4.3 for an explanation of the options in the installation dialog box.
</para>
					<variablelist>
						<title>Figure 4.3(a) Global Options
</title>
						<varlistentry>
							<term>
								<guilabel moreinfo="none">Install path
</guilabel>
							</term>
							<listitem>
								<para>Shows the directory into which the Alligata Server program files are installed. Defaults to <filename moreinfo="none">/usr/share/alligata</filename> in Linux, and <filename moreinfo="none">/opt/TGLBallig</filename> in Solaris. The install path cannot be changed.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<guilabel moreinfo="none">Binary directory
</guilabel>
							</term>
							<listitem>
								<para>Shows the directory into which the Alligata Server&apos;s binary files are installed. Defaults to <filename moreinfo="none">/usr/bin</filename>, and cannot be changed.
</para>
							</listitem>
						</varlistentry>
					</variablelist>
					<variablelist>
						<title>Figure 4.3(b) Installation Options
</title>
						<varlistentry>
							<term>
								<guilabel moreinfo="none">Alligata Gateway (Kannel core)
</guilabel>
							</term>
							<listitem>
								<para>Installs the Alligata Server on the current computer, including the Bearer Box, one WAP Box and one SMS Box. If you want to install extra WAP and SMS Boxes on other computers, see Section 6.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<guilabel moreinfo="none">Start the Bearer Box at boot
</guilabel>
							</term>
							<listitem>
								<para>If selected, causes the Alligata Server&apos;s Bearer Box to be started automatically every time the computer is booted.
</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>
								<guilabel moreinfo="none">Start the WAP Box at boot