Simula Research Laboratory / Center for Resilient Networks and Applications / NorNet
Homepage of Thomas Dreibholz / HiPerConTracer Homepage

HiPerConTracer
High-Performance Connectivity Tracer
HiPerConTracer Results Example from the SoftCOM 2020 Paper

πŸ“‘ Quick Navigation

πŸ“° Latest News

πŸ’‘ What is High-Performance Connectivity Tracer (HiPerConTracer)?

High-Performance Connectivity Tracer (HiPerConTracer) is a Ping/Traceroute measurement framework.

HiPerConTracer denotes the actual measurement tool. It performs regular Ping and Traceroute runs among sites, featuring:

Furthermore, the HiPerConTracer Framework provides additional tools for helping to obtain, process, collect, store, and retrieve measurement data:

The HiPerConTracer Framework

πŸ“¦ Binary Package Installation

Please use the issue tracker at https://github.com/dreibh/hipercontracer/issues to report bugs and issues!

Ubuntu Linux

For ready-to-install Ubuntu Linux packages of HiPerConTracer, see Launchpad PPA for Thomas Dreibholz! 

sudo apt-add-repository -sy ppa:dreibh/ppa
sudo apt-get update
sudo apt-get install hipercontracer-all

Fedora Linux

For ready-to-install Fedora Linux packages of HiPerConTracer, see COPR PPA for Thomas Dreibholz! 

sudo dnf copr enable -y dreibh/ppa
sudo dnf install hipercontracer-all

FreeBSD

For ready-to-install FreeBSD packages of HiPerConTracer, it is included in the ports collection, see FreeBSD ports tree index of benchmarks/hipercontracer/! 

sudo pkg install hipercontracer

Alternatively, to compile it from the ports sources: 

cd /usr/ports/benchmarks/hipercontracer
make
sudo make install

πŸ’Ύ Build from Sources

HiPerConTracer is released under the GNU General Public Licence (GPL).

Please use the issue tracker at https://github.com/dreibh/hipercontracer/issues to report bugs and issues!

Development Version

The Git repository of the HiPerConTracer sources can be found at https://github.com/dreibh/hipercontracer: 

git clone https://github.com/dreibh/hipercontracer
cd hipercontracer
sudo ci/get-dependencies --install
cmake .
make

Optionally, for installation to the standard paths (usually under /usr/local): 

sudo make install

Note: The script ci/get-dependencies automatically installs the build dependencies under Debian/Ubuntu Linux, Fedora Linux, and FreeBSD. For manual handling of the build dependencies, see the packaging configuration in debian/control (Debian/Ubuntu Linux), hipercontracer.spec (Fedora Linux), and Makefile FreeBSD.

Contributions:

Current Stable Release

The tarball has been signed with my GnuPG key 21412672­518D8B2D­1862EFEF­5CD5D12A­A0877B49. Its authenticity and integrity can be verified by: 

gpg --keyserver hkp://keyserver.ubuntu.com --recv-keys 21412672518D8B2D1862EFEF5CD5D12AA0877B49
gpg --verify hipercontracer-<VERSION>.tar.xz.asc hipercontracer-<VERSION>.tar.xz

Old Stable Releases

The tarballs have been signed with my GnuPG key 21412672­518D8B2D­1862EFEF­5CD5D12A­A0877B49. Its authenticity and integrity can be verified by: 

gpg --keyserver hkp://keyserver.ubuntu.com --recv-keys 21412672518D8B2D1862EFEF5CD5D12AA0877B49
gpg --verify hipercontracer-<VERSION>.tar.xz.asc hipercontracer-<VERSION>.tar.xz

In the simple case, HiPerConTracer can just be used as a measurement tool without creating special directory setups; to be described in Running a HiPerConTracer Measurement.

For a larger setup, particularly consisting of measurement nodes and/or database import, it is recommended to properly set up storage directories. As current best practises for using the HiPerConTracer framework securely, the following directory structure and file permissions are recommended:

Users

Groups

Directories and Permissions

Access Control Lists (ACL)

πŸ˜€ Running a HiPerConTracer Measurement

HiPerConTracer is the measurement tool itself.

Example 1

A simple Ping run, without data storage, from arbitrary local addresses, to all IPv4 and IPv6 addresses of www.heise.de (resolved by DNS) via ICMP (default): 

