path: root/usr/src/man/man1m/traceroute.1m

'\" te
.\" Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH TRACEROUTE 1M "Dec 11, 2015"
.SH NAME
traceroute \- print the route packets take to network host
.SH SYNOPSIS
.LP
.nf
\fBtraceroute\fR [\fB-adFIlnSvx\fR] [\fB-A\fR \fIaddr_family\fR] [\fB-c\fR \fItraffic_class\fR]
     [\fB-f\fR \fIfirst_hop\fR] [\fB-g\fR \fIgateway\fR [\fB-g\fR \fIgateway\fR...] | \fB-r\fR]
     [\fB-i\fR \fIiface\fR] [\fB-L\fR \fIflow_label\fR] [\fB-m\fR \fImax_hop\fR]
     [\fB-P\fR \fIpause_sec\fR] [\fB-p\fR \fIport\fR] [\fB-Q\fR \fImax_timeout\fR]
     [\fB-q\fR \fInqueries\fR] [\fB-s\fR \fIsrc_addr\fR] [\fB-t\fR \fItos\fR] [\fB-w\fR \fIwait_time\fR] host
     [\fIpacketlen\fR]
.fi

.SH DESCRIPTION
.LP
The Internet is a large and complex aggregation of network hardware, connected
by gateways. Tracking the route a packet follows can be difficult. The utility
\fBtraceroute\fR traces the route that an \fBIP\fR packet follows to another
internet host.
.sp
.LP
The \fBtraceroute\fR utility utilizes the both the IPv4 and IPv6 protocols. Use
the \fB-A\fR option to override the default behavior. \fBtraceroute\fR uses the
IPv4 protocol \fIttl\fR (time to live) field or the IPv6 field \fIhop limit\fR.
It attempts to elicit an \fBICMP\fR or \fBICMP6\fR \fBTIME_EXCEEDED\fR response
from each \fIgateway\fR along the path, and a \fBPORT_UNREACHABLE\fR(or
\fBECHO_REPLY\fR if \fB-I\fR is used) response from the destination host. It
starts by sending probes with a \fIttl\fR or \fIhop limit\fR of \fB1\fR and
increases by \fB1\fR until it either gets to the host, or it hits the maximum
\fImax_hop\fR. The default maximum \fImax_hop\fR is 30 hops, but this can be
set by the \fB-m\fR option.
.sp
.LP
Three probes are sent at each \fIttl\fR (\fIhop limit\fR) setting, and a line
is printed showing the \fIttl\fR (\fIhop limit\fR), the hostname and the
address of the gateway, and the \fIrtt\fR (round trip time) of each probe. The
number of probes may be specifically set using the \fB-q\fR option. If the
probe answers come from different gateways, the hostname and the address of
each responding system will be printed. If there is no response within a 5
second timeout interval, an asterisk (\fB*\fR) is displayed for that probe. The
\fB-w\fR option may be used to set the timeout interval. Other possible
annotations that may appear after the time are:
.sp
.ne 2
.na
\fB\fB!\fR\fR
.ad
.sp .6
.RS 4n
the \fIttl\fR (\fIhop limit\fR) value in the received packet is \fB<= 1\fR\&.
.RE

.sp
.ne 2
.na
\fB\fB!H\fR\fR
.ad
.sp .6
.RS 4n
host unreachable.
.RE

.sp
.ne 2
.na
\fB\fB!X\fR\fR
.ad
.sp .6
.RS 4n
communication administratively prohibited.
.RE

.sp
.ne 2
.na
\fB\fB<!N>\fR\fR
.ad
.sp .6
.RS 4n
\fBICMP\fR (\fBICMP6\fR) unreachable code N.
.RE

.sp
.LP
The following annotations appear only for IPv4:
.sp
.ne 2
.na
\fB\fB!F\fR\fR
.ad
.sp .6
.RS 4n
fragmentation needed. This should never occur. If this is seen, the associated
gateway is broken.
.RE

.sp
.ne 2
.na
\fB\fB!N\fR\fR
.ad
.sp .6
.RS 4n
network unreachable.
.RE

.sp
.ne 2
.na
\fB\fB!P\fR\fR
.ad
.sp .6
.RS 4n
protocol unreachable.
.RE

