hwelte
/
mbuni
1
0
Fork 0
Code Releases Activity
mbuni/mbuni/doc/userguide.shtml

1803 lines
53 KiB
Plaintext
Raw Blame History

<!-- when on site, user #include virtual="header.html" -->
<!-- otherwise we use this: -->
<!-- begin header -->
<title>Mbuni: Open Source MMS Gateway - User documentation</title>
<meta name="author" content="info@mbuni.org" />
<meta name="Description" content="Open Source MMS Gateway" />
<meta name="robots" content="ALL" />
<style type="text/css">
<!--
H1 {font-family:Geneva,Verdana,Book Antiqua,Cochin,Calisto MT;color:#000000;}
H2 {font-family:Geneva,Verdana,Book Antiqua,Cochin,Calisto MT,Verdana;color:#000000;}
H3 {font-family:Geneva,Verdana,Book Antiqua,Cochin,Calisto MT,Verdana;color:#000000;}
H4 {font-family:Geneva,Verdana,Book Antiqua,Cochin,Calisto MT,Verdana;color:#000000;}
body {font-family:Geneva,Verdana,Book Antiqua,Cochin,Calisto MT,Verdana;color:#000000;}
a:link {text-decoration:underline;color:#0000bb;}
a:visited{text-decoration:underline;color:#bb0000;}
a:active {text-decoration:underline;color:#bbbbbb;}
a:hover {text-decoration:underline;color:#bbbbbb;}
-->
</style>
</head>
<body topmargin="0" leftmargin="0" rightmargin="0"
marginwidth="0" marginheight="0">
<h1>Mbuni: Open Source MMS Gateway</h1>
<!-- end header -->
<H2><!--TableOfContentsAnchor:Begin--><A NAME="Section_.1"></A><!--TableOfContentsAnchor:End-->User Guide</H2>
This document describes the installation and usage of the MMS Gateway.
<h4>Table of Contents</h4>
<!--TableOfContents:Begin-->
<UL>
<LI><A HREF="#Section_.1.1">Chapter 1: Introduction</A>
<UL>
<LI><A HREF="#Section_.1.1.1">Overview of MMS</A></LI>
<LI><A HREF="#Section_.1.1.2">Features</A></LI>
<LI><A HREF="#Section_.1.1.3">Requirements</A></LI>
</UL></LI>
<LI><A HREF="#Section_.1.2">Chapter 2: Installing The Gateway</A><UL>
<LI><A HREF="#Section_.1.2.1">Patching and Installing Kannel</A></LI>
<LI><A HREF="#Section_.1.2.2">Installing Mbuni MMS Gateway</A></LI>
<LI><A HREF="#Section_.1.2.3">Installing Required Components</A></LI>
</UL></LI>
<LI><A HREF="#Section_.1.3">Chapter 3: Running the Gateway</A><UL>
<LI><A HREF="#Section_.1.3.1">General Configuration File</A></LI>
<LI><A HREF="#mm7">MM7 Configuration</A></LI>
<LI><A HREF="#mm4">MM4 Configuration File</A></LI>
</UL></LI>
<LI><A HREF="#Section_.1.4">Chapter 4: Gateway Architecture</A><UL>
<LI><A HREF="#Section_.1.4.1">MMS Proxy</A></LI>
<LI><A HREF="#Section_.1.4.2">MMS Relay</A></LI>
<LI><A HREF="#Section_.1.4.4">SMTP/Mail Interface</A></LI>
<LI><A HREF="#Section_.1.4.5">Utilities</A></LI>
</UL></LI>
<LI><A HREF="#Section_.1.5">Chapter 5: Tips & Tricks</A><UL>
<LI><A HREF="#Section_.1.5.1">Passing MSISDNs to Mbuni</A></LI>
<LI><A HREF="#Section_.1.5.2"> Sample Kannel WAP configuration</A></LI>
</UL>
<LI><A HREF="#Section_.1.6">Chapter 6: Log Files</A></LI></UL>
</UL>
<!--TableOfContents:End-->
<br>
<H3><!--TableOfContentsAnchor:Begin--><A NAME="Section_.1.1"></A><!--TableOfContentsAnchor:End-->Chapter 1: Introduction</H3>
<p>
This chapter provides an overview of MMS
(short for Multimedia Messaging Service) and the Mbuni MMS Gateway.
</p>
<p>MMS offers mobile
users enhanced messaging capabilities like the ability to send pictures and
sound from a cell phone. It is generally considered the natural successor to
the very popular SMS service.</p>
<p>MMS usage has
continued to grow since introduction, and it is expected that projects
such as Mbuni should further boost the adoption of MMS and its
explosion.
</p>
<p>
The Mbuni Project attempts to provide that
little bit of boost to MMS adoption/growth, by providing a crucial part of the
MMS infrastructure in the form of a fully-fledged Open Source MMS Gateway (more
commonly called a MMS Centre).</p>
<p>Mbuni aims to
support all the major MMS interfaces, including phone-to-phone (so-called MM1
interface), phone-to-email (MM3), inter-MMSC (MM4) and MMS VAS
(MM7). The
current release fully supports the MM1, MM3 and MM7 interfaces, and provides
rudimentary support for the MM4 interface. This version also supports
network-side MMBox storage and transactions as specified in the OMA
MMS v1.2 specification. </p>
<p>Mbuni is
inspired, in part by the Kannel project, and utilises Kannel's GWLIB and WAP
libraries. Kannel provides
well-designed, simple interfaces for management of octet strings, lists,
threads, servers, etc, and a certified WAP implementation. This made
it a natural choice for Mbuni, rather than re-inventing the wheel.</p>
<H4><!--TableOfContentsAnchor:Begin--><A NAME="Section_.1.1.1"></A><!--TableOfContentsAnchor:End-->Overview of MMS</H4>
<p>The Multimedia
Messaging Service (MMS), is intended to provide a rich set of content to
subscribers (pictures, audio, games, etc). It supports both sending
and receiving of rich content by
properly enabled client devices. MMS is a non-real-time delivery service, much
like SMS or email. The service utilises a store-and-forward usage model. </p>
<p> MMS is designed to be transported
largely over IP rather than traditional GSM (SS7) networks. It is also designed
to interoperate with other IP services such as email and WAP. In fact, MMS
messages are typically transported over WAP, and are encoded using WAP MIME
formats. </p>
<p> The MMS Gateway acts as the
message-switching device in the MMS architecture. The general architecture is
shown below.</p>
<center>
<img src="images/mmsgw.png" width="430" height="362">
</center>
<p >The elements
shown in the figure can be summarised as follows:</p>
<ul>
<li><b>MMS
Client: </b>A device through
which the user receives or sends multimedia messages. This might be a phone or
a PC-based MMS client. The Client sends messages to and receives messages from
the Gateway using WAP/HTTP as transport.
<li><b>MMS
Gateway:</b> Switches
messages between different MMS clients and between MMS and Email. The Gateway
may also interface with other gateways to exchange messages destined for
foreign networks.
<li><b>MMS
Server:</b> This component
typically providers persistent storage of messages on the network. Typically
users can access stored messages via a web interface.
<li><b>Other MMS
Systems:</b>Other systems,
such as Third Party MMS systems (e.g. MMS VAS providers) can interface to the
Gateway to receive and send MMS content. The Interface used is termed
MM7.
<li><b>SMSC: </b>The MMS Gateway utilises WAP Push to send
notifications to MMS Clients. These are typically sent using SMS as the bearer
service, hence the need for a link to a Short Message Service Centre.
</ul>
<p>Typically, the
message cycle begins with a user sending a multimedia message (MM) via the MMS
client. The client must be configured for MMS, which includes bearer settings
(i.e. GPRS or GSM/CSD settings), WAP gateway address and MMS Gateway address (a
URL).</p>
<p>An MM is typically a multi-part message
with pictures, sound, text and other media. Each part of the message is
identified by media (MIME) type, name and/or Content ID. When submitting a
message, the MMS client indicates the intended recipient list, but usually not
the sender address, which the MMS Gateway retrieves from the WAP
gateway. Like Email, a single MMS can specify
multiple recipients (MSISDNs and Email addresses), and it is up to the Gateway
to ensure correct delivery to each of the recipients. </p>
<p>When the gateway
receives a message destined for an email address, it typically re-codes the
message as standard MIME and passes it on to an SMTP server for delivery. Email
messages received are similarly re-coded as MMS and forwarded to the relevant
MMS Client.</p>
<p>When the gateway receives a message
destined to MMS Clients in the area served by the gateway, the message is
stored and an MMS notification sent to the recipient via WAP Push. On receipt
of the notification, the client typically fetches the message via a URL
provided in the notification.</p>
<p>When a recipient requests an incoming MM
from the server, it indicates to the server its capabilities for a User Agent
Profile URL. The profile data includes such things as supported media types,
screen size, supported character sets, etc. Typically, the gateway will re-code
the MM to suit the client's capabilities before returning the message. Messages
destined to email may also be re-coded to make them more suitable for email
readers.</p>
<p><![if !supportEmptyParas]>&nbsp;<![endif]></p>
<p>The gateway may also interface with a
subscriber database, which controls message delivery and billing. The
subscriber database will provide such information as which subscribers are
provisioned for MMS, tariffs, etc.</p>
<H4><!--TableOfContentsAnchor:Begin--><A NAME="Section_.1.1.2"></A><!--TableOfContentsAnchor:End-->Features</H4>
<p>Mbuni MMS gateway is a modular software system, designed to
be full-featured, efficient and simple, supporting current generation two-way
multimedia messaging. Feature highlights include:</p>
<ul>
<li> Phone-to-phone messaging
<li> Automatic content adaptation: The server modifies message
content depending on the capabilities of the receiving terminal
<li> Integrated Email-to-MMS and MMS-to-Email gateway
<li> Support for persistent storage of messages for subscribers (MMbox).
<li> Inter-MMSC message exchange (MM4 interface)
<li> Support for MMS Value Added Service Providers using MM7
protocols (SOAP or EAIF).
<li> Support for integration with subscriber database to enable
smart handling of handsets that do not support MMS, handsets not
provisioned, etc.
<li> Support for flexible billing structure through billing/CDR plug-in architecture
<li> Bearer (data) technology neutral: Works with GSM/CSD or GPRS.
</ul>
<p>
The Gateway is designed and tested to conform to Open Mobile Alliance
(OMA), WAP and 3rd Generation Partnership Project (3GPP) MMS standards
including:
<ul>
<li> WAP: 209
<li> OMA: MMS v1.2, UAProf v1.1
<li> 3GPP: TS 23.140
</ul>
</p>
<H4><!--TableOfContentsAnchor:Begin--><A NAME="Section_.1.1.3"></A><!--TableOfContentsAnchor:End-->Requirements</H4>
<p>
Mbuni is being developed on MacOS X and Linux systems using the C programming language. It should compile and run on any similar system.
</p>
<p>
Mbuni utilises some libraries that are part of the Kannel source,
specifically GWLIB and WAP libraries. In order to install Mbuni you
will need to install (a patched) Kannel (and therefore fulfil those
dependencies Mbuni shares with it).
</p>
<a name="required"></a>
The following additional components are required:
<ul>
<li> Libiconv v2.0 or higher is required for character set conversions
<li> Audio conversion tools required by the content adaptation module:
<ul><li> Sox from <a
href="http://sox.sourceforge.net">sox.sourceforge.net</a>
<li> Lame (v3.93 or higher) from <a
href="http://www.mp3dev.org">www.mp3dev.org</a>
<li> Mpg123 from <a href="http://www.mpg123.de">www.mpg123.de</a>
<li> AMR encoder/decoder from <a
href="http://www.3gpp.org">www.3gpp.org</a> (modified, <a href="#install">see below</a>)
</ul>
<li> Image conversion tools required by the content adaptation
module:
<ul>
o ImageMagick from <a href="http://www.imagemagick.org">www.imagemagick.org</a>
</ul>
<li> Mail server such as Postfix (<a href="http://www.postfix.org">www.postfix.org</a>)
<li> You will also need to be running a WAP gateway (we recommend Kannel).
<li> You may optionally need to run an HTTP proxy such as Squid
(<a href="http://squid-cache.org">squid-cache.org</a>), since some
newer phones (e.g. Nokia 6600) do
not send MMS over WAP but directly over HTTP via an HTTP Proxy.
</ul>
Hardware requirements will depend on amount of traffic, required
response times, etc. Keep in mind however that the gateway performs a
lot of heavy media re-coding tasks, particularly during content
adaptation, so you should always err on the side of more rather than
less power.
<a name="install"></a>
<H3><!--TableOfContentsAnchor:Begin--><A NAME="Section_.1.2"></A><!--TableOfContentsAnchor:End-->Chapter 2: Installing The Gateway</H3>
<p>This section
explains the steps required to install the gateway. Currently only installation
from source is provided (binary option coming soon).</p>
<p>
In brief, to install Mbuni, you need to:
<ul>
<li>Download and install required packages (such as libXML, libiconv)
<li>Download, patch and install Kannel v1.4.0
<li>Download and install Mbuni
<li>Download, patch and install the AMR encoder/decoder
<li>Download and install additional <a href="#required">requried</a> packages
</ul>
</p>
<p>The source code
for Mbuni is available for download from the <a
href="http://www.mbuni.org/downloads.shtml">download area</a> of the website
</p>
<H4><!--TableOfContentsAnchor:Begin--><A NAME="Section_.1.2.1"></A><!--TableOfContentsAnchor:End-->Patching and Installing Kannel</H4>
<p>In order to compile the software, you
will first need to download, patch, compile and install Kannel v1.4.0 from <a
href="http://www.kannel.org/download/1.4.0/gateway-1.4.0.tar.bz2">kannel.org</a>:</p>
<p>Unpack the kannel
source files using a command like:</p>
<p><tt>bzip2 -cd
gateway-1.4.0.tar.bz2 | tar xf -</tt></p>
<p>The kannel
sources need to be patched for Mbuni using one of the supplied patch files from
the Mbuni downloads section given above. You can use either one of the patch
files: </p>
<ul>
<li><tt>mbuni-kannel-patch-minimal</tt> has minimal patches to Kannel
for:
<ul>
<li>Support of configuration directives
required by the MMS Gateway in the configuration file format used by
kannel. This is patch to gwlib
<li>Makefile patch so that WAP library
and header files are installed as part of Kannel installation</li>
</ul>
<li ><tt>mbuni-kannel-patch-full</tt> has all the patches above and
patches to Kannel itself to enable it support sending of Over-The-Air
settings using <a
href="http://www.openmobilealliance.org/release_program/cp_v11.html">OMA
Client Provisioning (v1.1) specifications</a>. The
changes have been tested but may of course contain a bug or
two. Since newer phones only support sending of MMS OTA settings
using OMA format, we thought this would be a useful addition.</li>
</ul>
<p>Which patch you
choose is a matter of taste. Apply the patch like this</p>
<p ><tt>cd gateway-1.4.0</tt>
<br>
<tt>patch -p1 &lt; ../mbuni-kannel-patch-full</tt>
</p>
<p >Then proceed to
compile and install Kannel normally:</p>
<p>
<tt>./configure</tt>
<br>
<tt>make install</tt>
</p>
<H4><!--TableOfContentsAnchor:Begin--><A NAME="Section_.1.2.2"></A><!--TableOfContentsAnchor:End-->Installing Mbuni MMS Gateway</H4>
<p>Download and
unzip/tar Mbuni sources in a directory of your choice:</p>
<tt>tar xzf mbuni-<i>version</i>.tgz</tt>
<p>Where <i>version</i> is the verion of Mbuni (e.g. 0.9.8). Compile and
install mbuni as follows:</p>
<p ><tt>cd
mbuni-<i>version</i></tt><br>
<tt>./configure</tt><br>
<tt>make insall</tt>
</p>
<p >If you installed
Kannel in a non-standard location, you will need to supply the location to <tt>configure</tt> using <tt>--with-kannel=<i>kannel_directory</i></tt></p>
<h5>Installing from CVS</h5>
<p> If you want to try out the development version of Mbuni, you can
download it from the CVS on sourceforge.net:</p>
<tt>cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/mbuni login</tt><br>
followed by<br>
<tt> cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/mbuni co -P mbuni</tt><br>
you can then <tt>cd mbuni</tt> and use the <tt>./configure</tt> and
<tt>make install</tt> as above.
<p >Mbuni consists of
3 programs:
<ul>
<li><tt>mmsc/mmsrelay</tt>
<li><tt>mmsc/mmsproxy</tt>
<li><tt>mmsc/mmsfromemail</tt>
</ul>
which are by
default installed in <tt>/usr/local/bin</tt>
</p>
<p ><tt>mmsrelay</tt> is the main relay server. It routes
incoming messages to email, other MMS gateways, MMS clients/handsets,
etc. It also manages routing messages to MMS clients
using WAP Push, sending of delivery reports, etc.
<br><br>
<tt>mmsproxy</tt>
provides the HTTP interface via which messages are
sent and received by MMS clients. <br><br><tt>mmsfromemail </tt>Is
the email2MMS gateway module. All programs must be configured, and the first
three running for the gateway to function smoothly.</p>
<H4><!--TableOfContentsAnchor:Begin--><A NAME="Section_.1.2.3"></A><!--TableOfContentsAnchor:End-->Installing Required Components</H4>
<p>Be sure to install all other required
components as detailed above, otherwise parts of the MMS gateway may not
function correctly. </p>
<p>Mbuni expects that an AMR decoder is installed and can be invoked
as: <br>
<tt>amrdecoder <i>infile outfile</i> </tt>
<br>
to decode an AMR
file to header-less (raw), 16-bit signed, mono, 8kHz audio samples in
the output file. (Input and output files may be '-' for standard input
or output respectively.)</p>
<p>Similarly, it is expected that an AMR encoder
called <tt>amrencoder</tt> exists and can be executed as follows:
<br>
<tt>amrencoder <i>mode infile outfile</i></tt>
<br>and convert raw, 16-bit signed, 8kHz
mono audio samples in the input file to AMR using the supplied
encoding mode.
<br>
<br>
For the AMR encoder/decoder, we have adapted the sample provided on the 3GPP
website. Follow the instructions below to install it:<br>
<ul>
<li>Download the AMR encoder/decoder source from <a
href="http://www.3gpp.org/ftp/Specs/archive/26_series/26.104/26104-520.zip">here</a>
<li>unzip/unpack the zip file, and unpack the source within:<br>
<tt>unzip 26104-520.zip</tt><br>
<tt>mkdir amr</tt><br>
<tt>cd amr</tt><br>
<tt>unzip ../26104-520_ANSI_C_source_code.zip</tt><br>
<li>Download the AMR code patch from the mbuni.org <a href="downloads.shtml">download section</a> and apply as follows:<br>
<tt>patch -p1 &lt; ../mbuni-amr-patch</tt>
<li> You should then compile and install the AMR encoder/decoder as follows:<br>
<tt>make -f makefile.gcc</tt><br>
<tt>cp -f amrdecoder amrencoder /usr/local/bin</tt>
</ul>
This AMR encoder
is not very efficient but it works (which is important!)</p>
<H3><!--TableOfContentsAnchor:Begin--><A NAME="Section_.1.3"></A><!--TableOfContentsAnchor:End-->Chapter 3: Running the Gateway</H3>
<p>To run the gateway, you must run the
two programs listed above (<tt>mmsrelay</tt>
and <tt>mmsproxy</tt>). <tt>mmsfromemail</tt>
should be called from your MTA (SMTP Mailer) to convert
and deliver an MMS from an email sender. The order in which they are started
is unimportant. They expect the configuration file to be passed as the last
argument on the command line (default is <tt>mmsc.conf</tt>). The
configuration file controls most aspects of
the operation of the gateway. </p>
<H4><!--TableOfContentsAnchor:Begin--><A
NAME="Section_.1.3.1"></A><!--TableOfContentsAnchor:End-->General Configuration File</H4>
<p >The configuration file format is the same as that used
by Kannel. The configuration file consists of groups of configuration
variables. Groups are separated by empty lines, each variable is defined on its
own line. Each group begins with the group name. Comments are lines that begin
with a hash (#) and are ignored.
<br><br>
A
variable definition line has the name of the variable, an equals sign (=) and
the value of the variable. The name of the variable can contain any characters
except white space and equals. The value of the variable is a string, with or
without quotation marks (&quot;) around it. Quotation marks are needed if the value
begins or ends with white space or contains special characters. Normal C escape
character syntax works inside quotation marks.</p>
<p >The variable <i>group</i> marks the
beginning of a new group with the given name.</p>
<p >The core group is
<i>core</i> and defines the log file location, log level (amount of debugging
information &#8211; the lower the number the more debugging
information), the location of the access log and the HTTP proxy host/port if any. (HTTP proxy host/port
is specified using the exact same parameters as used by Kannel.)
<br>
<br>
<tt>
group =
core<br>
log-file
= log/mmsgw.log<br>
log-level
= 0
<br>
access-log = log/access.log<br>
</tt>
</p>
<p>
This should be
followed by the main MMS gateway configuration group (<i>mmsbox</i>).
<br>
<br>
<tt>
group =
mmsbox<br>
name =
&quot;My MMSC&quot;<br>
hostname
= ds.co.ug<br>
host-alias
= mmsc<br>
local-mmsc-domains=
mbuni.org,service.com<br>
local-prefixes
= 075;+25675;25675<br>
directory-store
= spool<br>
max-send-threads
= 5<br>
send-mail-prog
= /usr/sbin/sendmail -f '%f' '%t'<br>
...<br>
</tt>
</p>
<p >The table below
lists all the configuration directives</p>
<table border=0 cellspacing=2 cellpadding=1 >
<tr>
<td valign=top>
<b>Variable
Name</b>
&nbsp; &nbsp;</td>
<td valign=top>
<b>Type</b>
&nbsp; &nbsp;</td>
<td valign=top>
<b>Description</b>
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top><tt>group </tt>
&nbsp; &nbsp;</td>
<td valign=top>
mmsbox
&nbsp; &nbsp;</td>
<td valign=top>
Mandatory
variable
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top ><tt>name </tt>
&nbsp; &nbsp;</td>
<td valign=top >
string
&nbsp; &nbsp;</td>
<td valign=top>
User-friendly
name for the Gateway, used in notices, etc
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top ><tt>hostname
</tt>
&nbsp; &nbsp;</td>
<td valign=top >
string
&nbsp; &nbsp;</td>
<td valign=top >
Local hostname.
This is added as a qualifier to the sender address when MMS is forwarded to
Email or to a foreign MMSC via SMTP. Defaults to <tt>localhost</tt>
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top ><tt>host-alias
</tt>
&nbsp; &nbsp;</td>
<td valign=top>
string
&nbsp; &nbsp;</td>
<td valign=top s>
Short form of
hostname. This is used in generating message IDs. It is also used to
generate the message retrieval URL (sent as part of the MMS
notification): For instance if you have this as <tt>mmsc</tt> then
the retrieval URL will have the form
<tt>http://mmsc/<i>msgtoken</i></tt> (no port is added). Be sure to
keep this value short as some handsets do not like long URLs in MMS
notifications. If you do not supply a host alias, the gateway will create a long form URL (http://<i>hostname:port/msgtoken</i>) when it sends notifications
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>local-mmsc-domains</tt>
&nbsp; &nbsp;</td>
<td valign=top >
List of
Internet domains (comma separated)
&nbsp; &nbsp;</td>
<td valign=top >
A list of
internet domains that should be considered local to this MMS gateway. Email
or MMS messages received destined to these domains should be treated as local
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top ><tt>local-prefixes</tt>
&nbsp; &nbsp;</td>
<td valign=top >
Number
prefix list
&nbsp; &nbsp;</td>
<td valign=top >
Number prefixes
that should be considered local. Messages to numbers that match these
prefixes will be delivered locally (via <tt>mmsrelay</tt>)
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>storage-directory
</tt>
&nbsp; &nbsp;</td>
<td valign=top >
Directory name
(string)
&nbsp; &nbsp;</td>
<td valign=top >
Directory where Mbuni creates message queues, MMBoxes, and the
User Agent profiles cache. Mbuni creates a set of sub-directories in here
for each function
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>max-send-threads</tt>
&nbsp; &nbsp;</td>
<td valign=top >
Number
&nbsp; &nbsp;</td>
<td valign=top >
How many queue
processing threads to start. A higher value means messages get delivered
faster.
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>send-mail-prog</tt>
&nbsp; &nbsp;</td>
<td valign=top >
String
&nbsp; &nbsp;</td>
<td valign=top >
Command to use for sending email messages
(MMS-to-email or to foreign MMS gateways via SMTP). This command can include variables: %f
&#8211; replaced with the message from address, %t &#8211; replaced with the
recipient address (RFC 822 compliant), %s &#8211; the message subject, %m
&#8211; the message ID
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>unified-prefix
&nbsp; &nbsp;</td>
<td valign=top >
Number list
&nbsp; &nbsp;</td>
<td valign=top >
A string to
unify received phone numbers, so that routing works correctly. Format is that
first comes the unified prefix,
then all prefixes which are replaced by the unified prefix, separated with
comma (','). For example &quot;+256,000256,0;+,000&quot; should
ensure correct UG prefixes. If
there are several unified prefixes, separate their rules with semicolon (';')
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>maximum-send-attempts
</tt>
&nbsp; &nbsp;</td>
<td valign=top >
integer
&nbsp; &nbsp;</td>
<td valign=top >
Maximum number
of attempts gateway must make to deliver message before giving up (e.g.
mobile phone is off, email domain is unavailable)
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>default-message-expiry</tt>
&nbsp; &nbsp;</td>
<td valign=top >
Integer
&nbsp; &nbsp;</td>
<td valign=top >
Default number
of seconds in which message expires and is purged from queue (if not yet
delivered). This figure is overridden by whatever is in the message.
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>queue-run-interval</tt>
&nbsp; &nbsp;</td>
<td valign=top >
Real
&nbsp; &nbsp;</td>
<td valign=top >
How many
seconds between each queue run
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>send-attempt-back-off</tt>
&nbsp; &nbsp;</td>
<td valign=top >
Integer
&nbsp; &nbsp;</td>
<td valign=top >
<tt>mmsrelay</tt> uses a form of exponential back-off
when sending notifications to MMS clients. This figure provides the starting
back-off value (in seconds).
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>sendsms-url</tt>
&nbsp; &nbsp;</td>
<td valign=top >
String
&nbsp; &nbsp;</td>
<td valign=top >
URL of the
service through which SMS can be sent to a mobile subscriber (e.g. for WAP
Push). It is expected that this url expects/supports Kannel-style send-sms
parameters (udh, from, to, text, etc.)
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>sendsms-username</tt>
&nbsp; &nbsp;</td>
<td valign=top >
String
&nbsp; &nbsp;</td>
<td valign=top >
Username to
pass (for authentication) to send-sms URL
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>sendsms-password</tt>
&nbsp; &nbsp;</td>
<td valign=top >
String
&nbsp; &nbsp;</td>
<td valign=top >
Password to
pass (for authentication) to send-sms URL
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>sendsms-global-sender</tt>
&nbsp; &nbsp;</td>
<td valign=top >
String
&nbsp; &nbsp;</td>
<td valign=top >
Optional sender
(<i>to</i> field) to use in send sms url
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>mms-port</tt>
&nbsp; &nbsp;</td>
<td valign=top >
Integer
&nbsp; &nbsp;</td>
<td valign=top >
Port on which <tt>mmsproxy</tt> listens for MMS messages from MMS
clients (Default
is 8191).
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>mm7-port</tt>
&nbsp; &nbsp;</td>
<td valign=top >
Integer
&nbsp; &nbsp;</td>
<td valign=top >
Port on which <tt>mmsproxy</tt> listens for MM7 requests from Value
Added Services providers. If this port is not supplied, the MM7
sub-system is not started.
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>allow-ip</tt>
&nbsp; &nbsp;</td>
<td valign=top >
List of IP
addresses
&nbsp; &nbsp;</td>
<td valign=top >
List of IP
addresses of hosts allowed to use/access the MMS Port (above). You can use
this for instance to insist that only connections coming via a known/trusted
WAP gateway are serviced. Leave out to allow all machines to connect.
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>mms-client-msisdn-header</tt>
&nbsp; &nbsp;</td>
<td valign=top >
String
&nbsp; &nbsp;</td>
<td valign=top >
Name of HTTP
Header sent/inserted by WAP gateway as part of MMS request to indicate MSISDN
of sender. Note that typically the MMS client does not indicate its MSISDN in
the MMS message, it is up to the gateway to discover this and insert it. We
rely on the WAP gateway to provide the MSISDN as an HTTP request header
(default header name is <tt>X-WAP-Network-Client-MSISDN</tt>)
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>mms-client-ip-header</tt>
&nbsp; &nbsp;</td>
<td valign=top >
String
&nbsp; &nbsp;</td>
<td valign=top >
Name of HTTP
Header sent/inserted by WAP gateway as part of MMS request to
indicate IP Address
of sender. Similar to the above, if the MSISDN is not set, then we
assume that the client is identified by IP address, which we extract
from the request headers (using this header). Default header name
is <tt>X-WAP-Network-Client-IP</tt>. If the header is not
found, we assume the IP address as seen by Mbuni's MM1 interface.
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>allow-ip-type</tt>
&nbsp; &nbsp;</td>
<td valign=top >
Boolean
&nbsp; &nbsp;</td>
<td valign=top >
Set this to false to prevent Mbuni accepting and processing messages from
senders identified by IP address (i.e. not by MSISDN). Default: True.
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>optimize-notification-size</tt>
&nbsp; &nbsp;</td>
<td valign=top >
Boolean
&nbsp; &nbsp;</td>
<td valign=top >
Set this to true make Mbuni attempt to squeeze MMS notifications
in one WAP Push SMS, by leaving out subject and sender
fields. Default: false
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>content-adaptation</tt>
&nbsp; &nbsp;</td>
<td valign=top >
Boolean
&nbsp; &nbsp;</td>
<td valign=top >
Set this to false to turn off content adaptation in Mbuni. This will
cause the MMSC to ignore client capabilities when sending messages,
and could cause problems so beware! Default: true
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>email2mms-relay-prefixes</tt>
&nbsp; &nbsp;</td>
<td valign=top >
Number list
&nbsp; &nbsp;</td>
<td valign=top >
When MMS is received
via SMTP, the gateway needs to determine whether it is for a local or a
foreign recipient. To determine if the recipient is local recipient, we use
the <tt>local-prefixes</tt> setting. If the recipient is not local,
the message should be forwarded on to the relevant foreign MMS gateway, only
if the recipient number matches one of the prefixes in this comma-separated
list.
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>billing-library</tt>
&nbsp; &nbsp;</td>
<td valign=top >
String
&nbsp; &nbsp;</td>
<td valign=top >
Optional
library containing billing and CDR functions. This library is loaded at
runtime and should contain functions to be called to effect billing and CDR
generation. See <tt>mms_billing.h</tt> for details.
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>billing-module-parameters</tt>
&nbsp; &nbsp;</td>
<td valign=top >
String
&nbsp; &nbsp;</td>
<td valign=top >
Parameters to
pass to the billing module specified above when it is loaded. This is a
generic string whose interpretation is entirely up to the module.
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>resolver-library</tt>
&nbsp; &nbsp;</td>
<td valign=top >
String
&nbsp; &nbsp;</td>
<td valign=top >
Optional
library containing functions for resolving recipient MSISDN to hostname
of Proxy-Relay that should handle the message. Supplying this libary
over-rides the <tt>local-prefixes</tt> setting given above. If the
Proxy-Relay hostname returned by the module is the hostname of the
local MMSC, then the recipient is considered local. See
<tt>mms_resolve.h</tt> for details.
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>resolver-module-parameters</tt>
&nbsp; &nbsp;</td>
<td valign=top >
String
&nbsp; &nbsp;</td>
<td valign=top >
Parameters to
pass to the Resolver module specified above when it is loaded. This is a
generic string whose interpretation is entirely up to the module.
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>detokenizer-library</tt>
&nbsp; &nbsp;</td>
<td valign=top >
String
&nbsp; &nbsp;</td>
<td valign=top >
Optional
library containing functions for finding MSISDN from request URL
sent by client. The last part of URL is treated as a string that is
interpreted by the library and transformed into an MSISDN. This libary
is only a fall-back in case the default sender address resolution
fails. See
<tt>mms_detokenize.h</tt> for details.
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>detokenizer-module-parameters</tt>
&nbsp; &nbsp;</td>
<td valign=top >
String
&nbsp; &nbsp;</td>
<td valign=top >
Parameters to
pass to the De-tokenizer module specified above when it is loaded. This is a
generic string whose interpretation is entirely up to the module.
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>prov-server-notify-script</tt>
&nbsp; &nbsp;</td>
<td valign=top >
String
&nbsp; &nbsp;</td>
<td valign=top >
Subscriber
database interface script 1: This script will be called by the gateway to
notify the subscriber database of per-subscriber events such as when a
subscriber sends a message, successfully fetches a message, etc. This script
is called with 2-3 arguments. Argument 1 is one of fetched, sent,
failedfetch; argument 2 is the subscriber MSISDN; argument 3, in case of a
failed fetch provides a description of the error (e.g. message expired).
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>prov-server-sub-status-script</tt>
&nbsp; &nbsp;</td>
<td valign=top >
string
&nbsp; &nbsp;</td>
<td valign=top >
Subscriber
database interface script 2: This script is called
by <tt>mmsrelay</tt> to determine whether the recipient's
device supports MMS. The script should exit with a value of 0 to indicate
that the device does not support receipt of MMS notifications; 1 to indicate
that the device supports MMS; -1 if the subscriber is not known or not
provisioned for MMS. The return value determines how
<tt>mmsrelay</tt> will deliver the message (see below).
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top>
<tt>notify-unprovisioned</tt>
&nbsp; &nbsp;</td>
<td valign=top >
Boolean
&nbsp; &nbsp;</td>
<td valign=top >
Whether
subscribers who are not provisioned for MMS should receive any notifications
(e.g. SMS) when an MMS message is received for them.
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top>
<tt>mms-notify-text</tt>
&nbsp; &nbsp;</td>
<td valign=top >
String
&nbsp; &nbsp;</td>
<td valign=top >
Message to send
to device that does not support MMS, when a message is received for the user.
This message is sent as plain SMS via the Send SMS URL specified above.
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>mms-notify-unprovisioned-text</tt>
&nbsp; &nbsp;</td>
<td valign=top>
String
&nbsp; &nbsp;</td>
<td valign=top>
Message to send
to devices that are not provisioned for MMS (only if
<tt>notify-unprovisioned</tt> is true).
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>mms-message-too-large-txt</tt>
&nbsp; &nbsp;</td>
<td valign=top >
String
&nbsp; &nbsp;</td>
<td valign=top >
If a device
tries to fetch a message, which during content adaptation is determined to be
too large for the target device (based on capabilities data supplied by the
device), the message is discarded, this text is sent to the device instead as
part of an MMS message.
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>mms-to-email-html</tt>
&nbsp; &nbsp;</td>
<td valign=top >
string
&nbsp; &nbsp;</td>
<td valign=top >
When an MM is
destined for email, we must format it to make it more suitable for email
readers. (For instance, the SMIL part of the MM will make no sense to most email
readers.) The gateway formats
the message as follows: It generates a multi-part MIME message with the main
part being an HTML entity in which MM parts are embedded. The text given here
is tagged at the bottom of the HTML.
&nbsp; &nbsp;</td>
</tr>
<tr>
<td valign=top >
<tt>mms-to-email-txt</tt>
&nbsp; &nbsp;</td>
<td valign=top >
String
&nbsp; &nbsp;</td>
<td valign=top >
This string is
placed in the MMS converted to email as an alternative to the HTML part, for
email clients that do not support HTML.
&nbsp; &nbsp;</td>
</tr>
</table>
<br>
<a name="mm7"></a>
<h4>MM7 Configuration</h4>
<!--- MM7 stuff -->
<p >MMS Value-Added Service Providers (VASPs) are configured using
one or more <i>mms-vasp</i> groups:</p>
<br>
<tt>
group =
mms-vasp<br>
vasp-id = newcorp<br>
type =
soap<br>
short-code
= 100<br>
vasp-username
= newscorp<br>
vasp-password
= news123<br>
vasp-url
= http://example.vasp.com:8080/mm7<br>
mmsc-username
= mymmsc<br>
mmsc-password
= mypass<br>
<br>
</tt>
<br>
<table border=0 cellspacing=2 cellpadding=2 >
<tr>
<td valign=top >
<b>Variable</b>
</td>
<td valign=top >
<b>Type</b>
</td>
<td valign=top >
<b>Description</b>
</td>
</tr>
<tr>
<td valign=top >
<tt>group</tt>
</td>
<td valign=top >
String
</td>
<td valign=top >
Mandatory:
<tt>mms-vasp</tt>
</td>
</tr>
<tr>
<td valign=top >
<tt>vasp-id</tt>
</td>
<td valign=top >
String
</td>
<td valign=top >
User friendly
name
</td>
</tr>
<tr>
<td valign=top >
<tt>type</tt>
</td>
<td valign=top >
String
</td>
<td valign=top >
This should be one of: soap, eaif
</td>
</tr>
<tr>
<td valign=top >
<tt>short-code</tt>
</td>
<td valign=top >
Number
</td>
<td valign=top >
Short number for this VASP: Messages received by Mbuni to this
number are routed to the VASP via MM7.
</td>
</tr>
<tr>
<td valign=top >
<tt>vasp-url</tt>
</td>
<td valign=top >
String
</td>
<td valign=top >
Outgoing messages to the VASP are sent via this URL (using HTTP POST)
</td>
</tr>
<tr>
<td valign=top >
<tt>mmsc-username</tt>
</td>
<td valign=top >
String
</td>
<td valign=top >
Outgoing HTTP authentication: The username Mbuni must use when sending data
to the VASP
</td>
</tr>
<tr>
<td valign=top >
<tt>mmsc-password</tt>
</td>
<td valign=top >
String
</td>
<td valign=top >
Outgoing HTTP authentication: password Mbuni must use when sending data
to the VASP
</td>
</tr>
<tr>
<td valign=top >
<tt>vasp-username</tt>
</td>
<td valign=top >
String
</td>
<td valign=top >
Incoming HTTP authentication: The username used by the VASP to
authenticate itself to Mbuni when sending data
</td>
</tr>
<tr>
<td valign=top >
<tt>vasp-password</tt>
</td>
<td valign=top >
String
</td>
<td valign=top >
Incoming HTTP authentication: The password used by the VASP to
authenticate itself to Mbuni when sending data
to the VASP
</td>
</tr>
</table>
Note that currently only HTTP Basic Authentication Scheme is supported
by Mbuni (for both incoming and out-going requests).
<a name="mm4"></a>
<h4>MM4 Configuration</h4>
<!-- Foreign MMSC stuff -->
<p >Foreign MMS
Gateways are configured using one or more <i>mmsproxy</i> groups:</p>
<br>
<tt>
group =
mmsproxy<br>
name =
&quot;A test mms proxy&quot;<br>
host =
test.com<br>
allowed-prefix
= &quot;075&quot;<br>
denied-prefix
= &quot;077&quot;<br>
<br>
</tt>
<br>
<table border=0 cellspacing=2 cellpadding=2 >
<tr>
<td valign=top >
<b>Variable</b>
</td>
<td valign=top >
<b>Type</b>
</td>
<td valign=top >
<b>Description</b>
</td>
</tr>
<tr>
<td valign=top >
<tt>group</tt>
</td>
<td valign=top >
String
</td>
<td valign=top >
Mandatory:
<tt>mmsproxy</tt>
</td>
</tr>
<tr>
<td valign=top >
<tt>name</tt>
</td>
<td valign=top >
String
</td>
<td valign=top >
User friendly
name
</td>
</tr>
<tr>
<td valign=top >
<tt>host</tt>
</td>
<td valign=top >
String
</td>
<td valign=top >
Fully qualified
domain name
</td>
</tr>
<tr>
<td valign=top >
<tt>allowed-prefix</tt>
</td>
<td valign=top >
Number list
</td>
<td valign=top >
List of
recipient number prefixes that can be delivered via this Proxy
</td>
</tr>
<tr>
<td valign=top >
<tt>denied-prefix</tt>
</td>
<td valign=top >
Number list
</td>
<td valign=top >
List of
recipient number prefixes that cannot be delivered via this proxy
</td>
</tr>
</table>
<p>
When an MM destined to an MSISDN cannot be delivered locally, the
gateway searches the list of Proxies to see if one of them can handle
the message. If one is found, the message is formatted as MIME and
sent via SMTP to the proxy.
</p>
<H3><!--TableOfContentsAnchor:Begin--><A NAME="Section_.1.4"></A><!--TableOfContentsAnchor:End-->Chapter 4: Gateway Architecture</H3>
<p>
In this section we provide an overview of the gateway architecture.
<br>
<br>
As indicated, there are thre components to the gateway: The Relay
(<tt>mmsrelay</tt>), the Proxy
(<tt>mmsproxy</tt>) and SMTP/Email Interface (<tt>mmsfromemail</tt>). We describe the
function of each of these in turn.
</p>
<H4><!--TableOfContentsAnchor:Begin--><A NAME="Section_.1.4.1"></A><!--TableOfContentsAnchor:End-->MMS Proxy</H4>
<p>
This component (<tt>mmsproxy</tt>) is the main point of interaction between the
gateway and MMS clients and VASPs. It provides an HTTP interface through which
clients can send MMS messages. From clients, message types expected on this
interface are typically:
<ul>
<li> Send Request: Used by client to submit an MM to the
gateway. When received, the message is placed in the global queue. If
the client has requested that a copy by saved to the MMbox, this is done.
<li> Forward Request: Used by the client to request the MM to
forward an MM. In this case the MM is resident on the gateway
(e.g. pending fetch by client) and is identified by its URL. The
message is retrieved and placed in the global queue for processing. If
a request to place a copy in the MMbox is indicated, this is done.
<li> Notify Response: Is sent by client as a response to an MM
notification via Wap Push. This message indicates status information
such as whether the client wishes to defer fetching of the message,
etc. If the notification indicates that the message has been fetched,
the message is removed from the queue. If the notification indicates
that retrieval has been deferred, the message is marked so that no
further notifications are sent to the client about this message.
<li> Read receipt: If requested by the sender, a read receipt can
be forwarded via this interface. This is queued for delivery to the
recipient
<li> MMbox Upload/Delete/Search: Upload and deletion to/from the user
MMbox are supported.
<li> MMbox search: A message search request when received is
processed. The proxy takes care to return only as much data as the
client can handle (as indicated by UA profile).
</ul>
All the above messages are sent to the proxy as the body of an HTTP POST request.
Messages are retrieved by supplying the message URL in an HTTP GET
request. When such a request is received, the proxy:
<ol>
<li> Locates the message: From the URL, the proxy can tell if this
is a message in the MMbox or in the in the queue for client-destined messages.
<li> Extracts the User Agent Profile URL from the (HTTP) request
headers. If that is missing, the profile information is built out of
the HTTP Accept headers. The profile URL is passed to the content
adaptation module, which performs various modifications to the MM such
as:
<ul>
<li> Converting images in the MM to a format supported by the client
<li> Scaling images to fit the screen size of the client
<li> Converting audio in the MM to a format supported by the client
<li> Converting text to a supported character set
<li> Removing unsupported content from the MM
</ul>
note that profile data is cached
(in <tt><i>storage-directory</i>/UserAgent_Profiles</tt>) so as not to have to fetch it each time.
<li> The message is then packed and returned to the client as the
result of the HTTP request.
</ol>
<p>
Currently, no MMbox quotas are imposed.
</p>
From VASPs mmsproxy expects and processes:
<ul>
<li>Send Requests: Used to submit messages for onward transmission by
Mbuni
<li> Cancellations: A previously submitted message can be cancelled if
it hasn't yet been routed to the next processor or receiver. (That is,
only messages still in the global queue can be cancelled.) Only the
original submitted can cancel a message.
<li>Replacement: A submitted message can be changed &mdash; the VASP may
supply different content, which will
then replace any content currently in
th queue.
</ul>
<br>
Note that only SOAP MM7 requests are supported at this stage.
<br>
This component must always be running.
</p>
<H4><!--TableOfContentsAnchor:Begin--><A NAME="Section_.1.4.2"></A><!--TableOfContentsAnchor:End-->MMS Relay</H4>
The Relay manages routing of all messages (to phone, email, VASP).
<p>
The Relay watches the global queue for incoming messages (from VASP,
external MMSCs or clients). For each message that arrives
in the queue, the relay:
<ol>
<li> Determines if the message is due for delivery attempt. An
attempt is made to deliver the message as soon as it is received
(deffered delivery requests are honoured however), with
exponential back-off in case of failure.
<li> At the first delivery attempt, a call is made to the billing
module to effect billing and CDR generation. If the billing module
indicates that the sender does not have sufficient credit, the message
is discarded and the sender notified via delivery report.
<li> If the message is due for delivery attempt, the global sender
determines, for each recipient, how to deliver the message:
<ol type="a">
<li> If the message is destined for a local MMS client, the message
is transferred to the mobile/local queue. A copy of the message is
sent (as MIME) to the MMBox host (if one is configured)
<li> If the message is destined for an email user, the message is
re-formatted as MIME, sender and recipient addresses normalised as RFC
822 addresses, and the message passed to the mailer.
<li> If the message is destined for a foreign gateway, it is coded
as MIME and passed to the mailer for delivery via SMTP
<li>If the the message is destined for a VASP (identified by short
code), then it is sent using MM7 protocols to the relevant VASP.
<li> If the message cannot be delivered, the sender is notified.
</ol>
</ol>
</p>
<p>
For messages placed in the mobile/local queue (i.e. those destined to
MSISDNs in the area served by this MMSC or IP-based clients), the
relay performs the following functions:
<ol>
<li> Notification is sent to the recipient client via WAP Push
<li> Delivery of other notifications such as delivery and read
reports to clients via WAP Push
</ol>
SMS is used as the transport for WAP Push messages, if the recipient
is an MSISDN, otherwise UDP is used.
<br>
The Relay maintains a separate queue for messages pending delivery. At
set intervals (see configuration section), it sends notifications to
the recipient. It keeps sending notifications until the message is
fetched or the client indicates that it wishes to defer message
retrieval. A back-off mechanism is utilised to prevent flooding of
notifications.
A message will be removed from the queue if:
<ul>
<li> It expires, either due to expiry period set within the message
being reached or system wide expiry time is reached. (The sender is
notified of expiry if they requested a delivery report)
<li> If the recipient retrieves the message
</ul>
</p>
<p>
<br>
A word about queue management: A simple queue management scheme is
used. Each queue entry consists of two files: The 'q' file (which is
plain text) contains the entry control data
(list of recipients, next delivery attempt time, etc), the 'd' file
contains the message data. This scheme is similar to that used by
popular MTAs. Queue processors mostly operate on the 'q' file, and
use file locking to guard against duplicate delivery, file corruption,
etc.
<br>
See <tt>mms_queue.h</tt> for details.
</p>
<p>
<H4><!--TableOfContentsAnchor:Begin--><A NAME="Section_.1.4.4"></A><!--TableOfContentsAnchor:End-->SMTP/Mail Interface</H4>
The SMTP/Mail interface receives MMS from the MTA and routes them
depending on recipient or sending proxy. Specifically:
<ol>
<li> If the
message is a send request, it is queued to the global queue for
delivery as long as the recipient is permitted via the interface (see
configs)
<li> If the message is a notification (e.g. delivery
report), the interface carries out the necessary action
(e.g. forwarding of receipt or deletion of message from local
queue)
</ol>
<br>
This interface should be invoked from your MTA as follows:<br><br>
<tt>
mmsfromemail -f <i>from_address</i> -t <i>recipient_address</i>
-p <i>sender_mmsc_hostname</i> <i>conf_file</i>
</tt>
<br/>
<br>
Note that no IP-based security is provided at this
interface. It is expected that security measures (e.g. firewalls, etc)
will have been setup to ensure that messages can only reach the MTA
and be handed over to this interface if they are legitimate.
</p>
<p>
<H4><!--TableOfContentsAnchor:Begin--><A
NAME="Section_.1.4.5"></A><!--TableOfContentsAnchor:End-->Utilities</H4>
We plan to add a number of utilities to the gateway. The first of
these is <tt>mmssend</tt>.
<br>
<br>
<tt>mmsssend</tt> can be used to submit (inject) a message into the
global queue. It should be invoked as follows:<br>
<br>
<tt>
mmssend -f <i>from_address</i> -t <i>recipient_list</i> -m
<i>mmsfile</i> [-b] <i>conf_file</i>
</tt>
<br><br>
Notes:
<ul>
<li>the recipient list can be a colon-separated list of multiple
recipients
<li>The MMS file may be binary coded, or MIME. The utility tries to
guess which by inspecting the first byte of the file.
<li>From/To addresses are only used for delivery purposes (so internal
message headers may not be updated
<li>The <tt>-b</tt> flag, if specified, causes a copy of the message
to be saved in the sender's MMbox. (No check is made to confirm that
sender address is local!)
</ul>
The message is placed in he global queue with expiry set to the system
maximum, and the queue entry ID is printed to standard output.
</p>
<p>
<H3><!--TableOfContentsAnchor:Begin--><A
NAME="Section_.1.5"></A><!--TableOfContentsAnchor:End-->Chapter 5: Tips & Tricks</H3>
This section is a compilation of tips and tricks on making Mbuni work
better for you
<H4><!--TableOfContentsAnchor:Begin--><A NAME="Section_.1.5.1"></A><!--TableOfContentsAnchor:End-->Passing MSISDNs to Mbuni</H4>
As indicated earlier, Mbuni expects the MSISDN to be sent to it as a
special HTTP request header. There are however times when it is
either not possible, or not practical to insert the header into the
MMS request. For such cases, Mbuni provides another way to specify
the sender MSISDN: The last part of the URL passed in the HTTP
transaction is passed to the De-tokenizer module (if specified),
which should return a valid sender address. So for instance
you can configure a clients to use a URL like <tt>http://mmsc/xYz12R2
</tt>
as the MMSC address, and Mbuni will pass <tt>xYz12R2</tt> to the
de-tokenizer module, which must return the sender
address. Mbuni will only do this it has failed to find the address request header.
<br>
If no sender address (MSISDN) is found, Mbuni assumes that the MMS client is
identified by IP address, and attempts to look up the IP address of
the sender (see config section) and use that as the sender
address. You can block this by specifying <tt>allow-ip-type = false</tt>
<br>
<br>
Note that because of the above feature, you need to configure your
WAP gateway and Mbuni IP security to ensure the system is not easily
spoofed.
</p>
<h4>Sample Kannel WAP configuration<a name="Section_.1.5.2"></a></h4>
<p>
We provide a sample Kannel <tt>wapbox</tt> config below, with some explanation
<br>
<tt>
group = wapbox<br>
bearerbox-host = localhost<br>
log-file = "/tmp/wapbox.log"<br>
syslog-level = none<br>
access-log = "/tmp/wapaccess.log"<br>
timer-freq = 10<br>
map-url = "http://mmsc/* http://localhost:1981/*"<br>
</tt>
<br>
This is a live example that was used in tests. In the example we use:
<ul>
<li> <tt>wapbox</tt> URL mapping to convert incoming MMS request URLs
into the long form. Note that the MMS gateway always sends short form
URLs so you need something like this
<li>We increase the <tt>timer-freq</tt> (essentially
slowing the timer) because over
slow bearer (such as CSD), the WAP gateway tends timeout on large
messages. Not sure if it is wise to do this. Although clearly whoever put this parameter in the config file expected it to be used!
</ul>
</p>
<H3><!--TableOfContentsAnchor:Begin--><A
NAME="Section_.1.6"></A><!--TableOfContentsAnchor:End-->Chapter 6: Log Files</H3>
The gateway writes a log file of important actions to the log file
configured. Message traffic is written to the access log in a standard
format.
<hr>
<!-- Author: Paul Bagyenda, Digital Solutions --><br>
<!-- when used within site, have #include virtual="footer.html" -->
<!-- begining of footer -->
</body>
</html>
<!-- end of footer -->
View Git Blame Copy Permalink