sudo hipercontracer --destination www.heise.de --ping --verbose

Example 2

Run HiPerConTracer measurement #1000000, from arbitrary local IPv4 address to destination 193.99.144.80 (www.heise.de), using Traceroute and Ping. Store data into sub-directory data in the current directory; run as current user $USER: 

sudo hipercontracer \
   --user $USER -#1000000 \
   --source 0.0.0.0 --destination 193.99.144.80 \
   --traceroute --ping \
   --resultsdirectory data \
   --verbose

Notes:

Example 3

Run HiPerConTracer measurement #1000001, from arbitrary local IPv4 (0.0.0.0) and IPv6 (::) addresses to destinations 193.99.144.80 and 2a02:2e0:3fe:1001:302:: with Traceroute and Ping via ICMP (default). Store results files into sub-directory data in the current directory; run as current user $USER: 

sudo hipercontracer \
   --user $USER \
   -#1000001 \
   --source 0.0.0.0 --source :: \
   --destination 193.99.144.80 --destination 2a02:2e0:3fe:1001:302:: \
   --traceroute --ping \
   --resultsdirectory data \
   --verbose

πŸ“„ Results File Formats

Header format: 

#? HPCT format version programID

Header details:

Column Field Description
1 format Measurement identifier (e.g. Ping, Traceroute)
2 version Version of the output data format (decimal)
3 programID Identifier for the program generating the output (e.g. HiPerConTracer/2.1.12)

Header example: 

#? HPCT Ping 2 HiPerConTracer/2.1.12

Ping

Version 2

Ping format, version 2
#P<io_module> measurementID sourceIP destinationIP timestamp burstseq traffic_class packetsize response_size checksum sourcePort destinationPort status timesource delay_app_send delay_queuing delay_app_receive rtt_app rtt_sw rtt_hw
Ping fields, version 2
Ping Fields (Version 2)
Column Field Description
1 ping #P<io_module>, with #Pi = ICMP Ping, #Pu = UDP Ping
2 measurementID Measurement identifier (decimal)
3 sourceIP Source IP address
4 destinationIP Destination IP address
5 sendTimestamp Send Timestamp (nanoseconds since the UTC epoch, hexadecimal)
6 burstseq Sequence number within a burst (decimal), numbered from 0
7 traffic_class The IP Traffic Class/Type of Service value of the sent packets (hexadecimal)
8 packet_size The sent packet size (decimal, in bytes) including IPv4/IPv6 header, transport header and HiPerConTracer header
9 response_size The response packet size (decimal, in bytes) including IPv4/IPv6 header, transport header and HiPerConTracer header
10 checksum The checksum of the ICMP Echo Request packets (hexadecimal); 0x0000 for other protocols, 0xffff for unknown
11 sourcePort Source port, 0 for ICMP (decimal)
12 destinationPort Destination port, 0 for ICMP (decimal)
13 status Status code (decimal); see Status Code and Status Flags
14 timesource Source of the timing information (hexadecimal) as AAQQSSHH; see Time Source
15 delay_app_send The measured application send delay (nanoseconds, decimal; -1 if not available)
16 delay_queuing The measured kernel software queuing delay (nanoseconds, decimal; -1 if not available)
17 delay_app_receive The measured application receive delay (nanoseconds, decimal; -1 if not available)
18 rtt_app The measured application RTT (nanoseconds, decimal)
19 rtt_sw The measured kernel software RTT (nanoseconds, decimal; -1 if not available)
20 rtt_hw The measured kernel hardware RTT (nanoseconds, decimal; -1 if not available)
Ping example, version 2
#Pi 88888888 10.193.4.168 10.193.4.67 178f2cc6c7ea013a 0 0 44 44 7d61 0 0 255 11666600 36997 6983 50311 426999 332708 -1

Version 1

Version 1 was used before HiPerConTracer 2.0.0 and is now deprecated! However, it can still be read and processed by the HiPerConTracer Results Tool and the HiPerConTracer Importer Tool. While HiPerConTracer still can generate version 1 output, this is strongly discouraged due to limitations of this format version!

