By Stacy Brown,2014-07-08 10:47
6 views 0
Mbuni: Open Source MMS Gateway

Mbuni: Open Source MMS Gateway

    User Guide

    This document describes the installation and usage of the MMS


    Table of Contents

    ? Chapter 1: Introduction

    o Overview of MMS

    o Features

    o Requirements

    ? 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

    ? Utilities

    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

    receiving terminal

    o Integrated Email-to-MMS and MMS-to-Email gateway

    o Support for persistent storage of messages for

    subscribers (MMbox).

    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

    plug-in architecture

    o Bearer (data) technology neutral: Works with GSM/CSD

    or GPRS.

    ? Operating as a VAS Gateway, Mbuni provides:

    o Support for both SOAP and EAIF connectivity with an

    operator MMSC

    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

    o Lame (v3.93 or higher) from

    o Mpg123 from

    o AMR encoder/decoder from (modified, see


    ? Image conversion tools required by the content adaptation


    o ImageMagick from

    ? Mail server such as Postfix (

    ? You will also need to be running a WAP gateway (we

    recommend Kannel).

    ? You may optionally need to run an HTTP proxy such as Squid

    (, since some newer phones (e.g. Nokia 6600)

    do not send MMS over WAP but directly over HTTP via an

    HTTP Proxy.

    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

    less power.

    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

    to here.

    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

    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:

    cd mbuni-version



    make insall

    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

    cvs login

    followed by

    cvs -z3 co -P mbuni

    you can then install as above. Mbuni consists of 4 programs:

    ? mmsc/mmsrelay

    ? mmsc/mmsproxy

    ? mmsc/mmsfromemail

    ? mmsbox/mmsbox

    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:


    mkdir amr

    cd amr

    unzip ../ ? Download the AMR code patch from the download

    section and apply as follows:

    patch -p1 < ../mbuni-amr-patch

    ? You should then compile and install the AMR encoder/decoder

    as follows:

    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 = "*"

Report this document

For any questions or suggestions please email