ESME

1.0

Handover Document
1.0

Table of Contents
Table of Contents.................................................................................................................2 1 Overview...........................................................................................................................3 2 Network Architecture ...................................................................................................3 3. Flow Description..............................................................................................................5 3.1 Flow from IN to Rule Engine (at Airtel)...................................................................5 3.2 Flow from IN to USSD-GATEWAY (at Airtel)........................................................6 3.3 Flow from USSD-GATEWAY to Rule Engine(at AIRTEL and TATA) .................6 34 Flow from Rule Engine to USSD-GATEWAY(at AIRTEL and TATA)...................8 3.5 Flow from USSD Gateway to USSD Gateway (at TATA).......................................9 4. Scripts............................................................................................................................10 4.1 AIRTEL...................................................................................................................10 4.1.1 /root/scripts/system_status.sh............................................................................10 4.1.2 /root/ESME/rm_logs.sh....................................................................................11 4.1.3 /root/scripts/Handle_HA.sh..............................................................................11 4.2.1 /home/tata/scripts/system_status.sh.................................................................12 4.2.2 /home/tata/scripts/rm_logs.sh...........................................................................13 4.1.3 /home/tata/scripts/Monitor.sh...........................................................................13 5. Deployment Sites...........................................................................................................15 5.1 AIRTEL...................................................................................................................16 5.2 TATA......................................................................................................................17 6. Cron Entries...................................................................................................................19 6.1 AIRTEL...................................................................................................................19 6.2 TATA.......................................................................................................................19 7. Logs and Alarms............................................................................................................21 8. Configuration Details.....................................................................................................22 8.1 Logging....................................................................................................................22 8.2 SMPP Account.........................................................................................................22 8.3 IN Connectivity........................................................................................................22 8.4 Gateway Connectivity..............................................................................................22 8.5 Rule Engine Connectivity........................................................................................23 8.6 DND.........................................................................................................................23 8.7 Load Management...................................................................................................24 9. Dos and Dont...............................................................................................................25

1 Overview
ESME (Extended Short Message Entity) is one of the modules in PCN product. It act as an intermediate node between Rule Engine and USSD Gateway. It exposes SMPP interface to USSD Gateway and IN for external traffic and XML interface to Rule Engine. It maintains transaction information in session for every XML send to Rule Engine other than to terminate session.

2 Network Architecture
ESME can be used in two differect Network Architetures. Network Architecture is dependent on the fact external session request to PCN is received over SMPP or MAP protocol. When external traffic is send to PCN using SMPP protocol,ESME exposes SMPP interface for IN to send SMPP PDU over TCP/IP.

Rule engine XML string TCP/IP

Radio Signalling SS7 Signalling MSC/HLR

SS7 Signalling IN

SMPP PDU TCP/IP

SMPP PDU TCP/IP USSD Gateway

ESME
SS7 Signalling

Figure 1: Network Architecture (Traffic on SMPP protocol at AIRTEL)

When external traffic is send to PCN using MAP protocol, USSD Gateway receives and send the new session request to ESME on SMPP protocol. Hence, ESME interacts only to USSD Gateway on SMPP protocol over TCP/IP for new session requests.

Rule engine XML string TCP/IP

Radio Signalling SS7 Signalling MSC/HLR

SS7 Signalling USSD

SMPP PDU TCP/IP

Gateway Figure 2: Network Architecture (Traffic on MAP protocol at TATA)

ESME

3. Flow Description
ESME has 3 major threads(SMPP-Server, SMPP-Client and XML-receiver) which perform the major tasks. Each thread receives PDU/message from one socket connection, perform necessary operations and send it to other socket connection.

3.1 Flow from IN to Rule Engine (at Airtel)

SMPP-Server thread receives SUBMIT-SM from IN, parse it using SMPP library (refer Appendix A) and stores it in PDU structure. It sends PDU to SMPP worker for further processing. SMPP Worker finds the Rule Engine Id for the subscriber number. Then, it checks Has timeout limit for Rule Engine Id received reached or is it in uploaded DND list? If not, it converts SMPP PDU structure into XML with request type IN and send it to Rule Engine. It also maintains session for the request send to Rule Engine.

RULE Engine

XML string TCP/IP

Session Info Add new Mssisdn and its session info

SMPP Worker

SMPP PDU Handling Functions Response PDU

SMPP - PDU OBJECT

SMPP Server

