1MTR(8)                       System Administration                      MTR(8)
2
3
4

NAME

6       mtr - a network diagnostic tool
7

SYNOPSIS

9       mtr  [-4|-6]  [-F FILENAME]  [--report] [--report-wide] [--xml] [--gtk]
10       [--curses]  [--displaymode MODE]  [--raw]  [--csv]  [--json]  [--split]
11       [--no-dns] [--show-ips] [-o FIELDS] [-y IPINFO] [--aslookup] [-i INTER‐
12       VAL]  [-c COUNT]   [-s PACKETSIZE]   [-B BITPATTERN]   [-G GRACEPERIOD]
13       [-Q TOS]     [--mpls]    [-a ADDRESS]    [-f FIRST-TTL]    [-m MAX-TTL]
14       [-U MAX-UNKNOWN]  [--udp]  [--tcp]  [--sctp]  [-P PORT]  [-L LOCALPORT]
15       [-Z TIMEOUT] [-M MARK] HOSTNAME
16

DESCRIPTION

18       mtr combines the functionality of the traceroute and ping programs in a
19       single network diagnostic tool.
20
21       As mtr starts, it investigates the network connection between the  host
22       mtr  runs  on  and HOSTNAME by sending packets with purposely low TTLs.
23       It continues to send packets with low TTL, noting the response time  of
24       the  intervening  routers.   This allows mtr to print the response per‐
25       centage and response times of the internet route to HOSTNAME.  A sudden
26       increase  in  packet  loss or response time is often an indication of a
27       bad (or simply overloaded) link.
28
29       The results are usually reported as round-trip-response times  in  mil‐
30       liseconds and the percentage of packetloss.
31

OPTIONS

