arch.xml

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

<sect1>
<title>Requirements</title>

	<para>This section lists the requirements of the gateway and
	its design.</para>

	<para>The gateway must be able to share load between several
	hosts. This is also necessary for fault tolerance.</para>

	<para>The gateway needs to be able to serve hundreds of concurrent
	users on a PC with a 400 MHz Pentium CPU, 128 MB of memory,
	10 Mbit/s network interface.</para>
	
	<para>The gateway needs to be able to serve thousands of
	concurrent users on reasonably priced hardware: less than ten
	PCs with high-end Intel CPUs, 128 MB of memory, fast network
	interfaces. It needs to be scalable to even higher levels of
	performance by adding more hardware (meaning that there can't
	be a single bottleneck that prevents more users from being
	served).</para>

	<para>If one of the hosts running the gateway crashes (or the
	gateway component running on that host crashes), the rest of the
	gateway must continue to work. If the crashed component recovers,
	the rest of the gateway needs to start using it again.	Likewise,
	for load balancing, new components must be able to connect to the
	rest of the gateway while running.  Sessions and transactions that
	were running on the crashed component may be terminated, i.e.,
	it is not necessary to migrate them to another component.  </para>
	
	<para>The architecture design needs to be simple. We have
	limited resources, and it is simply not realistic to assume
	that a complicated design is implementable quickly. We can assume
	that performance is adequate as long as no single bottleneck
	exists in the design.</para>
	
	<para>The gateway needs to support both WAP and SMS services.
	New bearers and transport protocols must be simple to add.</para>


</sect1>


<sect1>
<title>Gateway architecture</title>
  
	<highlights>
	<para>This section explains the gateway architecture. It
	gives requirements in more detail for perfomance, scalability,
	reliability, and simplicity of implementation and adding new
	boxes at run time.  It covers the division of gateway duties to
	processes (bearer, wap, and sms boxes), and explains the duties
	of each process. It covers interprocess communication between
	the different boxes, and covers gateway-level communication
	issues such as heartbeats. It should probably cover the different
	approaches to the design that were considered, and give the
	reasons for major (and some minor) design decisions.</para>
	</highlights>
	
<sect2>
<title>External interfaces of the gateway</title>

	<para>The gateway has interfaces to three external agents:
	
	<itemizedlist>

	<listitem><para>SMS centers, using various protocols.
	</para></listitem>

	<listitem><para>HTTP servers, to fetch WAP and SMS content and to 
        push WAP Content. The pull protocol is HTTP, push PAP.
	</para></listitem>

	<listitem><para>WAP phones, implementing the WAP protocol stack and
        (for push) WAP Push client.
	</para></listitem>

	</itemizedlist>
	
	</para>
	
	<figure>
	<title>External interfaces of Kannel</title>
	<graphic fileref="external-interfaces#FIGTYPE#"></graphic>
	</figure>
	
	<para>There are several vendors of SMS centers and most of them
	use a vendor specific protocol. The protocols are fairly similar
	in spirit, but the details of course differ. The differences
	are not relevant to this document, though. The protocols essentially
	follow the following pattern:
	
	<itemizedlist>
	
	<listitem><para>Client logs into the SMS center.
	</para></listitem>
	
	<listitem><para>When an SMS message from a phone arrives,
	the SMS center sends it. The client is expected to acknowledge
	it.
	</para></listitem>
	
	<listitem><para>When the client wants to send an SMS message,
	it sends a request, and the SMS center acknowledges it.
	</para></listitem>
	
	<listitem><para>When the client is done, it logs out.
	</para></listitem>
	
	</itemizedlist>
	
	</para>
	
	<para>The various SMS center protocols are implemented using
	somewhat different approaches within Kannel, but each
	implementation uses the same interface towards the rest of
	Kannel. This simplifies the rest of Kannel.</para>
	
	<para>Each SMS center account is bought from a mobile operator.
	Each account is assigned a number to which SMS messages are sent,
	and which typically also appears as the sender number for messages
	sent via that account. (Some connections will allow the account
	user to set the sender number, though.) There can usually be
	only one connection to an account at a time.  This restricts
	Kannel's design somewhat. Multiple concurrent connections would
	allow for higher performance and reliability.</para>
	
	<para>The HTTP protocol is a fairly pure request-response
	protocol.  The client connects to the server, sends a request,
	and then the server responds and this completes the transaction.
	Multiple requests may be done over the same connection, for
	performance, but the basic flavor of the protocol is still
	the same.</para>
	
	<para>The WAP protocol stack and WAP Push have already been briefly 
        described above.</para>
	
	<para>In order to achieve maximum throughput, Kannel needs to
	be able to communicate with each external agent independently
	from each other, i.e, by multitasking internally. For example,
	it is not good enough to read one request via SMS or WAP, fetch
	the requested content via HTTP, send the content to whoever
	requested it, and only then read the next request. This might be
	fast enough, if the HTTP servers were extremely fast, but they are
	not. Each HTTP transaction can potentially take an indeterminate
	time, without failing, and Kannel must not let one slow request
	prevent every other client from getting service.</para>
	
	<para>What Kannel needs to do, then, is read requests from each
	external interface as fast as possible, and keep them in an
	internal queue. Then it needs to make the HTTP requests for the
	contents as fast as possible, and then send the responses back
	to the requesters. Depending on how fast the HTTP requests take,
	the responses will be sent to the requesters in different
	orders. Things needs to be designed so that this works.</para>
	
	<para>There is a potential reliability problem in this kind of
	design: if Kannel reads many requests into an internal queue,
	and crashes, the requests will be lost. This can be expensive
	to the clients, if they use SMS (whether for SMS based
	services or for WAP), because each SMS message costs money
	when it is received by Kannel, not when Kannel sends the 
	response. Ideally, Kannel should keep the list in persistent
	memory (on disk), but it does not do so at the moment, because
	of implementation complexities.</para>

