Provided by: mtr_0.95-1_amd64 
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 Protocol 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, 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 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 intermediate 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).