33       -h, --help
34              Print the summary of command line argument options.
35
36       -v, --version
37              Print the installed version of mtr.
38
39       -4     Use IPv4 only.
40
41       -6     Use IPv6 only.  (IPV4 may be used for DNS lookups.)
42
43       -F FILENAME, --filename FILENAME
44              Reads the list of hostnames from the specified file.
45
46       -r, --report
47              This  option  puts mtr into report mode.  When in this mode, mtr
48              will run for the number of cycles specified by  the  -c  option,
49              and then print statistics and exit.
50
51              This  mode  is  useful  for  generating statistics about network
52              quality.  Note that each running instance  of  mtr  generates  a
53              significant amount of network traffic.  Using mtr to measure the
54              quality of your network may result in decreased network  perfor‐
55              mance.
56
57       -w, --report-wide
58              This  option puts mtr into wide report mode.  When in this mode,
59              mtr will not cut hostnames in the report.
60
61       -x, --xml
62              Use this option to tell mtr to use the xml output format.   This
63              format is better suited for automated processing of the measure‐
64              ment results.
65
66       -t, --curses
67              Use this option to force mtr to use the  curses  based  terminal
68              interface  (if available).  In case the list of hops exceeds the
69              height of your terminal, you can use the + and - keys to  scroll
70              up and down half a page.
71
72              Ctrl-L  clears  spurious error messages that may overwrite other
73              parts of the display.
74
75
76       --displaymode MODE
77              Use this option to select the initial display mode: 0  (default)
78              selects  statistics,  1  selects  the stripchart without latency
79              information, and 2 selects the stripchart with latency  informa‐
80              tion.
81
82       -g, --gtk
83              Use  this  option  to force mtr to use the GTK+ based X11 window
84              interface (if available).  GTK+ must have been available on  the
85              system  when  mtr  was built for this to work.  See the GTK+ web
86              page at ⟨http://www.gtk.org/⟩ for more information about GTK+.
87
88       -l, --raw
89              Use the raw output format.  This format  is  better  suited  for
90              archival  of  the measurement results.  It could be parsed to be
91              presented into any of the other display methods.
92
93              Example of the raw output format:
94              h 0 10.1.1.1
95              p 0 339
96              h 1 46.149.16.4
97              p 1 530
98              h 2 172.31.1.16
99              p 2 531
100              h 3 82.221.168.236
101              p 3 1523
102              h 5 195.130.211.8
103              p 5 1603
104              h 6 193.4.58.17
105              p 6 1127
106              h 7 193.4.58.17
107              d 7 www.isnic.is
108
109       -C, --csv
110              Use the Comma-Separated-Value (CSV) output format.   (Note:  The
111              separator is actually a semi-colon ';'.)
112
113              Example of the CSV output format:
114              MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;1;r-76520-PROD.greenqloud.internal;288
115              MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;2;46.149.16.4;2086
116              MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;3;172.31.1.16;600
117              MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;4;82.221.168.236;1163
118              MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;5;???;0
119              MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;6;rix-k2-gw.isnic.is;1654
120              MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;7;www.isnic.is;1036
121
122       -j, --json
123              Use this option to tell mtr to use the JSON output format.  This
124              format is better suited for automated processing of the measure‐
125              ment results.
126
127       -p, --split
128              Use this option to set mtr to spit out a format that is suitable
129              for a split-user interface.
130
131       -n, --no-dns
132              Use this option to force mtr to display numeric IP  numbers  and
133              not try to resolve the host names.
134
135       -b, --show-ips
136              Use  this  option to tell mtr to display both the host names and
137              numeric IP numbers.  In split mode this adds an extra  field  to
138              the  output.   In report mode, there is usually too little space
139              to add the IPs, and they will be truncated.  Use the wide report
140              (-w) mode to see the IPs in report mode.
141
142       -o FIELDS, --order FIELDS
143              Use  this option to specify which fields to display and in which
144              order.  You may use one or more  space  characters  to  separate
145              fields.
146              Available fields:
147
148                                 ┌──┬─────────────────────┐
149                                 │L │ Loss ratio          │
150                                 ├──┼─────────────────────┤
151                                 │D │ Dropped packets     │
152                                 ├──┼─────────────────────┤
153                                 │R │ Received packets    │
154                                 ├──┼─────────────────────┤
155                                 │S │ Sent Packets        │
156                                 ├──┼─────────────────────┤
157                                 │N │ Newest RTT(ms)      │
158                                 ├──┼─────────────────────┤
159                                 │B │ Min/Best RTT(ms)    │
160                                 ├──┼─────────────────────┤
161                                 │A │ Average RTT(ms)     │
162                                 ├──┼─────────────────────┤
163                                 │W │ Max/Worst RTT(ms)   │
164                                 ├──┼─────────────────────┤
165                                 │V │ Standard Deviation  │
166                                 ├──┼─────────────────────┤
167                                 │G │ Geometric Mean      │
168                                 ├──┼─────────────────────┤
169                                 │J │ Current Jitter      │
170                                 ├──┼─────────────────────┤
171                                 │M │ Jitter Mean/Avg.    │
172                                 ├──┼─────────────────────┤
173                                 │X │ Worst Jitter        │
174                                 ├──┼─────────────────────┤
175                                 │I │ Interarrival Jitter │
176                                 └──┴─────────────────────┘
177              Example: -o "LSD NBAW  X"
178
179       -y n, --ipinfo n
180              Displays information about each IP hop.  Valid values for n are:
181
182              0   Display AS number (equivalent to -z)
183              1   Display IP prefix
184              2   Display country code of the origin AS
185              3   Display RIR (ripencc, arin, ...)
186              4   Display the allocation date of the IP prefix
187
188              It  is  possible to cycle between these fields at runtime (using
189              the y key).
190
191       -z, --aslookup
192              Displays the Autonomous System (AS) number alongside  each  hop.
193              Equivalent to --ipinfo 0.
194
195              Example (columns to the right not shown for clarity):
196              1. AS???   r-76520-PROD.greenqloud.internal
197              2. AS51969 46.149.16.4
198              3. AS???   172.31.1.16
199              4. AS30818 82.221.168.236
200              5. ???
201              6. AS???   rix-k2-gw.isnic.is
202              7. AS1850  www.isnic.is
203
204       -i SECONDS, --interval SECONDS
205              Use  this  option  to  specify  the  positive  number of seconds
206              between ICMP ECHO requests.  The default value for this  parame‐
207              ter is one second.  The root user may choose values between zero
208              and one.
209
210       -c COUNT, --report-cycles COUNT
211              Use this option to set the number of  pings  sent  to  determine
212              both  the  machines  on the network and the reliability of those
213              machines.  Each cycle lasts one second.
214
215       -s PACKETSIZE, --psize PACKETSIZE
216              This option sets the packet size used for  probing.   It  is  in
217              bytes, inclusive IP and ICMP headers.
218
219              If  set to a negative number, every iteration will use a differ‐
220              ent, random packet size up to that number.
221
222       -B NUM, --bitpattern NUM
223              Specifies bit pattern to use in payload.  Should be within range
224              0 - 255.  If NUM is greater than 255, a random pattern is used.
225
226       -G SECONDS, --gracetime SECONDS
227              Use  this  option  to  specify the positive number of seconds to
228              wait for responses after the final request. The default value is
229              five seconds.
230
231       -Q NUM, --tos NUM
232              Specifies  value for type of service field in IP header.  Should
233              be within range 0 - 255.
234
235       -e, --mpls
236              Use this option to tell mtr to  display  information  from  ICMP
237              extensions  for MPLS (RFC 4950) that are encoded in the response
238              packets.
239
240       -a ADDRESS, --address ADDRESS
241              Use this option to bind the outgoing socket to ADDRESS, so  that
242              all  packets  will be sent with ADDRESS as source address.  NOTE
243              that this option doesn't apply to DNS requests (which  could  be
244              and could not be what you want).
245
246       -f NUM, --first-ttl NUM
247              Specifies with what TTL to start.  Defaults to 1.
248
249       -m NUM, --max-ttl NUM
250              Specifies  the  maximum  number of hops (max time-to-live value)
251              traceroute will probe.  Default is 30.
252
253       -U NUM, --max-unknown NUM
254              Specifies the maximum unknown host. Default is 5.
255
256       -u, --udp
257              Use UDP datagrams instead of ICMP ECHO.
258
259       -T, --tcp
260              Use TCP  SYN  packets  instead  of  ICMP  ECHO.   PACKETSIZE  is
261              ignored, since SYN packets can not contain data.
262
263       -S, --sctp
264              Use Stream Control Transmission Protocol packets instead of ICMP
265              ECHO.
266
267       -P PORT, --port PORT
268              The target port number for TCP/SCTP/UDP traces.
269
270       -L LOCALPORT, --localport LOCALPORT
271              The source port number for UDP traces.
272
273       -Z SECONDS, --timeout SECONDS
274              The number of seconds to keep probe sockets open  before  giving
275              up  on  the connection.  Using large values for this, especially
276              combined with a short interval,  will  use  up  a  lot  of  file
277              descriptors.
278
279       -M MARK, --mark MARK
280              Set the mark for each packet sent through this socket similar to
281              the netfilter MARK target but socket-based.  MARK is 32 unsigned
282              integer.   See  socket(7)  for  full  description of this socket
283              option.
284

