Configuration¶

Description of ps_master_config file¶

The ps_master_config.xml file either contains the configuration information required for each running process or points to other files that contain this configuration information.

File Structure

The following example provides an outline of the information that is contained in the ps_master_config.xml file.

<ps>
        <ps-logger>
                //ps logger specific data
        </ps-logger>
        <ps-init>
                //ps init specific data
        </ps-init>
        <console>
                //console specific data
        </console>
        <ps-httpd>
                //ps httpd specific data
        </ps-httpd>
        <ps-appexec>
                //ps appexec specific data
        </ps-appexec>
        <ps-proxy>
                //ps proxy specific data
        </ps-proxy>
        <ps-sip-agent>
                //ps sip agent specific data
        </ps-sip-agent>
        <ps-routing-rules file=""/>
        <ps-jvmserver>
                //ps jvm server specific data
        </ps-jvmserver>
        <ps-stats-collector>
                //ps statistics collector specific data
        </ps-stats-collector>
        <ps-softms-pcs>
                //ps soft media server specific data
        </ps-softms-pcs>
        <sigtran-agent>
                //sigtran agent specific data
        </sigtran-agent>
        <application-properties file=""/>
        <pca-registry file=""/>
</ps>

Location of Configuration Information

Each XML element in the ps_master_config.xml file contains the configuration information for one process running on the Application Server. A system administrator can enter process configuration information directly into ps_master_config.xml from the command line or by using the file property to point to a separate file that they create, as shown in the following example.

<ps>
        <pca-registry file="pca_registry.xml">
                <component>
                        name="Xpress.MsgCtr1.1"
                        type="PCA"
                        module="ps_msg_system_debug"
                </component>
                <component>
                        name="Xpress.MsgConfigChange.1"
                        type="PCA"
                        module="ps_msg_system_debug"
                </component>
        </pca-registry>
</ps>

Where type=”PCA” is configuration information and pca_registry.xml is the name of the file containing this information.

Application Properties

The properties for a particular application are stored in the <application-properties> element of the ps_master_config.xml file. Refer to the specific application User’s Guide for information about these properties.

The <application-properties> element of the ps_master_config.xml file is also used for providing SNMP trap notifications of HA events. For more information, see Sample Configuration Files.

In the ps_master_config.xml file, include an <applications-properties> tag:

<application-properties file="application-properties.xml"/>

Console Configuration

Application Server processes support an XML-based management and monitoring interface on the Evolve IMSWorkX Console.

The Console communicates with the application processes using Transport Layer Security (TLS) protocol. However, without explicit configuration of Console attributes, the encryption provides no guarantees of identity or protection.

Each process monitors requests on separate ports and posts events to the Console on another port. The following processes are supported on the Console interface:

• ps_appexec

• ps_init

• ps_proxy

Description of attributes:

port

This attribute is set to 7575 by default and should not be changed unless directed to do so by Customer Support.

server-key

This optional attribute specifies the secret key file (relative to /usr/sipxpress/config) for use as the server’s key. This field triggers certificate-based TLS if it is set to a non-empty value.

server-cert

This optional attribute specifies the certificate file (relative to /usr/sipxpress/config) used as the server’s certificate.

server-ca-cert

This optional attribute specifies the CA certificate (relative to /usr/sipxpress/config) that the server uses to verify the client’s certificate, if presented. If this resolves to a directory, that directory is used as a source of certificates to trust.

require-client-cert

This attribute indicates whether authentication is mutual or server only by determining whether a client certificate is also required. Accepted values are 1 for requiring a certificate or 0 for not requiring a certificate. The default value is 0, indicating server-only authentication.

The following is an example console configuration:

<console
        port="7575"
        endpoint-detail="always"
        server-key="console-server-key.pem"
        server-cert="console-server-cert.pem"
        server-ca-cert="console-ca-cert.pem">
        <access-control>
                <access-entry
                        host="0.0.0.0"
                        wildcard="255.255.255.255" />
        </access-control>
</console>

Logging¶

The logging system supports standard facilities for log aggregation or filtering. The main log for the Service Delivery Platform (PS_Syslog.txt) is sent through the standard syslog mechanism. The boot log (ps_boot_log.txt), SNMP agent log (pt_snmp_agent.log), and any application trace logs are written to the /usr/sipxpress/logs directory.

The PS_Syslog.txt log file is sent to the syslog using the default facility <local0>, but this can be configured to be any facility from <local0> through <local7> by placing the following definition inside the top level <ps> element in the ps_master_config.xml file:

<ps-logger>local-facility="{number0:7}"</ps-logger>

The Platform log levels correspond to syslog levels as shown in the following table:

Log files placed in the /usr/sipxpress/logs/ directory can be viewed using the Console. The Console can clear its log buffer, but this does not affect the log files on the Platform. It is highly recommended that you configure a log rotation and management scheme using your preferred tools, such as rsyslog, logrotate, or syslog-ng.

As an example configuration, rsyslog can be configured to place all log messages of WARNING or higher severity in the primary system log (/var/log/messages). This configuration allows long-term archival of important startup and shutdown conditions, errors, and potential configuration issues, while capturing all level log messages in PS_Syslog.txt for immediate inspection from the Console for debugging purposes.

The logrotate tool can then be configured to rotate the PS_Syslog.txt log file more often, as the volume of DEBUG and INFO logs can be very high.

The /var/log/messages directory can then be configured to rotate less often and to be archived for a longer period of time by editing the cron configuration. By default, logrotate runs once per day.

Description of pca_registry¶

The Portable Components Architecture (PCA) registry stores the configuration information that indicates which PCA components are installed on the system and whether they are located in a .so or .dll formatted file.

The pca_registry.xml file contains configuration information for the server plug-ins. This file acts as a registry of components that are installed on the server and indicates the shared object file or dynamic link library where each component is installed.

Description of attributes:

name

This attribute specifies the name of the component.

type

This attribute specifies the type of the component.

module

This attribute specifies the name of the library in which the component is defined.

The following is an example pca_registry configuration:

<pca-registry file="pca_registry.xml">
        <component>
                name="XpressSIP.MsgCtr1.1"
                type="PCA"
                module="ps_msg_system"
        </component>
        <component>
                name="XpressSIP.MsgSipInvite.1"
                type="PCA"
                module="ps_msg_sip"
        </component>
</pca-registry>

Description of ps_init¶

The ps_init process is the master process that starts all other Application Server processes and can restart processes that unexpectedly terminate.

Description of attributes:

process-dir

This attribute specifies the path of the file system directory in which the executables of the processes are stored. It is recommended to use this attribute with processes that switch users during execution.

The following section lists and describes the child processes that are started by ps_init, provides information about managing the unexpected termination of ps_init, and lists and describes ps_init elements.

Description of the <process> element

The attributes of the <process> element specify which processes are started by ps_init.

Description of attributes:

name

This required attribute is an arbitrary string that identifies the base command to invoke for the process.

process-args

This attribute is an arbitrary string that indicates any additional arguments to be passed to the process when invoked.

restart

This attribute indicates that the terminated process is to be restarted. Accepted values are 1 to restart the process or 0 to not restart the process.

critical

This attribute indicates that the process is critical and it is required for the system to successfully run. Accepted values are 1 for critical or 0 for non-critical.

termination

This attribute indicates that the process is to be forcefully terminated when shutting down. Accepted values are 1 for forced termination and 0 for not forced termination.

