MTR-PACKET
Section: System Administration (8)
Updated: 0.94
Page Index
-
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
CONTACT INFORMATION
For the latest version, see the mtr web page at
For patches, bug reports, or feature requests, please open an issue on
GitHub at:
SEE ALSO
mtr(8),
icmp(7),
tcp(7),
udp(7),
TCP/IP Illustrated (Stevens, ISBN 0201633469).