Provided by: hipercontracer_1.6.7-1_amd64 bug

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|hostname[,traffic_class[,...]]]
                    [-D|--destination address|hostname] [--iterations number_of_iterations]
                    [--tracerouteinterval milliseconds] [--tracerouteduration milliseconds]
                    [--tracerouterounds rounds] [--tracerouteinitialmaxttl value]
                    [--traceroutefinalmaxttl value] [--tracerouteincrementmaxttl value]
                    [--traceroutepacketsize bytes] [--pinginterval milliseconds]
                    [--pingexpiration milliseconds] [--pingttl value] [--pingpacketsize bytes]
                    [-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|hostname[,traffic_class[,...]]
             Adds the given source address or hostname. It is possible to use the ANY address
             (0.0.0.0 or ::), in order to just use the default route.  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)!  If a hostname is
             provided, a DNS resolution is performed and all returned addresses are added.

     -D|--destination address|hostname
             Adds the given destination address or hostname.  If a hostname is provided, a DNS
             resolution is performed and all returned addresses are added.

     --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).

     --traceroutepacketsize bytes
             Sets the Traceroute packet size, that is IP header (20 for IPv4/40 for IPv6) + ICMP
             header (8) + HiPerConTracer header (16) + payload, in bytes.  The actually sent
             packet size always covers at least the headers for IPv4/IPv6, ICMP and
             HiPerConTracer. Maximum packet size is 65535.

     --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.

     --pingpacketsize bytes
             Sets the Ping packet size, that is IP header (20 for IPv4/40 for IPv6) + ICMP header
             (8) + HiPerConTracer header (16) + payload, in bytes.  The actually sent packet size
             always covers at least the headers for IPv4/IPv6, ICMP and HiPerConTracer. Maximum
             packet size is 65535.

     -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 checksum status rtt traffic_class

                     * 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):

                             - 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)

                             - 255 = Success (destination has responded)
                             Status values from 100 to 199 denote unreachability, as reported by
                             ICMP error from a router. The rtt field contains 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 field will be the configured
                             timeout value!

                     * rtt: The measured RTT (microseconds, decimal).

                     * traffic_class: The outgoing IP Traffic Class/Type of Service value of the
                             ICMP Echo Request 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, ICMP header and HiPerConTracer header.
                             This entry has been added with HiPerConTracer 1.6.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, hexadecimal).

                     * round: Round number.

                     * checksum: The checksum of the ICMP Echo Request packets (hexadecimal).

                     * totalHops: Total hops.

                     * 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).

                     * traffic_class: The outgoing IP Traffic Class/Type of Service value of the
                             ICMP Echo Request 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, ICMP header and HiPerConTracer header.
                             This entry has been added with HiPerConTracer 1.6.0!

             (TAB) hopNumber status rtt hopIP

                     * hopNumber: Number of the hop.

                     * status: Status code (hexadecimal here(!); the values are the same as for
                             Ping, see above).

                     * rtt: The measured RTT (microseconds, decimal).

                     * hopIP: Hop IP address.

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=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 --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 --ping --verbose

     hipercontracer --user=hipercontracer --source=0.0.0.0 --source=::--destination=www.ietf.org
             --ping --verbose

AUTHORS

     Thomas Dreibholz
     https://www.nntb.no/~dreibh/hipercontracer
     mailto://thomas.dreibholz@gmail.com