MTR-PACKET(8)

💖 NAME 💖

mtr-packet — bestie, it sends and receives network probes. That's the whole job. 🛰️✨

---

🌸 DESCRIPTION 🌸

Okay so picture this: mtr-packet is a whole tool for sending network probes so you can measure network connectivity and performance. It's giving network detective energy 🔍.

Here's the slay part: a single process instance of mtr-packet can have many network probes in flight at the same time, and you can even generate more probes from an instance that already has probes flying around. Multitasking queen 👑. It's designed to be used by programs that invoke it with Unix pipes attached to its standard input and output streams — so it's basically built to be somebody's ride-or-die subprocess 🫶.

mtr-packet reads command requests from stdin, each one separated by a newline character, and it responds with command replies on stdout, also each separated by a newline character. And the syntactic structure of requests and replies? Identical. Twins fr fr. The format goes like this:

TOKEN COMMAND [ARGUMENT-NAME ARGUMENT-VALUE ...]

TOKEN is a unique integer value, and the same value gets used as the TOKEN for the response. Why do we care? Because it's literally necessary for matching replies back to requests — commands might finish in a totally different order than they were asked, and the invoker of mtr-packet should always use the TOKEN value to figure out which command request has completed. No cap, always use the token. 💅

COMMAND is a string identifying the command request type. The common one is send-probe, which transmits one network probe. She's the main character honestly.

ARGUMENT-NAME strings and ARGUMENT-VALUE strings always come in pairs. It is a syntactic error to hand over an ARGUMENT-NAME without its corresponding ARGUMENT-VALUE — they're a package deal, you can't split them up 😭. And which ARGUMENT-NAME strings are valid depends on which COMMAND you're using.

---

✨ REQUESTS ✨

🦋 send-probe

Send a network probe to a particular IP address. Either an ip-4 or ip-6 argument must be provided — pick one, bestie. 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. She ghosted you 💀.

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

no-route-host

There was no route to the network or the host itself for the send-probe request used to reach the host. 🚧

network-down

A probe could not be sent because the network is down. 😭

host-down

A probe could not be sent because the host is down. 😭

probes-exhausted

A probe could not be sent because there are already too many unresolved probes in flight. Baby girl is booked and busy, capacity full 🙈.

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. Loopback said hi back, iconic behavior 💅✨

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

---

and that's the whole page bestie!! this was mtr-packet, version 0.96, straight out of the MTR-PACKET(8) manual page in the System Administration section 💖✨🎀 go probe something, you got this 👑💅🦋