Home
   Status
   Documentation
   Downloads
   Mailing Lists
   Links
   License
   Commercial

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:

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:

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.

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:

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:

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