++ This chapter provides an overview of MMS +(short for Multimedia Messaging Service) and the Mbuni MMS Gateway. +
+ +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 a crucial part of the +MMS infrastructure in the form of a fully-fledged Open Source MMS Gateway (more +commonly called a MMS Centre).
+ +Mbuni aims to +support all the major MMS interfaces, including phone-to-phone (so-called MM1 +interface), phone-to-email (MM3), inter-MMSC (MM4) and MMS VAS (MM7). The +initial release fully supports the MM1 and MM3 interfaces, and provides +rudimentary support for the MM4 interface. This version also supports +network-side MMBox storage and transactions as specified in the OMA +MMS v1.2 specification.
+ +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.
+ +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.
+ + +The MMS Gateway acts as the +message-switching device in the MMS architecture. The general architecture is +shown below.
+ +
+The elements +shown in the figure can be summarised as follows:
+ +Typically, the +message cycle begins with a user sending a multimedia message (MM) via 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).
+ + +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. When submitting a +message, the MMS client indicates the intended recipient list, but usually not +the sender address, which the MMS Gateway retrieves from the WAP +gateway. Like Email, a single MMS can specify +multiple recipients (MSISDNs and Email addresses), and it is up to the Gateway +to ensure correct delivery to each of the recipients.
+ + +When the gateway +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 gateway receives a message +destined to MMS Clients in the area served by the gateway, 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 gateway 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 gateway 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.
+ + + +Mbuni MMS gateway is a modular software system, designed to +be full-featured, efficient and simple, supporting current generation two-way +multimedia messaging. Feature highlights include:
+ +
+Currently there is no support for VAS via MM7 protocols (SOAP or
+EIAF), but this is planned and should be available soon.
+
+The Gateway is designed and tested to conform to Open Mobile Alliance
+(OMA), WAP and 3rd Generation Partnership Project (3GPP) MMS standards
+including:
+
+
+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 (a patched) Kannel (and therefore fulfil those + dependencies Mbuni shares with it). +
+ + The following additional components are required: +This section +explains the steps required to install the gateway. Currently only installation +from source is provided (binary option coming soon).
+ ++In brief, to install Mbuni, you need to: +
The source code +for Mbuni is available for download from the download area of the website +
+ + + +In order to compile the software, you +will first need to download, patch, compile and install Kannel v1.4.0 from kannel.org:
+ + + +Unpack the kannel +source files using a command like:
+ +bzip2 -cd +gateway-1.4.0.tar.bz2 | tar xf -
+ + +The kannel +sources need to be patched for Mbuni using one of the supplied patch files from +the Mbuni downloads section given above. You can use either one of the patch +files:
+ +Which patch you +choose is a matter of taste. Apply the patch like this
+ + +cd gateway-1.4.0
+
+patch -p1 < ../mbuni-kannel-patch-full
+
+
Then proceed to +compile and install Kannel normally:
+ +
+
+./configure
+
+make install
+
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. 0.9.8). Compile and +install mbuni as follows:
+ +cd
+mbuni-version
+
+
+./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
+ +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@cvs.sourceforge.net:/cvsroot/mbuni loginMbuni consists of +4 programs: +
mmsglobalsender is the main relay server. It routes +incoming messages to email, other MMS gateways, MMS clients/handsets, +etc. mmsmobilesender manages routing messages to MMS clients +using WAP Push, sending of delivery reports, etc. mmsproxy +provides the HTTP interface via which messages are +sent and received by MMS clients. mmsfromemail Is +the email2MMS gateway module. All programs must be configured, and the first +three running for the gateway to function smoothly.
+ + +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:
+
+
To run the gateway, you must run the +three programs listed above (mmsglobalsender, +mmsmobilsender, mmsproxy). mmsfromemail +should be called from your MTA (SMTP Mailer) to convert +and deliver an MMS from an email sender. The order in which they are started +is unimportant. They expect the configuration file to be passed as the last +argument on the command line (default is mmsc.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.
+ +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) and the location of the access log.
+
+
+
+
+
+group =
+core
+log-file
+= log/mmsgw.log
+log-level
+= 0
+
+access-log = log/access.log
+
+
+This should be
+followed by the main MMS gateway configuration group (mmsbox).
+
+
+
+
+group =
+mmsbox
+
+name =
+"My MMSC"
+
+hostname
+= ds.co.ug
+
+host-alias
+= mmsc
+
+local-mmsc-domains=
+mbuni.org,service.com
+
+local-prefixes
+= 075;+25675;25675
+
+send-queue-directory
+= spool/global
+
+mm1-queue-directory
+= spool/mm1
+
+mm4-queue-directory
+= spool/mm4
+
+max-send-threads
+= 5
+
+send-mail-prog
+= /usr/sbin/sendmail -f '%f' '%t'
+
+ ...
+
+
The table below +lists all the configuration directives
+ +| + Variable + Name + | ++ Type + | ++ Description + | +
| group + | ++ mmsbox + | ++ Mandatory + variable + | +
| name + | ++ string + | ++ User-friendly + name for the Gateway, used in notices, etc + | +
| hostname + + | ++ 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 + + | ++ string + | ++ Short form of + hostname. This is used in generating message IDs. It is also used to + generate 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. 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-mmsc-domains + + | ++ List of + Internet domains (comma separated) + | ++ A list of + internet domains that should be considered local to this MMS gateway. Email + or MMS messages received destined to these domains should be treated as local + | +
| local-prefixes + | ++ Number + prefix list + | ++ Number prefixes + that should be considered local. Messages to numbers that match these + prefixes will be delivered locally (via mmsmobilesender) + | +
| + send-queue-directory + + | ++ Directory name + (string) + | ++ Global Queue directory: + Used by mmsglobalsender to store out-going messages. + All messages will be stored here until they can be delivered + | +
| + mm1-queue-directory + + | ++ Directory name + (string) + | ++ Queue directory + for messages destined to (local) MMS clients. Used by mmsmobilesender + | +
| + mm4-queue-directory + + | ++ Directory name + (string) + | ++ Queue directory + for messages destined to or coming from foreign MMS + gateways. mmsglobalsenderfromemail manages this queue + | +
| + mmbox-root-directory + + | ++ Directory name + (string) + | ++ Directory where all user/subscriber MMboxes will be stored. This + directory will contain a set of sub-directories under which user + MMboxes will be stored. Each user MMbox has a maildir-like structure | +
| + max-send-threads + | ++ Number + | ++ How many queue + processing threads to start. A higher value means messages get delivered + faster. + | +
| + send-mail-prog + | ++ 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 + | +
| + 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 (';') + | +
| + maximum-send-attempts + + | ++ integer + | ++ Maximum number + of attempts gateway must make to deliver message before giving up (e.g. + mobile phone is off, email domain is unavailable) + | +
| + default-message-expiry + + | ++ Integer + | ++ Default number + of seconds in which message expires and is purged from queue (if not yet + delivered). This figure is overridden by whatever is in the message. + | +
| + queue-run-interval + + | ++ Real + | ++ How many + seconds between each queue run + | +
| + send-attempt-back-off + + | ++ Integer + | ++ mmsmobilesender uses a form of exponential back-off + when sending notifications to phones. This figure provides the starting + back-off value (in seconds). + | +
| + sendsms-url + | ++ 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 + + | ++ String + | ++ Username to + pass (for authentication) to send-sms URL + | +
| + sendsms-password + | ++ String + | ++ Password to + pass (for authentication) to send-sms URL + | +
| + sendsms-global-sender + | ++ String + | ++ Optional sender + (to field) to use in send sms url + | +
| + mms-port + + | ++ Integer + | ++ Port on which mmsproxy listens for MMS messages from MMS + clients (Default + is 8191). + | +
| + allow-ip + | ++ List of IP + addresses + | ++ List of IP + addresses of hosts allowed to use/access the MMS Port (above). You can use + this for instance to insist that only connections coming via a known/trusted + WAP gateway are serviced. Leave out to allow all machines to connect. + | +
| + mms-client-msisdn-header + | ++ String + | ++ Name of HTTP + Header sent/inserted by WAP gateway 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 + | ++ String + | ++ Name of HTTP + Header sent/inserted by WAP gateway 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-Address. If the header is not + found, we assume the IP address as seen by Mbuni's MM1 interface. + | +
| + allow-ip-type + | ++ 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 + | ++ 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 + | +
| + email2mms-relay-prefixes + | ++ Number list + | ++ 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 local-prefixes setting. If the recipient is not local, + the message should be forwarded on to the relevant foreign MMS gateway, only + if the recipient number matches one of the prefixes in this comma-separated + list. + | +
| + ua-profile-cache-directory + + | ++ Directory name + (string) + | ++ User Agent + Profile Cache: When an MMS client requests (via HTTP GET command) a message + about which it has been notified, it sends its profile URL (such as + http://nds.nokia.com/uaprof/N3650r100.xml + for the Nokia 3650) as part + of the HTTP request headers. The gateway should fetch the URL presented and + parse it to figure out the client's capabilities (so-called User Agent + Profile). It would be inefficient to fetch the profile data each time from + an external server, therefore the gateway caches fetched profile data in the + directory specified here. Cache entries are never expired (which is unlikely + to be a problem). Some badly behaved MMS clients to do not submit a profile + URL. In this case, the gateway relies on the HTTP + Accept request headers to determine its + capabilities. + | +
| + billing-library + | ++ 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. + | +
| + billing-module-parameters + | ++ 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. + | +
| + resolver-library + | ++ String + | ++ Optional + library containing functions for resolving recipient MSISDN to hostname + of Proxy-Relay that should handle the message. 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. + | +
| + resolver-module-parameters + | ++ 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 + | ++ 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. + | +
| + detokenizer-module-parameters + | ++ 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 + | ++ 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 2-3 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). + | +
| + prov-server-sub-status-script + | ++ string + | ++ Subscriber + database interface script 2: This script is called + by mmsmobilesender 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 + mmsmobilesender will deliver the message (see below). + | +
| + notify-unprovisioned + | ++ 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 + | ++ 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 + | ++ String + | ++ Message to send + to devices that are not provisioned for MMS (only if + notify-unprovisioned is true). + | +
| + mms-message-too-large-txt + | ++ 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 + | ++ 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 + | ++ 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. + | +
Foreign MMS +Gateways are configured using one or more mmsproxy groups:
+ +| + 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 + | +
+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 MIME and +sent via SMTP to the proxy. +
+ +
+ In this section we provide an overview of the gateway architecture.
+
+
+
+As indicated, there are four components to the gateway: The Global
+Sender (mmsglobalsender), Mobile Sender (mmsmobilesender), Proxy
+(mmsproxy) and SMTP/Email Interface (mmsfromemail). We describe the
+function of each of these in turn.
+
+ +This component (mmsproxy) is the main point of interaction between the +gateway and MMS clients. It provides an HTTP interface through which +clients can send MMS messages. The message types expected on this +interface are typically: +
+Currently, no MMbox quotas are imposed. +
++ +This component handles +
+
+
+
+
+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:
+