Getting hex dumps of E1/T1 timeslots
Posted May 7th 2014
This post looks at a few simple tricks for understanding the WWW browser-based hex dump from a typical E1/T1 and then moves on to some more complicated things you can do with timeslot data by piping it to the standard (from BSD, but now on most unix-like systems) hexdump tool.
Browser-based hex dumps
The HTTP server built into GTH (and STH 3.0) lets you click your way to a timeslot-by-timeslot hexdump of an E1/T1. It shows 8ms of data, which gives you a rough idea of what's happening on an E1/T1:
The HTTP server is on port 8888. To get to the hex dump, click 'L1' (at the top), then the E1/T1 you're interested in, for instance pcm4A, then 'hex dump' (at the bottom).
In the screenshot, timeslot 0 has a repeating two-octet pattern typical of an E1 link using doubleframe.
Timeslots 1 and 2 have the default idle pattern for E1 links: hex 54. That's silence, so those timeslots are most likely unused for the moment.
Timeslot 3 has nonstop 3f 3f 3f 3f. Writing that out in binary, 00111111001111110011111100111111, lets you see the pattern of six ones with a zero on either side. That's a flag. ISDN LAPD and Frame Relay links transmit flags between packets. Timeslot 3 probably contains LAPD signalling. There are eight possible bit rotations of the flag: 7e, e7, fc, cf, 9f, f9, 3f, f3.
Timeslot 4 has a repeating six-octet pattern. That's an MTP-2 FISU. Timeslot 4 is almost certainly running MTP-2.
Command-line hex dumps
This section assumes you're comfortable compiling C programs and using a Unix-like operating system, probably one of the BSDs or Linux. (You can do the same thing using Python, if you prefer, there's sample code for that too.)
Corelatus.com has some C sample code. It's also on github. Using that code, you can record a timeslot to a file:
./record 172.16.2.8 4A 1 /tmp/recording.raw
Let it run for 10 or 20 seconds, then stop it with ^C. You can now look at the data using the standard BSD tool 'hexdump' (on Debian, it's in the 'bsdmainutils' package):
tmp >hexdump -C recording.raw | head -2 00000000 72 f9 d8 76 e5 df d6 fd dc 5d ff f5 f0 94 57 da 00000010 eb 6e fa e4 7d 90 e4 e0 91 e2 eb ea ed e4 e3 e4
There's no limit to how large such recordings can be, so if you're debugging something, you can leave the recorder running for hours.
Live hex dumps
The 'record.c' sample code can also write to standard output. You can use that to get a live view of a timeslot via hexdump:
c >./record 172.16.2.7 3A 3 - 2>/dev/null | hexdump -C 00000000 3f 3f 3f 3f 3f 3f 3f 3f 3f 3f 3f 3f 3f 3f 3f 3f *
The example above demonstrates a neat feature in 'hexdump': 'hexdump' suppresses repeated data. So you can leave it running in a window and it'll only produce output when something changes.
Permalink | Tags: GTH, telecom-signalling, C
Controlling a GTH from Amazon EC2
Posted October 1st 2011
This post is about what I did to get the GTH example code (the C version) to run on Amazon EC2, controlling a GTH on the public internet.
Amazon EC2 is a service where you rent a virtual server by the second. The virtual server can run Windows or Linux. Our in-house environment is all-linux, so we use EC2 to give us an on-demand Windows environment to check example code on.
Overview
- Connect a GTH to the Internet
- Create and set up an Amazon EC2 Instance running Windows Server
- Install the example code
- Open up holes in the firewall
Taking each step in detail:
Connect a GTH to the Internet
First off: spend a moment thinking about security. You probably don't want SS7 traffic from a live network going over the internet. The GTH is designed to be installed in a secure network, not directly facing the internet. Take care.
Most likely, you've got the GTH behind a firewall. The firewall needs to be configured so that TCP port 2089 gets to the GTH.
The GTH needs to be told where the firewall is. In my case, it's at 172.16.1.1:
query_set 172.16.1.10 eth1 "default gateway" 172.16.1.1
Create an Amazon EC2 Instance
I'm assuming you're familiar with Amazon EC2. It's your choice which OS you want to run at Amazon. In my case, I wanted Windows because our primary development environment is linux, so I like the convenience of starting up an Amazon machine when I need to do something with Windows.
Install the example code
An easy way to do that is to use a WWW browser on EC2 to download the example code from corelatus.com.
On Amazon windows instances, an alternative is to use a remote share via terminal server. Still another is to install 'putty' and use 'psftp' to get the code from your own server.
Now you can try out the install:
> query_set 128.250.22.3 board LED mode=normal PCM LED assignment=universal voice coding=alaw architecture=gth2.1 ROM ID=0x26cbce800000005f temperature=40.2 power consumption=6.4 power source=A POE source=
'query_set' only uses the port 2089 API socket. But some of the other examples do more complicated things with TCP. 'playback_file', 'record' and 'save_to_pcap' all open TCP connections back to EC2 to send data.
Relaxing firewall rules
There are three places which are likely to block TCP connections originating at the GTH. You need to make sure each of those lets them through.
- The firewall between the GTH and the internet needs to allow the GTH to make outbound TCP connections. On most small firewall setups, that's the default. Some firewalls block outbound connections entirely, in which case you're out of luck (unless you can tunnel TCP through something else, such as SSH or an HTTP/1.1 proxy, but even that will require modifying the example code to use known port numbers).
- The firewall in EC2 Windows "security groups" needs to allow inbound TCP connections on all ports, as long as the originate from the GTH. Use the "Security Group" screen of the AWS console, in the "inbound" tab create a new rule. Use the internet-facing IP address the GTH has as the "source" IP. That way only the GTH can connect to your EC2 instance.
- Windows' own firewall needs to allow inbound TCP connections.
Either make a program-specific exception, or disable the windows
firewall entirely (and just rely on EC2's firewall).
netsh firewall add allowedprogram c:\users\mml\downloads\save_to_pcap.exe mode=ENABLE
All done
Now you can run use pretty much anything in the GTH API from a machine in Amazon's cloud.
Live Wireshark captures on Windows
Posted June 15th 2011
Update 23. January 2014: the -c switch is needed to force save_to_pcap to emit data in classic Pcap format, instead of Pcap-NG. Wireshark 1.10.5 doesn't allow Pcap-NG in pipes.
I've written about using Wireshark to look at signalling captured from an E1/T1 before. As of a few days ago, it's possible to do live captures on Windows, like this:
save_to_pcap -c 172.16.1.10 1A 2A 16 \\.\pipe\ss7.1 wireshark -k -i \\.\pipe\ss7.1
When you're capturing live, the SS7 packets appear in Wireshark in real-time.
The new version of 'save_to_pcap' program is part of the C examples, the .zip file contains both source (compiles on Unix and Windows) and .exe files.
It's always been possible to do live captures on Unix, you just pipe stdout:
./save_to_pcap -c gth21 1A 2A 16 - | wireshark -k -i -
Porting C socket code to Windows
Posted June 16th 2010
I just ported the C example code for controlling Corelatus E1/T1 hardware to Visual Studio 2010. Doing that was easier than expected. This first part of this post is about how to use that code. The second part is a bit of history about what I had to do to port the code.
Obtaining Visual Studio
Microsoft have their C/C++ compiler available for free download on microsoft.com
The install process is pretty standard for windows, if you're accustomed to Microsoft products, there are no surprises here.
Compiling the code
- Start the "Visual Studio Command Prompt". By default, that's in "Start/Programs/Microsoft Visual Studio 2010 Express".
- Navigate to the directory you unpacked the sample code in. Remove any old .exe files with 'del *.exe'.
- Run 'nmake /f NMakefile'. After a couple of seconds, you have six brand-new .exe files. Here's what this step looks like:
If you just wanted to see how to compile the code, you can stop reading now. The rest of the post is just about what I had to do to make this work with Microsoft's compiler.
Hurdle #1: MS nmake vs gnumake vs Visual Studio projects
Conclusion: I ended up using Microsoft's nmake and wrote a separate NMakefile for it.
My code gets built by 'make', through a Makefile. Visual Studio doesn't include a make program which can understand normal Makefiles, leaving me a choice of either using the Visual Studio IDE or using Microsoft's nmake.
I spent half an hour trying the IDE route. When you make a new project, you have to choose what sort it is. "CLR Console Application" seemed closest to what I wanted to do, so I chose that. Maybe "Makefile Project" would have worked better. Things got increasingly confusing from there. What's a "solution?" Why are "precompiled headers" enabled? I just want to compile a few hundred lines of C. At that point, I gave up, the IDE is clearly not the easiest way for me to get started.
Next, I tried Microsoft's replacement for make, called nmake. That didn't start flawlessly either, nmake uses its own syntax. Initially, I thought I might be able to write one Makefile which both gnumake and nmake understand. But Microsoft's syntax seems to be too different to allow that. Oh well. The NMakefile is just a dozen lines or so.
Hurdle #2: Missing header files
Conclusion: I used #ifdefs to include different header files when compiling in a win32 environment.
Visual Studio doesn't provide some of the header files the code uses, e.g. there's no 'unistd.h' and no 'sys/socket.h'. Odd. Providing most of unistd.h shouldn't be too hard.
The point of this exercise is to get the code to compile using a Microsoft toolchain, so I didn't investigate using cygwin or mingw.
In the end, it turns out that I wasn't using anything from 'unistd.h' which didn't get provided by something else in win32. 'socket.h' (and friends) was a bit harder, but it turns out that's provided by 'winsock2.h'.
Hurdle #3: 'Mostly compatible' socket API
Conclusion: winsock2 is different to the BSD socket API, but the differences can be worked around with just a few changes.
Sockets were invented on unix, so I assumed that other OSes would just copy the interface. But no, not on win32. There seem to be at least two attempts to make a socket API for windows, called 'winsock' and 'winsock2'. The first seems to be deprecated. The main problems I hit were:
- You can't use close() on a socket, you have to use closesocket()
- You can't use read() on a socket, you have to use recv()
- errno doesn't report socket errors, you have to call a special Windows Socket error reporting function.
None of those problems are hard to get around.
Hurdle #4: GNU and Microsoft can't agree on function names
Both GNU and Microsoft have replacements for some functions which are prone to security problems. If you use plain strcat() or strcpy, visual studio warns about security problems.
Disabling the warnings would be quick but feels like cheating. So I looked at the 'less insecure' alternatives. GNU call them strncat and strncpy whereas Microsoft call them strcat_s and strcpy_s. And the arguments are the same way around. It would have been nice if GNU and MS had solved this the same way, but no. Minor annoyance.
Hurdle #5: Structure packing pragmas
Conclusion: Both MS and GNU understand the #pragma pack(N) syntax, but only GNU understands the __attribute__((__packed__)) syntax.
A couple of the examples (save_to_pcap.c and record.c) use structures to encode or decode data defined by an external format. For instance, here's what the wire format of a 'Pcap' protocol capture file looks like:
typedef struct {
unsigned int magic;
unsigned short major_version;
unsigned short minor_version;
unsigned int GMT_to_localtime;
unsigned int sigfigs;
unsigned int snaplen;
unsigned int network;
} PCAP_global_header;
We have to tell the compiler that spacing out the fields to get a certain alignment isn't allowed. The recommended GNU way to do that is to add __attribute__((__packed__)) after the structure. The recommended Microsoft way is to add #pragma pack(1) somewhere before the structure, and then remember to change the packing back again before hitting any code which is sensitive to performance.
Since this is just example code, we don't care about that last bit of performance, so we can just leave the packing at 1.
Aside: the structure above is a bit sloppy because just quietly assumes that an int is 32 bits and a short 16.
Hurdle #6: Windows firewall
Some of the example code opens TCP sockets for listening. By default, the windows firewall doesn't allow that. Just click "fine, ok, let me do this".
Unfortunately, that looks ugly for the user---the program will fail the first time you run it, and the pop-up box says "publisher unknown". Does anyone know how to improve on this? It'd be nice if the user could approve the publisher, i.e. me, once, and then every program works.
How long did the porting take?
A couple of days, including getting Visual Studio installed. That's for a few thousand lines of code with a bit of socket IO and file IO.
If I had to do it again, it'd take an afternoon or so.
GTH 'C' API
Posted January 20th 2010
This post is for people who want to use C to control a GTH. Other languages (e.g. Erlang, Java, Python and Perl) are easier to work with, but in some applications you want the complete control that C gives you.
Corelatus provides a C API for GTH. The C API lets you control a GTH using plain C function calls---all of the XML wire format is taken care of.
Here's an example of how to use it to record speech on an E1/T1 timeslot, something you'd typically do in a voicemail system:
#include "gth_apilib.h"
...
GTH_api api; // GTH_api represents one GTH API connection
int result;
int data_socket;
char buffer[2000];
char job_id[MAX_JOB_ID];
int octet_count;
result = gth_connect(&api, "172.16.1.10"); // Assuming the default GTH IP
assert(result == 0);
// We want to record audio on the E1/T1 called "1A", on timeslot 3.
data_socket = gth_new_recorder(api, "1A", 3, job_id);
while ( (octet_count = recv(data_socket, buffer, sizeof buffer, 0)) ) {
// do whatever you want with the received data
}
...
The recording above happens in the 'while' loop. It continues forever (i.e. until you abort it). The audio data is bit-for-bit identical to what was on the E1/T1 timeslot, so this can be used for recording both voice and signalling.
Further examples
The C API code includes further examples to:
- Record audio or signalling from a timeslot to a .wav file
- Play back previously recorded files
- Install (upgrade) the firmware on a GTH
- Monitor (sniff) SS7 MTP-2 and save the signalling to a wireshark (PCap) compatible file.
- Monitor CAS R2 signalling.
Standalone Parser
Aside: the C API code includes a standalone parser for the XML responses the GTH emits. You can use the parser without using the rest of the API library, if you want to.