shutdown-tier

This attribute specifies the tier of a process to determine the order in which the process is shut down. The shutdown order is as follows:

• shuts down all processes assigned a shutdown-tier value of 1

• shuts down all processes assigned a shutdown-tier value of 2

• repeats the cycle until all processes have been shut down

The default value is 1.

max-restarts

This attribute specifies the maximum number of times to restart the process within the max-restarts-period before considering the process as failed. The default value is 2.

max-restarts-period

This attribute specifies the length of time (in seconds) in which the process can restart before considering the process as failed. The default value is 3.

restart-delay

This attribute specifies the length of time (in seconds) that the system should wait before restarting the process. The default value is 0.

start-delay

This attribute specifies the length of time (in seconds) that the system should wait before attempting to initially start the process. The default value is 0.

start-minimized

This attribute indicates that ps_init is started alone without any of the associated processes. This attribute can be used, for example, if you want to start the individual processes through the system management Console. Accepted values are True or False.

minimizable

This attribute can override the start-minimized attribute. Accepted values are True or False. A value of False disables the start-minimized attribute.

run-offline

This attribute indicates that the process should run even when the NIU is in the offline state. Accepted values are 1 to run in offline state and 0 to not run in offline state.

notify-cluster-changes

This attribute indicates that the process should be notified when a paired NIU state changes to offline or online.

start-before-cluster

This attribute indicates that the process should be started immediately at the server startup instead of waiting for the cluster to initialize. Accepted values are 1 to start before and 0 to not start before.

run-as

This attribute indicates that the process should be run with the privileges of the specified user. It is recommended to use this attribute with processes that switch users during execution.

stop-script

This attribute indicates that the process should be shut down by running this program or script.

control-queue

This attribute specifies the name of the message queue that the native process is listening on for process control messages.

online-script

This attribute indicates that the process should be notified that the NIU has transitioned online by running this program or script.

offline-script

This attribute indicates that the process should be notified that the NIU has transitioned offline by running this program or script.

script-timeout

This attribute specifies the length of time (in seconds) to wait for normal exit of any script invoked to notify the process before considering the script to have failed. A value of 0 disables the timeout.

wait-to-stop

This attribute specifies the length of time (in seconds) to wait after sending a graceful stop command before forcing the process to stop.

wait-to-start

This attribute specifies the length of time (in seconds) to wait after exec() on the process to receive a confirmation message. A value of 0 disables confirmation and immediately moves to the running state.

Description of the <send-arp> element

The attributes of the <send-arp> element specify the options used for sending Address Resolution Protocol (ARP) messages.

Description of attributes:

enabled

This attribute indicates that the process must send ARP messages. Accepted values are 1 to send messages or 0 to not send messages.

if-name

This attribute specifies the name of the interface to use in the ARP messages. Typically, this value is the public (virtual) IP address of an HA pair. For example, eth0 or eth1.

socket-if-name

This attribute specifies the interface to use for sending ARP messages. For example, eth0.

interval

This attribute specifies the frequency (in seconds) with which messages are sent. For example, if this attribute is set to 30, an ARP message will be sent every 30 seconds.

The following is an example ps_init process configuration:

<ps-init process-dir="home/build/server/bin/processes">
        <send-arp>
                enabled="1"
                local-ip-addr=""
                if-name="eth2:1"
                interval="30"
                socket-if-name="eth2"
        </send-arp>
        <process>
                name="ps_eventdispatcher"
                control-gueue="Xpress_SRmain"
                restart="1"
                critical="1"
        </process>
        <process>
                name="ps_httpd"
                control-queue="Xpress_ps_httpd"
                restart="1"
                critical="1"
                max-restarts="3"
                max-restarts-period="200"
                start-delay="5"
                restart-delay="0"
                shutdown-tier="2"
        </process>
</ps-init>

Description of ps_appexec¶

The ps_appexec process is responsible for communicating with remote application management consoles and for starting and stopping XTML virtual machines by monitoring a User Datagram Protocol (UDP) port for requests from remote consoles.

Description of attributes:

start-appserver-id

This attribute specifies the minimum ID value to assign to new XTML servers.

stop-appserver-id

This attribute specifies the maximum ID value to assign to new XTML servers.

Description of the <appserver> element

The <appserver> element specifies the server ID number of each Application Server that has to be automatically started. There can be none or several <appserver> elements configured within the ps_appexec process.

Description of the <application> element

The <application> element specifies each application that has to be automatically started. There can be none or several <application> elements configured within the ps_appexec process.

Description of attributes:

session

This attribute specifies the number of sessions to run.

iterations

This attribute specifies the maximum number of iterations each session should complete. Set the value to 0 for infinite iterations.

The following is an example ps_appexec process configuration:

<ps-appexec
        start-appserver-id="100"
        stop-appserver-id="200">
                <appserver id="100">
                        <application>
                                session="100"
                                iterations="0"
                        </application>
                        <application>
                                session="1000"
                                iterations="0"
                        </application>
                </appserver>
</ps-appexec>

Description of ps_appserver¶

The ps_appserver process provides the execution environment to the XTML application.

Description of the <xtml-server> element

The <xtml-server> element provides configuration information for the ps_appserver process.

Description of attributes:

libs

This attribute specifies a list of XTML libraries separated by semicolons. If an XTML application initiates a function that is not defined within the application document, these libraries are searched, in the order specified, for the unresolved function. The function is loaded from the first library application that contains the function of the specified name.

lib-path

This attribute specifies a list of locations to search for the libraries specified in the libs attribute. Locations can be defined as either file paths or HTTP URLs.

The following is an example ps_appserver process configuration:

<xtml-server>
        libs="lib_callcontrol.xml;lib-utils.xml"
        lib-path="http://asl.pt.com;/usr/pcs/xpress_app_server/apps/libs"
</xtml-server>

Description of ps_eventdispatcher¶

The ps_eventdispatcher process routes incoming events or network messages to Application Server sessions. For example, incoming SIP INVITE messages are sent by the SIP stack to this process, which then selects a waiting session and forwards the message to the selected session. Sessions register for events by declaring a public event handler for the event in the Evolve IMSWorkX Service Creation Environment (SCE).

The ps_eventdispatcher process can be configured to apply routing rules when determining how to route events to sessions. If no rules are specified, ps_eventdispatcher randomly selects any waiting session. For more information, see Description of ps_routing_rules.

Description of ps_httpd¶

The ps_httpd process is an HTTP server daemon that accepts connection from HTTP clients and provides web access for system information such as log files.

Description of attributes:

port

This attribute specifies the name of the Transmission Control Protocol (TCP) port to monitor. If not specified, the default port 8080 will be monitored.

cache-rules

This attribute indicates whether the process should recheck for newer versions of files when loading files from a remote system.

suffix

This cache-rules sub-attribute indicates the file name extension that should be included when the verification for newer file versions is performed.

allow-put

This attribute indicates whether to allow file transfer saves such as applications. The default value is True.

allow-get

This attribute indicates whether to allow file retrieval saves such as syslogs. The default value is True.

The following is an example ps_httpd process configuration:

<ps-httpd port="8080">
        <cache-rules>
                suffix=".xml"
                suffix=".vxml"
        </cache-rules>
</ps-httpd>

Description of ps_jvmserver¶

