Mbuni: Open Source MMS Gateway

User Guide

Table of Contents

• Chapter 1: Introduction
  • Overview of MMS
  • Features
  • Requirements
• Chapter 2: Installing The Gateway
  • Installing Kannel
  • Installing Mbuni MMS Gateway
  • Installing Required Components
• Chapter 3: Running the Gateway
  • Running Mbuni as a MMSC
  • Running Mbuni as a VAS Gateway
  • General Configuration File
  • MMSC-specific Configuration
    • MM7 Configuration
    • MM4 Configuration
  • MMS VAS Gateway-specific Configuration
    • MMSC Connection Configuration
    • SendMMS User Configuration
    • MMS Service Configuration
  • Using the VAS Gateway Administration Interface
  • Built-in Billing, Resolver and Detokenizer Modules
• Chapter 4: Gateway Architecture
  • MMSC Architecture
    • MMS Proxy
    • MMS Relay
    • SMTP/Mail Interface
    • Utilities
  • VAS Gateway Architecture
• Chapter 5: Tips & Tricks
  • Passing MSISDNs to Mbuni
  • 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 MMSC.
• 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 MM7.
• 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 Centre.

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.

Features

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:
  • Phone-to-phone messaging
  • Automatic content adaptation: The server modifies message content depending on the capabilities of the receiving terminal
  • Integrated Email-to-MMS and MMS-to-Email gateway
  • Support for persistent storage of messages for subscribers (MMbox).
  • Inter-MMSC message exchange (MM4 interface)
  • Support for MMS Value Added Service Providers using MM7 protocols (SOAP or EAIF).
  • Support for integration with subscriber database to enable smart handling of handsets that do not support MMS, handsets not provisioned, etc.
  • Support for flexible billing structure through billing/CDR plug-in architecture
  • Bearer (data) technology neutral: Works with GSM/CSD or GPRS.
• Operating as a VAS Gateway, Mbuni provides:
  • Support for SOAP, EAIF, MM1 and MM4 connectivity with an operator MMSC (plus a special HTTP-based relay mechanism)
  • Multiple connections to different MMSC of different types can be maintained
  • MMS content can be loaded from file, URL or as the output of a program
  • MM composition from SMIL: The gateway will automatically fetch all components referenced in the SMIL and add them to the MM.
  • 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

Requirements

Mbuni is being developed on MacOS X and Linux systems using the C programming language. It should compile and run on any similar system.

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).

• Libiconv v2.0 or higher is required for character set conversions
• Audio conversion tools required by the content adaptation module:
  • Sox from sox.sourceforge.net
  • Lame (v3.93 or higher) from www.mp3dev.org
  • Mpg123 from www.mpg123.de
  • AMR encoder/decoder from www.3gpp.org (modified, see below)
• Image conversion tools required by the content adaptation module:
  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 recommend Kannel).
• 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 HTTP Proxy.

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, libiconv)
• Download and install Kannel (v1.4.2 and above)
• 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 (v1.4.2 and above) from kannel.org:

Unpack the kannel source files using a command like:

tar xvf kannel-version.tar.gz

Then proceed to compile and install Kannel normally:

cd kannel-version; ./configure
make install

Installing Mbuni MMS Gateway

Download and unzip/tar Mbuni sources in a directory of your choice:

Where version is the verion of Mbuni (e.g. 1.5.0). Compile and install mbuni as follows:

cd mbuni-version
./bootstrap
./configure
make insall

If you installed Kannel in a non-standard location, you will need to supply the location to configure using --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:

Mbuni consists of 3 programs:

• mmsc
• mmsfromemail
• mmsbox

mmsc is the MMSC component. It consists of the relay server (mmsrelay), which routes incoming messages to email, other MMS gateways, MMS clients/handsets, and the client-facing MMSC interface (mmsproxy) via which messages are sent and received by MMS clients (MM1 as well as MM7).

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 as:
amrdecoder infile outfile
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.zip
  mkdir amr
  cd amr
  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 as follows:
  make -f makefile.gcc
  cp -f amrdecoder amrencoder /usr/local/bin