ENVIRONMENT

286       mtr recognizes a few environment variables.
287
288       MTR_OPTIONS
289              This environment variable allows to specify options, as if  they
290              were  passed  on  the command line.  It is parsed before reading
291              the actual command line options, so that  options  specified  in
292              MTR_OPTIONS are overridden by command-line options.
293
294              Example:
295
296              MTR_OPTIONS="-4 -c 1" mtr -6 localhost
297
298              would  send  one probe (because of -c 1) towards ::1 (because of
299              -6, which overrides the -4 passed in MTR_OPTIONS).
300
301       MTR_PACKET
302              A path to the mtr-packet executable, to be used for sending  and
303              receiving network probes.  If MTR_PACKET is unset, the PATH will
304              be used to search for an mtr-packet executable.
305
306       DISPLAY
307              Specifies an X11 server for the GTK+ frontend.
308

BUGS

310       Some modern routers give a lower priority to ICMP ECHO packets than  to
311       other  network traffic.  Consequently, the reliability of these routers
312       reported by mtr will be significantly lower than the actual reliability
313       of these routers.
314

CONTACT INFORMATION

316       For  the latest version, see the mtr web page at ⟨http://www.bitwizard.
317       nl/mtr/⟩
318
319       For patches, bug reports, or feature requests, please open an issue  on
320       GitHub at: ⟨https://github.com/traviscross/mtr⟩.
321

SEE ALSO

323       mtr-packet(8),  traceroute(8),  ping(8),  socket(7), TCP/IP Illustrated
324       (Stevens, ISBN 0201633469).
325
326
327
328mtr                                  0.92                               MTR(8)
Impressum