Mbuni

   Home
   Status
   Documentation
   Downloads
   Mailing Lists
   Links
   License
   Commercial


 

Mbuni: Open Source MMS Gateway

User Guide

This document describes the installation and usage of the MMS Gateway.

Table of Contents


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

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 module:
  • Image conversion tools required by the content adaptation module:
  • 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.
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, 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:

tar xzf mbuni-version.tgz

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

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 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:

cvs -d:pserver:anonymous@mbuni.cvs.sourceforge.net:/cvsroot/mbuni login
followed by
cvs -z3 -d:pserver:anonymous@mbuni.cvs.sourceforge.net:/cvsroot/mbuni co -P mbuni
you can then install as above.

Mbuni consists of 3 programs:

  • mmsc
  • mmsfromemail
  • mmsbox
which are by default installed in /usr/local/bin

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
This AMR encoder is not very efficient but it works (which is important!)

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

Configuring Mbuni using a Loadable Module

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

Configuration Items

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.

Variable Name     Mode     Type     Description    
group     ALL     mbuni     Mandatory variable    
name     ALL     string     User-friendly name for the Gateway, used in notices, etc    
hostname     ALL     string     Local hostname. This is added as a qualifier to the sender address when MMS is forwarded to Email or to a foreign MMSC via SMTP. Defaults to localhost    
host-alias     MMSC     string     Short MMC hostname. This is used in generating message IDs as well as the message retrieval URL (sent as part of the MMS notification): For instance if you have this as mmsc then the retrieval URL will have the form http://mmsc/msgtoken (no port is added). Be sure to keep this value short (as some handsets do not like long URLs in MMS notifications), and it must not include non-alphanumeric characters as this can screw up URL location parsing. If you do not supply a host alias, the gateway will create a long form URL (http://hostname:port/msgtoken) when it sends notifications    
local-prefixes     MMSC     Number prefix list     Number prefixes that should be considered local. Messages to numbers that match these prefixes will be delivered locally (via mmsrelay)    
mmsc-services     MMSC     Comma-separated list     Comma-separated list of MMSC services to be started/activated on this host. List should contain one or more of the following items MM1, MM7, Relay: These activate MM1 message processing, MM7 message processing, and the Relay function respectively. To start all services, leave out this directive entirely, or set it to All.    
smtp-relay     ALL     String     SMTP relay host in the form host:port. (If port is not included, defaults to 25.) If set, mmsbox uses this to relay all outgoing MM4 and email requests. Otherwise the sendmail command defined above is used.    
storage-directory     ALL     Directory name (string)     Directory where Mbuni creates message queues, MMBoxes, and the User Agent profiles cache. Mbuni creates a set of sub-directories in here for each function    
max-send-threads     ALL     Number     How many queue processing threads to start. A higher value means messages get delivered faster.    
send-mail-prog     ALL     String     Command to use for sending email messages (MMS-to-email or to foreign MMS gateways via SMTP). This command can include variables: %f – replaced with the message from address, %t – replaced with the recipient address (RFC 822 compliant), %s – the message subject, %m – the message ID. (NOTE: Special shell characters — &, |, $, (, ), and so on &mdash are escaped after variable substitution, hence parameter quoting is not necessary.)    
strip-prefixes     ALL     Number list     A semi-colon (;) separated string of prefixes that should (if found) be stripped off the phone number prior to number normalisation as described below. Only the first prefix that matches will be stripped.    
unified-prefix     ALL     Number list     A string to unify received phone numbers, so that routing works correctly. Format is that first comes the unified prefix, then all prefixes which are replaced by the unified prefix, separated with comma (','). For example "+256,000256,0;+,000" should ensure correct UG prefixes. If there are several unified prefixes, separate their rules with semicolon (';')    
maximum-send-attempts     ALL     integer     Maximum number of attempts gateway must make to deliver message before giving up (e.g. mobile phone is off, VAS service is down, email domain is unavailable)    
mm1-maximum-notify-attempts     MMSC     integer     Maximum number of attempts gateway must make to notify a device of a pending message on the MM1 interface, before giving up. Defaults to maximum-send-attempts    
mmsbox-maximum-request-attempts     VAS GW     integer     Maximum number of attempts VAS Gateway must make to fetich a MMS service URL before giving up. Defaults to maximum-send-attempts    
default-message-expiry     ALL     Integer     Default number of seconds in which message expires and is purged from queue (if not yet delivered). This value is overridden by whatever is in the message.    
max-message-expiry     ALL     Integer     Maximum age (in seconds) allowed for all messages. If set, this determines when messages must mandatorily be expired. This cannot be overridden by the expiry value requested in the message.    
queue-run-interval     ALL     Real     How many seconds between each queue run    
mm1-queue-run-interval     MMSC     Real     How many seconds between each queue run for the MM1 queue. Defaults to the value given above (queue-run-interval)    
queue-manager-module     ALL     String     Library to handle queue/message storage and processing (see mms_queue.h for details)    
queue-module-init-data     ALL     String     Initialiser data for queue/message storage engine.    
send-attempt-back-off     ALL     Integer     The exponential back-off factor to employ on subsequent message delivery attempts, when a delivery attempt fails.    
sendsms-url     MMSC     String     URL of the service through which SMS can be sent to a mobile subscriber (e.g. for WAP Push). It is expected that this url expects/supports Kannel-style send-sms parameters (udh, from, to, text, etc.)    
sendsms-username     MMSC     String     Username to pass (for authentication) to send-sms URL    
sendsms-password     MMSC     String     Password to pass (for authentication) to send-sms URL    
sendsms-global-sender     MMSC     String     Optional sender (to field) to use in send sms url    
mms-port     MMSC     Integer     Port on which mmsproxy listens for MMS messages from MMS clients (Default is 8191).    
mm7-port     MMSC     Integer     Port on which mmsproxy listens for MM7 requests from Value Added Services providers. If this port is not supplied, the MM7 sub-system is not started.    
mm4-port     MMSBOX     Integer     Port on which mmsbox listens for MM4 requests from Value Added Services providers. If this port is not supplied, the MM4 receiver sub-system is not started.    
mmsbox-mm4-domain-number-prefixes     MMSBOX    
allow-ip     ALL     List of IP addresses     List of IP addresses of hosts allowed to use/access the Send MMS Port (MM1 interface for MMSC or SendMMS port for VAS Gateway). You can use this for instance to insist that only connections coming via a known/trusted WAP gateway are serviced by the MMSC. Leave out to allow all machines to connect.    
deny-ip     ALL     List of IP addresses     List of IP addresses of hosts not allowed to use/access the Send MMS Port (MM1 interface for MMSC or SendMMS port for VAS Gateway).    
mms-client-msisdn-header     MMSC     String     Comma-separated list of HTTP request headers MMSC should look for to determine sender MSISDN. WAP gateway should insert one of these headers as part of MMS request to indicate MSISDN of sender. Note that typically the MMS client does not indicate its MSISDN in the MMS message, it is up to the gateway to discover this and insert it. We rely on the WAP gateway to provide the MSISDN as an HTTP request header (default header name is X-WAP-Network-Client-MSISDN)    
mms-client-ip-header     MMSC     String     Comma-separated list of HTTP request headers MMSC should look for to determine sender IP address. WAP gateway or HTTP proxy should insert one of these headers as part of MMS request to indicate IP Address of sender. Similar to the above, if the MSISDN is not set, then we assume that the client is identified by IP address, which we extract from the request headers (using this header). Default header name is X-WAP-Network-Client-IP. If the header is not found, we assume the IP address as seen by Mbuni's MM1 interface.    
allow-ip-type     MMSC     Boolean     Set this to false to prevent Mbuni accepting and processing messages from senders identified by IP address (i.e. not by MSISDN). Default: True.    
optimize-notification-size     MMSC     Boolean     Set this to true make Mbuni attempt to squeeze MMS notifications in one WAP Push SMS, by leaving out subject and sender fields. Default: false    
content-adaptation     MMSC     Boolean     Set this to false to turn off content adaptation in Mbuni. This will cause the MMSC to ignore client capabilities when sending messages, and could cause problems so beware! Default: true    
send-dlr-on-fetch     MMSC     Boolean     The MMSC sends a confirmation delivery report to the sender only when the recipient confirms receipt on the MM1 interface. If you want a report as soon as the recipient fetches the message (before receipt of the acknowledge-ind MM1 packet) set this to true. Default: false    
email2mms-relay-hosts     MMSC     Number list     A semi-colon separated list of hosts/domains. When MMS is received via SMTP, the gateway needs to determine whether it is for a local or a foreign recipient. To determine if the recipient is local recipient, we use the resolver module, if supplied. (Note that default resolution uses local-prefixes setting to determine if the recipient is local, returning the local MMSC name, if not, then it checks each of the defined relays to see if the recipient address is for one of them, by checking the prefixes, returning the matching proxy/relay name.) The resolver should return a host name that is matched against this setting. If any name matches, the message is queued, otherwise it is discarded.    
billing-library     MMSC     String     Optional library containing billing and CDR functions. This library is loaded at runtime and should contain functions to be called to effect billing and CDR generation. See mms_billing.h for details. (builtin:shell supported as a special built-in library.)    
billing-module-parameters     MMSC     String     Parameters to pass to the billing module specified above when it is loaded. This is a generic string whose interpretation is entirely up to the module.    
mmsbox-cdr-module     VAS GW     String     Optional library containing CDR functions for mmsbox. This library is loaded at runtime and should contain functions to be called to effect CDR logging for the VAS Gateway. See mmsbox_cdr.h for details. (Default behaviour is to log CDR to tab-delimited file storage-dir/mmsbox-cdr.asc)    
mmsbox-module-parameters     VAS GW     String     Parameters to pass to the mmsbox CDR module specified above when it is loaded. This is a generic string whose interpretation is entirely up to the module.    
resolver-library     ALL     String     Optional library containing functions for resolving recipient MSISDN to hostname of Proxy-Relay that should handle the message (on the MMC side) or the connected MMC that should (internally) route an incoming MM7 message (on the MMSBOX side).
For Mbun MMSC, supplying this libary over-rides the local-prefixes setting given above. If the Proxy-Relay hostname returned by the module is the hostname of the local MMSC, then the recipient is considered local. See mms_resolve.h for details. (See mmsbox_resolve.h for usage under mmsbox). (builtin:shell supported as a special built-in library.)    
resolver-module-parameters     ALL     String     Parameters to pass to the Resolver module specified above when it is loaded. This is a generic string whose interpretation is entirely up to the module.    
detokenizer-library     String     MMSC     Optional library containing functions for finding MSISDN from request URL sent by client. The last part of URL is treated as a string that is interpreted by the library and transformed into an MSISDN. This libary is only a fall-back in case the default sender address resolution fails. See mms_detokenize.h for details. (builtin:shell supported as a special built-in library.)    
detokenizer-module-parameters     MMSC     String     Parameters to pass to the De-tokenizer module specified above when it is loaded. This is a generic string whose interpretation is entirely up to the module.    
prov-server-notify-script     MMSC     String     Subscriber database interface script 1: This script will be called by the gateway to notify the subscriber database of per-subscriber events such as when a subscriber sends a message, successfully fetches a message, etc. This script is called with 4 arguments. Argument 1 is one of fetched, sent, failedfetch; argument 2 is the subscriber MSISDN; argument 3, in case of a failed fetch provides a description of the error (e.g. message expired); argument 4 is the message ID (if any). NOTE: Any missing argument is passed as a quoted empty string for ease of parsing in the script.    
prov-server-sub-status-script     MMSC     string     Subscriber database interface script 2: This script is called by mmsrelay to determine whether the recipient's device supports MMS. The script should exit with a value of 0 to indicate that the device does not support receipt of MMS notifications; 1 to indicate that the device supports MMS; -1 if the subscriber is not known or not provisioned for MMS. The return value determines how mmsrelay will deliver the message (see below).    
notify-unprovisioned     MMSC     Boolean     Whether subscribers who are not provisioned for MMS should receive any notifications (e.g. SMS) when an MMS message is received for them.    
mms-notify-text     String     MMSC     Message to send to device that does not support MMS, when a message is received for the user. This message is sent as plain SMS via the Send SMS URL specified above.    
mms-notify-unprovisioned-text     MMSC     String     Message to send to devices that are not provisioned for MMS (only if notify-unprovisioned is true).    
mms-message-too-large-txt     MMSC     String     If a device tries to fetch a message, which during content adaptation is determined to be too large for the target device (based on capabilities data supplied by the device), the message is discarded, this text is sent to the device instead as part of an MMS message.    
mms-to-email-html     MMSC     string     When an MM is destined for email, we must format it to make it more suitable for email readers. (For instance, the SMIL part of the MM will make no sense to most email readers.) The gateway formats the message as follows: It generates a multi-part MIME message with the main part being an HTML entity in which MM parts are embedded. The text given here is tagged at the bottom of the HTML.    
mms-to-email-txt     MMSC     String     This string is placed in the MMS converted to email as an alternative to the HTML part, for email clients that do not support HTML.    
mms-to-email-default-subject     MMSC     String     This string is used as the default message subject when sending MMS to email in the event that no subject is defined in the message    
sendmms-port     VAS GW     number     The port on which the MMS VAS gateway listens for incoming MMS send requests. (Optional.)    
sendmms-port-ssl     VAS GW     Boolean     Set to true if SendMMS port of VAS Gateway should be secure (HTTPS). This is only supported if Mbuni is compiled with SSL support.    
mmsbox-mt-filter-library     String     VAS GW     Optional library to be used for filtering/transforming all content (except SMIL), while building the MT MMS from a SMIL file (or from a file). This is useful if say you want to implement custom filtering/transformation of content (e.g. DRM wrappers around selected content). Note that only elements referenced by URL/file name (e.g. within the returned SMIL or if fetched by the send-mms interface via URL) are filtered. See mmsbox_mt_filter.h for details. Also see mm7-mt-filter-params config variable in the VAS specific config section.    
mmsbox-admin-port     Integer     VAS GW     Optional port where mmsbox listens for administrative commands (see below).    
admin-port-ssl     Boolean     VAS GW     Whether admin port (above) is SSLed.    
admin-allow-ip     string     VAS GW     If set, admin requests will only be allowed if originated by one of the IP addresses listed here (semi-colon separated list).    
admin-deny-ip     string     VAS GW     If set, admin requests will not be allowed if originated by one of the IP addresses listed here (semi-colon separated list).    
admin-password     string     VAS GW     Authentication password for admin port    