SMPP PDU TCP/IP

Figure 3:IN to Rule Engine IN

3.2 Flow from IN to USSD-GATEWAY (at Airtel)

SMPP-Server thread receives SUBMIT-SM from IN, parse it using SMPP library (refer Appendix A) and stores it in PDU structure. It sends PDU to SMPP worker for further processing. SMPP Worker finds the Rule Engine Id for the subscriber number. Then, it check has timeout limit for Rule Engine Id received reached or is it in uploaded DND list? If any of the condition is met, then it sends the SUBMIT-SM receievd to USSDGateway.

USSD Gateway

SMPP PDU TCP/IP SMPP - PDU OBJECT

SMPP Sender

SMPP Worker

SMPP PDU Handling Functions Response PDU

SMPP - PDU OBJECT

SMPP Server

SMPP PDU TCP/IP

Figure 4: IN to USSD Gateway IN

3.3 Flow from USSD-GATEWAY to Rule Engine(at AIRTEL and TATA)

SMPP Reciever/ Client thread receives DELIVER-SM from USSD Gateway, parse it using SMPP library (refer Appendix A) and stores it in PDU structure. It sends PDU to

SMPP worker for further processing. SMPP-Worker finds whether it is first request in session or other than first or last. If it is first request in session, it checks has timeout limit for Rule Engine Id received reached or is it in uploaded DND list? If not, it converts SMPP PDU structure into XML with request type IN and send it to Rule Engine. It maintains session for the request send to Rule Engine. This condition is met only in TATA. If it is other than first and last request in session, it converts SMPP PDU structure into XML with request type MID and send it to Rule Engine. It maintains session for the request send to Rule Engine. If it is last request in session, it converts SMPP PDU structure into XML with request type TR and send it to Rule Engine. It does not maintain session for the request send to Rule Engine.

RULE Engine

XML string TCP/IP

SMPP Worker

Add new session info for msisdn

Session Info SMPP PDU Handling Functions Response PDU

SMPP - PDU OBJECT

SMPP Receiver Response PDU

SMPP PDU TCP/IP

USSD Gateway Gateway to Rule Engine Figure 5: USSD

34 Flow from Rule Engine to USSD-GATEWAY(at AIRTEL and TATA)

XML- Receiver thread receives XML from Rule Engine and send XML to XML worker for further processing. XML worker retrieves session for subscriber number. If session is not found, it drops the XML. If session is found, it converts XML to SMPP PDU and send to SMPP Sender method. SMPP Sender send PDU to USSD Gateway.

RULE Engine
XML string TCP/IP XML Receiver

XML received Get session info for msisdn

XML Worker

Session Info

SMPP - PDU OBJECT

SMPP Sender SMPP PDU TCP/IP

USSD Gateway6 Rule Engine to USSD Gateway Figure

3.5 Flow from USSD Gateway to USSD Gateway (at TATA)

SMPP Reciever/ Client thread receives DELIVER-SM from USSD Gateway, parse it using SMPP library (refer Appendix A) and stores it in PDU structure. It sends PDU to SMPP worker for further processing. SMPP-Worker finds whether it is first request in session or other than first or last. If it is first request in session and timeout limit for Rule Engine Id has reached or is in uploaded DND list,it send SMPP PDU to USSD Gateway. It does not maintain session for the request send.
SMPP Worker

SMPP - PDU OBJECT SMPP PDU Handling Functions Response PDU

SMPP - PDU OBJECT SMPP Sender

SMPP Receiver Response PDU SMPP PDU TCP/IP SMPP PDU TCP/IP

Figure 7 USSD Gateway to USSD Gateway

USSD Gateway

4. Scripts
4.1 AIRTEL
4.1.1 /root/scripts/system_status.sh
#!/bin/bash echo '<--------------------------------------------------------------------------------------------->' echo 'DATE-----TIME' date Prints current date and time echo 'CPU STATUS' top -n 1 -b | grep java top -n 1 -b | grep Tasks top -n 1 -b | grep Cpu top -n 1 -b | grep Mem top -n 1 -b | grep Swap top -n 1 -b | grep ESME top -n 1 -b | grep USSD Prints current status of CPU, Memory and modules running on system echo echo 'DISC STATUS' df k Prints current disc occupancy echo '<--------------------------------------------------------------------------------------------->' netstat -an | grep 5050 Prints currently connected IPs from IN and their socket status echo '<--------------------------------------------------------------------------------------------->' netstat -an | grep 415 Prints current socket status with Rule Engine echo '<--------------------------------------------------------------------------------------------->' netstat -an | grep 2050 Prints current socket status with Gateway

