Technical Helpweb

- more articles

IMGtools application

Introduction

The IMGtools application is intended to help with the diagnosis of issues with the Dialogic® IMG Integrated Media Gateways, including the Dialogic® IMG 2020 Integrated Media Gateway (IMG 2020), formerly referred to as Dialogic® BorderNet™ 2020 Session Border Controller. The tool can be used to format, analyze and extract individual call traces from a call trace, and supersedes the "IMG Call Trace Viewer" application that was previously available.

IMGtools incorporates the "trace2pcap" tool which can be used to export SS7 raw data from a trace to a pcap trace (which can be opened in Wireshark), and an SS7 decoding module which can be used to show decoded SS7 messages from the call flow graph page. It also includes a tool for converting point codes between various formats and a tool for decoding ISDN messages from a raw trace.

Installation

The IMGtools application requires the .NET 4.0 or above framework to be installed and the Visual C++ 2010 SP1 redistributable package (for 32bit or 64bit operating system as appropriate). They MUST be installed before attempting to run the IMGtools2.exe program.

NOTE: It is extremely important that the correct version of the Visual C++ 2010 redistributable package is installed; otherwise, the application could fail to run or will show an exception when trying to load a trace file. Please see the "Download" section at the bottom of this article for links to the relevant files.

The application is completely self-contained, i.e., all the files required to run it are in the same directory/zip file. Simply extract the zip file to a place where you have read/write permissions and run "IMGtools2.exe" to start.

NOTE: As of Windows 7, non-Administrator users do NOT have permission to WRITE to the "Program Files" or "Program Files (x86)" directories. Do NOT install IMGtools to one of these directories (or a sub-directory) otherwise the application will fail to start if you run it as a non-elevated user.

To work around this, it is possible to right-click the executable and select "Run as Administrator".

User Interface

On running "IMGtools2.exe", the application will start and will look like this:

Please click on the following image to view it full size.

• 1 - Application Selection Tab : Select an application from the vertical tabbed list. By default this will be the "Trace Viewer" application.
• 2 - Call Reference List : When the Trace Viewer is selected, the call reference list will appear here. Select one or more items from this list (with SHIFT-click or CTRL-click) to make one or more (up to 5) calls "active". The call data will be displayed in the Call Flow and Selected Calls tabs of the Trace Viewer application. Note that when a file is successfully loaded, the "Expand" checkbox will become active. This will display more data for the loaded calls.
• 3 - Call Data Window : When a call is selected, the call flow and selected calls tabs will contain a view of the call(s) data. The All Calls tab will contain the parsed call data for all detected calls in the loaded file.
• 4 - The status bar contains progress information when a file (or files) is loaded.
• 5 - The call reference filter allows the user to filter the "CallRef" list.

Most views of the call trace have context-sensitive menus which are accessed with the right mouse button. For example, when a call is selected and the call flow graph is visible, the context menu looks like this:

Please click on the following image to view it full size.

There are options in this example to save either the selected call, or all calls, to a text file (which is useful for extracting a single call or a few calls from a large trace file), or to export the data to a Wireshark file.

Opening a Call Trace

Call trace files can be opened in one of three ways:

• Right-clicking and choosing the "Open..." option from the context menu.
• Dragging and dropping a compatible file* onto the application.
• Pressing CTRL-V to paste the text of a call trace directly into the application.

In all cases, the call reference list will be populated with a list of calls found in the files. This may take a few seconds depending on how many calls are in the trace files. It is possible to use the first two options to open multiple files simultaneously.

* Note: compatible file extensions for call trace files are .txt and .log.

The Context Menu

In the trace viewer application, right-clicking almost anywhere will bring up the context menu. This allows you to do the following:

Open : Open an existing log file or multiple log files.

Save : There are options to save either all calls, or the currently selected calls only in the call reference list, to a file. In this way it is possible to extract the tracing for a single call to a file.

Export : There are options to export either all calls, or the currently selected calls, to a Wireshark .pcap file. This will dump all SIP and SS7 signalling messages to a Wireshark file so it can be opened and decoded in Wireshark.

Export CallRefs to CSV : This will dump the contents of the call reference list to a CSV file.

Decode SS7 as... : Select either the default Q.763 or ND1007 (BT) protocol for decoding SS7 messaging.

Call Flow Options : The timestamp displayed in the call flow graph can either be absolute time or relative time.

Note that all options are saved when the program exits and will be remembered when the program restarts.

The Call Reference List

The call reference list will be populated with a list of all calls found in any files that are loaded. By default these will be ordered by the call reference itself, although it may be sorted by clicking the column headers. Clicking the "expand" check box will show additional details about the calls. Note that these columns may take some time to be populated depending on how large the trace files are.

This list can be filtered by entering a partial call reference in the box at the bottom of the list entitled "Filter by call ref...". This will filter showing any partial matches (i.e., not just matches beginning or ending with the filter).

It is sometimes useful to select two or more calls at a time that are related to each other (i.e., a call out from the IMG Gateway and the corresponding call in from whatever device was called). To this end, up to five calls at a time can be selected in the call reference list by using a combination of SHIFT-click and CTRL-click. Selecting a sixth call will cause the first to be de-selected. The call trace for all calls will be shown in the call data window as described in the next section. 

The Call Data Window

To the right hand side of the application, there is a tabbed window with 4 tabs. Initially the "Selected Calls" tab will be selected. The sections below describe the function of each of these tabs.

Call Flow

When call references are selected, the call flow tab will show a graphical view of the signalling for the selected call(s).

For SS7 and SIP calls, each signalling message can be clicked to show the decoded signalling detected for that message. Please note that for various reasons, ISDN messages cannot be decoded in this way.

Call Flow (Text)

This tab shows the same signalling data as the "Call Flow" tab but in text format that can be copied & pasted. The signalling messages in this tab are not click-able.

Selected Calls

This shows the filtered call tracing information for just the call references that are selected. There is an arrow at the top which can be expanded to filter the call tracing data further to show only particular call "legs" and to switch on/off the display of any "errors". Note that an "error" is defined as a trace message that has a call reference of "00:00000" i.e., it does not apply to any specific call. Errors with a timestamp which is a few seconds before the call(s) in question, to a few seconds after the call ends, are also shown.

Pressing the key combination CTRL-F will open/close the "find" toolbar at the top where you can search for specific text in the selected calls trace. 

All Calls

This shows the call tracing information for all calls in the file. Note that this is not a view of the raw text of the trace files, but is compacted with line spaces removed, and lines joined together where appropriate.

Download

IMGtools2 (64bit) for Windows

IMGtools2 (32bit) for Windows

Microsoft .NET Framework 4.0 (Standalone Installer)

Microsoft Visual C++ 2010 SP1 Redistributable Package (32 bit / x86)

Microsoft Visual C++ 2010 SP1 Redistributable Package (64 bit / x64)

Legal Note

This document discusses one or more open source products, systems and/or releases. Dialogic is not responsible for your decision to use open source in connection with Dialogic products (including without limitation those referred to herein), nor is Dialogic responsible for any present or future effects such usage might have, including without limitation effects on your products, your business, or your intellectual property rights.