1627 lines
50 KiB
Plaintext
1627 lines
50 KiB
Plaintext
|
|
||
|
<!-- 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">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 Mobile Sender</A></LI>
|
||
|
<LI><A HREF="#Section_.1.4.3">MMS Global Sender</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
|
||
|
initial release fully supports the MM1 and MM3 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]> <![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 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>
|
||
|
Currently there is no support for VAS via MM7 protocols (SOAP or
|
||
|
EIAF), but this is planned and should be available soon.
|
||
|
<br>
|
||
|
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.1, 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 < ../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
|
||
|
4 programs:
|
||
|
<ul>
|
||
|
<li><tt>mmsc/mmsglobalsender</tt>
|
||
|
<li><tt>mmsc/mmsmobilesender</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>mmsglobalsender</tt> is the main relay server. It routes
|
||
|
incoming messages to email, other MMS gateways, MMS clients/handsets,
|
||
|
etc. <tt>mmsmobilesender</tt> manages routing messages to MMS clients
|
||
|
using WAP Push, sending of delivery reports, etc. <tt>mmsproxy</tt>
|
||
|
provides the HTTP interface via which messages are
|
||
|
sent and received by MMS clients. <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 < ../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
|
||
|
three programs listed above (<tt>mmsglobalsender</tt>,
|
||
|
<tt>mmsmobilsender</tt>, <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-->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 (") 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 – the lower the number the more debugging
|
||
|
information) and the location of the access log.
|
||
|
|
||
|
<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 =
|
||
|
"My MMSC"<br>
|
||
|
|
||
|
hostname
|
||
|
= ds.co.ug<br>
|
||
|
|
||
|
host-alias
|
||
|
= mmsc<br>
|
||
|
|
||
|
local-mmsc-domains=
|
||
|
mbuni.org,service.com<br>
|
||
|
|
||
|
local-prefixes
|
||
|
= 075;+25675;25675<br>
|
||
|
|
||
|
send-queue-directory
|
||
|
= spool/global<br>
|
||
|
|
||
|
mm1-queue-directory
|
||
|
= spool/mm1<br>
|
||
|
|
||
|
mm4-queue-directory
|
||
|
= spool/mm4<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>
|
||
|
</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>
|
||
|
mmsbox
|
||
|
</td>
|
||
|
<td valign=top>
|
||
|
Mandatory
|
||
|
variable
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top ><tt>name </tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
string
|
||
|
</td>
|
||
|
<td valign=top>
|
||
|
User-friendly
|
||
|
name for the Gateway, used in notices, etc
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top ><tt>hostname
|
||
|
</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
string
|
||
|
</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>
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top ><tt>host-alias
|
||
|
</tt>
|
||
|
</td>
|
||
|
<td valign=top>
|
||
|
string
|
||
|
</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
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>local-mmsc-domains</tt>
|
||
|
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
List of
|
||
|
Internet domains (comma separated)
|
||
|
</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
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top ><tt>local-prefixes</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
Number
|
||
|
prefix list
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
Number prefixes
|
||
|
that should be considered local. Messages to numbers that match these
|
||
|
prefixes will be delivered locally (via <tt>mmsmobilesender</tt>)
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>send-queue-directory
|
||
|
</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
Directory name
|
||
|
(string)
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
Global Queue directory:
|
||
|
Used by <tt>mmsglobalsender</tt> to store out-going messages.
|
||
|
All messages will be stored here until they can be delivered
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>mm1-queue-directory</tt>
|
||
|
|
||
|
</td>
|
||
|
<td valign=top>
|
||
|
Directory name
|
||
|
(string)
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
Queue directory
|
||
|
for messages destined to (local) MMS clients. Used by <tt>mmsmobilesender</tt>
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>mm4-queue-directory</tt>
|
||
|
|
||
|
</td>
|
||
|
<td valign=top>
|
||
|
Directory name
|
||
|
(string)
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
Queue directory
|
||
|
for messages destined to or coming from foreign MMS
|
||
|
gateways. <tt>mmsglobalsenderfromemail</tt> manages this queue
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>mmbox-root-directory</tt>
|
||
|
|
||
|
</td>
|
||
|
<td valign=top>
|
||
|
Directory name
|
||
|
(string)
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
Directory where all user/subscriber MMboxes will be stored. This
|
||
|
directory will contain a set of sub-directories under which user
|
||
|
MMboxes will be stored. Each user MMbox has a maildir-like structure </td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>max-send-threads</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
Number
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
How many queue
|
||
|
processing threads to start. A higher value means messages get delivered
|
||
|
faster.
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>send-mail-prog</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
String
|
||
|
</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
|
||
|
– replaced with the message from address, %t – replaced with the
|
||
|
recipient address (RFC 822 compliant), %s – the message subject, %m
|
||
|
– the message ID
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>unified-prefix
|
||
|
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
Number list
|
||
|
</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 "+256,000256,0;+,000" should
|
||
|
ensure correct UG prefixes. If
|
||
|
there are several unified prefixes, separate their rules with semicolon (';')
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>maximum-send-attempts
|
||
|
</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
integer
|
||
|
</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)
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>default-message-expiry</tt>
|
||
|
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
Integer
|
||
|
</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.
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>queue-run-interval</tt>
|
||
|
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
Real
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
How many
|
||
|
seconds between each queue run
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>send-attempt-back-off</tt>
|
||
|
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
Integer
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
<tt>mmsmobilesender</tt> uses a form of exponential back-off
|
||
|
when sending notifications to phones. This figure provides the starting
|
||
|
back-off value (in seconds).
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>sendsms-url</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
String
|
||
|
</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.)
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>sendsms-username</tt>
|
||
|
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
String
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
Username to
|
||
|
pass (for authentication) to send-sms URL
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>sendsms-password</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
String
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
Password to
|
||
|
pass (for authentication) to send-sms URL
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>sendsms-global-sender</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
String
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
Optional sender
|
||
|
(<i>to</i> field) to use in send sms url
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>mms-port</tt>
|
||
|
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
Integer
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
Port on which <tt>mmsproxy</tt> listens for MMS messages from MMS
|
||
|
clients (Default
|
||
|
is 8191).
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>allow-ip</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
List of IP
|
||
|
addresses
|
||
|
</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.
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>mms-client-msisdn-header</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
String
|
||
|
</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>)
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>mms-client-ip-header</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
String
|
||
|
</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-Address</tt>. If the header is not
|
||
|
found, we assume the IP address as seen by Mbuni's MM1 interface.
|
||
|
</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>allow-ip-type</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
Boolean
|
||
|
</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.
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>optimize-notification-size</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
Boolean
|
||
|
</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
|
||
|
</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>email2mms-relay-prefixes</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
Number list
|
||
|
</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.
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>ua-profile-cache-directory</tt>
|
||
|
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
Directory name
|
||
|
(string)
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
User Agent
|
||
|
Profile Cache: When an MMS client requests (via HTTP GET command) a message
|
||
|
about which it has been notified, it sends its profile URL (such as
|
||
|
<tt>http://nds.nokia.com/uaprof/N3650r100.xml </tt>
|
||
|
for the Nokia 3650) as part
|
||
|
of the HTTP request headers. The gateway should fetch the URL presented and
|
||
|
parse it to figure out the client's capabilities (so-called <i>User Agent
|
||
|
Profile</i>). It would be inefficient to fetch the profile data each time from
|
||
|
an external server, therefore the gateway caches fetched profile data in the
|
||
|
directory specified here. Cache entries are never expired (which is unlikely
|
||
|
to be a problem). Some badly behaved MMS clients to do not submit a profile
|
||
|
URL. In this case, the gateway relies on the HTTP
|
||
|
<i>Accept</i> request headers to determine its
|
||
|
capabilities.
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>billing-library</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
String
|
||
|
</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.
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>billing-module-parameters</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
String
|
||
|
</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.
|
||
|
</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>resolver-library</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
String
|
||
|
</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.
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>resolver-module-parameters</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
String
|
||
|
</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.
|
||
|
</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>detokenizer-library</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
String
|
||
|
</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.
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>detokenizer-module-parameters</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
String
|
||
|
</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.
|
||
|
</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>prov-server-notify-script</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
String
|
||
|
</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).
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>prov-server-sub-status-script</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
string
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
Subscriber
|
||
|
database interface script 2: This script is called
|
||
|
by <tt>mmsmobilesender</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>mmsmobilesender</tt> will deliver the message (see below).
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top>
|
||
|
<tt>notify-unprovisioned</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
Boolean
|
||
|
</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.
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top>
|
||
|
<tt>mms-notify-text</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
String
|
||
|
</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.
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>mms-notify-unprovisioned-text</tt>
|
||
|
</td>
|
||
|
<td valign=top>
|
||
|
String
|
||
|
</td>
|
||
|
<td valign=top>
|
||
|
Message to send
|
||
|
to devices that are not provisioned for MMS (only if
|
||
|
<tt>notify-unprovisioned</tt> is true).
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>mms-message-too-large-txt</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
String
|
||
|
</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.
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>mms-to-email-html</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
string
|
||
|
</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.
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td valign=top >
|
||
|
<tt>mms-to-email-txt</tt>
|
||
|
</td>
|
||
|
<td valign=top >
|
||
|
String
|
||
|
</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.
|
||
|
</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
<br>
|
||
|
|
||
|
<p >Foreign MMS
|
||
|
Gateways are configured using one or more <i>mmsproxy</i> groups:</p>
|
||
|
|
||
|
<br>
|
||
|
<tt>
|
||
|
group =
|
||
|
mmsproxy<br>
|
||
|
|
||
|
name =
|
||
|
"A test mms proxy"<br>
|
||
|
|
||
|
host =
|
||
|
test.com<br>
|
||
|
|
||
|
allowed-prefix
|
||
|
= "075"<br>
|
||
|
|
||
|
denied-prefix
|
||
|
= "077"<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 four components to the gateway: The Global
|
||
|
Sender (<tt>mmsglobalsender</tt>), Mobile Sender (<tt>mmsmobilesender</tt>), 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. It provides an HTTP interface through which
|
||
|
clients can send MMS messages. The 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:
|
||
|
|
||
|
<p>
|
||
|
Currently, no MMbox quotas are imposed.
|
||
|
</p>
|
||
|
<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>
|
||
|
<li> The message is then packed and returned to the client as the
|
||
|
result of the HTTP request.
|
||
|
|
||
|
</ol>
|
||
|
This component must always be running.
|
||
|
|
||
|
|
||
|
</p>
|
||
|
|
||
|
<H4><!--TableOfContentsAnchor:Begin--><A NAME="Section_.1.4.2"></A><!--TableOfContentsAnchor:End-->MMS Mobile Sender</H4>
|
||
|
|
||
|
<p>
|
||
|
|
||
|
This component handles
|
||
|
<ol>
|
||
|
<li> Notification of MMS clients of received message via WAP Push
|
||
|
<li> Delivery of other notifications such as delivery and read
|
||
|
reports to MMS clients via WAP Push
|
||
|
</ol>
|
||
|
SMS is used as the transport for WAP Push messages, if the recipient
|
||
|
is an MSISDN, otherwise TCP/IP is used.
|
||
|
<br>
|
||
|
The mobile sender maintains a queue of messages pending delivery. At
|
||
|
set intervals (see configuration section), it sends notifications to
|
||
|
the recipients. 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>
|
||
|
<H4><!--TableOfContentsAnchor:Begin--><A NAME="Section_.1.4.3"></A><!--TableOfContentsAnchor:End-->MMS Global Sender</H4>
|
||
|
This is the master message switch. It consists largely of a queue
|
||
|
runner that monitors the global queue. For each message that arrives
|
||
|
in the queue, the global sender:
|
||
|
<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, 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 sender 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 message cannot be delivered, the sender is notified.
|
||
|
</ol>
|
||
|
</ol>
|
||
|
<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>
|
||
|
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>
|
||
|
<tt>
|
||
|
|
||
|
mmssend -f <i>from_address</i> -t <i>recipient_list</i> -m
|
||
|
<i>mmsfile</i> [-b] -- <i>conf_file</i>
|
||
|
</tt>
|
||
|
<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 recipients MMbox. (No check is made to confirm that
|
||
|
recipient 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 an MSISDN. 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
|
||
|
MSISDN. Mbuni will only do this it has failed to find the MISDN request header.
|
||
|
<br>
|
||
|
If no 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 -->
|