echo '<--------------------------------------------------------------------------------------------->' echo "Stack Stats" cd /opt/dialogic . ./../../root/GATEWAYSCRIPTING/USSDGATEWAY/Env.ini echo './gctload -t1' ./gctload -t1 Prints current status of meesages on septel stack echo '<--------------------------------------------------------------------------------------------->' echo './gctload -t2' ./gctload -t2 Prints current message in queues of septel stack echo '<--------------------------------------------------------------------------------------------->'

4.1.2 /root/ESME/rm_logs.sh
#!/bin/bash cd /var/PCN_ESME_LOG/ echo Deleting Log files older than 1 hrs echo `date` find * -cmin +4000 -exec rm {} \; Delete logs older than 4000 minutes from /var/PCN_ESME_LOG

4.1.3 /root/scripts/Handle_HA.sh
cd /root/scripts pgrep -x ESME_PCN > esme.txt Get process id of ESME_PCN in esme.txt if [[ -s esme.txt ]] then echo "ESME is up and running....." else echo `date` echo "ESME is down." pgrep -x ESME_PCN|xargs kill -9 cd /root/ESME/

. ./Env.ini ./ESME_PCN & Start ESME_PCN if it is not running fi

4.2 TATA
4.2.1 /home/tata/scripts/system_status.sh
#!/bin/bash echo '<--------------------------------------------------------------------------------------------->' echo 'DATE-----TIME' date Prints current date and time echo 'CPU STATUS' top -n 1 -b | grep Tasks top -n 1 -b | grep Cpu top -n 1 -b | grep Mem top -n 1 -b | grep Swap top -n 1 -b | grep ESME top -n 1 -b | grep USSD Prints current status of CPU, Memory and modules running on system echo echo 'DISC STATUS' df k Prints current disc occupancy echo '<--------------------------------------------------------------------------------------------->' echo "RAM STATUS" free echo '<--------------------------------------------------------------------------------------------->' netstat -an | grep 9000 Prints currently connected IPs from IN and their socket status echo '<--------------------------------------------------------------------------------------------->' netstat -an | grep 400 Prints current socket status with Rule Engine

echo '<--------------------------------------------------------------------------------------------->' netstat -an | grep 2052 Prints current socket status with Gateway echo '<--------------------------------------------------------------------------------------------->' echo "Stack Stats" cd /opt/dialogic . ./../../root/GATEWAYSCRIPTING/USSDGATEWAY/Env.ini echo './gctload -t1' ./gctload -t1 Prints current status of meesages on septel stack echo '<--------------------------------------------------------------------------------------------->' echo './gctload -t2' ./gctload -t2 Prints current message in queues of septel stack echo '<--------------------------------------------------------------------------------------------->'

4.2.2 /home/tata/scripts/rm_logs.sh
#!/bin/bash cd /mysql/logs/ESME_LOG echo Deleting Log files older than 1 hrs echo `date` find * -cmin +2880 -exec rm {} \; Delete logs older than 2880 minutes from /mysql/logs/ESME_LOG

4.1.3 /home/tata/scripts/Monitor.sh
cd /home/tata/scripts pgrep -x ESME > esme.txt Get process id of ESME in esme.txt if [[ -s esme.txt ]] then

echo "ESME is up and running....." else echo `date` echo "ESME is down." pgrep -x ESME|xargs kill -9 cd /home/tata/ESME_PCN/ . ./Env.ini ./ESME & Start ESME if it is not running fi

5. Deployment Sites

5.1 AIRTEL
Steps to connect 1. Connect Mohali: IP 117.99.128.54 user putty password - echo@one97 2. Redirect Delhi from Mohali : IP - 10.2.29.67 user puttyuser password secured! 197 3. Reditrect Application server from Mohali: IP 10.31.33.142 user root password redhat ESME is deployed at location /root/ESME/ . Its configuration file config.txt and PcnInstanceConfig.properties at location /root/ESME Log location /var/PCN_ESME_LOG/ DND file validator location is /root/DND_VALIDATOR/ DND file location is /root/DND_FILES Steps to validate ./validateFile f DNDfileName Error message will be displayed if validation error is found in DND file.