Chapter 3: Running the Gateway

Running Mbuni as a MMSC

To run the MMSC, you must run the command mmsc. 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 gateway.

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 name.

Mbuni supports configuration using a dynmically linked module. This is particularly useful if you wish to configure Mbuni from a database or a script.

In order to do this, the first (and only) group in the config file must be a config-source group. An example is shown below:

group = config-source
config-library = path_to_dll
config-library-init-param = init_param_for_dynamic_lib


Mbuni will load the supplied DLL and get all subsequent configuration parameters from the module. (See mms_cfg-imp.h for DLL requirements.)

If not using a module as configuration source, the config-source group must not exist. The rest of the configuration file must have the format as described above. Groups and respective items are described below.

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

This should be followed by the main gateway configuration group (mbuni).

group = mbuni
name = "My MMSC"
hostname = ds.co.ug
host-alias = mmsc
local-prefixes = 075;+25675;25675
directory-store = spool
max-send-threads = 5
send-mail-prog = /usr/sbin/sendmail -f %f %t
...

The table below lists all the configuration directives. The column Mode indicates operation mode in which the parameter is applicable: Config params marked VAS GW are only applicable when operating in VAS Gateway mode, while those marked MMSC are only applicable when operating in MMSC mode. The rest are used in both modes.

Using the VAS Gateway Administration Interface

http://server_ip:server_admin_port/command_uri?password=admin_password?mmsc-id=mmsc

stop

To stop a specific MMSC link, specified using the mmsc-id CGI parameter.This means no MT MMS will be routed out via this connection until it is started again. The provided ID must match the ID of one of the mmsc groups defined in the configuration file. If mmsc-id is not provided, all defined MMSC connections are stopped.

start

To start a specific MMSC link, specified using the mmsc-id CGI parameter. The provided ID must match the ID of one of the mmsc groups defined in the configuration file. If mmsc-id is not provided, all defined MMSC connections are started.

status

To retrieve the status of a specific MMSC link, specified using the mmsc-id CGI parameter. The provided ID must match the ID of one of the mmsc groups defined in the configuration file. If mmsc-id is not provided, all defined MMSC connections' status is reported.

<mmsbox>
<mmsc id="eaif" type="EAIF">
 <port>8190</port>
<group>eaif</group>
<throughput>0.0000</throughput>
<re-route>false</re-route>
<reroute-mmsc>N/A</reroute-mmsc>
<stats>
<uptime>23 secs</uptime>
<last-pdu>n/a</last-pdu>
<mt><pdus>0</pdus><errors>0</errors></mt>
<mo><pdus>0</pdus><errors>0</errors></mo>
</stats>
</mmsc>
<mmsc id="mail" type="MM4">
 <port>n/a</port>
<group>mail</group>
<throughput>0.0000</throughput>
<re-route>false</re-route>
<reroute-mmsc>N/A</reroute-mmsc>
<stats>
<uptime>23 secs</uptime>
<last-pdu>n/a</last-pdu>
<mt><pdus>0</pdus><errors>0</errors></mt>
<mo><pdus>0</pdus><errors>0</errors></mo>
</stats>
</mmsc>
<mmsc id="http" type="HTTP">
 <port>9001</port>
<group>http</group>
<throughput>0.0000</throughput>
<re-route>true</re-route>
<reroute-mmsc>local</reroute-mmsc>
<stats>
<uptime>23 secs</uptime>
<last-pdu>n/a</last-pdu>
<mt><pdus>0</pdus><errors>0</errors></mt>
<mo><pdus>0</pdus><errors>0</errors></mo>
</stats>
</mmsc>
<mmsc id="local" type="SOAP">
 <port>12345</port>
<group>local</group>
<throughput>0.0000</throughput>
<re-route>false</re-route>
<reroute-mmsc>N/A</reroute-mmsc>
<stats>
<uptime>23 secs</uptime>
<last-pdu>n/a</last-pdu>
<mt><pdus>0</pdus><errors>0</errors></mt>
<mo><pdus>0</pdus><errors>0</errors></mo>
</stats>
</mmsc>
</mmsbox>

