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.

Table C–20 Global Options

Options	Default	Description
DEBUG	6	Selects the types of diagnostic output generated
HISTORY_FILE_DIRECTORY		Absolute directory path for files of historical data
HISTORY_FILE_MODE	0770	Permissions for files of historical data
HISTORY_FILE_ROLLOVER_PERIOD	30 mins	Maximum length of time to write to the same file of historical data
LISTEN_CONNECTION_MAX	10,000	Maximum number of concurrent inbound connections across all SMPP relay and server instantiations
RECORD_LIFETIME	3 days	Lifetime of a record in the historical data archive
THREAD_COUNT_INITIAL	10 threads	Initial number of worker threads
THREAD_COUNT_MAXIMUM	50 threads	Maximum number of worker threads
THREAD_STACK_SIZE	64 Kb	Stack size for each worker thread

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.

Table C–21 DEBUG Bitmask

Bit	Value	Description
0-31	-1	Extremely verbose output
0	1	Informational messages
1	2	Warning messages
3	4	Error messages
3	8	Subroutine call tracing
4	16	Hash table diagnostics
5	32	I/O diagnostics, receive
6	64	I/O diagnostics, transmit
7	128	SMS to email conversion diagnostics (mobile originate and SMS notification)
8	256	PDU diagnostics, header data
9	512	PDU diagnostics, body data
10	1024	PDU diagnostics, type-length-value data
11	2048	Option processing; sends all option settings to the log file.

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.