The ps_jvmserver process provides a Java Native Interface (JNI) to support user-defined functions called through the Drop-to-Java Plug-In Action Component (PAC).

Description of attributes:

class-path

This attribute specifies the class path used by the Java Virtual Machine (JVM) implemented within this process.

jvm-start-size

This attribute specifies the amount of memory initially allocated to this process.

jvm-max-size

This attribute specifies the maximum amount of memory allowed for this process.

num-threads

This attribute specifies the number of threads.

The following is an example ps_jvmserver process configuration:

<ps-jvmserver>
        class-path="/usr/sipxpres/jars/pt-mutables.jar:/usr/sipxpress/jars/icr/icr-core.jar:/usr/sipxpress/jars/icr/icr-xtml.jar:/usr/sipxpress/config"
        jvm-start-size="-Xms16m"
        jvm-max-size="-Xmx32m"
        num-threads="9"
</ps-jvmserver>

When running separate ps_jvmserver processes, specify alternate configuration information so that each process logs to a different file, as shown in the following example.

<process>
        name="ps_jvmserver"
        control-queue="Xpress_ps_jvmserver_alternate"
        process-args="-q Xpress_ps_jvmserver_alternate -c ps-jvm2"
        critical="1"
</process>

<ps-jvmserver>
        <ps-jvm>
                class-path="/export/home/pcs/xpress/_applications/callflow_config"
                jvm-start-size="-Xms16m"
                jvm-max-size="-Xmx32m"
                num-threads="9"
        </ps-jvm>
        <ps-jvm2>
                class-path="/export/home/pcs/xpress/_applications/callflow2_config"
                jvm-start-size="-Xms16m"
                jvm-max-size="-Xmx32m"
                num-threads="9"
        </ps-jvm2>
</ps-jvmserver>

Each example instance of ps_jvmserver uses the same Java but different pcs_javalog.properties files (callflow_config directory and callflow2_config directory). Each of these logging configuration files specify a different log file. Therefore, each of the ps_jvmserver instances log to a different file. The default is ps-jvm, so the first instance of the ps_jvmserver configuration does not require running the -c command.

Description of ps_mail_agent¶

The ps_mail_agent process initiates and controls connections to the mail server system. This agent is used for storing and retrieving voice messages for the broadband applications.

Description of attributes:

temp-dir

This optional attribute specifies the directory in which to save file attachments retrieved from email storage. The mail PACs allow you to send and receive up to three attachments with a mail message. When retrieved, the attachments are stored in this directory if specified or in the local directory if not specified. The attachments are automatically deleted when the application session that retrieved them ends.

SMTP

This attribute specifies the Simple Mail Transfer Protocol (SMTP) server details.

server

This SMTP sub-attribute specifies the name or IP address of the server to connect to.

connections

This SMTP sub-attribute specifies the number of connections to establish to the server.

keep-alive-interval

This SMTP sub-attribute specifies the length of time (in seconds) between sending heartbeat messages to the server to keep the connection open.

IMAP

This attribute specifies the Internet Message Access Protocol (IMAP) server details.

server

This IMAP sub-attribute specifies the name or IP address of the server to connect to.

connections

This IMAP sub-attribute specifies the number of connections to establish to the server.

keep-alive-interval

This IMAP sub-attribute specifies the length of time (in seconds) between sending heartbeat messages to the server to keep the connection open.

login

This IMAP sub-attribute specifies the user name for logging in to the IMAP server.

password

This IMAP sub-attribute specifies the password for logging in to the IMAP server.

The following is an example ps_mail_agent process configuration:

<ps-mail-agent temp-dir="usr/sipxpress/mail/local">
        <smtp>
                server="10.10.100.134"
                connections="1"
                keep-alive-interval="10"
                login="postmaster"
                password="1234"
        </smtp>
</ps-mail-agent>

Description of ps_proxy¶

The ps_proxy process is a message proxy that allows the Application Server processes to be distributed across multiple machines.

The configuration information describes the local queues that messages should be proxied from and the remote nodes that messages should be proxied to. The configuration file also allows an operator to specify a cluster of remote nodes to load balance requests across and a backup NIU to use if the primary NIU is unavailable.

Description of attributes:

port

This attribute specifies the TCP port to monitor for connections from remote ps_proxy processes. If not specified, the default port 7590 will be monitored.

max-replies

This attribute specifies the maximum number of replies allowed for a request message. The default value is 1. The state information that ps_proxy keeps about a request is cleared out after exceeding this limit or max-ttl.

max-ttl

This attribute specifies the maximum length of time (in seconds) that a request message stays active. The state information that ps_proxy keeps about a request is cleared out after exceeding this time limit or max-replies.

initiate-connect

This attribute determines whether remote proxies defined in sub-elements should initiate the connection to the remote server or wait for that server to connect to the remote proxy first. It is recommended that this attribute has a value of False.

disconnect-on-keepalive-trigger

This attribute determines whether the system disconnects the socket when the keepalive-count is exceeded. The default value is True.

keepalive-count

This attribute specifies the maximum keepalive count (in seconds). The default value is 5.

keepalive-interval

This attribute specifies the length of time (in seconds) between sending keepalive messages. The default value is 3.

Description of the <proxy-queue> element

The <proxy-queue> element identifies a queue on the local machine that messages are being proxied from.

Description of attributes:

name

This attribute specifies the name of the queue from which to proxy messages.

initiate-connect

This attribute determines the connection initiation behavior for this proxy queue and overrides the behavior specified in the parent ps_proxy process.

Description of the <remote-proxy> element

The text of the <remote-proxy> element is the IP address or Domain Name System (DNS) name of the remote server.

Description of attributes:

type

This attribute specifies the type of the server. Accepted values are Primary or Backup. The default value is Primary.

port

This attribute specifies the TCP port that the remote proxy is monitoring. If not specified, the default port 7590 will be monitored.

Description of the <request-queue> and <reply-queue> elements

The <request-queue> element identifies a queue to which ps_proxy should forward the requests that it receives from remote proxies. The ps_proxy process opens these queues at system startup to speed up the processing of the first request handled for this queue.

The <reply-queue> element specifies a queue from which ps_proxy should expect to receive response messages. The ps_proxy process also opens these queues to speed up the processing of the first message handled.

Description of attributes:

name

This attribute specifies the name of the queue that should be opened.

The following is an example ps_proxy process configuration:

<ps-proxy>
        <proxy-queue>name="ps_softms_pcs@10.10.100.174"</proxy-queue>
</ps-proxy>

Description of ps_routing_rules¶

The ps_routing_rules process determines how events are routed. The event dispatcher and SIP redirector use this process.

Description of the <screen-list> element

A screen list is a list of phone numbers or strings against which parameters such as the Automatic Number Identification (ANI) or Dialed Number Identification Service (DNIS) in the incoming message can be compared.

Description of attributes:

name

This attribute specifies the name of the screen list as used in the routing rules.

The <screen-list> element can contain none or several screen lists, each defined as a separate <list> child element.

The <list> element can contain none or several phone numbers or string values, each defined as a separate <item> child element.

Description of the <event> element

The <event> element defines a set of symbolic names to use for an incoming event and its parameters. These names are then used in the routing rules.

Description of attributes:

name

This attribute specifies the name of the event.

The <event> element can contain none or several <parameter> and <rule> child elements.

Description of the <parameter> element

The <parameter> element provides a name for an event parameter.

Description of the <rule> element