Steps to run cd /root/ESME . Envi.ini nohup ./ESME_PCN &

5.2 TATA
Steps to connect 1. Connect : IP 182.156.191.39 or 182.156.191.40 user tata password - tata@197 2. Redirect or ssh from IP mentioned above: (App-1) IP - 182.156.191.20 user tata password tata@197 3. Redirect or ssh from IP mentioned above: (App-2) IP - 182.156.191.17 user tata password tata@197 ESME is deployed at location /home/tata/ESME_PCN. Its configuration file config.txt at /home/tata/ESME_PCN and PcnInstancesConfig.properties at /home/tata/COMMON/conf/. Log location /mysql/logs/ESME_LOG/ ESME is deployed at location /root/ESME/ . Its configuration file config.txt and PcnInstanceConfig.properties at location /root/ESME DND file validator location is /home/tata/DND_VALIDATOR/

DND file location is /home/tata/DND_FILES Steps to validate ./validateFile f DNDfileName Error message will be displayed if validation error is found in DND file. Steps to run cd /home/tata/ESME_PCN . Envi.ini nohup ./ESME & It can be done from root access only.

6. Cron Entries
6.1 AIRTEL
* * * * * /root/scripts/system_status.sh >> /root/scripts/system_status.log * * */1 * * /root/ESME/rm_logs.sh 1>>/root/ESME/rm_logs.log 2>>/root/ESME/rm_logs.log * * * * * /root/scripts/Handle_HA.sh >> /root/scripts/HA.log 2>>/root/scripts/HA.log

6.2 TATA
* * * * * /home/tata/scripts/Monitor.sh >> /home/tata/scripts/Monitor.log * */2 * * * /home/tata/scripts/rm_logs.sh >> /home/tata/scripts/rm_log.log * * * * * /home/tata/scripts/system_status.sh >> /home/tata/scripts/system_status.log

7. Logs and Alarms

1. Current TPS Submit Sm received from IN in last 1 minute [xxxx] Above mentioned log in latest Alarm log file at log location 2. Timeouts sessionScannerMethod: Search above mentioned log in latest ESME log file at log location to find when timeouts have occurred Session scanner:: RuleEngineId [x] timeout [yy] consecutiveTimeout [zz] Above mentioned log in latest Alarm log file says timeouts condition has reached for Rule Engine Id x in last minute, yy timeouts had occurred

3.

Cumulative Counts These are printed half hourly in latest Alarm log file displayCounters:: IP[10.124.157.17] total Received from IP[754469] send to Engine[674935] directly Send to Gateway[904] dnd Applied to Numbers[78630] total Timeout from Engine[15] total Dropped[0] Above mention log dispalys traffic counters for IP that initaite new session request displayCounters:: EngineId[0] total Send to engine [104776] total Received from engine [104776] directly Send to Gateway[0] total Timeout from engine[3] no Of TimeOut in minutes[0] Above mention log dispalys traffic counters for rule engines Response Time from Rule Engine MSISDN [9029547177] response time 0 Above mentioned log in latest ESME log file displays the response time taken by Rule Engine for msisdn

4.

5.

Way to check MSISDN notifcation is received at ESME grep MSISDN in latest ESME log file or the file made at that point of time

8. Configuration Details
8.1 Logging
TRACE_LEVEL o 1 error mode o 2 PDU mode o 3 DEBUG mode o 4 GENERIC LOG_FILE Location of logging file ALARM_LOG_FILE Location of alarm log file

8.2 SMPP Account

SMPP protocol parametrs as configured at IN or USSD Gateway according to SMPP protocol specfications V3.4 SMPP_PASSWORD - password SMPP_SYSTEM_ID system id SMPP_SOURCE_ADDRESS source address SMPP_ADDRESS_RANGE address range SMPP_DEST_TON destination ton SMPP_SRC_TON source ton SMPP_DEST_NPI destination NPI SMPP_SRC_NPI sourec NPI SMPP_ENQUIRE_INTERVAL Interval after which Enquire Link Request is to be send to USSD Gateway

8.3 IN Connectivity
IN_SERVER_PORT Port at which ESME binds and IN tries to connect MAX_IN_CONNECTIONS Maximum number of socket connections allowed to IN SELF_IP IP at which ESME binds and IN tries to connect

8.4 Gateway Connectivity

