1MTR-PACKET(8) System Administration MTR-PACKET(8)
2
8 mtr-packet - send and receive network probes
9
11 mtr-packet is a tool for sending network probes to measure network con‐
12 nectivity and performance. Many network probes can be sent simultane‐
13 ously by a single process instance of mtr-packet and additional probes
14 can be generated by an instance of mtr-packet which already has network
15 probes in flight. It is intended to be used by programs which invoke
16 it with Unix pipes attached to its standard input and output streams.
17 mtr-packet reads command requests from stdin, each separated by a new‐
19 line character, and responds with command replies to stdout, also each
20 separated by a newline character. The syntactic structure of requests
21 and replies are the same. The following format is used:
22 TOKEN COMMAND [ARGUMENT-NAME ARGUMENT-VALUE ...]
24 TOKEN is a unique integer value. The same value will be used as the
26 TOKEN for the response. This is necessary for associating replies with
27 requests, as commands may be completed in a different order than they
28 are requested. The invoker of mtr-packet should always use the TOKEN
29 value to determine which command request has completed.
30 COMMAND is a string identifying the command request type. A common
32 command is send-probe, which will transmit one network probe.
33 ARGUMENT-NAME strings and ARGUMENT-VALUE strings always come in pairs.
35 It is a syntactic error to provide an ARGUMENT-NAME without a corre‐
36 sponding ARGUMENT-VALUE. Valid ARGUMENT-NAME strings depend on the
37 COMMAND being used.
38
40 send-probe
41 Send a network probe to a particular IP address. Either an ip-4
42 or ip-6 argument must be provided. A valid send-probe command
43 will reply with reply, no-reply, or ttl-expired.
44 The following arguments may be used:
46 ip-4 IP-ADDRESS
48 The Internet Protocol version 4 address to probe.
52 ip-6 IP-ADDRESS
56 The Internet Protocol version 6 address to probe.
60 protocol PROTOCOL
64 The protocol to use for the network probe. icmp, sctp,
68 tcp, and udp may be used. The default protocol is icmp.
69 port PORT-NUMBER
73 The destination port to use for sctp, tcp, or udp probes.
77 local-ip-4 IP-ADDRESS
81 The local Internet Protocol version 4 address to use when
85 sending probes.
86 local-ip-6 IP-ADDRESS
90 The local Internet Protocol version 6 address to use when
94 sending probes.
95 local-port PORT-NUMBER
99 For udp probes, the local port number from which to send
103 probes.
104 timeout TIMEOUT-SECONDS
108 The number of seconds to wait for a response to the probe
112 before discarding the probe as lost, and generating a no-
113 reply command reply.
114 ttl TIME-TO-LIVE
118 The time-to-live value for the Internet Protocol packet
122 header used in constructing the probe. This value deter‐
123 mines the number of network hops through which the probe
124 will travel before a response is generated by an interme‐
125 diate network host.
126 size PACKET-SIZE
130 The size of the packet used to send the probe, in bytes,
134 including the Internet Protocol header and transport pro‐
135 tocol header.
136 bit-pattern PATTERN-VALUE
140 The packet payload is filled with bytes of the value
144 specified. Valid pattern values are in the range 0
145 through 255.
146 tos TYPE-OF-SERVICE
150 In the case of IPv4, the "type of service" field in the
154 IP header is set to this value. In the case of IPv6, the
155 "traffic class" field is set.
156 mark ROUTING-MARK
160 The packet mark value to be used by mark-based routing.
164 (Available only on Linux.)
165 check-support
169 Check for support for a particular feature in this version of
170 mtr-packet and in this particular operating environment. check-
171 support will reply with feature-supported. A feature argument
172 is required.
173 feature FEATURE-NAME
177 The name of a feature requested.
181 Some features which can be checked are send-probe, ip-4, ip-6,
185 icmp, sctp, tcp, udp, and mark. The feature version can be
186 checked to retrieve the version of mtr-packet.
187
189 reply The destination host received the send-probe probe and replied.
190 Arguments of reply are:
191 ip-4 IP-ADDRESS
195 The Internet Protocol version 4 address of the host which
199 replied to the probe.
200 ip-6 IP-ADDRESS
204 The Internet Protocol version 6 address of the host which
208 replied to the probe.
209 round-trip-time TIME
213 The time which passed between the transmission of the
217 probe and its response. The time is provided as a inte‐
218 gral number of microseconds elapsed.
219 no-reply
223 No response to the probe request was received before the timeout
224 expired.
225 ttl-expired
227 The time-to-live value of the transmitted probe expired before
228 the probe arrived at its intended destination. Arguments of
229 ttl-expired are:
230 ip-4 IP-ADDRESS
234 The Internet Protocol version 4 address of the host at
238 which the time-to-live value expired.
239 ip-6 IP-ADDRESS
243 The Internet Protocol version 6 address of the host at
247 which the time-to-live value expired.
248 round-trip-time TIME
252 The time which passed between the transmission of the
256 probe and its response. The time is provided as a inte‐
257 gral number of microseconds elapsed.
258 mpls MPLS-LABEL-LIST
262 A list of Multiprotocol Label Switching values returned
266 with the probe response. If the mpls argument is
267 present, one or more MPLS labels will be represented by a
268 comma separated list of values. The values are provided
269 in groups of four. The first four values in the list
270 correspond to the first MPLS label, the next four values
271 correspond to the second MPLS label, and so on. The val‐
272 ues are provided in this order: label, traffic-class,
273 bottom-of-stack, ttl.
274 no-route
278 There was no route to the host used in a send-probe request.
279 network-down
281 A probe could not be sent because the network is down.
282 probes-exhausted
284 A probe could not be sent because there are already too many
285 unresolved probes in flight.
286 permission-denied
288 The operating system denied permission to send the probe with
289 the specified options.
290 invalid-argument
292 The command request contained arguments which are invalid.
293 feature-support
295 A reply to provided to check-support indicating the availability
296 of a particular feature. The argument provided is:
297 support PRESENT
301 In most cases, the PRESENT value will be either ok, indi‐
305 cating the feature is supported, or no, indicating no
306 support for the feature.
307 In the case that version is the requested FEATURE-NAME,
309 the version of mtr-packet is provided as the PRESENT
310 value.
311
315 A controlling program may start mtr-packet as a child process and issue
316 the following command on stdin:
317 42 send-probe ip-4 127.0.0.1
319 This will send a network probe to the loopback interface. When the
321 probe completes, mtr-packet will provide a response on stdout such as
322 the following:
323 42 reply ip-4 127.0.0.1 round-trip-time 126
325 This indicates that the loopback address replied to the probe, and the
327 round-trip time of the probe was 126 microseconds.
328 In order to trace the route to a remote host, multiple send-probe com‐
330 mands, each with a different ttl value, are used.
331 11 send-probe ip-4 8.8.8.8 ttl 1
333 12 send-probe ip-4 8.8.8.8 ttl 2
334 13 send-probe ip-4 8.8.8.8 ttl 3
335 ...
336 Each intermediate host would respond with a ttl-expired message, and
338 the destination host would respond with a reply:
339 11 ttl-expired ip-4 192.168.254.254 round-trip-time 1634
341 12 ttl-expired ip-4 184.19.243.240 round-trip-time 7609
342 13 ttl-expired ip-4 172.76.20.169 round-trip-time 8643
343 14 ttl-expired ip-4 74.40.1.101 round-trip-time 9755
344 15 ttl-expired ip-4 74.40.5.126 round-trip-time 10695
345 17 ttl-expired ip-4 108.170.245.97 round-trip-time 14077
346 16 ttl-expired ip-4 74.40.26.131 round-trip-time 15253
347 18 ttl-expired ip-4 209.85.245.101 round-trip-time 17080
348 19 reply ip-4 8.8.8.8 round-trip-time 17039
349 Note that the replies in this example are printed out of order. (The
351 reply to probe 17 arrives prior to the reply to probe 16.) This is the
352 reason that it is important to send commands with unique token values,
353 and to use those token values to match replies with their originating
354 commands.
355
357 A Python 3.x package for sending asynchronous network probes using mtr-
358 packet is available. See ⟨https://pypi.org/project/mtrpacket/⟩
359
361 For the latest version, see the mtr web page at ⟨http://www.bitwizard.
362 nl/mtr/⟩
363 For patches, bug reports, or feature requests, please open an issue on
365 GitHub at: ⟨https://github.com/traviscross/mtr⟩.
366
368 mtr(8), icmp(7), tcp(7), udp(7), TCP/IP Illustrated (Stevens, ISBN
369 0201633469).
370mtr-packet 0.94 MTR-PACKET(8)