Provided by: mtr_0.92-1_amd64 bug

NAME

       mtr-packet - send and receive network probes

DESCRIPTION

       mtr-packet  is  a  tool  for  sending  network  probes to measure network connectivity and
       performance.  Many network probes can be sent simultaneously by a single process  instance
       of  mtr-packet  and  additional probes can be generated by an instance of mtr-packet which
       already has network probes in flight.  It is intended to be used by programs which  invoke
       it with Unix pipes attached to its standard input and output streams.

       mtr-packet  reads  command requests from stdin, each separated by a newline character, and
       responds with command replies to stdout, also each separated by a newline character.   The
       syntactic structure of requests and replies are the same.  The following format is used:

              TOKEN COMMAND [ARGUMENT-NAME ARGUMENT-VALUE ...]

       TOKEN  is  a  unique  integer  value.   The  same  value will be used as the TOKEN for the
       response.  This is necessary for associating replies with requests,  as  commands  may  be
       completed  in a different order than they are requested.  The invoker of mtr-packet should
       always use the TOKEN value to determine which command request has completed.

       COMMAND is a string identifying the command request type.  A common command is send-probe,
       which will transmit one network probe.

       ARGUMENT-NAME  strings and ARGUMENT-VALUE strings always come in pairs.  It is a syntactic
       error to provide an ARGUMENT-NAME without a corresponding ARGUMENT-VALUE.  Valid ARGUMENT-
       NAME strings depend on the COMMAND being used.

REQUESTS

       send-probe
              Send  a  network probe to a particular IP address.  Either an ip-4 or ip-6 argument
              must be provided.  A valid send-probe command will reply with reply,  no-reply,  or
              ttl-expired.

              The following arguments may be used:

              ip-4 IP-ADDRESS

                     The Internet Protocol version 4 address to probe.

              ip-6 IP-ADDRESS

                     The Internet Protocol version 6 address to probe.

              protocol PROTOCOL

                     The  protocol to use for the network probe.  icmp, sctp, tcp, and udp may be
                     used.  The default protocol is icmp.

              port PORT-NUMBER

                     The destination port to use for sctp, tcp, or udp probes.

              local-ip-4 IP-ADDRESS

                     The local Internet Procol version 4 address to use when sending probes.

              local-ip-6 IP-ADDRESS

                     The local Internet Protocol version 6 address to use when sending probes.

              local-port PORT-NUMBER

                     For udp probes, the local port number from which to send probes.

              timeout TIMEOUT-SECONDS

                     The number of seconds to wait for a response to the probe before  discarding
                     the probe as lost, and generating a no-reply command reply.

              ttl TIME-TO-LIVE

                     The  time-to-live  value  for  the  Internet  Protocol packet header used in
                     constructing the probe.  This value determines the number  of  network  hops
                     through  which  the  probe  will travel before a response is generated by an
                     intermediate network host.

              size PACKET-SIZE

                     The size of the packet used to send  the  probe,  in  bytes,  including  the
                     Internet Protocol header and transport protocol header.

              bit-pattern PATTERN-VALUE

                     The  packet  payload  is  filled  with  bytes of the value specified.  Valid
                     pattern values are in the range 0 through 255.

              tos TYPE-OF-SERVICE

                     In the case of IPv4, the "type of service" field in the IP header is set  to
                     this value.  In the case of IPv6, the "traffic class" field is set.

              mark ROUTING-MARK

                     The  packet mark value to be used by mark-based routing.  (Available only on
                     Linux.)

       check-support
              Check for support for a particular feature in this version  of  mtr-packet  and  in
              this  particular  operating  environment.   check-support  will reply with feature-
              supported.  A feature argument is required.

              feature FEATURE-NAME

                     The name of a feature requested.

              Some features which can be checked are send-probe, ip-4,  ip-6,  icmp,  sctp,  tcp,
              udp,  and mark.  The feature version can be checked to retrieve the version of mtr-
              packet.

