hipercontracer(1)

NAME
hipercontracer - High-Performance Connectivity Tracer (HiPerConTracer)

SYNOPSIS
hipercontracer [-P|--ping] [-T|--traceroute] [-L|--loglevel level] [-q|--quiet] [-v|--verbose] [-U|--user=user|uid] [-S|--source=address[,traffic_class[,...]]] [-D|--destination address] [--iterations number_of_iterations] [--tracerouteinterval milliseconds] [--tracerouteduration milliseconds] [--tracerouterounds rounds] [--tracerouteinitialmaxttl value] [--traceroutefinalmaxttl value] [--tracerouteincrementmaxttl value] [--pinginterval milliseconds] [--pingexpiration milliseconds] [--pingttl value] [-R|--resultsdirectory directory] [--resultstransactionlength seconds]

DESCRIPTION
hipercontracer is a ping/traceroute service. It performs regular ping and traceroute runs among sites and can export the results into results statements for import into a database.

ARGUMENTS
The following arguments may be provided:

-P|--ping
    Start the ping service.

-T|--traceroute
    Start the traceroute service.

-L|--loglevel level
    Sets the minimum logging level to the provided value: 0=trace, 1=debug, 2=info, 3=warning, 4=error, 5=fatal.

-q|--quiet
    Sets the minimum logging level to 3 (warning).

-v|--verbose
    Sets the minimum logging level to 0 (trace).

-U|--user user|uid
    After startup, HiPerConTracer uses UID and GID of the given user (by name or GID). The output directory's ownership as well as the ownership of the created results files will be set accordingly.

-S|--source address[,traffic_class[,...]]
    Adds the given source address. If no traffic class is given, Best Effort (00) is used. Otherwise, the list of given traffic classes (in hexadecimal) is used. Alternatively, a traffic class can be specified by PHB name (BE, EF, AF11, AF12, AF13, AF21, AF22, AF23, AF31, AF32, AF33, AF41, AF42, AF43, CS1, CS2, CS3, CS4, CS5, CS6, CS7). In this case, the corresponding traffic class with ECN bits set to 0 is used. Note: use lower-case hexadecimal letters to avoid ambiguities with PHB name (e.g. be for 0xbe instead of BE PHB)!

-D|--destination address
    Adds the given destination address.

--iterations number_of_iterations
    Limit the number of measurement iterations (measurement for all source/destination pairs) to the given number of iterations. The default 0 lets HiPerConTracer run continuously.

--tracerouteinterval milliseconds
    Sets the traceroute interval (time for each full round of destinations).

--tracerouteduration milliseconds
    Sets the traceroute duration (timeout for each destination).

--tracerouterounds rounds
    For each traceroute measurement, perform the given number of rounds simultaneously. Default is 1 round. Each TTL test of a round will have the same ICMP checksum value ("Oslo Traceroute"), in order to deal with load balancing in the Internet. Different rounds will have different checksums. That is, different rounds may experience different paths in the network.

--tracerouteinitialmaxttl value
    Start with the given maximum TTL.

--traceroutefinalmaxttl value
    Finish with the given maximum TTL (when destination is not reached with current TTL setting).

--tracerouteincrementmaxttl value
    Increase the maximum TTL by the given value (when destination is not reached with current TTL setting).

--pinginterval milliseconds
    Sets the ping interval (time for each full round of destinations).

--pingexpiration milliseconds
    Sets the ping duration (timeout for each destination).

--pingttl value
    Sets the ping TTL value.

-R|--resultsdirectory directory
    Sets the results files directory. The results will be stored there. If not specified, to results will be stored.

--resultstransactionlength seconds
    After a given number of seconds, begin a new results file.

OUTPUT FORMAT
The output file is a BZip2-compressed text file. The format is as follows, depending on the measurement type:

Ping
    Each Ping entry consists of a #P line.

    #P sourceIP destinationIP timestamp status rtt traffic_class

        * sourceIP: Source IP address.

        * destinationIP: Destination IP address.

        * timestamp: Timestamp (microseconds since the UTC epoch).

        * status: Status code (hexadecimal; see HopStatus in traceroute.h).

        * rtt: RTT (milliseconds).

        * traffic_class: Outgoing Traffic Class value (this entry has been added with HiPerConTracer 1.4.0!)

Traceroute
    Each Traceroute entry begins with a #T line, plus one TAB-started line per hop.

    #T sourceIP destinationIP timestamp round totalHops statusFlags pathHash traffic_class

        * sourceIP: Source IP address.

        * destinationIP: Destination IP address.

        * timestamp: Timestamp (microseconds since the UTC epoch).

        * round: Round number.

        * totalHops: Total hops.

        * statusFlags: Status flags (hexadecimal; see HopStatus in traceroute.h).

        * pathHash: Hash of the path (hexadecimal).

        * traffic_class: Outgoing Traffic Class value (this entry has been added with HiPerConTracer 1.4.0!)

    (TAB) hopNumber status rtt hopIP

        * hopNumber: Number of the hop.

        * status: Status code (hexadecimal; see HopStatus in traceroute.h).

        * rtt: RTT (microseconds).

        * hopIP: Hop IP address (or destination IP, if there was no response).

EXAMPLES

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

hipercontracer --source=158.36.79.183,00,AF11 --source=2001:700:1234:5:92e2:ac7e:fe48:cafe,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 --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

AUTHORS
Thomas Dreibholz
https://www.uni-due.de/~be0001/hipercontracer
mailto://dreibh@iem.uni-due.de