<Start-Mmsc><Error>error message</Error></Start-Mmsc>

<Stop-Mmsc><Success/></Stop-Mmsc>

<Stop-Mmsc><Failed/></Stop-Mmsc>

Built-in billing, resolver and detokenizer modules

• If billing-library configuration parameter is set to builtin:shell, the billing-module-parameters must the path to the shell script to be called by Mbuni to provide billing and CDR handling. For each message, the script will be with invoked each recipient as follows:
  script from_address to_address
  If the script returns with a non-zero exit status, the message is discarded.
• If resolver-library is set to builtin:shell, resolver-module-parameters must be set to a the path to the shell script to be invoked for each destination address to determine how to deliver the message. The script is invoked with one command line parameter (the destination address) and should output (on standard output) the hostname of the home MMSC (or MM7 connection ID in the case of mmsbox), to which the message should be routed.
• If detokenizer-library is set to builtin:shell then detokenizer-module-parameters should be set to the script that should be called to resolve the last part of the MM1 request URL (the token) or sender IP address to sender number. The shell is called with two arguments: The URL token and the IP address (in that order), and should output (on standard output) the sender number.

MMSC-specific Configurations

MM7 Configuration

MMS Value-Added Service Providers (VASPs) are configured using one or more mms-vasp groups:

MM4 Configuration

Foreign MMS Gateways are configured using one or more mmsproxy groups:

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 MM4 MIME (according to 3GPP TS 23.140) and sent via SMTP to the proxy.

MMS VAS Gateway-specific Configuration

When Mbuni is used as a VAS Gateway, the configurations in this section are required to ensure smooth functioning of the system. We describe each configuration set in turn.

MMSC Connection Configuratiom

MMSC connections are configured using one or more mmsc groups:

SendMMS User Configuration

To be able to send MMS into Mbuni via the sendMMS port (if configured), at least one sendmms user must be configured:

Configuration parameters are:

Variable	Type	Description
group	mandatory	send-mms-user
username	mandatory	Username
password	mandatory	Password
faked-sender	string	Optional sender address used (irrespective of whether from address has been specified in MMS send request).
delivery-report-url	string	Optional URL to call to send message delivery status as reported to the VAS gateway by a MMSC for a message submitted by this user.
read-report-url	string	Optional URL to call to send message read status reports as returned to the VAS gateway by a MMSC for a message submitted by this user.
mmsc	string	Optional id of the mmsc to use, if none is specified using the CGI Variables

The Send MMS service can be invoked using HTTP GET or POST requests to the Send MMS port on the VAS Gateway hosts. The interface expects and processes the following CGI paramerters:

CGI Variable	Description
username	authentication username (must match a configured send-mms-user).
password	authentication password (must match password of corresponding send-mms-user).
from	Message sender. This is over-ridden by faked-sender setting of the send-mms-user.
to	Message recipient(s). Multiple recipients can be separated with a whitespace.
subject	Message subject
mmsc	Outgoing MMSC via which to route the message. If this is not given, the VAS Gateway routes the message based on the recipient address and the allowed-prefix/denied-prefix settings for the configured MMSCs. Note: The VAS Gateway considers that any MMSC can handle email and IP address recipient addresses and so routes messages to such destinations to the first configured MMSC. Note too that MT MMS filtering will not be done on messages sent via the send-mms interface unless a particular destination MMC is specified using this variable
dlr-url	URL to invoke when a delivery report for this message is received
rr-url	URL to invoke when a read report for this message is received
text	If provided, this is used as the (text) content of the MM to be sent. The content type of the MM is set to text/plain
charset	Used in conjuction with the text parameter, it specifies the character set of the text, if it is not the default (iso-8859-1).
smil	If provided, specifies the SMIL for the MM. An MM is built out of the SMIL as described below, and the MM body will have content type multipart/related, which is the expected default.
content-url	If provided, specifies the URL of the content to be sent.
content	If provided, specifies the arbitrary content for the MM. The Content type of the content is determined either by the content_type CGI variable (see below), or if enctype=multipart/form-data is used in the HTTP POST request, then the content type associated with this variable data is used.
content_type	If the content variable is provided, this variable specifies the content type of the content. The default, if no content type is provided (or can be gleaned from the HTTP request), this is set to application/octet-stream.
base-url	If the smil URL parameter is provided, then this parameter may be supplied to be used as the base URL for resolving all relative URLs specified within the SMIL file while building the MM. Default: http://localhost/
vasid	This will be passed on the MMC as the VASID parameter in the MM7/SOAP message. If not provided, defaults to sendmms-user
servicecode	This will be passed on the MMC as the ServiceCode parameter in the MM7/SOAP message. If not provided, this parameter is not sent.
allow-adaptations	Should be 1 (yes) or 0 (no). This flag will be passed on to the operator MMSC (MM7/SOAP only) to turn on/off content adapation. If not passed, then setting in MMSC section in mmsbox.conf will be used.
mclass	Message Class. (e.g. Personal)
priority	Message Priority. (e.g. Normal)
mms-direction	MT (mobile terminating) or MO (mobile orginating). When set to MO, the MMS is queued as if it came from the operator MMSC side. This is useful for testing service configurations as it mimics receiving an MO MMS. Default is MT.
distribution	Optional. Should be true or false. This is set as the MM7/SOAP DistributionIndicator parameter.
validityperiod	Optional. Should be an integer, giving the number of minutes before this message is considered expired by the receiving MMSC.
charged-party	Optional. Set to the MM7/SOAP ChargedParty parameter.

Note: Only one of text, smil, content-url or content should be speficied, as only one makes sense at any time. Specifying more than one causes others to be (silently) ignored.

If a delivery-report-url or read-report-url is specified for the send mms user (or as parameters in the send mms request), and a report is sent to the VAS Gateway by a MMSC, the relevant URL is called (using the HTTP GET method), and information about the report sent to it via X-Mbuni headers.

The SendMMS interface can also be used to send binary content (e.g. binary-coded MMS, image or audio) directly to Mbuni. This is done as follows:

• Send the binary content as the body of an HTTP POST request to the SendMMS port. Be sure to specify the correct body content type as part of the HTTP request headers. This is interpreted according to the rules set out below.
• Supply to the request URL all but the text and smil URL parameters (as described above) as part of the request URL.

MMS Service Configuration

Messages are routed to services based on the first word of the text part of the MM. That is, Mbuni extracts the first text part of the MM, and finds the first word — the keyword — in the message. Mbuni then searches through the list of configured MMS Services for a matching service based on the keyword, and fetches the response from the associated URL, file or program.

A sample service configuration might look like this:
group = mms-service
name = me
post-url = http://localhost/photoblog.php
catch-all = true
http-post-parameters = fx=true&images[]=%i&text[]=%t
accept-x-mbuni-headers = true
keyword = test

A detailed list of configuration parameters for MMS Services is given below.