GATEWAY_INSTANCES_COUNT Total USSD Gateway connected to ESME GATEWAY_PORT_1 Port of 1st Gateway connected to ESME GATEWAY_IP_1 IP of 1st Gateway connected to ESME

GATEWAY_PORT_X - Port of X Gateway connected to ESME GATEWAY_IP_X IP of X Gateway connected to ESME

8.5 Rule Engine Connectivity

ENGINE_CONFIG_FILE Location of Configuration file of Rule Engine Server details RULE_ENGINE_FILTER o 1 : modulo division of series o 2 : series division in Rule Engines RULE_ENGINE_CONNECTIONS_COUNT Total socket connections to each Rule Engine CURRENT_RULE_ENGINE_INSTANCES_COUNT Total Rule Engine connected to ESME DEFAULT_RULE_ENGINE_INSTANCE_ID Rule Engine ID if no ID was found for a series (optional parameter) SERVER_PORT Port number from which Rule Engine listens incrementally for the socket connection SERVER_IP_1 IP of 1st Rule Engine SERVER_SERIES_COUNT_1 It is for 1st Rule Engine o 0 when RULE_ENGINE_FILTER is 1 o Count of total series assigned to Rule Engine when RULE_ENGINE_FILTER is 2 SERVER_SERIES_1 It is not read when RULE_ENGINE_FILTER is 1. Otherwise, it should have comma separated series assigned to 1st Rule Engine. SERVER_IP_X IP of X Rule Engine SERVER_SERIES_COUNT_X It is for X Rule Engine o 0 when RULE_ENGINE_FILTER is 1 o Count of total series assigned to Rule Engine when RULE_ENGINE_FILTER is 2 SERVER_SERIES_X It is not read when RULE_ENGINE_FILTER is 1. Otherwise, it should have comma separated series assigned to X Rule Engine.

8.6 DND
IS_DND_FEATURE o 1 DND feature is on o 0 DND feature is off IS_PARSING_ON o 1 If short message received is to be parsed for patterns o 0 Short message received is not be parsed DND_CHARACTER If this character is found at the end of short message received, then number is treated as DND number (optional parameter) DND_TOKEN Token that separates two DND numbers in DND file DND_MSISDN_LENGTH Length of MSISDN in DND file DND_FILE Folder where DND files are kept

DND_RELOAD_TIME Time at which DND file should be re-loaded into the system IS_CALL_DURATION o 0 Call duration pattern is not necessary in short message o 1 - Call duration pattern is necessary in short message CALL_CHARGE_MSG_FORMAT_X X call charge format, $LASTCALLCOST is necessary variable to be present in this format BALANCE_MSG_FORMAT_X X balance format, $NEWBALANCE is necessary variable to be present in this format CALL_DURATION_MSG_FORMAT_X X call duration format, $LASTCALLDURATION is necessary variable to be present in this format OUTPUT_CALL_CHARGE_MSG_FORMAT Output format of call charge if parsing is enabled OUTPUT_BALANCE_MSG_FORMAT Output format of balance if parsing is enabled OUTPUT_CALL_DURATION_MSG_FORMAT Output format of call duration if parsing is enabled

8.7 Load Management

INITIATION_SOURCE o 1 SMPP Server is to be initalized and external load will come from IN o 4 SMPP Server is not initalized and external load will come from USSD Gateway MAX_OBJECTS - Maximum sessions that can be maintained by ESME, it should not be greater than 50000 OBJ_TIMER Maximum duration that any session can exist in system, if this limit exceeds then it is treated as timeout MAX_TIMEOUT Maximum number of timeouts from Rule Engine, if this limit exceeds then traffic will be directed to USSD Gateway for that minute. MAX_CTS_TIMEOUT - Maximum number of cotinuous timeouts from Rule Engine, if this limit exceeds then traffic will be directed to USSD Gateway for that minute. IS_TR_ON_TIMEOUT o 1 - XML with termination reason is send to Rule Engine on timeout o 0 - XML with termination reason is not send to Rule Engine on timeout RECONNECT_INTERVAL An attempt to connect Rule Engine is made after this interval elapses if Engine not connected ESME_ID ID to be appended each transaction id generated by ESME

9. Dos and Dont

Always manually kill or restart at ESME after cumulative logs are printed for last half an hour. For example: If current system time is 12:15, do not kill ESME.Wait till cumulative counts are printed in latest Alarm log file After logs are printed, kill ESME and script will re-start ESME.