Using the VAS Gateway Administration Interface

Mbuni VAS Gateway provides an administration interface (HTTP-based) to view the status of MMSC connections, start or stop all or a specific MMSC connection. (This is especially useful if the configurations are being loaded dynamically using a configurations module.) To use the interface, you load a URL of the form:

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

If admin-port-ssl was set to yes then you must use https://. The server_admin_port and admin_password should be given as specified in the configuration file. Supported command_uri values are:
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.
The response in each case is XML-formatted. For the status command, the result is the following form:

<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>
The information includes basic MMSC configuration data, connection uptime, time of last received PDU, received and sent PDUs, errors. For the start command, the response is the same as that for status if the command succeeds, otherwise the result is of the form:
<Start-Mmsc><Error>error message</Error></Start-Mmsc>
For the stop command the result is of the form:
<Stop-Mmsc><Success/></Stop-Mmsc>
or
<Stop-Mmsc><Failed/></Stop-Mmsc>
depending on whether the command succeeded or failed.

Built-in billing, resolver and detokenizer modules

Mbuni supports one type of built-in modules: Shell script handlers. Each expect a parameter that is a shell script that is used as follows:
  • 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

This section describes extra configuration sections that should only be used when Mbuni is configured to operate as an MMSC.
MM7 Configuration

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


