mtr.8.in

.ds o6 "46
.ds oe "e
.ds og "g
.ds on "n
.ds oN "N
.ds oo "o
.ds oor "r
.ds oot "t
.ds ooc "c
.ds ooj "j
.ds oox "x
.ds op "p
.ds oq "q
.ds oy "yz
.Dd $Mdocdate$
.Dt MTR 8 SMM
.Os
.Sh NAME
.Nm mtr
.Nd a network diagnostic tool
.Sh SYNOPSIS
.Nm
.Op Fl a\*[on b]Bcd\*[oe]fF\*[og]im\*[on]\*[oN]\*[oo]\*[op]\*[oq]rsStTuvwx\*[oy]\*[o6]
TARGET[:PORT] ...
.Sh DESCRIPTION
.Nm
combines the functionality of the
.Sy traceroute
and
.Sy ping
programs in a single network diagnostic tool.
.Pp
As
.Nm
starts, it investigates the network connection between the host
.Nm
runs on and
.Sy TARGET
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
.Nm
to print the response percentage and response times of the internet route to
.Sy TARGET .
A sudden increase in packet loss or response time is often an indication of a bad (or simply overloaded) link.
.Pp
The results are usually reported as round-trip-response times in milliseconds and the percentage of packetloss.
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl a, Fl -address Ar IPADDRESS
Bind outgoing packets' socket to specific interface, so that any packet will be sent through this interface.
.Sy Note
that this option doesn't apply to DNS requests (which could be and could not be what you want).
.ie "b"\*[on b]" \{\
.It Fl b, Fl -show-ips
Display both hostnames and IP addresses.  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 mode
.Fl w
to see the IPs in report mode.
.\}
.It Fl B, Fl -bitpattern Ar NUM
Specify bit pattern to use in payload.  Should be either within range 0-255, or -1 for random sampling.
.It Fl c, Fl -cycles Ar COUNT
Set number of ping cycles.  Duration of one cycle is set with interval option
.Sy -i ,
one second by default.
.It Fl d, Fl -display Ar MODE
Choose the initial display mode
.Bl -tag -offset Ds
.It Cm 1st and 2nd bits
.br
.Sy 0
default
.br
.Sy 1
without latency information
.br
.Sy 2
with latency information
.br
.Sy 3
unicode histogram
.El
.Bl -tag -offset Ds
.It Cm 3rd bit
reserved
.It Cm 4th bit
color/mono mode, on/off
.It Cm 5th bit
audible bell (beep), on/off
.It Cm 6th bit
visible bell (flash), on/off
.It Cm 7th bit
bell for target host only, on/off
.El
.ie "e"\*[oe]" \{\
.It Fl e, Fl -mpls
Display MPLS information encoded in response packets
.\}
.It Fl f, Fl -first-ttl Ar NUM
Specify initial TTL to start.  Default is 1, `a' means auto (corresponding to TTL of the destination host).
.It Fl F, Fl -fields Ar DISPLAY-FIELDS
Specify fields to display and their order
.Pp
Available fields:
.Bl -tag -offset Ds -compact
.It Cm L
Loss ratio, %
.It Cm D
Dropped packets
.It Cm R
Received packets
.It Cm S
Sent Packets
.It Cm N
Newest RTT, msec
.It Cm B
Min/Best RTT, msec
.It Cm A
Average RTT, msec
.It Cm W
Max/Worst RTT, msec
.It Cm V
Standard Deviation
.It Cm G
Geometric Mean
.It Cm J
Current Jitter
.It Cm M
Jitter Mean/Average
.It Cm X
Worst Jitter
.It Cm I
Interarrival Jitter
.It Cm _
<space>
.El
.sp 2
Examples:
.Bl -tag -offset Ds -compact
.It Cm -F LS_NABWV
.It Cm -F DR_AGJMXI
.El
.ie "g"\*[og]" \{\
.It Fl g, Fl -graph Ar ARGUMENTS
Draw simple graphs
.Pp
Available arguments by order:
.Bl -tag -offset Ds
.It Cm 1st arg: graph type
1=dot 2=line 3=curve (default 3, curve)
.It Cm 2nd arg: viewport period
in 10sec ticks (default 6, i.e. 60sec)
.It Cm 3rd arg: legend on/off
0=disable 1=enable (default 1)
.It Cm 4th arg: multipath on/off
0=disable 1=enable (default 1)
.It Cm 5th arg: latency or jitter graph
0=latency 1=jitter (default 0, latency)
.El
.sp
Note: `,' (comma) is used as the separator
.sp
Examples:
.Bl -tag -width indent-two -offset Ds -compact
.It Cm -g,
all args in default (curve, 1min, legend, multipath, latency)
.It Cm -g2
line, default, default, default, default
.It Cm -g,30,,0
default, 5min, default, disable, default
.El
.\}
.It Fl i, Fl -interval Ar SECONDS
Set number of seconds between ICMP ECHO requests.  Default is 1.
.It Fl m, Fl -max-ttl Ar NUM
Specify maximum number of hops (max time-to-live value) traceroute will probe.  Default is 30.
.ie "n"\*[on]" \{\
.It Fl n, Fl -no-dns
Don't resolve IP addresses
.ie "N"\*[oN]" \{\
.It Fl N, Fl -ns Ar NSADDRESS[:PORT]
Specify nameserver instead of ones defined in
.Sy resolv.conf
.\}
.\}
.ie "o"\*[oo]" \{\
.It Fl o, Fl -output Ar \*[oor] \*[oot] \*[ooc] \*[ooj] \*[oox]
Use one of these suboptions to get
.ie "r"\*[oor]" \{RAW\}
.ie "t"\*[oot]" \{TXT\}
.ie "c"\*[ooc]" \{CSV\}
.ie "j"\*[ooj]" \{JSON\}
.ie "x"\*[oox]" \{XML\}
formatted output respectively
.\}
.ie "p"\*[op]" \{\
.It Fl p, Fl -split
Split out a format that is suitable for a split-user interface
.\}
.ie "q"\*[oq]" \{\
.It Fl q, Fl -tos Ar NUM
Set value for type of service (ToS) field in IP header.  Should be within range 0-255.
.\}
.It Fl r, Fl -report
This option puts
.Nm
into report mode.  When in this mode,
.Nm
will run for the number of cycles specified by the
.Fl c
option, and then print statistics and exit.
.sp
This mode is useful for generating statistics about network quality.
.sp
Note that each running instance of
.Nm
generates a significant amount of network traffic.  Using
.Nm
to measure the quality of your network may result in decreased network performance.
.It Fl s, Fl -psize Ar BYTES
Set packet size used for probing.  It is in bytes inclusive IP and ICMP headers.
.sp
Set it to a negative VALUE to randomize in a range of [28, -VALUE].
.It Fl S, Fl -summary
Print send/receive summary at exit
.It Fl t, Fl -tcp
Use TCP SYN packets instead of ICMP ECHO
.It Fl T, Fl -timeout Ar SECONDS
The number of seconds (minimum 1, maximum 60) to keep the TCP socket open before giving up on the connection.  This will only affect the final hop.  Using large values for this, will use up a lot of file descriptors.
.It Fl u, Fl -udp
Use UDP datagrams instead of ICMP ECHO
.It Fl v, Fl -version
.br
Print
.Nm
version and build options
.It Fl w, Fl -wide
This option puts
.Nm
into wide report mode.  When in this mode,
.Nm
will not cut hostnames in the report.
.It Fl x, Fl -cache Ar SECONDS
Cache mode. Don't ping known hops during cache-timeout period (0 means default 60 seconds).
.ie "yz"\*[oy]" \{\
.It Fl y, Fl -ipinfo Ar ORIGIN,FIELDS
Specify IP info origin and its fields
.Pp
Available origins and their fields:
.Bl -tag -width indent -offset Ds
.It Cm 1 - origin.asn.cymru.com (both IPv4 and IPv6)
ASN, Route, CC, Registry, Allocated
.It Cm 2 - riswhois.ripe.net (both IPv4 and IPv6)
Route, Origin, Descr, CC
.It Cm 3 - peer.asn.shadowserver.org
Peers, ASN, Route, AS Name, CC, Org
.It Cm 4 - origin.asn.spameatingmonkey.net
Route, ASN, Org, Allocated, CC
.It Cm 5 - ip-api.com
Country, CC, RC, Region, City, Zip, Lat, Long, TZ, ISP, Org, AS Name
.It Cm 6 - asn.routeviews.org
ASN
.El
.sp
Abbreviations:
.Bl -tag -width indent-two -offset Ds -compact
.It Cm TZ
TimeZone
.It Cm Org
Organization
.It Cm DMA
Designated Market Area
.It Cm CC/RC/MC/LC
Country/Region/Metro/Local Code
.El
.sp
Examples:
.Bl -tag -width indent-two -offset Ds -compact
.It Cm -y5,2,5,7,8
ip-api.com: CC City Lat Long
.It Cm -y2,4,2
riswhois.ripe.net: CC Origin
.It Cm -y,
origin.asn.cymru.com: ASN
.El
.It Fl z, Fl -aslookup
Turn on ASN lookups. The data source is
.Lk riswhois.ripe.net
.\}
.ie "46"\*[o6]" \{\
.It Fl 4
Use IPv4 only
.It Fl 6
Use IPv6 only
.\}
.El
.Sh 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
.Nm
will be significantly lower than the actual reliability of these routers.
.Sh CONTACT INFORMATION
.Pp
.Pp
For more information about
.Nm
diagnostic tool, see web page at
.Lk http://www.bitwizard.nl/mtr
.Pp
Project's location is
.Lk https://github.com/traviscross/mtr
.Pp
This version is built from
.Lk https://github.com/yvs2014/mtr085
fork
.Sh "SEE ALSO"
ping(8), traceroute(8)