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

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 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.results.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, .bz 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:

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:

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!

2025

2024

2023

2022

2020

2014