.sp
.ne 2
.na
\fB\fB!S\fR\fR
.ad
.sp .6
.RS 4n
source route failed. It is likely that the gateway does not support source
routing.
.RE

.sp
.ne 2
.na
\fB\fB!T\fR\fR
.ad
.sp .6
.RS 4n
unreachable for the specified tos (type-of-service).
.RE

.sp
.ne 2
.na
\fB\fB!U\fR\fR
.ad
.sp .6
.RS 4n
source host isolated or precedence problem.
.RE

.sp
.LP
The following annotations appear only for IPv6:
.sp
.ne 2
.na
\fB\fB!A\fR\fR
.ad
.sp .6
.RS 4n
host unreachable for a reason other than lack of an entry in the routing table.
.RE

.sp
.ne 2
.na
\fB\fB!B\fR\fR
.ad
.sp .6
.RS 4n
packet too big.
.RE

.sp
.ne 2
.na
\fB\fB!E\fR\fR
.ad
.sp .6
.RS 4n
destination is not a neighbor.
.RE

.sp
.ne 2
.na
\fB\fB!R\fR\fR
.ad
.sp .6
.RS 4n
unrecognized next header.
.RE

.sp
.LP
If almost all the probes result in some kind of unreachable code, then
\fBtraceroute\fR gives up and exits.
.sp
.LP
The destination \fIhost\fR is not supposed to process the \fBUDP\fR probe
packets, so the destination \fIport\fR default is set to an unlikely value.
However, if some application on the destination is using that value, the value
of \fIport\fR can be changed with the \fB-p\fR option.
.sp
.LP
The only mandatory parameter is the destination \fIhost\fR name or \fBIP\fR
number. The default probe datagram length is 40 bytes (60 bytes for IPv6), but
this may be increased by specifying a packet length (in bytes) after the
destination \fIhost\fR name.
.sp
.LP
All integer arguments to \fBtraceroute\fR can be specified in either decimal or
hexadecimal notation. For example, \fIpacketlen\fR can be specified either as
\fB256\fR or \fB0x100\fR.
.SH OPTIONS
.ne 2
.na
\fB\fB-A\fR\ \fIaddr_family\fR\fR
.ad
.sp .6
.RS 4n
Specify the address family of the target host. \fIaddr_family\fR can be either
\fBinet\fR or \fBinet6\fR. Address family determines which protocol to use. For
an argument of \fBinet\fR, IPv4 is used. For \fBinet6\fR, IPv6 is used.
.sp
By default, if the name of a host is provided, not the literal \fBIP\fR
address, and a valid IPv6 address exists in the name service database,
\fBtraceroute\fR will use this address. Otherwise, if the name service database
contains an IPv4 address, it will try the IPv4 address.
.sp
Specify the address family \fBinet\fR or \fBinet6\fR to override the default
behavior. If the argument specified is \fBinet\fR, \fBtraceroute\fR will use
the IPv4 address associated with the hostname. If none exists, \fBtraceroute\fR
will state that the host is unknown and exit. It will not try to determine if
an IPv6 address exists in the name service database.
.sp
If the specified argument is \fBinet6\fR, \fBtraceroute\fR will use the IPv6
address that is associated with the hostname. If none exists, \fBtraceroute\fR
will state that the host is unknown and exit.
.RE

.sp
.ne 2
.na
\fB\fB-a\fR\fR
.ad
.sp .6
.RS 4n
Probe all of the addresses of a multi-homed destination. The output looks like
\fBtraceroute\fR has been run once for each \fBIP\fR address of the
destination. If this option is used together with \fB-A\fR, \fBtraceroute\fR
probes only the addresses that are of the specified address family. While
probing one of the addresses of the destination, user can skip to the next
address by sending a \fBSIGINT\fR, or exit \fBtraceroute\fR by sending a
\fBSIGQUIT\fR signal. See \fBsignal\fR(3C)
.RE

.sp
.ne 2
.na
\fB\fB-c\fR\ \fItraffic_class\fR\fR
.ad
.sp .6
.RS 4n
Specify the traffic class of probe packets. The value must be an integer in the
range from 0 to 255. Gateways along the path may route the probe packet
differently depending upon the value of \fItraffic_class\fR set in the probe
packet. This option is valid only on IPv6.
.RE