</sect2>

<sect2>
<title>Division of duties to processes: the boxes</title>

	<para>Kannel divides its various duties into three different
	kinds of processes, called boxes,
	
		<footnote><para><emphasis>Box</emphasis> seemed like
		a nice, non-technical term that should be understandable
		for marketing people, specially if each box is run on
		its own host. In this case, each Kannel box corresponds
		to a physical box, which should be clear enough.</para>
		</footnote>
	
	mostly based on what kinds of external
	agents it needs to interact with:
	
	<itemizedlist>

	<listitem><para>The <glossterm>bearerbox</glossterm> implements
	the bearer level of WAP (the WDP layer). As part of this, it
	connects to the SMS centers. Kannel currently implements SMS only 
        as a WAP push bearer. When it does this fully, its SMS gateway
	functionality will have to interact with the WDP layer: it
	needs to be possible to use a single SMS center connection
	for both textual SMS based services and as a WAP bearer.
	</para></listitem>

	<listitem><para>The <glossterm>smsbox</glossterm> implements
	the rest of the SMS gateway functionality. It receives textual
	SMS messages from the bearerbox, and interprets them as
	service requests, and responds to them in the appropriate
	way.
	</para></listitem>

	<listitem><para>The <glossterm>wapbox</glossterm> implements 
        WAP protocol stack and WAP Push (an application level protocol). 
        If wapbox is used for pushing, it is called <glossterm> Push
        Proxy Gateway</glossterm> or <glossterm>PPG</glossterm> Another
        term for fetching data is <glossterm>pulling</glossterm> For
        Kannel box structure for pulling, see <xref linkend="pull-boxes">,
        and for pushing, see <xref linkend="push-boxes">.
	</para></listitem>

	</itemizedlist>
	
	</para>
	
	<figure id="pull-boxes">
	<title>Boxes of pull Kannel</title>
	<graphic fileref="kannel-boxes#FIGTYPE#"></graphic>
	</figure>
	
	<para>There can be only one bearerbox, but any number of smsboxes
	and wapboxes. Duplicating the bearerbox is troublesome. If there
	were multiple bearerboxes, they would still have to be known
	by the same IP number for WAP phones, which needs help from
	network routers. Also, each SMS center can only be connected
	to by one client. While it would be possible to have each SMS
	center served by a different process, this has been deemed not
	to give enough extra reliability or scalability to warrant the
	complexity.</para>
	
	<para>Having multiple smsboxes or wapboxes can be beneficial
	when the load is very high. Although the processing requirements
	as such are fairly low per request, network bandwidth from a
	single machine, or at least operating system limits regarding
	the number of concurrent network connections are easier to
	work around with multiple processes, which can, if necessary,
	be spread over several hosts.</para>
	
	<para>Each box is internally multithreaded. For example,
	in the bearerbox, each SMS center connection is handled by a
	separate thread. The thread structures in each box are fairly
	static: the threads are mostly spawned at startup, instead of
	spawning a new one for each message. </para>

        <figure id="push-boxes">
	<title>Boxes of push Kannel</title>
	<graphic fileref="kannel-push-boxes#FIGTYPE#"></graphic>
	</figure>
	
</sect2>

<sect2>
<title>Making sure things are working: heartbeats</title>

	<para>In addition to shuffling packets between the phones
	(directly or via SMS centers) and the other boxes, also keeps
	track of the <glossterm>heartbeat</glossterm> of each box. Each
	box sends a heartbeat message, essentially saying `I am still
	alive', and the bearerbox will keep track of when each box
	has sent it last. If a box stops sending heartbeat messages
	for too long a time, the bearerbox will close the connection
	to it.</para>
	
	<para>A parameter to the hearbeat message is the <glossterm>load
	factor</glossterm> of the box. The bearerbox uses this to decide
	which box it should send each package to. If all boxes were
	alike, a simple round-robin system would usually work, but this
	is not something the bearerbox can assume.</para>

</sect2>

</sect1>

<sect1>
<title>The Bearer Box</title>
  
	<highlights>
	<para>This section explain how the bearer box works: its internal
	architecture with messages, message queues, thread structure,
	heartbeats inside the box, and how communication between internal
	and external modules happens.</para>
	</highlights>
	
    <para>At the moment, the bearerbox implements only UDP as a bearer for
    the WAP protocol stack. In the future, it will support SMS messages
    as well. The bearerbox already implements the necessary SMS center
    connections, but they are used for SMS gateway functionality only,
    and are thus ignored for this thesis. (This is true in spite of an
    implemented WAP Push. Using SMS as a pull bearer requires reassembly
    of SMS messages and routing them to one of wapboxes.)
    
	<footnote><para>Once the thesis is submitted to the university,
	descriptions of the SMS gateway functionality will be
	added.</para></footnote>
	
    </para>

    <para>The bearerbox