1: .TH MTR 8 "0.87.203-0e5e" "mtr" "System Administration"
2: .SH NAME
3: mtr \- a network diagnostic tool
4: .SH SYNOPSIS
5: .B mtr
6: [\c
7: .BR \-4 |\c
8: .B \-6\c
9: ]
10: [\c
11: .BI \-F \ FILENAME\c
12: ]
13: [\c
14: .B \-\-report\c
15: ]
16: [\c
17: .B \-\-report-wide\c
18: ]
19: [\c
20: .B \-\-xml\c
21: ]
22: [\c
23: .B \-\-gtk\c
24: ]
25: [\c
26: .B \-\-curses\c
27: ]
28: [\c
29: .BI \--displaymode \ MODE\c
30: ]
31: [\c
32: .B \-\-raw\c
33: ]
34: [\c
35: .B \-\-csv\c
36: ]
37: [\c
38: .B \-\-json\c
39: ]
40: [\c
41: .B \-\-split\c
42: ]
43: [\c
44: .B \-\-no-dns\c
45: ]
46: [\c
47: .B \-\-show-ips\c
48: ]
49: [\c
50: .BI \-o \ FIELDS\c
51: ]
52: [\c
53: .BI \-y \ IPINFO\c
54: ]
55: [\c
56: .B \-\-aslookup\c
57: ]
58: [\c
59: .BI \-i \ INTERVAL\c
60: ]
61: [\c
62: .BI \-c \ COUNT\c
63: ]
64: [\c
65: .BI \-s \ PACKETSIZE\c
66: ]
67: [\c
68: .BI \-B \ BITPATTERN\c
69: ]
70: [\c
71: .BI \-G \ GRACEPERIOD\c
72: ]
73: [\c
74: .BI \-Q \ TOS\c
75: ]
76: [\c
77: .B \-\-mpls\c
78: ]
79: [\c
80: .BI \-a \ ADDRESS\c
81: ]
82: [\c
83: .BI \-f \ FIRST\-TTL\c
84: ]
85: [\c
86: .BI \-m \ MAX\-TTL\c
87: ]
88: [\c
89: .BI \-U \ MAX\-UNKNOWN\c
90: ]
91: [\c
92: .B \-\-udp\c
93: ]
94: [\c
95: .B \-\-tcp\c
96: ]
97: [\c
98: .BI \-\-sctp\c
99: ]
100: [\c
101: .BI \-P \ PORT\c
102: ]
103: [\c
104: .BI \-L \ LOCALPORT\c
105: ]
106: [\c
107: .BI \-Z \ TIMEOUT\c
108: ]
109: [\c
110: .BI \-M \ MARK\c
111: ]
112: .I HOSTNAME
113: .SH DESCRIPTION
114: .B mtr
115: combines the functionality of the
116: .B traceroute
117: and
118: .B ping
119: programs in a single network diagnostic tool.
120: .PP
121: As
122: .B mtr
123: starts, it investigates the network connection between the host
124: .B mtr
125: runs on and
126: .BR HOSTNAME
127: by sending packets with purposely low TTLs. It continues to send
128: packets with low TTL, noting the response time of the intervening
129: routers. This allows
130: .B mtr
131: to print the response percentage and response times of the internet
132: route to
133: .BR HOSTNAME .
134: A sudden increase in packet loss or response time is often an indication
135: of a bad (or simply overloaded) link.
136: .PP
137: The results are usually reported as round-trip-response times in milliseconds
138: and the percentage of packetloss.
139: .SH OPTIONS
140: .TP
141: .B \-h\fR, \fB\-\-help
142: Print the summary of command line argument options.
143: .TP
144: .B \-v\fR, \fB\-\-version
145: Print the installed version of mtr.
146: .TP
147: .B \-4
148: Use IPv4 only.
149: .TP
150: .B \-6
151: Use IPv6 only. (IPV4 may be used for DNS lookups.)
152: .TP
153: .B \-F \fIFILENAME\fR, \fB\-\-filename \fIFILENAME
154: Reads the list of hostnames from the specified file.
155: .TP
156: .B \-r\fR, \fB\-\-report
157: This option puts
158: .B mtr
159: into
160: .B report
161: mode. When in this mode,
162: .B mtr
163: will run for the number of cycles specified by the
164: .B \-c
165: option, and then print statistics and exit.
166: .TP
167: \c
168: This mode is useful for generating statistics about network quality.
169: Note that each running instance of
170: .B mtr
171: generates a significant amount of network traffic. Using
172: .B mtr
173: to measure the quality of your network may result in decreased
174: network performance.
175: .TP
176: .B \-w\fR, \fB\-\-report\-wide
177: This option puts
178: .B mtr
179: into
180: .B wide report
181: mode. When in this mode,
182: .B mtr
183: will not cut hostnames in the report.
184: .TP
185: .B \-x\fR, \fB\-\-xml
186: Use this option to tell
187: .B mtr
188: to use the xml output format. This format is better suited for
189: automated processing of the measurement results.
190: .TP
191: .B \-t\fR, \fB\-\-curses
192: Use this option to force
193: .B mtr
194: to use the curses based terminal
195: interface (if available).
196: In case the list of hops exceeds the
197: height of your terminal, you can use the
198: .B +
199: and
200: .B -
201: keys to scroll up and down half a page.
202:
203: .B Ctrl\fR-\fPL
204: clears spurious error messages that may overwrite other parts of the display.
205:
206: .TP
207: .B -\-displaymode \fIMODE
208: Use this option to select the initial display mode: 0 (default)
209: selects statistics, 1 selects the stripchart without latency
210: information, and 2 selects the stripchart with latency
211: information.
212: .TP
213: .B \-g\fR, \fB\-\-gtk
214: Use this option to force
215: .B mtr
216: to use the GTK+ based X11 window interface (if available).
217: GTK+ must have been available on the system when
218: .B mtr
219: was built for this to work. See the GTK+ web page at
220: .UR http://\:www.\:gtk.\:org/
221: .UE
222: for more information about GTK+.
223: .TP
224: .B \-l\fR, \fB\-\-raw
225: Use the raw output format. This format is better suited for
226: archival of the measurement results. It could be parsed to
227: be presented into any of the other display methods.
228: .IP
229: Example of the raw output format:
230: .nf
231: h 0 10.1.1.1
232: p 0 339
233: h 1 46.149.16.4
234: p 1 530
235: h 2 172.31.1.16
236: p 2 531
237: h 3 82.221.168.236
238: p 3 1523
239: h 5 195.130.211.8
240: p 5 1603
241: h 6 193.4.58.17
242: p 6 1127
243: h 7 193.4.58.17
244: d 7 www.isnic.is
245: .fi
246: .TP
247: .B \-C\fR, \fB\-\-csv
248: Use the Comma-Separated-Value (CSV) output format.
249: (Note: The separator is actually a semi-colon ';'.)
250: .IP
251: Example of the CSV output format:
252: .nf
253: MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;1;r-76520-PROD.greenqloud.internal;288
254: MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;2;46.149.16.4;2086
255: MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;3;172.31.1.16;600
256: MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;4;82.221.168.236;1163
257: MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;5;???;0
258: MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;6;rix-k2-gw.isnic.is;1654
259: MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;7;www.isnic.is;1036
260: .fi
261: .TP
262: .B \-j\fR, \fB\-\-json
263: Use this option to tell
264: .B mtr
265: to use the JSON output format. This format is better suited for
266: automated processing of the measurement results.
267: .TP
268: .B \-p\fR, \fB\-\-split
269: Use this option to set
270: .B mtr
271: to spit out a format that is suitable for a split-user interface.
272: .TP
273: .B \-n\fR, \fB\-\-no\-dns
274: Use this option to force
275: .B mtr
276: to display numeric IP numbers and not try to resolve the
277: host names.
278: .TP
279: .B \-b\fR, \fB\-\-show\-ips
280: Use this option to tell
281: .B mtr
282: to display both the host names and numeric IP numbers. In split mode
283: this adds an extra field to the output. In report mode, there is usually
284: too little space to add the IPs, and they will be truncated. Use the
285: wide report (-w) mode to see the IPs in report mode.
286: .TP
287: .B \-o \fIFIELDS\fR, \fB\-\-order \fIFIELDS
288: Use this option to specify which fields to display and in which order.
289: You may use one or more space characters to separate fields.
290: .br
291: Available fields:
292: .TS
293: center allbox tab(%);
294: ll.
295: L%Loss ratio
296: D%Dropped packets
297: R%Received packets
298: S%Sent Packets
299: N%Newest RTT(ms)
300: B%Min/Best RTT(ms)
301: A%Average RTT(ms)
302: W%Max/Worst RTT(ms)
303: V%Standard Deviation
304: G%Geometric Mean
305: J%Current Jitter
306: M%Jitter Mean/Avg.
307: X%Worst Jitter
308: I%Interarrival Jitter
309: .TE
310: .br
311:
312: Example:
313: -o "LSD NBAW X"
314: .TP
315: .B \-y \fIn\fR, \fB\-\-ipinfo \fIn
316: Displays information about each IP hop. Valid values for \fIn\fR are:
317: .TS
318: tab(%);
319: ll.
320: 0%Display AS number (equivalent to \fB-z\fR)
321: 1%Display IP prefix
322: 2%Display country code of the origin AS
323: 3%Display RIR (ripencc, arin, ...)
324: 4%Display the allocation date of the IP prefix
325: .TE
326: .br
327:
328: It is possible to cycle between these fields at runtime (using the \fBy\fR key).
329: .TP
330: .B \-z\fR, \fB\-\-aslookup
331: Displays the Autonomous System (AS) number alongside each hop. Equivalent to \fB\-\-ipinfo 0\fR.
332: .IP
333: Example (columns to the right not shown for clarity):
334: .nf
335: 1. AS??? r-76520-PROD.greenqloud.internal
336: 2. AS51969 46.149.16.4
337: 3. AS??? 172.31.1.16
338: 4. AS30818 82.221.168.236
339: 5. ???
340: 6. AS??? rix-k2-gw.isnic.is
341: 7. AS1850 www.isnic.is
342: .fi
343: .TP
344: .B \-i \fISECONDS\fR, \fB\-\-interval \fISECONDS
345: Use this option to specify the positive number of seconds between ICMP
346: ECHO requests. The default value for this parameter is one second. The
347: root user may choose values between zero and one.
348: .TP
349: .B \-c \fICOUNT\fR, \fB\-\-report\-cycles \fICOUNT
350: Use this option to set the number of pings sent to determine
351: both the machines on the network and the reliability of
352: those machines. Each cycle lasts one second.
353: .TP
354: .B \-s \fIPACKETSIZE\fR, \fB\-\-psize \fIPACKETSIZE
355: This option sets the packet size used for probing. It is in bytes,
356: inclusive IP and ICMP headers.
357:
358: If set to a negative number, every iteration will use a different, random
359: packet size up to that number.
360: .TP
361: .B \-B \fINUM\fR, \fB\-\-bitpattern \fINUM
362: Specifies bit pattern to use in payload. Should be within range 0 - 255. If
363: .I NUM
364: is greater than 255, a random pattern is used.
365: .TP
366: .B \-G \fISECONDS\fR, \fB\-\-gracetime \fISECONDS
367: Use this option to specify the positive number of seconds to wait for responses
368: after the final request. The default value is five seconds.
369: .TP
370: .B \-Q \fINUM\fR, \fB\-\-tos \fINUM
371: Specifies value for type of service field in IP header. Should be within range 0
372: - 255.
373: .TP
374: .B \-e\fR, \fB\-\-mpls
375: Use this option to tell
376: .B mtr
377: to display information from ICMP extensions for MPLS (RFC 4950)
378: that are encoded in the response packets.
379: .TP
380: .B \-a \fIADDRESS\fR, \fB\-\-address \fIADDRESS
381: Use this option to bind the outgoing socket to
382: .IR ADDRESS ,
383: so that all packets will be sent with
384: .I ADDRESS
385: as source address. NOTE that this option doesn't apply to DNS requests
386: (which could be and could not be what you want).
387: .TP
388: .B \-f \fINUM\fR, \fB\-\-first-ttl \fINUM
389: Specifies with what TTL to start. Defaults to 1.
390: .TP
391: .B \-m \fINUM\fR, \fB\-\-max-ttl \fINUM
392: Specifies the maximum number of hops (max time-to-live value) traceroute will
393: probe. Default is 30.
394: .TP
395: .B \-U \fINUM\fR, \fB\-\-max-unknown \fINUM
396: Specifies the maximum unknown host. Default is 5.
397: .TP
398: .B \-u\fR, \fB\-\-udp
399: Use UDP datagrams instead of ICMP ECHO.
400: .TP
401: .B \-T\fR, \fB\-\-tcp
402: Use TCP SYN packets instead of ICMP ECHO.
403: .I PACKETSIZE
404: is ignored, since SYN packets can not contain data.
405: .TP
406: .B \-S\fR, \fB\-\-sctp
407: Use Stream Control Transmission Protocol packets instead of ICMP ECHO.
408: .TP
409: .B \-P \fIPORT\fR, \fB\-\-port \fIPORT
410: The target port number for TCP/SCTP/UDP traces.
411: .TP
412: .B \-L \fILOCALPORT\fR, \fB\-\-localport \fILOCALPORT
413: The source port number for UDP traces.
414: .TP
415: .B \-Z \fISECONDS\fR, \fB\-\-timeout \fISECONDS
416: The number of seconds to keep probe sockets open before giving up on
417: the connection. Using large values for this, especially combined with
418: a short interval, will use up a lot of file descriptors.
419: .TP
420: .B \-M \fIMARK\fR, \fB\-\-mark \fIMARK
421: Set the mark for each packet sent through this socket similar to the
422: netfilter MARK target but socket-based.
423: .I MARK
424: is 32 unsigned integer. See
425: .BR socket (7)
426: for full description of this socket option.
427: .SH ENVIRONMENT
428: .B mtr
429: recognizes a few environment variables.
430: .TP
431: .B MTR_OPTIONS
432: This environment variable allows to specify options, as if they were
433: passed on the command line. It is parsed before reading the actual
434: command line options, so that options specified in
435: .B MTR_OPTIONS
436: are overridden by command-line options.
437:
438: Example:
439:
440: .BI MTR_OPTIONS ="-4\ -c\ 1"
441: .B mtr
442: .I \-6\ localhost
443:
444: would send one probe (because of
445: .I -c\ 1\c
446: ) towards
447: .B ::1
448: (because of
449: .IR -6 ,
450: which overrides the
451: .I -4
452: passed in
453: .B MTR_OPTIONS\c
454: ).
455: .TP
456: .B MTR_PACKET
457: A path to the
458: .I mtr-packet
459: executable, to be used for sending and receiving network probes. If
460: .B MTR_PACKET
461: is unset, the
462: .B PATH
463: will be used to search for an
464: .I mtr-packet
465: executable.
466: .TP
467: .B DISPLAY
468: Specifies an X11 server for the GTK+ frontend.
469: .SH BUGS
470: Some modern routers give a lower priority to ICMP ECHO packets than
471: to other network traffic. Consequently, the reliability of these
472: routers reported by
473: .B mtr
474: will be significantly lower than the actual reliability of
475: these routers.
476: .SH CONTACT INFORMATION
477: .PP
478: For the latest version, see the mtr web page at
479: .UR http://\:www.\:bitwizard.\:nl/\:mtr/
480: .UE
481: .PP
482: For patches, bug reports, or feature requests, please open an issue on
483: GitHub at:
484: .UR https://\:github\:.com/\:traviscross/\:mtr
485: .UE .
486: .SH "SEE ALSO"
487: .BR mtr-packet (8),
488: .BR traceroute (8),
489: .BR ping (8),
490: .BR socket (7),
491: TCP/IP Illustrated (Stevens, ISBN 0201633469).
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to mtr.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