The <rule> element specifies a routing rule to be applied to events of this type. Routing rules are evaluated in the order that they are found in the file for a given event. The event is dispatched to the target application associated with the first rule found to be true. Rules, therefore, provide an if-then-else logic.

Description of attributes:

target

This attribute specifies the name of the application to route the event to if the associated logical expression is true. The logical expression is contained inside the <![CDATA[expression]]> block associated with this element. If there is no such block, the rule is evaluated as if it were true. The rules are evaluated by the ps_eventdispatcher process in the order that they appear in the configuration file until one is found to be true. If no rule is found to be true, the incoming event is discarded.

Description of pattern matching

The logical expression can use any arithmetic comparison for number parameters and the match operator for string comparisons. The match operator provides Perl-style regular expression matching. The screen operator can also be used to compare a string parameter against a screen list of numbers in the configuration file.

The syntax of expressions allowed in routing rules is essentially a binary operator notation as follows:

LEFT OP RIGHT where each of LEFT and RIGHT can be expressions themselves.

Variables are evaluated to their value, and literal numbers and strings can be supplied. Variables can store many types, including structured values.

Equality comparison is performed with == and requires exact equality. Variables may be empty, and any comparison with an empty value other than equality or inequality will return false (where only empty values compare equal to each other). For example, msg.hdr.subject == "Performance Test".

Ordering can be compared with the following typical operators: >, >=, <, <=. This applies numerical ordering for numeric types and lexicographic ordering (based on byte values) for string types. For example, msg.sccp_dest.subsystem_number > 128 or msg.sccp_dest.global_title.tt <= 32. Since routing rules are stored in XML format, the < and > characters need to be referenced as < and > or enclosed in a CDATA block.

Unary NOT inverts the boolean sense of a value and coerces any other type to boolean values. For example, NOT (msg.hdr.from SCREEN "blocked_numbers").

The operators AND and OR coerce their LEFT and RIGHT to boolean values and evaluate the boolean operation. For example, NOT (msg.hdr.from SCREEN "blocked_numbers") AND (msg.hdr.to SCREEN "access_numbers").

The match operator coerces its LEFT to a string and evaluates a regex match based on the pattern in RIGHT. For example, msg.hdr.request_uri MATCH "^sips?:(\+1)?\d{10}". This is not implicitly anchored, so ^ and $ metacharacters should be used to ensure the entire value is matched.

The screen operator requires both LEFT and RIGHT to be string values, where every value in the screening list named by RIGHT is searched for as a substring of the string value of LEFT. For example, msg.hdr.to SCREEN "access_numbers".

The matchN operator family is a set of operators, where N is an integer value 0 through 9, which expect both LEFT and RIGHT to be strings. This operator then extracts from the LEFT string the sequence of substrings that are enclosed in < and >. Then the N value of the operator is used to index into this sequence, and the RIGHT regex pattern is tested against that indexed string value. For example, msg.hdr.route MATCH0 "^sips?:scscf".

The following is an example ps_routing_rules process configuration:

<ps-routing-rules>
        <screen-list>
                <list name="prepaid numbers">
                        <item>8007435693</item>
                        <item>8002920202</item>
                </list>
                <list name="personal toll-free numbers">
                        <item>8007451234</item>
                        <item>8007453321</item>
                        <item>8008741411</item>
                </list>
        </screen-list>
        <event name="XpressSIP.EveSessionRequest.1">
                <parameter>msg</parameter>
                <rule target="prepaid">
                        <![CDATA[msg.hdr.to screen "prepaid numbers"]]>
                </rule>
                <rule target="personal_tollfree">
                        <![CDATA[msg.hdr.to screen "personal toll-free numbers"]]>
                </rule>
        </event>
</ps-routing-rules>

The following is an example of pseudo-code routing rules configuration:

IF (the SIP To parameter is in the "prepaid number" screen list)
        execute prepaid;
ELSE
        execute postpaid;

Therefore, you can create the ps-routing-rules process configuration by combining all the attributes described in this section, as shown in the following example.

<ps-routing-rules>
        <screen-list>
                <list name="prepaid numbers">
                        <item>8007435693</item>
                        <item>8002920202</item>
                </list>
                <list name="postpaid numbers">
                        <item>7817435693</item>
                        <item>7814738291</item>
                </list>
        </screen-list>
        <event name="XpressSIP.EveSessionRequest.1">
                <parameter>msg</parameter>
                <rule target="prepaid">
                        <![CDATA[msg.hdr.to screen "prepaid numbers"]]>
                </rule>
                <rule target="postpaid">
                        <![CDATA[msg.hdr.to screen "postpaid numers"]]>
                </rule>
        </event>
</ps-routing-rules>

The following example shows <event> element configuration for routing based on subsystem number (SSN) for an Info_Anaylzed message.

<event name="XpressWorkXIN.EveInfoAnalyzed.1">
        <parameter>msg</parameter>
        <rule target="application-1">
                <![CDATA[msg.sccp_dest.subsystem_number == 251]]>
        </rule>
        <rule target="application-2">
                <![CDATA[msg.sccp_dest.subsystem number == 252]]>
        </rule>
        <rule target="application-default"</rule>
</event>

Description of ps_sip_agent¶

The ps_sip_agent process implements the SIP network stack and interfaces to soft switches and SIP user agents.

Description of attributes:

port

This attribute specifies the port to monitor for SIP messages. The default value is the SIP port 5060.

local-ip-addr

This attribute specifies the IP address from which messages should be sent if the host machine has more than one IP address.

send-100-trying-for-invite

This attribute indicates if the SIP agent should automatically send a 100 TRYING to an incoming INVITE. Accepted values are 1 to send or 0 to not send. The default value is 1.

invite-response-throttling

This attribute indicates whether a throttling mechanism is based on the time between an INVITE and its response. Accepted values are 1 to enable or 0 to disable. The default value is 0.

invites-in-progress-throttling

This attribute indicates whether a throttling mechanism is based on a maximum number of network INVITEs awaiting a final response. Accepted values are 1 to enable or 0 to disable. The default value is 0.

average-invite-response-time

This attribute specifies the maximum time (in seconds) to respond to an INVITE. The default value is 4.

max-invites-in-progress

This attribute specifies the maximum number of network INVITEs allowed to await a final response before a throttling procedure goes into effect. The default value is 1000.

outbound-proxy

This attribute specifies the address of the outbound proxy server to which all outgoing requests are sent. If specified, all requests are sent to this destination, regardless of the Request-URI provided in the request itself. If not specified, requests are sent to the destination specified in the maddr parameter of the Request-URI if the destination is provided or to the SIP URI specified by the Request-URI if the destination is not provided. The outbound proxy is specified in host:[port] syntax, with the port defaulting to 5060 if not provided. For example, outbound-proxy=192.168.10.1 or outbound-proxy=192.168.10.1:5061.

ignore-case-and-spaces-for-msg-comparison

This attribute indicates how the SIP stack should match the To, From, and Request URI fields. Accepted values are 1 to enable or 0 to disable. When disabled, the SIP stack matches fields only if they are identical. In this case, 200 OK SIP/2.0 and 200 Ok SIP/2.0 would be considered different. This attribute should only be enabled to facilitate interoperation with non-conforming SIP agents, and enabling this option has a negative effect on performance. The default value is 0.

fixup-sdp-version

