Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 packet loss.

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.   Jansson library must have been available	on the
	      system when mtr was built	for this to work.

       -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.94				MTR(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | ENVIRONMENT | INTERACTIVE CONTROL | BUGS | CONTACT INFORMATION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=mtr&sektion=8&manpath=FreeBSD+Ports+13.0>

home | help