Mbuni: Open Source MMS Gateway
This document describes the installation and usage of the MMS
Table of Contents
? Chapter 1: Introduction
o Overview of MMS
? Chapter 2: Installing The Gateway
o Installing Kannel
o Installing Mbuni MMS Gateway
o Installing Required Components ? Chapter 3: Running the Gateway
o Running Mbuni as a MMSC
o Running Mbuni as a VAS Gateway
o General Configuration File
o MMSC-specific Configuration
? MM7 Configuration
? MM4 Configuration
o MMS VAS Gateway-specific Configuration
? MMSC Connection Configuration
? SendMMS User Configuration
? MMS Service Configuration ? Chapter 4: Gateway Architecture
o MMSC Architecture
? MMS Proxy
? MMS Relay
? SMTP/Mail Interface
o VAS Gateway Architecture ? Chapter 5: Tips & Tricks
o Passing MSISDNs to Mbuni
o Sample Kannel WAP configuration ? Chapter 6: Log Files
Chapter 1: Introduction
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. 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.
The Mbuni Project attempts to provide that little bit of boost to MMS adoption/growth, by providing two important parts of the MMS infrastructure: For the network "operator" Mbuni includes a fully-fledged MMS switching centre (MMSC), while for the MMS content provider Mbuni includes a MMS Value Added Services (VAS) Gateway (MMSBox).
Mbuni implements all major MMS interfaces, including
phone-to-phone (so-called MM1 interface), phone-to-email (MM3), inter-MMSC (MM4) and MMS VAS (MM7). The level of support for each type of interface is listed on status page of the website.
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.
Overview of MMS
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.
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.
Multimedia messages can be originated by or terminate to end-user client devices (i.e. MMS-enabled phones) or third party applications (typically used by MMS content providers). In the MMS architecture, the MMSC acts as the message-switching system within the core
network, while the MMSBox acts as the message dispatch and
content management system on the VAS (third party) side. The
overall architecture is shown below.
The elements shown in the figure can be summarised as follows:
? MMS Client: 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 MMSC using WAP/HTTP as transport.
? MMS Gateway: 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. This is also more properly known as the
? MMS Server: This component provides persistent storage of
messages on the network. Typically users can access stored
messages via a web interface.
? Other MMS Systems:Other systems, such as Third Party MMS
systems (e.g. MMS VAS providers) can interface to the MMSC
to receive and send MMS content. The Interface used is termed
? SMSC: The MMSC 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
Typically, the message cycle begins with a user sending a multimedia message (MM) from 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). On receipt of the message, the MMSC decides how to deliver the message (e.g. to another MMS client or to a VASP), and proceeds to dispatch the message. A VASP may also originate a message to the MMSC, for onward delivery.
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. Usually the message is of a multipart/related MIME type, with the start element being a SMIL part
that controls how the message should be displayed.
When submitting a message, the MMS client indicates the intended recipient list, but usually not the sender address, which the MMSC retrieves from the WAP gateway. Like Email, a single MMS can specify multiple recipients (MSISDNs and Email addresses), and it is up to the MMSC to ensure correct delivery to each of the recipients. When the MMSC 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. When the MMSC receives a message destined to MMS Clients in the area served by the MMSC, 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.
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 MMSC 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.
The MMSC 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.
On the VASP side of things, typically the content provider receives a
request MM from a subscriber and must respond with an MM. The
content to be sent back depends on the contents of the request.
Mbuni MMS gateway is a modular software system, designed to be
full-featured, efficient and simple, supporting current generation
multimedia messaging. Mbuni operates in one of two modes: As an
MMSC or as a VAS gateway.
? Operating as MMSC, Mbuni provides:
o Phone-to-phone messaging
o Automatic content adaptation: The server modifies
message content depending on the capabilities of the
o Integrated Email-to-MMS and MMS-to-Email gateway
o Support for persistent storage of messages for
o Inter-MMSC message exchange (MM4 interface)
o Support for MMS Value Added Service Providers using
MM7 protocols (SOAP or EAIF).
o Support for integration with subscriber database to enable
smart handling of handsets that do not support MMS,
handsets not provisioned, etc.
o Support for flexible billing structure through billing/CDR
o Bearer (data) technology neutral: Works with GSM/CSD
? Operating as a VAS Gateway, Mbuni provides:
o Support for both SOAP and EAIF connectivity with an
o Multiple connections to different MMSC of different types
can be maintained
o MMS content can be loaded from file, URL or as the
output of a program
o MM composition from SMIL: The gateway will
automatically fetch all components referenced in the
SMIL and add them to the MM.
o A URL interface for MM dispatch.
The Gateway is designed and tested to conform to Open Mobile
Alliance (OMA), WAP and 3rd Generation Partnership Project (3GPP)
MMS standards including: ? WAP: 209
? OMA: MMS v1.2, UAProf v1.1
? 3GPP: TS 23.140
Mbuni is being developed on MacOS X and Linux systems using the
C programming language. It should compile and run on any similar
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 Kannel (and therefore fulfil those dependencies
Mbuni shares with it).
The following additional components are required:
? Libiconv v2.0 or higher is required for character set conversions
? Audio conversion tools required by the content adaptation
o Sox from sox.sourceforge.net
o Lame (v3.93 or higher) from www.mp3dev.org
o Mpg123 from www.mpg123.de
o AMR encoder/decoder from www.3gpp.org (modified, see
? Image conversion tools required by the content adaptation
o ImageMagick from www.imagemagick.org
? Mail server such as Postfix (www.postfix.org)
? You will also need to be running a WAP gateway (we
? You may optionally need to run an HTTP proxy such as Squid
(squid-cache.org), since some newer phones (e.g. Nokia 6600)
do not send MMS over WAP but directly over HTTP via an
Hardware requirements will depend on amount of traffic, required
response times, etc. Keep in mind however that the gateway performs
a lot of heavy multimedia re-coding tasks, particularly during content
adaptation, so you should always err on the side of more rather than
Chapter 2: Installing The Gateway
This section explains the steps required to install the gateway. If you
are installing from a binary distribution, you may safely skip
In brief, to install Mbuni, you need to:
? Download and install required packages (such as libXML,
? Download and install Kannel CVS (pre-1.4.2)
? Download and install Mbuni
? Download, patch and install the AMR encoder/decoder
? Download and install additional requried packages
The source code for Mbuni is available for download from
the download area of the website Installing Kannel
In order to compile the software, you will first need to download and
install Kannel CVS (2008-07-28) from mbuni.org:
Unpack the kannel source files using a command like:
tar xvf kannel-snapshot.tar.gz Then proceed to compile and install Kannel normally:
cd kannel-snapshot; ./configure make install
Installing Mbuni MMS Gateway
Download and unzip/tar Mbuni sources in a directory of your choice:
tar xzf mbuni-version.tgz Where version is the verion of Mbuni (e.g. 1.4.0). Compile and install mbuni as follows:
You need to have AutoMake for the above to work
If you installed Kannel in a non-standard location, you will need to
supply the location to configureusing --with-kannel=kannel_directory
Installing from CVS
If you want to try out the development version of Mbuni, you can
download it from the CVS on sourceforge.net:
cvs -d:pserver:email@example.com:/cvsroot/mbuni login
cvs -z3 -d:pserver:firstname.lastname@example.org:/cvsroot/mbuni co -P mbuni
you can then install as above. Mbuni consists of 4 programs:
which are by default installed in /usr/local/bin mmsrelay is the main relay server of the MMSC. 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.
mmsproxy provides the HTTP interface of the MMSC via which
messages are sent and received by MMS clients.
mmsfromemail is the email2MMS MMSC module.
mmsbox is the VAS gateway
Installing Required Components
If you intend to use Mbuni as an MMSC, be sure to install all other
required components as detailed above, otherwise parts of the MMS
gateway may not function correctly.
Mbuni expects that an AMR decoder is installed and can be invoked amrdecoder infile outfile as:
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.)
Similarly, it is expected that an AMR encoder called amrencoder exists
and can be executed as follows:
amrencoder mode infile outfile
and convert raw, 16-bit signed, 8kHz mono audio samples in the input
file to AMR using the supplied encoding mode.
For the AMR encoder/decoder, we have adapted the sample provided
on the 3GPP website. Follow the instructions below to install it:
? Download the AMR encoder/decoder source from here
? unzip/unpack the zip file, and unpack the source within:
unzip ../26104-520_ANSI_C_source_code.zip ? Download the AMR code patch from the mbuni.org download
section and apply as follows:
patch -p1 < ../mbuni-amr-patch
? You should then compile and install the AMR encoder/decoder
make -f makefile.gcc
cp -f amrdecoder amrencoder /usr/local/bin This AMR encoder is not very efficient but it works (which is
Chapter 3: Running the Gateway
How one runs Mbuni depends on its intended use or mode of
operation. We look at the two usage scenarios below.
Running Mbuni as a MMSC
To run the MMSC, you must run
(mmsrelay and mmsproxy). mmsfromemail 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.
Running Mbuni as a VAS Gateway
To run Mbuni as a VAS gateway you must run mmsbox
General Configuration File
All Mbuni programs expect the configuration file to be passed as the
last argument on the command line (default is mbuni.conf). The
configuration file controls most aspects of the operation of the
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.
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.
The variable group marks the beginning of a new group with the given
The core group is core and defines the log file location, log level
(amount of debugging information – the lower the number the more
debugging information), the location of the access log, the HTTP
interface to listen on for incoming connections, HTTP proxy host/port
if any (HTTP proxy host/port and HTTP interface name are specified
using the exact same parameters as used by Kannel.) and SSL client
and server certificate files to be used for incoming and outgoing
HTTPS connections, if Kannel and Mbuni are compiled to have SSL
enabled. The syntax for specifying SSL certificates is exactly as that
used by Kannel.
group = core
log-file = log/mmsgw.log
log-level = 0
access-log = log/access.log
http-interface-name = "*"