1861 lines
54 KiB
Plaintext
1861 lines
54 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">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]> <![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.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
|
|
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 < ../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 (") 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>mm7-port</tt>
|
|
|
|
</td>
|
|
<td valign=top >
|
|
Integer
|
|
</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.
|
|
</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-IP</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>
|
|
|
|
<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 =
|
|
"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 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>
|
|
<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 — 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 --> |