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]  [-I NAME]  [-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 packet loss.
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.   Jansson library must have been available on the
126              system when mtr was built for this to work.
127
128       -p, --split
129              Use this option to set mtr to spit out a format that is suitable
130              for a split-user interface.
131
132       -n, --no-dns
133              Use  this  option to force mtr to display numeric IP numbers and
134              not try to resolve the host names.
135
136       -b, --show-ips
137              Use this option to tell mtr to display both the host  names  and
138              numeric  IP  numbers.  In split mode this adds an extra field to
139              the output.  In report mode, there is usually too  little  space
140              to add the IPs, and they will be truncated.  Use the wide report
141              (-w) mode to see the IPs in report mode.
142
143       -o FIELDS, --order FIELDS
144              Use this option to specify which fields to display and in  which
145              order.   You  may  use  one or more space characters to separate
146              fields.
147              Available fields:
148
149                                 ┌──┬─────────────────────┐
150                                 │L │ Loss ratio          │
151                                 ├──┼─────────────────────┤
152                                 │D │ Dropped packets     │
153                                 ├──┼─────────────────────┤
154                                 │R │ Received packets    │
155                                 ├──┼─────────────────────┤
156                                 │S │ Sent Packets        │
157                                 ├──┼─────────────────────┤
158                                 │N │ Newest RTT(ms)      │
159                                 ├──┼─────────────────────┤
160                                 │B │ Min/Best RTT(ms)    │
161                                 ├──┼─────────────────────┤
162                                 │A │ Average RTT(ms)     │
163                                 ├──┼─────────────────────┤
164                                 │W │ Max/Worst RTT(ms)   │
165                                 ├──┼─────────────────────┤
166                                 │V │ Standard Deviation  │
167                                 ├──┼─────────────────────┤
168                                 │G │ Geometric Mean      │
169                                 ├──┼─────────────────────┤
170                                 │J │ Current Jitter      │
171                                 ├──┼─────────────────────┤
172                                 │M │ Jitter Mean/Avg.    │
173                                 ├──┼─────────────────────┤
174                                 │X │ Worst Jitter        │
175                                 ├──┼─────────────────────┤
176                                 │I │ Interarrival Jitter │
177                                 └──┴─────────────────────┘
178              Example: -o "LSD NBAW  X"
179
180       -y n, --ipinfo n
181              Displays information about each IP hop.  Valid values for n are:
182
183              0   Display AS number (equivalent to -z)
184              1   Display IP prefix
185              2   Display country code of the origin AS
186              3   Display RIR (ripencc, arin, ...)
187              4   Display the allocation date of the IP prefix
188
189              It is possible to cycle between these fields at  runtime  (using
190              the y key).
191
192       -z, --aslookup
193              Displays  the  Autonomous System (AS) number alongside each hop.
194              Equivalent to --ipinfo 0.
195
196              Example (columns to the right not shown for clarity):
197              1. AS???   r-76520-PROD.greenqloud.internal
198              2. AS51969 46.149.16.4
199              3. AS???   172.31.1.16
200              4. AS30818 82.221.168.236
201              5. ???
202              6. AS???   rix-k2-gw.isnic.is
203              7. AS1850  www.isnic.is
204
205       -i SECONDS, --interval SECONDS
206              Use this option  to  specify  the  positive  number  of  seconds
207              between  ICMP ECHO requests.  The default value for this parame‐
208              ter is one second.  The root user may choose values between zero
209              and one.
210
211       -c COUNT, --report-cycles COUNT
212              Use  this  option  to  set the number of pings sent to determine
213              both the machines on the network and the  reliability  of  those
214              machines.  Each cycle lasts one second.
215
216       -s PACKETSIZE, --psize PACKETSIZE
217              This  option  sets  the  packet size used for probing.  It is in
218              bytes, inclusive IP and ICMP headers.
219
220              If set to a negative number, every iteration will use a  differ‐
221              ent, random packet size up to that number.
222
223       -B NUM, --bitpattern NUM
224              Specifies bit pattern to use in payload.  Should be within range
225              0 - 255.  If NUM is greater than 255, a random pattern is used.
226
227       -G SECONDS, --gracetime SECONDS
228              Use this option to specify the positive  number  of  seconds  to
229              wait for responses after the final request. The default value is
230              five seconds.
231
232       -Q NUM, --tos NUM
233              Specifies value for type of service field in IP header.   Should
234              be within range 0 - 255.
235
236       -e, --mpls
237              Use  this  option  to  tell mtr to display information from ICMP
238              extensions for MPLS (RFC 4950) that are encoded in the  response
239              packets.
240
241       -I NAME, --interface NAME
242              Use  the network interface with a specific name for sending net‐
243              work probes.  This can be useful when you have multiple  network
244              interfaces  with  routes  to  your destination, for example both
245              wired Ethernet and WiFi, and wish to test  a  particular  inter‐
246              face.
247
248       -a ADDRESS, --address ADDRESS
249              Use  this option to bind the outgoing socket to ADDRESS, so that
250              all packets will be sent with ADDRESS as source  address.   NOTE
251              that  this  option doesn't apply to DNS requests (which could be
252              and could not be what you want).
253
254       -f NUM, --first-ttl NUM
255              Specifies with what TTL to start.  Defaults to 1.
256
257       -m NUM, --max-ttl NUM
258              Specifies the maximum number of hops  (max  time-to-live  value)
259              traceroute will probe.  Default is 30.
260
261       -U NUM, --max-unknown NUM
262              Specifies the maximum unknown host. Default is 5.
263
264       -u, --udp
265              Use UDP datagrams instead of ICMP ECHO.
266
267       -T, --tcp
268              Use  TCP  SYN  packets  instead  of  ICMP  ECHO.   PACKETSIZE is
269              ignored, since SYN packets can not contain data.
270
271       -S, --sctp
272              Use Stream Control Transmission Protocol packets instead of ICMP
273              ECHO.
274
275       -P PORT, --port PORT
276              The target port number for TCP/SCTP/UDP traces.
277
278       -L LOCALPORT, --localport LOCALPORT
279              The source port number for UDP traces.
280
281       -Z SECONDS, --timeout SECONDS
282              The  number  of seconds to keep probe sockets open before giving
283              up on the connection.  Using large values for  this,  especially
284              combined  with  a  short  interval,  will  use  up a lot of file
285              descriptors.
286
287       -M MARK, --mark MARK
288              Set the mark for each packet sent through this socket similar to
289              the netfilter MARK target but socket-based.  MARK is 32 unsigned
290              integer.  See socket(7) for  full  description  of  this  socket
291              option.
292