This attribute indicates whether a SIP agent modifies all session description offers made as follows:

• a new session offer must increment the version by one from the previous session offer

• a refreshing INVITE or an INVITE on hold must use the same version as the previous session offer

• an INVITE on hold must use the same session description as the previous offer with the exception of the null address in the connection information

Accepted values are 1 to enable or 0 to disable. The default value is 0.

use-tcp-and-udp

This attribute indicates whether the SIP agent allows the use of both UDP and TCP messages. In other words, this agent follows the transport used in the first message establishing the dialog for all subsequent dialog messages. Accepted values are 1 to enable or 0 to disable.

default-transport

This attribute specifies the transport protocol the agent should use when initiating a dialog. Accepted values are udp or tcp. The default value is udp.

nat-mode

This attribute indicates whether the SIP agent runs in Network Address Translation (NAT) mode and keeps a mapping of internal and external addresses. Accepted values are 1 for enabled or 0 for disabled.

nat-ping-interval

This attribute specifies the interval used to periodically refresh mapped connections if sip_stack runs in NAT mode.

nat-mapping-unused-purge-interval

This attribute specifies the interval of the life-time of address mappings if sip_stack runs in NAT mode.

min-throttling-time

This attribute specifies the minimum length of time that sip_stack operates in throttling mode when the sip_stack switches to this mode.

nat-keepalive-type

This attribute specifies the type of messaging used by sip_stack to refresh address mappings. Accepted values are NOTIFY, OPTIONS, or SIMPLE (rn string).

The following is an example ps_sip_agent process configuration:

<ps-sip-agent
        local-ip-addr="my_ip_address"
        send-100-trying-for-invite="1"
</ps-sip-agent>

Throttling

When the number of calls becomes too large for a SIP agent to handle, a deterioration of service is unavoidable. Throttling makes the deterioration of service more gradual and establishes conditions that help resume normal service.

In throttling mode, the SIP agent rejects a certain percentage of calls depending on its load. The messages are rejected by sending 503 Service Unavailable responses. If the load reaches a point where the SIP agent cannot process any more messages, all incoming INVITES are rejected. Throttling mode is adjusted as the conditions change, and this mode is automatically turned off if the load returns to normal.

The SIP agent switches to throttling mode under the following conditions only:

• The average time to respond to an incoming network INVITE exceeds the average-invite-response-time value and invite-response-throttling has not been explicitly disabled.

• The number of network invites that are awaiting a final response exceeds the max-invites-in-progress value and invites-in-progress-throttling has not been explicitly disabled.

Description of ps_sip_rs¶

The ps_sip_rs process is a SIP redirector or a SIP proxy depending on configuration. This process balances the load to distribute incoming SIP INVITEs between all AS. The command line parameters (-r) run in redirector mode.

Description of attributes:

port

This attribute specifies the port to monitor for SIP messages. The default value is the SIP port 5060.

tag-in-to

This attribute indicates whether a tag that holds information about the selected treatment should be added to proxied INVITEs. The SIP agent later strips this tag, and the message is sent to the event dispatcher requesting the selected treatment. Accepted values are 1 for enabled or 0 for disabled. The default value is 0. This attribute is ignored in redirector mode.

to-in-contact

This attribute indicates whether a To header should be added to the contact header in the redirecting reply specifying how the To header in the redirected INVITE should appear. Accepted values are 1 for enabled or 0 for disabled. The default value is 0. This attribute is ignored in proxy mode.

ignore-case-and-spaces-for-msg-comparison

This attribute indicates how the SIP stack should match the To, From, and Request URI fields. Accepted values are 1 to enable or 0 to disable. When disabled, the SIP stack matches fields only if they are identical. In this case, 200 OK SIP/2.0 and 200 Ok SIP/2.0 would be considered different. This attribute should only be enabled to facilitate interoperation with non-conforming SIP agents, and enabling this option has a negative effect on performance. The default value is 0.

select-max-sessions

This attribute indicates whether an AS is selected based only on the number of sessions that the server has available without using any other selection criteria. Accepted values are 1 for enabled or 0 for disabled. The default value is 0.

max-calls-to-best-appserver

This attribute specifies the maximum number of consecutive times the same AS can be selected.

max-calls-to-other-appservers

This attribute specifies the maximum number off calls that must be sent to another AS.

skip-app-server-on-failure

This attribute specifies the number of calls to process without considering a previously failed AS. For example, a value of 10 indicates that the SIP redirector would not send any of the next 10 calls to a failed AS.

max-skipped-calls-backoff

This attribute is not used.

nat-mode

This attribute indicates whether the SIP stack operates in Network Address Translation (NAT) mode. Accepted values are 1 for enabled or 0 for disabled.

dns-enable

This attribute indicates whether the DNS update feature is used. This feature writes the DNS zone file with REGISTER server availability. Accepted values are 1 for enabled or 0 for disabled. The default value is 0.

dns-server

This attribute specifies the host name or IP address of the DNS server. This server is usually the local system.

dns-zone-file

This attribute specifies the location and name of the DNS zone file.

named-pid-file

This attribute specifies the location and name of the file containing the DNS server (named) process ID. The default value for this attribute is /var/run/named/named.pid.

write-dns-zonefile

This attribute specifies the length of time (in seconds) between updating the DNS zone file.

records-ttl

This attribute specifies the time to live (TTL) value written into the SOA record. The default value is 60.

max-records

This attribute specifies the maximum number of records written to the DNS zone file. The default value writes all available appserver records to the file.

use-rndc

This attribute indicates whether to use the rndc utility to reload (rndc -c /usr/sipxpress/config/rndc.conf reload). Accepted values are 1 for enabled or 0 for disabled. The default value is 0.

public-ip-addr

This attribute specifies the IP address from which messages should be sent if the host machine has more than one IP address.

invite-storage-time

This attribute specifies the length of time (in milliseconds) that the SIP redirector stores an INVITE for which there is an outstanding response. The default value is 66 seconds, determined by the number of INVITE retransmissions and the default response timeout.

local-ip-addr

This attribute specifies the IP address from which messages should be sent if the host machine has more than one IP address.

The ps_sip_rs process supports the <app-server> child element.

Description of the <app-server> element

The attributes of the <app-server> element describe the AS used for load balancing.

Description of attributes:

ip-address

This attribute specifies the IP address of an AS.

cluster

This attribute specifies the cluster to which an AS belongs. If this attribute is not specified, the default value is 0.

The following is an example of ps_sip_rs process configuration:

<ps-sip-redirect-server local-ip-addr="local ip">
        <app-server>ip-address="hostname"</app-server>
</ps-sip-redirect-server>

Cluster Attribute Description

The Application Server is deployed as a cluster. Within the cluster are the AS nodes that are always active. In redirect mode, the SIP redirector can return multiple AS in the Contact header. With a cluster attribute specified, the SIP redirector tries to return AS that belong to different clusters. By default, SIP redirector can return up to three AS.

For example, for the purpose of routing messages, the AS with IP address 10 is the best, 20 is second best, and 30 is third best. Without clustering, SIP redirector returns the following contact header:

Contact: sip:10.10.100.10, sip:10.10,100.20, sip:10.10.100.30

However, this scenario changes in a clustered configuration. Since AS 10 and 20 belong to the same cluster, the SIP redirector selects AS 30 to AS 20. Therefore, the following contact header appears:

