MTR(8)



MTR(8)                       System Administration                      MTR(8)

NAME
       mtr - a network diagnostic tool

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

DESCRIPTION
       mtr combines the functionality of the traceroute and ping programs in a
       single network diagnostic tool.

       As mtr starts, it investigates the network connection between the  host
       mtr  runs  on  and HOSTNAME by sending packets with purposely low TTLs.
       It continues to send packets with low TTL, noting the response time  of
       the  intervening  routers.   This allows mtr to print the response per-
       centage and response times of the internet route to HOSTNAME.  A sudden
       increase  in  packet  loss or response time is often an indication of a
       bad (or simply overloaded) link.

       The results are usually reported as round-trip-response times  in  mil-
       liseconds and the percentage of packetloss.

OPTIONS
       -h, --help
              Print the summary of command line argument options.

       -v, --version
              Print the installed version of mtr.

       -4     Use IPv4 only.

       -6     Use IPv6 only.  (IPV4 may be used for DNS lookups.)

       -F FILENAME, --filename FILENAME
              Reads the list of hostnames from the specified file.

       -r, --report
              This  option  puts mtr into report mode.  When in this mode, mtr
              will run for the number of cycles specified by  the  -c  option,
              and then print statistics and exit.

       This mode is useful for generating statistics about network quality.
              Note  that  each running instance of mtr generates a significant
              amount of network traffic.  Using mtr to measure the quality  of
              your network may result in decreased network performance.

       -w, --report-wide
              This  option puts mtr into wide report mode.  When in this mode,
              mtr will not cut hostnames in the report.

       -x, --xml
              Use this option to tell mtr to use the xml output format.   This
              format is better suited for automated processing of the measure-
              ment results.

       -t, --curses
              Use this option to force mtr to use the  curses  based  terminal
              interface  (if available).  In case the list of hops exceeds the
              height of your terminal, you can use the + and - keys to  scroll
              up and down half a page.

              Ctrl-L  clears  spurious error messages that may overwrite other
              parts of the display.

       --displaymode MODE
              Use this option to select the initial display mode: 0  (default)
              selects statistics, 1 selects the stripchart without latency in-
              formation, and 2 selects the stripchart  with  latency  informa-
              tion.

       -g, --gtk
              Use  this  option  to force mtr to use the GTK+ based X11 window
              interface (if available).  GTK+ must have been available on  the
              system  when  mtr  was built for this to work.  See the GTK+ web
              page at <http://www.gtk.org/> for more information about GTK+.

       -l, --raw
              Use the raw output format.  This format  is  better  suited  for
              archival  of  the measurement results.  It could be parsed to be
              presented into any of the other display methods.

              Example of the raw output format:
              h 0 10.1.1.1
              p 0 339
              h 1 46.149.16.4
              p 1 530
              h 2 172.31.1.16
              p 2 531
              h 3 82.221.168.236
              p 3 1523
              h 5 195.130.211.8
              p 5 1603
              h 6 193.4.58.17
              p 6 1127
              h 7 193.4.58.17
              d 7 www.isnic.is

       -C, --csv
              Use the Comma-Separated-Value (CSV) output format.   (Note:  The
              separator is actually a semi-colon ';'.)

              Example of the CSV output format:
              MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;1;r-76520-PROD.greenqloud.internal;288
              MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;2;46.149.16.4;2086
              MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;3;172.31.1.16;600
              MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;4;82.221.168.236;1163
              MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;5;???;0
              MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;6;rix-k2-gw.isnic.is;1654
              MTR.0.86+git:16e39fc0;1435562787;OK;nic.is;7;www.isnic.is;1036

       -j, --json
              Use this option to tell mtr to use the JSON output format.  This
              format is better suited for automated processing of the measure-
              ment results.

       -p, --split
              Use this option to set mtr to spit out a format that is suitable
              for a split-user interface.

       -n, --no-dns
              Use this option to force mtr to display numeric IP  numbers  and
              not try to resolve the host names.

       -b, --show-ips
              Use  this  option to tell mtr to display both the host names and
              numeric IP numbers.  In split mode this adds an extra  field  to
              the  output.   In report mode, there is usually too little space
              to add the IPs, and they will be truncated.  Use the wide report
              (-w) mode to see the IPs in report mode.

       -o FIELDS, --order FIELDS
              Use  this option to specify which fields to display and in which
              order.  You may use one or more  space  characters  to  separate
              fields.
              Available fields:

                                 +--+---------------------+
                                 |L | Loss ratio          |
                                 +--+---------------------+
                                 |D | Dropped packets     |
                                 +--+---------------------+
                                 |R | Received packets    |
                                 +--+---------------------+
                                 |S | Sent Packets        |
                                 +--+---------------------+
                                 |N | Newest RTT(ms)      |
                                 +--+---------------------+
                                 |B | Min/Best RTT(ms)    |
                                 +--+---------------------+
                                 |A | Average RTT(ms)     |
                                 +--+---------------------+
                                 |W | Max/Worst RTT(ms)   |
                                 +--+---------------------+
                                 |V | Standard Deviation  |
                                 +--+---------------------+
                                 |G | Geometric Mean      |
                                 +--+---------------------+
                                 |J | Current Jitter      |
                                 +--+---------------------+
                                 |M | Jitter Mean/Avg.    |
                                 +--+---------------------+
                                 |X | Worst Jitter        |
                                 +--+---------------------+
                                 |I | Interarrival Jitter |
                                 +--+---------------------+
              Example: -o "LSD NBAW  X"

       -y n, --ipinfo n
              Displays information about each IP hop.  Valid values for n are:

              0   Display AS number (equivalent to -z)
              1   Display IP prefix
              2   Display country code of the origin AS
              3   Display RIR (ripencc, arin, ...)
              4   Display the allocation date of the IP prefix

              It  is  possible to cycle between these fields at runtime (using
              the y key).

       -z, --aslookup
              Displays the Autonomous System (AS) number alongside  each  hop.
              Equivalent to --ipinfo 0.

              Example (columns to the right not shown for clarity):
              1. AS???   r-76520-PROD.greenqloud.internal
              2. AS51969 46.149.16.4
              3. AS???   172.31.1.16
              4. AS30818 82.221.168.236
              5. ???
              6. AS???   rix-k2-gw.isnic.is
              7. AS1850  www.isnic.is

       -i SECONDS, --interval SECONDS
              Use  this  option  to specify the positive number of seconds be-
              tween ICMP ECHO requests.  The default value for this  parameter
              is one second.  The root user may choose values between zero and
              one.

       -c COUNT, --report-cycles COUNT
              Use this option to set the number of  pings  sent  to  determine
              both  the  machines  on the network and the reliability of those
              machines.  Each cycle lasts one second.

       -s PACKETSIZE, --psize PACKETSIZE
              This option sets the packet size used for  probing.   It  is  in
              bytes, inclusive IP and ICMP headers.

              If  set to a negative number, every iteration will use a differ-
              ent, random packet size up to that number.

       -B NUM, --bitpattern NUM
              Specifies bit pattern to use in payload.  Should be within range
              0 - 255.  If NUM is greater than 255, a random pattern is used.

       -G SECONDS, --gracetime SECONDS
              Use  this  option  to  specify the positive number of seconds to
              wait for responses after the final request. The default value is
              five seconds.

       -Q NUM, --tos NUM
              Specifies  value for type of service field in IP header.  Should
              be within range 0 - 255.

       -e, --mpls
              Use this option to tell mtr to display information from ICMP ex-
              tensions  for  MPLS  (RFC 4950) that are encoded in the response
              packets.

       -I NAME, --interface NAME
              Use the network interface with a specific name for sending  net-
              work  probes.  This can be useful when you have multiple network
              interfaces with routes to your  destination,  for  example  both
              wired  Ethernet  and  WiFi, and wish to test a particular inter-
              face.

       -a ADDRESS, --address ADDRESS
              Use this option to bind the outgoing socket to ADDRESS, so  that
              all  packets  will be sent with ADDRESS as source address.  NOTE
              that this option doesn't apply to DNS requests (which  could  be
              and could not be what you want).

       -f NUM, --first-ttl NUM
              Specifies with what TTL to start.  Defaults to 1.

       -m NUM, --max-ttl NUM
              Specifies  the  maximum  number of hops (max time-to-live value)
              traceroute will probe.  Default is 30.

       -U NUM, --max-unknown NUM
              Specifies the maximum unknown host. Default is 5.

       -u, --udp
              Use UDP datagrams instead of ICMP ECHO.

       -T, --tcp
              Use TCP SYN packets instead of ICMP  ECHO.   PACKETSIZE  is  ig-
              nored, since SYN packets can not contain data.

       -S, --sctp
              Use Stream Control Transmission Protocol packets instead of ICMP
              ECHO.

       -P PORT, --port PORT
              The target port number for TCP/SCTP/UDP traces.

       -L LOCALPORT, --localport LOCALPORT
              The source port number for UDP traces.

       -Z SECONDS, --timeout SECONDS
              The number of seconds to keep probe sockets open  before  giving
              up  on  the connection.  Using large values for this, especially
              combined with a short interval, will use up a lot  of  file  de-
              scriptors.

       -M MARK, --mark MARK
              Set the mark for each packet sent through this socket similar to
              the netfilter MARK target but socket-based.  MARK is 32 unsigned
              integer.   See socket(7) for full description of this socket op-
              tion.

