hipercontracer(1)

📦
version 2.2.10 · 4 versions
, in ubuntu stonking

✨ NAME ✨

okay bestie, welcome to the hipercontracer(1) manual page, you're gonna slay this 💅

  • hipercontracer — High-Performance Connectivity Tracer (HiPerConTracer)

🎀 SYNOPSIS 🎀

here's literally every way you can call this icon. copy these exactly, no cap, character for character 👑

       hipercontracer [-P | --ping]
                      [-T | --traceroute] [-L level | --loglevel level]
                      [-Z on|off | --logcolor on|off]
                      [-O file | --logfile file]
                      [-q | --quiet] [-w | --verbose]
                      [-U user|uid | --user user|uid]
                      [-# identifier | --measurement-id identifier]
                      [-S address|‐
                      hostname[,traffic_class[,...]] | --source address|‐
                      hostname[,traffic_class[,...]]]
                      [-D address|hostname | --destination address|hostname]
                      [--sources-from-file file]
                      [--destinations-from-file file]
                      [-M ICMP|UDP | --iomodule ICMP|UDP]
                      [-I number_of_iterations | --iterations number_of_‐
                      iterations]
                      [--tracerouteinterval milliseconds]
                      [--tracerouteintervaldeviation fraction]
                      [--tracerouteduration milliseconds]
                      [--tracerouterounds rounds]
                      [--tracerouteinitialmaxttl value]
                      [--traceroutefinalmaxttl value]
                      [--tracerouteincrementmaxttl value]
                      [--traceroutepacketsize bytes]
                      [--tracerouteudpsourceport port]
                      [--tracerouteudpdestinationport port]
                      [--pinginterval milliseconds]
                      [--pingintervaldeviation fraction]
                      [--pingexpiration milliseconds]
                      [--pingburst packets]
                      [--pingttl value]
                      [--pingpacketsize bytes]
                      [--pingudpsourceport port]
                      [--pingudpdestinationport port]
                      [-R directory | --resultsdirectory directory]
                      [-x seconds | --resultstransactionlength seconds]
                      [-C none|XZ|BZip2|GZip|ZLIB|‐
                      ZSTD | --resultscompression none|XZ|BZip2|GZip|ZLIB|ZSTD]
                      [-F version | --resultsformat version]
                      [-z depth | --resultstimestampdepth depth]
       hipercontracer [--check]
       hipercontracer [-h | --help]
       hipercontracer [-v | --version]

🦋 DESCRIPTION 🦋

so like, <pink>hipercontracer</pink> is a Ping/Traceroute service, periodt. 💖 It performs regular Ping and Traceroute runs among sites, and it can export the results into results statements for import into a database. it's giving very much "network diagnostics but make it scheduled and database-ready" energy, and we're obsessed 🫶

💅 ARGUMENTS 💅

okay bestie, here comes the whole menu — every flag, every value, every default, nothing left out. buckle up 🎀

  • -P, --ping — spins up the Ping service. that's it, that's the whole job ✨
  • -T, --traceroute — spins up the Traceroute service. iconic behavior honestly 💅
  • -L level, --loglevel level — sets the minimum logging level to whatever you hand it: 0=trace, 1=debug, 2=info, 3=warning, 4=error, 5=fatal. lower number = more yapping 📢
  • -Z on|off, --logcolor on|off — turns ANSI color escape sequences on or off so your log output gets colored by level. cute but optional 🌈
  • -O file, --logfile file — names a file to append the log output to. heads up: once a file is set, no log output goes to the console at all. if you don't set one, everything goes to the console 🍓
  • -q, --quiet — shortcut that slams the minimum logging level to 3 (warning). shhh mode 🤫
  • -w, --verbose — shortcut that drops the minimum logging level all the way to 0 (trace). tell me EVERYTHING 😭
  • -U user|uid, --user user|uid — after startup, HiPerConTracer takes on the UID and GID of the user you name (by name or by GID). the output directory's ownership and the ownership of the results files it creates get set to match 👑
  • -# identifier, --measurement-id identifier — sets a unique measurement identifier for the run. every output file gets this identifier baked into its filename as #<ID>. super useful for a setup-wide unique vantage-point id. if you don't set one, files carry the process ID instead, as P<ID>. range: 0-2147483647. default: 0 (which means "use the process ID instead") 🔖
  • -S address|hostname[,traffic_class[,...]], --source address|hostname[,traffic_class[,...]] — adds the given source address or hostname. the ANY address (0.0.0.0 or ::) is fair game if you just wanna use the default route. no traffic class given? then Best Effort (00) is what you get. otherwise the list of traffic classes you gave (in hexadecimal) is used. you can also name the traffic class by PHB name: BE, EF, AF11, AF12, AF13, AF21, AF22, AF23, AF31, AF32, AF33, AF41, AF42, AF43, CS1, CS2, CS3, CS4, CS5, CS6, CS7 — and in that case the matching traffic class is used with ECN bits set to 0. give a hostname and a DNS resolution happens, with all returned addresses added. and if you provide no source address at all, HiPerConTracer auto-adds 0.0.0.0 when there's an IPv4 destination, and :: when there's an IPv6 destination 🦋
⚠️ Note: use lower-case hexadecimal letters so you don't get tangled up with PHB names (like be for 0xbe instead of the BE PHB)! iykyk 💀
  • -D address|hostname, --destination address|hostname — adds the given destination address or hostname. hostname means DNS resolution, and every returned address gets added 🎯
  • --sources-from-file file — reads sources from the given file. can be used multiple times to pull from multiple files 📂
  • --destinations-from-file file — reads destinations from the given file. also repeatable, also multiple files 🗂️
  • -M ICMP|UDP, --iomodule ICMP|UDP — adds an I/O module: ICMP or UDP. yes you can pass it multiple times with different modules 🧚
  • -I number_of_iterations, --iterations number_of_iterations — caps the number of measurement iterations (one iteration = measuring all source/destination pairs) at the number you give. the default 0 lets HiPerConTracer run forever, continuously, no cap, no chill 😌
  • --tracerouteinterval milliseconds — sets the Traceroute interval, i.e. how long each full round of destinations takes ⏱️
  • --tracerouteintervaldeviation fraction — randomly deviates the Traceroute interval by the given fraction (as 0.0 to 1.0), so it picks from [interval - fraction * interval, interval + fraction * interval], all to dodge synchronisation effects. default is 0.1 (10%) 🎲
  • --tracerouteduration milliseconds — sets the Traceroute duration: the timeout for each destination ⏳
  • --tracerouterounds rounds — for each Traceroute measurement, run that many rounds simultaneously. default is 1 round. range: 1-64. every TTL test within a round shares the same ICMP checksum value ("Oslo Traceroute") so we can survive load balancing on the Internet. different rounds get different checksums — meaning different rounds may take different paths through the network. chaos, but make it scientific 🔥
  • --tracerouteinitialmaxttl value — start with this maximum TTL. default is 6 🚀
  • --traceroutefinalmaxttl value — finish with this maximum TTL (used when the destination still isn't reached at the current TTL setting). default is 36 🏁
  • --tracerouteincrementmaxttl value — bump the maximum TTL up by this much (again, when the destination isn't reached at the current TTL setting). default is 6 📈
  • --traceroutepacketsize bytes — sets the Traceroute packet size, which is IP header (20 for IPv4 / 40 for IPv6) + ICMP header (8) / UDP header (8) + HiPerConTracer header (16) + payload, in bytes. the packet actually sent always covers at least the headers for IPv4/IPv6, ICMP, and HiPerConTracer. maximum packet size is 65535 📦
  • --tracerouteudpsourceport port — sets the Traceroute source port for the UDP module (default: 0, meaning automatic allocation).
🛑 Note: if you're using a fixed UDP port for Traceroute, you must use different UDP source ports for any other services!
  • --tracerouteudpdestinationport port — sets the Traceroute destination port for the UDP module (default: 7, for Echo) 📮
  • --pinginterval milliseconds — sets the Ping interval (the time for each full round of destinations). default is 5000 ms ⏲️
  • --pingintervaldeviation fraction — randomly deviates the Ping interval by the given fraction (as 0.0 to 1.0), choosing out of [interval - fraction * interval, interval + fraction * interval] to avoid synchronisation effects. default is 0.1 (10%) 🎰
  • --pingexpiration milliseconds — sets the Ping duration: the timeout for each destination. default is 10000 ms 🕐
  • --pingburst packets — for each Ping measurement, fire a burst of that many packets. default is 1 packet. range: 1-1024 💥
  • --pingttl value — sets the Ping TTL value. default is 64. range: 1-255 🛣️
  • --pingpacketsize bytes — sets the Ping packet size, which is IP header (20 for IPv4 / 40 for IPv6) + ICMP header (8) / UDP header (8) + HiPerConTracer header (16) + payload, in bytes. the packet actually sent always covers at least the headers for IPv4/IPv6, the transport protocol, and HiPerConTracer. default is 0 (use the minimum possible value). range: 0-65535 📐
  • --pingudpsourceport port — sets the Ping source port for the UDP module (default: 0, for automatic allocation).
🛑 Note: same deal as before — if you use a fixed UDP port for Ping, any other services need different UDP source ports!
  • --pingudpdestinationport port — sets the Ping destination port for the UDP module (default: 7, for Echo) 📬
  • -R directory, --resultsdirectory directory — sets the directory where the results files live. if you don't specify it, the results get stored... well, that's the deal 🏠
  • -x seconds, --resultstransactionlength seconds — after the given number of seconds, crack open a brand new results file 🔄
  • -C none|XZ|BZip2|GZip|ZLIB|ZSTD, --resultscompression none|XZ|BZip2|GZip|ZLIB|ZSTD — sets the compression for the output files. default: XZ 🗜️
  • -F version, --resultsformat version — sets the results file format version. default: 2 (the current version). range (currently): 1-2.
👀 Note: a future version of HiPerConTracer may bump this default setting up!
  • -z depth, --resultstimestampdepth depth — builds a timestamp-based directory hierarchy for the results, of the given depth (default: 0). 0 = none, 1 = year, 2 = year/month, 3 = year/month/day, 4 = year/month/day/hour:00, 5 = year/month/day/hour:00/hour:minute 🗓️
  • --check — prints build environment info for debugging 🔍
  • -h, --help — prints command help. the classic 🫶
  • -v, --version — prints the program version 🏷️

📄 OUTPUT FORMAT 📄

the output file is a text file (possibly compressed, see above). the format depends on the measurement type, and it goes a little something like this:

🩷 Format identifier in first line 🩷

#? HPCT format version program
  • format: the format of the output data (Ping, Traceroute, etc.) 🧾
  • version: the version of the output data format (decimal) 🔢
  • program: the identifier for the program generating the output, e.g. HiPerConTracer/2.1.12 🖥️

🩵 Ping (version 2, current) 🩵

each Ping entry is a #P<m> line, where m=i for ICMP and m=u for UDP (matching the underlying I/O module) 💫

#P<m> 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
  • measurementID: the measurement identifier 🔖
  • sourceIP: the source IP address 📍
  • destinationIP: the destination IP address 🎯
  • sendTimestamp: the send timestamp (nanoseconds since the UTC epoch, hexadecimal) ⏱️
  • burstseq: the sequence number within a burst (decimal), numbered from 0 🔢
  • traffic_class: the IP Traffic Class / Type of Service value of the sent packets (hexadecimal) 🚦
  • packet_size: the sent packet size (decimal, in bytes), including the IPv4/IPv6 header, the transport header, and the HiPerConTracer header 📦
  • response_size: the response packet size (decimal, in bytes), including the IPv4/IPv6 header, the transport header, and the HiPerConTracer header 📬
  • checksum: the checksum of the ICMP Echo Request packets (hexadecimal); 0x0000 for other protocols, 0xffff for unknown 🧮
  • sourcePort: the source port, 0 for ICMP (decimal) 🔌
  • destinationPort — the destination port, babes 💅 it's 0 for ICMP, and it's written in decimal.
  • status — the status code, decimal. Here's the whole mood board fr:
    • 1 = ICMP response: Time Exceeded ⏰
    • 100 = ICMP response: Unreachable scope
    • 101 = ICMP response: Unreachable network
    • 102 = ICMP response: Unreachable host
    • 103 = ICMP response: Unreachable protocol
    • 104 = ICMP response: Unreachable port
    • 105 = ICMP response: Unreachable, prohibited (firewall) 🚫
    • 110 = ICMP response: Unreachable, unknown reason
    • 200 = Timeout (no response from a router) 💀
    • 210 = sendto() call failed (generic error)
    • 211 = sendto() error: tried to send to broadcast address (EACCES)
    • 212 = sendto() error: network unreachable (ENETUNREACH)
    • 213 = sendto() error: host unreachable (EHOSTUNREACH)
    • 214 = sendto() error: address not available (EADDRNOTAVAIL)
    • 215 = sendto() error: invalid message size (EMSGSIZE)
    • 216 = sendto() error: not enough buffer space (ENOBUFS)
    • 255 = Success (destination has responded) ✨

Status values from 100 to 199 denote unreachability, as reported by an ICMP error from a router, bestie. The rtt_* fields contain the response time of the corresponding router. Status values from 200 to 254 have the destination IP in their destinationIP field. However, there was no response from a router, so the rtt_* fields will be the configured timeout value (on timeout) or the send trial time (on send errors)! 😭

  • timesource — where the timing tea actually came from, hexadecimal, formatted as: AAQQSSHH 🫶
    • AA: Application
    • QQ: Queuing (queuing packet until sending it by driver, in software)
    • SS: Software (sending request by driver until receiving response by driver, in software; decimal, in nanoseconds; -1 if not available)
    • HW: Hardware (sending request by NIC until receiving response by NIC, in hardware; decimal, in nanoseconds; -1 if not available)

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

  • 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
  • delay_app_send — the measured application send delay (nanoseconds, decimal; -1 if not available).
  • delay_queuing — the measured kernel software queuing delay (nanoseconds, decimal; -1 if not available).
  • delay_app_receive — the measured application receive delay (nanoseconds, decimal; -1 if not available).
  • rtt_app — the measured application RTT (nanoseconds, decimal).
  • rtt_sw — the measured kernel software RTT (nanoseconds, decimal; -1 if not available).
  • rtt_hw — the measured kernel hardware RTT (nanoseconds, decimal; -1 if not available).

🕰️ Ping (version 1, SUPERSEDED!)

Okay so this is the old one, the ancestor, the lowkey vintage era 🙈 Every Ping entry is exactly one #P line. That's it, that's the whole vibe.

#P sourceIP destinationIP timestamp checksum status rtt [traffic_class [packet_size [timesource]]]
  • sourceIP — source IP address.
  • destinationIP — destination IP address.
  • timestamp — timestamp (microseconds since the UTC epoch, hexadecimal).
  • checksum — the checksum of the ICMP Echo Request packets (hexadecimal).
  • status — status code (decimal).
  • rtt — the measured RTT (microseconds, decimal).
  • traffic_class — the outgoing IP Traffic Class/Type of Service value of the sent packets (hexadecimal). This entry has been added with HiPerConTracer 1.4.0! ✨
  • packet_size — the sent packet size (decimal, in bytes) including IPv4/IPv6 header, transport header and HiPerConTracer header. This entry has been added with HiPerConTracer 1.6.0!
  • timesource — source of the timing information (hexadecimal) as: AA (same as for Ping, see above). This entry has been added with HiPerConTracer 2.0.0 development versions! 🧚

🌈 Traceroute (version 2, current)

This is the one we actually stan, the current era, the main character 💅 Each Traceroute entry begins with a #Tm line, with m=i for ICMP and m=u for UDP (according to the underlying I/O module). Then it's followed with one TAB-started line per each hop, okay?

#T<m> measurementID sourceIP destinationIP timestamp round totalHops traffic_class packet_size checksum sourcePort destinationPort statusFlags pathHash
  • measurementID — measurement identifier.
  • sourceIP — source IP address.
  • destinationIP — destination IP address.
  • timestamp — timestamp (nanoseconds 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! The actual send timestamp of the request to each hop can be found in sendTimeStamp of the corresponding hop! 🔍
  • round — round number (decimal).
  • totalHops — total hops (decimal).
  • traffic_class — the IP Traffic Class/Type of Service value of the sent packets (hexadecimal).
  • packet_size — the sent packet size (decimal, in bytes) including IPv4/IPv6 header, transport header and HiPerConTracer header.
  • checksum — the checksum of the ICMP Echo Request packets (hexadecimal); 0x0000 for other protocols, 0xffff for unknown.
  • sourcePort — source port, 0 for ICMP (decimal).
  • destinationPort — destination port, 0 for ICMP (decimal).
  • statusFlags — status flags (hexadecimal). See the status code for Ping above for the lower 8 bits. Additionally:
    • 0x100 = Route with * (at least one router did not respond)
    • 0x200 = Destination has responded ✨
  • pathHash — hash of the path (hexadecimal).

Then each hop line looks like this:

(TAB) sendTimeStamp hopNumber response_size status timesource delay_queuing delay_app_receive rtt_app rtt_app rtt_sw rtt_hw hopIP
  • sendTimeStamp — timestamp (nanoseconds since the UTC epoch, hexadecimal) for the request to this hop.
  • hopNumber — number of the hop.
  • response_size — the response packet size (decimal, in bytes) including IPv4/IPv6 header, transport header and HiPerConTracer header.
  • status — status code (decimal; the values are the same as for Ping, see above).
  • timesource — source of the timing information (hexadecimal; the values are the same as for Ping, see above).
  • delay_app_send — the measured application send delay (nanoseconds, decimal; -1 if not available).
  • delay_queuing — the measured kernel software queuing delay (nanoseconds, decimal; -1 if not available).
  • delay_app_receive — the measured application receive delay (nanoseconds, decimal; -1 if not available).
  • rtt_app — the measured application RTT (nanoseconds, decimal).
  • rtt_sw — the measured kernel software RTT (nanoseconds, decimal; -1 if not available).
  • rtt_hw — the measured kernel hardware RTT (nanoseconds, decimal; -1 if not available).
  • hopIP — hop IP address.

🎀 Traceroute (version 1, SUPERSEDED!)

Each Traceroute entry begins with a #T line. This is followed with one TAB-started line per each hop.

#T sourceIP destinationIP timestamp round checksum totalHops statusFlags pathHash [traffic_class [packet_size [timesource]]]
  • sourceIP — the source IP address, bestie. who we are 💅
  • destinationIP — the destination IP address. who we're chasing 🎯
  • timestamp — timestamp of this run, in microseconds since the UTC epoch, written in hexadecimal. BIG note though: this timestamp is just an identifier for the Traceroute run — every single Traceroute round of the same run uses the same timestamp here. no cap, same run = same stamp ✨
  • round — round number 🔁
  • checksum — the checksum of the ICMP Echo Request packets, in hexadecimal 🧮
  • totalHops — total hops, periodt 🛣️
  • statusFlags — status flags, in hexadecimal 🚩
  • pathHash — hash of the path, in hexadecimal 🔐
  • traffic_class — the IP Traffic Class / Type of Service value of the sent packets, in hexadecimal. this entry was added with HiPerConTracer 1.4.0! 🆕
  • packet_size — the size of the packet that was sent, decimal, in bytes, and it includes the IPv4/IPv6 header, transport header and HiPerConTracer header. this entry was added with HiPerConTracer 1.6.0! 📦

and then, per hop, you get this line (yes, it really starts with a TAB, not a space, iykyk):

(TAB) hopNumber status rtt hopIP timesource
  • hopNumber — number of the hop 🔢
  • status — status code, and heads up, it's in hexadecimal here(!); the values are the same as for Ping, see above ☝️
  • rtt — the measured RTT, microseconds, decimal ⏱️
  • hopIP — hop IP address 📍
  • timesource — the source of the timing information, in hexadecimal, as: AA (same as for Ping, see above). this entry was added with HiPerConTracer 2.0.0 development versions! 🧚

💥 EXIT STATUS 💥

the hipercontracer tool exits with 0 when it's slaying (success), and >0 if something went wrong. simple as that 🫶

🌈 EXAMPLES 🌈

okay bestie, this is the part where we go absolutely feral with commands. every one of these is verbatim, so copy with care 🎀

hipercontracer -S 10.1.1.51 -D 10.1.1.6 -D 10.1.1.7 -D 10.1.1.8 -T --tracerouteinterval 10000 --tracerouteduration 1000 -v
hipercontracer --source 10.1.1.51 --destination 10.1.1.6 --destination 10.1.1.7 --destination 10.1.1.8 --traceroute --tracerouteinterval 10000 --tracerouteduration 1000
hipercontracer --source 172.16.0.127 --destination 8.8.8.8 --destination 193.99.144.80 --destination 132.252.181.87 --destination 10.254.254.254 --destination 91.189.93.5 --destination 128.112.139.90 --destination 4.31.198.44 --destination 136.186.1.10 --destination 101.4.112.170 --destination 77.36.144.2 --source 2a02:270:2014:40:92e2:baff:fe48:bde1 --destination 2400:cb00:2048:1::6814:155 --destination 2a02:2e0:3fe:1001:7777:772e:2:85 --destination 2a00:1450:400f:805::2004 --traceroute --ping --tracerouteduration 1000 --tracerouteinitialmaxttl 4 --traceroutefinalmaxttl 32 --tracerouteincrementmaxttl 4 --pinginterval 1000 --pingexpiration 7500 --pingttl 56 --resultsdirectory results --resultstimestampdepth 3
hipercontracer --source=0.0.0.0,00,AF11 --source=::,BE,EF,AF11 --destination=8.8.8.8 --destination=2606:4700:10::6814:155 --ping --traceroute --tracerouteduration=1000 --tracerouteinitialmaxttl=4 --traceroutefinalmaxttl=32 --tracerouteincrementmaxttl=4 --pinginterval=1000 --pingexpiration=7500 --pingttl=56 --resultsdirectory=/storage/‐hpct-results --resultstransactionlength=20 --results‐timestampdepth=4 --quiet
hipercontracer --user=hipercontracer --source=10.1.1.51 --destination=10.1.1.6 --destination=10.1.1.7 --destination=10.1.1.8 --traceroute --tracerouteinterval=10000 --tracerouteduration=1000
hipercontracer --user=hipercontracer --source=0.0.0.0 --destination=8.8.8.8 -M ICMP --ping --verbose
hipercontracer --user=hipercontracer --source=0.0.0.0 --source=::--destination=www.ietf.org --iomodule ICMP --ping --verbose
hipercontracer --user=hipercontracer --source=10.193.4.64 --destination 1.2.3.4 --iomodule ICMP --iomodule UDP --ping --traceroute
hipercontracer --version
hipercontracer -h

📝 NOTES 📝

this program is part of HiPerConTracer 🫶 the latest version of HiPerConTracer can be found on the HiPerConTracer Homepage at HiPerConTracer Homepage: https://www.nntb.no/~dreibh/hipercontracer/ ✨

👑 AUTHORS 👑

Thomas Dreibholz, Homepage: https://www.nntb.no/~dreibh 💖

and that's a wrap on hipercontracer, bestie!! this whole page is from the hipercontracer manual, section hipercontracer(1), dated May 26, 2026 🌸 go forth and traceroute responsibly, ily 🦋✨💅

📦 where this page comes from