Appendix C Short Message Service (SMS)

This chapter describes how to implement the Short Message Service (SMS) on the Sun^TM ONE Messaging Server. It covers the following topics:

• C.1 Introduction

• C.2 SMS Channel Theory of Operation

• C.3 SMS Channel Configuration

• C.4 SMS Gateway Server Theory of Operation

• C.5 SMS Gateway Server Configuration

• C.6 SMS Gateway Server Storage Requirements

C.1 Introduction

Sun Java System Messaging Server implements email-to-mobile and mobile-to-email messaging using a Short Message Service (SMS). SMS can be configured to be either one-way (email-to-mobile only) or two-way (both email-to-mobile and mobile-to-email). To enable one-way service only, you must add and configure the SMS channel. To enable two-way service, you must add and configure the SMS channel, and in addition, configure the SMS Gateway Server.

For both one- and two-way SMS, the generated SMS messages are submitted to a Short Message Service Center (SMSC) using the Short Message Peer to Peer (SMPP) protocol. Specifically, the SMSC must provide a V3.4 or later SMPP server that supports TCP/IP.

Figure C–1 illustrates the logical flow of messages for both one-way and two-way SMS.

Figure C–1 Logical Flow For One-Way and Two-Way SMS

C.1.1 One-Way SMS

To enable one-way service, the Messaging Server implements an SMPP client (the MTA SMS channel) that communicates with remote SMSCs. The SMS channel converts enqueued email messages to SMS messages as described in C.2.2 The Email to SMS Conversion Process of multipart MIME messages as well as character set translation issues.

Operating in this capacity, the SMS channel functions as an (SMPP) External Short Message Entity (ESME).

C.1.1.1 Two-Way SMS

Two-Way SMS enables the mail server not only to send email to remote devices, but allows for receiving replies from the remote devices and for remote device email origination.

Enabling two-way SMS service requires both the MTA SMS channel (SMPP client), as explained in the previous topic, and the SMS Gateway Server. Sun Java System Messaging Server installs an SMS Gateway Server as part of its general installation process, which you must then configure. The SMS Gateway Server performs two functions:

• SMPP relay

  The SMS Gateway Server acts as a transparent SMPP client between the MTA SMS channel and SMSCs. However, in addition, while acting as a relay, the SMS Gateway Server generates unique SMS source addresses for relayed messages, and saves the message IDs returned by the remote SMSCs for later correlation with SMS notification messages.

• SMPP server

  The SMS Gateway Server acts as an SMPP server to receive mobile originated SMS messages, replies to prior email messages, and SMS notifications. The SMS Gateway Server extracts destination email addresses from the SMS messages using profiles that define the conversion process. Profiles also describe how to handle notification messages returned by remote SMSCs in response to previously sent email-to-mobile messages.

Sun Java System Messaging Server does not support the two-way SMS on the Windows platform.

C.1.2 Requirements

This manual assumes that you have read Logica CMG’s SMPP specification, and the SMPP documentation for your SMSC.

In order to implement SMS, you must have the following:

• Sun Java System Messaging Server 6 or greater. (One-way SMS is also implemented in iPlanet Messaging Server 5.2.)

• The SMSC must support SMPP V3.4, or later, over TCP/IP and there must be TCP/IP connectivity between the host running Messaging Server and the SMSC.

For storage planning information for the SMS Gateway Server, see C.6 SMS Gateway Server Storage Requirements

C.2 SMS Channel Theory of Operation

The SMS channel is a multi-threaded channel which converts queued email messages to SMS messages and then submits them for delivery to an SMSC.

The following channel operation topics are covered in this section:

• C.2.1 Directing Email to the Channel.

• C.2.2 The Email to SMS Conversion Process.

• C.2.3 The SMS Message Submission Process.

• C.2.4 Site-defined Address Validity Checks and Translations

• C.2.5 Site-defined Text Conversions

C.2.1 Directing Email to the Channel

When the SMS channel is configured as per C.3 SMS Channel Configuration purposes of discussion, let us assume that the host name sms.siroe.com is a host name associated with the channel. In that case, email is directed to the channel with an address of the form:

local-part@sms.siroe.com

in which local-part is either the SMS destination address (for example, a wireless phone number, pager ID, etc.) or an attribute-value pair list in the format:

/attribute1=value1/attribute2=value2/.../@sms.siroe.com

The recognized attribute names and their usages are given in Table C–1. These attributes allow for per-recipient control over some channel options.

Some example addresses:

123456@sms.siroe.com
/id=123456/@sms.siroe.com
/id=123456/maxlen=100/@sms.siroe.com
/id=123456/maxpages=1/@sms.siroe.com

For information on performing translations, validity checks, and other operations on the SMS destination address portion of the email address, see C.2.4 Site-defined Address Validity Checks and Translations

C.2.2 The Email to SMS Conversion Process

In order for email to be sent to a remote site, email must be converted to SMS messages that can be understood by the remote SMSCs. This section describes the process of converting an email message queued to the SMS channel to one or more SMS messages. As described below, options allow control over the maximum number of SMS messages generated, the maximum total length of those SMS messages, and the maximum size of any single SMS message. Only text parts (that is, MIME text content types) from the email message are used and the maximum number of parts converted may also be controlled.

Character sets used in the email message’s header lines and text parts are all converted to Unicode and then converted to an appropriate SMS character set.

When there is no SMS_TEXT mapping table (see C.2.5 Site-defined Text Conversions) an email message queued to the SMS channel receives the processing illustrated in Figure C–2.

Figure C–2 SMS Channel Email Processing

Figure C–3 SMS Channel Email Processing (continued)

The following steps correspond to the numbered boxes in Figure C–2:

1. An empty output buffer is started. The character set used for the buffer is Unicode.

2. The email message’s originator address is taken from one of the following five sources, shown in decreasing order of preference:

   1. Resent-from: 2. From: 3. Resent-sender: 4. Sender: 5. Envelope From:

   If the originator address is an empty string, then the value of the FROM_NONE channel option is instead appended to the buffer.

   If, however, the originator address is a non-empty string, then the result of processing the FROM_FORMAT channel option, and the value of the LINE_STOP channel option are appended to the output buffer.

   Note that the Resent-from: and Resent-sender: header lines are only considered if the USE_HEADER_RESENT option has the value 1. Otherwise, Resent- header lines are ignored.

3. If a Subject: header line is not present or is empty, then the value of the SUBJECT_NONE option is appended to the output buffer.

   Otherwise, the result of processing the SUBJECT_FORMAT option, and the value of the LINE_STOP channel option are appended to the output buffer.

4. If there are no text message parts, then the value of the NO_MESSAGE channel option is appended to the output buffer.

   If there are text message parts, then the value of the CONTENT_PREFIX channel option is appended to the output buffer.

   Non-text message parts are discarded.

5. For each text part, while the MAX_MESSAGE_PARTS limit has not been reached, the text part is decoded to Unicode and appended to the buffer, along with the value of the LINE_STOP channel option.

6. The resulting output buffer is then converted from Unicode to either the SMSC’s default character set or UCS2 (UTF-16). The SMSC’s default character set is specified with the SMSC_DEFAULT_CHARSET option.

7. After being converted, it is then truncated to not exceed MAX_MESSAGE_SIZE bytes.

8. The converted string from C.2.2 The Email to SMS Conversion Process is then broken into one or more SMS messages, no single SMS message longer than MAX_PAGE_SIZE bytes. At most, MAX_PAGES_PER_MESSAGE SMS messages will be generated.

   ---

   Note –

   As an email message may have multiple recipients, Step 6 through Step 8 may need to be done for each recipient address which makes use of the MAXLEN, MAXPAGES, or PAGELEN attributes described in “Directing Email to the Channel,” on page 4.

   ---

C.2.2.1 Sample Email Message Processing

For example, with the channel’s default settings, the email message:

From: John Doe 
To: 1234567@sms.siroe.com
Subject: Today’s meeting
Date: Fri, 26 March 2001 08:17

The staff meeting is at 14:30 today in the big conference room.

Would be converted to the SMS message:

jdoe@siroe.com (Today’s meeting) The staff meeting is at 14:30 today in the big conference room.

A different set of option settings, that follows:

CONTENT_PREFIX=Msg:
FROM_FORMAT=From:${pa}
SUBJECT_FORMAT=Subj:$s

would instead produce:

From:John Doe Subj:Today’s meeting Msg:The staff meeting is at 14:30 today in the big conference room.

C.2.3 The SMS Message Submission Process

Once an email message has been converted to one or more SMS messages, with possibly different sets for each recipient, the SMS messages are then submitted to the destination SMSC. The submissions are effected using SMPP V3.4 over TCP/IP. The hostname (SMPP_SERVER) of the SMPP server is taken to be the official host name associated with the SMS channel; the TCP port (SMPP_PORT) to use is specified with the port channel keyword.

When there are messages to process, the channel is started. The channel binds to the SMPP server as a transmitter, presenting the credentials specified with the ESME_ channel options described in C.3.3.4 SMPP Options. Table C–2 lists the fields set in a BIND_TRANSMITTER PDU (Protocol Data Unit), and gives their values:

Note that the channel is multithreaded. Depending on how much mail there is to send, the channel may have multiple dequeue thread running. (There can even be multiple channel processes running.) Each thread does a BIND_TRANSMITTER and then on that TCP/IP connection, sends all of the SMS messages it has to send, and then sends an UNBIND, and then closes the connection. No attempt is made to hold a connection open for a period of idle time for potential reuse. If the remote SMPP server sends back a throttle error, then an UNBIND is issued, the TCP/IP connection is closed, and a new connection and BIND established. It behaves similarly if the remote SMPP server sends an UNBIND before it is finished sending its SMS messages.

The SMS messages are then submitted using SMPP SUBMIT_SM PDUs. If a permanent error is returned (for example, ESME_RINVDSTADR), then the email message is returned as undeliverable. If a temporary error is returned, then the email message is re-enqueued for a later delivery attempt. To clarify, a permanent error is one for which the condition is likely to exist indefinitely and for which repeated delivery attempts will have no positive effect, such as invalid SMS destination addresses. Whereas, a temporary error is one for which the condition is likely to not exist in the near future, such as a server down or server congested condition.

If the USE_HEADER_FROM option has the value 1, then the source address for the submitted SMS message is set. The value used is derived from the originating email message and is chosen to be the most likely (email) address to which any replies should be directed. Accordingly, the source address taken from one of the following seven sources, shown in decreasing order of preference:

1. Resent-reply-to:
2. Resent-from:
3. Reply-to:
4. From:
5. Resent-sender:
6. Sender:
7. Envelope From:

Note that the Resent-reply-to: and Reply-to: header lines are only considered if the USE_HEADER_REPLY_TO option has the value 1. Moreover, the Resent-reply-to:, Resent-from:, and Resent-sender: header lines are only considered if the USE_HEADER_RESENT option has the value 1. (Note that this means that both of those options must have the value 1 for the Resent-reply-to: header line to be considered.) The default value for both of these options is the value 0. As such, only items 4, 6, and 7 are considered by the default configuration. Finally, since the source address in an SMS message is limited to 20 bytes, the source address chosen will be truncated if it exceeds that limit.

Table C–3 shows the mandatory fields set in a SUBMIT_SM PDU:

Table C–4 shows the optional fields in a SUBMIT_SM PDU:

The channel remains bound to the SMPP server until either it has no more SMS messages to submit (the message queue is empty), or MAX_PAGES_PER_BIND has been exceeded. In the latter case, a new connection is made and bind operation performed if there remain further SMS messages to send.

Note that the SMS channel is multithreaded. Each processing thread in the channel maintains its own TCP connection with the SMPP server. For example, if there are three processing threads each with SMS messages to submit, then the channel will have three open TCP connections to the SMPP server. Each connection will bind to the SMPP server as a transmitter. Moreover, any given processing thread will only have one outstanding SMS submission at a time. That is, a given thread will submit an SMS message, then wait for the submission response (that is, SUBMIT_SM_RESP PDU) before submitting another SMS message.

C.2.4 Site-defined Address Validity Checks and Translations

Sites may wish to apply validity checks or translations to SMS destination addresses encoded in the recipient email addresses described in C.2.1 Directing Email to the Channel