group = mms-vasp
vasp-id = newcorp
type = soap
short-code = 100
vasp-username = newscorp
vasp-password = news123
vasp-url = http://mmsc1:pass@example.vasp.com:8080/mm7

Variable Type Description
group String Mandatory: mms-vasp
vasp-id String User friendly name
type String This should be one of: soap, eaif
mm7-version String Optional. The MM7 version to use on this interface. (defaults are "5.3.0" for XML/SOAP, "3.0" for EAIF.) For SOAP, this is used as the value for the MM7Version XML node. For EAIF it is reported in the HTTP headers.
mm7-soap-xmlns String Optional. The namespace URI for the "mm7:" XML namespace. Only valid for MM7/SOAP, and is used in the SOAP message to identify the namespace for all MM7/SOAP specific elements. Default value is http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-MM7-1-0
use-mm7-soap-namespace-prefix Boolean Optional. Set to true if the MM7/SOAP tags should have the mm7: prefix. Some MMC/VAS GW implementations do not seem to like this, so you can set this to false to see what mileage you get.
short-codes Number Semi-colon separated list of short numbers for this VASP: Messages received by Mbuni to any of these numbers are routed to the VASP via MM7.
vasp-url String Outgoing messages to the VASP are sent via this URL (using HTTP POST)
vasp-username String Incoming HTTP authentication: The username used by the VASP to authenticate itself to Mbuni when sending data
vasp-password String Incoming HTTP authentication: The password used by the VASP to authenticate itself to Mbuni when sending data to the VASP
mms-to-email-handler Boolean Set this to true if all MMS destined to email addresses should be routed via this VASP by the MMC. The message will be packed as an MM7 message and handed over. This could be used to customise the appearance of the email.
mms-to-local-copy-handler Boolean Set this to true if all MMS destined to local recipients (e.g. mobiles) should be copied to this VASP. This is useful if you want to implement a web-based viewer (as a backup solution) for your users.
send-uaprof String Optional. This parameter determines whether the User Agent string is sent to the VASP (for MM7/SOAP only, as part of UACapabilities entity). Set to ua to send the full client User Agent string (i.e. the value of the HTTP request header User-Agent). Set to url to send the client Profile URL (i.e. the value of the X-WAP-Profile HTTP request header). Leave empty not to send any info. Note that this field is only sent in MO transactions (e.g. message delivery, delivery reports).
Note that currently only HTTP Basic Authentication Scheme is supported by Mbuni (for both incoming and out-going requests).
MM4 Configuration

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


