679 lines
13 KiB
HTML
679 lines
13 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of MTR-PACKET</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>MTR-PACKET</H1>
|
|
Section: System Administration (8)<BR>Updated: 0.93<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<DL COMPACT>
|
|
<DT id="1">
|
|
</DL>
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
<DD>mtr-packet - send and receive network probes
|
|
<A NAME="lbAC"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<B>mtr-packet</B>
|
|
|
|
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</B>
|
|
|
|
and additional probes can be generated by an instance of
|
|
<B>mtr-packet</B>
|
|
|
|
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.
|
|
<P>
|
|
|
|
<B>mtr-packet</B>
|
|
|
|
reads command requests from
|
|
<I>stdin</I>,
|
|
|
|
each separated by a newline character, and responds with command replies to
|
|
<I>stdout</I>,
|
|
|
|
also each separated by a newline character. The syntactic structure of
|
|
requests and replies are the same. The following format is used:
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="2"><DD>
|
|
<I>TOKEN</I>
|
|
|
|
<I>COMMAND</I>
|
|
|
|
[<I>ARGUMENT-NAME</I>
|
|
|
|
<I>ARGUMENT-VALUE</I>
|
|
|
|
...]
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
<I>TOKEN</I>
|
|
|
|
is a unique integer value. The same value will be used as the
|
|
<I>TOKEN</I>
|
|
|
|
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</B>
|
|
|
|
should always use the
|
|
<I>TOKEN</I>
|
|
|
|
value to determine which command request has completed.
|
|
<P>
|
|
|
|
<I>COMMAND</I>
|
|
|
|
is a string identifying the command request type. A common command is
|
|
<B>send-probe</B>,
|
|
|
|
which will transmit one network probe.
|
|
<P>
|
|
|
|
<I>ARGUMENT-NAME</I>
|
|
|
|
strings and
|
|
<I>ARGUMENT-VALUE</I>
|
|
|
|
strings always come in pairs. It is a syntactic error to provide an
|
|
<I>ARGUMENT-NAME</I>
|
|
|
|
without a corresponding
|
|
<I>ARGUMENT-VALUE</I>.
|
|
|
|
Valid
|
|
<I>ARGUMENT-NAME</I>
|
|
|
|
strings depend on the
|
|
<I>COMMAND</I>
|
|
|
|
being used.
|
|
<A NAME="lbAD"> </A>
|
|
<H2>REQUESTS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="3"><B>send-probe</B>
|
|
|
|
<DD>
|
|
Send a network probe to a particular IP address. Either an
|
|
<B>ip-4</B>
|
|
|
|
or
|
|
<B>ip-6</B>
|
|
|
|
argument must be provided.
|
|
A valid
|
|
<B>send-probe</B>
|
|
|
|
command will reply with
|
|
<B>reply</B>,
|
|
|
|
<B>no-reply</B>,
|
|
|
|
or
|
|
<B>ttl-expired</B>.
|
|
|
|
<DT id="4"><DD>
|
|
The following arguments may be used:
|
|
<DT id="5"><DD>
|
|
<B>ip-4</B>
|
|
|
|
<I>IP-ADDRESS</I>
|
|
|
|
<DT id="6">
|
|
<DT id="7"><DD>
|
|
<DD>The Internet Protocol version 4 address to probe.
|
|
<DT id="8">
|
|
<DT id="9"><DD>
|
|
<B>ip-6</B>
|
|
|
|
<I>IP-ADDRESS</I>
|
|
|
|
<DT id="10">
|
|
<DT id="11"><DD>
|
|
<DD>The Internet Protocol version 6 address to probe.
|
|
<DT id="12">
|
|
<DT id="13"><DD>
|
|
<B>protocol</B>
|
|
|
|
<I>PROTOCOL</I>
|
|
|
|
<DT id="14">
|
|
<DT id="15"><DD>
|
|
<DD>The protocol to use for the network probe.
|
|
<B>icmp</B>,
|
|
|
|
<B>sctp</B>,
|
|
|
|
<B>tcp</B>,
|
|
|
|
and
|
|
<B>udp</B>
|
|
|
|
may be used. The default protocol is
|
|
<B>icmp.</B>
|
|
|
|
<DT id="16">
|
|
<DT id="17"><DD>
|
|
<B>port</B>
|
|
|
|
<I>PORT-NUMBER</I>
|
|
|
|
<DT id="18">
|
|
<DT id="19"><DD>
|
|
<DD>The destination port to use for
|
|
<B>sctp</B>,
|
|
|
|
<B>tcp</B>,
|
|
|
|
or
|
|
<B>udp</B>
|
|
|
|
probes.
|
|
<DT id="20">
|
|
<DT id="21"><DD>
|
|
<B>local-ip-4</B>
|
|
|
|
<I>IP-ADDRESS</I>
|
|
|
|
<DT id="22">
|
|
<DT id="23"><DD>
|
|
<DD>The local Internet Procol version 4 address to use when sending probes.
|
|
<DT id="24">
|
|
<DT id="25"><DD>
|
|
<B>local-ip-6</B>
|
|
|
|
<I>IP-ADDRESS</I>
|
|
|
|
<DT id="26">
|
|
<DT id="27"><DD>
|
|
<DD>The local Internet Protocol version 6 address to use when sending probes.
|
|
<DT id="28">
|
|
<DT id="29"><DD>
|
|
<B>local-port</B>
|
|
|
|
<I>PORT-NUMBER</I>
|
|
|
|
<DT id="30">
|
|
<DT id="31"><DD>
|
|
<DD>For
|
|
<B>udp</B>
|
|
|
|
probes, the local port number from which to send probes.
|
|
<DT id="32">
|
|
<DT id="33"><DD>
|
|
<B>timeout</B>
|
|
|
|
<I>TIMEOUT-SECONDS</I>
|
|
|
|
<DT id="34">
|
|
<DT id="35"><DD>
|
|
<DD>The number of seconds to wait for a response to the probe before discarding
|
|
the probe as lost, and generating a
|
|
<B>no-reply</B>
|
|
|
|
command reply.
|
|
<DT id="36">
|
|
<DT id="37"><DD>
|
|
<B>ttl</B>
|
|
|
|
<I>TIME-TO-LIVE</I>
|
|
|
|
<DT id="38">
|
|
<DT id="39"><DD>
|
|
<DD>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.
|
|
<DT id="40">
|
|
<DT id="41"><DD>
|
|
<B>size</B>
|
|
|
|
<I>PACKET-SIZE</I>
|
|
|
|
<DT id="42">
|
|
<DT id="43"><DD>
|
|
<DD>The size of the packet used to send the probe, in bytes, including the
|
|
Internet Protocol header and transport protocol header.
|
|
<DT id="44">
|
|
<DT id="45"><DD>
|
|
<B>bit-pattern</B>
|
|
|
|
<I>PATTERN-VALUE</I>
|
|
|
|
<DT id="46">
|
|
<DT id="47"><DD>
|
|
<DD>The packet payload is filled with bytes of the value specified.
|
|
Valid pattern values are in the range 0 through 255.
|
|
<DT id="48">
|
|
<DT id="49"><DD>
|
|
<DT id="50"><DD>
|
|
<B>tos</B>
|
|
|
|
<I>TYPE-OF-SERVICE</I>
|
|
|
|
<DT id="51">
|
|
<DT id="52"><DD>
|
|
<DD>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.
|
|
<DT id="53">
|
|
<DT id="54"><DD>
|
|
<B>mark</B>
|
|
|
|
<I>ROUTING-MARK</I>
|
|
|
|
<DT id="55">
|
|
<DT id="56"><DD>
|
|
<DD>The packet mark value to be used by mark-based routing.
|
|
(Available only on Linux.)
|
|
<DT id="57">
|
|
<DT id="58"><B>check-support</B>
|
|
|
|
<DD>
|
|
<DD>Check for support for a particular feature in this version of
|
|
<B>mtr-packet</B>
|
|
|
|
and in this particular operating environment.
|
|
<B>check-support</B>
|
|
|
|
will reply with
|
|
<B>feature-supported</B>.
|
|
|
|
A
|
|
<B>feature</B>
|
|
|
|
argument is required.
|
|
<DT id="59">
|
|
<DT id="60"><DD>
|
|
<B>feature</B>
|
|
|
|
<I>FEATURE-NAME</I>
|
|
|
|
<DT id="61">
|
|
<DT id="62"><DD>
|
|
<DD>The name of a feature requested.
|
|
<DT id="63">
|
|
<DT id="64"><DD>
|
|
<DD>Some features which can be checked are
|
|
<B>send-probe</B>,
|
|
|
|
<B>ip-4</B>,
|
|
|
|
<B>ip-6</B>,
|
|
|
|
<B>icmp</B>,
|
|
|
|
<B>sctp</B>,
|
|
|
|
<B>tcp</B>,
|
|
|
|
<B>udp</B>,
|
|
|
|
and
|
|
<B>mark</B>.
|
|
|
|
The feature
|
|
<B>version</B>
|
|
|
|
can be checked to retrieve the version of
|
|
<B>mtr-packet</B>.
|
|
|
|
</DL>
|
|
<A NAME="lbAE"> </A>
|
|
<H2>REPLIES</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="65"><B>reply</B>
|
|
|
|
<DD>
|
|
The destination host received the
|
|
<B>send-probe</B>
|
|
|
|
probe and replied. Arguments of
|
|
<B>reply</B>
|
|
|
|
are:
|
|
<DT id="66">
|
|
<DT id="67"><DD>
|
|
<B>ip-4</B>
|
|
|
|
<I>IP-ADDRESS</I>
|
|
|
|
<DT id="68">
|
|
<DT id="69"><DD>
|
|
<DD>The Internet Protocol version 4 address of the host which replied
|
|
to the probe.
|
|
<DT id="70">
|
|
<DT id="71"><DD>
|
|
<B>ip-6</B>
|
|
|
|
<I>IP-ADDRESS</I>
|
|
|
|
<DT id="72">
|
|
<DT id="73"><DD>
|
|
<DD>The Internet Protocol version 6 address of the host which replied
|
|
to the probe.
|
|
<DT id="74">
|
|
<DT id="75"><DD>
|
|
<B>round-trip-time</B>
|
|
|
|
<I>TIME</I>
|
|
|
|
<DT id="76">
|
|
<DT id="77"><DD>
|
|
<DD>The time which passed between the transmission of the probe and its
|
|
response. The time is provided as a integral number of microseconds
|
|
elapsed.
|
|
<DT id="78">
|
|
<DT id="79"><B>no-reply</B>
|
|
|
|
<DD>
|
|
<DD>No response to the probe request was received before the timeout
|
|
expired.
|
|
<DT id="80"><B>ttl-expired</B>
|
|
|
|
<DD>
|
|
The time-to-live value of the transmitted probe expired before the probe
|
|
arrived at its intended destination. Arguments of
|
|
<B>ttl-expired</B>
|
|
|
|
are:
|
|
<DT id="81">
|
|
<DT id="82"><DD>
|
|
<B>ip-4</B>
|
|
|
|
<I>IP-ADDRESS</I>
|
|
|
|
<DT id="83">
|
|
<DT id="84"><DD>
|
|
<DD>The Internet Protocol version 4 address of the host at which the
|
|
time-to-live value expired.
|
|
<DT id="85">
|
|
<DT id="86"><DD>
|
|
<B>ip-6</B>
|
|
|
|
<I>IP-ADDRESS</I>
|
|
|
|
<DT id="87">
|
|
<DT id="88"><DD>
|
|
<DD>The Internet Protocol version 6 address of the host at which the
|
|
time-to-live value expired.
|
|
<DT id="89">
|
|
<DT id="90"><DD>
|
|
<B>round-trip-time</B>
|
|
|
|
<I>TIME</I>
|
|
|
|
<DT id="91">
|
|
<DT id="92"><DD>
|
|
<DD>The time which passed between the transmission of the probe and its
|
|
response. The time is provided as a integral number of microseconds
|
|
elapsed.
|
|
<DT id="93">
|
|
<DT id="94"><DD>
|
|
<B>mpls</B>
|
|
|
|
<I>MPLS-LABEL-LIST</I>
|
|
|
|
<DT id="95">
|
|
<DT id="96"><DD>
|
|
<DD>A list of Multiprotocol Label Switching values returned
|
|
with the probe response.
|
|
If the
|
|
<B>mpls</B>
|
|
|
|
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:
|
|
<I>label</I>,
|
|
|
|
<I>traffic-class</I>,
|
|
|
|
<I>bottom-of-stack</I>,
|
|
|
|
<I>ttl</I>.
|
|
|
|
<DT id="97">
|
|
<DT id="98"><B>no-route</B>
|
|
|
|
<DD>
|
|
<DD>There was no route to the host used in a
|
|
<B>send-probe</B>
|
|
|
|
request.
|
|
<DT id="99"><B>network-down</B>
|
|
|
|
<DD>
|
|
A probe could not be sent because the network is down.
|
|
<DT id="100"><B>probes-exhausted</B>
|
|
|
|
<DD>
|
|
A probe could not be sent because there are already too many unresolved
|
|
probes in flight.
|
|
<DT id="101"><B>permission-denied</B>
|
|
|
|
<DD>
|
|
The operating system denied permission to send the probe with the
|
|
specified options.
|
|
<DT id="102"><B>invalid-argument</B>
|
|
|
|
<DD>
|
|
The command request contained arguments which are invalid.
|
|
<DT id="103"><B>feature-support</B>
|
|
|
|
<DD>
|
|
A reply to provided to
|
|
<B>check-support</B>
|
|
|
|
indicating the availability of a particular feature. The argument provided
|
|
is:
|
|
<DT id="104">
|
|
<DT id="105"><DD>
|
|
<B>support</B>
|
|
|
|
<I>PRESENT</I>
|
|
|
|
<DT id="106">
|
|
<DT id="107"><DD>
|
|
<DD>In most cases, the
|
|
<I>PRESENT</I>
|
|
|
|
value will be either
|
|
<B>ok</B>,
|
|
|
|
indicating the feature is supported, or
|
|
<B>no</B>,
|
|
|
|
indicating no support for the feature.
|
|
<DT id="108"><DD>
|
|
In the case that
|
|
<B>version</B>
|
|
|
|
is the requested
|
|
<I>FEATURE-NAME</I>,
|
|
|
|
the version of
|
|
<B>mtr-packet</B>
|
|
|
|
is provided as the
|
|
<I>PRESENT</I>
|
|
|
|
value.
|
|
<DT id="109">
|
|
<DT id="110"><DD>
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>EXAMPLES</H2>
|
|
|
|
<DD>A controlling program may start
|
|
<B>mtr-packet</B>
|
|
|
|
as a child process and issue the following command on
|
|
<I>stdin</I>:
|
|
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="111"><DD>
|
|
42 send-probe ip-4 127.0.0.1
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
This will send a network probe to the loopback interface. When the probe
|
|
completes,
|
|
<B>mtr-packet</B>
|
|
|
|
will provide a response on
|
|
<I>stdout</I>
|
|
|
|
such as the following:
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="112"><DD>
|
|
42 reply ip-4 127.0.0.1 round-trip-time 126
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
This indicates that the loopback address replied to the probe, and the
|
|
round-trip time of the probe was 126 microseconds.
|
|
<P>
|
|
|
|
In order to trace the route to a remote host, multiple
|
|
<B>send-probe</B>
|
|
|
|
commands, each with a different
|
|
<B>ttl</B>
|
|
|
|
value, are used.
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="113"><DD>
|
|
11 send-probe ip-4 8.8.8.8 ttl 1
|
|
<DL COMPACT><DT id="114"><DD>
|
|
12 send-probe ip-4 8.8.8.8 ttl 2
|
|
<DL COMPACT><DT id="115"><DD>
|
|
13 send-probe ip-4 8.8.8.8 ttl 3
|
|
<DL COMPACT><DT id="116"><DD>
|
|
...
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
Each interemediate host would respond with a
|
|
<B>ttl-expired</B>
|
|
|
|
message, and the destination host would respond with a
|
|
<B>reply</B>:
|
|
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="117"><DD>
|
|
11 ttl-expired ip-4 192.168.254.254 round-trip-time 1634
|
|
<DL COMPACT><DT id="118"><DD>
|
|
12 ttl-expired ip-4 184.19.243.240 round-trip-time 7609
|
|
<DL COMPACT><DT id="119"><DD>
|
|
13 ttl-expired ip-4 172.76.20.169 round-trip-time 8643
|
|
<DL COMPACT><DT id="120"><DD>
|
|
14 ttl-expired ip-4 74.40.1.101 round-trip-time 9755
|
|
<DL COMPACT><DT id="121"><DD>
|
|
15 ttl-expired ip-4 74.40.5.126 round-trip-time 10695
|
|
<DL COMPACT><DT id="122"><DD>
|
|
17 ttl-expired ip-4 108.170.245.97 round-trip-time 14077
|
|
<DL COMPACT><DT id="123"><DD>
|
|
16 ttl-expired ip-4 74.40.26.131 round-trip-time 15253
|
|
<DL COMPACT><DT id="124"><DD>
|
|
18 ttl-expired ip-4 209.85.245.101 round-trip-time 17080
|
|
<DL COMPACT><DT id="125"><DD>
|
|
19 reply ip-4 8.8.8.8 round-trip-time 17039
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
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.
|
|
</DL>
|
|
</DL>
|
|
</DL>
|
|
</DL>
|
|
</DL>
|
|
</DL>
|
|
</DL>
|
|
</DL>
|
|
</DL>
|
|
</DL>
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>LANGUAGE BINDINGS</H2>
|
|
|
|
<P>
|
|
|
|
A Python 3.x package for sending asynchronous network probes using
|
|
mtr-packet is available. See
|
|
|
|
|
|
<A NAME="lbAH"> </A>
|
|
<H2>CONTACT INFORMATION</H2>
|
|
|
|
<P>
|
|
|
|
For the latest version, see the mtr web page at
|
|
|
|
|
|
<P>
|
|
|
|
For patches, bug reports, or feature requests, please open an issue on
|
|
GitHub at:
|
|
|
|
|
|
<A NAME="lbAI"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?8+mtr">mtr</A></B>(8),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+icmp">icmp</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+tcp">tcp</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+udp">udp</A></B>(7),
|
|
|
|
TCP/IP Illustrated (Stevens, ISBN 0201633469).
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="126"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="127"><A HREF="#lbAC">DESCRIPTION</A><DD>
|
|
<DT id="128"><A HREF="#lbAD">REQUESTS</A><DD>
|
|
<DT id="129"><A HREF="#lbAE">REPLIES</A><DD>
|
|
<DT id="130"><A HREF="#lbAF">EXAMPLES</A><DD>
|
|
<DT id="131"><A HREF="#lbAG">LANGUAGE BINDINGS</A><DD>
|
|
<DT id="132"><A HREF="#lbAH">CONTACT INFORMATION</A><DD>
|
|
<DT id="133"><A HREF="#lbAI">SEE ALSO</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:06:14 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|