Contact: sip:10.10.100.10, sip:10.10,100.30, sip:10.10.100.20

Clustering can be used to increase reliability. The clusters are usually based around sharing a common resource such as a media server. If this common resource fails, every AS in a cluster becomes unusable. Clustering ensures that a client will try an AS belonging to a different cluster before trying another AS of the same cluster.

Configuration of ps-proxy

For the SIP redirector to communicate with the SIP agent and the event dispatcher on each remote AS, proxy queues have to be set up in the ps_proxy process. The following is an example configuration for this setup:

<ps-proxy
        local-ip-addr="my_ip_addr"
        initiate-connect="true">
                <proxy-queue>
                        name="ps_eventdispatcher@10.10.100.10"
                        port="9063"
                </proxy-queue>
                <proxy-queue>
                        name="ps_sip_agent@10.10.100.10"
                        port="9063"
                </proxy-queue>
                <proxy-queue>
                        name="ps_eventdispatcher@10.10.100.20"
                        port="9063"
                </proxy-queue>
                <proxy-queue>
                        name="ps_sip_agent@10.10.100.20"
                        port="9063"
                </proxy-queue>
</ps-proxy>

Description of ps_softms_pcs¶

The ps_softms_pcs process provides Interactive Voice Response (IVR) media functionality using general-purpose processors rather than dedicated hardware. In other words, this process acts as a software media server. The ps_softms_pcs process can run either on the same machine as the XTML applications that use its functionality or on a remote machine dedicated to media processing. Applications use the soft media server by specifying PCS as the media server type in the media server PACs.

Description of attributes:

start-port

This attribute specifies the starting (lowest) UDP port to use for media server endpoints. The first endpoint allocated uses this port number and subsequent endpoints use the next largest port number.

initial-sessions

This attribute specifies the number of media server endpoints to create at startup.

increase-sessions

This attribute specifies the number of additional media server endpoints to create when a request cannot be fulfilled from the existing pool of endpoints.

max-sessions

This attribute specifies the maximum number of sessions to create. When this limit is reached, further requests to create an endpoint returns a resource unavailable result.

local-ip-addr

This attribute specifies the IP address that the software media server process should bind to for media processing. If this attribute is not specified, the attribute binds to the default address.

default-promptfile

This attribute specifies the indexed prompt file to be used if a language that is not configured is specified.

telephone-event-payload-type

This attribute specifies the payload type to use in SDP to represent RFC 2883. In most cases, the payload type is taken from the incoming INVITE. However, if a connection is created as inactive, this attribute is used to specify the type.

critical-timeout

This attribute specifies the length of time (in milliseconds) to wait before returning a dual-tone multi-frequency (DTMF) string when a digit timeout satisfies the digit map. For example, if the digit map is 12T and the user enters 12, a result of 12T is returned when this time limit is reached. The default value is 4000.

first-digit-timeout

This attribute specifies the length of time (in milliseconds) to wait for the user to enter the first digit after being prompted. The first digit timer starts when a play command finishes playing and a digit map has been specified. If the user does not enter any digits before this timer expires, a timeout result is returned to the application. The default value is 8000.

partial-timeout

This attribute specifies the length of time (in milliseconds) to wait before returning a DTMF string when a digit timeout does not satisfy the digit map (interdigit timeout). For example, if the digit map is 12T and the user only enters 1, a result of 1T is returned when this time limit is reached. The default value is 16000.

disable-audio

This attribute indicates whether the response to INVITEs is only 2833 (refusal of incoming audio packets). Accepted values are 1 for enabled or 0 for disabled.

inband-audio

This attribute specifies how DTMF detection is handled. Accepted values are 1 for handling by monitoring the Real-Time Transport Protocol (RTP) audio packets for DTMF frequencies or 0 for handling using RFC 2833.

DTMF-threshold

This attribute specifies the minimum threshold for detecting the start of DTMF. This attribute applies only if inband-audio is enabled. Typically, this attribute should not be changed from the default value.

DTMF-reduced-threshold

This attribute specifies the minimum threshold for detecting the continuation of DTMF. This attribute applies only if inband-audio is enabled. Typically, this attribute should not be changed from the default value.

silence-threshold-energy

This attribute specifies the minimum energy threshold for detecting voice energy. This attribute applies only if inband-audio is enabled. Typically, this attribute should not be changed from the default value of 80.

local-record-directory

This attribute specifies the directory where recordings are saved. The default value for the attribute is /usr/sipxpress/media/local.

endpoint-idle-timer

This attribute specifies an interval (in seconds). If the most recent command or response on an endpoint is greater than this interval, the endpoint is cleared and returned to the list of available endpoints. The default value is infinite, meaning no such checking is done.

read-mgcpagent-queue

This attribute indicates whether the ps_softms_pcs process reads from the MGCP agent queue instead of its normal queue. Accepted values are 1 for enabled or 0 for disabled. This attribute is intended to be used only for backwards compatibility when an Application Server running an earlier release is using a software media server on a different machine.

default-prompt-file

This attribute specifies the prompt file to use in the absence of any other selection information.

thread-poolsize

This attribute specifies the initial number of threads in thread pool. The default value is 10.

ptime

This attribute specifies the RTP packetization size.

realtime

This attribute specifies the real-time flag that controls setting the priority of threads.

sdp-subject

This attribute specifies the session name in the s = line of the SDP created by the ps_softms_pcs process.

silence-threshold-zero-crossings

This attribute is not used.

energy-threshold-low

This attribute is not used.

energy-threshold-high

This attribute is not used.

ping-list

This attribute specifies the list of hosts to ping.

codecs

This attribute specifies the codec used. Accepted values are PCMU, PCMA, or G729.

default-codec

This attribute specifies the default codec used. Accepted values are PCMU, PCMA, or G729.

select-first-requested-codec

This attribute indicates whether the first requested codec is selected. Accepted values are 1 for enabled or 0 for disabled.

fax-detection

This attribute indicated whether fax-tone detection and answering-machine-tone detection (2100 Hz) is used. Accepted values are 1 for enabled or 0 for disabled.

fax-energy-threshold

This attribute specifies the minimum energy required for fax tone detection. The default value is 1000.

fax-hit-threshold

This attribute specifies the number of times in sequence that the RTP packet analyzer has to detect a fax tone to recognize that a fax tone has been received. The default value is 5.

fax-detection-event

This attribute specifies the event for fax detection.

sessions-per-thread

This attribute specifies the number of RTP sessions that one thread handles. The default value is 64.

allow-packet-interrupt

This attribute indicates whether small, real-time packets can interrupt large, presumably non-real-time packets in order to reduce delay. Accepted values are 1 for enabled or 0 for disabled. The default value is 0.

endpoint-type

This attribute specifies the type of endpoint. Accepted values are pcs for soft media server or ms for other equipment.

rtp-relay

This attribute indicates whether the soft media server operates in RTP-relay mode. Accepted values are 1 for enabled or 0 for disabled.

n-loudest

This attribute indicates whether the n-loudest algorithm is used. When in conference mode, only add this number of the loudest speakers to the conference mix. Accepted values are 1 for enabled or 0 for disabled. The default value is 0.

udp-buf-size

This attribute specifies the UDP buffer size.

fast-packetforwarding

This attribute indicates whether RTP packets are forwarded. Accepted values are 1 for enabled or 0 for disabled. The default value is 0.

send-comfort-noise