group = mmsproxy
name = "A test mms proxy"
host = test.com
allowed-prefix = "075"
denied-prefix = "077"


Variable Type Description
group String Mandatory: mmsproxy
name String User friendly name
host String Fully qualified domain name
allowed-prefix Number list List of recipient number prefixes that can be delivered via this Proxy
denied-prefix Number list List of recipient number prefixes that cannot be delivered via this proxy
confirmed-delivery Boolean Specifies whether to use request MM4 acknowledgement from the recipient MMC for each message. Default is true.
send-mail-prog     String     Command to use for sending messages (via email) to foreign MMS gateways. This command over-rides, for this proxy, the global send-mail-prog setting, and provides the same variable substitutions.    
strip-prefixes     Number list     A semi-colon (;) separated string of prefixes that should (if found) be stripped of the phone number prior to number normalisation and message sending, as described below. Only the first prefix that matches will be stripped.    
unified-prefix     Number list     A string to unify received phone numbers, so that routing works correctly. Format is that first comes the unified prefix, then all prefixes which are replaced by the unified prefix, separated with comma (','). For example "+256,000256,0;+,000" should ensure correct UG prefixes. If there are several unified prefixes, separate their rules with semicolon (';')    

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:

group = mmsc
id = testone
group-id = mmc1
mmsc-url = http://mbuni:test@192.168.129.52:8080/eaif
incoming-username = user
incoming-password = pass
incoming-port = 10002
type = eaif

