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