This attribute indicates whether a comfort noise is sent after the prompts are played and continues to stream the comfort noise while collecting DTMF. Accepted values are 1 for enabled or 0 for disabled. The default value is 0.

use-comfort-noise-payload-type

This attribute specifies the packets sent. Accepted values are 1 for sending packets with payload type 13 or 0 for sending pcma/pcmu packets. The default value is 0.

comfort-noise-update-rate

This attribute specifies the length of time (in milliseconds) between sending comfort-noise packets. If this attribute is set to 0, only a single comfort-noise packet is sent. The default value is 0.

tts-server-host

This attribute specifies the IP address of the text-to-speech server.

tts-max-ports

This attribute specifies the maximum number of streaming connections.

The ps_softms_pcs process supports the <prompt> child element.

Description of the <prompt> element

The attributes of the <prompt> element indicate the codec and prompt file to use for each language. If file names are not fully qualified, they are assumed to be located in the /usr/sipxpress directory.

Description of attributes:

language

This attribute specifies the language identifier. For example, eng.

codec

This attribute specifies the codec for this language. For example, pcmu.

The following is an example ps_softms_pcs process configuration:

<ps-softms-pcs
        start-port="20000"
        initial-sessions="100"
        increase-sessions="50"
        max-sessions="300"
        local-ip-addr="10.10.100.1"
        default-prompt-file="pcs-english.vox"
        telephone-event-payload-type="101"
        partial-timeout="4000"
        critical-timeout="16000"
        first-digit-timeout="5000"
        disable-audio="0"
        tts-server-address="10.10.100.174:15000,1ocalhost:8001"
        tts-voice-gender="male"
        tts-voice-age="adult">
                <prompt>
                        language="eng"
                        codec="pcmu">pcs_English_pcmu.vox
                </prompt>
                <prompt>
                        language="spa"
                        codec="pcmu">pcs_Spanish_pcmu.vox
                </prompt>
</ps-softms-pcs>

Using Multiple Codecs

In addition to the usual G711 codec, G729 can also be used with limitations. The following capabilities are not supported by G729:

• conference mixing

• recording

• tone and DTMF generation

• in-band DTMF detection

Playing prompts and collecting DTMF using RFC 2833 is supported. The media server can simultaneously use any of the three supported codecs (PCMU, PCMA, and G729) on different media streams, allowing the use of either G729 or a mix of G729 and G711. To use G729, there should be a VOX file containing the G729 version of the prompts. The ps_create_vox_file utility makes that easier.

The selection of the codec is negotiated through the SDP with help from some configuration parameters. To specify the list of codecs that you want the ps-softms-pcs process to simultaneously support, use the codecs keyword in the configuration, as shown in the following example.

<ps-softms-pcs>codecs="PCMU,PCMA,G729"</ps-softms-pcs>

By default, the order in which the codecs are listed indicates the order of preference.

The codec can also be selected based on the order specified by the remote side. To allow the remote side to indicate the preferences using this method, set the select-first-requested-codec to 1, as shown in the following example.

<ps-softms-pcs>
        codecs="PCMU,PCMA,G729"
        select-first-requested-codec="1"
</ps-softms-pcs>

To use G729, the prompts have to be recorded in a G729 VOX file or a G729 WAV file. To map the combination of language and codec to a VOX file, use the <prompt> tag, as shown in the following example.

<ps-softms-pcs codecs"PCMU,PCMA,G729">
        <prompt>
                language="eng"
                codec="pcmu">pcs_english_pcmu.vox
        </prompt>
        <prompt>
                language="eng"
                codec="g729">pcs_english_pcmu.vox
        </prompt>
        <prompt>
                language="eng"
                codec="pcma">pcs_english_g729.vox
        </prompt>
        <prompt>
                language="spa"
                codec="pcma">pcs_spanish_pcma.vox
        </prompt>
</ps-softms-pcs>

To create a VOX file in G729 codec, or another codec, use the ps_create_vox_file utility. This utility functions similar to a prompt builder acting on a directory of audio files. The audio files can be either raw files or have a wave header, but they must be encoded in the target encoding and have a file name that starts with the index number of the clip (for example, 100_g729.wav for the clip at index 100). Only audio clip files should be in the directory.

The utility takes the parameters of the input directory, the required encoding, and the output file name, as shown in the following example.

ps_create_vox_file
Usage: ps-create_vox_file -d directory -o outputfile directory: directory in which to find raw audio files. The directory must contain only audio files, with no header, where the filename starts with a number indicating the desired index position (e.g.'100_g729.wav')
        outputfile: name of the output file to write
        encoding: one of the following:
        1 - NMS ADPCM 16
        2 - NMS ADPCM 24
        3 - NMS ADPCM 32
        4 - NMS ADPCM 64
        10 - MULAW
        11 - ALAW
        13 - PCM8M16
        14 - OKI_24
        15 - OKI_32
        16 - PCM1IMB
        17 - PCM11.6
        20 - G726
        22 - IMA_24
        23 - IMA_32
        24 - GSM
        26 - G723 5.3 kbps
        27 - G723 6.3 kbps
        28 - G729a 8 kbps

Description of ps_stats_collector¶

The ps_stats_collector process collects information about events and writes this information to the Call Detail Record (CDR). For example, you can use this process to collect information about how many times the database is accessed in an hour or how many calls are received in a day.

Description of attributes:

collect-period

This attribute specifies the length of time (in minutes) between collecting the compiled information.

report-period

This attribute specifies the length of time (in minutes) between writing the data to CDR.

log-method

This attribute specifies the method to use for writing statistics to an external database. The default value is file.

jvm-control-queue

This attribute indicates whether the use of an alternate queue, as specified in an alternate ps_jvmserver process, is allowed.

The ps_stats_collector process supports the <request-classes> element, which supports the <collect> child element. A message that indicates a request (for example, a SIP INVITE) is contained in <collect>.

Description of pt_license_server¶

The pt_license_server process handles the validation and accounting for session licenses active in the Application Server. The licenses that are available to the server are keyed and installed in the /usr/sipxpress/licenses file. The license key contains information about the machine on which the Application Server is running and the number of sessions that are available.

This process has no attributes that can be configured in the ps_master_config.xml file, but it is started by the ps_init process.

Description of pt_snmp¶

The pt_snmp process is a net-snmp sub-agent that provides responses to the SIP and MIBs. For more information, see SNMP Configuration.

This process has no attributes that can be configured in the ps_master_config.xml file, but it is started by the ps_init process.

Description of ps_sigtran_agent¶

The ps_sigtran_agent process supports the IN protocol. To configure the Signaling Transport (SIGTRAN) agent, add a <sigtran-agent> element to the configuration file.

Description of attributes:

standard

This attribute specifies the implementation standard to use for the SIGTRAN agent. Accepted values are “ansi” and “itu”.

local-asp-id

This attribute specifies the local AS process ID.

nw-app-id

This attribute specifies the network appearance identifier used by the SIGTRAN agent when communicating with the signaling gateway.

include-nw-app

This attribute indicates whether the network appearance is included. Accepted values are 1 to include or 0 to omit. The default value is 1.

include-trf-mode

This attribute indicates whether the TRF mode is included. Accepted values are 1 to include or 0 to omit. The default value is 0.

include-asp-id

This attribute indicates whether the AS process ID is included. Accepted values are 1 to include or 0 to omit. The default value is 1.