Ping format, version 1
#P sourceIP destinationIP sendTimestamp checksum status rtt [traffic_class [packet_size [timesource]]]
Ping fields, version 1
Ping Fields (Version 1)
Column Field Description
1 ping #P; HiPerConTracer <2.0 only provided ICMP Ping
2 sourceIP Source IP address
3 destinationIP Destination IP address
4 sendTimestamp Send Timestamp (microseconds since the UTC epoch, hexadecimal)
5 checksum The checksum of the ICMP Echo Request packets (hexadecimal); 0x0000 for other protocols, 0xffff for unknown
6 status Status code (decimal); see Status Code and Status Flags
7 rtt The measured RTT (microseconds, decimal)
8 traffic_class The IP Traffic Class/Type of Service value of the sent packets (hexadecimal)
9 packet_size The sent packet size (decimal, in bytes) including IPv4/IPv6 header, transport header and HiPerConTracer header
10 timesource Source of the timing information (hexadecimal) as AAQQSSHH; see Time Source

Notes:

Ping example, version 1
#P 2001:700:4100:4::2 2001:250:3801:71::149 5ed91fe263db1 9106 200 5000000 0 6

Traceroute

Version 2

Traceroute format, version 2
#T<io_module> measurementID sourceIP destinationIP timestamp round totalHops traffic_class packet_size checksum sourcePort destinationPort statusFlags pathHash
β‡₯sendTimeStamp hopNumber response_size status timesource delay_queuing delay_app_receive rtt_app rtt_app rtt_sw rtt_hw hopIP
β‡₯...
Traceroute fields, version 2
Traceroute Fields (Version 2)
Column Field Description
1 traceroute #T<io_module>, with #Ti = ICMP Traceroute, #Tu = UDP Traceroute
2 measurementID Measurement identifier
3 sourceIP Source IP address
4 destinationIP Destination IP address
5 timestamp Timestamp (nanoseconds since the UTC epoch, hexadecimal) of the current run. Note: This timestamp is only an identifier for the Traceroute run
6 round Round number (decimal)
7 totalHops Total hops (decimal)
8 traffic_class The IP Traffic Class/Type of Service value of the sent packets (hexadecimal)
9 packet_size The sent packet size (decimal, in bytes) including IPv4/IPv6 header, transport header and HiPerConTracer header
10 checksum The checksum of the ICMP Echo Request packets (hexadecimal); 0x0000 for other protocols, 0xffff for unknown
11 sourcePort Source port, 0 for ICMP (decimal)
12 destinationPort Destination port, 0 for ICMP (decimal)
13 statusFlags Status flags including the status code for Ping above for the lower 8 bits (hexadecimal); see Status Code and Status Flags
14 pathHash Hash of the path (hexadecimal); see Path Hash

For each hop:

Traceroute Hop Fields (Version 2)
Column Field Description
1 sendTimeStamp Timestamp (nanoseconds since the UTC epoch, hexadecimal) for the request to this hop
2 hopNumber Number of the hop
3 response_size The response packet size (decimal, in bytes) including IPv4/IPv6 header, transport header and HiPerConTracer header
4 status Status code (decimal; the values are the same as for Ping, see see Status Code and Status Flags)
5 timesource Source of the timing information (hexadecimal) as AAQQSSHH; see Time Source
6 delay_app_send The measured application send delay (nanoseconds, decimal; -1 if not available)
7 delay_queuing The measured kernel software queuing delay (nanoseconds, decimal; -1 if not available)
8 delay_app_receive The measured application receive delay (nanoseconds, decimal; -1 if not available)
9 rtt_app The measured application RTT (nanoseconds, decimal)
10 rtt_sw The measured kernel software RTT (nanoseconds, decimal; -1 if not available)
11 rtt_hw The measured kernel hardware RTT (nanoseconds, decimal; -1 if not available)
12 hopIP Hop IP address
Traceroute example, version 2
#Ti 12345678 10.44.33.111 1.1.1.1 1795a9a23c629fbf 0 11 0 44 90e1 0 0 200 a7cfb997ef00d133
β‡₯1795a9a23c629fbf 1 56 1 116666aa 117720 19410 40428729 57465605 16899746 16778688 10.44.32.1
β‡₯1795a9a23c5919e1 2 56 1 116666aa 117473 18421 40878737 56759042 15744411 15665625 10.42.241.24
β‡₯1795a9a23c28493f 3 56 1 116666aa 119417 19180 59070590 59398475 189288 132438 10.42.241.1
β‡₯1795a9a23b66efe6 4 56 1 116666aa 569585 18709 67972981 69165724 604449 481875 158.36.144.49
β‡₯1795a9a24305dce5 5 56 1 116666aa 74164 13164 10927655 12438014 1423031 1370062 10.42.240.11
β‡₯1795a9a242fdee25 6 56 1 116666aa 74629 12132 11430786 12039303 521756 467438 158.36.84.53
β‡₯1795a9a242f3ae6c 7 56 1 116666aa 74315 11634 11205225 13171634 1880460 1787750 128.39.230.22
β‡₯1795a9a2426f70c5 8 96 1 116666aa 51574 9678 19737124 20904021 1105645 1060562 128.39.254.179
β‡₯1795a9a244849c7e 9 56 1 116666aa 93468 16452 15676158 16511633 725555 687625 128.39.254.79
β‡₯1795a9a2447bdf7e 10 56 1 116666aa 92733 15981 12837025 17723353 4777614 4718312 185.1.55.41
β‡₯1795a9a2447335b4 11 44 255 116666aa 85299 13915 16096643 17068626 872769 802375 1.1.1.1

