Annotation of embedaddon/mtr/mtr-packet.8, revision 1.1.1.1
1.1 misho 1: .TH MTR-PACKET 8 "0.87.203-0e5e" "mtr-packet" "System Administration"
2: .HP 7
3: .SH NAME
4: mtr-packet - send and receive network probes
5: .SH DESCRIPTION
6: .B mtr-packet
7: is a tool for sending network probes to measure network connectivity and
8: performance. Many network probes can be sent simultaneously by a single
9: process instance of
10: .B mtr-packet
11: and additional probes can be generated by an instance of
12: .B mtr-packet
13: which already has network probes in flight. It is intended to be used
14: by programs which invoke it with Unix pipes attached to its standard input
15: and output streams.
16: .LP
17: .B mtr-packet
18: reads command requests from
19: .IR stdin ,
20: each separated by a newline character, and responds with command replies to
21: .IR stdout ,
22: also each separated by a newline character. The syntactic structure of
23: requests and replies are the same. The following format is used:
24: .LP
25: .RS
26: .I TOKEN
27: .I COMMAND
28: [\c
29: .I ARGUMENT-NAME
30: .I ARGUMENT-VALUE
31: \&...]
32: .RE
33: .LP
34: .I TOKEN
35: is a unique integer value. The same value will be used as the
36: .I TOKEN
37: for the response. This is necessary for associating replies with requests,
38: as commands may be completed in a different order than they are requested.
39: The invoker of
40: .B mtr-packet
41: should always use the
42: .I TOKEN
43: value to determine which command request has completed.
44: .LP
45: .I COMMAND
46: is a string identifying the command request type. A common command is
47: .BR send-probe ,
48: which will transmit one network probe.
49: .LP
50: .I ARGUMENT-NAME
51: strings and
52: .I ARGUMENT-VALUE
53: strings always come in pairs. It is a syntactic error to provide an
54: .I ARGUMENT-NAME
55: without a corresponding
56: .IR ARGUMENT-VALUE .
57: Valid
58: .I ARGUMENT-NAME
59: strings depend on the
60: .I COMMAND
61: being used.
62: .SH REQUESTS
63: .TP
64: .B send-probe
65: Send a network probe to a particular IP address. Either an
66: .B ip-4
67: or
68: .B ip-6
69: argument must be provided.
70: A valid
71: .B send-probe
72: command will reply with
73: .BR reply ,
74: .BR no-reply ,
75: or
76: .BR ttl-expired .
77: .IP
78: The following arguments may be used:
79: .IP
80: .B ip-4
81: .I IP-ADDRESS
82: .HP 14
83: .IP
84: The Internet Protocol version 4 address to probe.
85: .HP 7
86: .IP
87: .B ip-6
88: .I IP-ADDRESS
89: .HP 14
90: .IP
91: The Internet Protocol version 6 address to probe.
92: .HP 7
93: .IP
94: .B protocol
95: .I PROTOCOL
96: .HP 14
97: .IP
98: The protocol to use for the network probe.
99: .BR icmp ,
100: .BR sctp ,
101: .BR tcp ,
102: and
103: .B udp
104: may be used. The default protocol is
105: .BR icmp.
106: .HP 7
107: .IP
108: .B port
109: .I PORT-NUMBER
110: .HP 14
111: .IP
112: The destination port to use for
113: .BR sctp ,
114: .BR tcp ,
115: or
116: .B udp
117: probes.
118: .HP 7
119: .IP
120: .B local-ip-4
121: .I IP-ADDRESS
122: .HP 14
123: .IP
124: The local Internet Procol version 4 address to use when sending probes.
125: .HP 7
126: .IP
127: .B local-ip-6
128: .I IP-ADDRESS
129: .HP 14
130: .IP
131: The local Internet Protocol version 6 address to use when sending probes.
132: .HP 7
133: .IP
134: .B local-port
135: .I PORT-NUMBER
136: .HP 14
137: .IP
138: For
139: .B udp
140: probes, the local port number from which to send probes.
141: .HP 7
142: .IP
143: .B timeout
144: .I TIMEOUT-SECONDS
145: .HP 14
146: .IP
147: The number of seconds to wait for a response to the probe before discarding
148: the probe as lost, and generating a
149: .B no-reply
150: command reply.
151: .HP 7
152: .IP
153: .B ttl
154: .I TIME-TO-LIVE
155: .HP 14
156: .IP
157: The time-to-live value for the Internet Protocol packet header used in
158: constructing the probe. This value determines the number of network hops
159: through which the probe will travel before a response is generated by an
160: intermediate network host.
161: .HP 7
162: .IP
163: .B size
164: .I PACKET-SIZE
165: .HP 14
166: .IP
167: The size of the packet used to send the probe, in bytes, including the
168: Internet Protocol header and transport protocol header.
169: .HP 7
170: .IP
171: .B bit-pattern
172: .I PATTERN-VALUE
173: .HP 14
174: .IP
175: The packet payload is filled with bytes of the value specified.
176: Valid pattern values are in the range 0 through 255.
177: .HP 7
178: .IP
179: .IP
180: .B tos
181: .I TYPE-OF-SERVICE
182: .HP 14
183: .IP
184: In the case of IPv4, the "type of service" field in the IP header
185: is set to this value. In the case of IPv6, the "traffic class"
186: field is set.
187: .HP 7
188: .IP
189: .B mark
190: .I ROUTING-MARK
191: .HP 14
192: .IP
193: The packet mark value to be used by mark-based routing.
194: (Available only on Linux.)
195: .HP 7
196: .TP
197: .B check-support
198: Check for support for a particular feature in this version of
199: .B mtr-packet
200: and in this particular operating environment.
201: .B check-support
202: will reply with
203: .BR feature-supported .
204: A
205: .B feature
206: argument is required.
207: .HP 7
208: .IP
209: .B feature
210: .I FEATURE-NAME
211: .HP 14
212: .IP
213: The name of a feature requested.
214: .HP 7
215: .IP
216: Some features which can be checked are
217: .BR send-probe ,
218: .BR ip-4 ,
219: .BR ip-6 ,
220: .BR icmp ,
221: .BR sctp ,
222: .BR tcp ,
223: .BR udp ,
224: and
225: .BR mark .
226: The feature
227: .B version
228: can be checked to retrieve the version of
229: .BR mtr-packet .
230: .SH REPLIES
231: .TP
232: .B reply
233: The destination host received the
234: .B send-probe
235: probe and replied. Arguments of
236: .B reply
237: are:
238: .HP 7
239: .IP
240: .B ip-4
241: .I IP-ADDRESS
242: .HP 14
243: .IP
244: The Internet Protocol version 4 address of the host which replied
245: to the probe.
246: .HP 7
247: .IP
248: .B ip-6
249: .I IP-ADDRESS
250: .HP 14
251: .IP
252: The Internet Protocol version 6 address of the host which replied
253: to the probe.
254: .HP 7
255: .IP
256: .B round-trip-time
257: .I TIME
258: .HP 14
259: .IP
260: The time which passed between the transmission of the probe and its
261: response. The time is provided as a integral number of microseconds
262: elapsed.
263: .HP 7
264: .TP
265: .B no-reply
266: No response to the probe request was received before the timeout
267: expired.
268: .TP
269: .B ttl-expired
270: The time-to-live value of the transmitted probe expired before the probe
271: arrived at its intended destination. Arguments of
272: .B ttl-expired
273: are:
274: .HP 7
275: .IP
276: .B ip-4
277: .I IP-ADDRESS
278: .HP 14
279: .IP
280: The Internet Protocol version 4 address of the host at which the
281: time-to-live value expired.
282: .HP 7
283: .IP
284: .B ip-6
285: .I IP-ADDRESS
286: .HP 14
287: .IP
288: The Internet Protocol version 6 address of the host at which the
289: time-to-live value expired.
290: .HP 7
291: .IP
292: .B round-trip-time
293: .I TIME
294: .HP 14
295: .IP
296: The time which passed between the transmission of the probe and its
297: response. The time is provided as a integral number of microseconds
298: elapsed.
299: .HP 7
300: .IP
301: .B mpls
302: .I MPLS-LABEL-LIST
303: .HP 14
304: .IP
305: A list of Multiprotocol Label Switching values returned
306: with the probe response.
307: If the
308: .B mpls
309: argument is present, one or more MPLS labels will be represented by
310: a comma separated list of values. The values are provided in groups
311: of four. The first four values in the list correspond to the
312: first MPLS label, the next four values correspond to the second MPLS
313: label, and so on. The values are provided in this order:
314: .IR label ,
315: .IR experimental-use ,
316: .IR bottom-of-stack ,
317: .IR ttl .
318: .HP 7
319: .TP
320: .B no-route
321: There was no route to the host used in a
322: .B send-probe
323: request.
324: .TP
325: .B network-down
326: A probe could not be sent because the network is down.
327: .TP
328: .B probes-exhausted
329: A probe could not be sent because there are already too many unresolved
330: probes in flight.
331: .TP
332: .B permission-denied
333: The operating system denied permission to send the probe with the
334: specified options.
335: .TP
336: .B invalid-argument
337: The command request contained arguments which are invalid.
338: .TP
339: .B feature-support
340: A reply to provided to
341: .B check-support
342: indicating the availability of a particular feature. The argument provided
343: is:
344: .HP 7
345: .IP
346: .B support
347: .I PRESENT
348: .HP 14
349: .IP
350: In most cases, the
351: .I PRESENT
352: value will be either
353: .BR ok ,
354: indicating the feature is supported, or
355: .BR no ,
356: indicating no support for the feature.
357: .IP
358: In the case that
359: .B version
360: is the requested
361: .IR FEATURE-NAME ,
362: the version of
363: .B mtr-packet
364: is provided as the
365: .I PRESENT
366: value.
367: .HP 7
368: .IP
369: .SH EXAMPLES
370: A controlling program may start
371: .B mtr-packet
372: as a child process and issue the following command on
373: .IR stdin :
374: .LP
375: .RS
376: 42 send-probe ip-4 127.0.0.1
377: .RE
378: .LP
379: This will send a network probe to the loopback interface. When the probe
380: completes,
381: .B
382: mtr-packet
383: will provide a response on
384: .I stdout
385: such as the following:
386: .LP
387: .RS
388: 42 reply ip-4 127.0.0.1 round-trip-time 126
389: .RE
390: .LP
391: This indicates that the loopback address replied to the probe, and the
392: round-trip time of the probe was 126 microseconds.
393: .LP
394: In order to trace the route to a remote host, multiple
395: .B send-probe
396: commands, each with a different
397: .B ttl
398: value, are used.
399: .LP
400: .RS
401: 11 send-probe ip-4 8.8.8.8 ttl 1
402: .RS 0
403: 12 send-probe ip-4 8.8.8.8 ttl 2
404: .RS 0
405: 13 send-probe ip-4 8.8.8.8 ttl 3
406: .RS 0
407: \&...
408: .RE 0
409: .LP
410: Each interemediate host would respond with a
411: .B ttl-expired
412: message, and the destination host would respond with a
413: .BR reply :
414: .LP
415: .RS
416: 11 ttl-expired ip-4 192.168.254.254 round-trip-time 1634
417: .RS 0
418: 12 ttl-expired ip-4 184.19.243.240 round-trip-time 7609
419: .RS 0
420: 13 ttl-expired ip-4 172.76.20.169 round-trip-time 8643
421: .RS 0
422: 14 ttl-expired ip-4 74.40.1.101 round-trip-time 9755
423: .RS 0
424: 15 ttl-expired ip-4 74.40.5.126 round-trip-time 10695
425: .RS 0
426: 17 ttl-expired ip-4 108.170.245.97 round-trip-time 14077
427: .RS 0
428: 16 ttl-expired ip-4 74.40.26.131 round-trip-time 15253
429: .RS 0
430: 18 ttl-expired ip-4 209.85.245.101 round-trip-time 17080
431: .RS 0
432: 19 reply ip-4 8.8.8.8 round-trip-time 17039
433: .RE 0
434: .LP
435: Note that the replies in this example are printed out of order.
436: (The reply to probe 17 arrives prior to the reply to probe 16.)
437: This is the reason that it is important to send commands with unique
438: token values, and to use those token values to match replies with
439: their originating commands.
440: .SH CONTACT INFORMATION
441: .PP
442: For the latest version, see the mtr web page at
443: .UR http://\:www.\:bitwizard.\:nl/\:mtr/
444: .UE
445: .PP
446: For patches, bug reports, or feature requests, please open an issue on
447: GitHub at:
448: .UR https://\:github\:.com/\:traviscross/\:mtr
449: .UE .
450: .SH "SEE ALSO"
451: .BR mtr (8),
452: .BR icmp (7),
453: .BR tcp (7),
454: .BR udp (7),
455: TCP/IP Illustrated (Stevens, ISBN 0201633469).
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to mtr-packet.8 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / mtr