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 Configuring the SMS Channel for Two-Way SMS

This section includes the following topics:

• Adding an SMS Channel

• Creating an SMS Channel Option File

• Available Options

• Adding Additional SMS Channels

• Adjusting the Frequency of Delivery Retries

• Sample One-Way Configuration (MobileWay)

• Configuring the SMS Channel for Two-Way SMS

Adding an SMS Channel

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

1. Adding the Channel Definition and Rewrite Rules.

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

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

Steps

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 Controlling the Number of Simultaneous Connections

   See 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 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 inAdding Additional SMS Channels.

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.

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 Available Options

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

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

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 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 Directing Email to the Channel or Directing Email to the Channel addressing attributes described in 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 D–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.

SMS Gateway Server Option

GATEWAY_PROFILE

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

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 D–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 D–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 D–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 D–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 D–13 that follows:

The mapping used to translate RFC 822 Sensitivity: header line values to SMS privacy values is shown in Table D–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 D–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.

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.

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 D–2 shows the language part of the option file:

Example D–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 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 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 D–16 defines the bit values of the DEBUG bitmask.

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 D–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

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.

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.

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

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.

Configuring the SMS Channel for Two-Way SMS

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

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

As mentioned in 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 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.