Version 1

Version 1 was used before HiPerConTracer 2.0.0 and is now deprecated! However, it can still be read and processed by the HiPerConTracer Results Tool and the HiPerConTracer Importer Tool. While HiPerConTracer still can generate version 1 output, this is strongly discouraged due to limitations of this format version!

Traceroute format, version 1
#T sourceIP destinationIP timestamp round checksum totalHops statusFlags pathHash [traffic_class [packet_size]]
β‡₯hopNumber status rtt hopIP timesource [timesource]
β‡₯...
Traceroute fields, version 1
Traceroute Fields (Version 1)
Column Field Description
1 traceroute #T; HiPerConTracer <2.0 only provided ICMP Traceroute
2 sourceIP Source IP address
3 destinationIP Destination IP address
4 timestamp Timestamp (microseconds since the UTC epoch, hexadecimal) of the current run. Note: This timestamp is only an identifier for the Traceroute run. All Traceroute rounds of the same run use the same timestamp here!
5 round Round number (decimal)
6 checksum The checksum of the ICMP Echo Request packets (hexadecimal); 0x0000 for other protocols, 0xffff for unknown
7 totalHops Total hops (decimal)
8 statusFlags Status flags including the status code for Ping above for the lower 8 bits (hexadecimal)
9 pathHash Hash of the path (hexadecimal); see Path Hash
10 traffic_class The IP Traffic Class/Type of Service value of the sent packets (hexadecimal)
11 packet_size The sent packet size (decimal, in bytes) including IPv4/IPv6 header, transport header and HiPerConTracer header

For each hop:

Traceroute Hop Fields (Version 1)
Column Field Description
1 hopNumber Number of the hop
2 status Status code (in hexadecimal here)
3 rtt The measured RTT (microseconds, decimal)
4 hopIP Hop IP address
5 timesource Source of the timing information (hexadecimal) as AAQQSSHH; see Time Source

Notes:

Traceroute example, version 1
#T 192.168.0.88 8.8.8.8 5d2f2db8ecbb3 0 2be 12 200 ea86903f1fdb8faa 0 44
β‡₯1 1 9858 192.168.0.1
β‡₯2 1 18552 10.248.0.1
β‡₯3 1 18573 84.208.41.118
β‡₯4 1 18595 109.163.76.161
β‡₯5 1 18618 109.163.76.160
β‡₯6 1 18641 62.115.175.156
β‡₯7 1 24116 62.115.116.101
β‡₯8 1 24135 62.115.142.219
β‡₯9 1 24157 72.14.205.198
β‡₯10 1 24179 142.251.67.181
β‡₯11 1 18755 142.250.239.185
β‡₯12 ff 18863 8.8.8.8

Special Fields

Status Code and Status Flags

The status code provides the result of a Ping, i.e. whether the remote endpoint responded or there was a local or on-route error, as unsigned byte:

Status Codes
Status Code Description Meaning of the Corresponding RTT Value
1 ICMP/ICMPv6 response: Time Exceeded Response from router sending the ICMP error
100 ICMP/ICMPv6 response: Unreachable scope Response from router sending the ICMP error
101 ICMP/ICMPv6 response: Unreachable network Response from router sending the ICMP error
102 ICMP/ICMPv6 response: Unreachable host Response from router sending the ICMP error
103 ICMP/ICMPv6 response: Unreachable protocol Response from router sending the ICMP error
104 ICMP/ICMPv6 response: Unreachable port Response from router sending the ICMP error
105 ICMP/ICMPv6 response: Unreachable, prohibited (firewall) Response from router sending the ICMP error
110 ICMP/ICMPv6 response: Unreachable, unknown reason Response from router sending the ICMP error
200 Timeout (no response from a router) Timeout value configured for HiPerConTracer
210 sendto() call failed (generic error) RTT is set to 0
211 sendto() error: tried to send to broadcast address (EACCES) RTT is set to 0
212 sendto() error: network unreachable (ENETUNREACH) RTT is set to 0
213 sendto() error: host unreachable (HOSTUNREACH) RTT is set to 0
214 sendto() error: address not available (ADDRNOTAVAIL) RTT is set to 0
215 sendto() error: invalid message size (MSGSIZE) RTT is set to 0
216 sendto() error: not enough buffer space (NOBUFS) RTT is set to 0
255 Success (destination has responded) The actual RTT to the destination

The status flag extends the status code, by providing an overall result of a Traceroute run consisting of multiple Ping measurements. That is: StatusCode := (StatusFlags & 0xff).

Status Flags
Status Flag Description
0x100 Route with β€œ*” (at least one router did not respond; see also Path Hash)
0x200 Destination has responded

Time Source

The time source provides the source of the recorded timing information as hexadecimal 4-byte unsigned integer AAQQSSHH:

Time Source Components
Component Description
AA Application
QQ Queuing (queuing packet until sending it by driver, in software)
SS Software (sending request by driver until receiving response by driver)
HW Hardware (sending request by NIC until receiving response by NIC)

Each byte AA, QQ, SS, HH provides the receive time source (upper nibble) and send time source (lower nibble):

Time Source Values
Nibble Description
0x0 Not available
0x1 System clock
0x2 SO_TIMESTAMPING socket option, microseconds granularity
0x3 SO_TIMESTAMPINGNS socket option (or SO_TIMESTAMPING+SO_TS_CLOCK), nanoseconds granularity
0x4 SIOCGSTAMP ioctl, microseconds granularity
0x5 SIOCGSTAMPNS ioctl, nanoseconds granularity
0x6 SO_TIMESTAMPING socket option, in software, nanoseconds granularity
0xa SO_TIMESTAMPING socket option, in hardware, nanoseconds granularity

For details, particularly also see: Dreibholz, Thomas: Β«High-Precision Round-Trip Time Measurements in the Internet with HiPerConTracerΒ» (PDF, 12474 KiB, 7 pages, πŸ‡¬πŸ‡§), in Proceedings of the 31st International Conference on Software, Telecommunications and Computer Networks (SoftCOM), DOI 10.23919/SoftCOM58365.2023.10271612, ISBN 979-8-3503-0107-6, Split, Dalmacija/Croatia, September 22, 2023.

Path Hash

The path hash is an SHA-1 hash over the textual representation of a Traceroute run, i.e. SHA1(β€œ<Source IP>-<Router 1 IP>-<…>-<Router n IP>-<Destination IP>”), where the IP addresses correspond to source, destination, and routers. If a router is unknown, it is represented by β€œ*”. The purpose of the path hash is to quickly identify identical paths. In this case, of course, routers must have consistently responded (non-β€œ*”, i.e. revealing their IP address) or not responded (β€œ*”) to lead to the same hash value.

Results File Examples

Some simple results file examples (from src/results-examples):

Notes:

Further Details

See the manpage of β€œhipercontracer” for all options, including a description of the results file formats: 

man hipercontracer

πŸ“š The HiPerConTracer Viewer Tool

The HiPerConTracer Viewer Tool displays the contents of a results file.

Example