• Strip non-numeric characters (for example, translating 800.555.1212 to 8005551212)

• Prepend a prefix (for example, translating 8005551212 to +18005551212)

• Validate for correctness (for example, 123 is too short)

The first two tasks can be done specifically with the DESTINATION_ADDRESS_NUMERIC and DESTINATION_ADDRESS_PREFIX channel options. In general, all three of these tasks, and others can be implemented using mapping tables: either mapping table callouts in the rewrite rules or by means of a FORWARD mapping table. Using a mapping table callout in the rewrite rules will afford the most flexibility, including the ability to reject the address with a site-defined error response. The remainder of this section will focus on just such an approach -- using a mapping table callout from the rewrite rules.

Let us suppose that destination addresses need to be numeric only, be 10 or 11 digits long, and be prefixed with the string “+1”. This can be accomplished with the following rewrite rule

sms.siroe.com      ${X-REWRITE-SMS-ADDRESS,$U}@sms.siroe.com
sms.siroe.com       $?Invalid SMS address

The first rewrite rule above calls out to the site-define mapping table named X-REWRITE-SMS-ADDRESS. That mapping table is passed the local part of the email address for inspection. If the mapping process decides that the local part is acceptable, then the address is accepted and rewritten to the SMS channel. If the mapping process does not accept the local part, then the next rewrite rule is applied. Since it is a $? rewrite rule, the address is rejected with the error text “Invalid SMS address”.

The X-REWRITE-SMS-ADDRESS mapping table is shown below. It performs the necessary validation steps for local parts in either attribute-value pair list format or just a raw SMS destination address.

X-VALIDATE-SMS-ADDRESS

! Iteratively strip any non-numeric characters 
   $_*$[$ -/:-~]%*  $0$2$R
! Accept the address if it is of the form 1nnnnnnnnnn or nnnnnnnnnn
! In accepting it, ensure that we output +1nnnnnnnnnn
   1%%%%%%%%%%      +1$0$1$2$3$4$5$6$7$8$9$Y
   %%%%%%%%%%       +1$0$1$2$3$4$5$6$7$8$9$Y
! We didn’t accept it and consequently it’s invalid
   *                $N