Variable	Type	Description
group	mandatory	mms-service
name	string	Service name. Used for logging, also sent to MMSC as VAS ID parameter for MM7 SOAP requests
keyword	string	mandatory keyword. Incoming messages whose text part matching this parameter will be routed via this service.
aliases	list of string	semi-colon separated list of keyword aliases. Any of these keywords will also match and cause message to be routed via the service.
catch-all	boolean	Set this to true if this is the default service (i.e. all other messages routed through this service in case of no match).
accepted-mmscs	list of strings	semi-colon separated list of MMSCs (listed by ID). Only messages from these MMSCs will be routed to this service on match. Leave this empty to allow all.
denied-mmscs	list of strings	Messages from these MMSCs will never be routed to this service on match. Leave this empty to allow all.
allowed-receiver-prefix	Strings	Semicolon-separated strings: List of receiver short code prefixes allowed to use this MMS Service.
denied-receiver-prefix	Strings	Semicolon-separated strings: List of receiver short code prefixes not allowed to use this MMS Service.
get-url	string	The URL to fetch for response content. No parameter substitution is done, but X-Mbuni headers are sent as part of the HTTP request. See below for an explanation on how the response content is interpreted.
exec	string	Program to execute to obtain response content. Response is exptected on standard output, and must be of type SMIL. See below for an explanation on how the SMIL is processed.
file	string	File from which to obtain response content. Response type is inferred from the file name extension for a few well-known media types (text, SMIL, GIF, JPEG, PNG, BMP/WBMP, WAV, AMR, MP3, etc.), otherwise it defaults to application/octet-stream. See below for further information on how fetched content is converted to an MM.
text	string	If provided, the response content is the value of this parameter, and is assumed to be of media type text/plain.
post-url	string	Response content is obtained as result of sending a HTTP POST request to the provided URL. The POST message is always submitted using the multipart/form-data encoding (such as that used by a web browser when an HTML form has the enctype=multipart/form-data parameter set). If http-post-parameters field is given (see below), then the relevant parameters are sent as part of the request. X-Mbuni headers are sent as well. See below for an explanation on how the response content is interpreted.
http-post-parameters	string	Used in conjunction with post-url. Parameters are provided in the same way as would be provided in an HTTP GET request (e.g. message=true&myname=test&image=%i). Parameter values that begin with % are interpolated according to the rules listed below.
accept-x-mbuni-headers	boolean	Set this to true if Mbuni should honour X-Mbuni HTTP headers in the service response. See below for the list of headers.
pass-thro-headers	List	Set this to a comma-separated list of HTTP response headers that, if received from the service response, should be passed to the MMC (with their corresponding values) unchanged. Note that these headers are merged with other headers generated by Mbuni.
omit-empty	boolean	Set this to true if Mbuni should send an empty response to the requestor if one is returned by the service
suppress-reply	boolean	Set this to true if Mbuni not send a reply back to the user of this service. Note that the request URL will still be invoked.
assume-plain-text	boolean	Set this to true if an unknown content type in the response should be mapped to plain text.
faked-sender	string	If set, Mbuni will change the sender address in the response message to this value, irrespective of any X-Mbuni headers or the original recipient address.
service-code	string	If set, Mbuni will use this as the ServiceCode parameter to send back the MMSC (MM7/SOAP only) in a SubmitReq packet. This paramter overrides the X-Mbuni-ServiceCode header, if set int the response.

Note that only one of get-url, post-url, file or text may be specified.

When the MMS Service response content is fetched for a service, or a message is pushed using the send-mms interface, it is converted into an MM based on the reported or inferred (in the case of file content) response content type. For content fetched from URLs, the content type is taken as received from the HTTP server. For file content it is inferred from the file extension. For exec content, it is assumed to be SMIL. General conversion rules are as follows:

• SMIL: If the content type is application/smil, the VAS gateway parses the SMIL and finds all content (e.g. images, audio) it references. ("Referenced" is currently interpreted as any element with an src attribute.) These are fetched and added to the response MM, and corresponding SMIL component modified (i.e. the src attribute modified) to reference the content within the MM. Note that the VAS gateway is smart enough to understand partial URL or file references (e.g. images/smile.gif or ./test.txt), as well as absolute (e.g. /images/smile.gif or http://somehost/test.txt) references within the SMIL. It will attempt to fetch the content relative to the location of the base SMIL content in the case of relative references. To prevent the content from being fetched, you can prepend a backslash to the location value.
  The resulting MM will be a standard multipart/related message, with the SMIL as the start element.
• MMS Content Type: If the returned content type is application/vnd.wap.mms-message, the content is assumed to be a binary-coded MM and will be returned as the response content.
• URL List type: A special Mbuni mime type application/vnd.mbuni.url-list has been defined, and files with extension .urls are mapped to this content type (if the content type is not provided by the HTTP server or other means). Files of this type should contain a list of URLs (file:// and http(s):// supported), one per line. Mbuni will load each content item from the URL and build an MMS containing the list of data items (multipart/mixed).
• Other Content Types: All other content types cause an MM to be built having the corresponding content type. Where the content type is not reported (or is impossible to determine) in the response, if the parameter assume-plain-text is set, MIME type text/plain is assumed.

Mbuni VAS Gateway utilises a number of HTTP extension headers to pass additional MM information to and receive information from the MMS Service. Note that all applicable headers are always sent in the HTTP request, but headers are only honoured in the response if the accept-x-mbuni-headers parameter of the service is set to true. On the response side, if honoured, the set values over-ride the ones in the request, and are used in the response.

The list of supported headers is listed below:

Header	Description
X-Mbuni-From	MM Sender address (e.g. +25674334444/TYPE=PLMN)
X-Mbuni-Subject	MM Subject
X-Mbuni-To	Recipient address. Multiple recipients can be specified as separate headers or as a comma-separated value
X-Mbuni-Expiry	MM Expiry as an HTTP date.
X-Mbuni-DLR-Url	Delivery report URL. This URL will be called with the delivery report status. It is also sent X-Mbuni headers
X-Mbuni-RR-Url	Read Report URL. This URL is called with the read report status. It is sent X-Mbuni headers.
X-Mbuni-MMSC	MMSC (id) through which message was received (on the request side) or through which it should be routed.
X-Mbuni-Message-ID	MM message ID. Only makes sense on the request side.
X-Mbuni-Report-Type	One of delivery-report or read-report, used when calling the DLR or RR URL.
X-Mbuni-MM-Status	Report status. Used in conjuction with X-Mbuni-Report-Type for transmitting report status.
X-Mbuni-ServiceCode	ServiceCode parameter for MM7/SOAP response packet. If set, its value is sent to the MMSC as the value of the ServiceCode element in the MM7/SOAP message body.
X-Mbuni-MessageClass	Message Class parameter for message.
X-Mbuni-Priority	MMS message priority
X-Mbuni-TransactionID	This special header is used for transaction tracking. It is included in the MMS service request and uniquely identifies the service request transaction. The transaction ID will be included in the delivery or read report when the DLR URL is called, so that the service side can match the DLR to the service request transaction.
X-Mbuni-UAProf	This special header is included in the service request (and DLR URL request) and contains the client User-Agent Profile string as received from the MMC side. (Requires MM7/SOAP v6.x support on the MMC side.)
X-Mbuni-Timestamp	This special header is included in the service request (and DLR URL request) and contains the client submission time stamp (HTTP date format). This header is only included if the User-Agent Profile string is included. (Requires MM7/SOAP v6.x support on the MMC side.)
X-Mbuni-DistributionIndicator	Should be set to the DistributionIndicator value to be passed to the MMSC in the MM7/SOAP message submission.
X-Mbuni-Charged-Party	Should be set to the ChargedParty value to be passed to the MMSC in the MM7/SOAP message submission.

When a post-url is used, you may specify the GCI parameters to be sent in the POST transaction, using % escaepe codes as interpolation markers. The list of supported escape codes is listed below:

Escape Code	Description
%k	Keyword
%i	Image part(s) of the MM
%v	Video part(s) of the MM
%t	Text part(s) of the MM
%s	SMIL part(s) of the MM
%a	Audio part(s) of the MM
%b	Entire, binary coded MM
%z	All part(s) of the MM
%o	Other part(s) of the MM (not text, video, audio, smil, or audio)
%%	Interpolated as %.

Note that the parameter name/value is repeated as many times in the POST data as there are matching parts in the message. That is, if there are three images in the MM and http-post-parameters is image=%i then the parameter image will be passed thrice, with different values. (The CGI script used must therefore be prepared to handle multiple parameters with the same name.)

Because multipart/form-data encoding is used in the HTTP POST transaction, the content type of each element, as well as its name (if present in the MM) are sent to the service URL.

All other URL parameter name/value pairs are passed to the service URL as-is.

Chapter 4: Gateway Architecture

In this section we provide an overview of the gateway architecture.

MMSC Architecture

MMS Proxy

This component (mmsproxy) 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:

• 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.
• 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.
• 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.
• Read receipt: If requested by the sender, a read receipt can be forwarded via this interface. This is queued for delivery to the recipient
• MMbox Upload/Delete/Search: Upload and deletion to/from the user MMbox are supported.
• 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).

1. 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.
2. 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:
   • Converting images in the MM to a format supported by the client
   • Scaling images to fit the screen size of the client
   • Converting audio in the MM to a format supported by the client
   • Converting text to a supported character set
   • Removing unsupported content from the MM
   note that profile data is cached (in storage-directory/UserAgent_Profiles) so as not to have to fetch it each time.
3. The message is then packed and returned to the client as the result of the HTTP request.

Currently, no MMbox quotas are imposed.

• Send Requests: Used to submit messages for onward transmission by Mbuni
• 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.
• Replacement: A submitted message can be changed — the VASP may supply different content, which will then replace any content currently in th queue.

MMS Relay

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:

1. 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.
2. 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.
3. If the message is due for delivery attempt, the global sender determines, for each recipient, how to deliver the message:
   1. 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.
   2. If the the message is destined for a VASP (identified by short code), then it is sent using MM7 protocols to the relevant VASP.
   3. 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)
   4. If the message is destined for a foreign gateway, it is coded as MIME and passed to the mailer for delivery via SMTP
   5. If the message cannot be delivered, the sender is notified.

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:

1. Notification is sent to the recipient client via WAP Push
2. Delivery of other notifications such as delivery and read reports to clients via WAP Push

• 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)
• If the recipient retrieves the message

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.
See mms_queue.h for details.

SMTP/Mail Interface

1. 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)
2. 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)

Utilities

• the recipient list can be a colon-separated list of multiple recipients
• The MMS file may be binary coded, or MIME. The utility tries to guess which by inspecting the first byte of the file.
• From/To addresses are only used for delivery purposes (so internal message headers may not be updated
• The -b 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!)

VAS Gateway Architecture

The VAS gateway consists of a single multi-threaded program mmsbox. This program performs a number of simultaneous functions, including receiving incoming MM from MMSCs, dispatching requests to services, composing and sending responses, and listening for and handling sendmms requests. The key modules of the engine are described below.

The VAS gateway maintains two main message queues: One for incoming messages (received from MMSCs), one for outgoing messages (received from services or the send-mms port). These are maintained in the storage-directory directory, in directories mmsbox_incoming and mmsbox_outgoing respectively. Queue structure is the same as that used by the MMSC component.
A separate directory (mmsbox_dlr) is maintained for storing DLR URLs.

• SendMMS Module: This module listens on the send-mms-port for incoming requests. These are received and turned into MM as described above and written to the outgoing queue. If the sender requested a read or delivery report (by specifying the requisite URL), the relevant URL is stored to the DLR URL store for future use. On success, the interface returns the message submission transaction ID (which is also reported with an DLR).
• MMSC handler module: Receives messages coming from MMSCs, and saves them to the incoming queue. Also watches the outgoing message queue for new messages, which it dispatches to the relevant MMSC based on recipient number routing (if the destination MMSC was not set)
• Service Dispatch: Reads messages from the incoming queue, determines which service to invoke, receives the result and creates a response MM, which is written to the outgoing queue. If the service requested a read or delivery report, the relevant URL is stored to the DLR URL store for future use.

Chapter 5: Tips & Tricks

Passing MSISDNs to Mbuni MMSC

Sample Kannel WAP configuration

We provide a sample Kannel wapbox config below, with some explanation
group = wapbox
bearerbox-host = localhost
log-file = "/tmp/wapbox.log"
syslog-level = none
access-log = "/tmp/wapaccess.log"
timer-freq = 10
map-url = "http://mmsc/* http://localhost:1981/*"

This is a live example that was used in tests. In the example we use:

• wapbox 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
• We increase the timer-freq (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!

Chapter 6: Log Files