ENVIRONMENT
       mtr recognizes a few environment variables.

       MTR_OPTIONS
              This environment variable allows one to specify options,  as  if
              they were passed on the command line.  It is parsed before read-
              ing the actual command line options, so that  options  specified
              in MTR_OPTIONS are overridden by command-line options.

              Example:

              MTR_OPTIONS="-4 -c 1" mtr -6 localhost

              would  send  one probe (because of -c 1) towards ::1 (because of
              -6, which overrides the -4 passed in MTR_OPTIONS).

       MTR_PACKET
              A path to the mtr-packet executable, to be used for sending  and
              receiving network probes.  If MTR_PACKET is unset, the PATH will
              be used to search for an mtr-packet executable.

       DISPLAY
              Specifies an X11 server for the GTK+ frontend.

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

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

CONTACT INFORMATION
       For  the latest version, see the mtr web page at <http://www.bitwizard.
       nl/mtr/>

       For patches, bug reports, or feature requests, please open an issue  on
       GitHub at: <https://github.com/traviscross/mtr>.

SEE ALSO
       mtr-packet(8),  traceroute(8),  ping(8),  socket(7), TCP/IP Illustrated
       (Stevens, ISBN 0201633469).

mtr                                  0.93                               MTR(8)

Man(1) output converted with man2html
list of all man pages