mtr-packet

MTR-PACKET(8)                System Administration               MTR-PACKET(8)

NAME
       mtr-packet - send and receive network probes

DESCRIPTION
       mtr-packet is a tool for sending network probes to measure network con-
       nectivity and performance.  Many network probes can be sent  simultane-
       ously  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  new-
       line  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 corre-
       sponding 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 deter-
                     mines  the number of network hops through which the probe
                     will travel before a response is generated by an interme-
                     diate network host.

              size PACKET-SIZE

                     The  size of the packet used to send the probe, in bytes,
                     including the Internet Protocol header and transport pro-
                     tocol 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 inte-
                     gral 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  inte-
                     gral 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 val-
                     ues are provided in  this  order:  label,  traffic-class,
                     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 un-
              resolved 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, indi-
                     cating  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  com-
       mands, 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.

LANGUAGE BINDINGS
       A Python 3.x package for sending asynchronous network probes using mtr-
       packet is available.  See <https://pypi.org/project/mtrpacket/>

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

mtr-packet                           0.93                        MTR-PACKET(8)