.sp
.ne 2
.na
\fB\fB-d\fR\fR
.ad
.sp .6
.RS 4n
Set the \fBSO_DEBUG\fR socket option.
.RE

.sp
.ne 2
.na
\fB\fB-F\fR\fR
.ad
.sp .6
.RS 4n
Set the "don't fragment" bit. This option is valid only on IPv4. When specified
from within a shared-IP zone, this option has no effect as the "don't fragment"
bit is always set in this case.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR \fIfirst_hop\fR\fR
.ad
.sp .6
.RS 4n
Set the starting \fIttl\fR ( \fIhop limit\fR) value to \fIfirst_hop\fR, to
override the default value \fB1\fR. \fBtraceroute\fR skips processing for those
intermediate gateways which are less than \fIfirst_hop\fR hops away.
.RE

.sp
.ne 2
.na
\fB\fB-g\fR \fIgateway\fR\fR
.ad
.sp .6
.RS 4n
Specify a loose source route \fIgateway\fR. The user can specify more than one
\fIgateway\fR by using \fB-g\fR for each gateway. The maximum number of
gateways is 8 for IPv4 and 127 for IPv6. Note that some factors such as the
link \fBMTU\fR can further limit the number of gateways for IPv6. This option
cannot be used with the \fB-r\fR option.
.sp
Only users with the \fB{PRIV_NET_RAWACCESS}\fR privilege can specify a loose
source route with this option.
.RE

.sp
.ne 2
.na
\fB\fB-I\fR\fR
.ad
.sp .6
.RS 4n
Use \fBICMP\fR (\fBICMP6\fR) \fBECHO\fR instead of \fBUDP\fR datagrams.
.RE

.sp
.ne 2
.na
\fB\fB-i\fR \fIiface\fR\fR
.ad
.sp .6
.RS 4n
For IPv4, this option specifies a network interface to obtain the source
\fBIP\fR address. This is normally only useful on a multi-homed host. The
\fB-s\fR option is also another way to do this. For IPv6, it specifies the
network interface on which probe packets are transmitted. The argument can be
either an interface index, for example, \fB1\fR, \fB2\fR, or an interface name,
for example, \fBeri0\fR, \fBhme0\fR.
.RE

.sp
.ne 2
.na
\fB\fB-L\fR\ \fIflow_label\fR\fR
.ad
.sp .6
.RS 4n
Specify the flow label of probe packets. The value must be an integer in the
range from 0 to 1048575. This option is valid only on IPv6.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR\fR
.ad
.sp .6
.RS 4n
Print the value of the \fIttl\fR (\fIhop limit\fR) field in each packet
received.
.RE

.sp
.ne 2
.na
\fB\fB-m\fR \fImax_hop\fR\fR
.ad
.sp .6
.RS 4n
Set the maximum \fIttl\fR (\fIhop limit\fR) used in outgoing probe packets. The
default is 30 hops, which is the same default used for \fBTCP \fR connections.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.sp .6
.RS 4n
Print hop addresses numerically rather than symbolically and numerically. This
saves a nameserver address-to-name lookup for each gateway found on the path.
.RE

.sp
.ne 2
.na
\fB\fB-P\fR \fIpause_sec\fR\fR
.ad
.sp .6
.RS 4n
Specify a delay, in seconds, to pause between probe packets. This may be
necessary if the final destination does not accept undeliverable packets in
bursts. By default, \fBtraceroute\fR sends the next probe as soon as it has
received a reply. Note that \fIpause_sec\fR is a real number.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR \fIport\fR\fR
.ad
.sp .6
.RS 4n
Set the base \fBUDP\fR \fIport\fR number used in probes.The default is 33434.
\fBtraceroute\fR hopes that nothing is listening on \fBUDP\fR \fIports\fR
\fB(base+(nhops-1)*nqueries)\fR to \fB(base+(nhops*nqueries)-1)\fRat the
destination host, so that an \fBICMP\fR (\fBICMP6\fR) \fBPORT_UNREACHABLE\fR
message will be returned to terminate the route tracing. If something is
listening on a \fIport\fR in the default range, this option can be used to
select an unused \fIport\fR range. \fBnhops\fR is defined as the number of hops
between the source and the destination.
.RE

