Document usage for the SS7 simulator

[angrygreenfrogs]

Related to RestComm/jss7#100

It'd be nice to include some "Getting Started" user (or developer) level documentation explaining how to install and use the JSS7 simulator with the GMLC.

I haven't used the simulator before myself, but it looks like it has a bit of a learning curve on it. There's some related docs here:

https://github.com/RestComm/jss7/blob/master/docs/userguide/sources-asciidoc/src/main/asciidoc/Chapter-Simulator.adoc#_running_ss7_simulator

[angrygreenfrogs]

Note: There's some mention of the simulator and how to start it here:

http://documentation.telestax.com/core/gmlc/GMLC_Admin_Guide.html#_running_the_gateway_simulator

But what we're really missing is a step by step of how to actually use it and do a full test request with the GMLC.

[FerUy]

Thanks @angrygreenfrogs. Agreed.
We are currently working on some improvements for adding 3G location MAP procedures in jSS7 simulator as for RestComm/jss7#100, so I would rather wait for that to be finished to make the tutorial with all use cases...
Would you agree?

[FerUy]

Btw, that Admin Guide needs a total refactor. I'm committed to do that.

[angrygreenfrogs]

All sounds good, @FerUy. Yeah, I can see the admin guide was essentially a find/replace from USSD it looks like - a lot of it is still close to the truth, of course. In my spare minutes I'll poke around a bit more with the simulator and write down any relevant notes somewhere (perhaps I'll keep going with putting them in the readme until we pull them out into the full guides).

[FerUy]

Great @angrygreenfrogs ... actually, I've been working on that since yesterday too (along with other tasks). Will come back when finished debugging some stuff there.

[deruelle]

@FerUy do we have an issue in github to track the Admin Guide refactoring ?

[FerUy]

Yes @deruelle : this one #52

[FerUy]

@angrygreenfrogs tell me if this helps. Follow this steps in order to run the simulation. First you'll need to fix the default configuration (0.1 and 0.2):

0.1) In $JBOSS_HOME/server/simulator/data/SccpStack_sccprouter2.xml set the configuration to the following:
<?xml version="1.0" encoding="UTF-8" ?> <rule> <id value="1"/> <value ruleType="Solitary" loadSharingAlgo="Undefined" originatingType="LocalOriginated" mask="K" paddress="1" saddress="-1" networkId="0"> <patternSccpAddress pc="0" ssn="6"> <ai value="82"/> <gt type="GT0100" tt="0" es="1" np="1" nai="4" digits="*"/> </patternSccpAddress> </value> <id value="2"/> <value ruleType="Solitary" loadSharingAlgo="Undefined" originatingType="RemoteOriginated" mask="K" paddress="2" saddress="-1" networkId="0"> <patternSccpAddress pc="0" ssn="145"> <ai value="82"/> <gt type="GT0100" tt="0" es="1" np="1" nai="4" digits="*"/> </patternSccpAddress> </value> </rule> <routingAddress> <id value="1"/> <sccpAddress pc="1" ssn="6"> <ai value="83"/> <gt type="GT0100" tt="0" es="1" np="1" nai="4" digits="000"/> </sccpAddress> <id value="2"/> <sccpAddress pc="2" ssn="145"> <ai value="83"/> <gt type="GT0100" tt="0" es="1" np="1" nai="4" digits="000"/> </sccpAddress> </routingAddress> <longMessageRule/> <sap> <id value="1"/> <value mtp3Id="1" opc="2" ni="2" networkId="0"> <mtp3DestinationMap> <id value="1"/> <value firstDpc="1" lastDpc="1" firstSls="0" lastSls="255" slsMask="255"/> </mtp3DestinationMap> </value> </sap>

0.2) In $JBOSS_HOME/server/simulator/data/SccpStack_sccpresource2.xml set the configuration to the following:
<?xml version="1.0" encoding="UTF-8" ?> <remoteSsns> <id value="1"/> <value remoteSpc="1" remoteSsn="6" remoteSsnFlag="0" markProhibitedWhenSpcResuming="false"/> </remoteSsns> <remoteSpcs> <id value="1"/> <value remoteSpc="1" remoteSpcFlag="0" mask="0"/> </remoteSpcs> <concernedSpcs/>

