1MTR-PACKET(8)                System Administration               MTR-PACKET(8)
2
3
4
5
6

NAME

8       mtr-packet - send and receive network probes
9

DESCRIPTION

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
18       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
23              TOKEN COMMAND [ARGUMENT-NAME ARGUMENT-VALUE ...]
24
25       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
31       COMMAND  is  a  string  identifying the command request type.  A common
32       command is send-probe, which will transmit one network probe.
33
34       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

REQUESTS

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
45              The following arguments may be used:
46
47              ip-4 IP-ADDRESS
48
49
50
51                     The Internet Protocol version 4 address to probe.
52
53
54
55              ip-6 IP-ADDRESS
56
57
58
59                     The Internet Protocol version 6 address to probe.
60
61
62
63              protocol PROTOCOL
64
65
66
67                     The  protocol  to use for the network probe.  icmp, sctp,
68                     tcp, and udp may be used.  The default protocol is icmp.
69
70
71
72              port PORT-NUMBER
73
74
75
76                     The destination port to use for sctp, tcp, or udp probes.
77
78
79
80              local-ip-4 IP-ADDRESS
81
82
83
84                     The local Internet Protocol version 4 address to use when
85                     sending probes.
86
87
88
89              local-ip-6 IP-ADDRESS
90
91
92
93                     The local Internet Protocol version 6 address to use when
94                     sending probes.
95
96
97
98              local-port PORT-NUMBER
99
100
101
102                     For udp probes, the local port number from which to  send
103                     probes.
104
105
106
107              timeout TIMEOUT-SECONDS
108
109
110
111                     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
115
116
117              ttl TIME-TO-LIVE
118
119
120
121                     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
127
128
129              size PACKET-SIZE
130
131
132
133                     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
137
138
139              bit-pattern PATTERN-VALUE
140
141
142
143                     The  packet  payload  is  filled  with bytes of the value
144                     specified.  Valid pattern  values  are  in  the  range  0
145                     through 255.
146
147
148
149              tos TYPE-OF-SERVICE
150
151
152
153                     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
157
158
159              mark ROUTING-MARK
160
161
162
163                     The  packet  mark value to be used by mark-based routing.
164                     (Available only on Linux.)
165
166
167
168       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
174
175
176              feature FEATURE-NAME
177
178
179
180                     The name of a feature requested.
181
182
183
184              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

REPLIES

189       reply  The  destination host received the send-probe probe and replied.
190              Arguments of reply are:
191
192
193
194              ip-4 IP-ADDRESS
195
196
197
198                     The Internet Protocol version 4 address of the host which
199                     replied to the probe.
200
201
202
203              ip-6 IP-ADDRESS
204
205
206
207                     The Internet Protocol version 6 address of the host which
208                     replied to the probe.
209
210
211
212              round-trip-time TIME
213
214
215
216                     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
220
221
222       no-reply
223              No response to the probe request was received before the timeout
224              expired.
225
226       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
231
232
233              ip-4 IP-ADDRESS
234
235
236
237                     The  Internet  Protocol  version 4 address of the host at
238                     which the time-to-live value expired.
239
240
241
242              ip-6 IP-ADDRESS
243
244
245
246                     The Internet Protocol version 6 address of  the  host  at
247                     which the time-to-live value expired.
248
249
250
251              round-trip-time TIME
252
253
254
255                     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
259
260
261              mpls MPLS-LABEL-LIST
262
263
264
265                     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
275
276
277       no-route
278              There was no route to the host used in a send-probe request.
279
280       network-down
281              A probe could not be sent because the network is down.
282
283       probes-exhausted
284              A  probe  could  not  be sent because there are already too many
285              unresolved probes in flight.
286
287       permission-denied
288              The operating system denied permission to send  the  probe  with
289              the specified options.
290
291       invalid-argument
292              The command request contained arguments which are invalid.
293
294       feature-support
295              A reply to provided to check-support indicating the availability
296              of a particular feature.  The argument provided is:
297
298
299
300              support PRESENT
301
302
303
304                     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
308                     In the case that version is the  requested  FEATURE-NAME,
309                     the  version  of  mtr-packet  is  provided as the PRESENT
310                     value.
311
312
313

EXAMPLES

315       A controlling program may start mtr-packet as a child process and issue
316       the following command on stdin:
317
318              42 send-probe ip-4 127.0.0.1
319
320       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
324              42 reply ip-4 127.0.0.1 round-trip-time 126
325
326       This  indicates that the loopback address replied to the probe, and the
327       round-trip time of the probe was 126 microseconds.
328
329       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
332              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
337       Each  intermediate  host  would respond with a ttl-expired message, and
338       the destination host would respond with a reply:
339
340              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
350       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

LANGUAGE BINDINGS

357       A Python 3.x package for sending asynchronous network probes using mtr-
358       packet is available.  See ⟨https://pypi.org/project/mtrpacket/
359

CONTACT INFORMATION

361       For  the latest version, see the mtr web page at ⟨http://www.bitwizard.
362       nl/mtr/⟩
363
364       For patches, bug reports, or feature requests, please open an issue  on
365       GitHub at: ⟨https://github.com/traviscross/mtr⟩.
366

SEE ALSO

368       mtr(8),  icmp(7),  tcp(7),  udp(7),  TCP/IP  Illustrated (Stevens, ISBN
369       0201633469).
370
371
372
373mtr-packet                           0.94                        MTR-PACKET(8)
Impressum