.sp
.ne 2
.na
\fB\fB-Q\fR \fImax_timeout\fR\fR
.ad
.sp .6
.RS 4n
Stop probing this hop after \fImax_timeout\fR consecutive timeouts are
detected. The default value is 5. Useful in combination with the \fB-q\fR
option if you have specified a large \fInqueries\fR probe count.
.RE

.sp
.ne 2
.na
\fB\fB-q\fR \fInqueries\fR\fR
.ad
.sp .6
.RS 4n
Set the desired number of probe queries. The default is 3.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR\fR
.ad
.sp .6
.RS 4n
Bypass the normal routing tables and send directly to a host on an attached
network. If the host is not on a directly-attached network, an error is
returned. This option can be used to send probes to a local host through an
interface that has been dropped by the router daemon. See \fBin.routed\fR(1M).
You cannot use this option if the \fB-g\fR option is used.
.RE

.sp
.ne 2
.na
\fB\fB-S\fR\fR
.ad
.sp .6
.RS 4n
Display a summary of how many probes were not answered for each hop.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR \fIsrc_addr\fR\fR
.ad
.sp .6
.RS 4n
Use the following address, which usually is given as a literal \fBIP\fR
address, not a hostname, as the source address in outgoing probe packets. On
multi-homed hosts, those with more than one \fBIP\fR address, this option can
be used to force the source address to be something other than the \fBIP\fR
address \fBtraceroute\fR picks by default. If the \fBIP\fR address is not one
of this machine's interface addresses, an error is returned and nothing is
sent. For IPv4, when used together with the \fB-i\fR option, the given \fBIP\fR
address should be configured on the specified interface. Otherwise, an error
will be returned. In the case of IPv6, the interface name and the source
address do not have to match.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR \fItos\fR\fR
.ad
.sp .6
.RS 4n
Set the \fItos\fR(type-of-service) in probe packets to the specified value. The
default is zero. The value must be an integer in the range from 0 to 255.
Gateways along the path may route the probe packet differently depending upon
the \fItos\fR value set in the probe packet. This option is valid only on IPv4.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.sp .6
.RS 4n
Verbose output. For each hop, the size and the destination of the response
packets is displayed. Also \fBICMP\fR (\fBICMP6\fR) packets received other than
\fBTIME_EXCEEDED\fR and \fBUNREACHABLE\fR are listed as well.
.RE

.sp
.ne 2
.na
\fB\fB-w\fR \fIwaittime\fR\fR
.ad
.sp .6
.RS 4n
Set the time, in seconds, to wait for a response to a probe. The default is 5
seconds.
.RE

.sp
.ne 2
.na
\fB\fB-x\fR\fR
.ad
.sp .6
.RS 4n
Prevent \fBtraceroute\fR from calculating checksums. Checksums are usually
required for the last hop when using \fBICMP\fR \fBECHO\fR probes. This option
is valid only on IPv4. See the \fB-I\fR option.
.sp
When specified from within a shared-IP zone, this option has no effect as the
checksum is always calculated by the operating system in this case.
.RE

.SH OPERANDS
.LP
The following operands are supported:
.sp
.ne 2
.na
\fB\fIhost\fR\fR
.ad
.sp .6
.RS 4n
The network host.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRSample Output From the \fBtraceroute\fR Utility
.sp
.LP
Some sample output from the \fBtraceroute\fR utility might be:

.sp
.in +2
.nf
istanbul% \fBtraceroute london\fR
traceroute: Warning: london has multiple addresses;  \e
  using 4::114:a00:20ff:ab3d:83ed
traceroute: Warning: Multiple interfaces found; \e
  using 4::56:a00:20ff:fe93:8dde @ eri0:2
traceroute to london (4::114:a00:20ff:ab3d:83ed), 30 hops max, \e
  60 byte packets