1. Run the GMLC in simulator mode (next, I'm also binding it to the machine's IP 192.168.26.128). Go to $JBOSS_HOME/bin, then execute: ./run.sh -b 192.168.26.128 -c simulator (if you don't use the -b option, it will run in 127.0.0.1). Wait until you see the server has completely started by seeing in the console log something like this:
   13:47:56,877 INFO ServerImpl JBoss (Microcontainer) [5.1.0.GA (build: SVNTag=JBoss_5_1_0_GA date=200905221634)] Started in 1m:31s:455ms

2. From $JBOSS_HOME go to the jSS7 simulator path, i.e. cd ../tools/restcomm-jss7-simulator/bin.

3. Execute ./run.sh gui (you need to give x rights to the file, chmod +x run.sh).

4. On the GUI that pops up (see image below), just click "Start":

5. SS7 simulator configuration will pop up. Make sure M3UA settings appear like the images below:

This is consistent with what's by default configured in $JBOSS_HOME/server/simulator/data/Mtp3UserPart_m3ua1.xml

6. Set SCCP settings like it's shown below:

The latter shall be consistent with what was configured in 0.1 & 0.2, i.e. $JBOSS_HOME/server/simulator/data/SccpStack_sccprouter2.xml and $JBOSS_HOME/server/simulator/data/SccpStack_sccpresource2.xml (NEVER run the simulator previous to the server, as it might overwrite the server configuration).

7. Just in case, make sure TCAP/MAP settings is as follows:

and ATI_TEST_SERVER is set, then click "Run Test":

8. On the window that pops up, click on "Start". After some seconds, you should see that SCTP state is connected and M3UA is active, like in the following image:

In the server console log, you should see something like this:
14:31:31,775 INFO SelectorThread Connected Association [name=ass1, associationType=SERVER, ipChannelType=SCTP, hostAddress=, hostPort=0, peerAddress=127.0.0.1, peerPort=8011, serverName=serv1, extraHostAddress=[]]
14:31:31,776 INFO AssociationHandler New association setup for Association=ass1 with 10 outbound streams, and 32 inbound streams.

14:31:31,825 WARN SccpStackImpl-SccpStack Rx : MTP-RESUME: AffectedDpc=1

You are then set to test.

9. Open a browser and perform an HTTP GET test, for example: http://192.168.26.128:8080/restcomm?msisdn=59898437910 (if you are binded to 192.168.26.128)
   You should immediately receive the following "hardcoded" response:
   mcc=250,mnc=1,lac=32000,cellid=221,aol=5,vlrNumber=5555555666

Meanwhile, in the server console log, you should read something like this:
14:40:50,911 INFO MobileCoreNetworkInterfaceSbb HTTP Request received and response sent.

If you check the SS7 simulator (where the MAP ATI was sent and responded back), you should be able to see the following request and response (click on "Open Event Window" on each event logged):

10. Try an HTTP POST, for example, by issuing the following command on a terminal window at $JBOSS_HOME/bin (the following assumes the server is running binded to 192.168.26.128):
    curl -X POST -d @mlpreq.txt http://192.168.26.128:8080/restcomm

mlpreq.txt is like this (you may change the MSISDN):

`

<svc_init xmlns="MLP_SVC_INIT_310.dtd">


USERNAME
PASSWORD
SERVICEID




59899077937


<resp_timer>15</resp_timer>


</svc_init>`

You should receive the following "hardcoded" response:
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE svc_result SYSTEM "MLP_SVC_RESULT_310.DTD"> <svc_result xmlns="MLP_SVC_RESULT_310.dtd" ver="3.1.0"> <slia ver="3.1.0"> <pos> <msid>59899077937</msid> <pd> <time utc_off="-0300">20160726144431</time> <shape> <CircularArea> <coord> <X>27 28 25.00S</X> <Y>153 01 43.00E</Y> </coord> <radius>5000</radius> </CircularArea> </shape> </pd> </pos> </slia> </svc_result>

In the server console log, you should see something like this:

Parsed location request for MSISDN: 59899077937
14:44:31,083 INFO MobileCoreNetworkInterfaceSbb Generated response XML: <?xml version="1.0" encoding="UTF-8"?><!DOCTYPE svc_result SYSTEM "MLP_SVC_RESULT_310.DTD"> <svc_result xmlns="MLP_SVC_RESULT_310.dtd" ver="3.1.0"> <slia ver="3.1.0"> <pos> <msid>59899077937</msid> <pd> <time utc_off="-0300">20160726144431</time> <shape> <CircularArea> <coord> <X>27 28 25.00S</X> <Y>153 01 43.00E</Y> </coord> <radius>5000</radius> </CircularArea> </shape> </pd> </pos> </slia> </svc_result>
14:44:31,083 INFO MobileCoreNetworkInterfaceSbb HTTP Request received and response sent.

Looking forward for your feedback to close this issue and make the proper additions to Admin Guide and perhaps README file.
Best regards