https://www.nntb.no/~dreibh/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:
- multi-transport-protocol support (ICMP, UDP);
- multi-homing and parallelism support;
- handling of load balancing in the network;
- multi-platform support (currently Linux and FreeBSD);
- high-precision (nanoseconds) timing support (Linux timestamping, both software and hardware);
- a library (shared/static) to integrate measurement functionality into other software (libhipercontracer);
- open source and written in a performance- and portability-focused programming language (C++) with only limited dependencies.
Furthermore, the HiPerConTracer Framework provides additional tools for helping to obtain, process, collect, store, and retrieve measurement data:
- HiPerConTracer Viewer Tool for displaying the contents of results files;
- HiPerConTracer Results Tool for merging and converting results files, e.g. to create a Comma-Separated Value (CSV) file;
- HiPerConTracer Sync Tool for copying data from a measurement node (vantage point) to a remote HiPerConTracer Collector server (via RSync/SSH);
- HiPerConTracer Reverse Tunnel Tool for maintaining a reverse SSH tunnel from a remote measurement node to a HiPerConTracer Collector server;
- HiPerConTracer Collector/Node Tools for simplifying the setup of HiPerConTracer Nodes and a HiPerConTracer Collector server;
- HiPerConTracer Trigger Tool for triggering HiPerConTracer measurements in the reverse direction;
- HiPerConTracer Importer Tool for storing measurement data from results files into SQL or NoSQL databases. Currently, database backends for MariaDB/MySQL, PostgreSQL and MongoDB are provided;
- HiPerConTracer Query Tool for querying data from a database and storing it into a results file;
- HiPerConTracer Database Shell as simple command-line front-end for the underlying database backends;
- HiPerConTracer Database Tools with some helper scripts to e.g. to join HiPerConTracer database configurations into an existing DBeaver (a popular SQL database GUI application) configuration;
- HiPerConTracer UDP Echo Server as UDP Echo (RFC 862) protocol endpoint;
- Wireshark dissector for HiPerConTracer packets.
Also see the HiPerConTracer Homepage for details!
See Binary Package Installation for ready-to-use binary package installation from repositories for:
- Ubuntu Linux (via Launchpad PPA)
- Fedora Linux (via COPR PPA)
- FreeBSD (via Ports Collection)
Basic procedure:
cmake .
make
sudo make install
Notes:
- There are various CMake options to enable/disable database backends and tools. A GUI tool like CCMake provides a comfortable way of configuration.
- The CMake run will show missing dependencies, and provide help for installing them on Debian, Ubuntu and Fedora Linux as well as on FreeBSD.
HiPerConTracer is the measurement tool itself.
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
Run HiPerConTracer measurement #1000000, from arbitrary local IPv4 address to destination 193.99.144.80, 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:
- Run HiPerConTracer as a non-privileged user ("--user" option). HiPerConTracer only needs superuser permissions to create the raw sockets.
- HiPerConTracer uses the sub-directory "data" (provided by "--resultsdirectory") to write the results files to. This directory must be writable for the user $USER!
- See the manpage of "hipercontracer" for various options to set Ping and Traceroute intervals, results file lengths, results file compression, etc.!
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
Some simple results file examples (from src/results-examples):
- HiPerConTracer ICMP Ping over IPv4
- HiPerConTracer ICMP Ping over IPv6
- HiPerConTracer ICMP Traceroute over IPv4
- HiPerConTracer ICMP Traceroute over IPv6
Notes:
- See the manpage of "hipercontracer" for a detailed description of the results file formats:
man hipercontracer - The HiPerConTracer Viewer Tool can be used to display results files, including uncompressed ones.
- The HiPerConTracer Results Tool can be used to merge and/or convert the results files.
See the manpage of "hipercontracer" for all options, including a description of the results file formats:
man hipercontracer
The HiPerConTracer Viewer Tool displays the contents of a results file.
hpct-viewer src/results-examples/Traceroute-UDP-#88888888-fdb6:6d27:be73:4::50-20231018T102656.821891-000000001.results.xz
See the manpage of "hpct-viewer" for a detailed description of the available options:
man hpct-viewer
The HiPerConTracer Results Tool provides merging and converting data from results files, e.g. to create a Comma-Separated Value (CSV) file.
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, or none for uncompressed output into the output CSV file!
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
See src/results-examples for some examples.
See src/results-examples/r-install-dependencies to get the necessary library packages installed!
- r-ping-example ping.csv
- r-traceroute-example traceroute.csv.gz
Import CSV file into spreadsheet.
Hints:
- Use English (US) language, to avoid strange number conversions.
- Choose column separator (" ", ",", etc.), if not automatically detected.
See the manpage of "hpct-results" for a detailed description of the available options:
man hpct-results
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 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.
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!
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
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!
See the manpage of "hpct-importer" for a detailed description of the available options:
man hpct-importer
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.
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:
- Make sure to specify a Measurement ID range, or a time range. Otherwise, the Query tool will export everything!
- The output is in the same format as the originally written HiPerConTracer results. See the manpage of "hipercontracer" for all options, including a description of the results file formats:
man hipercontracer - You can use the extension .gz for GZip, .bz for BZip2, .xz for XZ, or none for uncompressed output!
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
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
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"
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!
See the manpage of "hpct-query" for a detailed description of the available options:
man hpct-query
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.
Synchronise results files, with the following settings:
- local node is Node 1000;
- run as user "hipercontracer";
- from local directory /var/hipercontracer;
- to remote server's directory /var/hipercontracer (here, the data is going to be stored in sub-directory "1000");
- remote server is sognsvann.domain.example (must be a resolvable hostname);
- private key for logging into the remote server via SSH is in /var/hipercontracer/ssh/id_ed25519;
- known_hosts file for SSH is /var/hipercontracer/ssh/known_hosts;
- run with verbose output
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
See the manpage of "hpct-sync" for a detailed description of the available options:
man hpct-sync
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).
Establish a Reverse Tunnel, with the following settings:
- local node is Node 1000;
- run as user "hipercontracer";
- connect to Collector server 10.44.35.16;
- using SSH private key from /var/hipercontracer/ssh/id_ed25519;
- with SSH known_hosts file /var/hipercontracer/ssh/known_hosts
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
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 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.
- hpct-node-setup (on a Node): Connect the node to a Collector.
- hpct-nodes-list (on the Collector): List connected nodes, together with status information about last data synchronisation and reverse tunnel setup.
- hpct-node-removal (on the Collector): Remove a node from the Collector.
See the manpages of these tools for further details!
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.
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
See the manpage of "hpct-trigger" for a detailed description of the available options:
man hpct-trigger
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.
Connect to the database, using the configuration from "hipercontracer-importer.conf":
dbshell hipercontracer-importer.conf
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
See the manpage of "dbshell" for a detailed description of the available options:
man dbshell
The HiPerConTracer Database Tools are some helper scripts to e.g. join HiPerConTracer database configurations into an existing DBeaver configuration:
- make-dbeaver-configuration: Make DBeaver configuration from HiPerConTracer database configuration files, with possibility to join with an existing DBeaver configuration
- encrypt-dbeaver-configuration: Encrypt DBeaver credentials configuration file
- decrypt-dbeaver-configuration: Decrypt DBeaver credentials configuration file
See the manpages of these tools for further details!
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:
- The UDP Echo Server only responds to source ports >= 1024, to avoid using the server in attacks, like spoofing a packet from another Echo server (port 7) to create a flooding loop.
- Also, packets from the same port as the listening port are ignored!
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_ADDRESS> -M UDP --ping --verbose --pingudpdestinationport 7777
Start UDP Echo server on port 7 as user "hipercontracer":
sudo udp-echo-server --user hipercontracer --port 7
See the manpage of "udp-echo-server" for a detailed description of the available options:
man udp-echo-server
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.
HiPerConTracer BibTeX entries can be found in src/hipercontracer.bib!
- Dreibholz, Thomas: HiPerConTracer - A Versatile Tool for IP Connectivity Tracing in Multi-Path Setups, in Proceedings of the 28th IEEE International Conference on Software, Telecommunications and Computer Networks (SoftCOM), pp. 1–6, DOI 10.23919/SoftCOM50211.2020.9238278, ISBN 978-953-290-099-6, Hvar, Dalmacija/Croatia, September 17, 2020.
- Dreibholz, Thomas: High-Precision Round-Trip Time Measurements in the Internet with HiPerConTracer, 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.