Home

API Specification

1. tag 0 timeout 15 detect_abort yes ip_addr int int int int ip_port 0 gt lt pcm_source span string timeslot int first_bit 0 bandwidth 64 gt lt lapd_monitor gt lt new gt lt lt job id string gt A LAPD monitor extracts ISDN LAPD signal units from a timeslot and forwards the signal units to the TCP port specified by the IP address and port number su esu Whether or not correct signal units and error signal units should be delivered respectively buffer_limit f the socket carrying the signalling to the controller has a backlog greater than this limit the GTH issues an event average_period the time in seconds the average load is calculated over tag A user supplied value which is then sent in the header of each packet generated by this job timeout f there are no correct SUs for this many seconds the link state moves to down detect_abort If the link switches to sending abort signals change link states to down A standards conforming LAPD link in normal operation never contains an abort signal Seven or more consecutive 1 bits Monitoring Socket Protocol The signal units extracted from a link using a lapd_monitor are forwarded to the external host given by the ip_addr over a TCP socket separate to the socket used for API commands The GTH expects the external host to be listening on this socket before the new command is issued Each signal unit is delivered on a dedicate
2. 0x07 DL Establish Indication none 0x09 DL Release Confirm none Ox0A DL Release Indication none 0x10 MDL Error Indication one octet the ASCII value of the error code A O The messages transmitted on the socket to the GTH are Opcode Signal name Data following the header 0x01 DL Data Request Up to N201 octets of payload 0x05 DL Establish Request none 0x08 DL Release Request none The implementation defined timer and counter values are Parameter Default value Unit T200 1000 ms T203 10000 ms N200 3 attempts N201 260 octets k 7 outstanding frames Error reasons re re fused The GTH is already decoding signalling at maximum capacity fused The GTH already has the maximum number of signalling sockets open conflict The GTH is already decoding a different incompatible protocol on the given input timeslots Standards ITU T Q 920 and ITU T Q 921 Example Setting up one duplex LAPD channel gt lt new gt lt lapd_layer ip_addr 172 16 2 side network sapi 3 tei 9 gt 1 ip _port 1234 tag 548 lt pcm_source span 2A timeslot lt pcem_sink span 2A timeslot lt lapd_layer gt lt new gt lt job id lapd123 gt 53 6 gt 6 gt 3 19 new lapd_monitor 3 COMMANDS 3 19 new lapd_monitor gt lt new gt lt lapd_monitor id string Su yes esu no load_limit 50 buffer_limit 256000 average_period 30
3. The final class of errors is the most subtle nothing crashes but the results aren t as expected The tools for solving that are the API manual the log files Ethernet traces e g from tcpdump or wireshark and Corelatus support at http www corelatus com contact html 3 COMMANDS 3 Commands This chapter describes each GTH command in detail Each section starts with a brief description of the syntax A right arrow starts each possible variant of a command for instance lt custom name inventory board http_server os gt lt attribute name string value string gt lt custom gt The custom command in the example above has one parameter name and that parameter is shown in bold because it is mandatory Name has four possible values which is indicated by listing the values separated by a vertical bar The custom command always contains at least one attribute the dots indicate that you can have more than one attribute The attribute has two string parameters both bold and therefore both mandatory A few commands such as update section 3 35 have more than one variant Each variant starts with a new arrow gt The GTH s possible successful responses to each command are shown in the same format but start with a left arrow lt lt ok gt Abnormal responses When the GTH cannot execute a command the GTH responds with error lt lt error reason bad argument busy confli
4. buffer_overrun remote_close ip_addr int int int int ip_port int gt lt event gt Error reasons refused The GTH is already decoding signalling at maximum capacity 37 3 11 new atm_aal5_monitor 3 COMMANDS refused The GTH already has the maximum number of signalling sockets open conflict The GTH is already decoding a different incompatible protocol on the given input timeslots Standards ITU T 1 363 5 and ANSI T1 111 1 section 2 2 3A T1 635 Example Monitoring a standard 1980kbit s ATM AAL5 channel This example uses VPI VCI 0 5 which is the channel used in SS7 HSSL high speed signalling link gt lt new gt lt atm_aal5_monitor vpi 0 vci 5 ip_addr 172 16 2 1 ip_port 1234 tag 98 gt lt pcm_source span 2A timeslot 1 gt lt pcm_source span 2A timeslot 15 gt lt pcem_source span 2A timeslot 17 gt lt pcm_source span 2A timeslot 31 gt lt atm_aal5 monitor gt lt new gt lt job id at5m199 gt Example Examining the AAL5 counters gt lt query gt lt job id at5m199 gt lt query gt lt lt state gt lt atm_aal5_monitor id at5m199 owner apic18 gt lt attribute name span value 3A gt lt attribute name timeslot value 1 gt lt attribute name n_sdu value 136134 gt lt attribute name sdu_o value 13461346 gt lt at
5. dup_fisu no Issu yes dup_Issu no msu yes eSu no mark_likely_retrans no load_limit 50 buffer_limit 256000 average_period 30 tag 0 esnf no ip_addr int int int int ip_port 0 gt lt pcm_source span string timeslot int first_bit 0 bandwidth 64 gt lt mtp2_monitor gt lt new gt lt lt job id string gt An MTP 2 monitor passively extracts MTP 2 signal units from an MTP 2 link and forwards them to a server over TCP Both single timeslot 56 or 64kbit s and a list of timeslots ITU T Q 703 Annex A or ANSI T1 111 1 section 2 2 2 are supported id only required when issuing an update The job ID of the item being updated It is not allowed as part of a new fisu whether or not FISUs should be sent to the external system dup_fisu whether or not duplicate FISUs should be delivered lssu dup_lssu msu analogous to fisu dup_fisu mark_likely_retrans undocumented and unsupported option ip_addr the destination IP address for the packets A dotted quad e g 172 16 2 1 load_limit a percentage of maximum MSU load if the load exceeds this an event s generated buffer_limit sets the limit at which an alarm is generated if more than N bytes are queued for transmission on a socket The default corresponds to half the buffer size The buffer limit is the same for all mtp2_monitor jobs i e itis always set to either the default or whatever was specifi
6. lt lapd_layer gt lt new gt lt lt job id string gt A lapd_layer terminates a LAPD ISDN Layer 2 signalling link The GTH can act as either the network or the user side of the link selectable on a per job basis A lapd_layer requires both a sink and source Normally these will be the same E1 T1 and timeslot usually timeslot 16 Side either network or user SAPI and TEI identifiers the GTH uses on the signalling link tag a user specified integer in the range 0 65535 Each signal unit is marked with this tag ip_adar and ip_port these parameters define the TCP port the GTH will connect to in order to transfer the signal units After the initial setup through the XML interface the specified socket is used to transfer signal units All messages on the socket have an eight octet header Bt 4 S29 8 7 O15 41 3 21 1 octet octet 2 octet 4 protocol i octet The ength indicates the number of octets following the length field including the rest of the header The tag is a user specified channel identifier The tag must have the same value in the initial XML command and in all subsequent communication with the LAPD data transfer socket The messages transmitted on the socket by the GTH are 52 3 18 new lapd_layer 3 COMMANDS Opcode Signal name Data following the header 0x02 DL Data Indication Up to N201 octets of payload 0x06 DL Establish Confirm none length is always 6
7. 4 5 SONET Links 4 RESOURCES 4 4 3 LOP resources On SDH links used for carrying E1 T1 lines the GTH exposes another level of resources representing the VC 11 VC 12 When AU 3 these resources are named sdhX hopB_A lopL_M where X B A L and M are integers When AU 4 these resources are named sdhX hopB_A lopK_L_M Example assuming an STM 1 with AU 3 the resource sdh1 hop1_1 lop1_1 represents the first VC 12 inside the first TUG 2 inside the first and only AU 3 in the first and only STM 1 Example assuming an STM 1 with AU 4 the resource sdh1 hop1_1 lop3_7_3 represents the last VC 72 inside the last TUG 2 inside the last TUG 3 The read only attributes are Attribute Notes status The current state at LOP level OK TU AIS TU LOP LP AIS LP PLM LP RDI LP UNEQ signal_label The LOP signal label payload type trace_identifier The name given to the LOP by the remote equipment entered The number of times the state was entered There are four of these counters one for each state duration The number of milliseconds the link has been in the state in total There are four of these counters LP BIP The Lower Order Path Bit Interleaved Parity counter LP REI The Lower Order Path Remote Error Indication counter Section 3 30 shows an example of reading out a LOP resource s state and counters Whenever the LOP resource changes states it broadcasts an event lt lt event gt lt sdh_message
8. MS AIS Multiplex Section Alarm Indication Signal means that there is an incoming signal but that the link is not in ser vice MS RDI Multiplex Section Remote Defect Indication means that there is an incoming signal but that the remote system has detected a problem trace_identifier The name given to the link by the remote equipment entered The number of times the state was entered There are four of these counters one for each state duration The number of milliseconds the link has been in the state in total There are four of these counters RS BIP The RS BIP counter Regenerator Section Bit Interleaved Parity MS BIP The MS BIP counter Multiplex Section Bit Interleaved Parity MS REI The MS REI counter Multiplex Section Remote Error Indica tion child The name of a child resource In AU 3 mode there are three children and thus three child attributes In AU 4 mode there is only one child 98 4 4 SDH Links 4 RESOURCES Each SDH resource broadcasts an event when its state changes lt lt event gt lt sdh_message name sdh1 state OK RS LOF MS AIS MS RDI gt lt event gt 4 4 2 HOP resources An SDH link can carry many independent streams of signalling and data These streams are organised into a multiplexing structure The HOP resources represent the counters at the AU 3 AU 4 level Each of these resources is named sdhE hopF_G where E F and G are integers and the colon
9. The ethernet interfaces on GTH 3 0 and STH 3 0 support 100 Mbit s If using more than 32 E1 lines or 42 T1 lines distribute the load evenly over the two ethernet interfaces by setting up some jobs to send packets to an address on the subnet eth1 uses and other jobs to send packets to an address on the subnet eth2 uses See also The recorder command described on p 70 Example Recording an entire E1 T1 to UDP gt lt new gt lt wide_recorder span 3A tag 39 gt lt udp_sink ip_addr 172 16 2 1 ip_port 2221 gt lt wide_recorder gt lt new gt lt lt job id strw11 gt 80 3 29 nop 3 COMMANDS 3 29 nop gt lt nop gt lt lt ok gt The nop no operation command does nothing The GTH responds immediately with an ok Applications which want to supervise the GTH i e detect a fault in the GTH or the ethernet connecting it can send periodic nop commands to check that the GTH is responding See also Section 5 4 describes how to use the nop command to supervise a GTH 81 3 30 query 3 COMMANDS 3 30 query lt query verbose false gt lt job id string gt lt query gt gt lt query verbose false gt lt resource name string gt lt query gt lt lt state gt lt atm_aal0_monitor gt lt atm_aal0_layer gt lt atm_aal2_monitor gt lt atm_aal5_monitor gt lt cas_r2_linesig_monitor gt lt cas_r2_mfc_detector gt lt
10. gt lt new gt lt player loop false gt lt tcp_source ip_addr int int int int ip_port int gt lt pcm_sink span sstring timeslot int bandwidth 64 gt lt player gt lt new gt lt lt job id string gt A player is used to play audio on an E1 T1 timeslot The GTH plays the audio exactly as is octet for octet The input data can be voice tones or even raw signalling data There are two possible sources of audio Either the audio is streamed in over a dedicated TCP socket a tcp_source or the audio is replayed from a clip which was previously stored in the GTH s memory loop when playing from a clip setting joop t rue repeats the clip forever When all the audio has been played on the timeslot the GTH automatically deletes the player job and issues an event lt lt event gt lt message_ended id string gt lt event gt How to play from a tcp_source 1 Establish a listening TCP socket on the controller In C on Unix like systems this is done using the listen call 2 Issue the XML command to start a player The GTH will now connect to the specified TCP socket on the controller 3 On the controller accept the inbound connection In C this is done using the accept Call 4 On the controller send the audio data TCP has flow control so the data being sent is not timing sensitive Write data until the socket blocks 64 3 22 new player 3 COMMANDS Implicit Conferences If anot
11. 0 bandwidth 64 gt lt cas_r2_mfc_detector gt lt new gt lt lt job id string gt A CAS R2 MFC register signalling detector detects the CAS tones 1 15 CAS MFC is normally used in conjunction with CAS line signalling tag A user supplied value which is then sent in the header of each packet generated by this job direction CAS MFC uses one set of frequencies for each direction of signalling This parameter selects which of the two Monitoring Socket Protocol The signalling information extracted from a link using a cas_r2_mfc_detector is forwarded to a socket on a remote machine defined by ip_addr and ip_port This socket is independent of the controller s API socket The GTH expects the external host to be listening on this socket before the new command is issued Each MFC tone is delivered with a 16 octet big endian header s epee BT 7 8 5 4 8 21 tO octet 0x06 octet 0x08 Timestamp octet Ox0a octet Ox0c octet 0x0e Length the number of octets following the length field including the rest of the header Tag the tag value sent by the controller in the XML command Type 1 start of tone 2 end of tone Digit The Q 400 digit number 1 15 Error reasons refused The GTH is already decoding signalling at maximum capacity 41 3 13 newcas_r2_mfc_detector 3 COMMANDS refused The GTH already has the maximum number of signalling sockets open conflict The GTH is already decoding a differ
12. 1 LAPD 2 Frame Relay FS 1 Frame too short FL 1 Frame too long NA 1 Non octet aligned frame not a multiple of 8 bits AF 1 Aborted frame frame was terminated by an abort signal CR 1 Invalid CRC timestamp Timestamp marks the instant of time the packet ended measured in milliseconds since the Unix epoch It is a monotonically increasing integer Error reasons refused The GTH is already decoding signalling at maximum capacity refused The GTH already has the maximum number of signalling sockets open conflict The GTH is already decoding a different incompatible protocol on the 50 3 17 new fr_monitor 3 COMMANDS given input timeslots Standards ITU T Q 922 Example Monitoring a quad timeslot 256kbit s frame relay channel lt new gt lt fr_monitor ip_addr 172 16 2 1 ip_port 1234 tag 98 gt lt pcm_source span 2A timeslot 13 gt lt pcm_source span 2A timeslot 14 gt lt pcm_source span 2A timeslot 15 gt lt pcm_source span 2A timeslot 17 gt lt fr_monitor gt lt new gt lt lt job id frmo146 gt 51 3 18 new lapd_layer 3 COMMANDS 3 18 new lapd_layer gt lt new gt lt lapd_layer side network sapi 0 tei 0 tag int ip_addr int int int int ip_port int gt lt pcm_source spansstring timeslot int first_bit 0 bandwidth 64 gt lt pcm_sink span sstring timeslot int bandwidth 64 gt
13. 117 5 6 Controller Replication and Failover 5 FAULT TOLERANT SYSTEMS this case the transfer command could not have saved the situation because the second server cannot always carry out the transfer before the GTH automatically deletes the jobs The solution is to configure the GTH to transfer the jobs to apic2 instead of deleting them by setting the backups list gt lt update gt lt controller timeout 20000 backups apic2 gt lt update gt lt lt ok gt In this configuration when apic1 terminates abnormally i e without a bye command the GTH will transfer all jobs owned by apici to apic2 i e to the second server All events associated with those jobs will now go to apic2 The GTH will also send an event to apic2 to inform it of the automatic transfer lt lt event gt lt backup gt lt job id play19413 gt lt job id cnxn16448 gt lt backup gt lt event gt 118 6 XML TOOLS 6 XML Tools There are several tools to help with validating XML If the GTH is rejecting an apparently valid command try passing it through a validator together with the provided DTD 6 1 Internet Explorer and Mozilla Firefox These browsers can be used to check whether a document is well formed or not Loading this file lt xml version 1 0 gt lt DOCTYPE gth_in SYSTEM http www corelatus se gth api gth_in dtd gt lt gth_in gt lt new gt lt player gt lt clip id clip please try aga
14. 3500 Hz and minimum ength in milliseconds from 20ms to 2000ms A custom detector can detect signals down to 30 dBm0 Whenever a tone is detected the GTH sends an event to the control socket which created the detector lt lt event gt lt tone detector string name string length int gt lt event gt Error reasons refused The GTH does not currently have enough capacity to start another tone detector See also The voice coding attribute of the board resource see 4 9 can be set to either alaw or mulaw voice coding Standards ITU T Q 23 Q 24 Example DTMF Tone Detection gt lt new gt lt tone_detector type DTMF gt lt pcm_source span 2A timeslot 13 gt lt tone_detector gt lt new gt lt lt job id tode9613 gt When a tone is detected the GTH sends a message like this 76 3 27 new tone_detector 3 COMMANDS lt event gt lt tone detector tode9613 name 9 length 81 gt lt event gt The tone length is approximate typically 20ms Example Tone detection interleaved with a command gt lt query gt lt resource name cpu gt lt query gt lt event gt lt tone detector tode3 name 3 length 80 gt lt event gt lt lt state gt lt state gt This example shows how asynchronously generated events can arrive at any time at all including while a command is pending Controllers must be able to deal with this situation Example
15. Detecting a CED fax tone A terminating answering fax machine always transmits a 2100 Hz tone the CED signal for at least 2600ms This example uses a length of 1800ms to provide an 800ms margin to carry out an action in response to detecting a fax call lt new gt lt tone_detector type custom frequency 2100 length 1800 gt lt pcm_source span 2A timeslot 13 gt lt tone_detector gt lt new gt lt lt job id tode83216 gt When a tone is detected the GTH sends a message like this lt event gt lt tone detector tode83216 name 2100 length 1809 gt lt event gt Example Detecting a CNG signal Some originating fax machines send the CNG signal at the start of the call gt lt new gt lt tone_detector type custom frequency 1800 length 400 gt lt pcm_source span 2A timeslot 13 gt lt tone_detector gt lt new gt 77 3 27 new tone_detector 3 COMMANDS lt job id tode83216 gt 78 3 28 new wide_recorder 3 COMMANDS 3 28 new wide_recorder gt lt new gt lt wide_recorder span string tag int gt lt udp_sink ip_addr int int int int ip_port int gt lt wide_recorder gt lt new gt lt lt job id string gt PRELIMINARY INFORMATION wide recorder is implemented for field testing on E1 T1 Monitor 3 0 and SDH SONET Monitor 3 0 This interface may change when adopted into the supported API A wide_recorder streams an e
16. The maximum _load is the highest observed current_load value All counters and timers are 32 bits wide so the octet counters on 2Mbit s frame relay link can wrap after a few hours 2 7 Handling Errors By being well separated from the controller a system using a GTH is relatively easy to debug There is no shared bus so you don t have to worry about the GTH corrupting the controllers memory or vice versa The control protocol runs over plain TCP so no proprietary device drivers intrude on your system The next sections look at the remaining problems Attempting the Impossible The first class of errors occurs when an application sends a command the GTH can t carry out For instance an application might try enabling E1 T1 port which doesn t exist lt enable name pcm972 gt 2 7 Handling Errors 2 PRINCIPLES AND TERMS lt lt error reason bad argument gt invalid PCM lt error gt These sorts of errors are fairly common during development They re easy to deal with as long your application prints or logs the error message The GTH also helps by logging incoming commands you can browse the log on the in built webserver on port 8888 commands appear in the application log which is under OS The logs can also be read automatically with a query command section 3 30 Returning to a Known State After some error conditions you want to return a GTH to a known starting state The most complete way t
17. for instance A B eth1 On other models it can be one of A Bor both If more than one input is powered up the GTH uses the one with the higher voltage ROM ID is an arbitrary value which is guaranteed to uniquely identify a particular GTH temperature indicates the PCB temperature at the part of the GTH with the greatest power dissipation In a properly ventilated rack the PCB temperature is typically 15 25 above the air temperature The voice coding affects the tone detector conferencing and players It defaults to alaw In general public telephone systems in Europe use alaw while systems in the USA use mulaw The architecture reveals the hardware generation In releases before gth2_system_33a both gth2 0 and gth2 1 are reported as gth2 Events If the temperature goes outside the allowed range 10 60 Celsius 10 70 on STH Monitor 3 0 an event is broadcast to all API sockets lt lt event gt lt alarm name board attribute temperature state set clear value string gt lt event gt If the power is lost on one of the two 48VDC inputs or on an input with power over Ethernet lt lt event gt lt alert reason power A lost power B lost power ethl lost power eth2 lost gt lt event gt If power returns on a power input lt lt event gt 109 4 10 OS 4 RESOURCES lt alert reason power A recovered power B recovered power ethl recovered powe
18. name sdhl hopl_1 lop1_1 state OK TU AIS TU LOP LP AITS LP PLM LP RDI LP UNEQ gt lt event gt 4 5 SONET Links SONET is used on 155 Mbit s links usually optical GTH modules with SFPs support SONET which in turn can carry many E1 T1 links GTH modules with electrical E1 T1 interfaces do not support SONET 100 4 5 SONET Links 4 RESOURCES 155 Mbit s E1 2 Mbit s T1 1 5 Mbit s The SONET multiplexing structure Each SONET link has resources at three of the levels in the multiplexing structure shown in the diagram above The top of the hierarchy is called sah1 and sdh2 see 4 5 1 The next level with GTH resources is at STS 1 see 4 5 2 The lowest level with GTH resources is at VT2 VT1 5 SPE see 4 5 3 E1 links are carried in V72s shown on the right side of the diagram above T1 links are carried in V77 5s The map command makes an E1 T1 carried in one of those VTs accessible to other commands 4 5 1 sdh1 and sdh2 sdh1 represents the SONET structure associated with sfp1 sdh2 and sfp2 are similarly associated The configurable attributes are Attribute Possible values OC 3 VT 2y lz5 SONET true selects SONET mode daisy_chain false true OC sets the OC level OC 3 means the optical link operates at 155Mbit s VT selects which path through the SONET multiplexing structure is used SONET selects which names are used for attributes states counters and events By
19. separates path components HOP naming example On an STM 1 link configured for AU 4 the resource sdhi hop1_1 represents the first and only AU 4 in the first and only AUG 1 in the link connected to the first SFP slot HOP naming example On an STM 1 link configured for AU 3 the resource sdh2 hop1_3 represents the last AU 3 in the first and only AUG 1 in the link connected to the second second SFP slot Each HOP resource can be queried to see its state and counters Attribute Notes status The current state at HOP level OK AU AIS AU LOP HP AIS TU LOM HP PLM HP RDI HP UNEQ signal_label The HOP signal label payload type trace_identifier The name given to the HOP by the remote equipment entered The number of times the state was entered There are four of these counters one for each state duration The number of milliseconds the link has been in the state in total There are four of these counters HP BIP The Higher Order Path Bit Interleaved Parity counter HP REI The Higher Order Path Remote Error Indication counter child The name of a child resource There are always multiple chil dren Section 3 30 shows an example of reading out a HOP resource s state and counters Each HOP resource broadcasts an event when its state changes lt lt event gt lt sdh_message name sdh1 hop1_1 state 0K AU AIS AU LOP HP AIS TU LOM HP PLM HP RDI HP UNEQ gt lt event gt 99
20. the power on that timeslot crosses the specified threshold an event appears on the API socket lt lt event gt lt level detector string state string gt lt event gt threshold 60 6 The power threshold is in dBm0 as defined in ITU T G 711 6 is the loudest possible signal on a timeslot and 60 is the quietest possible The practical range is from about 50 to about 0 with an accuracy of about 3aB type Determines which transitions are reported By default both transitions from low power silence to high power Speech and vice versa are reported period 100 10000 The time period the power is measured for in milliseconds In an IVR application a level detector could be used to detect a subscriber repeatedly attempting to speak to the application instead of pressing keys on their handset so that the subscriber can be forwarded to a human operator Ina telephone conference system party line a level detector can help identify which party is currently speaking Error reasons refused The GTH does not have enough capacity left to start another level detector Example Level Detection lt new gt lt level_detector threshold 10 type both period 200 gt lt pcm_source span 2A timeslot 19 gt lt level_detector gt lt new gt lt job id ledel gt 58 3 21 new mtp2_monitor 3 COMMANDS 3 21 new mtp2_monitor gt lt new gt lt mtp2_monitor id string fisu yes
21. Operating System Logs 4 14 HTTP Server Fault Tolerant Systems 5 1 Startup Checks 5 2 Runtime Checks 5 3 E1 T1 Layer 1 Runtime Checks 5 4 Heartbeat Supervision 5 5 Duplicating Ethernet 5 6 Controller Replication and Failover XML Tools 6 1 Internet Explorer and Mozilla Firefox 6 2 W3 Online Validator 6 3 xmllint Changelog sdh1 and sdh2 4 4 2 HOP resources 4 4 3 LOP resources 4 5 SONET Links sdhi and sdh2 4 5 2 HOP resources 4 5 3 LOP resources 1 INTRODUCTION 1 Introduction Corelatus GTH is a family of rack mounted systems for interfacing to the telecommunications network via E1 T1 and SDH SONET This note describes the commands used to control GTH hardware over ethernet The commands can be used to connect to signalling and to work with audio on timeslots Impatient Skip to the command reference starting on page 15 Looking at the commands and examples is the quickest way to see what s possible 1 1 Hardware Models E1 T1 Monitor 3 0 shown above has two 10 100Mbit s ethernet interfaces the two leftmost RJ45 ports and 64 E1 T1 receivers in the other 16 RJ45 ports It is mainly used for extracting signalling information from GSM and UMTS 3G radio networks SDH Monitor 3 0 the chassis shown above has three sub modules in one chassis has two 10 100Mbit s ethernet interfaces and two SFP slots per sub module The SFP slots accommodate SFP modules for 155Mbit s STM 1 OC 3 fiber This probe is used
22. RDI V UNEQ V gt lt event gt 4 6 Sync sources The sync resource lets you control and monitor how the GTH synchronises itself to the telecom network frequency and to the absolute time Absolute time sync GTH can adjust the absolute wall time using the Network Time Protocol NTP or by explicitly setting the time attribute NTP is the preferred method if an NTP server is configured the GTH will automatically adjust its time approximately once every 15 minutes The attributes related to the absolute time are Attribute Possible values in query Allowed values in set primary ntp an IP4 address a dotted quad as for query secondary ntp 3 ntp status the last clock adjustment read only time the current time UTC see below The NTP status indicates the last time NTP was successfully used to adjust the clock followed by the clock error in seconds Time is indicated and set using a format which places the components of the time in order of magnitude For example 11 34am on the 8 January 2002 is represented by the string 2002 1 8 11 34 00 SDH SONET network sync On hardware with SDH SONET interfaces the telecom network sync is always automatic Sync is taken from the first interface which is enabled and has status OK Or MS RDI Attribute Possible values in query Allowed values in set mode auto read only source sdhl1 sdh2 none read only status locked dead read only The special source none indicates
23. a Unix server netcat l p 2222 lt my_onhold_music alaw Netcat is a freely available package A slightly more complex command line would allow on the fly MP3 decoding Example Playing audio clips previously stored on the GTH An alternative to streaming in audio over a TCP socket is to play short clips of audio which were previously stored on the GTH like this gt lt new gt lt clip id DTMF 9 gt lt new gt lt job id clip DTMF 9 gt The audio data is sent by the client immediately after the end of the new command in a block of content with content type binary audio To play the clip gt lt new gt lt player gt lt clip id clip DTMF 9 gt 66 3 22 new player 3 COMMANDS lt pcm_sink span 4B timeslot 17 gt lt player gt lt new gt lt job id play7431 gt Use the optional Joop parameter to loop the audio from a clip forever this is useful for continuous or repeating tones It s also possible to specify several clips The GTH will join them seamlessly gt lt new gt lt player gt lt clip id clip DTMF 9 gt lt clip id clip 100ms silence gt lt clip id clip DTMF 8 gt lt pcm_sink span 4B timeslot 17 gt lt player gt lt new gt lt job id play7432 gt Example Error condition attempting to play from an unreachable IP In this example 128 250 22 3 is not reachable from the example GTH gt lt new gt lt player
24. arbitrary nonstandard combinations of timeslots cell oam_cell corrupt_cell select whether or not normal OAM and corrupt cells are delivered scrambling ATM payload scrambling is on by default ITU 1 432 3 requires scrambling xf 1 to be enabled for E1 links and leaves it optional for T1 buffer_limit f the socket carrying the signalling to the controller has a backlog greater than this limit the GTH issues an event average_period the time in seconds the average load is calculated over tag A user supplied value which is then sent in the header of each packet generated by this job Counters and Indicators Use query to read counters and indicators 27 3 8 new atm_aal0_monitor 3 COMMANDS Category Members Description Cell counters n_cells The total number of cells including idle and O amp M n_idle The number of idle cells which have arrived on the interface n_oam The number of O amp M cells Load meters current average and maximum load State current state either sync or hunt n_sync t_sync The number of times the sync state was en t_hunt tered and the number of milliseconds spent in the sync and hunt states respectively Monitoring Socket Protocol The signalling information extracted from a link using an atm_aalO_monitor is forwarded to a socket on a remote machine defined by ip_addr and ip_port This socket is independent of the controllers API socket The GTH expects the external host
25. clip gt lt connection gt lt controller gt lt error gt lt fr_layer gt lt fr_monitor gt lt job gt lt lapd_layer gt lt lapd_monitor gt lt level_detector gt lt mtp2_monitor gt lt player gt lt raw_monitor gt lt recorder gt lt resource gt lt ss5_linesig_monitor gt lt ss5_registersig monitor gt lt tone_detector gt lt wide_recorder gt lt state gt query is used to obtain information about one or more of the GTH s resources and jobs The response to a query always contains exactly as many children answers as there were jobs and resources in the command If one or more of the jobs or resources in the command result in an error the corresponding child will be an error but the query command itself will still succeed 82 3 30 query 3 COMMANDS Verbose queries Setting the verbose attribute to true makes the GTH provide detailed information about each job The return includes all the information needed to start an identical job in the same format as for the corresponding new command Jobs with counters for example mtp2_monitor then add additional attribute children for counters and indicators related to the job Example Monitoring temperature the temperature is in degrees Celsius The temperature sensor is located on the warmest part of the module lt resource name board gt gt
26. field including the rest of the header tag is specified by the user It is used for identifying the channel timestamp Timestamp marks the instant of time the packet ended measured in milliseconds since the Unix epoch It is a monotonically increasing integer Error reasons refused The GTH is already decoding signalling at maximum capacity refused The GTH already has the maximum number of signalling sockets open conflict The GTH is already decoding a different incompatible protocol on the given input timeslots See also The recorder command described on p 70 Example A raw monitor on a 64kbit s timeslot gt lt new gt lt raw_monitor tag 1182 ip_addr 172 16 2 1 ip_port 1234 gt lt pcm_source span 2A timeslot 1 gt lt raw_monitor gt lt new gt 68 3 23 new raw_monitor 3 COMMANDS lt job id ramo7219 gt 69 3 24 new recorder 3 COMMANDS 3 24 new recorder gt lt new gt lt recorder gt lt pcm_source span string timeslot int first_bit 0 bandwidth 64 gt lt tcp_sink ip_addr int int int int ip_port int gt lt recorder gt lt new gt gt lt new gt lt recorder gt lt pcm_source span string timeslot int first_bit 0 bandwidth 64 gt lt udp_sink ip_addr int int int int ip_port int gt lt recorder gt lt new gt lt lt job id string gt A recorder streams data from an E1 T1 timeslot to a remote socket via TCP or UDP The
27. gt lt state gt Example Looking up the job ID of this API connection In a sophisticated system with fail over support a controller needs to be able to identify an API socket The special query of the job called se f reveals that gt lt query gt lt job id self gt lt query gt lt lt state gt lt job id apic232 gt lt state gt Example Finding out which jobs a GTH is currently running lt query gt lt resource name schedule gt lt query gt lt lt state gt lt job id cnxn565 owner apic232 gt lt job id m2mo153 owner apic232 gt lt state gt Example Examining the GTH s logs The GTH contains two sets of logs the operating system log and the control system log These can be retrieved using queries gt lt query gt lt resource name application_log gt lt query gt lt state gt lt resource name application_log gt lt attribute name verbosity value changes gt lt resource gt lt state gt The log is delivered as a text plain block immediately following the XML block 85 3 30 query 3 COMMANDS Example Querying two players The query command accepts multiple jobs and multiple resources This provides a quicker answer than querying each job separately gt lt query gt lt job id play4 gt lt job id play5 gt lt query gt lt lt state gt lt player id play4 owner apic7 octets_played 1001728 gt lt play
28. handlers and connections between timeslots are jobs V Ei Controller tone detector source 1A ts 9 DR SeSesse5 i connection 2000 ooo 4 source 1A ts 9 sink 3A ts 7 DA m x A connection source 3A ts 7 sink 1A ts 9 ooo o GTH The figure above shows the API components used to set up a normal telephone call between two subscribers while detecting DTMF on one subscriber s line 2 1 Sending Commands to the GTH To send commands to the GTH open a socket to the GTH s API on TCP port 2089 The factory default IP address is 172 16 1 10 netmask 255 255 0 0 Once the socket is open you can start sending commands Every command starts with these three lines Content type text xml Content length 6 a blank line The content length indicates the number of octets bytes which follow the three header lines Each header line is case sensitive and is always terminated with the two octets 0x0d CR and 0x0a LF Then send the command itself Here s a complete command Content type text xml Content length 6 2 2 Commands and Responses 2 PRINCIPLES AND TERMS lt nop gt and here s the response from the GTH Content type text xml Content length 5 lt ok gt After the response the GTH waits for the next command l e the same socket is kept open indefinitely Multiple API sockets can
29. n_idle value 134690 gt lt attribute name n_oam value 134 gt lt attribute name n_sync value 1 gt lt attribute name t_sync value 346113 gt lt attribute name t_hunt value 24708 gt lt attribute name current state value sync gt lt attribute name current load value 8 gt lt attribute name average load value 4 gt lt attribute name maximum load value 32 gt lt atm_aal0_monitor gt lt state gt 30 3 9 new atm_aal0_layer 3 COMMANDS 3 9 new atm_aal0_layer gt lt new gt lt atm_aal0_layer ip_addrs int int int int ip_port int scrambling yes gt lt pcm_source span string timeslot int first_bit 0 bandwidth 64 gt lt pem_sink spansstring timeslot int bandwidth 64 gt lt atm_aal0_layer gt lt new gt lt lt job id string gt The atm_aal0_layer is unsupported Use it to transmit ATM cells on one or more timeslots of an E1 After the initial setup through the XML interface the specified socket is used to transfer signal units All messages on the socket have a six octet header at espe tw ey ey res 41 3 2 11 The ength indicates the number of octets following the length field including the rest of the header This is always 52 octets The GFC VPI VCI and PTC fields make up the ATM cell header ITU T 1 361 describes the purpose of these fields in ATM networks The GTH automatically calculates and inserts the header checksum HEC
30. on the given input timeslots Standards ITU T 1 363 2 34 3 11 new atm_aal5 monitor 3 COMMANDS 3 11 new atm_aal5 monitor gt lt new gt lt atm_aal5_monitor vpi int vei int sdu yes corrupt_sdu no scrambling yes link_load_alarm no load_limit 50 buffer_limit 256000 average_period 30 timeout 0 tag 0 ip_addr int int int int ip_port int gt lt pcm_source span string timeslot int first_bit 0 bandwidth 64 gt lt atm_aal5_monitor gt lt new gt lt lt job id string gt An atm_aal2_monitor extracts packets from the interface above the CPCS sublayer of ATM AAL5 on ATM over E1 links and forwards them to an external server over TCP vpi vci These parameters specify which AAL5 channel is monitored sdu corrupt_sdu select whether normal packets SDUs and corrupt SDUs should be delivered scrambling ATM payload scrambling is on by default ITU 1 432 3 requires scrambling a4 1 to be enabled for E1 links and leaves it optional for T1 timeout The AAL5 re assembly timeout in seconds 0 means disabled buffer_limit lf the socket carrying the signalling to the controller has a backlog greater than this limit the GTH issues an event average_period the time in seconds the average load is calculated over tag A user supplied value which is then sent in the header of each packet generated by this job Counters and Indicators Use query to read cou
31. recording is stopped by deleting the recorder or less cleanly by closing the socket To use a recorder with a TCP destination 1 Establish a listening TCP socket on the remote system for instance the controller 2 Issue the XML command to start a recorder The GTH will now connect to the specified TCP socket 3 On the remote system accept the inbound connection 4 On the remote system read the audio data as it comes in To use a recorder with a UDP destination PRELIMINARY INFORMATION Using a UDP sink is implemented for field testing with special firmware This interface may change when adopted into the supported API TCP sinks have been supported since 2002 1 Open a UDP socket on the remote system for instance the controller 2 Issue the XML command to start a recorder The GTH will now start sending UDP packets 3 On the remote system read the audio data as it comes in 70 3 24 new recorder 3 COMMANDS Data format When using TCP no headers or padding bytes are added When using UDP each UDP packet looks like this Cate eT Ay eT 8 7 8 5 4 3 2 1 0 octet 0x00 octet 0x02 octet 0x04 octet 0x06 octet 0x08 octet 0x0a Reserved octet 0x0c octet Sequence Increases by one for each packet sent for this job The initial value is undefined Error handling Recorders can encounter errors both during initial startup and while the recorder is running If the error is detected early
32. set gt lt lt ok gt gt lt install name system_image gt lt lt ok gt The firmware image is sent immediately following the install command in a block with content type binary filesystem When the GTH has completed all background tasks started by the install process it sends an event 4 lt event gt lt info reason install_done gt lt event gt Wait for that event before rebooting Do not rely on the event coming after the ok if there isn t any background work to do the event can arrive first 25 3 7 map 3 COMMANDS 3 7 map gt lt map target_type pcm_source gt lt sdh_source name string gt lt map gt lt lt resource namesstring gt Make an E1 T1 carried on an SDH SONET link available to commands which use a pcem_source The command returns the name of the mapped E1 T1 resource There are two ways to remove a mapping 1 Send an unmap command 2 Disable the SDH SONET interface this removes all mappings for that SDH SONET interface The resource name chosen by the GTH for a particular E1 T1 is always the same as long as the SDH SONET interface is configured with the same options Or sending two map commands with the same interface options results in the same response even across a reboot Example Mapping a T1 line carried on SONET VT1 5 containers can carry T1 lines Assuming the SDH interface has been enabled with SONET true OC 3 and VT 1 5 this command would m
33. set to enable buttons in the WWW interface which zero out counters on the L1 and L2 interfaces Enabling this feature is not recommended because it leads to situations where a supervising application cannot distinguish between a counter wrapping and a counter being manually zeroed URL rewriting All of the pages on the HTTP server can be overridden with user defined pages by setting an attribute to a URL Attribute Purpose top The page reached at http gth 8888 ethernet The ethernet configuration page 2 status Layer 2 MTP2 and LAPD status page os The operating system and logs page pcm_overview The PCM interface overview page status The top level system status page By default this is the same as top Example to set the top level page such that the client browser visits google lt set name http_server gt lt attribute name top value http www google com gt lt set gt lt lt ok gt 113 5 FAULT TOLERANT SYSTEMS 5 Fault Tolerant Systems GTH provides support for building systems which tolerate hardware and software failure Which features you use depends on which failures you want to be able to handle and on how much effort you want to expend on fault tolerance Each of the following sections covers an aspect of fault tolerance the sections are ordered approximately in order of difficulty 5 1 Startup Checks Automatically checking that the GTH s state using query commands at startup
34. status of jobs and resources in the GTH Restart the GTH Change a resource s attributes Transfer control of a job from one API socket to another Remove an E1 T1 resource created by the map command Change parameters in a job Set counters and timers to zero 15 explains each command in detail The GTH responds to each command The possible responses are GETO job ok resource state There is a problem with the command The successful reply to new it carries the new job s ID The successful reply to commands such as set and delete The successful reply to map it carries the mapped E1 T1 resource name The successful reply to query commands 2 3 Data on the API Socket 2 PRINCIPLES AND TERMS 2 3 Data on the API Socket In addition to the text xm1 content type the port 2089 API socket can carry blocks of data of other content types Such data blocks always come immediately after the command and use the content length header in exactly the same way as blocks carrying commands Commands which use data blocks include install query and custom the command reference for those commands notes which content type to use 2 4 Events The GTH informs the controller of asynchronous events i e events which didn t occur in direct response to a command A controller must be prepared to receive an event even when there is no command pending An event may even arrive between the moment a command is issue
35. that the internal frequency source is used because no better sync source is available 104 4 7 Ethernet Interfaces 4 RESOURCES E1 T1 network sync On hardware with E1 T1 interfaces the source controls which E1 T1 interface the GTH uses as a frequency reference The special value none causes the GTH s internal temperature compensated frequency source to be used The special value auto allows the GTH to decide which of the E1 T1 interfaces to use as a reference mode indicates whether the sync source was chosen by the GTH auto or set by the user manual Attribute Possible values in query Allowed values in set mode auto manual read only source none pcmlA pcm2A as for query plus auto status trying locked dead read only The sync state trying indicates that the GTH is attempting to sync to the given E1 T1 port when it successfully syncs the state changes to locked If the port does not contain a usable sync the state changes to dead Events If an NTP server fails to respond to NTP requests the GTH sends an event lt lt event gt lt alert reason ntp gt human readable text lt alert gt lt event gt If the E1 T1 sync system changes states the GTH sends an event showing the new state lt lt event gt lt sync_message state trying locked on dead limit reached gt lt event gt The pseudo state 1imit_reached is reported when the sync system reaches the limit of its frequency adj
36. to be listening on this socket before the new command is issued Each AIM cell is delivered with a 16 octet big endian header ata eT wT sy 8 71 6 5 41 31 21 11 octet 0x06 octet 0x08 Timestamp octet 0x0a Length the number of octets following the length field including the rest of the header Tag the tag value sent by the controller in the XML command CR set if the HEC CRC was incorrect Ver The header version currently 0x0 Timestamp A 48 bit wide field indicating the instant the packet arrived in number of milliseconds since the 1970 Unix epoch This value is nondecreasing The GFC VPI VCI and PTC fields make up the ATM cell header ITU T 1 361 describes the purpose of these fields in ATM networks 28 3 8 new atm_aal0_monitor 3 COMMANDS See also Section 2 6 describes general principles concerning layer 2 signalling sockets Link status information An ATM link running normally is in link state sync The other possible state hunt indicates that the link is not working Whenever the link switches from one to the other GTH sends an event lt lt event gt lt atm_message id string value hunt sync gt lt event gt The GTH also issues an event whenever the average_load exceeds the value supplied in load_limit lt lt event gt lt l2_alarm id string attribute string state string value string gt lt event gt The GTH also issues an event whenever the TCP socket carrying t
37. used See also wide_recorder described on p 79 Example Recording an E1 T1 timeslot to a TCP socket gt lt new gt lt recorder gt lt pem_source span 3A timeslot 1 gt lt tcp_sink ip_addr 172 16 2 1 ip_port 2221 gt lt recorder gt lt new gt lt lt job id strr11 gt Example Forwarding an E1 T1 timeslot to a TCP socket at an unreachable address lt new gt lt recorder gt lt pcm_source span 3A timeslot 1 gt lt tcp_sink ip_addr 128 250 22 3 ip_port 2222 gt lt recorder gt lt new gt lt error reason bad argument gt cannot connect to given socket lt error gt The GTH determined that 128 250 22 3 2222 was not reachable and returned an error immediately Example Forwarding an E1 T1 timeslot to a TCP socket at an unused port number gt lt new gt lt recorder gt lt pem_source span 3A timeslot 1 gt lt tcp_sink ip_addr 172 16 2 1 ip_port 2222 gt lt recorder gt lt new gt lt lt job id strr12 gt 72 3 24 new recorder 3 COMMANDS lt event gt lt fatality id strr1l2 reason cannot connect to given socket gt lt event gt The GTH issued a job id and initiated an attempt to connect to TCP port 2222 but then failed to connect so it issued a fatality 73 3 25 new ss5_linesig_monitor 3 COMMANDS 3 25 newss5 linesig_monitor gt lt new gt lt ss5_linesig_monitor tag 0 ip_addr int int
38. 1 T1 resources named pem1 pem2 pcm3 These resources appear after they are configured using the map command The configurable attributes on an E1 T1 link are 94 4 2 E1 T1 links 4 RESOURCES Attribute Possible values in query Allowed values in set framing E1 mode doubleframe multiframe as for query T1 mode extended superframe superframe as for query idle_pattern 0 255 E1 mode 84 0 255 T1 mode 127 0 255 impedance 120 100 75 as for query line_coding E1 mode HDB3 T1 mode B8ZS AMI mode El T1 E monitoring false true status disabled LOS LFA LMFA AIS RAI OK tx_ enabled true false The idle_pattern impedance line_coding monitoring and tx_enabled attributes are not present on SDH Monitor 3 0 framing can usually be left at the default setting impedance selects the receiver and transmitter impedance which depends on the type of cable used T1 installations always use 100 ohm E1 on twisted pair uses 120 ohm and E1 on coaxial cable 75 ohm idle_pattern selects the octet sent on unused timeslots Common values in practice are 84 and 255 mode is used to select E1 or T1 operation T1 is mainly used in North America whereas most of the rest of the world uses E1 In T1 mode there are 24 useable timeslots numbered 1 24 In E1 mode there are 31 useable timeslots numbered 1 31 monitoring is used for non intrusive monitoring of links typically through a resistive pad as p
39. 3 5 enable 3 COMMANDS 3 5 enable lt enable name string gt lt attribute name string value string gt lt enable gt lt lt ok gt Activates a telecom interface either an E1 T1 or an SDH SONET interface allowing other commands on the GTH to process the data carried on the interface E1 T1 interfaces are described in 4 2 SDH interfaces are described in 4 4 SONET interfaces are described in 4 5 The LED next to each telecom interface lights up when the interface is enabled See also The disable command History enable is available in release 37a and later It replaces functionality previously offered by the set command Example Enable an E1 interface gt lt enable name pcmlA gt lt attribute name framing value multiframe gt lt enable gt lt lt ok gt Example Enable a T1 interface gt lt enable name pcmlA gt lt attribute name mode value T1 gt lt attribute name framing value extended superframe gt lt enable gt lt ok gt 22 3 5 enable 3 COMMANDS Example Enable an SDH interface gt lt enable name sdhli gt lt attribute name STM value 1 gt lt attribute name AU value 4 gt lt attribute name TU value 12 gt lt enable gt lt ok gt All three attributes must be specified there are no default values 23 3 6 install 3 COMMANDS 3 6 install gt lt instal
40. 4 The alias is kept for backwards compatibility Events Whenever the TX load exceeds the load limit GTH sends an event lt lt event gt lt alarm name eth1 attribute TX load state set clear value string gt lt event gt 106 4 7 Ethernet Interfaces 4 RESOURCES Restrictions For the IP configuration the GTH API checks for some common mistakes and then allows anything else The common mistakes are e Setting an IP or mask which isn t valid e g 1 6 3 c is not an IP address e Disabling both ethernet ports e Setting an IP which is a broadcast or loopback address e Setting an unreachable gateway The on board HTTP interface also checks for e Both addresses on the same subnet e Changing an IP such that the gateway would be unreachable Routed Networks The best location for a GTH is on the same subnet as the server controlling it i e connected to the same switch or connected by a direct ethernet cable It is also possible to use a GTH on a routed network by setting the default gateway This is convenient for accessing the CLI or WWW interfaces remotely It is even possible to place the server controlling the GTH remotely The price is additional complexity Security The GTH s security is appropriate for a safe network i e free of attackers When setting a default gateway you must be confident that the entire routed network is still safe TCP timeouts A routed network may
41. CPU There are four commands to work with resources set modifies a resource s attributes section 3 32 query command section 3 30 shows a resource s settings counters and indicators enable and disable commands section 3 5 turn E1 T1 and SDH SONET interfaces on and off 4 1 Inventory and Schedule A list of the GTH s resources is always available by querying the inventory Different models of GTH hardware have different resources for instance the sfp1 resource is only present on hardware with slots for SFP modules A list of the currently running jobs is always available by querying the schedule resource Page 83 has examples of querying the schedule and inventory resources 4 2 E1 T1 links E1 and T1 lines are the basic transmission lines i e layer 1 used for voice signalling and data in most fixed and mobile telephone networks in the world E1 T1 Monitor 2 1 systems have 16 listen only E1 T1 interfaces named pcm1A pem1B pem1C pemlD pcm4D The names indicate which connector the E1 is on 1 2 3 or 4 and which pair of pins within that connector A B C or D The Getting Started leaflet enclosed with every system shows the pinouts E1 T1 Messenger 2 1 systems have eight full duplex E1 T1 interfaces named pemlA pcmlB pcm2A pcm4B E1 T1 Monitor 3 0 systems have 64 listen only E1 T1 interfaces named pcm1A pcm1B pcmlC pcmlD pcml D SDH Monitor 3 0 systems have up to 84 listen only E
42. Ver The header version currently 0 33 3 10 new atm_aal2_monitor 3 COMMANDS GFC VPI VCI PTC are all members of the AALO packet header CID LI UUI HEC are all members of the CPS packet header as described in ITU T 1 363 2 These fields are presented in the same format as 363 2 specifies Link status information An ATM link running normally is in link state sync The other possible state hunt indicates that the link is not working Whenever the link switches from one to the other GTH sends an event lt lt event gt lt atm_message id string value hunt sync gt lt event gt The GTH issues an event whenever the average_load exceeds the limit lt lt event gt lt l2_alarm id string attribute string state string value string gt lt event gt If the link_load_alarmn attribute is yes then GTH also issues load alarms for the average link load The GTH also issues an event whenever the TCP socket carrying the signalling data is congested buffer more than half full overruns or is closed remotely lt lt event gt lt l2_socket_alert reason buffer_limit buffer_overrun remote_close ip_addr int int int int ip_port int gt lt event gt Error reasons refused The GTH is already decoding signalling at maximum capacity refused The GTH already has the maximum number of signalling sockets open conflict The GTH is already decoding a different incompatible protocol
43. ame pcm3A gt lt event gt 4 3 SFP Modules The sfp1 and sfp2 resources are only present on hardware with slots for SFP modules An SFP module is an adaptor which converts a particular type of optical signal to a signal the GTH hardware can process Different types of SFPs work with different fiber types speeds connectors and wavelengths The SFP can describe itself 96 4 4 SDH Links 4 RESOURCES through a number of attributes Attribute Possible values in query Allowed values in set status OK LOS not present read only vendor a string identifying the SFP manufacturer part_number a string set by the SFP manufacturer i supported_rates OC 12 OC 3 GbE tx_enabled true false E The SFP resources broadcast an event to all API sockets when their state changes lt lt event gt lt sfp_message name sfp2 state OK LOS not present gt lt event gt 4 4 SDH Links SDH is used on 155 Mbit s links usually optical GTH modules with SFPs support SDH which in turn can carry many E1 T1 links GTH modules with electrical E1 T1 interfaces do not support SDH 622 Mbit s 155 Mbit s E1 2 Mbit s T1 1 5 Mbit s The SDH multiplexing structure Each SDH link has resources at three of the levels in the multiplexing structure shown in the diagram above The top of the hierarchy is called sdh1 and sdh2 section 4 4 1 The level at AU 3 AU 4 is described in 4 4 2 The level at C 11 C 12 is descr
44. an incorrect CRC The total number of octets in the packet types above either up or down The number of times the up and down states were entered and the number of milliseconds spent in each state LAPD links have two possible link states up and down A link moves to the up state when a correct SU is received A link moves to the down state for two possible reasons 1 No correct SUs are received for timeout seconds 2 The space between SUs is filled with something other than flags for instance abort Oxff Whenever the link switches from one to the other GTH sends an event lt lt event gt lt lapd_message id string value up down gt lt event gt The GTH issues an event whenever the average_load exceeds the load _limit lt lt event gt lt l2_alarm id string attribute string state string value string gt lt event gt The GTH also issues an event whenever the TCP socket carrying the signalling data is congested buffer more than half full overruns or is closed remotely 56 3 19 new lapd_monitor 3 COMMANDS lt lt event gt lt l2_socket_alert reason buffer_limit buffer_overrun remote_close ip_addr int int int int ip_port int gt lt event gt Error reasons refused The GTH is already decoding signalling at maximum capacity refused The GTH already has the maximum number of signalling sockets open conflict The GTH is already decodi
45. ap one of the T1 lines gt lt map target_type pcm_source gt lt sdh_source name sdhl hop2 lop3_2 gt lt map gt lt resource name pcm42 gt Once a T1 is mapped enable starts layer 1 processing on the T1 and new starts layer 2 processing on the data carried by the T1 Example Mapping an E1 T1 line carried on an STM 1 C 12 containers can carry E1 and T1 lines Assuming the SDH interface has been enabled with AU 4 and TU 12 this command would map one of the E1 T1 lines lt map target_type pcm_source gt lt sdh_source name sdhl hopl1_1 lop1_5_2 gt lt map gt lt resource name pcm18 gt 26 3 8 new atm_aal0_monitor 3 COMMANDS 3 8 new atm_aal0_ monitor gt lt new gt lt atm_aal0_monitor cell yes oam_cell no corrupt_cell no idle_cell no scrambling yes load_limit 50 buffer_limit 256000 average_period 30 tag 0 ip_addr int int int int ip_port int gt lt pcm_source span string timeslot int first_bit 0 bandwidth 64 gt lt atm_aal0_monitor gt lt new gt lt lt job id string gt An atm_aal0_monitor extracts packets from the interface above the ATM layer on ATM over E1 links and forwards them to an external server over TCP E1 installations usually use timeslots 1 15 and 17 31 to make a 1920 kbit s channel T1 installations normally use 1 24 to make a 1536 kbit s channel The GTH supports both configurations as well as
46. ater than this limit the GTH issues an event average_period the time in seconds the average load is calculated over tag A user supplied value which is then sent in the header of each packet generated by this job timeout If nonzero it indicates the maximum time in seconds the channel can be without packets before it is considered to be down Counters and Indicators Use query to read counters and indicators 48 3 17 new fr_monitor 3 COMMANDS Category Members Description Packet counters n_su The number of signal units which have arrived on the interface n_esu The number of errored signal units which is de fined as all packets which are too short too long non octet aligned or have an incorrect CRC Octet counters su_o eSU_O The total number of octets in the packet types above Load meters current average and maximum load State current state either up or down n_up t_up The number of times the up and down states n_down t_down were entered and the number of milliseconds spent in each state Link status information Frame relay links have two possible link states up and down A link moves to the up state when a correct SU is received A link moves to the down state for two possible reasons 1 No correct SUs are received for timeout seconds 2 The space between SUs is filled with something other than flags for instance abort Oxff Whenever the link switches from one to the other GTH s
47. be open at the same time the GTH will serve the API sockets concurrently The GTH guarantees three things for commands issued in one socket 1 One command is executed at a time 2 Commands are executed in reception order 3 GTH sends a response for every command in execution order 2 2 Commands and Responses The text protocol used on the port 2089 socket is a small XML language If you know nothing about XML don t worry you can figure all you need to know from the examples in this manual and from the library you use to parse the XML Here s a complete list of commands 2 2 Commands and Responses 2 PRINCIPLES AND TERMS custom delete disable enable install map new nop query reset set takeover unmap update zero Section 3 p Modifies the firmware on the GTH module This lets you put your own logo on the in built webserver for instance Remove a previously started job Disable a telecom interface E1 T1 or SDH SONET Enable a telecom interface E1 T1 or SDH SONET Install firmware on the GTH module s flash memory Extract an E1 T1 carried by SDH SONET Create a job There are jobs which perform signalling for instance atm_aal5_monitor and lapd_layer and jobs which manipulate au dio such as connection and player Normally jobs run until the delete command kills them or the port 2089 API socket is terminated with a bye command The no operation command Check the
48. cal application which does the same thing tkxmllint available from http tclxml sourceforge net tkxmllint html 120 7 CHANGELOG 7 Changelog The changelog shows changes made in the past few years since December 2012 e Daisy chaining is now supported on SDH resources This allows one fiber to be monitored by multiple sub modules without needing additional splitters It also allows intrusive monitoring i e monitoring without a splitter e LAPD monitoring can now handle 32 kbit s subrate channels e The recorder job has been experimentally extended to work with UDP sinks since March 2012 e The enable and disable commands are documented These commands are used in releases from 37a onwards to enable disable E1 T1 and SDH SONET interfaces e The raw_monitor feature is now documented for field testing on E1 T1 Monitor 2 1 e The instant in time when packets are timestamped has been moved from the start of each packet to the end This affects MTP 2 Frame Relay LAPD and raw monitoring e The API manual has been extended to cover the new SDH Monitor 3 0 since October 2011 e The query command now has an option for verbose queries Verbose queries return complete information about a job sufficient to allow serialisation of a GTH module s state e The board resource has a new attribute auto conferences e The API manual has been updated to cover the new E1 T1 Monitor 3 0 since January 2010 e The wide_reco
49. can decode multiple signalling protocols on the same input timeslots at the same time ATM AALO AAL2 and AAL5 can be run concurrently on the same timeslots The remaining protocols are mutually exclusive Signalling Socket Multiplexing Multiple signalling jobs can share one socket to the controller by all indicating the same IP address and port number to the socket Different channels are 11 2 7 Handling Errors 2 PRINCIPLES AND TERMS distinguished by the tag value supplied by the controller in the new command Signalling Socket Auto reconnect If the controller closes the signalling socket the GTH will first send an XML 12_socket_alert event and then after a few seconds attempt to reconnect the socket In most cases such a remote close will result in dropped signal units The reconnect attempts continue periodically Signalling counters Each signalling monitor has three load meters current_load average_load and maximum_load The current load is computed over a period of 1s Mi Mi 1s current_load t 100 x where M is the number of octets contained in correct signalling packets and B is the nominal channel bandwidth in octets per second Typical values for B are 8000 for a 64kbit s MTP 2 link 7000 for a 56kbit s ANSI MTP 2 link 2000 for a 16kbit s subrate LAPD link and 240000 for ATM over E1 links The average load is updated once every 30 seconds by default Mi Mi 30s average_load t 100 x 30x B
50. ch SONET resource broadcasts an event when its state changes lt lt event gt lt sdh_message name sdhi state OK LOF AIS L RDI L gt lt event gt 4 5 2 HOP resources An SONET link can carry many independent streams of signalling and data These streams are organised into a multiplexing structure The HOP resources represent the counters at the STS 1 level Each of this resources is named named sdhE hopF where E and F are integers and the colon separates path components HOP naming example On an OC 3 link there are three possible STS 1s to choose between The resource sdh1 hop1 represents the first STS 1 in the link connected to the first SFP slot on the GTH module Each HOP resource can be queried to see its state and counters 102 4 5 SONET Links 4 RESOURCES Attribute Notes status The current state at the HOP level OK AIS P LOP P LOM PLM P RDI P and UNEQ P signal_label The path signal label payload type trace_identifier The name given to the HOP by the remote equipment entered The number of times the state was entered There are four of these counters one for each state duration The number of milliseconds the link has been in the state in total There are four of these counters B3 STS Path Error Monitoring counter REI P STS Path Remote Error Indication counter child The name of a child resource There are always multiple chil dren at this level Section 3 30 show
51. cit conference is also created if a recorded message i e a player is currently playing to the same sink as a connection the subscriber will hear the linear sum of the player and the connection O O N e Ordinary telephone call Intercepted telephone call each arrow represents a connection the interceptor is listen only Figure 1 Two examples of call switching Error reasons refused The GTH has used up all available switching capacity 44 3 15 new connection 3 COMMANDS See also The voice coding attribute of the board resource see 4 9 can be set to either alaw or mulaw voice coding Conferences will have very bad audio quality if the GTH s coding is different to the coding used in the telephone network The auto conferences attribute of the board resource see 4 9 can be set to disable conferences Example Creating a half call gt lt new gt lt connection gt lt pcm_source span 2A timeslot 16 gt lt pcm_sink span 3A timeslot 1 gt lt connection gt lt new gt lt lt job id cnxn15 gt It s called a half call because the connection is unidirectional i e the subscriber at span 3 timeslot 1 can hear the subscriber at span 2 timeslot 16 but not vice versa A normal telephone call consists of two half calls Example Breaking a half call gt lt delete id cnxn15 gt lt ok gt Example Creating a 3 party conference call gt lt n
52. consistent with the number of received octets CG CPCS congestion indicator Set if CPCS re assembly failed after packets were dropped due to congestion AB CPCS abort indicator Set if the CPCS re assembly failed due to a remote abort CR CPCS CRC error indicator Set if the CPCS PDU is corrupt Ver The header version currently 0x0 Timestamp A 48 bit wide field indicating the instant the packet arrived in number of milliseconds since the 1970 Unix epoch This value is nondecreasing GFC VPI VCI PTC are all members of the ATM cell header CPCS UU CPI CPCS Length and CPCS CRC are the CPCS trailer field as described in ITU T 1 3863 5 Link status information An ATM link running normally is in link state sync The other possible state hunt indicates that the link is not working Whenever the link switches from one to the other GTH sends an event lt lt event gt lt atm_message id string value hunt sync gt lt event gt The GTH issues an event whenever the average_load exceeds the limit lt lt event gt lt l2_alarm id string attribute string state string value string gt lt event gt If link_load_alarm is yes then GTH also issues load alarms for the average_link_load The GTH also issues an event whenever the TCP socket carrying the signalling data is congested buffer more than half full overruns or is closed remotely lt lt event gt lt l2_socket_alert reason buffer_limit
53. contain firewalls or NAT devices which discard idle TCP connections If the firewall terminates a TCP connection carrying the API the GTH will respond by terminating all jobs e g signalling decoding started on that API connection The GTH has a heartbeat feature 5 4 which can be used avoid this problem Performance Reasoning about TCP performance on a single subnet is straightforward there is no ethernet packet loss and round trip times are short In contrast a routed network may suffer from packet loss congestion and have long round trip times You need to be sure that the network s characteristics are good enough for your reliability requirements 107 4 8 CPU 4 RESOURCES 4 8 CPU The cpu resource has these attributes Attribute Possible values in query Allowed values in set load the unix load average read only total memory integer in octets read only free memory integer in octets read only load limit an integer an integer The load is the unix load average i e the mean number of runnable jobs in the run queue It is possible for this to exceed 1 0 Events If the CPU load exceeds the limit the GTH sends an event to all API sockets lt lt event gt lt alarm name cpu attribute load state set clear value string gt lt event gt 4 9 Board The rest of the attributes which affect a whole module are grouped in the board resource Attribute Possible values in quer
54. corelatus CONTENTS CONTENTS Corelatus GTH API December 2013 Part number 10 0003 The latest version is available at http Awww corelatus com gth api Contents 1 Introduction 1 1 1 2 1 3 1 4 io Hardware Models og o thw SEER EWES EE eaa Typical Application A Voicemail System Typical Application Signalling Analysis Typical Application Voice Quality Measurement Sample Code and Blog Examples 50004 Principles and Terms 2 1 Be 2 3 2 4 2 5 2 6 2d Sending Commands to the GTH aoaaa aaa a Commands and Responses aooo a Data on the API Socket 224 ck aks eonig ea EGA Se E R G Signalling se o esga ES RRA Se ERE EEK ES Handing EMOS Gxt eee eh ie ke bee a eh eae eS Commands 3 1 3 2 3 3 3 4 3 5 3 6 3 7 3 8 3 9 CUSTODI Aa a fac o onc ew ck Re oe ee a eee Oe a KG cee acy ER ee es dlate cok wd aoe d wA Geek Ge De BS Yee od oe 2a eS CISAUIG erie mn A A A BR See eg A A ne A aaa np A D oN O OD CONTENTS CONTENTS 3 10 newatm_aal2_monitor 2 a eee ee es 32 3 11 newatmn_aal5 Monitor 2665 5 eee a eo we ee ee Ps 35 3 12 newcas_r2_linesig monitor 0 5000 39 3 13 newcas r2_mfc_detector a ee eee 41 le WONG or bee CRG whe eA e de ae eS EEA Ae he a 43 3 15 new connection ct eee RE RE EER EER ee RR RE 44 SIS NOW NYE 2 oe hee eberw ds heed Be bh 444 SAAS 47 3 17 new fr_mo
55. ct failure no such job not yet im plemented parse refused transport gt human readable text lt error gt The reason is intended to be machine readable The human readable text is not documented it is intended to help humans debug problems for instance by appearing in an application s log file 3 COMMANDS Reason Description bad argument busy conflict failure no such job not yet implemented parse refused transport One of the attributes in the command had an invalid value The command attempted to start an action which was already in progress The command attempted to configure the GTH in a way which conflicts with the GTH s current configuration The GTH had an internal problem If you see this report it to Corelatus preferably with log files The command included a job_id but the job_id does not correspond to any currently running job The command attempted to use a feature which is not implemented in the currently installed firmware release The command could not be parsed a syntax error The command could not be executed due to a constraint on the GTH for example a capacity limit The content type content length headers preceding the com mand were invalid The bad argument parse and transport errors can occur for all commands The remaining errors are specifically noted in each command s description Machine Readable Protocol Defin
56. d TCP connection with a 12 octet big endian header 54 3 19 new lapd_monitor 3 COMMANDS Bt 15 14 713 12 11 10 9 8 7 6 5 4 3 2 if 0 octet 0x00 Length octet 0x02 Tag tag ss octet 0x06 octet 0x08 Timestamp octet 0x0a length indicates the number of octets following the length field including the rest of the header and the CRC tag specified by the user It identifies the channel protocol indicates which protocol is being monitored 0 MTP2 1 LAPD 2 Frame Relay FS 1 Frame too short FL 1 Frame too long NA 1 Non octet aligned frame not a multiple of 8 bits AF 1 Aborted frame frame was terminated by an abort signal CR 1 Invalid CRC timestamp Timestamp marks the instant of time the packet ended measured in milliseconds since the Unix epoch It is a monotonically increasing integer 55 3 19 new lapd_monitor 3 COMMANDS Counters and Indicators Category Members Packet counters n_su i_ frames s_ frames u_frames n_esu Octet counters su_0 eSU_O Load meters current average and maximum load State current state n_up t_up n_down t_down Link status information Description The number of correct signal units which have arrived on the interface The number of correct signal units broken down into types The number of errored signal units which is de fined as all packets which are too short too long non octet aligned or have
57. d and when its response is sent Events concerning resources are broadcast to all controllers alarm A resource has exceeded a limit e g the temperature is outside the range 10 60 Celsius 10 70 on SDH Monitor 3 0 alert An external system has failed in such a way that may cause problems for the GTH for instance one of the two power inputs is no longer supplying power info An informative message for instance an indication of progress during firmware upgrade ll_message The Layer 1 state of an E1 T1 resource has changed 12_socket_alert A TCP socket carrying L2 signalling to a controller has encountered a problem sdh_message The state of an SDH SONET resource has changed sfp_message_ The state of an SFP resource has changed slip An E1 T1 resource has slipped sync_message The E1 T1 sync subsystem has changed state Events concerning jobs are only sent to the command socket which started the job the owner 2 5 Voice 2 PRINCIPLES AND TERMS atm_message AnATMchannel changed state backup One or more jobs have been automatically transferred to this command socket fatality A job died f_relay_message A frame relay channel changed state 12_alarm A layer 2 signalling job has altered its alarm state lapd_message AnLAPD timeslot changed state level A voice level detector has tripped message_ended A voice prompt has completed mtp2_message An MTP 2 timeslot changed state tone A DTMF tone was detected A s
58. default the names used in the SDH standard are used If SONET is true names corresponding to the SONET standard are used instead daisy chain controls whether or not the incoming data on this SDH resource is re transmitted Daisy chaining occurs cross wise i e enabling daisy _chain on sdh1 means that the data received by sdh1 is re transmitted on sdh2 The read only attributes are 101 4 5 SONET Links 4 RESOURCES Attribute Notes status The current state OK LOF AIS L Or RDI L OK is the normal operating state LOF Loss of Framing indicates that framing cannot be recov ered typically because there is no incoming signal AIS L Line Alarm Indication Signal means that there is an incoming signal but that the link is not in service RDI L Line Remote Defect Indication means that there is an incoming signal but that the remote system has detected a problem trace_identifier The name given to the link by the remote equipment _entered The number of times the state was entered There are four of these counters one for each state duration The number of milliseconds the link has been in the state in total There are four of these counters B1 The B1 counter Regenerator Section Error Monitoring B2 The B2 counter Line Error Monitoring REI L The REI L counter Line Remote Error Indication child The name of an STS 1 child An OC 12 always carries 12 such children An OC 3 always carries three Ea
59. e player command see 3 22 plays a clip on a timeslot Example Defining a clip gt lt new gt lt clip id dtmf9 gt lt new gt Content type binary audio Content length 120 the audio data lt lt job id clip dtmf9 gt A player is used to play the audio on a timeslot player copies the clip byte by byte without any modifying it and without removing any header e g wav header which might be present So the audio data you provide to a GTH should not have a header and should be 8000 samples per second mono A law or mu law 43 3 15 new connection 3 COMMANDS 3 15 new connection gt lt new gt lt connection gt lt pcm_source span string timeslot int first_bit 0 bandwidth 64 gt lt pcm_sink span string timeslot int bandwidth 64 gt lt connection gt lt new gt lt lt job id string gt A connection is used for switching A connection establishes a simplex stream of data from one source to one sink An ordinary telephone call is made by creating two simplex connections An N part conference call is made by setting up multiple connections to the same sink one from each source which that sink should hear The subscriber will then hear the linear sum of all the sources If necessary the sum will be clipped Calls can also be intercepted without interruption by creating one or more additional connections from the source or sources to an intercepting sink An impli
60. ed in the most recently created mtp2_monitor average_period the length of time in seconds over which average load is computed The load limit alarm uses the average load as its trigger source The 59 3 21 new mtp2_monitor 3 COMMANDS maximum allowed value is 900 seconds tag a user specified integer in the range 0 65535 esnf Enables the extended sequence number format often used on 2Mbit s ITU T Q 703 annex A links Monitoring Socket Protocol The signal units extracted from a link using an mtp2_monitor are forwarded to the external host given by the ip_addr over a TCP socket separate to the socket used for API commands The GTH expects the external host to be listening on this socket before the new command is issued Each signal unit is delivered on a dedicated TCP connection with a 12 octet big endian header Bit 15 14 13 12 11 10 9 8 7 6 5 4 3 2 if o octet 0x00 Length octet 0x02 Tag ee ee ee ead octet 0x06 octet 0x08 Timestamp octet 0x0a length indicates the number of octets following the length field including the rest of the header and the CRC tag specified by the user It identifies the channel protocol indicates which protocol is being monitored 0 MTP2 1 LAPD 2 Frame Relay FS 1 Frame too short FL 1 Frame too long NA 1 Non octet aligned frame not a multiple of 8 bits AF 1 Aborted frame frame was terminated by an abort signal CR 1 Inva
61. ends an event lt lt event gt lt f_relay_message id string value string gt lt event gt The GTH issues an event whenever the average_load exceeds the value specified in the load_limit lt lt event gt lt l2_alarm id string attribute string state string value string gt lt event gt The GTH also issues an event whenever the TCP socket carrying the signalling data is congested buffer more than half full overruns or is closed remotely lt lt event gt 49 3 17 new fr_monitor 3 COMMANDS lt l2_socket_alert reason buffer_limit buffer_overrun remote_close ip_addr int int int int ip_port int gt lt event gt Monitoring Socket Protocol The signal units extracted from a link using fr_monitor are forwarded to the external host given by the ip_addr over a TCP socket separate to the socket used for API commands The GTH expects the external host to be listening on this socket before the new command is issued Each signal unit is delivered on a dedicated TCP connection with a 12 octet big endian header Bit 15 14 13 12 11 f 10 9 8 7 et 5 4 3 2 ito octet 0x00 Length octet 0x02 Tag tag ss octet 0x06 octet 0x08 Timestamp octet 0x0a length indicates the number of octets following the length field including the rest of the header and the CRC tag specified by the user It identifies the channel protocol indicates which protocol is being monitored 0 MTP2
62. ent incompatible protocol on the given input timeslots Standards ITU T Q 440 and ITU T Q 441 Table 5 Example Monitoring CAS R2 MFC register signalling lt new gt lt cas_r2_mfc_detector direction forward tag 1234 ip_addr 172 16 2 1 ip_port 1234 gt lt pcm_source span 2A timeslot 3 gt lt cas_r2_mfc_detector gt lt new gt lt lt job id cmfm17 gt 42 3 14 new clip 3 COMMANDS 3 14 newclip gt lt new gt lt clip id string gt lt new gt lt lt job id string gt A clip represents a short sequence of sampled audio stored on the GTH It could be a tone e g a dial tone or some voice for instance a greeting for a mailbox id a string of the controllers choosing The job ID returned by the GTH will be that string with a clip prefix The GTH expects a block of audio immediately following the end of the XML command The block must have content type binary audio and it may be up to 500000 octets 60 seconds of audio long In a system which uses large clips sending a clip to the GTH may tie up the Ethernet interface for a few hundred milliseconds Applications can avoid delaying other commands by using a second API socket for the timing critical operations Error reasons refused The GTH does not have enough memory to store this clip either because there are too many clips on the GTH or because the total length of all the clips on the GTH is too large See also Th
63. er ITU T G 772 Enabling monitoring increases the signal sensitivity by 20dB and also disables transmit status shows the link s current state which is either OK or one of several error states LOS Loss of signal The incoming line doesn t have a signal at all or a signal too weak to detect In North America LOS LFA and LMFA are often called a red alarm This state does not exist on SDH Monitor 3 0 LFA Loss of frame alignment There is a signal on the line but E1 or T1 framing cannot be recovered LMFA Loss of multiframe alignment There is a signal on the line framing can be recovered but not multiframe framing Als Alarm indication signal The E1 receiver in the GTH has detected a fault on the signal it is receiving too many 1 bits in a frame This is often called a blue alarm in North America RAI Remote alarm indication The equipment at the other end of the link is signalling that it is not in the OK state This is often called a yellow alarm in North America The enable command turns an E1 T1 link on with default values for all attributes which aren t specified in the command Section 3 32 has an example of how to 95 4 3 SFP Modules 4 RESOURCES enable an interface in T1 mode and E1 mode tx_enabled When set to false transmit is disabled for that E1 T1 On hardware which shares pins for transmit and receive attempting to enable all four E1 T1 receivers in one RJ45 connector without setting tx_enabled to false
64. er id play5 owner apic7 octets_played 148992 gt lt state gt Example Querying two players and a nonexistant resource bogus is not an actual resource The response to the query contains answers to all three items queried in the same order as queried gt lt query gt lt job id play3 gt lt resource name bogus gt lt job id playl gt lt query gt lt state gt lt player id play3 owner apic27 octets_played 246784 gt lt error reason bad argument gt no such resource lt error gt lt player id playl owner apic27 octets_played 1267712 gt lt state gt Example A verbose query Adding verbose true provides complete information about the job including everything needed to start an identical job lt query verbose true gt lt job id play4 gt lt query gt lt lt state gt lt player id play2 owner apicl loop true gt lt clip id clip leave_message_after_tone gt lt pcem_sink span 1A timeslot 1 gt lt attribute name octets_played value 192768 gt lt player gt lt state gt Verbose queries are intended for debugging They could also be used in migrating jobs from one system to another in a warm standby setup If you re writing a parser for GTH responses you might want to skip verbose queries the return values the generate are much more complex than anything else the GTH genera
65. est supervision by the GTH The GTH implicitly creates a job with the ID apicXXX whenever a port 2089 API connection is started Configure this implicit job using update Look up its ID by querying the special job self One of the controller job s attributes is the timeout which controls supervision If the timeout in milliseconds is nonzero then the GTH starts a timer after each command is received If the timer expires before the next XML command arrives the socket is closed an error logged and all jobs started on owned by that socket deleted i e the GTH falls back to a known state gt lt update gt lt controller timeout 10000 gt lt update gt 116 5 5 Duplicating Ethernet 5 FAULT TOLERANT SYSTEMS lt lt ok gt 8s elapses lt nop gt lt ok gt ft 4 10s elapses lt lt error reason timeout gt 5 5 Duplicating Ethernet GTH hardware has two ethernet interfaces so it is possible to build systems with completely duplicated IP networks two switches two ethernet interfaces on the controller and two ethernet interfaces on the GTH The only restriction the GTH imposes is that its ethernet interfaces must be on separate subnets this is a general restriction in Linux and other operating systems Some ways to use duplicated IP networks are e Duplicated network with cold failover The controller normally uses one of the two networks If that network fails typica
66. ew gt lt connection gt lt pcm_source span 1A timeslot 1 gt lt pcm_sink span 2A timeslot 1 gt lt connection gt lt new gt lt lt job id cnxn16 gt lt new gt lt connection gt lt pcm_source span 1A timeslot 1 gt lt pcm_sink span 3A timeslot 1 gt lt connection gt lt new gt lt lt job id cnxn17 gt lt new gt lt connection gt lt pcm_source span 2A timeslot 1 gt lt pcm_sink span 1A timeslot 1 gt lt connection gt lt new gt lt lt job id cnxn18 gt lt new gt lt connection gt lt pcm_source span 2A timeslot 1 gt lt pcm_sink span 3A timeslot 1 gt lt connection gt lt new gt job id cnxn19 gt tt A gt lt new gt lt connection gt lt pcm_source span 3A timeslot 1 gt lt pcm_sink span 2A timeslot 1 gt lt connection gt lt new gt 45 3 15 new connection 3 COMMANDS lt lt job id cnxn20 gt lt new gt lt connection gt lt pcm_source span 3A timeslot 1 gt lt pcm_sink span 1A timeslot 1 gt lt connection gt lt new gt lt lt job id cnxn21 gt 46 3 16 new fr_layer 3 COMMANDS 3 16 new fr_layer gt lt new gt lt fr_layer ip_addr int int int int ip_port int gt lt pcm_source span string timeslot int first_bit 0 bandwidth 64 gt lt pem_sink spansstring timeslot int bandwidth 64 gt lt tr_layer gt lt new gt lt lt job id string gt The fr_layer is uns
67. failsafe During everyday operation the system image is used it supports the full set of GTH commands In exceptional circumstances for instance while upgrading the failsafe image is used The failsafe image provides just enough functionality to support upgrading and troubleshooting The only commands it understands are bye install nop query reset and set 110 4 12 Start Script 4 RESOURCES If the GTH fails to boot after five attempts it switches boot images e g to failsafe and tries five more times Each firmware image has a set of attributes Attribute Possible values in query Allowed values in set locked true false as for query version string read only busy true false read only An empty image has the special version string empty cannot be locked and cannot be busy A locked image must be unlocked before it can be overwritten There are three circumstances under which the failsafe image may be booted 1 The system image is damaged for instance as a result of a failed upgrade 2 The GTH has attempted more than 5 consecutive boots without successfully booting Successfully booting is defined as completing the boot process starting the API and staying up for four minutes 3 The boot mode has been manually set to failsafe before the most recent boot 4 12 Start Script At boot time the GTH runs a start_script consisting of a sequence of custom commands separated by blank lines By default t
68. for extracting signalling information carried on optical fiber E1 T1 Monitor 2 1 has two 10 100Mbit s ethernet interfaces the two leftmost RJ45 ports and 16 E1 T1 receivers or 8 E1 T1 transceivers The chassis above has three modules in one chassis 1 2 Typical Application A Voicemail System Using the command interface on a GTH you can build a scalable voicemail system suitable for connecting to E1 or T1 lines The GTH handles 1 3 Typical Application Signalling Analysis 1 INTRODUCTION e Recording timeslots for later playback for instance as the message left in a mailbox e Switching timeslots among the GTH s E1 T1 interfaces for instance when a call needs to be forwarded to an operator e Playing pre recorded messages on timeslots e Detecting and generating DTMF signalling e Terminating ISDN LAPD signalling for setting up calls 1 3 Typical Application Signalling Analysis GTH is well suited for building permanently installed signalling analysis systems for a networks consisting of SDH SONET optical links which carry many E1 or T1 lines and electrical E1 T1 links An E1 T1 Monitor 2 1 can connect to a G 772 monitor point to sniff and decode SS7 MTP2 ATM LAPD Frame Relay and CAS signalling An SDH Monitor 3 0 can be connected to an optical splitter to perform the same function on a fiber The decoded signalling is then sent over Ethernet to an external system for analysis or logging 1 4 Typical Applica
69. gt lt tcp_source ip_addr 128 250 22 3 ip_port 1234 gt lt pem_sink span 1A timeslot 9 gt lt player gt lt new gt lt lt error reason bad argument gt cannot connect to given socket lt error gt Example Error condition attempting to play from a non listening port In this example the server at 172 16 2 1 has not established a listening socket on port 1234 lt new gt lt player gt lt tcp_source ip_addr 172 16 2 1 ip _port 1234 gt lt pem_sink span 1A timeslot 9 gt lt player gt lt new gt lt lt job id strp33 gt lt lt event gt lt fatality id strp33 reason cannot connect to given socket gt lt event gt 67 3 23 new raw_monitor 3 COMMANDS 3 23 new raw_monitor gt lt new gt lt raw_monitor id string ip_addr int int int int ip_port 0 tag 0 gt lt pcm_source span string timeslot int first_bit 0 bandwidth 64 gt lt raw_monitor gt lt new gt lt lt job id string gt A raw monitor extracts a bit exact copy of the data on a 64kbit s timeslot and forwards it to a server over TCP The data is sent in fixed length packets with the same header as other signalling monitoring Bt 5 14 13 2 iio 9 Bf 7 6 5 4 3 2 1 0 octet 0x00 Length octet 0x02 Tag octet 0x04 protocol 7 protocols 4 octet 0x06 octet 0x08 Timestamp octet 0x0a length indicates the number of octets following the length
70. he controller s operating system and configuration but 8 16 seconds is typical If the buffers underrun the GTH sends an event lt lt event gt lt fatality id strp3 reason underrun gt lt event gt The opposite to underrun overrun can never happen with a player since TCP flow control will block the sending socket See also The voice coding attribute of the board resource see 4 9 can be set to either alaw or mulaw voice coding This setting affects conferences If the network uses alaw 65 3 22 new player 3 COMMANDS but the GTH is configured for mulaw or vice versa conferences will sound so bad that it s almost impossible to hear what the participants are saying A player does not do any alaw mulaw conversion The auto conferences attribute of the board resource see 4 9 can be set to disable conferences Example Playing a TCP stream on an E1 T1 Timeslot gt lt new gt lt player gt lt tcp_source ip_addr 172 16 2 1 ip_port 2222 gt lt pcem_sink span 3A timeslot 1 gt lt player gt lt new gt lt lt job id strp9 gt Almost every application which uses recorded audio can use this type of TCP streaming to feed out the data on an E1 T1 timeslot A voicemail system can use it to play back recorded messages An IVR system can use it to play voice prompts On hold music can be streamed for indefinite periods A simple on hold music system could be implemented like this on
71. he custom command section 3 2 and section 4 11 Error reasons refused The name was not one of the names in the table above refused The firmware image was the one currently being executed the system image can only be upgraded while the system is running the failsafe image 24 3 6 install 3 COMMANDS busy Another install command is currently executing failure The release could not be installed The on board log files provide more information about why One reason is that the release file is corrupt Another is that the release file is intended for a different hardware generation Example Checking which image is running gt lt query gt lt resource name system_image gt lt query gt lt state gt lt resource name system_image gt lt attribute name version value gth2_system_37a gt lt attribute name locked value false gt lt attribute name busy value true gt lt resource gt lt state gt Example Booting the failsafe image gt lt set name os gt lt attribute name boot mode value failsafe gt lt set gt lt ok gt gt lt reset gt lt resource name cpu gt lt reset gt lt lt ok gt Example Installing new system firmware Once the GTH has booted in failsafe unlock the firmware we want to change and then send the new firmware lt set name system_image gt lt attribute name locked value false gt lt
72. he signalling data is congested buffer more than half full overruns or is closed remotely lt lt event gt lt l2_socket_alert reason buffer_limit buffer_overrun remote_close ip_addr int int int int ip_port int gt lt event gt Error reasons refused The GTH is already decoding signalling at maximum capacity refused The GTH already has the maximum number of signalling sockets open conflict The GTH is already decoding a different incompatible protocol on the given input timeslots Standards ITU T 1 432 3 1 432 1 ANSI T1 111 1 section 2 2 3A Example Monitoring a standard 1920kbit s ATM AALO channel gt lt new gt lt atm_aal0O_monitor ip_addr 172 16 2 1 ip_port 1234 tag 98 gt lt pcm_source span 2A timeslot 1 gt 29 3 8 new atm_aal0_monitor 3 COMMANDS lt pcm_source span 2A timeslot 15 gt lt pcem_source span 2A timeslot 17 gt lt pcm_source span 2A timeslot 31 gt lt atm_aal0_monitor gt lt new gt lt lt job id at0m72 gt Example Examining the AALO counters lt query gt lt job id at0m72 gt lt query gt lt lt state gt lt atm_aal0_monitor id at0m72 owner apic18 gt lt attribute name span value 1A gt lt attribute name timeslot value 3 gt lt attribute name n_cell value 41631 gt lt attribute name
73. he start script is empty The custom command 3 2 describes the format and contents of the start script The install command 3 6 writes a start script to the firmware A query command on the start_script shows the contents of the start script 4 13 Control System and Operating System Logs The GTH divides event and fault information into two logs application_log and system_log These logs can be inspected using a query on the respective resource which will cause the log as ASCII text to be returned in a text plain block immediately following the query response The verbosity attribute controls the level of logging in the application log Starting with the greatest amount of logging the available levels are 111 4 14 HTTP Server 4 RESOURCES Log level Information logged all All logging enabled All XML commands are logged All XML responses are logged All XML events are logged Internal system status messages are logged In applications which send many XML commands per second logging all of the above will significantly reduce GTH perfor mance and wrap logs quickly changes XMLcommands apart from nop and query are logged Internal system status messages are logged This setting is the default info As for changes except all successful commands are sup pressed The info setting provides the best performance at the expense of leaving less debugging information The resources standby_application_log and s
74. her player is already playing audio to the sink the subscriber will hear the linear sum of the two audio sources If a player is currently playing to the same sink as a connection the subscriber will hear the linear sum of the player and the connection Error handling Things can go wrong with players both during initial startup and while the player is running If the error is detected early the GTH returns an error response If the error is detected after a job_id was returned the GTH indicates errors by sending a fatality The possible reason attributes in an error response are refused The GTH does not currently have enough capacity to start another player refused There are too many clips in the list of clips to be played in gth2_system_33a and later the limit is 500 clips The human readable text accompanying the error provides more information to help distinguish between the different causes for refused A player using clips for input cannot fail once it has started A player using a tcp_source can fail after starting When this happens the GTH sends a fatality lt event gt lt fatality id strpl reason cannot connect to given socket gt lt event gt Once a player has started the TCP socket must provide at least enough data to keep a timeslot filled i e 8000 Byte s The GTH provides about 2 seconds of buffering The TCP stack on the controller provides additional buffering the amount is dependent on t
75. ibed in 4 4 3 E1 links are carried in C 12 containers shown on the right side of the diagram above T1 links are carried in C 11 containers The map command makes an E1 T1 carried in one of those containers accessible to other commands 4 4 1 sdh1 and sdh2 sdh1 represents the SDH structure associated with s fp1 97 4 4 SDH Links 4 RESOURCES sdh2 and sfp2 are similarly associated The configurable attributes are Attribute Possible values STM AU 3 4 TU ii 2 SONET false selects SDH mode daisy_chain false true STM sets the STM level STM 1 means the optical link operates at 155Mbit s AU and TU select which of several possible paths through the SDH multiplexing structure are used SONET selects which names are used for attributes states counters and events By default the names used in the SDH standard are used If SONET is true names corresponding to the SONET standard are used instead see 4 5 daisy_chain controls whether or not the incoming data on this SDH resource is re transmitted Daisy chaining occurs cross wise i e enabling daisy_chain on sdh1 means that the data received by sdh1 is re transmitted on sdh2 The read only attributes are Attribute Notes status The current state OK RS LOF MS AIS or MS RDI OK is the normal operating state RS LOF Regenerator Section Loss of Framing indicates that framing cannot be recovered typically because there is no in coming signal
76. id m2mol7 gt Example Monitoring a 56kbit s ANSI MTP 2 timeslot gt lt new gt lt mtp2_monitor tag 1234 ip_addr 172 16 2 1 ip_port 1234 gt lt pcm_source span 15B timeslot 16 bandwidth 56 gt lt mtp2_monitor gt lt new gt lt job id m2mo18 gt 62 3 21 new mtp2_monitor 3 COMMANDS Example Monitoring a 1920kbit s HSSL MTP 2 timeslot gt lt new gt lt mtp2_monitor tag 1234 ip_addr 172 16 2 1 ip_port 1234 gt lt pcm_source span 8A timeslot 1 gt lt pcm_source span 8A timeslot 15 gt lt pcm_source span 8A timeslot 17 gt lt pcem_source span 8A timeslot 31 gt lt mtp2_monitor gt lt new gt lt job id m2mo0733 gt Example Finding out how many FISUs have been filtered lt query gt lt job id m2mo17 gt lt query gt lt lt state gt lt mtp2_monitor id m2mo590 owner apic89 gt lt attribute name span value 1A gt lt attribute name timeslot value 3 gt lt attribute name n_fisu value 571984 gt lt attribute name fisu_o value 2859920 gt lt attribute name n_lssu value 0 gt lt mtp2_monitor gt lt state gt 63 3 22 new player 3 COMMANDS 3 22 new player gt lt new gt lt player loop false gt lt clip id string gt lt pcm_sink span sstring timeslot int bandwidth 64 gt lt player gt lt new gt
77. ig endian header s peja een oeer 5 41 3 21 11 protocol 7 proloco octet 0x06 octet 0x08 Timestamp octet 0x0a octet Ox0c octet Ox0e Length the number of octets following the length field including the rest of the header Tag the tag value sent by the controller in the XML command Channel The telephone channel number as numbered in G 704 i e timeslots 1 15 17 31 are numbered 1 30 Bits The current a b c d bits CAS only uses the first two out of the four bits The c and d are normally fixed at 0 and 1 respectively 39 3 12 new cas_r2_linesig_monitor 3 COMMANDS Error reasons refused The GTH is already decoding signalling at maximum capacity refused The GTH already has the maximum number of signalling sockets open conflict The GTH is already decoding a different incompatible protocol on the given input timeslots Standards ITU T Q 421 ITU T G 704 Table 9 Example Extracting CAS line signalling gt lt new gt lt cas_r2_linesig_monitor tag 1234 ip_addr 172 16 2 1 ip_port 1234 gt lt pcem_source span 2A timeslot 16 gt lt cas_r2_linesig_monitor gt lt new gt lt job id clsm19 gt 40 3 13 newcas_r2_mfc_detector 3 COMMANDS 3 13 new cas r2_mfc_detector gt lt new gt lt cas_r2_mfc_detector tag 0 direction forward backward ip_addr int int int int ip_port int gt lt pcm_source span string timeslot int first_bit
78. imple policy to deal with events is to handle the expected ones and log the unexpected ones for manual attention 2 5 Voice The GTH s connection to the telephone network is via either E1 T1 interfaces or SDH SONET A timeslot leaving the GTH i e going to a subscriber is called a sink A timeslot entering the GTH is called a source GTH uses the new connection command section 3 15 to switch timeslots to connect a source to a sink This is the building block used to let subscribers talk to each other GTH can play pre recorded messages on a timeslot using new player section 3 22 and record a timeslot using new recorder section 3 24 You can make IVR and voicemail systems using these commands In both recording and playback the audio data is streamed to or from the controller over a separate TCP socket GTH can detect DTMF tones from a subscriber s handset using new tone_detector section 3 27 The DTMF tones could be a dialled number or they could be the user navigating in a menu system 2 6 Signalling GTH can monitor passively sniff all common layer 2 signalling protocols used on E1 T1 and SDH SONET links SS7 MTP 2 ATM AAL5 used in SS7 HSSL ATM AAL2 ATM AALO frame relay used on the GSM Gb interface ISDN LAPD and CAS Monitoring is useful if you want to keep track of what is happening in a 10 2 6 Signalling 2 PRINCIPLES AND TERMS network to create billing data to detect when mobiles enter and leave a ne
79. in gt lt pcem_sink span 3 timeslot 12 gt lt player gt lt new gt lt gth_in gt produces the following error message in the browser XML Parsing Error not well formed Location file home matthias bad xml Line Number 8 Column 36 lt pcm_sink span 3 timeslot 12 gt A Browsers only check for well formedness They verify whether or not a file is valid XML but they do not check that the file follows the GTH DTD 6 2 W3 Online Validator The W3 consortium has an online validator at http validator w3 org Validating the above example produces this error report Line 8 column 35 an attribute value literal can occur in an attribute specification list only after a VI delimiter lt pcm_sink span 3 timeslot 12 gt AN 119 6 3 xmllint 6 XML TOOLS The W3 validator checks using the GTH DTD so it will find more errors than a browser 6 3 xmllint xmllint is a freely available command line driven XML parser It produces error output similar to the W3 validator and it is straightforward to use in automated test systems gt xmllint valid play xml play xml 8 parser error Specification mandate value for attribute timeslot lt pcm_sink span 3 timeslot 12 gt AN xmllint is free Download it from http www xmlsoft org Many Linux distributions include it e g in Debian based distributions it s in libxml2 utils For Windows and Mac users there s a graphi
80. in the cell header 31 3 10 new atm_aal2_monitor 3 COMMANDS 3 10 new atm_aal2_monitor gt lt new gt lt atm_aal2_monitor vpi int vei int sdu yes corrupt_sdu no scrambling yes link_load_alarm no load_limit 50 buffer_limit 256000 average_period 30 tag 0 ip_addr int int int int ip_port int gt lt pcm_source span string timeslot int first_bit 0 bandwidth 64 gt lt atm_aal2_monitor gt lt new gt lt lt job id string gt An atm_aal2_monitor extracts packets from the interface above the ATM AAL2 layer on ATM over E1 links and forwards them to an external server over TCP The GTH supports starting multiple AAL2 monitors with different VPI VCl on the same set of timeslots AAL2 is used on some interfaces in UMTS 3G systems vpi vci These parameters specify which AAL2 channel is monitored sdu corrupt_sdu select whether normal packets SDUs and corrupt SDUs should be delivered scrambling ATM payload scrambling is on by default ITU 1 432 3 requires scrambling a4 1 to be enabled for E1 links and leaves it optional for T1 buffer_limit lf the socket carrying the signalling to the controller has a backlog greater than this limit the GTH issues an event average_period the time in seconds the average load is calculated over tag A user supplied value which is then sent in the header of each packet generated by this job Counters and Indicator
81. int int ip_ port int gt lt pcm_source span string timeslot int first_bit 0 bandwidth 64 gt lt ss5_linesig_monitor gt lt new gt lt lt job id string gt SPECIFIC FIRMWARE REQUIRED SS5 signalling monitoring requires a firmware upgrade which is available on request The firmware includes an API description for SS5 74 3 26 new ss5_registersig_monitor 3 COMMANDS 3 26 newss5 registersig_ monitor gt lt new gt lt ss5_registersig_monitor tag 0 ip_addr int int int int ip_port int gt lt pcm_source spansstring timeslot int first_bit 0 bandwidth 64 gt lt ss5_registersig_monitor gt lt new gt lt lt job id string gt SPECIFIC FIRMWARE REQUIRED SS5 signalling monitoring requires a firmware upgrade which is available on request The firmware includes an API description for SS5 75 3 27 new tone_detector 3 COMMANDS 3 27 new tone detector gt lt new gt lt tone_detector type DTMF custom frequency int length int gt lt pcm_source span string timeslot int first_bit 0 bandwidth 64 gt lt tone_detector gt lt new gt lt lt job id string gt A tone detector detects DTMF touch tone and other types of in band signalling on a timeslot type DTMF detects DTMF tones This is the default The frequency and length attributes should not be specified for DTMF type custom detects tones of user selectable frequency in Hertz useable range is 500
82. irtual Container VCI ATM Virtual Channel Identifier Part of the cell address VPI ATM Virtual Path Identifier Part of the cell address VT SONET Virtual Tributary XML Extensible Markup Language http www w3 org TR REC xml 124
83. ition The XML protocol s syntax is defined in a machine readable format by a pair of document type definitions DTDs one for commands to the GTH another for responses from the GTH The DTDs are available at http Awww corelatus com gth api A validating XML parser such as xmilint can use the DTDs to find syntax errors in your XML commands Section 6 shows how to do that 3 1 bye 3 COMMANDS 3 1 bye gt lt bye gt lt lt ok gt bye terminates an API connection gracefully When the GTH receives a bye the GTH deletes all jobs started by owned by the the API socket responds with ok and closes the socket If the controller closes the API socket without a bye the GTH performs the same steps as above but also logs an error See also takeover 3 33 can be used to prevent the GTH from automatically deleting jobs when an API connection is closed Example Terminating an API connection gracefully gt lt bye gt lt lt ok gt 3 2 custom 3 COMMANDS 3 2 custom lt custom name inventory board http_server os gt lt attribute name string value string gt lt custom gt lt lt ok gt At boot time the GTH runs a start script consisting of a sequence of custom commands separated by blank lines The start script is installed using the install command To test the custom commands they can also be issued one at a time in normal operation The GTH takes the same actio
84. ive frame_error code_violation crc_error state counters Normal range 0 none Comments A slip always causes data loss or corruption It is possi ble to build national PDH networks with sync so stable that they never have a slip Typical carrier class networks run for months without a slip A code violation almost always causes a bit error A code violation indicates that the incoming PCM signal followed a pattern which is not allowed by the config urable line coding The most common cause is line noise On E1 T1 Monitor 3 0 there is a related counter called code_violation_seconds In doubleframe mode the CRC is not present so this counter is always zero In mult iframe mode it indicates errors PCM L1 can be in one of a number of states LOS LFA LMFA RAI AIS and OK The GTH counts how long each PCM was in each state There should never be an L1 state change without an explanation Typical explanations are that PCM cabling was unplugged or a remote system was restarted Several of the events these counters detect have causal relations for instance in a multiframe system every code violation is expected to cause a CRC error 5 4 Heartbeat Supervision A controller can supervise a GTH as well as the network between the GTH and the controller by periodically sending a nop command If the GTH does not reply with ok within one second the controller can assume there is a fault A controller can also requ
85. iven job_id is this API connection Use bye to make an API connection terminate itself Example Deleting a job Normally the application running on the controller keeps track of which jobs it started with new and deletes them when they re no longer needed lt delete id cnxn182 gt lt ok gt Example Querying the schedule to find unwanted jobs In some special cases for instance recovering from a software error in the controller it may be necessary to ask the GTH for a list of jobs and then to kill unwanted ones gt lt query gt lt resource name schedule gt lt query gt lt state gt lt job id cnxn182 owner apicl6 gt lt job id m2mo4 owner apicl5 gt lt job id m2mo5 owner apicl5 gt lt job id m2mo6 owner apicl5 gt lt job id at5m16 owner apicl5 gt lt state gt lt delete id cnxn182 gt lt ok gt 20 3 4 disable 3 COMMANDS 3 4 disable lt disable name string gt lt lt ok gt Disable E1 T1 and SDH SONET interfaces When an SDH SONET interface is disabled any E1 T1 interfaces mapped from that interface are automatically removed The LED next to each telecom interface is dark once the interface is disabled All interfaces are disabled at startup Example Disable an E1 T1 interface gt lt disable name pcmlA gt lt ok gt Example Disable an SDH SONET interface gt lt disable name sdh2 gt lt ok gt 21
86. k status information MTP 2 monitors have five possible link states Whenever the monitored link changes states GTH sends an event to the monitoring job s owner lt lt event gt lt mtp2_message id string value in service out of service proc outage congested no signal units gt lt event gt 61 3 21 new mtp2_monitor 3 COMMANDS Load alarm events The GTH issues an event whenever the average_load exceeds the load _limit lt lt event gt lt l2_alarm id string attribute string state string value string gt lt event gt The GTH also issues an event whenever the TCP socket carrying the signalling data is congested buffer more than half full overruns or is closed remotely lt lt event gt lt l2_socket_alert reason buffer_limit buffer_overrun remote_close ip_addr int int int int ip_port int gt lt event gt Error reasons refused The GTH is already decoding signalling at maximum capacity refused The GTH already has the maximum number of signalling sockets open conflict The GTH is already decoding a different incompatible protocol on the given input timeslots Standards ITU T Q 703 ANSI T1 111 1 3 Example Monitoring an ordinary 64kbit s MTP 2 timeslot gt lt new gt lt mtp2_monitor tag 1234 ip_addr 172 16 2 1 ip_port 1234 gt lt pcm_source span 2A timeslot 16 gt lt mtp2_monitor gt lt new gt lt job
87. l name string gt lt lt ok gt install loads new software into the GTH s flash memory New releases are released several times per year with new features and bug fixes Releases are available to customers at http www corelatus com gth releases An install command is always followed by a block with the content to be installed The block s content type is Name Description Content type failsafe_image the failsafe firmware binary filesystem system_image the normal firmware binary filesystem logo the webserver logo binary file start_script a script run at boot time _ binary file The failsafe image can only be upgraded if the system is currently running the system image and vice versa install reports ok once the complete content has been received When installing firmware images the GTH also sends an event when all the actions associated with the firmware installation are complete lt lt event gt lt info reason string gt lt event gt The order of the ok and the event is not defined An installation script should wait until it has seen both install can also be used to customise a software image at install time The webserver logo password file and a startup script can be customised Name Description logo The logo displayed in the left margin on most of the web pages It is a PNG image file start_script A customisation file executed when the GTH starts Section 3 2 describes the syntax See also T
88. leshooting faulty MTP 2 links it is useful to disable the filter gt lt update gt lt mtp2_monitor id m2mo19 lssu yes gt lt update gt lt lt ok gt Example Setting a backups list on a controller This example configures the current API socket called a controller to time out after 20 seconds On timeout instead of deleting all jobs owned by the socket the jobs will be transferred to apic13 and apic15 gt lt update gt lt controller timeout 20 backups apicl3 apicl5 gt lt update gt lt ok gt 92 3 36 zero 3 COMMANDS 3 36 zero gt lt zero gt lt resource name string gt lt zero gt gt lt zero gt lt job id string gt lt zero gt lt lt ok gt Reset counters and timers on e SDH SONET resources sdh1 sdh1 hop1_1 sdh1 hop1_1 lop1_1 e E1 T1 L1 resources pcm1A pcm2A e Layer 2 monitors CAS MTP 2 LAPD frame relay and ATM Example Zeroing the layer 1 E1 T1 counters gt lt Zero gt lt resource name pcmlA gt lt zero gt lt lt ok gt Example Zeroing SDH SONET gt lt Zero gt lt resource name sdh2 gt lt zero gt lt ok gt This sets all the counters in sdh2 and all of its children i e sdh2 hop1_1 and so on to zero 93 4 RESOURCES 4 Resources Resources are parts of the GTH which always exist the ethernet interfaces the firmware the E1 T1 interfaces the SDH SONET interfaces and the
89. lid CRC timestamp Timestamp marks the instant of time the packet ended measured in milliseconds since the Unix epoch It is a monotonically increasing integer Counters and Indicators Use query to read counters and indicators 60 3 21 new mtp2_monitor 3 COMMANDS Category Members Description Packet counters n_fisu n_Issu n_msu n_esu n_rsu The number of packets of different MTP 2 types which have arrived on the interface n_esu is the number of errored packets which is defined as all packets which are too short too long non octet aligned or incorrect CRC n_rsu is the number of retransmitted MSUs When the FIB inverts all subsequent MSUs up to the first one with a FSN equal to the FSN at FIB inversion time are counted as retransmitted MSUs The total number of octets in the packet types above Octet counters fisu_o ISsu_o MSU_O ESU_O rsu_O Load meters current average and maximum load State current state see table below n_in service The number of times the link was in each state n_congested t_in service The number of milliseconds spent in each state t_congested The current state and the state counters can be used to infer part of the MTP 2 transmitter s internal state Packet received State entered LSSU SIB congested LSSU SIO or SIOS out of service LSSU SIPO processor outage FISU or MSU in service no valid packet for 1s no signal units Lin
90. lly detected with heartbeat supervision the controller restarts the system using the second network dropping all calls e Duplicated network with hot failover This is like cold failover except that the controller uses transfer to move jobs to the new port 2089 socket With this method it is possible to recover from an IP network failure without dropping calls e Duplicated network and replicated controllers This is discussed in the next section 5 6 Controller Replication and Failover The GTH allows multiple concurrent API socket connections This can be exploited to provide fault containment within an application but it also allows a system with several cooperating controllers to recover from a controller failure without dropping calls Imagine a system consisting of one GTH and two servers Each server opens an API socket to the GTH each with its own GTH supplied job ID for this example apicl and apic2 The first server is the live one it enables E1 T1 resources issues new connection and new player commands and processes DTMF tones The second controller is in standby i e it does nothing Both servers configured a 10s timeout and send nop commands at 5s intervals as a heartbeat What happens if the power supply for the first server spontaneously combusts In less than 10s the GTH will timeout on apic1 log an error and delete all the jobs started on apicl i e all the players will stop and the connections will be broken In
91. lt query gt lt query gt lt state gt lt resource name board gt ttribu lt a te name temperature value 32 4 gt lt attribute name power consumption value 6 8 gt lt resource gt lt state gt Example Finding out which resources a GTH has lt query gt lt resourc lt query gt lt lt state gt lt resource lt resource lt resource lt resource lt resource lt resource lt resource lt resource lt resource lt resource lt resource lt resource lt resource lt state gt name inventory gt name sync gt name cpu gt name board gt name o0s gt name system_image gt name failsafe_image gt name application_log gt name system_log gt name eth1 gt name eth2 gt name http_server gt name pcmlA gt name pcm1B gt 83 3 30 query 3 COMMANDS Example Reading the counters for an SDH SONET hierarchy gt lt query gt lt resource name sdh1 gt lt query gt lt lt state gt lt resource name sdh1 gt lt attribute name STM value 1 gt lt attribute name AU value 4 gt lt attribute name TU value 12 gt lt attribute name SONET value false gt lt attribute name status value 0K gt lt attribute name 0K_entered value 1 gt lt attribute name 0K_d
92. n as it would if the commands were in a start script though the effects only persist until the next reboot Each custom command affects a resource in exactly the same way as a set command except that resources and attributes are limited to Resource Possible Description Attribute Values inventory physical physical numbering uses the E1 T1_ inter pcm_numbering sequential face names pcm1A pcm1B pcm1C pcm1D pcm4D where the number corresponds to the RJ45 port and the letter to the position within that port sequential numbering uses the scheme pcm1 pcm2 pcms pcm4 pcmsd pcm16 board universal E1 T1 probe modules used in monitoring appli PCM LED sequential cations have four E1 T1 receivers in each RJ45 assignment connector but only two LEDs The default universal scheme maps PCM1A and PCM1C to the left LED and PCM1B and PCMI1D to the right LED The sequential scheme maps 1A and 1B to the left and 1C and 1D to the right http_ server All the attributes in the http server resource may be customised see section 4 14 os enabled remote login disabled os IP A space delimited list of IP addresses from which API whitelist addresses the API can be accessed 3 2 custom 3 COMMANDS See also install 8 6 loads a start script onto a GTH Example A start script gt lt custom name inventory gt lt attribute name pcm_numbering value sequential gt lt custom gt gt lt custom name http_
93. ng a different incompatible protocol on the given input timeslots Standards ITU T Q 921 Example Monitoring a 64kbit s LAPD timeslot gt lt new gt lt lapd_monitor ip_addr 172 16 2 1 ip_port 1234 tag 77 gt lt pcm_source span 2A timeslot 16 gt lt lapd_monitor gt lt new gt lt lt job id 1dmo81 gt Example Monitoring subrate LAPD timeslots Some GSM interfaces use 16kbit s or 32kbit s LAPD This pair of examples shows a 16kbit s channel on bits 4 and 5 in each octet and then a 32kbit s channel on bits 4 5 6 and 7 gt lt new gt lt lapd_monitor ip_addr 172 16 2 1 ip_port 1234 tag 77 gt lt pcm_source span 2A timeslot 16 first_bit 4 bandwidth 16 gt lt lapd_monitor gt lt new gt lt lt job id 1dmo82 gt gt lt new gt lt lapd_monitor ip_addr 172 16 2 1 ip_port 1234 tag 78 gt lt pcem_source span 2A timeslot 17 first_bit 4 bandwidth 32 gt lt lapd_monitor gt lt new gt lt lt job id ldmo83 gt 57 3 20 new level_detector 3 COMMANDS 3 20 new level_detector gt lt new gt lt level_detector threshold 10 type both low_to_high high_to_low period 100 gt lt pcm_source span string timeslot int first_bit 0 bandwidth 64 gt lt level_detector gt lt new gt lt lt job id string gt A level_detector requires an audio source Whenever it detects that the audio level
94. nitor aooaa a a a 48 3 18 new apd layer xos eoor a a a ee ee Re eee ee O 52 3 19 new lapd_monitor aaao a PEE SG DRE DEES 54 3 20 new level_detector o oo noaoo e a a 58 3 21 new mtp2_monitor aaa eke Oa a Be oS 59 ice NON player oor a iek BR ee Be a e Se AR a 64 329 NSW taw MONIO o o sa recura aa e RE we ee a ee Se es 68 3 24 new recorder aaa a a 70 3 25 new ss5_linesig_monitor 6655 046 ee bea a 74 3 26 new ss5_registersig_monitor a aaoo a 75 3 27 new tone detecto sa aa siras be bre eatas ra kanis 76 3 28 new wide_recorder nooo ooo a e a e e a 79 ae OD ae ea nk eta a e oe Eee aT eek aa ae ek a Se 81 S30 GUE Gaede beep bet Ge ee bebee hee bi beaga desde 82 mil EGE 5 4 enh eka wk Oe wea eae ed Ree ee ee OE aon a 4 87 See SOU aos ke he Re ee ed Ee ee a O ae aie 88 3 33 takeover oo sooo ae he Ge ee SO E KG ee ok oe 89 See WINGY 648 oe aw tee ee ee ee eh Pee ee de ioa 90 Oy WR eek a a Se ee Se Bee eee ee ee Se Be Se ete 91 S00 ZOO 2 2 eae 2 EWA ae bee ke ak ee PO Ga ee bea 93 4 Resources 94 4 1 Inventory and Schedule 2 2 000002 eee 94 Me Te INS 6k 24 hk gne eee a ee a ee a 94 45 SFP Modules 2 4 44 64448854 58444046 2482444844 96 AA SDH OI so oc eee os ee eee ae ee ee eee Sg re ae 97 CONTENTS CONTENTS 6 7 8 Acronyms and Initialisms 4 4 1 4 5 1 4 6 Sync sources 4 7 Ethernet Interfaces 4 11 System Image and Failsafe Image 4 12 Start Script 4 13 Control System and
95. nters and indicators 35 3 11 new atm_aal5 monitor 3 COMMANDS Category Members Description Packet counters n_sdu The number of valid SDUs n_cdu The number of corrupt SDUs n_oam The number of O amp M cells Octet counters sdu_o cdu_o Load meters current average The percentage of the nominal link capacity and maximum used by this particular VPI VCI combination load current average The percentage of the nominal link capacity and maximum used by all VPI VCI channels on this ATM link link load State current state either sync or hunt n_sync t_sync The number of times the sync state was en t_hunt tered and the number of milliseconds spent in the sync and hunt states respectively Monitoring Socket Protocol The signalling information extracted from a link using an atm_aal5_monitor is forwarded to a socket on a remote machine defined by ip_addr and ip_port This socket is independent of the controllers API socket The GTH expects the external host to be listening on this socket before the new command is issued Each AAL PDU is delivered with a 24 octet big endian header e octet 0x06 octet 0x08 Timestamp octet 0x0a octet Ox0e PTC GPI Length the number of octets following the length field including the rest of the header Tag the tag value sent by the controller in the XML command 36 3 11 new atm_aal5 monitor 3 COMMANDS IL CPCS Invalid Length Set if the length in the CPCS trailer is not
96. ntire E1 T1 to a remote system via UDP Deleting the recorder stops the recording To use a wide_recorder 1 Establish a UDP socket on the remote system for instance the controller 2 Issue the XML command to start a wide_ recorder 3 On the remote system read the audio data as it comes in When transmitting from an E1 line each UDP packet payload looks like this ate eT Aw ey 8 7 8 5 4 S21 11 OY octet 0x06 octet 0x08 Timestamp octet 0x0a octet Ox0c octet Ox0e octet 0x2a TS30 TS31 octet Ox2c Tag The user supplied value given in the XML command to start the wide_recorder LD set to 1 if the E1 T1 is disabled or in any of the LOS AIS LMFA or LFA states 0 in normal operation i e if the E1 T1 is in the OK or RAI state Sequence Number A 16 bit sequence number which increments by one for each packet 79 3 28 new wide_recorder 3 COMMANDS Timestamp Timestamp marks the instant of time the E1 T1 data in this packet started measured in milliseconds since the Unix epoch TSO TS1 The timeslot data on the E1 presented frame by frame A new UDP packet is sent every 32 frames i e 250 packets per second When transmitting from a T1 line there are fewer timeslots and so the packet looks like this instead Bt eT 9 8 7 8 5 41 31 21 11 octet 0x06 octet 0x08 Timestamp octet 0x0a octet Ox0c octet Ox0e ae O F The F bit in T1 Ethernet Interface Capacity Restriction
97. o do that is issue a reset command which is equivalent to cycling power The GTH completely resets on boot up there are only three things it remembers from before 1 IP address settings addresses masks and default gateway 2 Log files 3 The firmware images see section 4 11 A less brutal and less complete way to return to a known state is to close the port 2089 API socket from the controller by issuing a bye The GTH will automatically delete all jobs started using that socket Resources such as E1 T1 interfaces are not returned to their default state i e everything done via set enable and map is remembered Jobs started by other API sockets are not terminated either GTH Crashes If all of the GTH s power inputs lose power the GTH will use a small on board power store to write a log entry before shutting down When power is restored the GTH knows the reason for the most recent shutdown gt lt query gt lt resource name o0s gt lt query gt lt lt state gt lt resource name 0s gt lt attribute name last restart value Mon Feb 25 08 21 31 2008 gt lt attribute name restart cause value power failure gt lt resource gt lt state gt If the GTH crashes in response to some combination of XML commands that is a problem Corelatus will track down and fix for you by studying log files and Ethernet traces 2 7 Handling Errors 2 PRINCIPLES AND TERMS Semantic Problems
98. oad Unexpectedly high ethernet load can be a symptom of an underlying problem alarm eth2 load alert ntp Losing contact with an NTP server will cause the GTH s time to drift In signalling monitor ing applications this will complicate correlating timestamps from different GTHs alert power inputs In high reliability installations losing one power input indicates that either the site power supply has failed or the battery backup has failed A simple general policy for dealing with events is to automatically deal with expected events and report all other events to an operator for manual attention 5 3 E1 T1 Layer 1 Runtime Checks In all GTH applications a correctly functioning E1 T1 PDH network is crucial Once a system is running all E1 T1 resources should stay in the ox state If they leave the OK state GTH sends an 11_message to warn that calls and signalling are likely to be degraded or fail completely A second symptom of E1 T1 network problems is difficulty maintaining synchronisation The GTH reports changes in E1 T1 synchronisation status via the sync_message Per E1 T1 slip messages indicate lost data on that E1 T1 which will degrade speech and signalling For each E1 T1 interface these counters should be sampled at regular intervals e g once every 15 minutes and reported if they go outside the normal range 115 5 4 Heartbeat Supervision 5 FAULT TOLERANT SYSTEMS Counter slip_positive slip negat
99. order Path Payload Label Mismatch HP RDI SDH SONET state Higher order Path Remote Defect Indication HP REI SDH SONET state Higher order Path Remote Error Indication HP UNEQ SDH SONET state Higher order Path Unequipped HTTP Hyper Text Transfer Protocol Defined in RFC 2068 IVR Interactive Voice Response The automated systems you ring up and communicate with by pressing buttons on your phone 122 8 ACRONYMS AND INITIALISMS L1 Layer 1 e g an E1 T1 line L2 Layer 2 e g MTP 2 or IP or ATM LAPD The protocol described in ITU T Q 920 and Q 921 LFA Loss of frame alignment See section 4 2 LOP SDH SONET Lower Order Path LP PLM SDH SONET state Lower order Path Payload Label Mismatch LP RDI SDH SONET state Lower order Path Remote Defect Indication LP UNEQ SDH SONET state Lower order Path Unequipped LMFA Loss of multi frame alignment See section 4 2 LOF SDH SONET Loss of Framing LOS Loss of signal See section 4 2 LSSU Link status signal unit Part of MTP 2 MS AIS SDH Multiplex Section Alarm Indication Signal MS BIP SDH Multiplex Section Bit Interleaved Parity MS RDI SDH Multiplex Section Remote Defect Indication MSU MTP 2 Message Signal Unit MTP 2 Message Transfer Protocol layer 2 Described in ITU T Q 703 and ANSI T1 111 1 NTP Network Time Protocol A method for synchronising clocks over IP networks defined in RFC 1305 OC 3 Optical carrier rate 3 A 155Mbit s optical fiber OC 12 Optical carrie
100. r rate 12 A 622Mbit s optical fiber PCM Pulse Code Modulation used in 2Mbit s E1 and 1 5Mbit s T1 connections PLM P SDH SONET Payload Mismatch Path PLM V SDH SONET Payload Mismatch Virtual Tributary PoE Power over Ethernet RAI Remote Alarm Indication See section 4 2 RDI SDH SONET Remote Defect Indication RS BIP SDH Regenerator Section Bit Interleaved Parity RS LOF SDH Regenerator Section Loss Of Framing SDH Synchronous Digital Hierarchy 123 8 ACRONYMS AND INITIALISMS SDU ATM Service Data Unit SFP Small Form factor Pluggable A plug in transciever module used by SDH SONET capable hardware to connect to optical fiber links SONET Synchronous Optical Networking SPE SONET Synchronous Payload Envelope SS7 Signalling System 7 The signalling protocol used in telephone networks SSH Secure SHell A remote login protocol STM 1 Synchronous Transport Module level 1 An optical transmission standard which runs at 155Mbit s and can carry 63 E1 links or 84 T1 links STM 4 Synchronous Transport Module level 4 An optical transmission standard which runs at 622Mbit s STS SONET Synchronous Transport Signal T1 A 1 544Mbit s PCM link as described in ITU T G 703 TCP Transmission Control Protocol Defined in RFC793 TU SDH Tributary Unit TUG SDH Tributary Unit Group UNEQ SDH SONET Uneduipped UTC Coordinated Universal Time A method of defining absolute time It is almost identical to GMT VC SDH SONET V
101. r eth2 recovered gt lt event gt 4 10 OS The GTH operating system represented by os has a number of attributes Attribute Possible values in query Allowed values in set boot mode normal failsafe as for query remote login enabled disabled i API whitelist a list of IP addresses j uptime a time read only last restart a time read only restart type hard soft watchdog read only restart cause kernel reboot power failure unknown read only The GTH includes two complete installations of the operating system and application firmware The boot mode controls which of those two installations is booted In the normal boot mode the system image is used remote login enables or disables SSH on port 22 API whitelist is a list of IP addresses from which the GTH will accept connections on port 2089 IP addresses are represented as dotted quads and separated by spaces An empty list the default means all IP addresses are allowed Example lt set name os gt lt attribute name API whitelist value 128 250 22 3 172 16 2 1 gt lt set gt lt lt ok gt uptime is the number of seconds since the last reboot the wall clock time UTC of that reboot is given by ast restart restart type and restart cause indicate why the GTH restarted This is useful for forensics i e answering why did the system restart 4 11 System Image and Failsafe Image The two firmware images on the GTH are called system and
102. rder feature is now documented for field testing on E1 T1 Monitor 3 0 hardware e The locked attribute in the eth1 and eth2 resources has been moved to the http_server resource An alias is retained for backwards compatibility 121 8 ACRONYMS AND INITIALISMS 8 Acronyms and Initialisms AALO ATM Adaptation Layer Zero A stream of raw ATM cells AAL5 ATM Adaptation Layer Five Defined in ITU T 1 363 5 AIS Alarm Indication Signal Used in both E1 T1 and SDH SONET See 4 2 and 4 4 API Application Programming Interface ATM Asynchronous Transfer Mode A family of signalling protocols defined in a series of ITU standards including ITU T 1 361 AU SDH SONET Administrative Unit B8ZS Bipolar Eight Zero Substitution See section 4 2 CPCS ATM Common Part Convergence Sublayer An ATM AAL5 sublayer CRC Cyclic Redundancy Check A type of checksum DSP Digital Signal Processor DTD An XML Document Type Definition DTMF Dual Tone Multi Frequency touch tone in band signalling E1 A 2Mbit s PCM link as described in ITU T G 703 ESU Errored signal unit Part of MTP 2 LAPD and frame relay signalling FISU MTP 2 Fill in signal unit GbE Gigabit Ethernet GTH Generic Telecom Hardware A family of systems made by Corelatus to connect to the telephone network HDB3 High Density Bipolar 3 See section 4 2 HOP SDH SONET Higher Order Path HP AIS SDH SONET state Higher order Path Alarm Indication Signal HP PLM SDH SONET state Higher
103. s Use query to read counters and indicators 32 3 10 new atm_aal2_monitor 3 COMMANDS Category Members Description Packet counters n_sdu The number of valid SDUs n_cdu The number of corrupt SDUs n_oam The number of O amp M cells Octet counters sdu_o cdu_o Load meters current average The percentage of the nominal link capacity and maximum used by this VPI VCI combination load current average The percentage of the nominal link capacity and maximum used by all VPI VCI channels on this ATM link link load State current state either sync or hunt n_sync The number of times the sync state was en t_sync tered and the number of milliseconds spent in t_hunt the sync and hunt states respectively Monitoring Socket Protocol The signalling information extracted from a link using an atm_aal2_monitor is forwarded to a socket on a remote machine defined by ip_addr and ip_port This socket is independent of the controllers API socket The GTH expects the external host to be listening on this socket before the new command is issued Each AAL2 PDU is delivered with a 19 octet big endian header ate w e 8 71 6 5 41 3121 110 octet 0x06 octet 0x08 Timestamp octet 0x0a oaeo eooo CT oo o O e Ce En o ae d ea oteto 0 y eeo Pao E Length the number of octets following the length field including the rest of the header Tag the tag given in the new command CR CRC error in the AAL2 PDU
104. s an example of reading out a HOP resource s state and counters Each HOP resource broadcasts an event when its state changes lt lt event gt lt sdh_message name sdhli hop1 state 0K AIS P LOP P AIS P LOM PLM P RDI P UNEQ P gt lt event gt 4 5 3 LOP resources On SONET links used for carrying E1 T1 lines the GTH exposes another level of resources representing the VT1 5 VT2 These resources are named sdhJ hopK lopL_x where J K L and X are integers LOP naming example assuming an OC 3 the resource sdhi hop1 lop1_1 represents the first VT1 5 inside the first V7 group inside the first STS 1 LOP naming example assuming an OC 3 the resource sdh1 hop3 lop7_4 represents the last VT1 5 inside the last V7 group inside the last STS 1 The read only attributes are Attribute Notes status The current state at the LOP level OK AIS V LOP V PLM V RDI V and UNEQ V signal_label The VT signal label payload type trace_identifier The name given to the LOP by the remote equipment LP BIP The Lower Order Path Bit Interleaved Parity counter LP REI The Lower Order Path Remote Error Indication counter Section 3 30 shows an example of reading out a LOP resource s state and counters Whenever the LOP resource changes states it broadcasts an event lt lt event gt 103 4 6 Sync sources 4 RESOURCES lt sdh_message name sdhl hopl lop1_1i state OK AIS V LOP V PLM V
105. server gt lt attribute name pcm_overview value http www corelatus com gt lt attribute name pcm_zero_buttons value true gt lt custom gt gt lt custom name os gt lt attribute name API whitelist value 172 16 2 1 128 250 22 3 gt lt attribute name remote login value disabled gt lt custom gt This configuration script sets up the PCM numbering to sequential mode customises several attributes in the on board WWW server disables remote SSH logins and restricts API control to two IP addresses Example Altering PCM numbering with a custom command at runtime gt lt custom name inventory gt lt attribute name pcm_numbering value sequential gt lt custom gt lt ok gt Sending custom commands at runtime only has a temporary effect If you want them to be permanent put them in the start script 3 3 delete 3 COMMANDS 3 3 delete lt delete id string gt lt lt ok gt delete removes the given job The ID argument is the ID returned by new See also new Creates jobs which delete deletes query can show a list of all the jobs currently running bye terminates the API socket which in turn terminates all the jobs started on owned by this API socket Error reasons no such job the given job_id does not correspond to any currently running job The job either never existed or it terminated before the delete was executed refused the g
106. tandby_system_log provide access to the logs from the firmware image which is not running 4 14 HTTP Server The on board HTTP server represented by the http_server resource has these configurable attributes Attribute Possible Values Purpose enabled true false Enable disable the webserver locked true false Limit the webserver to read only opera tions passwords See below Alter the passwords used to access the in built webserver pcm_L1_zero_buttons false true If true buttons are shown on the WWW interface which can be used to reset the PCM L1 counters pcem_L2_zero_buttons false true If true buttons are shown on the WWW interface which can be used to reset the PCM L2 counters The ocked attribute is used to control configuration changes from the webserver If locked is true the web server cannot change the IP address and mask nor can it upgrade the firmware image The API is not affected by the locked attribute The locked attribute persists across system restarts The passwords attribute is a comma delimited sequence of username password pairs for example userl passwordl user2 password2 user3 password3 112 4 14 HTTP Server 4 RESOURCES The webserver uses HTTP 1 1 digest authentication RFC 2617 to avoid exposing passwords to ethernet sniffers Passwords are vulnerable to sniffing when they are loaded into the system via a set or custom command pcm_L1_zero_buttons and pcm_L1_zero_buttons can be
107. tes 86 3 31 reset 3 COMMANDS 3 31 reset gt lt reset gt lt resource name string gt lt reset gt lt lt ok gt The resource must be cpu This command reboots the GTH which takes about 40s 87 3 32 set 3 COMMANDS 3 32 set lt set namezsstring gt lt attribute name string value string gt lt set gt lt lt ok gt set configures resources The name value tuples attributes are the same as returned by query Section 4 lists the resources how they work and which attributes can be read and written Error reasons no such resource the named resource doesn t exist A query command on the inventory returns a list of valid resources on a GTH invalid attribute or attribute value the named resources exists but it either doesn t have one of the attributes being set or the attribute is being set to an impossible value Example Set the IP address on the second Ethernet interface gt lt set name eth2 gt lt attribute name IP4 address value 10 0 0 1 gt lt attribute name IP4 mask value 255 0 0 0 gt lt set gt Example Explicitly set an E1 T1 sync source on hardware with E1 T1 ports By default the GTH scans its ports lowest port number first until it finds an E1 T1 with valid sync If the sync source is lost e g the cable is unplugged the ports are scanned again In most monitoring applications the default sync behaviour is satisfactor
108. the GTH returns an error response If the error is detected after a job_id was returned the GTH indicates errors by sending a fatality The possible reason attributes in an error response are refused The GTH does not currently have enough capacity to start another recorder When a recorder fails after starting the GTH sends a fatality for instance lt lt event gt lt fatality id strr5 reason overrun gt lt event gt The recorder specific reasons fora fatality are overrun the buffers on the GTH and in the TCP socket filled up so the GTH terminated the job The GTH provides about two seconds of buffering the TCP stack on the remote system provides 8 16 seconds depending on OS and configuration An overrun is normally the result of the remote system falling behind in reading from the socket but can also be caused by a lossy or congested IP network between the GTH and the remote system This error cannot happen when UDP is used socket problem the socket was closed by the remote server cannot connect to given socket A lt new gt lt recorder gt command returns a job immediately The TCP socket carrying the timeslot data may complete the 71 3 24 new recorder 3 COMMANDS connection process after the job is returned If the TCP connection attempt fails after the job has already been issued the GTH sends a fatality with the reason cannot connect to given socket This error cannot happen when UDP is
109. time is a simple way to catch misconfigurations A typical set of attributes to check would include all of the following Resource Attribute Why system_image version Avoid wasting time debugging old bugs busy false is bad it means the GTH is in failsafe mode Proceeding is pointless manual investigation is in or der os restart type If it is watchdog the card crashed Send a bug re port to Corelatus restart cause lfitis power failure investigate the cause schedule The schedule is a list of jobs currently running on the GTH In most systems this will contain just one job at startup the controller itself sync ntp status Without time synchronisation the log timestamps will be wrong which makes debugging harder When restarting after an error reading out and saving the GTH s logs the application_log and system_log for later analysis is good practice 5 2 Runtime Checks The GTH performs many continuous runtime checks on resources and jobs and reports potentially interesting status changes via asynchronous event messages The important alarm and alert events are 114 5 3 E1 T1 Layer 1 Runtime Checks 5 FAULT TOLERANT SYSTEMS Type When Where Notes alarm board temperature Running hardware outside its rated tempera ture range shortens hardware lifetime and can result in temporary or permanent failure alarm cpu load An unexpectedly high CPU load can be a symp tom of an underlying problem alarm eth1 l
110. tion Voice Quality Measurement The GTH can forward a copy of selected conversations for instance test conversations to an external system for storage and analysis The GTH handles e Sniffing MTP 2 or LAPD signalling Your software can analyse the signalling to determine A and B numbers of interest and which timeslots are carrying the call e Recording selected timeslots 1 5 Sample Code and Blog Examples The Corelatus website has complete working examples for decoding signalling recording timeslot audio setting up E1 T1 and SDH SONET interfaces and more The examples are written in five languages C Java Python Erlang and Perl at http www corelatus com gth api A comfortable way to get started with GTH is to hack some of those examples Corelatus blog at http blog corelatus com includes explanations of many of the examples and screenshots showing them in action 2 PRINCIPLES AND TERMS 2 Principles and Terms A controller is the system controlling i e issuing commands to the Corelatus hardware It could be a Java system running on a 1U unix server in the same rack as the GTH or it could be a laptop running a net application on windows GTH is language and OS agnostic Resources are parts of the GTH which always exist the CPU the logs and ethernet interfaces are all resources Jobs are transient parts of the GTH which are created in response to commands DTMF detectors message players MTP 2 protocol
111. tribute name n_cdu value 5 gt lt attribute name maximum load value 33 gt lt attribute name current link load value 23 gt lt attribute name average link load value 41 gt lt attribute name maximum link load value 48 gt lt atm_aal5_monitor gt lt state gt 38 3 12 new cas_r2_linesig_monitor 3 COMMANDS 3 12 newcas r2_linesig_ monitor gt lt new gt lt cas_r2_linesig_monitor tag 0 ip_addr int int int int ip_port int gt lt pcm_source span string timeslot int first_bit 0 bandwidth 64 gt lt cas_r2_linesig_monitor gt lt new gt lt lt job id string gt A CAS Line signalling monitor detects changes in the a and b bits in CAS signalling and forwards this information to a server over a TCP socket The GTH reports each time the bits change and stay stable for at least 10ms CAS line signalling normally occupies timeslot 16 on an E1 The GTH can decode CAS signalling on any timeslot tag A user supplied value which is then sent in the header of each packet generated by this job Monitoring Socket Protocol The signalling information extracted from a link using a cas_r2_linesig_monitor is forwarded to a socket on a remote machine defined by jp addr and ip_port This socket is independent of the controllers API socket The GTH expects the external host to be listening on this socket before the new command is issued Each bit change is delivered with a 16 octet b
112. twork to detect fraud in real time to trace calls and to log signalling for later analysis GTH can terminate actively participate in ISDN LAPD allowing an application with ISDN Layer 3 support to set up and tear down calls Signalling Setup The steps for monitoring and terminating signalling are the same 1 Establish a listening TCP socket on the controller 2 Issue the XML command to start the signalling job specifying the IP address and port number of the socket created in the previous step 3 On the controller accept the inbound connection 4 The GTH sends the signalling packets to the newly established socket completely separate from the socket carrying XML commands Signalling Socket Protocol Each signalling packet arrives with a header which starts with the same fields all big endian for all protocols Bt ee yey Oy eT 8 77 81 5 41 31 21 11 octet 0x02 Tag The Length field indicates how many octets of data the rest of the packet contains To find the next packet read exactly Length octets The rest of the header is protocol specific and defined separately for each protocol for instance section 3 17 shows the complete header for frame relay Mixing Signalling Protocols The GTH can decode different signalling protocols at the same time on different timeslots For instance the GTH can decode MTP 2 on one E1 T1 while simultaneously decoding ATM AAL5 on another E1 T1 In some special cases the GTH
113. upported Use it to transmit frame relay data on Nx64kbit s timeslots using a GTH After the initial setup through the XML interface the specified socket is used to transfer signal units All messages on the socket have a six octet header e pees Te wT ey ey res 41 3 2 tO octet 0 octet 2 octet 4 octet 6 Payload The ength indicates the number of octets following the length field including the rest of the header The GTH automatically calculates and appends the frame check sequence to the payload 47 3 17 new fr_monitor 3 COMMANDS 3 17 new fr_monitor gt lt new gt lt fr_monitor sSu yes esu no load_limit 50 buffer_limit 256000 average_period 30 tag 0 timeout 0 ip_addr int int int int ip_port int gt lt pcm_source span string timeslot int first_bit 0 bandwidth 64 gt lt fr_monitor gt lt new gt lt lt job id string gt A frame relay monitor extracts frame relay signal units from a frame relay link and forwards them to a server over TCP Common input bandwidths are 256kbit s and 1980kbit s The GTH supports all multiples of 64kbit s All timeslots in a channel must be from the same E1 T1 span Timeslots need not be consecutive but they must be in ascending order su esu Select whether or not correct signal units packets and errored signal units are delivered buffer_limit f the socket carrying the signalling to the controller has a backlog gre
114. uration value 46226 gt lt attribute name RS LOF_entered value 1 gt lt attribute name RS LOF_duration value 11 gt lt attribute name RS BIP value 0 gt lt attribute name MS BIP value 0 gt lt attribute name MS REI value 0 gt lt attribute name child value sdh1 hop1_1 gt lt resource gt lt state gt Example Reading the counters for an SDH SONET HOP resource lt query gt lt resource name sdh1 hop1_3 gt lt query gt lt lt state gt lt resource name sdh1 hop1_3 gt lt attribute name status va lt attribute name OK_entered value 1 gt lue 0K gt lt attribute name OK_duration value 8335621 gt lt attribute name chil d val lt attribute name child val lt attribute name child val lt resource gt lt state gt ue sdh1l hop1_3 lop1_1 gt ue sdhl hop1_3 lop1_2 gt ue sdh1 hop1_3 lop1_3 gt Example Reading the counters for an SDH SONET LOP resource gt lt query gt lt resource name sdhl hopl_3 lop1_1 gt 84 3 30 query 3 COMMANDS lt query gt lt lt state gt lt resource name sdh1 hop1_3 10p1_1 gt lt attribute name status value 0K gt lt attribute name 0K_entered value 1 gt lt attribute name 0K_duration value 733623864 gt lt attribute name trace_identifier value MSC_south gt lt resource
115. ustment range 4 7 Ethernet Interfaces The GTH s two Ethernet interfaces are named eth1 and eth2 105 4 7 Ethernet Interfaces 4 RESOURCES Attribute Possible values in query Allowed values in set MAC address a string of hex digits read only IP4 address a dotted quad as for query IP4 mask a dotted quad default gateway a dotted quad collisions an integer read only TX errors an integer TX load an integer TX average load an integer TX maximum load an integer TX octets an integer link status up down Or unknown link speed 10 100 or unknown j link duplex HD FD or unknown j load limit an integer an integer The P4 address mask and gateway settings persist across reboots In most cases the IP4 address and mask should be set in the same operation lt set name eth1 gt lt attribute name IP4 address value 128 250 22 3 gt lt attribute name IP4 mask value 255 255 255 0 gt lt set gt lt lt ok gt The default gateway setting makes the GTH module accessible in a routed network Use this with caution see below The special value none disables an interface or clears the default gateway The TX load and TX load limit show how many percent of the interface s capacity are being used E g 5 of a 100Mbit s ethernet interface is 5Mbit s about 600kByte s The ocked attribute is an alias for an attribute of the same name in the in built WWW server see 4 1
116. will result ina conflict error The read only attributes on an E1 T1 link are Attribute Notes slip_positive The number of slips where an extra frame was inserted slip negative The number of slips where a frame was skipped frame_error The number of times a framing error occurred code_violation The number of line symbols which were in violation of the line coding rules only valid on E1 T1 Monitor 2 1 and E1 T1 Mes senger 2 1 code_ violation seconds The number of seconds in which there was at least one viola tion of the line coding rules only valid on E1 T1 Monitor 3 0 crc_error The number of L1 CRC errors Some framing modes for in stance doubleframe do not have an L1 CRC in those modes this counter is always zero LFA_entered The number of times the LFA state was entered There is a similar counter for each of the other possible states LFA_duration The cumulative number of milliseconds the link was in the LFA state There are analogous counters for each of the other pos sible states origin An SDH LOP resource only present when the E1 T1 comes from an SDH SONET interface It indicates which LOP the E1 T1 is mapped from Each E1 T1 resource broadcasts an event to all API sockets whenever its state changes lt lt event gt lt lil_message name pcem1A state 0K LOS LFA LMFA AIS RAI gt lt event gt Whenever an E1 T1 interface slips it broadcasts an event lt lt event gt lt slip n
117. y In other applications it s often necessary to explicitly designate one port as the sync source gt lt set name sync gt lt attribute name source value pcmlA gt lt set gt lt lt ok gt 88 3 33 takeover 3 COMMANDS 3 33 takeover gt lt takeover gt lt job id string gt lt takeover gt lt lt ok gt All jobs have an owner Initially the owner is the socket which used a new command to create the job Takeover allows ownership to be transferred to another socket Any evenis for instance DTMF events are then sent to the new owner When a socket is closed all the jobs it owns are deleted A system using failover could transfer ownership of jobs from one server to another to allow a system to be taken down for maintenance without interrupting calls Example Taking over ownership of a switched connection gt lt takeover gt lt job id cnxnl4 gt lt takeover gt lt ok gt 89 3 34 unmap 3 COMMANDS 3 34 unmap gt lt unmap namezsstring gt lt lt ok gt Remove a previously mapped E1 T1 Only used on hardware with SDH SONET interfaces See also The map command Example Removing a previously mapped E1 T1 gt lt unmap name pcm13 gt lt ok gt 90 3 35 update 3 COMMANDS 3 35 update gt lt update gt lt controller timeout int backups string gt lt update gt lt update gt lt mtp2_ monitor id string fisu
118. y Allowed values in set auto conferences enabled warn disabled as for query LED mode normal flashing as for query PCMLED assignment universal sequential as for query power consumption power in W read only power source A B both ethl eth2 ROM ID A hex number temperature temperature in degrees Celsius voice coding alaw mulaw as for query architecture gthl gth2 0 gth2 1 read only gth3 0 sth3 0 The auto conferences setting tells the GTH what to do when multiple connection Or player jobs send output to the same timeslot enabled means that the GTH will sum the audio so that the subscriber hears all sources warn behaves the same as enabled but also writes a warning to the application_log disabled causes the GTH to reject any new job which would create such a conference 108 4 9 Board 4 RESOURCES The PCM LED assignment changes the mapping between PCMs and LEDs in the connectors and on the front panel The default setting universal is backwards compatible with all Corelatus hardware and agrees with the diagrams in Corelatus documentation power consumption indicates the module s current power consumption This value typically fluctuates between readings depending on what the GTH is doing at the instant of reading power source indicates which of the power inputs currently has power On GTH models which support PoE Power over Ethernet this is a space delimited list of currently active power sources
119. yes dup_fisu no Issu yes dup_Issu no msu yes eSu no mark_likely_retrans no load_limit 50 buffer_limit 256000 average_period 30 tag 0 esnf no ip_addr int int int int ip_port 0 gt lt pcm_source gt lt mtp2_monitor gt lt update gt lt update gt lt lapd_monitor id string su yes esu no load_limit 50 buffer_limit 256000 average_period 30 tag 0 timeout 15 detect_abort yes ip_addr int int int int ip_port 0 gt lt pcm_source gt lt lapd_monitor gt lt update gt lt lt ok gt Update allows a job s attributes to be changed The changeable attributes on a controller are timeout and backups 91 3 35 update 3 COMMANDS timeout is in milliseconds with 0 meaning disabled backups is a space delimited list of controller job IDs Section 5 4 describes how to build fault tolerant systems by setting these attributes to non default values If backups is specified then timeout must also be specified in the same command On an mtp2_monitor and lapd_monitor the changeable attributes are load_limit buffer_limit and the signal unit filter settings fisu dup_fisu etc See also Section 3 21 describes the mtp2_monitor and its parameters in detail Example Disabling LSSU filtering In many applications LSSUs do not provide useful information so the GTH can be set up to discard them When troub

API Specification

Contents

Download Pdf Manuals

Related Search

Related Contents