hpct-viewer src/results-examples/Traceroute-UDP-#88888888-fdb6:6d27:be73:4::50-20231018T102656.821891-000000001.hpct.xz

Further Details

See the manpage of β€œhpct-viewer” for a detailed description of the available options: 

man hpct-viewer

πŸ“š The HiPerConTracer Results Tool

The HiPerConTracer Results Tool provides merging and converting data from results files, e.g. to create a Comma-Separated Value (CSV) file.

Example 1

Merge the data from all files matching the pattern Ping*.hpct.* into CSV file ping.csv.gz, with β€œ,” as separator: 

find data -maxdepth 1 -name "Ping*.hpct.*" | \
   hpct-results --input-file-names-from-stdin --separator=, -o ping.csv.gz

Hint: You can use the extension .gz for GZip, .bz2 for BZip2, .xz for XZ, .zst for ZSTD, or none for uncompressed output into the output CSV file!

Example 2

Merge the data from all files matching the pattern Traceroute*.hpct.* into CSV file traceroute.csv.xz, with β€œ;” as separator: 

find data -maxdepth 1 -name "Traceroute*.hpct.*" | \
   hpct-results --input-file-names-from-stdin --separator=; -o traceroute.csv.xz

Further Details

See the manpage of β€œhpct-results” for a detailed description of the available options: 

man hpct-results

πŸ“š Processing Results for Analysis

The directory src/results-examples contains some example results files, as well as some example scripts for reading them and computing some statistics.

GNU R

The GNU R examples need, in addition to GNU R, some libraries. See src/results-examples/r-install-dependencies to get the necessary library packages installed from the Comprehensive R Archive Network (CRAN)!

Alternatively:

Example for Ping Results Processing in R

See r-ping-example for the script, and src/results-examples for some example results files! The Ping example creates a statistical summary table for each Measurement ID / Source IP / Destination IP / Protocol relation found in the given input results file(s).

Usage: 

./r-ping-example <input> <output_prefix>

Example for Traceroute Results Processing in R

See r-traceroute-example for the script, and src/results-examples for some example results files! The Traceroute example simply counts the number of HiPerConTracer Traceroute runs for each Measurement ID / Source IP / Destination IP / Protocol relation found in the given input results file(s).

Usage: 

./r-traceroute-example <input>

LibreOffice (or any similar spreadsheet program)

Import CSV file into spreadsheet.

Hints:

πŸ—ƒοΈ Setting Up a Database for Results Collection

See src/SQL and src/NoSQL for schema, user and permission setups. Create the database of your choice (MariaDB/MySQL, PostgreSQL, or MongoDB).

Use separate users for importer (import access only), researcher (read-only access to the data) and maintainer (full access), for improved security.

Hint: The HiPerConTracer tools support Transport Layer Security (TLS) configuration. It is strongly recommended to properly setup TLS for secure access to a database!

See src/TestDB as example. This is the CI test, which includes a full database setup and test cycle with all supported database backends. Of course, this setup also includes proper TLS setup as well.

πŸ“š The HiPerConTracer Importer Tool

The HiPerConTracer Importer Tool provides the continuous storage of collected measurement data from results files into SQL or NoSQL databases. Currently, database backends for MariaDB/MySQL, PostgreSQL and MongoDB are provided.

Write Configuration Files for the Importer

See src/hipercontracer-importer.conf (importer configuration) and src/hipercontracer-database.conf (database configuration) for examples. Make sure that the database access details are correct, so that Importer Tool and Query Tool can connect to the right database and has the required permissions! See src/SQL and src/NoSQL for schema, user and permission setups. Use the HiPerConTracer Database Shell tool to verify and debug access.

Note: Make sure the data directory, as well as the directory for good imports and the directory for bad (i.e. failed) imports are existing and accessible by the user running the importer!

Run the Importer Tool

Example 1

Just run one import round, quit when there are no more files to import: 

hpct-importer \
   --importer-config hipercontracer-importer.conf \
   --database-config hipercontracer-database.conf \
   --verbose \
   --quit-when-idle

Example 2

Continuously run, waiting for new files to import: 

hpct-importer \
   --importer-config hipercontracer-importer.conf \
   --database-config hipercontracer-database.conf \
   --verbose

Note: If running without --quit-when-idle (recommended), the importer keeps running and imports new files as soon as they appear in the results directory. The importer uses INotify!