ENVIRONMENT

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

INTERACTIVE CONTROL

318       mtr can be controlled while it is running with the following keys:
319         ?|h     help
320         p       pause (SPACE to resume)
321         d       switching display mode
322         e       toggle MPLS information on/off
323         n       toggle DNS on/off
324         r       reset all counters
325         o str   set the columns to display, default str='LRS N BAWV'
326         j       toggle latency(LS NABWV)/jitter(DR AGJMXI) stats
327         c <n>   report cycle n, default n=infinite
328         i <n>   set the ping interval to n seconds, default n=1
329         f <n>   set the initial time-to-live(ttl), default n=1
330         m <n>   set the max time-to-live, default n= # of hops
331         s <n>   set the packet size to n or random(n<0)
332         b <c>   set ping bit pattern to c(0..255) or random(c<0)
333         Q <t>   set ping packet's TOS to t
334         u       switch between ICMP ECHO and UDP datagrams
335         y       switching IP info
336         z       toggle ASN info on/off
337         q       exit
338

BUGS

340       Some  modern routers give a lower priority to ICMP ECHO packets than to
341       other network traffic.  Consequently, the reliability of these  routers
342       reported by mtr will be significantly lower than the actual reliability
343       of these routers.
344

CONTACT INFORMATION

346       For the latest version, see the mtr web page at  ⟨http://www.bitwizard.
347       nl/mtr/⟩
348
349       For  patches, bug reports, or feature requests, please open an issue on
350       GitHub at: ⟨https://github.com/traviscross/mtr⟩.
351

SEE ALSO

353       mtr-packet(8), traceroute(8), ping(8),  socket(7),  TCP/IP  Illustrated
354       (Stevens, ISBN 0201633469).
355
356
357
358mtr                                  0.94                               MTR(8)
Impressum