X-REWRITE-SMS-ADDRESS
    */id=$_*/*       $C$0/id=$|X-VALIDATE-SMS-ADDRESS;$1|/$2$Y$E
    */id=$_*/*       $N
    *                $C$|X-VALIDATE-SMS-ADDRESS;$0|$Y$E
    *                $N

With the above set up, be sure that DESTINATION_ADDRESS_NUMERIC option has the value 0 (the default). Otherwise, the “+” will be stripped from the SMS destination address.

C.2.5 Site-defined Text Conversions

Sites may customize Steps 1 - 6 described in C.2.2 The Email to SMS Conversion Process a mapping table in the MTA’s mapping file.

The name of the mapping table should be SMS_Channel_TEXT where SMS_Channel is the name of the SMS channel; for example, SMS_TEXT if the channel is named sms or SMS_MWAY_TEXT if the channel is named sms_mway.

Two types of entries may be made in this mapping table. However, before explaining the format of those entries, let it be made clear that an understanding of how to use the mapping file is essential in order to understand how to construct and use these entries. An example mapping table is given after the description of these two types of entries.

Now, the two types of entries are:

• C.2.5.1 Message Header Entries

• C.2.5.2 Message Body Entries

C.2.5.1 Message Header Entries

These entries specify which message header lines should be included in an SMS message and how they should be abbreviated or otherwise converted. Only if a header line is successfully mapped to a string of non-zero length by one of these entries will it be included in the SMS message being generated. Each entry has the format

H|pattern replacement-text

If a message header line matches the pattern then it will be replaced with the replacement text replacement-text using the mapping file’s pattern matching and string substitution facilities. The final result of mapping the header line will then be included in the SMS message provided that the metacharacter $Y was specified in the replacement text. If a header line does not match any pattern string, if it maps to a string of length zero, or if the $Y metacharacter is not specified in the replacement text, then the header line will be omitted from the SMS message. The two entries

H|From:* F:$0$Y 
H|Subject:* S:$0$Y

cause the From: and Subject: header lines to be included in SMS messages with From: and Subject: abbreviated as F: and S:. The entries:

H|Date:* H|D:$0$R$Y 
H|D:*,*%19%%*:*:* H|D:$0$ $5:$6$R$Y

cause the Date: header line to be accepted and mapped such that, for instance, the header line

Date: Wed, 16 Dec 1992 16:13:27 -0700 (PDT)

will be converted to

D: Wed 16:13

Very complicated, iterative mappings may be built. Sites wishing to set up custom filters will first need to understand how the mapping file works. The H| in the right-hand-side of the entry may be omitted, if desired. The H| is allowed in that side so as to cut down on the number of table entries required by sets of iterative mappings.

C.2.5.2 Message Body Entries

Body mappings are not supported.

C.2.5.3 Example SMS Mapping Table

An example SMS_TEXT mapping table is shown in Example C–1. The numbers inside parentheses at the end of each line correspond to the item numbers in the section titled Explanatory Text that follows this table.

Example C–1 Example SMS_TEXT Mapping Table.

SMS_TEXT

   H|From:*        H|F:$0$R$Y       (1)
   H|Subject:*     H|S:$0$R$Y       (1)
   H|F:*<*>*       H|F:$1$R$Y       ()
   H|F:*(*)*       H|F:$0$2$R$Y     (2)
   H|F:*"*"*       H|F:$0$2$R$Y     (3)
   H|F:*@*         H|F:$0$R$Y       (4)
   H|%:$ *         H|$0:$1$R$Y      (5)
   H|%:*$          H|$0:$1$R$Y      (5)
   H|%:*$ $ *      H|$0:$1$ $2$R$Y  (6)
   B|*--*          B|$0-$1$R        (7)
   B|*..*          B|$0.$1$R        (7)
   B|*!!*          B|$0!$1$R        (7)
   B|*??*          B|$0?$1$R        (7)
   B|*$ $ *        B|$0$ $1$R       (6)
   B|$ *           B|$0$R           (5)
   B|*$            B|$0$R           (5)

               

Explanatory Text

The entries in the example SMS_TEXT mapping table above are explained below:

In the example above, the metacharacter $R is used to implement and control iterative application of the mappings. By iterating on these mappings, powerful filtering is achieved. For instance, the simple mappings to remove a single leading or trailing space (6) or reduce two spaces to a single space (7) become, when taken as a whole, a filter which strips all leading and trailing spaces and reduces all consecutive multiple spaces to a single space. Such filtering helps reduce the size of each SMS message.

1. These two entries cause From: and Subject: header lines to be included in an SMS message. From: and Subject: are abbreviated as, respectively, F: and S:. Some of the other entries may have further effects on From: and Subject: header lines.

   This entry will reduce a From: header line containing a <...> pattern to only the text within the angle brackets. For example:

   F: "John C. Doe" <jdoe@siroe.com> (Hello)

   will be replaced with:

   F: jdoe@siroe.com

2. This entry will remove, inclusively, everything inside of a (...) pattern in a From: header line. For example:

   F: "John C. Doe" <jdoe@siroe.com> (Hello)

   will be replaced with:

   F: "John C. Doe" <jdoe@siroe.com>

3. This entry will remove, inclusively, everything inside of a “...” pattern in a From: header line. For example:

   F: "John C. Doe" <jdoe@siroe.com> (Hello)

   will be replaced with:

   F: <jdoe@siroe.com> (Hello)

4. This entry will remove, inclusively, everything to the right of an at-sign, @, in a From: header line. For example:

   F: "John C. Doe" <jdoe@siroe.com> (Hello)

   will be replaced with:

   F: "John C. Doe" <jdoe@

5. These four entries remove leading and trailing spaces from lines in the message header and body.

6. These two entries reduce two spaces to a single space in lines of the message header and body.

7. These four entries reduce double dashes, periods, exclamation and question marks to single occurrences of the matching character. Again, this helps save bytes in an SMS message.

The order of the entries is very important. For instance, with the given ordering, the body of the message From: header line:

From: "John C. Doe" (Hello)

will be reduced to:

jdoe

The steps taken to arrive at this are as follows:

1. We begin with the From: header line:

   From: "John C. Doe" (Hello)

   The pattern in the first mapping entry matches this and produces the result:

   F: "John C. Doe" (Hello)

   The $R metacharacter in the result string causes the result string to be remapped.

2. The mapping is applied to the result string of the last step. This produces:

   F: jdoe@siroe.com

   The $R in the mapping causes the entire set of mappings to be re-applied to the result of this step.

3. Next, the mapping is applied producing:

   F: jdoe

   The $R in the mapping causes the entire set of mappings to be re-applied to the result of this step.

4. Next, the mapping is applied producing:

   F:jdoe

   The $R in the mapping causes the entire set of mappings to be re-applied to the result of this step.

5. Since no other entries match, the final result string:

   F:jdoe

   is incorporated into the SMS message.

   ---

   Note –

   The imsimta test-mapping utility may be used to test a mapping table. For instance,

   # imsimta test -mapping -noimage_file -mapping_file=test.txt Enter table name: SMS_TEXT Input string: H|From: "John C. Doe" (Hello) Output string: H|F:jdoe Output flags: [0,1,2,89] Input string: ^D #

   For further details on the imsimta test utility, see imsimta test in Sun Java System Messaging Server 6.3 Administration Reference.

   ---

C.3 SMS Channel Configuration

This section gives directions on how to set up the SMS channel for both one-way (email-to-mobile) and two-way (email-to-mobile and mobile-to-email) functionality. The SMS channel is set up the same for both one-way and two-way functionality, with the exceptions noted in the topic C.3.7 Configuring the SMS Channel for Two-Way SMS

This section includes the following topics:

• C.3.1 Adding an SMS Channel

• C.3.2 Creating an SMS Channel Option File

• C.3.3 Available Options

• C.3.4 Adding Additional SMS Channels

• C.3.5 Adjusting the Frequency of Delivery Retries

• C.3.6 Sample One-Way Configuration (MobileWay)

• C.3.7 Configuring the SMS Channel for Two-Way SMS

C.3.1 Adding an SMS Channel

Two steps are required to add an SMS channel to a Messaging Server configuration:

1. C.3.1.1 Adding the Channel Definition and Rewrite Rules.

2. C.3.2 Creating an SMS Channel Option File.

While there are no channel options which must be set in all situations, it is likely that one or more of the following options may need to be set: ESME_PASSWORD, ESME_SYSTEM_ID, MAX_PAGE_SIZE, DEFAULT_SOURCE_TON, and DEFAULT_DESTINATION_TON. And, as described, the SMPP server’s hostname or IP address and TCP port must be set either through the channel definition in the imta.cnf file or the channel option file.

You may configure more than one SMS channel, giving different characteristics to different SMS channels. See C.3.4 Adding Additional SMS Channels for further information on the use of multiple SMS channels.

Note for the instructions that follow: if you change the imta.cnf file you must recompile. if you change just a channel option file, there is no need to recompile.

Note also that the time before a channel change takes effect can differ depending on what the change is. Many channel option changes take effect in all channels started since the change was made, which may seem almost instantaneous since the Job Controller is often starting new channels. Some of the changes don’t take effect until you recompile and restart the SMTP server. These options are processed as a message is enqueued to the channel and not when the channel itself runs.

C.3.1.1 Adding the Channel Definition and Rewrite Rules

To add the channel definition and rewrite rules, do the following:

To Add Channel Definition and Rewrite Rules

1. Before adding an SMS channel to the MTA’s configuration, you need to pick a name for the channel. The name of the channel may be either sms or sms_x where x is any case-insensitive string whose length is between one and thirty-six bytes. For example, sms_mway.

2. To add the channel definition, edit the imta.cnf file located in the installation-directory/config/ directory. At the bottom of the file add a blank line followed by the two lines:

   channel-name port p threaddepth t \ 
     backoff "pt2m" "pt5m" "pt10m" "pt30m" notices 1
   smpp-host-name
   

   where channel-name is the name you chose for the channel, p is the TCP port the SMPP server listens on, t is the maximum simultaneous number of SMPP server connections per delivery process, and smpp-host-name is the host name of the system running the SMPP server.

   For example, you might specify a channel definition as follows:

   sms_mway port 55555 threaddepth 20 \ backoff "pt2m" "pt5m" "pt10m" "pt30m" notices 1 smpp.siroe.com

   For instructions on how to calculate threaddepth, see C.3.1.2 Controlling the Number of Simultaneous Connections

   See C.3.5 Adjusting the Frequency of Delivery Retries for a discussion of the backoff and notices channel keywords.

   If you wish to specify an IP address rather than a host name, for smpp-host-name, specify a domain literal. For example, if the IP address is 127.0.0.1, then specify [127.0.0.1] for smpp-host-name. Alternatively, consider using the SMPP_SERVER channel option.

   ---

   Note –

   For Sun Java System Messaging Server 6.1, the use of the master channel keyword has been deprecated. It is ignored if present.

   ---

3. Once the channel definition has been added, go to the top half of the file and add a rewrite rule in this format:

   smpp-host-name $u@smpp-host-name

   For example,

   smpp.siroe.com $u@smpp.siroe.com

4. Save the imta.cnf file.

5. Recompile the configuration with the imsimta cnbuild command.

6. Restart the SMTP server with the imsimta restart dispatcher command.

7. With the above configuration, email messages are directed to the channel by addressing them to id@smpp-host-name (for example, 123456@smpp.siroe.com). See C.2.2 The Email to SMS Conversion Process for further information on addressing.

8. Optionally, if you wish to hide the SMPP server’s host name from users or associate other host names with the same channel, then add additional rewrite rules. For instance, to associate host-name-1 and host-name-2 with the channel, add the following to rewrite rules:

   host-name-1 $U%host-name-1@smpp-host-name host-name-2 $U%host-name-2@smpp-host-name

   For example, if the SMPP server’s host name is smpp.siroe.com but you want users to address email to id@sms.sesta.com, then add the rewrite rule:

   sms.sesta.com $U%sms.sesta.com@smpp.siroe.com

   Note that the SMPP_SERVER and SMPP_PORT channel options will override the channel’s official host name and port channel keyword settings. When the SMPP_PORT option is used, it is not necessary to also use the port keyword. The advantage of using these two options is that they can be put into effect and subsequently changed without needing to recompile the configuration. An additional use of the SMPP_SERVER option is described inC.3.4 Adding Additional SMS Channels.

C.3.1.2 Controlling the Number of Simultaneous Connections

The threaddepth channel keyword controls the number of messages to assign to each delivery thread within a delivery process. To calculate the total number of concurrent connections allowed, multiply the values of the two following options: SMPP_MAX_CONNECTIONS and job_limit (SMPP_MAX_CONNECTIONS * job_limit). The SMPP_MAX_CONNECTIONS option controls the maximum number of delivery threads in a delivery process. And, the job_limit option, for the Job Controller processing pool in which the channel is run, controls the maximum number of simultaneous delivery processes.

To limit the total number of concurrent connections, you must adjust appropriately either or both of these options. For instance, if the remote SMPP server allows only a single connection, then both SMPP_MAX_CONNECTIONS and job_limit must be set to 1. When adjusting the values, it’s preferable to allow job_limit to exceed 1.

C.3.2 Creating an SMS Channel Option File

In general, a channel option file contains site-specific parameters required for the operation of the channel. A channel option file is not required for SMS. If you determine that one is necessary for your installation, store it in a text file in the installation-directory/config/ directory. As with other channel option files, the name of the file takes the form:

channel_name_option

For instance, if the channel is named sms_mway then the channel option file is:

installation-directory/config/sms_mway_option

Each option is placed on a single line in the file using the format:

option_name=option_value

For example,

PROFILE=GSM
SMSC_DEFAULT_CHARSET=iso-8859-1 
USE_UCS2=1

For a list of available SMS channel options and a description of each, see C.3.3 Available Options

C.3.3 Available Options

The SMS channel contains a number of options which divide into six broad categories:

• Email to SMS conversion: Options which control the email to SMS conversion process.

• SMS Gateway Server Option: Gateway profile option.

• SMS fields: Options which control SMS-specific fields in generated SMS messages.

• SMPP protocol: Options associated with the use of the SMPP protocol over TCP/IP.

• Localization: Options which allow for localization of text fields inserted into SMS messages.

• Miscellaneous: Debug and logging options.

These options are summarized in the table below, and described more fully in the sections which follow.

C.3.3.1 Email to SMS Conversion Options

The following options control the conversion of email messages to SMS messages. The value range for the options are in parenthesis. In general, a given email message may be converted into one or more SMS messages. See C.2.2 The Email to SMS Conversion Process

GATEWAY_NOTIFICATIONS

(0 or 1) Specifies whether or not to convert email notifications to SMS notifications. Email notification messages must conform to RFCs 1892, 1893, 1894. The default value is 0.

When GATEWAY_NOTIFICATIONS=0, such notifications are discarded and are not converted to SMS notifications.

To enable the notifications to be converted to SMS notifications, set GATEWAY_NOTIFICATIONS=1. When the option set to 1, the localization options (DSN_*_FORMAT) control which notification types (success, failure, delay, relayed) are converted into SMS messages and sent through the gateway. (If the notification type has a value of an empty string, then that type notification is not converted into SMS messages.)

MAX_MESSAGE_PARTS

(integer) When converting a multi-part email message to an SMS message, only the first MAX_MESSAGE_PARTS number of text parts will be converted. The remaining parts are discarded. By default, MAX_MESSAGE_PARTS is 2. To allow an unlimited number of message parts, specify a value of -1. When a value of 0 is specified, then no message content will be placed into the SMS message. This has the effect of using only header lines from the email message (for example, Subject:) to generate the SMS message.

Note that an email message containing both text and an attachment will typically consist of two parts. Note further that only plain text message parts are converted. All other MIME content types are discarded.

MAX_MESSAGE_SIZE

(integer, >= 10) With this option, an upper limit may be placed on the total number of bytes placed into the SMS messages generated from an email message. Specifically, a maximum of MAX_MESSAGE_SIZE bytes will be used for the one or more generated SMS messages. Any additional bytes are discarded.

By default, an upper limit of 960 bytes is imposed. This corresponds to MAX_MESSAGE_SIZE=960. To allow any number of bytes, specify a value of zero.

The count of bytes used is made after converting the email message from Unicode to either the SMSC’s default character set or UCS2. This means, in the case of UCS2, that a MAX_MESSAGE_SIZE of 960 bytes will yield, at most, 480 characters since each UCS2 character is at least two bytes long.

Note that the MAX_MESSAGE_SIZE and MAX_PAGES_PER_MESSAGE options both serve the same purpose: to limit the overall size of the resulting SMS messages. Indeed, MAX_PAGE_SIZE=960 and MAX_PAGE_SIZE=160 implies MAX_PAGES_PER_MESSAGE=6. So why are there two different options? So as to allow control of the overall size or number of pages without having to consider the maximal size of a single SMS message, MAX_PAGE_SIZE. While this may not be important in the channel option file, it is important when using the C.2.1 Directing Email to the Channel or C.2.1 Directing Email to the Channel addressing attributes described in C.2.1 Directing Email to the Channel.

Finally, note that the smaller of the two limits of MAX_MESSAGE_SIZE and MAX_PAGE_SIZE * MAX_PAGES_PER_MESSAGE is used.

MAX_PAGE_SIZE

(integer, >= 10) The maximum number of bytes to allow in a single SMS message is controlled with the MAX_PAGE_SIZE option. By default, a value of 160 bytes is used. This corresponds to MAX_PAGE_SIZE=160.

MAX_PAGES_PER_MESSAGE

(integer, 1 - 255) The maximum number of SMS messages to generate for a given email message is controlled with this option. In effect, this option truncates the email message, only converting to SMS messages that part of the email message which fits into MAX_PAGES_PER_MESSAGE SMS messages. See the description of the MAX_PAGE_SIZE option for further discussion.

By default, MAX_PAGES_PER_MESSAGE is set to the larger of 1 or MAX_MESSAGE_SIZE divided by MAX_PAGE_SIZE.

ROUTE_TO

(string, IP host name, 1-64 bytes) All SMS messages targeted to the profile will be rerouted to the specified IP host name using an email address of the form:

SMS-destination-address@route-to

where SMS-destination-address is the SMS message’s destination address and the route-to is the IP host name specified with this option. The entire content of the SMS message is sent as the content of the resulting email message. The PARSE_RE_* options are ignored.

Use of PARSE_RE_* and ROUTE_TO options are mutually exclusive. Use of both in the same gateway profile is a configuration error.

SMSC_DEFAULT_CHARSET

(string) With this option, the SMSC’s default character set may be specified. Use the character set names given in the file

installation-directory/config/charsets.txt

When this option is not specified, then US-ASCII is assumed. Note that the mnemonic names used in charsets.txt are defined in charnames.txt in the same directory.

When processing an email message, the header lines and text message parts are first decoded and then converted to Unicode. Next, the data is then converted to either the SMSC’s default character set or UCS2, depending on the value of the USE_UCS2 option and whether or not the SMS message contains at least one glyph not found in the default SMSC character set. Note that the UCS2 character set is a 16-bit encoding of Unicode and is often referred to as UTF-16.

USE_HEADER_FROM

(integer, 0-2) Set this option to allow the From: address to be passed to the SMSC. The value indicates where the From: address is taken from and what format it will have. Table C–6 shows the allowable values and their meaning.

USE_HEADER_PRIORITY

(0 or 1) This option controls handling of RFC 822 Priority: header lines. By default, information from the Priority: header line is used to set the resulting SMS message’s priority flag, overriding the default SMS priority specified with the DEFAULT_PRIORITY option. This case corresponds to USE_HEADER_PRIORITY=1. To disable use of the RFC 822 Priority: header line, specify USE_HEADER_PRIORITY=0.

See the description of the DEFAULT_PRIORITY option for further information on the handling the SMS priority flag.

USE_HEADER_REPLY_TO

(0 or 1) When USE_HEADER_FROM =1, this option controls whether or not a Reply-to: or Resent-reply-to: header line is considered for use as the SMS source address. By default, Reply-to: and Resent-reply-to: header lines are ignored. This corresponds to an option value of 0. To enable consideration of these header lines, use an option value of 1.

Note that RFC 2822 has deprecated the use of Reply-to: and Resent-reply-to: header lines.

USE_HEADER_RESENT

(0 or 1) When USE_HEADER_FROM =1, this option controls whether or not Resent- header lines are considered for use as the SMS source address. By default, Resent- header lines are ignored. This corresponds to an option value of 0. To enable consideration of these header lines, use an option value of 1.

Note that RFC 2822 has deprecated the use of Resent- header lines.

USE_HEADER_SENSITIVITY

(0 or 1) The USE_HEADER_SENSITIVITY option controls handling of RFC 822 Sensitivity: header lines. By default, information from the Sensitivity: header line is used to set the resulting SMS message’s privacy flag, overriding the default SMS privacy specified with the DEFAULT_PRIVACY option. This case, which is the default, corresponds to USE_HEADER_SENSITIVITY=1. To disable use of RFC 822 Sensitivity: header lines, specify USE_HEADER_SENSITIVITY=0.

See the description of the DEFAULT_PRIVACY option for further information on the handling the SMS privacy flag.

USE_UCS2

(0 or 1) When appropriate, the channel will use the UCS2 character set in the SMS messages it generates. This is the default behavior and corresponds to USE_UCS2=1. To disable the use of the UCS2 character set, specify USE_UCS2=0. See the description of the SMSC_DEFAULT_CHARSET option for further information on character set issues.

C.3.3.2 SMS Gateway Server Option

GATEWAY_PROFILE

The name of the gateway profile in the SMS Gateway Server configuration file, sms_gateway.cnf.

C.3.3.3 SMS Options

The following options allow for specification of SMS fields in generated SMS messages.

DEFAULT_DESTINATION_NPI

(integer, 0 - 255) By default, destination addresses will be assigned an NPI (Numeric Plan Indicator) value of zero. With this option, an alternate integer value in the range 0 to 255 may be assigned. Typical NPI values include those found in Table C–8 that follows:

Values for this option may be specified in one of three ways:

• A decimal value (for example, 10).

• A hexadecimal value prefixed by “0x” (for example, 0x0a).

• One of the following case-insensitive text strings (the associated decimal value is shown in parentheses): data (3), default (0), e.163 (1), e.164 (1), e.212 (6), ermes (10), f.69 (4), Internet (14), ip (14), isdn (1), land-mobile (6), national (8), private (9), telex (4), unknown (0), wap (18), x.121 (3).

DEFAULT_DESTINATION_TON

(integer, 0 - 255) By default, destination addresses will be assigned a TON (Type of Number) designator value of zero. With this option, an alternate integer value in the range 0 to 255 may be assigned. Typical TON values include those found in Table C–9 that follows:

Values for this option may be specified in one of three ways:

• A decimal value (for example, 10)

• A hexadecimal value prefixed by “0x” (for example, 0x0a)

• One of the following case-insensitive text strings (the associated decimal value is shown in parentheses): abbreviated (6), alphanumeric (5), default (0), international (1), national (2), network-specific (3), subscriber (4), unknown (0).

DEFAULT_PRIORITY

(integer, 0 - 255) SMS messages have a mandatory priority field. The interpretation of SMS priority values is shown in Table C–10 that follows:

With this option, the default priority to assign to SMS messages may be specified. When not specified, a default priority of 0 is used for PROFILE=GSM and CDMA, and a priority of 1 for PROFILE=TDMA.

Note that if USE_HEADER_PRIORITY=1 and an email message has an RFC 822 Priority: header line, then the priority specified in that header line will instead be used to set the priority of the resulting SMS message. Specifically, if USE_HEADER_PRIORITY=0, then the SMS priority flag is always set in accord with the DEFAULT_PRIORITY option and the RFC 822 Priority: header line is always ignored. If USE_HEADER_PRIORITY=1, then the originating email message’s RFC 822 Priority: header line is used to set the SMS message’s priority flag. If that header line is not present, then the SMS priority flag is set using the DEFAULT_PRIORITY option.

The mapping used to translate RFC 822 Priority: header line values to SMS priority flags is shown in table that follows:

DEFAULT_PRIVACY

(integer, -1, 0 - 255) Whether or not to set the privacy flag in an SMS message, and what value to use is controlled with the DEFAULT_PRIVACY and USE_HEADER_SENSITIVITY options. By default, a value of -1 is used for DEFAULT_PRIVACY. Table C–12 that follows shows the result of setting the DEFAULT_PRIVACY and USE_HEADER_SENSITIVITY options to various values.

The SMS interpretation of privacy values is shown in Table C–13 that follows:

The mapping used to translate RFC 822 Sensitivity: header line values to SMS privacy values is shown in Table C–14 that follows:

DEFAULT_SERVICE_TYPE

(string, 0 - 5 bytes) Service type to associate with SMS messages generated by the channel. By default, no service type is specified (that is, a zero length string). Some common service types are: CMT (cellular messaging), CPT (cellular paging), VMN (voice mail notification), VMA (voice mail alerting), WAP (wireless application protocol), and USSD (unstructured supplementary data services).

DEFAULT_SOURCE_ADDRESS

(string, 0 - 20 bytes) Source address to use for SMS messages generated from email messages. Note that the value specified with this option is overridden by the email message’s originator address when USE_HEADER_FROM=1. By default, the value is disabled, that is, has a value of 0.

DEFAULT_SOURCE_NPI

(integer, 0 - 255) By default, source addresses will be assigned an NPI value of zero. With this option, an alternate integer value in the range 0 to 255 may be assigned. See the description of the DEFAULT_DESTINATION_NPI option for a table of typical NPI values.

DEFAULT_SOURCE_TON

(integer, 0 - 255) By default, source addresses will be assigned a TON designator value of zero. With this option, an alternate integer value in the range 0 to 255 may be assigned. See the description of the DEFAULT_DESTINATION_TON option for a table of typical TON values.

DEFAULT_VALIDITY_PERIOD

(string, 0 - 252 bytes) By default, SMS messages are not given a relative validity period; instead, they use the SMSC’s default value. Use this option to specify a different relative validity period. Values may be specified in units of seconds, minutes, hours, or days. Table C–15 that follows specifies the format and description of the various values for this option:

A specification of 0, 0s, 0m, 0h, or 0d may be used to select the SMSC’s default validity period. That is, when a specification of 0, 0s, 0m, 0h, or 0d is used, an empty string is specified for the validity period in generated SMS messages.

Note that this option does not accept values in UTC format.

DESTINATION_ADDRESS_NUMERIC

(0 or 1) Use this option to strip all non-numeric characters from the SMS destination address extracted from the email envelope To: address. For instance, if the envelope To: address is:

"(800) 555-1212"@sms.siroe.com

then it will be reduced to:

8005551212@sms.siroe.com

To enable this stripping, specify a value of 1 for this option. By default, this stripping is disabled which corresponds to an option value of 0. Note that when enabled, the stripping is done before any destination address prefix is added via the DESTINATION_ADDRESS_PREFIX option.

DESTINATION_ADDRESS_PREFIX

(string) In some instances, it may be necessary to ensure that all SMS destination addresses are prefixed with a fixed text string; for example, “+”. This option may be used to specify just such a prefix. The prefix will then be added to any SMS destination address which lacks the specified prefix. To prevent being stripped by the DESTINATION_ADDRESS_NUMERIC option, this option is applied after the DESTINATION_ADDRESS_NUMERIC option.

PROFILE

(string) Specify the SMS profiling to be used with the SMSC. Possible values are GSM, TDMA, and CDMA. When not specified, GSM is assumed. This option is only used to select defaults for other channel options such as DEFAULT_PRIORITY and DEFAULT_PRIVACY.

USE_SAR

(0 or 1) Sufficiently large email messages may need to be broken into multiple SMS messages. When this occurs, the individual SMS messages can optionally have sequencing information added using the SMS sar_ fields. This produces a “segmented” SMS message which can be re-assembled into a single SMS message by the receiving terminal. Specify USE_SAR=1 to indicate that this sequencing information is to be added when applicable. The default is to not add sequencing information and corresponds to USE_SAR=0.

When USE_SAR=1 is specified, the REVERSE_ORDER option is ignored.

C.3.3.4 SMPP Options

The following options allow for specification of SMPP protocol parameters. The options with names beginning with the string “ESME_” serve to identify the MTA when it acts as an External Short Message Entity (ESME); that is, when the MTA binds to an SMPP server in order to submit SMS messages to the server’s associated SMSC.

ESME_ADDRESS_NPI

(integer, 0 - 255) By default, bind operations will specify an ESME NPI value of zero indicating an unknown NPI. With this option, an alternate integer value in the range 0 to 255 may be assigned. See the description of the DEFAULT_DESTINATION_NPI option for a table of typical NPI values.

ESME_ADDRESS_TON

(integer, 0 - 255) By default, bind operations will specify an ESME TON value of 0. With this option, an alternate integer value in the range 0 to 255 may be assigned. See the description of the DEFAULT_DESTINATION_TON option for a table of typical TON values.

ESME_IP_ADDRESS

(string, 0 - 15 bytes) When binding to the SMPP server, the BIND PDU indicates that the client’s (that is, ESME’s) address range is an IP address. This is done by specifying a TON of 0x00 and an NPI of 0x0d. The value of the address range field is then set to be the IP address of the host running the SMS channel. Specify the IP address in dotted decimal format; for example, 127.0.0.1.

ESME_PASSWORD

(string, 0 - 8 bytes) When binding to the SMPP server, a password may be required. If so, then specify that password with this option. By default, a zero-length password string is presented.

ESME_SYSTEM_ID

(string, 0 - 15 bytes) When binding to the SMPP server, a system ID for the MTA may be supplied. By default, no system ID is specified (that is, a zero-length string is used). To specify a system ID, use this option.

ESME_SYSTEM_TYPE

(string, 0 - 12 bytes) When binding to the SMPP server, a system type for the MTA may be supplied. By default, no system type is specified (that is, a zero-length string is used).

MAX_PAGES_PER_BIND

(integer, >= 0) Some SMPP servers may limit the maximum number of SMS messages submitted during a single, bound session. In recognition of this, this option allows specification of the maximum number of SMS messages to submit during a single session. Once that limit is reached, the channel will unbind, close the TCP/IP connection, re-connect, and then rebind.

By default, a value of 1024 is used for MAX_PAGES_PER_BIND. Note that the channel will also detect ESME_RTHROTTLED errors and adjust MAX_PAGES_PER_BIND during a single run of the channel accordingly.

REVERSE_ORDER

(0 or 1) When an email message generates more than one SMS message, those SMS messages can be submitted to the SMSC in sequential order (REVERSE_ORDER=0), or reverse sequential order (REVERSE_ORDER=1). Reverse sequential order is useful for situations where the receiving terminal displays the last received message first. In such a case, the last received message will be the first part of the email message rather than the last. By default, REVERSE_ORDER=1 is used.

Note that this option is ignored when USE_SAR=1 is specified.

SMPP_MAX_CONNECTIONS

(integer, 1 - 50) This option controls the maximum number of simultaneous SMPP connections per process. As each connection has an associated thread, this option also places a limit on the maximum number of “worker” threads per process. By default, SMPP_MAX_CONNECTIONS=20.

SMPP_PORT

(integer, 1 - 65535) The TCP port which the SMPP server listens on may be specified with either this option or the port channel keyword. This port number must be specified through either of these two mechanisms. If it is specified with both mechanisms, then the setting made with the SMPP_PORT option takes precedence. Note that there is no default value for this option.

For two-way SMS, make sure its the same port as the LISTEN_PORT for the SMPP relay.

SMPP_SERVER

(string, 1 - 252 bytes) For one-way SMS, by default, the IP host name of the SMPP server to connect to is the official host name associated with the channel; that is, the host name shown on the second line of the channel’s definition in MTA’s configuration. This option may be used to specify a different host name or IP address which will override that specified in the channel definition. When specifying an IP address, use dotted decimal notation; for example, 127.0.0.1.

For two-way SMS, set to point to the host name or IP address of the SMS Gateway Server. If using the SMPP relay’s LISTEN_INTERFACE_ADDRESS option, then be sure to use the host name or IP address associated with the specified network interface address.

TIMEOUT

(integer, >= 2) By default, a timeout of 30 seconds is used when waiting for data writes to the SMPP server to complete or for data to be received from the SMPP server. Use the TIMEOUT option to specify, in units of seconds, a different timeout value. The specified value should be at least 1second.

C.3.3.5 Localization Options

In constructing SMS messages, the SMS channel has a number of fixed text strings it puts into those messages. These strings, for example, introduce the email’s From: address and Subject: header line. With the channel options described in this section, versions of these strings may be specified for different languages and a default language for the channel then specified. Example C–2 shows the language part of the option file:

Example C–2 Language Specification Part of Channel Option File

LANGUAGE=default-language

[language=i-default]
FROM_PREFIX=From:
SUBJECT_PREFIX=Subj:
CONTENT_PREFIX=Msg:
LINE_STOP= NO_MESSAGE=[no message]
REPLY_PREFIX=Re:

[language=en]
FROM_PREFIX=From:
SUBJECT_PREFIX=Subj:
CONTENT_PREFIX=Msg:
LINE_STOP= 
NO_MESSAGE=[no message]
REPLY_PREFIX=Re:
  ...

Within each [language=x] block, the localization options relevant to that language may be specified. If a particular option is not specified within the block, then the global value for that option is used. A localization option specified outside of a [language=x] block sets the global value for that option.

For the options listed below, the string values must be specified using either the US-ASCII or UTF-8 character sets. Note that the US-ASCII character set is a special case of the UTF-8 character set.

CONTENT_PREFIX

(string, 0 - 252 bytes) Text string to place in the SMS message before the content of the email message itself. Default global value is the US-ASCII string “Msg:”.

DSN_DELAYED_FORMAT

(string, 0-256 characters) Formatting string for delivery delay notifications. By default, an empty string is used for this option, thereby inhibiting the conversion to SMS of delay notifications. Note that GATEWAY_NOTIFICATIONS must be set to 1 for this option to be in effect. This option is ignored when GATEWAY_NOTIFICATIONS=0.

DSN_FAILED_FORMAT

(string, 0-256 characters) Formatting string for permanent delivery failure notifications. The default value of this option is the string:

Unable to deliver your message to $a; no further delivery attempts will be 
made.

To inhibit conversion of failure notifications, specify an empty string for this option. Note that GATEWAY_NOTIFICATIONS must be set to 1 for this option to be in effect. This option is ignored when GATEWAY_NOTIFICATIONS=0.

DSN_RELAYED_FORMAT

(string, 0-256 characters) Formatting string for relay notifications. The default value is the string:

Your message to $a has been relayed to a messaging system which may not 
provide a final delivery confirmation

To inhibit conversion of relay notifications, specify an empty string for this option. Note that GATEWAY_NOTIFICATIONS must be set to 1 for this option to be in effect. This option is ignored when GATEWAY_NOTIFICATIONS=0.

DSN_SUCCESS_FORMAT

(string, 0-256 characters) Formatting string for successful delivery notifications. The default value is the string:

Your message to $a has been delivered

To inhibit conversion of successful delivery notifications, specify an empty string for this option. Note that GATEWAY_NOTIFICATIONS must be set to 1 for this option to be in effect. This option is ignored when GATEWAY_NOTIFICATIONS=0.

FROM_FORMAT

(string, 0 - 252 bytes) Formatting template to format the originator information to insert into the SMS message. The default global value is the US-ASCII string “$a” which substitutes in the originator’s email address. See C.3.3.6 Formatting Templates

FROM_NONE

(string, 0 - 252 bytes) Text string to place in the SMS message when there is no originator address to display. The default global value is an empty string.

Note that normally, this option will never be used as sites will typically reject email messages which lack any originator address.

LANGUAGE

(string, 0 - 40 bytes) The default language group to select text strings from. If not specified, then the language will be derived from the host’s default locale specification. If the host’s locale specification is not available or corresponds to “C”, then i-default will be used. (i-default corresponds to “English text intended for an international audience.”)

LINE_STOP

(string, 0 - 252 bytes) Text string to place in the SMS message between lines extracted from the email message. The default global value is the US-ASCII space character, “ “.

NO_MESSAGE

(string, 0 - 252 bytes) Text string to place in the SMS message to indicate that the email message had no content. The default global value is the US-ASCII string “[no message]“.

SUBJECT_FORMAT

(string, 0 - 252 bytes) Formatting template to format the content of the Subject: header line for display in the SMS message. The global default value for this option is the US-ASCII string “($s)“. See C.3.3.6 Formatting Templates for further details.

See the SUBJECT_NONE option for a description of the handling when there is no Subject: header line or the content of that header line is an empty string.

SUBJECT_NONE

(string, 0 - 252 bytes) Text string to display when the originating email message either has no Subject: header line, or the Subject: header line’s value is an empty string. The default global value for this option is the empty string.

DEBUG

(integer, bitmask) Enable debug output. The default value is 6 which selects warning and error messages. Any non-zero value enables debug output for the channel itself, the same as specifying master_debug on the channel definition.Table C–16 defines the bit values of the DEBUG bitmask.

C.3.3.6 Formatting Templates

The formatting templates specified with the FROM_FORMAT, SUBJECT_FORMAT, and all the DSN_* channel options are UTF-8 strings which may contain a combination of literal text and substitution sequences. Assuming the sample email address of

Jane Doe <user@siroe>

The recognized substitution sequences are shown in Table C–17 that follows:

For example, the formatting template

From: $a

produces the text string

From: user@siroe

The construct,

${xy:alternate text}

may be used to substitute in the text associated with the sequence x. If that text is the empty string, the text associated with the sequence y is instead used. And, if that text is the empty string, to then substitute in the alternate text. For example, consider the formatting template

From: ${pa:unknown sender}

For the originator email address

John Doe <jdoe@siroe.com>

which has a phrase part, the template produces:

From: John Doe

However, for the address

jdoe@siroe.com

which lacks a phrase, it produces

From: jdoe@siroe.com

And for an empty originator address, it produces

From: unknown sender

C.3.4 Adding Additional SMS Channels

You may configure the MTA to have more than one SMS channel. There are two typical reasons to do this:

1. To communicate with different SMPP servers.

   This is quite straightforward: just add an additional SMS channel to the configuration, being sure to (a) give it a different channel name, and (b) associate different host names with it. For example,

   sms_mway port 55555 threaddepth 20 smpp.siroe.com sms_ace port 777 threaddepth 20 sms.ace.net

   Note that no new rewrite rule is needed. If there is no directly matching rewrite rule, Messaging Sever looks for a channel with the associated host name. For example, if the server is presented with user@host.domain, it would look for a channel of the name “host.domain”. If it finds such a channel, it routes the message there. Otherwise, it starts looking for a rewrite rule for the “.domain” and if none is there, then for the dot (“.”) rule. For more information on rewrite rules, see Chapter 11, Configuring Rewrite Rules.

2. To communicate with the same SMPP server but using different channel options.

   To communicate with the same SMPP server, using different channel options, specify the same SMPP server in the SMPP_SERVER channel option for each channel definition.

   Using this mechanism is necessary since two different channels cannot have the same official host name (that is, the host name listed in the second line of the channel definition). To allow them to communicate with the same SMPP server, define two separate channels, with each specifying the same SMPP server in their SMPP_SERVER in their channel option files.

   For example, you could have the following channel definitions,

   sms_mway_1 port 55555 threaddepth 20 SMS-DAEMON-1 sms_mway_2 port 55555 threaddepth 20 SMS-DAEMON-2

   and rewrite rules,

   sms-1.siroe.com $u%sms-1.siroe.com@SMS-DAEMON-1 sms-2.siroe.com $U%sms-2.siroe.com@SMS-DAEMON-2

   Then, to have them both use the same SMPP server, each of these two channels would specify SMPP_SERVER=smpp.siroe.com in their channel option file.

C.3.5 Adjusting the Frequency of Delivery Retries

When an SMS message cannot be delivered owing to temporary errors (for example, the SMPP server is not reachable), the email message is left in the delivery queue and retried again later. Unless configured otherwise, the Job Controller will not re-attempt delivery for an hour. For SMS messaging, that is likely too long to wait. As such, it is recommended that the backoff channel keyword be used with the SMS channel to specify a more aggressive schedule for delivery attempts. For example,

sms_mway port 55555 threaddepth 20 \ 
  backoff "pt2m" "pt5m" "pt10m" "pt30m" notices 1
smpp.siroe.com

With the above settings, a redelivery attempt will be made at two minutes after the first attempt. If that then fails, then five minutes after the second attempt. Then ten minutes later and finally every thirty minutes. The notices 1 channel keyword causes the message to be returned as undeliverable if it cannot be delivered after a day.

C.3.6 Sample One-Way Configuration (MobileWay)

The MTA SMS channel may be used with any SMPP V3.4 compatible SMPP server. For purposes of illustrating an example configuration, this section explains how to configure the SMS channel for use with a MobileWay SMPP server. MobileWay (http://www.mobileway.com/) is a leading provider of global data and SMS connectivity. By routing your SMS traffic through MobileWay, you can reach SMS subscribers on most of the major SMS networks throughout the world.

When requesting an SMPP account with MobileWay, you may be asked to answer the following questions:

• IP address of your SMPP client: Supply the IP address of your Messaging Server system as seen by other domains on the Internet.

• Default validity period: This is the SMS validity period which MobileWay will use should a validity period not be specified in the SMS messages you submit. SMS messages which cannot be delivered before this validity period expires will be discarded. Supply a reasonable value (for example, 2 days, 7 days, etc.).

• Window size: This is the maximum number of SMS messages your SMPP client will submit before it will stop and wait for responses from the SMPP server before submitting any further SMS messages. You must supply a value of 1 message.

• Timezone: Specify the timezone in which your Messaging Server system operates. The timezone should be specified as an offset from GMT.

• Timeout: Not relevant to one-way SMS messaging.

• IP address and TCP port for outbind requests: Not relevant for one-way SMS messaging.

After supplying MobileWay with the answers to the above questions, they will provide you with an SMPP account and information necessary to communicate with their SMPP servers. This information includes

Account Address: a.b.c.d:p
Account Login: system-id
Account Passwd: secret

The Account Address field is the IP address, a.b.c.d, and TCP port number, P., of the MobileWay SMPP server you will be connecting to. Use these values for the SMPP_SERVER and SMPP_PORT channel options. The Account Login and Passwd are, respectively, the values to use for the ESME_SYSTEM_ID and ESME_PASSWORD channel options. Using this information, your channel’s option file should include

SMPP_SERVER=a.b.c.d
SMPP_PORT=p
ESME_SYSTEM_ID=system-id
ESME_PASSWORD=secret

Now, to interoperate with MobileWay you need to make two additional option settings

ESME_ADDRESS_TON=0x01
DEFAULT_DESTINATION_TON=0x01

The rewrite rule in the imta.cnf file can appear as

sms.your-domain $u@sms.your-domain

And, the channel definition in the imta.cnf file can appear as

sms_mobileway 
sms.your-domain

Once the channel option file, rewrite rule, and channel definition are in place, a test message may be sent. MobileWay requires International addressing of the form

+<country-code><subscriber-number>

For instance, to send a test message to the North American subscriber with the subscriber number (800) 555-1212, you would address your email message to

+18005551212@sms.your-domain

C.3.6.1 Debugging

To debug the channel, specify the master_debug channel keyword in the channel’s definition. For example,

sms_mway port 55555 threaddepth 20 \ 
backoff "pt2m" "pt5m" "pt10m" "pt30m" notices 1 master_debug

With the master_debug channel keyword, basic diagnostic information about the channel’s operation will be output to the channel’s log file. For verbose diagnostic information about the SMPP transactions undertaken by the channel, also specify

DEBUG=-1

in the channel’s option file.

C.3.7 Configuring the SMS Channel for Two-Way SMS

For general directions on configuring the SMS channel, refer to earlier topics starting with C.3 SMS Channel Configuration. Configure the SMS channel as though it will be talking directly to the remote SMSC, with the exceptions listed in Table C–18 that follows:

All other channel configurations should be done as described in the SMS Channel documentation.

As mentioned in C.5.1 Setting Up Bidirectional SMS Routing, the remote SMSC needs to be configured to route the SMS address, defined in the DEFAULT_SOURCE_ADDRESS channel option, to the Gateway’s SMPP server using the TCP port number specified with the LISTEN_PORT option. (For how to specify the LISTEN_PORT, see C.5.5.3 An SMPP Server.)

Note that multiple SMS channels may use the same SMPP relay. Similarly, there need be only one SMPP server or gateway profile to handle SMS replies and notifications for multiple SMS channels. The ability to configure multiple relays, servers, and gateway profiles exists to effect different usage characteristics through configuration options.

C.4 SMS Gateway Server Theory of Operation

The SMS Gateway Server facilitates two-way SMS through mechanisms that allow mobile originated SMS messages to be matched to the correct email address. The following SMS Gateway Server topics are covered in this section:

• C.4.1 Function of the SMS Gateway Server

• C.4.2 Behavior of the SMPP Relay and Server

• C.4.3 Remote SMPP to Gateway SMPP Communication

• C.4.4 SMS Reply and Notification Handling

C.4.1 Function of the SMS Gateway Server

The SMS Gateway Server simultaneously functions as both an SMPP relay and server. It may be configured to have multiple “instantiations” of each function. For instance, it may be configured to have three different SMPP relays, each listening on different TCP ports or network interfaces and relaying to different remote SMPP servers. Similarly, it may be configured to have four different SMPP servers, each listening on different combinations of TCP ports and network interfaces.

The SMS Gateway Server may be configured with zero or more gateway profiles for sending SMS messages to email. Each gateway profile describes which destination SMS addresses match the profile, how to extract the destination email addresses from SMS messages, and various characteristics of the SMS to email conversion process. Each SMS message presented to the SMS Gateway Server through either its SMPP relay or server are compared to each profile. If a match is found, then the message is routed to email.

Finally, the gateway profiles also describe how to handle notification messages returned by remote SMSCs in response to previous email-to-mobile messages.

C.4.2 Behavior of the SMPP Relay and Server

When acting as an SMPP relay, the SMS Gateway Server attempts to be as transparent as possible, relaying all requests from local SMPP clients on to a remote SMPP server and then relaying back the remote server’s responses. There are two exceptions:

• When a local SMPP client submits a message whose SMS destination address matches one of the configured gateway profiles, the submitted SMS message is sent directly back to email; the SMS message is not relayed to a remote SMPP server.

• When a local or remote SMPP client submits a message whose SMS destination address matches a unique SMS source address previously generated by the SMPP relay, the SMS message is a reply to a previously relayed message. This reply is directed back to the originator of the original message.

Note that typically the SMS Gateway Server will be configured such that the unique SMS source addresses which it generates match one of the gateway profiles.

The SMS Gateway Server’s SMPP relay is only intended for use with qualified, Sun Java System SMPP clients, that is, the Sun Java System Messaging Server’s SMS channel. It is not intended for use with arbitrary SMPP clients.

When acting as an SMPP server, the SMS Gateway Server directs SMS messages to email for three circumstances:

• The SMS messages are mobile originated and match a gateway profile.

• The SMS messages are mobile originated and the SMS destination address matches a previously generated unique SMS source address.

• The SMS messages are SMS notifications which correspond to email-to-mobile messages previously relayed by the SMS Gateway Server’s SMPP relay.

All other SMS messages are rejected by the SMPP server.

C.4.3 Remote SMPP to Gateway SMPP Communication

Remote SMPP clients communicate to the Gateway SMPP server with Protocol Data Units (PDUs). Remote SMPP clients emit request PDUs to which the Gateway SMPP server responds. The Gateway SMPP server operates synchronously. It completes the response to a request PDU before it processes the next request PDU from the connected remote SMPP client.

Table C–19 that follows lists the request PDUs the Gateway SMPP server handles, and specifies the Gateway SMPP server’s response.

C.4.4 SMS Reply and Notification Handling

The SMS Gateway Server maintains a historical record of each SMS message relayed through its SMPP relays. The need to use historical data arises from the fact that when submitting an email message to SMS it is generally not possible to convert the email address of the message’s originator to an SMS source address. Since any SMS replies and notifications will be directed to this SMS source address, a problem arises. This is resolved by using automatically generated, unique SMS source addresses in relayed messages. The remote SMSCs are then configured to route these SMS source addresses back to the Gateway SMPP server.

The historical data is represented as an in-memory hash table of message IDs and generated, unique SMS source addresses. This data along with the associated email origination data are also stored on disk. The disk based storage is a series of files, each file representing HASH_FILE_ROLLOVER_PERIOD seconds of transactions (the default is 30 minutes). Each file is retained for RECORD_LIFETIME seconds (the default is 3 days). See theSun Java Communications Suite 5 Deployment Planning Guide for a discussion of the in-memory and on-disk resource requirements of the historical data.

Each record has three components:

• Email origination data (such as, envelope From: and To: addresses). This data is supplied by the MTA SMS channel when it submits a message.

• The unique SMS source address generated by the SMPP relay and inserted into the relayed SMS message.

• The resulting receipted message ID returned by the remote SMSC’s SMPP server when it accepts a submission.

C.4.4.1 Routing Process for SMS Replies

The Gateway SMPP relays and servers use historical records to handle SMS replies, notifications and mobile originated messages. When an SMS message is presented to the SMPP relay or server, the following routing process is followed:

1. The SMS destination address is compared against the historical record to see if there is a matching, unique SMS source address that the SMPP relay previously generated. If a match is found, see Step 6. .

2. If there is no match, but the message is an SMS notification (SMPP DELIVER_SM PDU), then the receipted message ID, if present, is compared against the historical record. If a match is found, go to Step 8. [The SMS Gateway Server actually allows these to be presented to either the SMPP relay or SMPP server.]

3. If there is no match, then the destination SMS address is compared against the SELECT_RE option expressions for each configured gateway profile. If a match is found, then go to Step 9.

4. If there is no match and the SMS message was presented to the Gateway SMPP relay, then the message is relayed to the remote SMPP server.

5. If there is no match and the SMS message was presented to the Gateway SMPP server, then the message is determined to be an invalid message and an error response is returned in the SMPP response PDU. For email to SMS, a Non Delivery Notification (NDN) is eventually generated.

6. If a matching unique SMS source address was found, then the SMS message is further inspected to see if it is a reply or a notification message. To be a notification message it must be a SUBMIT_SM PDU with a receipted message ID. Otherwise, it is considered to be a reply.

7. If it is a reply then the SMS message is converted to an email message using the origination email information from the historical record.

8. If it is a notification, then the SMS message is converted to an email Delivery Status Notification (DSN) as per RFC 1892-1894. Note that the ESMTP NOTIFY flags (RFC 1891) of the original email message will be honored (For example, if the SMS message is a “success” DSN but the original email message requested only “failure” notifications, then the SMS notification will be discarded).

9. If the destination SMS address matches a SELECT_RE option in a configured gateway profile, then the SMS message is treated as a mobile originated message and converted back to email message as per the PARSE_RE_n rules for that gateway profile. If the conversion fails, then the SMS message is invalid and an error response is returned.

C.5 SMS Gateway Server Configuration

This section gives directions on how to set up the SMS Gateway Server for both email-to-mobile and mobile-to-email functionality. This section includes the following topics:

• C.5.1 Setting Up Bidirectional SMS Routing

• C.5.2 Enabling and Disabling the SMS Gateway Server

• C.5.3 Starting and Stopping the SMS Gateway Server

• C.5.4 SMS Gateway Server Configuration File

• C.5.5 Configuring Email-To-Mobile on the Gateway Server

• C.5.6 Configuring Mobile-to-Email Operation

• C.5.7 Configuration Options

• C.5.8 Global Options

• C.5.9 SMPP Relay Options

• C.5.10 SMPP Server Options

• C.5.11 Gateway Profile Options

• C.5.12 Configuration Example for Two-Way SMS

C.5.1 Setting Up Bidirectional SMS Routing

The recommended way to set up bidirectional email and SMS routing between the MTA and SMSC is a three step process:

• C.5.1.1 Set the SMS Address Prefix– Choose an SMS address prefix. Any prefix may be used, so long as it is ten characters or less.

• C.5.1.2 Set the Gateway Profile– Reserve the prefix for use with the SMS Gateway Server (by setting the gateway profile).

• C.5.1.3 Configure the SMSC– Configure the SMSC to route SMS destination addresses to the SMS Gateway SMPP server that start with the prefix. Mobile originated email will have only the prefix. Replies and notifications will have the prefix followed by exactly ten decimal digits.

C.5.1.1 Set the SMS Address Prefix

The source SMS addresses generated by the MTA SMS channel should be set to match the selected SMS address prefix. Do this by setting the following:

• MTA SMS channel options:

  USE_HEADER_FROM=0

  DEFAULT_SOURCE_ADDRESS=prefix

  The first setting causes the channel to not attempt to set the SMS source address from information contained in the email message. The second setting causes the SMS source address to be set (to the selected prefix) when it is not set from any other source.

• Recognize the prefix as an SMS destination address to accept and route to email. Do this by specifying the SELECT_RE gateway profile option as follows:

  SELECT_RE=prefix

C.5.1.2 Set the Gateway Profile

The SMS Gateway Server’s gateway profile should then be set to make all relayed SMS source addresses unique. This is the default setting but may be explicitly set by specifying the gateway profile option MAKE_SOURCE_ADDRESSES_UNIQUE=1. This will result in relayed SMS source addresses of the form:

prefixnnnnnnnnnn

where nnnnnnnnnn will be a unique, ten digit decimal number.

C.5.1.3 Configure the SMSC

Finally, the SMSC should be configured to route all SMS destination addresses matching the prefix (either just the prefix, or the prefix plus a ten digit number) to the SMS Gateway Server’s SMPP server. The regular expression for such a routing will be similar to:

prefix([0-9]{10,10}){0,1}

where prefix is the value of DEFAULT_SOURCE_ADDRESS, [0-9] specifies the allowed values for the ten digit number, {10, 10} specifies that there will be a minimum of ten digits and a maximum of ten digits, and {0, 1} specifies that there can be zero or one of the 10-digit numbers.

C.5.2 Enabling and Disabling the SMS Gateway Server

• To enable the SMS Gateway Server, the configutil parameter local.smsgateway.enable must be set to the value 1. Use the following configuration utility command to set it:

  # configutil -o local.smsgateway.enable -v 1

• To disable the gateway server, set local.smsgateway.enable to the value 0, using the following command:

  # configutil -o local.smsgateway.enable -v 0

C.5.3 Starting and Stopping the SMS Gateway Server

After the SMS Gateway Server is enabled, it may be started and stopped with the following commands:

# start-msg sms

and

# stop-msg sms

C.5.4 SMS Gateway Server Configuration File

In order to operate, the SMS Gateway Server requires a configuration file. The configuration file is a Unicode text file encoded using UTF-8. The file can be an ASCII text file. The name of the file must be:

installation-directory/config/sms_gateway.cnf

Each option setting in the file has the following format:

option-name=option-value

Options that are part of an option group appear in the following format:

[group-type=group-name]
option-name-1=option-value-1
option-name-2=option-value-2
...
option-name-n=option-value-n

C.5.5 Configuring Email-To-Mobile on the Gateway Server

To implement the email-to-mobile part of two-way SMS, you must configure the following:

• C.5.5.1 A Gateway Profile

• C.5.5.2 An SMPP Relay

• C.5.5.3 An SMPP Server

C.5.5.1 A Gateway Profile

To configure an email-to-mobile gateway profile, follow these steps:

To Configure an Email-to-mobile Gateway Profile

1. Add a gateway profile to the SMS Gateway Server configuration file.

   To add an option group, use the following format:

   [GATEWAY_PROFILE=profile_name] option-name-1=option-value-1 option-name-2=option-value-2a ... option-name-n=option-value-n

   The length of the gateway profile name, profile_name in the preceding format, must not exceed 11 bytes. The name must be the same as the name for the GATEWAY_PROFILE channel option in the SMS channel option file. The name is case insensitive. For a list of the valid channel options, see C.3.3 Available Options

2. Set the gateway profile options (for example, SMSC_DEFAULT_CHARSET) to match characteristics of the remote SMSC.

3. Set the other gateway profile options to match the SMS channel’s email characteristics.

   A complete description of gateway profile options, see C.5.11 Gateway Profile Options

4. Set the CHANNEL option.

   Set its value to the name of the MTA SMS channel.

   When a notification is sent to email through the gateway, the resulting email message will be enqueued to the MTA using this channel name.

C.5.5.2 An SMPP Relay

To configure an SMPP Relay, complete the following steps:

To Configure an SMPP Relay

1. Add an SMPP relay instantiation (option group) to the SMS Gateway Server’s configuration file.

   To add an option group, use the following format:

   [SMPP_RELAY=relay_name] option-name-1=option-value-1 option-name-2=option-value-2 ... option-name-n=option-value-n

   Any name may be used for the relay’s name. All that matters is that the name not be used for any other SMPP relay instantiation within the same configuration file.

2. Set the LISTEN_PORT option.

   The value used for the SMS channel’s SMPP_PORT option must match that used for the relay’s LISTEN_PORT option. For the LISTEN_PORT, select a TCP port number which is not used by any other SMPP relay or server instantiation nor by any other server running on the same computer.

3. Set the SERVER_HOST option.

   The relay’s SERVER_HOST option should give the host name for the remote SMSC’s SMPP server. An IP address may be used in place of a host name.

4. Set the SERVER_PORT option.

   The relay’s SERVER_PORT option should give the TCP port for the remote SMSC’s SMPP server.

   For a complete description of all SMPP relay options, see C.5.9 SMPP Relay Options

C.5.5.3 An SMPP Server

To configure an SMPP server, complete the following steps:

To Configure an SMPP Server

1. Add an SMPP server instantiation (option group) to the SMS Gateway Server’s configuration file.

   To add an option group, use the following format:

   [SMPP_SERVER=server_name] option-name-1=option-value-1 option-name-2=option-value-2... option-name-n=option-value-n

   Any name may be used for the server’s name. All that matters is that the name not be used for any other SMPP server instantiation within the same configuration file.

2. Set LISTEN_PORT option.

   Select a TCP port number which is not being used by any other server or relay instantiation. Additionally, the port number must not be being used by any other server on the same computer.

   The remote SMSC needs to be configured to route notifications via SMPP to the SMS Gateway Server system using this TCP port.

   For a complete description of all SMPP server options, see C.5.10 SMPP Server Options

C.5.6 Configuring Mobile-to-Email Operation

To configure mobile-to-email functionality, two configuration steps must be performed:

• C.5.6.1 Configure a Mobile-to-Email Gateway Profile

• C.5.6.2 Configure a Mobile-to-Email SMPP Server

Note that multiple gateway profiles may use the same SMPP server instantiation. Indeed, the same SMPP server instantiation may be used for both email-to-mobile and mobile-to-email applications.

C.5.6.1 Configure a Mobile-to-Email Gateway Profile

For mobile origination, a gateway profile provides two key pieces of information: how to identify SMS messages intended for that profile and how to convert those messages to email messages. Note that this profile can be the same one used for email-to-mobile with the addition of the SELECT_RE option.

To configure the gateway profile, follow these steps:

To Configure the Gateway Profile

1. Add a gateway profile (option group) to the SMS Gateway Server’s configuration file.

   To add an option group, use the following format:

   [GATEWAY_PROFILE=profile_name] option-name-1=option-value-1 option-name-2=option-value-2 ... option-name-n=option-value-n

   Any name of 11 characters or less may be used for the profile’s name. All that matters is that it is not already used for another gateway profile within the same configuration file.

2. Set the SELECT_RE option must be specified for each gateway profile.

   The value of this option is an ASCII regular expression with which to compare SMS destination addresses. If an SMS destination address matches the regular expression, then the SMS message is sent through the gateway to email using the characteristics described by the matching profile.

   It is important to note that it is possible to configure multiple gateway profiles which have overlapping sets of SMS addresses (for example, a profile which matches the address 000 and another which matches any other three-digit address). However, so doing should be avoided as an SMS message will be passed off to only one gateway profile: the first one which matches. And, moreover, the order in which they are compared is undefined.

3. Set the CHANNEL option.

   Its value should be the name of the MTA’s SMS channel.

   For a complete description of all mobile origination options, see C.5.11 Gateway Profile Options

C.5.6.2 Configure a Mobile-to-Email SMPP Server

Adding an SMPP server is the same as for the email-to-mobile SMPP server (see C.5.5.3 An SMPP Server).

The remote SMSC needs to be configured to route SMS traffic to the gateway SMPP server. To do this, the SMS destination address used by the SMSC to route mobile-to-email traffic should be the value set for the gateway profile option SELECT_RE.

For example, if the SMS address 000 is to be used for mobile-to-email traffic, then the SMSC needs to be configured to route traffic for the SMS destination address 000 to the gateway SMPP server. The gateway profile should use the option setting SELECT_RE=000.

C.5.7 Configuration Options

The SMS Gateway Server configuration file options are detailed in this section. The tables that follow list all the available configuration options with a brief description of each. There is a table each for global options, SMPP relay options, SMPP server options, and SMS Gateway Server profile options.

In the subsections that follow, complete descriptions are given for all the available configuration options. The subsections are:

• C.5.8 Global Options

  Global options must be placed at the top of the configuration file, before any option groups. The remaining options must appear within option groups.

• C.5.9 SMPP Relay Options

• C.5.10 SMPP Server Options

• C.5.11 Gateway Profile Options

C.5.8 Global Options

The SMS Gateway Server presently has three categories of global options:

• C.5.8.1 Thread Tuning Options

• C.5.8.2 Historical Data Tuning

• C.5.8.3 Miscellaneous

All global options must be specified at the top of the configuration file, before any option groups are specified. Table C–20 lists all global configuration options.

C.5.8.1 Thread Tuning Options

Each inbound TCP connection represents an SMPP session. The processing for a session is handled by a worker thread from a pool of threads. When the session processing needs to wait for completion of an I/O request, the worker thread parks the session and is given other work to perform. When the I/O request completes, the session is resumed by an available worker thread from the pool.

The following options allow for tuning of this pool of worker thread processes: THREAD_COUNT_INITIAL, THREAD_COUNT_MAXIMUM, THREAD_STACK_SIZE.

THREAD_COUNT_INITIAL

(integer, > 0) Number of threads to initially create for the pool of worker threads. This count does not include the dedicated threads used to manage the in-memory historical data (2 threads) nor the dedicated threads used to listen for incoming TCP connections (one thread per TCP port/interface address pair the SMS Gateway Server listens on). The default value is for THREAD_COUNT_INITIAL is 10 threads.

THREAD_COUNT_MAXIMUM

(integer, >= THREAD_COUNT_INITIAL) Maximum number of threads to allow for the pool of worker threads. The default value is 50 threads.

THREAD_STACK_SIZE

(integer, > 0) Stack size in bytes for each worker thread in the pool of worker threads. The default value is 65,536 bytes (64 Kb).

C.5.8.2 Historical Data Tuning

When an SMS message is relayed, the message ID generated by the receiving, remote SMPP server is saved in an in-memory hash table. Along with this message ID, information about the original email message is also saved. Should that message ID subsequently be referenced by an SMS notification, this information may be retrieved. The retrieved information can then be used to send the SMS notification to the appropriate email recipient.

The in-memory hash table is backed to disk by a dedicated thread. The resulting disk files are referred to as “history files”. These history files serve two purposes: to save, in nonvolatile form, the data necessary to restore the in-memory hash table after a restart of the SMS Gateway Server, and to conserve virtual memory by storing potentially lengthy data on disk. Each history file is only written to for HASH_FILE_ROLLOVER_PERIOD seconds after which time it is closed and a new history file created. When a history file exceeds an age of RECORD_LIFETIME seconds, it is deleted from disk.

The following options allow for tuning historical files: HISTORY_FILE_DIRECTORY, HISTORY_FILE_MODE, HISTORY_FILE_ROLLOVER_PERIOD, RECORD_LIFETIME.

HISTORY_FILE_DIRECTORY

(string, absolute directory path) Absolute path to the directory to which to write the history files. The directory path will be created if it does not exist. The default value for this option is:

msg-svr-base/data/sms_gateway_cache/

The directory used should be on a reasonably fast disk system and have more than sufficient free space for the anticipated storage; see C.6 SMS Gateway Server Storage Requirements to change this option to a more appropriate value.

HISTORY_FILE_MODE

(integer, octal value) File permissions to associated with the history files. By default, a value of 0770 (octal) is used.

HISTORY_FILE_ROLLOVER_PERIOD

(integer, seconds) The current history file is closed and a new one created every HASH_FILE_ROLLOVER_PERIOD seconds. By default, a value of 1800 seconds (30 minutes) is used.

RECORD_LIFETIME

(integer, seconds > 0) Lifetime in seconds of a historical record. Records older than this lifetime will be purged from memory; history files older than this lifetime will be deleted from disk. By default, a value of 259,200 seconds (3 days) is used. Records stored in memory are purged in sweeps by a thread dedicated to managing the in-memory data. These sweeps occur every HASH_FILE_ROLLOVER_PERIOD seconds. Files on disk are purged when it becomes necessary to open a new history file.

C.5.8.3 Miscellaneous

These are miscellaneous options:

• DEBUG

• LISTEN_CONNECTION_MAX

• LOG_PAGE_COUNT

DEBUG

(integer, bitmask) Enable debug output. The default value is 6 which selects warning and error messages.

Table C–21 defines the bit values of the DEBUG bitmask.

LISTEN_CONNECTION_MAX

(integer, >= 0) The maximum number of concurrent, inbound TCP connections to allow across all SMPP relay and server instantiations. A value of 0 (zero) indicates that there is no global limit on the number of connections. There may, however, be per relay or server limits imposed by a given relay or server instantiation. Default: 10,000

LOG_PAGE_COUNT

(0, 1, 2) The LOG_PAGE_CONT SMS channel option only takes effect when logging is enabled for the channel with the logging channel keyword. When logging is enabled, this option controls the value recorded in the mail.log file's message size field. Normally that field gives the block size of the underlying message file. When LOG_PAGE_COUNT has a non-zero value, the number of transmitted pages will instead be recorded in that field of the log file.

0 - Log the block size of the underlying message file. This is the default behavior when LOG_PAGE_COUNT is not specified.

1 - Log the count of pages sent when the entire message is successfully transmitted to the recipient. Otherwise, log a page count of zero even if some pages were sent to the recipient.

2 - Log the count of pages sent to the recipient regardless of whether or not the entire message was sent.

The distinction between LOG_PAGE_COUNT=1 and LOG_PAGE_COUNT=2 is only relevant when a message is sufficiently large that it will be transmitted as several pages. In that case, it is possible that before transmitting all the pages an error might occur. For example, the network between the MTA and the remote SMPP server goes down. In that case, a later retransmission attempt will be made for the message. For each attempt, the previously sent pages are sent again along with the pages which were not sent. Sites may choose whether or not they want to record the count of pages successfully sent during these failed delivery attempts.

C.5.9 SMPP Relay Options

The SMS Gateway Server can have multiple instantiations of its SMPP relay, each with different characteristics chief of which will be the TCP port and interface listened on. Put differently, for each network interface and TCP port pair the SMPP relay listens on, distinct characteristics may be ascribed. These characteristics are specified using the options described in this section.

Each instantiation should be placed within an option group of the form:

[SMPP_RELAY=relay-name]
option-name-1=option-value-1
option-name-2=option-value-2
...
option-name-n=option-value-n

The string relay-name merely serves to differentiate this instantiation from other instantiations.

Table C–22 lists the SMPP relay configuration options.

C.5.9.1 LISTEN_BACKLOG

(integer, in [0,255]) Connection backlog allowed by the TCP stack for inbound SMPP client connections. The default value is 255.

LISTEN_CONNECTION_MAX

(integer, >= 0) The maximum number of concurrent, inbound TCP connections to allow for this SMPP relay instantiation. Note that this value will be ignored if it exceeds the global LISTEN_CONNECTION_MAX setting.

LISTEN_INTERFACE_ADDRESS

(string, "INADDR_ANY" or dotted decimal IP address) The IP address of the network interface to listen to for inbound SMPP client connections. May be either the string “INADDR_ANY” (all available interfaces) or an IP address in dotted decimal form. (For example, 193.168.100.1) The default value is “INADDR_ANY”. Clustered HA configurations will need to set this value to correspond to the HA logical IP address.

LISTEN_PORT

(integer, TCP port number) TCP port to bind to for accepting inbound SMPP client connections. Specification of this option is mandatory; there is no default value for this option. Note also that there is no Internet Assigned Numbers Authority (IANA) assignment for this service.

LISTEN_RECEIVE_TIMEOUT

(integer, seconds > 0) Timeout to allow when waiting to read data from an SMPP client. The default value is 600 seconds (10 minutes).

LISTEN_TRANSMIT_TIMEOUT

(integer, seconds > 0) Timeout to allow when sending data to an SMPP client. The default value is 120 seconds (2 minutes).

MAKE_SOURCE_ADDRESSES_UNIQUE

(0 or 1) By default, the SMPP relay will append to each SMS source address a unique, ten digit string. The resulting SMS source address is then saved along with the other historical data. The result is a unique SMS address which may then be replied to by SMS users. The SMPP server will detect this address when used as an SMS destination address and will then send the SMS message to the correct email originator.

To disable this generating of unique SMS source addresses (for one-way SMS), specify a value of 0 (zero) for this option.

SERVER_HOST

(string, TCP hostname or dotted decimal IP address) SMPP server to relay SMPP client traffic to. Either a hostname or IP address may be specified. Specification of this option is mandatory; there is no default value for this option.

SERVER_PORT

(integer, TCP port number) TCP port for the remote SMPP server to which to relay. Specification of this option is mandatory; there is no default value for this option. There is no IANA assignment for this service; do not confuse with the IANA assignment for SNPP.

SERVER_RECEIVE_TIMEOUT

(integer, seconds > 0) Timeout to allow when waiting to read data from the SMPP server. The default value is 600 seconds (10 minutes).

SERVER_TRANSMIT_TIMEOUT

(integer, seconds > 0) Timeout to allow when sending data to the SMPP server. The default value is 120 seconds (2 minutes).

C.5.10 SMPP Server Options

The SMS Gateway Server can have multiple instantiations of its SMPP server, each with different characteristics chief of which will be the TCP port and interface listened on. Put differently, for each network interface and TCP port pair the SMPP server listens on, distinct characteristics may be ascribed. These characteristics are specified using the options described in this section.

Each instantiation should be placed within an option group of the form:

[SMPP_SERVER=server-name]
option-value-1=option-value-1
option-value-2=option-value-2
...
option-name-n=option-value-n

The string server-name merely serves to differentiate the instantiation from other instantiations.

Table C–23 lists the SMPP server configuration options.

C.5.10.1 LISTEN_BACKLOG

(integer in [0,255]) Connection backlog allowed by the TCP stack for inbound SMPP client connections. The default value is 255.

LISTEN_CONNECTION_MAX

(integer >= 0) The maximum number of concurrent, inbound TCP connections to allow for this SMPP server instantiation. Note that this value will be ignored if it exceeds the global LISTEN_CONNECTION_MAX setting.

LISTEN_INTERFACE_ADDRESS

(string, "INADDR_ANY" or dotted decimal IP address) The IP address of the network interface to listen to for inbound SMPP client connections on. May be either the string “INADDR_ANY” (all available interfaces) or an IP address in dotted decimal form. (For example, 193.168.100.1.) The default value is “INADDR_ANY”.

LISTEN_PORT

(integer, TCP port number) TCP port to bind to for accepting inbound SMPP client connections. Specification of this option is mandatory; there is no default value for this option. Note that there is no IANA assignment for this service.

LISTEN_RECEIVE_TIMEOUT

(integer, seconds > 0) Timeout to allow when waiting to read data from an SMPP client. The default value is 600 seconds (10 minutes).

LISTEN_TRANSMIT_TIMEOUT

(integer, seconds > 0) Timeout to allow when sending data to an SMPP client. The default value is 120 seconds (2 minutes).

C.5.11 Gateway Profile Options

There may be zero or more gateway profiles. In the SMS Gateway Sever’s configuration file, each gateway profile is declared within an option group in the following format:

[GATEWAY_PROFILE=profile-name]
option-name-1=option-value-1
option-name-2=option-value-2
...
option-name-n=option-value-n

The string profile-name merely serves to differentiate the profile from other origination profiles.

Table C–24 lists the SMS Gateway Server profile options.

C.5.11.1 CHANNEL

(string, 1-40 characters) Name of the MTA channel used to enqueue email messages. If not specified, then “sms” is assumed. The specified channel must be defined in the MTA’s configuration.

EMAIL_BODY_CHARSET

(string, character set name) The character set to translate SMS text to prior to insertion into an email message’s body. If necessary, the translated text will be MIME encoded. The default value is US-ASCII. If the SMS message contains glyphs not available in the charset, they will be converted to mnemonic characters, which may or may not be meaningful to the recipient.

A list of the character sets known to the MTA may be found in the following file:

installation-directory/config/charsets.txt

EMAIL_HEADER_CHARSET

(string, character set name) The character set to translate SMS text to prior to insertion into an RFC 822 Subject: header line. If necessary, the translated string will be MIME encoded. The default value is US-ASCII. If the SMS message contains glyphs not available in the charset, they will be converted to mnemonic characters, which may or may not be meaningful to the recipient

FROM_DOMAIN

(string, IP host name, 1-64 characters) Domain name to append to SMS source addresses when constructing envelope From: addresses for email messages. The name specified should be the correct name for routing email back to SMS. (For example, the host name associated with the MTA SMS channel.) If not specified, then the official host name of the channel specified with the CHANNEL option will be used.

PARSE_RE_0, PARSE_RE_1, ..., PARSE_RE_9

(string, UTF-8 regular expression) For mobile origination of email, the gateway profile needs to extract a destination email address from the text of the SMS message. This is done by means of one or more POSIX-compliant regular expressions (REs). The text of the SMS message will be evaluated by each regular expression until either a match producing a destination email address is found or the list of regular expressions exhausted.

Use of PARSE_RE_* and ROUTE_TO options are mutually exclusive. Use of both in the same gateway profile is a configuration error.

Each regular expression must be POSIX compliant and encoded in the UTF-8 character set. The regular expressions must output as string 0 the destination address. They may optionally output text to use in a Subject: header line as string 1, and text to use in the message body as string 2. Any text not “consumed” by the regular expression will also be used in the message body, following any text output as string 2.

The regular expressions will be tried in the order PARSE_RE_0, PARSE_RE_1, ..., up to PARSE_RE_9. If no regular expressions are specified, then the following default regular expression is used:

[ \t]*([^\( ]*)[ \t]*(?:\(([^\)]*)\))?[ \t]*(.*)

This default regular expression breaks into the following components:

[ \t]*

Ignore leading white space characters (SPACE and TAB).

([^\( ]*)

Destination email address. This is the first reported string.

[ \t]*

Ignore white space characters.

(?:\(([^\)]*)\))?

Optional subject text enclosed in parentheses. This is the second reported string. The leading ?: causes the outer parentheses to not report a string. They are being used merely for grouping their contents together into a single RE for the trailing ?. The trailing ? causes this RE component to match only zero or one time and is equivalent to the expression {0,1}.

[ \t]*

Ignore white space characters.

(.*)

Remaining text to message body. This is the third reported string.

For example, with the above regular expression, the sample SMS message:

dan@sesta.com(Testing)This is a test

yields the email message:

To: dan@sesta.com
Subject: Testing

This is a test

As a second example, the SMS message:

sue@sesta.com This is another test

would yield:

To: sue@sesta.com

This is another test

Note that the SMS message, prior to evaluation with these regular expressions, will be translated to the UTF-16 encoding of Unicode. The translated text is then evaluated with the regular expressions which were previously converted from UTF-8 to UTF-16. The results of the evaluation are then translated to US-ASCII for the destination email address, EMAIL_HEADER_CHARSET for the Subject: text, if any, and EMAIL_BODY_CHARSET for the message body, if any.

PROFILE

(string, “GSM”, “TDMA”, or “CDMA”) SMS profile to assume. Presently this information is only used to map SMS priority flags to RFC 822 Priority: header lines. Consequently, this option has no effect when USE_SMS_PRIORITY=0 which is the default setting for that option.

SELECT_RE

(string, US-ASCII regular expression) A US-ASCII POSIX-compliant regular expression to compare against each SMS message’s SMS destination address. If an SMS message’s destination address matches this RE, then the SMS message will be sent through the gateway to email in accord with this gateway profile.

Note that since an SMS message’s destination address is specified in the US-ASCII character set, this regular expression must also be expressed in US-ASCII.

SMSC_DEFAULT_CHARSET

(string, character set name) The name of the default character set used by the remote SMSC. The two common choices for this option are US-ASCII and UTF-16-BE (USC2). If not specified, US-ASCII is assumed.

USE_SMS_PRIORITY

(integer, 0 or 1) By default (with USE_SMS_PRIORITY=0), priority flags in SMS messages are ignored and not sent with the email messages. To have the priority flags passed with the email, specify USE_SMS_PRIORITY=1. When passed with the email, the mapping from SMS to email is as shown in Table C–25:

Note that the email Priority: header line values are Nonurgent, Normal, and Urgent.

USE_SMS_PRIVACY

(integer, 0 or 1) By default (with USE_SMS_PRIVACY=0), SMS privacy indications are ignored and not sent with the email messages. To have this information passed with the email, specify USE_SMS_PRIVACY=1. When passed along with email, the mapping from SMS to email is as shown in Table C–26:

Note that the values of the email Sensitivity: header line are Personal, Private, and Company-confidential.

C.5.12 Configuration Example for Two-Way SMS

Assumptions on Behavior

For the sake of this example, let us assume that the following behavior is desired:

• Email messages addressed to

  sms-id@sms.domain.com

  are to be sent to the SMS address

  sms-id

  and given a unique SMS source address in the range 000nnnnnnnnnn.

• Mobile SMS messages addressed to the SMS address 000 are to be sent through the gateway to email with the email address extracted from the start of the SMS message text.

  For example, if the SMS message text is:

  jdoe@domain.com Interested in a movie?

  then the message “Interested in a movie?” is to be sent to jdoe@domain.com.

• SMS notifications sent to 000nnnnnnnnnn are to be sent through the gateway to email and directed to the originator of the message being receipted.

In order to bring about this behavior, the following assumptions and assignments are made

Further Assumptions and Assignments

• The MTA’s SMS channel uses the domain name sms.domain.com.

• The SMS Gateway Server runs on the host gateway.domain.com and uses:

  • TCP port 503 for its SMPP relay

  • TCP port 504 for its SMPP server

• The remote SMSC’s SMPP server runs on the host smpp.domain.com and listens on TCP port 377.

• The remote SMSC’s default character set is UCS2 (aka, UTF-16).

SMS Channel Configuration

To effect the above behavior, the following SMS channel configuration may be used in the imta.cnf file (add these lines to the bottom of the file):

(blank line)
sms
sms.domain.com

SMS Channel Option File

The channel’s option file, sms_option, would then contain the following settings:

SMPP_SERVER=gateway.domain.com
SMPP_PORT=503
USE_HEADER_FROM=0
DEFAULT_SOURCE_ADDRESS=000
GATEWAY_PROFILE=sms1
SMSC_DEFAULT_CHARSET=UCS2

SMS Gateway Server Configuration

Finally, the Gateway Server configuration file, sms_gateway.cnf, should look like the following:

HISTORY_FILE_DIRECTORY=/sms_gateway_cache/
[SMPP_RELAY=relay1]
LISTEN_PORT=503SERVER_HOST=smpp.domain.com
SERVER_PORT=377

[SMPP_SERVER=server1]
LISTEN_PORT=504

[GATEWAY_PROFILE=sms1]
SELECT_RE=000([0-9]{10,10}){0,1}
SMSC_DEFAULT_CHARSET=UCS2

Testing This Configuration

If you do not have an SMSC to test on, you may want to perform some loopback tests. With some additional settings in the sms_option file, some simple loop back tests may be performed for the above configuration.

C.5.12.1 Additional sms_option File Settings

The additional settings for the sms_option file are:

! So that we don’t add text to the body of the SMS message
FROM_FORMAT=
SUBJECT_FORMAT=
CONTENT_PREFIX=

Without these settings, an email containing:

user@domain.com (Sample subject) Sample text

would get converted into the SMS message:

From:user@domain.com Subject:Sample Subject Msg:Sample text

That, in turn, would not be in the format expected by the mobile-to-email code, which wants to see:

user@domain.com (Sample subject) Sample text

Hence the need (for loopback testing) to specify empty strings for the FROM_FORMAT, SUBJECT_FORMAT, and CONTENT_PREFIX options.

Performing the Loopback Test

Send test email messages addressed to 000@sms.domain.com, such as:

user@domain.com (Test message) This is a test message which should loop back

The result is that this email message should be routed back to the email recipient user@domain.com.Be sure to have added sms.domain.com to your DNS or host tables for the test.

C.6 SMS Gateway Server Storage Requirements

To determine the amount of resources you will need for the SMS Gateway Server, use the numbers you generate from the requirements in Table C–27 along with your expected number of relayed messages per second and the RECORD_LIFETIME setting.

Table C–27 covers the requirements for the historical records, the SMPP relay, and SMPP server.

For instance, if on average 50 messages per second are expected to be relayed, SMS source addresses are 13 bytes long, SMS message IDs have a typical length of 12 bytes, email addresses 24 bytes, Subject: lines 40 bytes, email message and envelope IDs 40 bytes each, and historical data is retained for 7 days, then:

• There will be 30.24 million historical records to store, each on average 58 bytes in memory and 311 bytes long on disk;

• The in-memory consumption of the historical records will be about 1.70 Gb (1.63 Gb + 64 Mb); and

• The on-disk storage will be approximately 8.76 Gb.

While a sufficiency of disk may be supplied to handle any on disk requirements, the virtual memory requirement on a 32-bit machine will be a hard limit of approximately 2 Gb. To reduce the amount of virtual memory or disk storage required, use the RECORD_LIFETIME option to reduce the length of time records are retained.