Further Details

See the manpage of β€œhpct-importer” for a detailed description of the available options: 

man hpct-importer

πŸ“š The HiPerConTracer Query Tool

Write a Configuration File for the Query Tool

See src/hipercontracer-database.conf for an example. Make sure that the database access details are correct, so that the Query tool can connect to the right database and has the required permissions! See src/SQL and src/NoSQL for schema, user and permission setups. Use the HiPerConTracer Database Shell tool to verify and debug access.

Run the Query Tool

Example 1

Export all Ping data to ping.hpct.gz (GZip-compressed data file): 

hpct-query ~/testdb-users-mariadb-researcher.conf ping -o ping.hpct.gz

Notes:

Example 2

Export all Ping data of Measurement ID #1000 to ping.hpct.gz (GZip-compressed data file): 

hpct-query ~/testdb-users-mariadb-researcher.conf \
   ping -o ping.hpct.gz \
   --from-measurement-id 1000 --to-measurement-id 1000

Example 3

Export all Traceroute data of Measurement ID #1000 to traceroute.hpct.bz2 (BZip2-compressed data file), with verbose logging: 

hpct-query ~/testdb-users-mariadb-researcher.conf \
   traceroute -o traceroute.hpct.bz2 --loglevel 0 \
   --from-measurement-id 1000 --to-measurement-id 1000

Example 4

Export all Traceroute data from 2023-09-22 00:00:00 to traceroute.hpct.xz (XZ-compressed data file), with verbose logging: 

hpct-query ~/testdb-users-mariadb-researcher.conf \
   traceroute -o traceroute.hpct.xz --verbose \
   --from-time "2023-09-22 00:00:00"

Example 5

Export all Traceroute data from time interval [2023-09-22 00:00:00, 2023-09-23 00:00:00) to traceroute.hpct.xz (XZ-compressed data file): 

hpct-query ~/testdb-users-mariadb-researcher.conf \
   traceroute -o traceroute.hpct.xz --verbose \
   --from-time "2023-09-22 00:00:00" --to-time "2023-09-23 00:00:00"

Note: data for time stamp 2023-09-23 00:00:00 will not be included, only data for time stamps less than 2023-09-23 00:00:00, i.e. data within the time interval [to-time, from-time). This ensures the possibility to e.g. export daily batches without having the same value included in two files!

Further Details

See the manpage of β€œhpct-query” for a detailed description of the available options: 

man hpct-query

πŸ“š The HiPerConTracer Sync Tool

The HiPerConTracer Sync Tool helps synchronising collected results files from a vantage point (denoted as HiPerConTracer Node) to a collection server (denoted as HiPerConTracer Collector), using RSync/SSH.

For information about the necessary underlying directory structure and file permissions, see Recommended Directory Structure and File Permissions. In case of problems, a misconfiguration of these is the most likely issue!

Example

Synchronise results files, with the following settings: 

sudo -u hipercontracer hpct-sync \
   --nodeid 1000 \
   --collector sognsvann.domain.example \
   --local /var/hipercontracer --remote /var/hipercontracer \
   --key /var/hipercontracer/ssh/id_ed25519 \
   --known-hosts /var/hipercontracer/ssh/known_hosts --verbose

Further Details

See the manpage of β€œhpct-sync” for a detailed description of the available options: 

man hpct-sync

πŸ“š The HiPerConTracer Reverse Tunnel Tool

The HiPerConTracer Reverse Tunnel (RTunnel) Tool maintains a reverse SSH tunnel from a remote HiPerConTracer Node to a HiPerConTracer Collector server. The purpose is to allow for SSH login from the Collector server to the Node, via this reverse tunnel. Then, the Node does not need a publicly-reachable IP address (e.g. a Node only having a private IP address behind a NAT/PAT firewall).

For information about the necessary underlying directory structure and file permissions, see Recommended Directory Structure and File Permissions. In case of problems, a misconfiguration of these is the most likely issue!

Example

Establish a Reverse Tunnel, with the following settings: 

sudo -u hipercontracer hpct-rtunnel \
   --nodeid 1000 --collector 10.44.35.16 \
   --key /var/hipercontracer/ssh/id_ed25519 \
   --known-hosts /var/hipercontracer/ssh/known_hosts