Supported configuration parameters are:
Variable Type Description
group String Mandatory: mmsc
id String Mandatory: Identifying name for this connection (used in logs for instance). For MM7 connections it also used as the VASP ID parameter, when vasp-id is not specified.
vasp-id String Optional: For MM7 connections it is used to explicitly set the VASP ID parameter. If left unspecified, the id is used instead.
group-id String Optional: Can be used to group different MMCs for purposes of receiving DLRs, etc.
type String Mandatory: Protocol spoken by this MMSC, one of soap for 3GPP MM7 SOAP, eaif for Nokia EAIF protocol, mm4 for 3GPP MM4, http for special HTTP-based inter-mmsbox message relay (see below), mm1 for GPRS/3G modem access to an operator MMSC, or custom for a custom implementation handled by a loadable module (see mmsc-library below).
For type = http the VAS GW will forward the message to the URL provided using HTTP POST, with CGI parameters: mms – the binary mms, from – the sender address, to – the recipient address. This allows fast inter-mmsbox message exchange.
For type=mm1 it is expected that mmsbox will send/receive messages directly from the operator using an attached modem. To receive MMS, Kannel (or similar SMS Gateway) must pass all received SMS to Mbuni via the MMSC port. To send MMS, Mbuni will use the mm1-sms-off-command (see below) to temporarily shutdown the SMS Gateway, and then use the modem to send MMS
mm7-version String Optional. The MM7 version to use on this interface. (defaults are "5.3.0" for MM7/SOAP, "3.0" for EAIF.) For SOAP, this is used in the MM7Version tag. For EAIF it is reported in the HTTP headers.
mm7-soap-xmlns String Optional. The namespace URI for the "mm7:" XML namespace. Only valid for MM7/SOAP, and is used in the SOAP message to identify the namespace for all MM7/SOAP specific elements. Default value is http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-MM7-1-0
use-mm7-soap-namespace-prefix Boolean Optional. Set to true if the MM7/SOAP tags should have the mm7: prefix. Some MMC/VAS GW implementations do not seem to like this, so you can set this to false to see what mileage you get.
default-vasid String Optional. The default VAS ID for this connection. Only valid for MM7/SOAP.
mmsc-url String Mandatory: URL address for the MMSC. Used for outgoing messages. When type is MM4, this must be set to the MM4 domain. If you wish to support email senders, create an mmsc group where the domain is set to *.
maximum-request-size int Optional: Maximum request size that this interface will receive. Larger requests will be dropped. Default is 500k.
incoming-port Number Port at which Mbuni listens for incoming messages from MMSC. Not used for MM4 incoming connections (mm4-port is used instead). For mm1 MMSCs this is the port to which (MO) MMS notification messages should be routed. In this case, the notification SMS should be contained in a text CGI parameter.
strip-domain boolean Optional: MM4 MMSC connections only: Whether to strip the domain name from the received sender/recipient addresses (if they are phone numbers)
incoming-user string Username to be used by MMSC to authenticate itself to Mbuni for incoming connections. (Using HTTP basic authentication scheme.)
incoming-password string Password to be used by MMSC to authenticate itself to Mbuni for incoming connections
incoming-port-ssl Boolean Specifies whether incoming port is secure (i.e. incoming requests use secure HTTP). Only supported if Mbuni is compiled with SSL support.
allow-ip     List of IP addresses     List of IP addresses of hosts allowed to use/access the incoming MMS port
deny-ip     List of IP addresses     List of IP addresses of hosts not allowed to use/access the incoming MMS port    
allowed-prefix Number list List of recipient number prefixes that can be delivered via this MMSC (used for routing out-going messages)
denied-prefix Number list List of recipient number prefixes that cannot be delivered via this MMSC
allowed-sender-prefix Number list List of sender number prefixes that can use this MMSC
denied-sender-prefix Number list List of sender number prefixes that cannot use this MMSC
max-throughput Number Maximum number of messages per second (outgoing) that this MMSC can handle.
max-recipients Number Maximum number of recipients per transaction for this MMSC (ignored for custom MMSC type). This controls how many To addresses are included in each send transaction. Default is 1. Note that failure of of the MMSC to accept any of the recipients can result in the entire send request being retried.
strip-prefixes     Number list     A semi-colon (;) separated string of prefixes that should (if found) be stripped off the phone number prior to sending message. Only the first prefix that matches will be stripped.    
reroute Boolean If set to true all messages received from this MMSC are routed directly to the outgoing queue (never to an MMS Service).
reroute-mmsc-id String If set (and reroute is true) then all messages received on this connection will be sent out directly via the MMSC with the ID set here.
reroute-add-sender-to-subject Boolean If reroute is true and this flag is also true then all messages received on this connection are re-routed, and the original sender is added to the message subject line
mm7-mt-filter-params String Parameter(s) to be passed to the init function of the MT MMS filter module specified in mmsbox-mt-filter-libary above. (See mmsbox_mt_filter.h for details.) The init function is called once for each MMC connection, and must return no error, otherwise no filtering will be done on MT messages via this MMC.
mmsc-library String If MMC type is custom, this parameter provides the dynamic shared object (DSO) library to be loaded to provide connectivity to the MMC. (See mmsbox_mmsc.h for details on required exported symbols.)
custom-settings String If MMC type is custom, this parameter provides settings to be provided to the dynamic shared object (DSO) library loaded to provide connectivity to the MMC. (See mmsbox_mmsc.h for details on how this is used.)
no-sender-address Boolean If set to true Mbuni will not set the SenderAddress tag in the SOAP Message Submit XML packet
mm1-http-proxy String HTTP Proxy (in the form host:port to be used when sending MMS to the MMSC. (mm1 MMSC only)
mm1-http-proxy String HTTP Proxy (in the form host:port) to be used when sending MMS to the MMSC. (mm1 MMSC only.)
mm1-gprs-on-command String Command mmsbox will call to start a GPRS/3G operator connection when sending MT MMS via the mm1 type. This command typically invokes pppd with suitable parameters. NOTE: This command should return immediately (i.e. it shouldn't block). (mm1 MMSC only.)
mm1-gprs-off-command String Command mmsbox will call to stop the GPRS/3G operator connection after sending MT MMS via the mm1 type. This command typically kills the pppd in charge of the connection started with the command above. (mm1 MMSC only.)
mm1-gprs-pid-command String Command mmsbox will call to determine the ID of the process controlling the GPRS/3G operator connection after it is started. If this option is provided, then a kill(2) will be used to terminate the GPRS/3G connection, rather than the mm1-gprs-off-command. (mm1 MMSC only.)
mm1-sms-off-command String Command mmsbox will call to stop the SMS Gateway modem link, just before starting the GPRS/3G operator connection. Because MO MMS is received as (SMS) notifications, the modem must be shared with the SMS Gateway (such as Kannel). When a notification is received by mmsbox, we must shutdown the SMS Gateway's connection to the modem (typically, if using Kannel, this means a call to the admin interface), fetch the MMS (via a GPRS/3G connection initiated using the same modem), and then turn SMS reception back on (see below). (mm1 MMSC only.)
mm1-sms-on-command String Command mmsbox will call to start the SMS Gateway modem link, once mmsbox has completed fetching MO MMS or sending MT MMS via a GPRS/3G operator connection. Typically, if using Kannel, this means a call to the Kannel admin interface to start the specific modem SMSC link. (mm1 MMSC only.)
mm1-ua-string String HTTP USer Agent String to send to MMSC in HTTP requests (e.g. "Mozilla/5.0 (SymbianOS/9.4;U; Series60/5.0 Nokia5800d-1/52.50.2008.24; Profile/MIDP-2.1Configuration/CLDC-1.1 ) AppleWebKit/413 (KHTML, like Gecko) Safari/413" to fake a request as a Nokia 5800). This is useful if the MMSC transcodes MT MMS based on the receiver type. (mm1 MMSC only.)
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:

group = send-mms-user
username = tester
password = foobar
faked-sender = 100

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


How Response Content Is Interpreted

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.


X-Mbuni Headers

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.


HTTP POST Parameters

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

As indicated, there are three components of the MMSC: The Relay (mmsrelay), the Proxy (mmsproxy) and SMTP/Email Interface (mmsfromemail). We describe the function of each of these in turn.

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).
All the above messages are sent to the proxy as the body of an HTTP POST request. Messages are retrieved by supplying the message URL in an HTTP GET request. When such a request is received, the proxy:
  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.

From VASPs mmsproxy expects and processes:
  • 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.

Both SOAP and EAIF MM7 requests are supported.
This component must always be running.

MMS Relay
The Relay manages routing of all messages (to phone, email, VASP).

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
SMS is used as the transport for WAP Push messages, if the recipient is an MSISDN, otherwise UDP is used.
The Relay maintains a separate queue for messages pending delivery. At set intervals (see configuration section), it sends notifications to the recipient. It keeps sending notifications until the message is fetched or the client indicates that it wishes to defer message retrieval. A back-off mechanism is utilised to prevent flooding of notifications. A message will be removed from the queue if:
  • 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
The SMTP/Mail interface receives MMS from the MTA and routes them depending on recipient or sending proxy. Specifically:
  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)

