estos ICE test tool
| State of knowledge | January 2024 |
|---|---|
| Product relevance | estos ProCall 8 Enterprise estos ProCall 7 Enterprise |
| Version status | 3.0.0.0 |
Introduction
The tool ICE-Test allows the user to test on the Internet STUN-/TURN server to check for availability. The ProCall Enterprise product from estos GmbH offers features such as audio / video chat or softphone, the operation of which may require correctly configured TURN / STUN servers. The ICE test tool therefore helps a system integrator or administrator, for example, to test the required servers and the associated configuration parameters.
Figure 1: User interface of the ICE-Test Tool
The program uses the same WebRTC components (see chapter Licenses) that are also used in estos ProCall Enterprise. This is not only to check the accessibility, but also the compatibility of the STUN / TURN server with estos ProCall Enterprise. It is also possible to use the tool to check the permeability of Internet routers or firewalls for STUN and TURN requests. This can be helpful for larger installations, for example, if certain external locations do not allow audio or video connections when configured centrally and correctly.
ICE Candidates
The ICE-Test tool determines the local ICE Candidates of the client to be tested, for which the Candidates
- of the type host,
- of the type srflx via STUN and
- of the type relay via TURN
can be determined. Compared to an ICE handshake for an AV chat or a SIP softphone call, these ICE candidates determined with the tool are not exchanged with a remote party. There is therefore no candidate pairing and candidate pair validation is also not carried out. Therefore, a successful test of the STUN or TURN connection using the ICE test is no guarantee for a secure media connection in communication practice. However, determining the ICE candidates with the help of this tool is a simple and reliable way of using the candidate lists to evaluate the network topology with regard to media connections in the customer environment more precisely.
Candidate type prflx is not considered further here, as this candidate type is not a local candidate, but a remote candidate (learned through communication with the other side).
Network routes
SIP softphone operation
With SIP softphone calls, media streams are exchanged between the estos ProCall Enterprise Client and the estos ProCall Enterprise Media Server. With the ICE-Test tool running on the client and the server, the candidates of the ProCall Enterprise Client and the ProCall Enterprise UC Media Server can be determined and a reliable and high-performance network route between these two components can be verified.
Audio/video chat
In AV chats (audio or video chats), media streams are exchanged between two estos ProCall Enterprise clients. With the ICE-Test tool running on both client hosts, the candidates can be determined and a reliable and high-performance network route between these two components can be verified.
Preparation and installation
As part of the estos UCServer administration, the tool ICE-Test can be found on the estos ProCall Enterprise Server directly in its program directory. The tool consists of a single file ICE-Test2.exe, which does not contain any dependencies to other modules, configurations or libraries.
Sample screenshot - Program directory ICE-Test.exe
This allows the tool to be copied from there to another host computer with a Microsoft Windows operating system to be tested (see the following chapter Operating systems).
For an ICE connection test on other systems such as smartphones with the iOS or Android operating systems, please use a different tool. For example, there are test pages on the Internet that enable STUN or TURN tests in the browser. Please refer to the note in the section Alternatives to the estos ICE test tool.
Product documentation estos ProCall Enterprise
The use of the ICE test in the estos ProCall Enterprise UCServer administration is described in the product documentation:
- ProCall 8 Enterprise settings STUN and TURN Server
- ProCall 7 Enterprise settings STUN and TURN Server
STUN Test
To check the accessibility of a STUN service, the required data such as URL and port number are entered in the STUN server field. If the usual port for STUN and TURN is 3478, the port parameter can also be omitted. The entry can be made as a URL or as an IP address, for example:
- ucturn.ucconnect.de
here without specifying the port number and the service or protocol (stun:), the content of the field is syntactically checked and supplemented accordingly if necessary.
When the Start test button is pressed, the complete format stun:ucturn.ucconnect.de:3478 appears. - ucturn.ucconnect.de:3478
here with the port number (3478 for the most common port for STUN or TURN services) - stun:ucturn.ucconnect.de:3478
the complete format was specified here syntactically. - 5.35.242.32
IP addresses can also be used. When the Start test button is pressed, the input is converted into the target format according to the usual protocol and port information, e.g. stun:5.35.242.32:3478.
When the Start test button is pressed, the current status is displayed in the status bar, e.g. whether errors have occurred or whether there is any information on the progress of the test. The status ICE gathering in progress describes that the target server has been addressed and a response is expected. Normally, the status only lasts a few fractions of a second and is therefore barely visible.
If the target server is not in operation, the status can also last up to 10 seconds until the error message STUN test failed appears. If further diagnostic information is available, this may be displayed (e.g. no answer).
If the server is reachable and presents a response that is compatible with the test tool, further information (Type, Prot, Local IP, External IP, Network Interface Name, see below for explanations) and the test result is displayed in the status line STUN test passed.
TURN Test
The input and evaluation of the TURN server parameters corresponds to the previous description of the STUN test.
If the TURN fields are left blank, no TURN test is performed.
The TURN test can be started even if no STUN server has been specified.
If the operator of the TURN server has assigned usernames and / or passwords, these can be entered in the corresponding optional fields Username and Password. It is possible to enter a password even if no username is used. The TURN password is not entered in plain text by default, i.e. the characters are masked by dots when entered. By ticking Show password, the display can be switched to unmasked and thus readable display and back at any time.
Detailed display in the text field
A list field above the status field displays additional information. The first line provides column-by-column information on the meaning of the listed values.
- Type:
local, STUN or TURN result data. - Local IP:
Local IP address of the test device with the port number that was used during the test. Even if no valid STUN server was found, the local IP address of the test device is displayed after a few seconds. During the TURN test, the IP address that the TURN server on the test device side sees from the outside is displayed. - External IP:
For data of type STUN, the IP address of the test client is displayed, which is visible from the public Internet. This IP address is usually also visible on the Internet router as the public address. Data of type Local has no External IP, dashes are displayed instead. Data of type TURN shows the IP address that the TURN server provides as an external relay address in the External IP column. - Network Interface Name:
Each network interface is assigned a name or a number, i.e. the Network Interface Name can also simply be a 0 or 1. For example, if a system has a LAN connection and a WLAN connection, the system is assigned two local IP addresses and therefore also two TURN and two STUN entries.
Figure 2: Detailed display in the list field
Test result
The status line shows the final test result. If only a STUN test was performed, only a result for the STUN test is displayed (e.g. STUN test passed). If the TURN test was also run, the result for the TURN test is also displayed (e.g. STUN test passed, TURN test passed).
Figure 3: Test result in the status bar - TURN passed
In the event of an error, additional diagnostic information is displayed, if available. The diagnostic information at the end of the log at Test result can also contain information that can help to solve a problem.
Figure 4: Test result in the status bar - TURN failed
Show log file
Pressing the Show Log button opens an editor window with the current content of the ICE-TLog.txt file. If the button is pressed after a TURN / STUN test, information on the progress of the test is displayed. The log file is preferably located in the same directory as the ICE-Test tool itself (the executable file ICE-Test2.exe). In this case, the beginning of the log shows the note Log file: ICE-TLog.txt without any further path information.
Figure 5: Editor window with log file
However, if the tool does not have write access to the current directory, the log file is created in the %temp% directory of the user context. In this case, the entry at the beginning of the log is e.g. Log file: C:\Users\MEIN~USER.NAME\AppData\Local\Temp\ICE-TLog.txt. If a different directory or a different log file name was assigned to the program via the command line, the entry in the log file is located accordingly.
Command line parameters and return values
The ICE-Test Tool can read in the parameters required for the test via the command line. The corresponding test is started immediately when the TURN / STUN parameters are specified. A further parameter enables automatic termination after the test has been completed. The ICE-Test Tool also passes a return value when the program is terminated, which allows the test result to be evaluated using a script, for example. During the test in command line mode, the file Ice-TLog.txt is written as usual and documents individual test details.
Parameters
| Parameter | Purpose | Sample |
|---|---|---|
| [/stunurl […]] | STUN test | Set STUN URL go.estos.de and port 3478: /stunurl go.estos.de:3478 |
| [/servers […]] | STUN and/or TURN test | STUN URL ucturn.ucconnect.de and set port 3478 , Set TURN URL ucturn.ucconnect.de, port (3478 and 443) and transport protocol (udp and tcp): /servers "stun:ucturn.ucconnect.de:3478" "turn:17******43:v*******o:zx**********************OA=@ucturn.ucconnect.de:3478?transport=udp" "turn:17******43:v********o:zx**********************OA=@ucturn.ucconnect.de:443?transport=tcp" The format for STUN: /servers "stun:URL:PORT" The format for TURN: /servers "turn:TIMESTAMP:USERID:PASSWORD@URL:PORT?transport=TRANSPORTPROTOCOL" |
| [/logfile […]] | Set log file path and log file name | /logfile „C:\Program Files (x86)\ESTOS\UCServer\logs\ICE-TLog.txt“ |
| [/autoexit] | ends the test automatically | n/a |
Application example
The ICE-Test Tool should test the accessibility of a STUN server with the URL go.estos.de and the port number 19302 . After a successful test, the program should exit automatically:
Return values
The return value can be evaluated by a calling program after the test has ended (e.g. with ERRORLEVEL if the call is made from a Windows terminal window / command prompt via command line).
The upper half-byte in hexadecimal format describes the TURN status. The lower half-byte describes the STUN status. This means that both test options can be evaluated with one call.
Table 1: Return values at the end of the program
| Meaning | TURN result | STUN result |
|---|---|---|
| Test not executed | 0x00 | 0x00 |
| Test successful | 0x10 | 0x01 |
| Test not successful, general | 0x20 | 0x02 |
| Test not successful, no response | 0x30 | 0x03 |
| Check password (check credentials) | 0x40 | n/a |
| Syntax error | 0x80 | 0x08 |
| No IP address (check cable) | 0x0A | |
| General system error (memory etc.) | 0x0B | |
| General input error | 0x0C | |
If, for example, successful TURN and STUN tests were performed simultaneously, the return value is 0x11 (i.e. 17 in decimal).
Operating systems
The ICE Test Tool was developed on the basis of the Windows® 7, Windows® 8.1 and Windows Server® 2012 operating systems.
As part of estos UCServer administration, this tool is also evaluated on the operating systems currently released for estos ProCall Enterprise Server:
- Systemvoraussetzungen estos ProCall 8 Enterprise Server
- Systemvoraussetzungen estos ProCall 7 Enterprise Server
There is no explicit guarantee of functionality on operating systems for estos ProCall Enterprise Client.
Licenses
This program is provided free of charge as part of a software package or as a download by estos GmbH. The use of the program takes place under exclusion of any warranty and liability of the manufacturer, as also explained in the last section of the license text below.
Further license information is displayed by pressing the About button in the ICE-Test Tool.
Figure 6: About the ICE-Test tool - License information
OSS licenses
The program uses open source components. The components are supplied as part of the ICE-Test binary program. The open source licenses used are listed below.
Licenses
http://www.webrtc.org/support/license
Copyright (c) 2011, The WebRTC project authors. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in
the documentation and/or other materials provided with the
distribution.
* Neither the name of Google nor the names of its contributors may
be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Explanations of the contents of the log file
Detailed information on the STUN test
A workstation computer for estos ProCall Enterprise Client is checked with regard to its connection to a STUN server.
The STUN server ucturn.ucconnect.de to be tested is addressed; the protocol and port are not specified, as the test is to be carried out on default values:
Or the execution of the STUN test via command prompt:
Once the test has been completed and a status is available, the log file is opened. This contains the following detailed information as an example.
Editorially inserted comments are marked with the character string ####.
Blank lines have been inserted to improve readability and structure.
For data protection reasons, some information is masked with *.
Detailed information on the TURN test
A workstation computer for estos ProCall Enterprise Client is checked with regard to its connection to a TURN server.
The TURN server ucturn.ucconnect.de to be tested is addressed; the protocol and port are not specified, as default values are to be checked:
Sample screenshot ICE-Test TURN Server - Start test
The use of the tool in the command prompt:
and the test result in the log file ICE-TLog.txt:
Further notes on the analysis
PCAP trace
For further details, a PCAP recording may be of interest.
A display filter for Wireshark can limit the display to packets of type STUN, TURNCHANNEL and CLASSICSTUN :
Sample screenshot: PCAP Trace - Set display filter for Wireshark - Set type
Alternatives to the estos ICE-Test Tool
There are other alternative tools on the Internet for checking STUN or TURN connections.
Only non-binding and exemplary is shown here https://icetest.info/:
Sample screenshot ICE-Test Info - Start test - Results
This allows testing in a browser not only under Microsoft Windows, but also under Apple macOS / iOS, Linux or Android.
This might be interesting to determine or test the ICE candidates for estos ProCall Mobile App.
ICE test of alternative TURN server
If ProCall Enterprise is to be operated in conjunction with TURN servers other than those integrated in estos UCConnect, a STUN and TURN test can also be carried out using the estos tool ICE-Test.
Because estos cannot guarantee the successful use of the estos tool ICE-Test with systems other than estos UCConnect, any TURN authentication mechanisms cannot be guaranteed.
Warranty and support claims for the operation of estos ProCall Enterprise with TURN services other than estos UCConnect are generally excluded.
If a TURN server works with a shared secret, this is entered in the ICE test tool:
- STUN URI
- TURN URI
- Username is not entered initially and is filled in automatically later
- Password is not entered initially and is filled in automatically later
- User Part remains empty
- Shared Secret: the shared secret which was entered for the TURN server to be tested
- and then press the button Generate... , this sets Username and Password.
Sample screenshot: ICE test - TURN server with shared secret
The diagnostics can now be started using the button Start test.
Further information
- Wissenswertes zu STUN/TURN für die Nutzung von Audio/Video und Softphone bei ProCall Enterprise
- Communication relations in softphone and AV operation
- STUN/TURN server: Requirements and commissioning
- Release ports for estos products – which network interfaces are used?
- Create PCAP record file/trace for UCServer – network analysis
- Introduction
- Preparation and installation
- Product documentation estos ProCall Enterprise
- STUN Test
- TURN Test
- Detailed display in the text field
- Test result
- Show log file
- Command line parameters and return values
- Operating systems
- Licenses
- Explanations of the contents of the log file
- Further notes on the analysis
- ICE test of alternative TURN server
- Further information