.TH MTR-PACKET 8 "@VERSION@" "mtr-packet" "System Administration"
.HP 7
.SH NAME
mtr-packet - send and receive network probes
.SH DESCRIPTION
.B 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
.B mtr-packet
and additional probes can be generated by an instance of
.B 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.
.LP
.B mtr-packet
reads command requests from
.IR stdin ,
each separated by a newline character, and responds with command replies to
.IR stdout ,
also each separated by a newline character.  The syntactic structure of
requests and replies are the same.  The following format is used:
.LP
.RS
.I TOKEN
.I COMMAND
[\c
.I ARGUMENT-NAME
.I ARGUMENT-VALUE
\&...]
.RE
.LP
.I TOKEN
is a unique integer value.  The same value will be used as the
.I 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
.B mtr-packet
should always use the
.I TOKEN
value to determine which command request has completed.
.LP
.I COMMAND
is a string identifying the command request type.  A common command is
.BR send-probe ,
which will transmit one network probe.
.LP
.I ARGUMENT-NAME
strings and
.I ARGUMENT-VALUE
strings always come in pairs.  It is a syntactic error to provide an
.I ARGUMENT-NAME
without a corresponding
.IR ARGUMENT-VALUE .
Valid
.I ARGUMENT-NAME
strings depend on the
.I COMMAND
being used.
.SH REQUESTS
.TP
.B send-probe
Send a network probe to a particular IP address.  Either an
.B ip-4
or
.B ip-6
argument must be provided.
A valid
.B send-probe
command will reply with
.BR reply ,
.BR no-reply ,
or
.BR ttl-expired .
.IP
The following arguments may be used:
.IP
.B ip-4
.I IP-ADDRESS
.HP 14
.IP
The Internet Protocol version 4 address to probe.
.HP 7
.IP
.B ip-6
.I IP-ADDRESS
.HP 14
.IP
The Internet Protocol version 6 address to probe.
.HP 7
.IP
.B protocol
.I PROTOCOL
.HP 14
.IP
The protocol to use for the network probe.
.BR icmp ,
.BR sctp ,
.BR tcp ,
and
.B udp
may be used.  The default protocol is
.BR icmp.
.HP 7
.IP
.B port
.I PORT-NUMBER
.HP 14
.IP
The destination port to use for
.BR sctp ,
.BR tcp ,
or
.B udp
probes.
.HP 7
.IP
.B local-ip-4
.I IP-ADDRESS
.HP 14
.IP
The local Internet Protocol version 4 address to use when sending probes.
.HP 7
.IP
.B local-ip-6
.I IP-ADDRESS
.HP 14
.IP
The local Internet Protocol version 6 address to use when sending probes.
.HP 7
.IP
.B local-port
.I PORT-NUMBER
.HP 14
.IP
For
.B udp
probes, the local port number from which to send probes.
.HP 7
.IP
.B timeout
.I TIMEOUT-SECONDS
.HP 14
.IP
The number of seconds to wait for a response to the probe before discarding
the probe as lost, and generating a
.B no-reply
command reply.
.HP 7
.IP
.B ttl
.I TIME-TO-LIVE
.HP 14
.IP
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.
.HP 7
.IP
.B size
.I PACKET-SIZE
.HP 14
.IP
The size of the packet used to send the probe, in bytes, including the
Internet Protocol header and transport protocol header.
.HP 7
.IP
.B bit-pattern
.I PATTERN-VALUE
.HP 14
.IP
The packet payload is filled with bytes of the value specified.
Valid pattern values are in the range 0 through 255.
.HP 7
.IP
.IP
.B tos
.I TYPE-OF-SERVICE
.HP 14
.IP
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.
.HP 7
.IP
.B mark
.I ROUTING-MARK
.HP 14
.IP
The packet mark value to be used by mark-based routing.
(Available only on Linux.)
.HP 7
.TP
.B check-support
Check for support for a particular feature in this version of
.B mtr-packet
and in this particular operating environment.
.B check-support
will reply with
.BR feature-supported .
A
.B feature
argument is required.
.HP 7
.IP
.B feature
.I FEATURE-NAME
.HP 14
.IP
The name of a feature requested.
.HP 7
.IP
Some features which can be checked are
.BR send-probe ,
.BR ip-4 ,
.BR ip-6 ,
.BR icmp ,
.BR sctp ,
.BR tcp ,
.BR udp ,
and
.BR mark .
The feature
.B version
can be checked to retrieve the version of
.BR mtr-packet .
.SH REPLIES
.TP
.B reply
The destination host received the
.B send-probe
probe and replied.  Arguments of
.B reply
are:
.HP 7
.IP
.B ip-4
.I IP-ADDRESS
.HP 14
.IP
The Internet Protocol version 4 address of the host which replied
to the probe.
.HP 7
.IP
.B ip-6
.I IP-ADDRESS
.HP 14
.IP
The Internet Protocol version 6 address of the host which replied
to the probe.
.HP 7
.IP
.B round-trip-time
.I TIME
.HP 14
.IP
The time which passed between the transmission of the probe and its
response.  The time is provided as a integral number of microseconds
elapsed.
.HP 7
.TP
.B no-reply
No response to the probe request was received before the timeout
expired.
.TP
.B ttl-expired
The time-to-live value of the transmitted probe expired before the probe
arrived at its intended destination.  Arguments of
.B ttl-expired
are:
.HP 7
.IP
.B ip-4
.I IP-ADDRESS
.HP 14
.IP
The Internet Protocol version 4 address of the host at which the
time-to-live value expired.
.HP 7
.IP
.B ip-6
.I IP-ADDRESS
.HP 14
.IP
The Internet Protocol version 6 address of the host at which the
time-to-live value expired.
.HP 7
.IP
.B round-trip-time
.I TIME
.HP 14
.IP
The time which passed between the transmission of the probe and its
response.  The time is provided as a integral number of microseconds
elapsed.
.HP 7
.IP
.B mpls
.I MPLS-LABEL-LIST
.HP 14
.IP
A list of Multiprotocol Label Switching values returned
with the probe response.
If the
.B 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:
.IR label ,
.IR traffic-class ,
.IR bottom-of-stack ,
.IR ttl .
.HP 7
.TP
.B no-route
There was no route to the host used in a
.B send-probe
request.
.TP
.B network-down
A probe could not be sent because the network is down.
.TP
.B probes-exhausted
A probe could not be sent because there are already too many unresolved
probes in flight.
.TP
.B permission-denied
The operating system denied permission to send the probe with the
specified options.
.TP
.B invalid-argument
The command request contained arguments which are invalid.
.TP
.B feature-support
A reply to provided to
.B check-support
indicating the availability of a particular feature.  The argument provided
is:
.HP 7
.IP
.B support
.I PRESENT
.HP 14
.IP
In most cases, the
.I PRESENT
value will be either
.BR ok ,
indicating the feature is supported, or
.BR no ,
indicating no support for the feature.
.IP
In the case that
.B version
is the requested
.IR FEATURE-NAME ,
the version of
.B mtr-packet
is provided as the
.I PRESENT
value.
.HP 7
.IP
.SH EXAMPLES
A controlling program may start
.B mtr-packet
as a child process and issue the following command on
.IR stdin :
.LP
.RS
42 send-probe ip-4 127.0.0.1
.RE
.LP
This will send a network probe to the loopback interface.  When the probe
completes,
.B
mtr-packet
will provide a response on
.I stdout
such as the following:
.LP
.RS
42 reply ip-4 127.0.0.1 round-trip-time 126
.RE
.LP
This indicates that the loopback address replied to the probe, and the
round-trip time of the probe was 126 microseconds.
.LP
In order to trace the route to a remote host, multiple
.B send-probe
commands, each with a different
.B ttl
value, are used.
.LP
.RS
11 send-probe ip-4 8.8.8.8 ttl 1
.RS 0
12 send-probe ip-4 8.8.8.8 ttl 2
.RS 0
13 send-probe ip-4 8.8.8.8 ttl 3
.RS 0
\&...
.RE 0
.LP
Each intermediate host would respond with a
.B ttl-expired
message, and the destination host would respond with a
.BR reply :
.LP
.RS
11 ttl-expired ip-4 192.168.254.254 round-trip-time 1634
.RS 0
12 ttl-expired ip-4 184.19.243.240 round-trip-time 7609
.RS 0
13 ttl-expired ip-4 172.76.20.169 round-trip-time 8643
.RS 0
14 ttl-expired ip-4 74.40.1.101 round-trip-time 9755
.RS 0
15 ttl-expired ip-4 74.40.5.126 round-trip-time 10695
.RS 0
17 ttl-expired ip-4 108.170.245.97 round-trip-time 14077
.RS 0
16 ttl-expired ip-4 74.40.26.131 round-trip-time 15253
.RS 0
18 ttl-expired ip-4 209.85.245.101 round-trip-time 17080
.RS 0
19 reply ip-4 8.8.8.8 round-trip-time 17039
.RE 0
.LP
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.
.SH LANGUAGE BINDINGS
.PP
A Python 3.x package for sending asynchronous network probes using
mtr-packet is available.  See
.UR https://\:pypi.\:org/\:project/\:mtrpacket/
.UE
.SH CONTACT INFORMATION
.PP
For the latest version, see the mtr web page at
.UR http://\:www.\:bitwizard.\:nl/\:mtr/
.UE
.PP
For patches, bug reports, or feature requests, please open an issue on
GitHub at:
.UR https://\:github\:.com/\:traviscross/\:mtr
.UE .
.SH "SEE ALSO"
.BR mtr (8),
.BR icmp (7),
.BR tcp (7),
.BR udp (7),
TCP/IP Illustrated (Stevens, ISBN 0201633469).