This interface should be invoked from your MTA as follows:

mmsfromemail -f from_address -t recipient_address -s sender_mmsc_hostname [-x] [-n] conf_file

The -n flag may be used to prevent stripping of the host/domain part from the sender address. The -x flag causes the sender address to be stripped of the TYPE=PLMN part.
Note that no IP-based security is provided at this interface. It is expected that security measures (e.g. firewalls, etc) will have been setup to ensure that messages can only reach the MTA and be handed over to this interface if they are legitimate.

Utilities
We plan to add a number of utilities to the gateway. The first of these is mmssend.

mmsssend can be used to submit (inject) a message into the global queue. It should be invoked as follows:

mmssend -f from_address -t recipient_list -m mmsfile [-b] conf_file

Notes:
  • 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!)
The message is placed in he global queue with expiry set to the system maximum, and the queue entry ID is printed to standard output.

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

This section is a compilation of tips and tricks on making Mbuni work better for you

Passing MSISDNs to Mbuni MMSC

As indicated earlier, Mbuni expects the MSISDN to be sent to it as a special HTTP request header. There are however times when it is either not possible, or not practical to insert the header into the MMS request. For such cases, Mbuni provides another way to specify the sender MSISDN: The last part of the URL passed in the HTTP transaction is passed to the De-tokenizer module (if specified), which should return a valid sender address. So for instance you can configure a clients to use a URL like http://mmsc/xYz12R2 as the MMSC address, and Mbuni will pass xYz12R2 to the de-tokenizer module, which must return the sender address. Mbuni will only do this it has failed to find the address request header.
If no sender address (MSISDN) is found, Mbuni assumes that the MMS client is identified by IP address, and attempts to look up the IP address of the sender (see config section) and use that as the sender address. You can block this by specifying allow-ip-type = false

Note that because of the above feature, you need to configure your WAP gateway and Mbuni IP security to ensure the system is not easily spoofed.

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

The gateway writes a log file of important actions to the log file configured. Message traffic is written to the access log in a standard format.