Tribblix: manual page: mtr-packet.8

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