include-route-context

This attribute indicates whether the route context is included. Accepted values are 1 to include or 0 to omit. The default value is 0.

As described in the following section, the SIGTRAN agent is further configured by setting up the Signaling Gateways and the AS components within the <sigtran-agent> element.

Configuring the Signaling Gateway

The signaling gateways are configured by adding <sg>, <sgp>, and <route> elements.

Description of <sg> attribute:

name

This attribute specifies a human-readable name that identifies the signaling gateway. This name is used in logs and monitoring tools such as SNMP and the Console.

Description of <sgp> attribute:

name

This attribute specifies a human-readable name that identifies the signaling gateway. This name is used in logs and monitoring tools such as SNMP and the Console.

Description of <route> attributes:

dpc

This attribute specifies the destination point code of the route.

priority

This attribute specifies the priority of the route. A higher value indicates a higher priority.

mask

This attribute specifies a symbolic value of “network” or “cluster” or a number. The “network” and “cluster” symbolic values are preset to the corresponding mask value determined by the standard of the SIGTRAN agent to mask the correct section of the point code. The number represents the number of bits to mask off the configured dpc attribute of the tag, creating a wildcard. Configuring a route as a mask disables certain availability tracking features in the M3UA stack, consequently the receipt of a DUNA message will trigger periodic AUDITs of the affected point codes until a DAVA is received.

Signaling gateway processes are further configured by adding a <connect> or <bind> element, and then adding <endpoint> child elements.

Description of <endpoint> attributes:

addr

This attribute specifies the IP address of the IPv4 or IPv6 with which to connect.

port

This attribute specifies the connection port. The default value is 2905 (default M3UA port).

Configuring the Application Servers

The Application Servers are configured by adding the <as> element.

Description of attributes:

name

This attribute specifies a human-readable name that identifies the Application Server. This name is used in logs and monitoring tools such as SNMP and the Console.

route-context

This attribute specifies the route context of the Application Server.

pc

This attribute specifies the point code of the Application Server.

si

This attribute specifies the service indicator of the Application Server.

opc

This attribute specifies one or more originating point codes that the Application Server will accept messages from.

sccp

This attribute configures the SCCP layer of the Application Server.

tcap

This attribute configures the Transaction Capabilities Application Part (TCAP) layer of the Application Server.

Configuring SCCP

SCCP is configured by adding the <sccp> and <remote-ssn> elements. The <remote-ssn> elements describe the remote resources being connected to at the SCCP layer.

Description of <sccp> attributes:

max-data-size

This attribute specifies the maximum data size for network messages.

network-indicator

This attribute specifies the network indicator for the SCCP layer.

return-error

This attribute indicated whether the Return Message on Error for SCCP messages used. Accepted values are 1 for enabled or 0 for disabled.

gt-router

This tag configures the default point code to route any “route on global title” SCCP messages which do not have a point code specified or for which the point code is the local point code. This point code must be configured in a <route> tag under the <as> element to be reachable. It does not need to be configured to have <remote-ssn> entries.

sls-bit-size

This attribute specifies the size of the SLS bit size. Accepted values are 4, 5, or 8.

Description of <remote-ssn> attributes:

pc

This attribute specifies the point code of the remote system.

ssn

This attribute specifies the subsystem number of the remote system.

national-reserved

This attribute specifies the national reserved indicator. Accepted values are 1 for nationally reserving pc and ssn or 0 for internationally reserving pc and ssn. This value should be 1 for ANSI networks and 0 for ITU networks.

mask

This attribute specifies a symbolic value of “network” or “cluster” or a number. The “network” and “cluster” symbolic values are preset to the corresponding mask value determined by the standard of the SIGTRAN agent to mask the correct section of the point code. The number represents the number of bits to mask off the configured dpc attribute of the tag, creating a wildcard. This attribute will cause the configuration to add all point codes individually with the same SSN and other options set on the <remote-ssn> tag.

send-sst

This attribute indicated whether the SST procedures are enabled on restart for this remote-ssn. Accepted values are 1 for enabled or 0 for disabled. The default value is 0.

Remote subsystems are not required to be configured to communicate with them, the <remote-ssn> entries indicate “concerned” subsystems, which receive status updates of local subsystems and may be polled for status if send-sst is enabled.

Configuring TCAP

TCAP is configured by adding the <tcap> element. This element can be repeated.

Description of attributes:

type

This attribute specifies the TCAP user type. Accepted values are ain, cnam, or ns800.

tx-prefix

This attribute specifies the prefix for transactions from the Application Server.

map

This attribute will cause the configuration to add all point codes individually with the same SSN and other options set on the <remote-ssn> tag.

ssn

This attribute specifies the subsystem number of the Application Server process.

With the latest release, these values are also supported:

• hlr = 6

• vlr = 7

• msc = 8

Adding multiple SSNs only enables the receipt of messages from each of the listed SSNs and allows responses to be appropriately sent. To route each SSN in the list to different applications, you must use routing rules.

The following is an example <sigtran-agent> element configuration:

<sigtran-agent
        standard="ansi"
        local-asp-id="3">
                <sg name="sgl">
                        <sgp name="sgpl">
                                <connect>
                                        <endpoint>
                                                addr="192.163.202.102"
                                                port="2905"
                                        </endpoint>
                                        <endpoint>
                                                addr="7031::4978:22c::2905"
                                                port="7905"
                                        </endpoint>
                                        <endpoint>addr="10.9.9.101"</endpoint>
                                </connect>
                                <bind>
                                        <endpoint>addr="192.153.202.101"</endpoint>
                                        <endpoint>addr="2001:4973:22c::2306"</endpoint>
                                        <endpoint>addr="10.9.9.111"</endpoint>
                                </bind>
                        </sgp>
                        <sgp name="sgp2">
                                        <connect>
                                        <endpoint>
                                                addr="192.163.202.103"
                                                port="2905"
                                        </endpoint>
                                        <endpoint>addr="192.168.204.221"</endpoint>
                                </connect>
                        </sgp>
                        <route>
                                dpc="10-20-30"
                                priority="1"
                        </route>
                        <route>
                                dpc="10-20-31"
                                priority="1"
                        </route>
                </sg>
                <sg name="sg2">
                        <sgp name="sgp3">
                                <connect>
                                        <endpoint>addr="10.9.9.12"</endpoint>
                                </connect>
                        </sgp>
                        <route>
                                dpc="10-20-93"
                                priority="2"
                        </route>
                </sg>
                <as
                        name="as1"
                        route-context="2"
                        pc="11-20-30"
                        si="SCCP"
                        opc="10-20-30,10-20-31">
                                <sccp
                                        max-data-size="272"
                                        network-indicator="0"
                                        national-reserved="0">
                                                <remote-ssn>
                                                        pc="10-20-30"
                                                        ssn="330"
                                                        national-reserved="0"
                                                </remote-ssn>
                                                <remote-ssn>
                                                        pc="10-20-31"
                                                        ssn="331"
                                                        national-reserved="1"
                                                </remote-ssn>
                                </sccp>
                                <tcap>
                                        type="ain"
                                        ssn="123,124"
                                </tcap>
                                <tcap>
                                        type="ns800"
                                        ssn="123,124"
                                </tcap>
                                <tcap>
                                        type="cnam"
                                        ssn="123,124"
                                </tcap>
                </as>
</sigtran-agent>