1  frbldg7c-86 (4::56:a00:20ff:fe1f:65a1)  1.786 ms  1.544 ms  1.719 ms
2  frbldg7b-77 (4::255:0:0:c0a8:517)  2.587 ms 3.001 ms  2.988 ms
3  london (4::114:a00:20ff:ab3d:83ed)  3.122 ms  2.744 ms  3.356 ms
.fi
.in -2
.sp

.sp
.LP
The target host, london, has both IPv4 and IPv6 addresses in the name service
database. According to the default behavior, \fBtraceroute\fR uses IPv6 address
of the destination host.

.LP
\fBExample 2 \fRUsing the \fBtraceroute\fR Utility For a Host Which has Only
IPv4 Addresses
.sp
.LP
In the following examples, \fBtraceroute\fR is tracking the route to host
sanfrancisco, which has only IPv4 addresses in the name service database.
Therefore traceroute uses only IPv4 addresses. The following shows the 7-hop
path that a packet would follow from the host istanbul to the host
sanfrancisco.

.sp
.in +2
.nf
istanbul% \fBtraceroute sanfrancisco\fR
traceroute: Warning: Multiple interfaces found; using 172.31.86.247 @eri0
traceroute to sanfrancisco (172.29.64.39), 30 hops max, 40 byte packets
1  frbldg7c-86 (172.31.86.1)  1.516 ms  1.283 ms  1.362 ms
2  bldg1a-001 (172.31.1.211)  2.277 ms  1.773 ms  2.186 ms
3  bldg4-bldg1 (172.30.4.42)  1.978 ms  1.986 ms  13.996 ms
4  bldg6-bldg4 (172.30.4.49)  2.655 ms  3.042 ms  2.344 ms
5  ferbldg11a-001 (172.29.1.236)  2.636 ms  3.432 ms  3.830 ms
6  frbldg12b-153 (172.29.153.72)  3.452 ms  3.146 ms  2.962 ms
7  sanfrancisco (172.29.64.39)  3.430 ms  3.312 ms  3.451 ms
.fi
.in -2
.sp

.LP
\fBExample 3 \fRUsing the \fBtraceroute\fR Utility With Source Routing
.sp
.LP
The following example shows the path of a packet that goes from istanbul to
sanfrancisco through the hosts cairo and paris, as specified by the \fB-g\fR
option. The \fB-I\fR option makes \fBtraceroute\fR send \fBICMP\fR \fBECHO\fR
probes to the host sanfrancisco. The \fB-i\fR options sets the source address
to the \fBIP\fR address configured on the interface \fBqe0\fR.

.sp
.in +2
.nf
istanbul% \fBtraceroute -g cairo -g paris -i qe0 -q 1 -I sanfrancisco\fR
traceroute to sanfrancisco (172.29.64.39), 30 hops max, 56 byte packets
1  frbldg7c-86 (172.31.86.1)  2.012 ms
2  flrbldg7u (172.31.17.131)  4.960 ms
3  cairo (192.168.163.175) 4.894 ms
4  flrbldg7u (172.31.17.131)  3.475 ms
5  frbldg7c-017 (172.31.17.83)  4.126 ms
6  paris (172.31.86.31) 4.086 ms
7  frbldg7b-82 (172.31.82.1)  6.454 ms
8  bldg1a-001 (172.31.1.211)  6.541 ms
9  bldg6-bldg4 (172.30.4.49)  6.518 ms
10  ferbldg11a-001 (172.29.1.236)  9.108 ms
11  frbldg12b-153 (172.29.153.72)  9.634 ms
12  sanfrancisco (172.29.64.39)  14.631 ms


.fi
.in -2
.sp

.SH EXIT STATUS
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.sp .6
.RS 4n
Successful operation.
.RE

.sp
.ne 2
.na
\fB>\fB0\fR\fR
.ad
.sp .6
.RS 4n
An error occurred.
.RE

.SH SEE ALSO
.LP
\fBnetstat\fR(1M), \fBsignal\fR(3C), \fBping\fR(1M), \fBattributes\fR(5),
\fBprivileges\fR(5), \fBzones\fR(5)
.SH WARNINGS
.LP
This utility is intended for use in network testing, measurement and
management. It should be used primarily for manual fault isolation. Because of
the load it could impose on the network, it is unwise to use
\fBtraceroute\fR(1M) during normal operations or from automated scripts.