On the Collector, to connect to Node 1000: 

hpct-ssh <USER>@1000

Further Details

See the manpage of β€œhpct-rtunnel” for a detailed description of the available options for hpct-rtunnel: 

man hpct-rtunnel

Also see the manpage of β€œhpct-ssh” for a detailed description of the available options for hpct-ssh: 

man hpct-ssh

πŸ“š The HiPerConTracer Collector/Node Tools

The HiPerConTracer Collector/Node Tools are some scripts for simplifying the setup of Nodes and a Collector server. Mainly, they ensure the creation of Node configurations on the Collector, and corresponding setup of HiPerConTracer Sync Tool and HiPerConTracer Reverse Tunnel.

See the manpages of these tools for further details!

For information about the necessary underlying directory structure and file permissions, see Recommended Directory Structure and File Permissions. In case of problems, a misconfiguration of these is the most likely issue!

πŸ“š The HiPerConTracer Trigger Tool

The HiPerConTracer Trigger Tool triggers HiPerConTracer measurements in the reverse direction, when a given number of Pings having a given size reaching the local node.

Example

Queue a received Ping’s sender address after having received 2 Pings of 88 bytes for a Traceroute measurement from 10.1.1.51, run as user hipercontracer and use results directory β€œ/var/hipercontracer”: 

sudo hpct-trigger \
   --user hipercontracer \
   --source 10.1.1.51 \
   --resultsdirectory=/var/hipercontracer \
   --traceroute \
   --triggerpingsbeforequeuing 2 --triggerpingpacketsize 88 \
   --verbose

Further Details

See the manpage of β€œhpct-trigger” for a detailed description of the available options: 

man hpct-trigger

πŸ“š The HiPerConTracer Database Shell

The HiPerConTracer Database Shell (DBShell) is a simple tool to test a database configuration file by running a database client with the settings from the file. It then provides an interactive shell for the database.

Example 1

Connect to the database, using the configuration from β€œhipercontracer-importer.conf”: 

dbshell hipercontracer-importer.conf

Example 2

As Example 1, but also export the database configuration as DBeaver configuration files (JSON for database, plain-text JSON for user credentials) with the prefix β€œdbeaver-config”: 

dbshell hipercontracer-database.conf --write-dbeaver-config dbeaver-config

Further Details

See the manpage of β€œdbshell” for a detailed description of the available options: 

man dbshell

πŸ“š The HiPerConTracer Database Tools

The HiPerConTracer Database Tools are some helper scripts to e.g. join HiPerConTracer database configurations into an existing DBeaver configuration:

See the manpages of these tools for further details!

πŸ“š The HiPerConTracer UDP Echo Server

The HiPerConTracer UDP Echo Server provides an UDP Echo (RFC 862) service, particularly as endpoint of HiPerConTracer Ping and Traceroute measurements over UDP.

Important security notes:

Example 1

Start UDP Echo server on port 7777: 

udp-echo-server --port 7777

A corresponding HiPerConTracer Ping measurement via UDP to this server could be run like: 

sudo hipercontracer -D <SERVER_ADDRES> -M UDP --ping --verbose --pingudpdestinationport 7777

Example 2

Start UDP Echo server on port 7 as user hipercontracer: 

sudo udp-echo-server --user hipercontracer --port 7

Further Details

See the manpage of β€œudp-echo-server” for a detailed description of the available options: 

man udp-echo-server

🦈 Wireshark Dissector for HiPerConTracer Packets

The Wireshark network protocol analyzer provides built-in support for the HiPerConTracer packet format. This support is already included upstream, i.e. Wireshark provides it out-of-the-box.

πŸ–‹οΈ Citing HiPerConTracer in Publications

HiPerConTracer BibTeX entries can be found in hipercontracer.bib!

πŸ“– Publications

The collected BibTeX references in a single file are available as: BiBTeX file, XML file, ODT file, DOCX file. These lists were generated using BibTeXCov 2.0!

2026

2025

2024

2023

2022

2020

2014

©️ 13.03.2026 Thomas Dreibholz, Simula Research Laboratory / Center for Resilient Networks and Applications / NorNet

Valid XHTML 1.1! Valid CSS!