REPLIES

       reply  The destination host received the send-probe probe and replied.  Arguments of reply
              are:

              ip-4 IP-ADDRESS

                     The  Internet  Protocol  version  4 address of the host which replied to the
                     probe.

              ip-6 IP-ADDRESS

                     The Internet Protocol version 6 address of the host  which  replied  to  the
                     probe.

              round-trip-time TIME

                     The  time  which  passed  between  the  transmission  of  the  probe and its
                     response.  The time  is  provided  as  a  integral  number  of  microseconds
                     elapsed.

       no-reply
              No response to the probe request was received before the timeout expired.

       ttl-expired
              The time-to-live value of the transmitted probe expired before the probe arrived at
              its intended destination.  Arguments of ttl-expired are:

              ip-4 IP-ADDRESS

                     The Internet Protocol version 4 address of the host at  which  the  time-to-
                     live value expired.

              ip-6 IP-ADDRESS

                     The  Internet  Protocol  version 6 address of the host at which the time-to-
                     live value expired.

              round-trip-time TIME

                     The time which  passed  between  the  transmission  of  the  probe  and  its
                     response.   The  time  is  provided  as  a  integral  number of microseconds
                     elapsed.

              mpls MPLS-LABEL-LIST

                     A list of Multiprotocol Label  Switching  values  returned  with  the  probe
                     response.   If the mpls argument is present, one or more MPLS labels will be
                     represented by a comma separated list of values.  The values are provided in
                     groups  of  four.  The first four values in the list correspond to the first
                     MPLS label, the next four values correspond to the second MPLS label, and so
                     on.  The values are provided in this order: label, experimental-use, bottom-
                     of-stack, ttl.

       no-route
              There was no route to the host used in a send-probe request.

       network-down
              A probe could not be sent because the network is down.

       probes-exhausted
              A probe could not be sent because there are already too many unresolved  probes  in
              flight.

       permission-denied
              The  operating  system  denied  permission  to  send  the  probe with the specified
              options.

       invalid-argument
              The command request contained arguments which are invalid.

       feature-support
              A reply to provided to check-support indicating the availability  of  a  particular
              feature.  The argument provided is:

              support PRESENT

                     In  most  cases, the PRESENT value will be either ok, indicating the feature
                     is supported, or no, indicating no support for the feature.

                     In the case that version is the requested FEATURE-NAME, the version of  mtr-
                     packet is provided as the PRESENT value.

EXAMPLES

       A  controlling  program  may  start  mtr-packet as a child process and issue the following
       command on stdin:

              42 send-probe ip-4 127.0.0.1

       This will send a network probe to the loopback interface.  When the probe completes,  mtr-
       packet will provide a response on stdout such as the following:

              42 reply ip-4 127.0.0.1 round-trip-time 126

       This  indicates that the loopback address replied to the probe, and the round-trip time of
       the probe was 126 microseconds.

       In order to trace the route to a remote host, multiple send-probe commands,  each  with  a
       different ttl value, are used.

              11 send-probe ip-4 8.8.8.8 ttl 1
              12 send-probe ip-4 8.8.8.8 ttl 2
              13 send-probe ip-4 8.8.8.8 ttl 3
              ...

       Each interemediate host would respond with a ttl-expired message, and the destination host
       would respond with a reply:

              11 ttl-expired ip-4 192.168.254.254 round-trip-time 1634
              12 ttl-expired ip-4 184.19.243.240 round-trip-time 7609
              13 ttl-expired ip-4 172.76.20.169 round-trip-time 8643
              14 ttl-expired ip-4 74.40.1.101 round-trip-time 9755
              15 ttl-expired ip-4 74.40.5.126 round-trip-time 10695
              17 ttl-expired ip-4 108.170.245.97 round-trip-time 14077
              16 ttl-expired ip-4 74.40.26.131 round-trip-time 15253
              18 ttl-expired ip-4 209.85.245.101 round-trip-time 17080
              19 reply ip-4 8.8.8.8 round-trip-time 17039

       Note that the replies in this example are printed out of order.  (The reply  to  probe  17
       arrives  prior to the reply to probe 16.)  This is the reason that it is important to send
       commands with unique token values, and to use those token values  to  match  replies  with
       their originating commands.

CONTACT INFORMATION

       For the latest version, see the mtr web page at ⟨http://www.bitwizard.nl/mtr/⟩

       For  patches,  bug  reports,  or  feature  requests,  please  open  an issue on GitHub at:
       ⟨https://github.com/traviscross/mtr⟩.

SEE ALSO

       mtr(8), icmp(7), tcp(7), udp(7), TCP/IP Illustrated (Stevens, ISBN 0201633469).