424 lines
14 KiB
Groff
424 lines
14 KiB
Groff
.\" $OpenBSD: traceroute.8,v 1.76 2024/03/24 00:33:41 sthen Exp $
|
|
.\" $NetBSD: traceroute.8,v 1.6 1995/10/12 03:05:50 mycroft Exp $
|
|
.\"
|
|
.\" Copyright (c) 1990, 1991, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to Berkeley by
|
|
.\" Van Jacobson.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)traceroute.8 8.1 (Berkeley) 6/6/93
|
|
.\"
|
|
.Dd $Mdocdate: March 24 2024 $
|
|
.Dt TRACEROUTE 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm traceroute ,
|
|
.Nm traceroute6
|
|
.Nd print the route packets take to network host
|
|
.Sh SYNOPSIS
|
|
.Nm traceroute\ \&
|
|
.Op Fl ADdIlnSvx
|
|
.Op Fl f Ar first_ttl
|
|
.Op Fl g Ar gateway_addr
|
|
.Op Fl m Ar max_ttl
|
|
.Op Fl P Ar proto
|
|
.Op Fl p Ar port
|
|
.Op Fl q Ar nqueries
|
|
.Op Fl s Ar sourceaddr
|
|
.Op Fl t Ar toskeyword
|
|
.Op Fl V Ar rtable
|
|
.Op Fl w Ar waittime
|
|
.Ar host
|
|
.Op Ar datalen
|
|
.Nm traceroute6
|
|
.Op Fl ADdIlnSv
|
|
.Op Fl f Ar first_hop
|
|
.Op Fl m Ar max_hop
|
|
.Op Fl p Ar port
|
|
.Op Fl q Ar nqueries
|
|
.Op Fl s Ar sourceaddr
|
|
.Op Fl t Ar toskeyword
|
|
.Op Fl V Ar rtable
|
|
.Op Fl w Ar waittime
|
|
.Ar host
|
|
.Op Ar datalen
|
|
.Sh DESCRIPTION
|
|
The Internet is a large and complex aggregation of
|
|
network hardware, connected together by gateways.
|
|
Tracking the route packets follow (or finding the miscreant
|
|
gateway that's discarding packets) can be difficult.
|
|
.Nm
|
|
and
|
|
.Nm traceroute6
|
|
attempt to elicit
|
|
.Dv TIME_EXCEEDED
|
|
responses from each gateway along the path to
|
|
.Ar host ,
|
|
in order to determine their route.
|
|
.Nm
|
|
is used for IPv4 networks and
|
|
.Nm traceroute6
|
|
for IPv6.
|
|
.Pp
|
|
The options are as follows:
|
|
.Bl -tag -width Ds
|
|
.It Fl A
|
|
Look up the AS number for each hop address.
|
|
Uses the DNS service described at
|
|
.Lk https://www.team-cymru.com/ip-asn-mapping
|
|
.It Fl D
|
|
Dump the packet data to standard error before transmitting it.
|
|
.It Fl d
|
|
Turn on socket-level debugging.
|
|
.It Fl f Ar first_ttl
|
|
Set the first TTL or hop limit used in outgoing probe packets.
|
|
The effect is that the first first_ttl \- 1 hosts will be skipped
|
|
in the output of
|
|
.Nm traceroute .
|
|
The default is 1 (skip no hosts).
|
|
.It Fl g Ar gateway_addr
|
|
Add
|
|
.Ar gateway_addr
|
|
to the list of addresses in the IP Loose Source Record Route (LSRR)
|
|
option.
|
|
If no gateways are specified, the LSRR option is omitted.
|
|
This option is not available for IPv6.
|
|
.It Fl I
|
|
Use ICMP or ICMP6 ECHO instead of UDP datagrams.
|
|
.It Fl l
|
|
Display the TTL or hop limit value of the returned packet.
|
|
This is useful for checking for asymmetric routing.
|
|
.It Fl m Ar max_ttl
|
|
Set the maximum TTL or hop limit.
|
|
The default is the value of the system's
|
|
.Va net.inet.ip.ttl
|
|
or
|
|
.Va net.inet6.ip6.hlim
|
|
.Xr sysctl 8
|
|
variable, which defaults to 64.
|
|
.It Fl n
|
|
Print hop addresses numerically rather than symbolically and numerically
|
|
(saves a nameserver address-to-name lookup for each gateway found on the
|
|
path).
|
|
.It Fl P Ar proto
|
|
Change the protocol being used from UDP
|
|
to a numeric protocol or a name as specified in
|
|
.Pa /etc/protocols .
|
|
This will not work reliably for most protocols.
|
|
If set to 1 (ICMP), then
|
|
ICMP Echo Request messages will be used (same as
|
|
.Xr ping 8 ) .
|
|
This option is not available for IPv6.
|
|
.It Fl p Ar port
|
|
Set the base UDP
|
|
.Ar port
|
|
number used in probes.
|
|
The default is 33434.
|
|
.Nm
|
|
hopes that nothing is listening on UDP ports
|
|
.Ar base
|
|
to
|
|
.Ar base Ns + Ns Ar nhops Ns * Ns Ar nqueries Ns -1
|
|
at the destination host (so an ICMP
|
|
.Dv PORT_UNREACHABLE
|
|
message will
|
|
be returned to terminate the route tracing).
|
|
If something is
|
|
listening on a port in the default range, this option can be used
|
|
to pick an unused port range.
|
|
.It Fl q Ar nqueries
|
|
Set the number of probes per TTL to
|
|
.Ar nqueries .
|
|
The default is three probes.
|
|
.It Fl S
|
|
Print how many probes were not answered for each hop.
|
|
.It Fl s Ar sourceaddr
|
|
Set the source address to transmit from, which is useful on machines
|
|
with multiple interfaces.
|
|
.It Fl t Ar toskeyword
|
|
Set the type-of-service (TOS) in probe packets.
|
|
The value may be one of
|
|
.Cm critical ,
|
|
.Cm inetcontrol ,
|
|
.Cm lowdelay ,
|
|
.Cm netcontrol ,
|
|
.Cm throughput ,
|
|
.Cm reliability ,
|
|
or one of the DiffServ Code Points:
|
|
.Cm ef ,
|
|
.Cm af11 ... af43 ,
|
|
.Cm cs0 ... cs7 ;
|
|
or a number in either hex or decimal.
|
|
The default is zero.
|
|
This option can be used to
|
|
see if different types-of-service result in different paths.
|
|
If this option is used, changes to the type-of-service in the
|
|
returned packets are displayed.
|
|
Not all values of TOS are legal or meaningful \-
|
|
see the IP spec for definitions.
|
|
Useful values are probably
|
|
.Cm lowdelay
|
|
and
|
|
.Cm throughput .
|
|
.It Fl V Ar rtable
|
|
Set the routing table to be used.
|
|
.It Fl v
|
|
Verbose output.
|
|
Received ICMP packets other than
|
|
.Dv TIME_EXCEEDED
|
|
and
|
|
.Dv UNREACHABLE Ns s
|
|
are listed.
|
|
.It Fl w Ar waittime
|
|
Set the time, in seconds, to wait for a response to a probe.
|
|
The default is 3.
|
|
.It Fl x
|
|
Print the ICMP extended headers if available.
|
|
This option is not available for IPv6.
|
|
.It Ar host
|
|
The destination host,
|
|
specified as a host name or numeric IP address.
|
|
.It Ar datalen
|
|
The probe datagram length.
|
|
The default is 40 bytes for IPv4 UDP
|
|
and 60 bytes for ICMP, IPv6 UDP and ICMP6.
|
|
.El
|
|
.Pp
|
|
The program attempts to trace the route an IP packet would follow to a
|
|
host by launching UDP probe packets with a small TTL or hop limit,
|
|
then listening for an ICMP "time exceeded" reply from a gateway.
|
|
It starts using probes with a TTL/hop limit of one
|
|
and increases by one until it gets an ICMP "port unreachable"
|
|
(which means it reached the host) or hits a maximum limit
|
|
(which defaults to 64, but can be changed using the
|
|
.Fl m
|
|
option).
|
|
Three probes (the exact number can be changed using the
|
|
.Fl q
|
|
option) are sent and a line is printed
|
|
showing the TTL or hop limit, address of the gateway,
|
|
and round trip time of each probe.
|
|
If the probe answers come from different gateways,
|
|
the address of each responding system will be printed.
|
|
If there is no response within a 3 second timeout
|
|
interval (which can be changed using the
|
|
.Fl w
|
|
option), a "*" is printed for that
|
|
probe.
|
|
If the host cannot be reached,
|
|
.Nm
|
|
skips printing lines consisting only of * until the maximum TTL/hop limit is
|
|
reached.
|
|
.Pp
|
|
We don't want the destination
|
|
host to process the UDP
|
|
probe packets so the destination port is set to an
|
|
unlikely value (if some clod on the destination is using that
|
|
value, it can be changed using the
|
|
.Fl p
|
|
option).
|
|
.Pp
|
|
A sample use and output might be:
|
|
.Bd -literal -offset indent
|
|
$ traceroute nis.nsf.net.
|
|
traceroute to nis.nsf.net (35.1.1.48), 64 hops max, 56 byte packet
|
|
1 helios.ee.lbl.gov (128.3.112.1) 19 ms 19 ms 0 ms
|
|
2 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms
|
|
3 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms
|
|
4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 39 ms
|
|
5 ccn-nerif22.Berkeley.EDU (128.32.168.22) 39 ms 39 ms 39 ms
|
|
6 128.32.197.4 (128.32.197.4) 40 ms 59 ms 59 ms
|
|
7 131.119.2.5 (131.119.2.5) 59 ms 59 ms 59 ms
|
|
8 129.140.70.13 (129.140.70.13) 99 ms 99 ms 80 ms
|
|
9 129.140.71.6 (129.140.71.6) 139 ms 239 ms 319 ms
|
|
10 129.140.81.7 (129.140.81.7) 220 ms 199 ms 199 ms
|
|
11 nic.merit.edu (35.1.1.48) 239 ms 239 ms 239 ms
|
|
.Ed
|
|
.Pp
|
|
Note that lines 2 & 3 are the same.
|
|
This is due to a buggy
|
|
kernel on the 2nd hop system \- lbl-csam.arpa \- that forwards
|
|
packets with a zero TTL (a bug in the distributed version of
|
|
.Bx 4.3 ) .
|
|
Note that you have to guess what path
|
|
the packets are taking cross-country since the NSFNET (129.140)
|
|
doesn't supply address-to-name translations for its NSSes.
|
|
.Pp
|
|
A more interesting example is:
|
|
.Bd -literal -offset indent
|
|
$ traceroute allspice.lcs.mit.edu.
|
|
traceroute to allspice.lcs.mit.edu (18.26.0.115), 64 hops max
|
|
1 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms
|
|
2 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 19 ms 19 ms
|
|
3 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 19 ms
|
|
4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 19 ms 39 ms 39 ms
|
|
5 ccn-nerif22.Berkeley.EDU (128.32.168.22) 20 ms 39 ms 39 ms
|
|
6 128.32.197.4 (128.32.197.4) 59 ms 119 ms 39 ms
|
|
7 131.119.2.5 (131.119.2.5) 59 ms 59 ms 39 ms
|
|
8 129.140.70.13 (129.140.70.13) 80 ms 79 ms 99 ms
|
|
9 129.140.71.6 (129.140.71.6) 139 ms 139 ms 159 ms
|
|
10 129.140.81.7 (129.140.81.7) 199 ms 180 ms 300 ms
|
|
11 129.140.72.17 (129.140.72.17) 300 ms 239 ms 239 ms
|
|
12 * * *
|
|
13 128.121.54.72 (128.121.54.72) 259 ms 499 ms 279 ms
|
|
14 * * *
|
|
15 * * *
|
|
16 * * *
|
|
17 * * *
|
|
18 ALLSPICE.LCS.MIT.EDU (18.26.0.115) 339 ms 279 ms 279 ms
|
|
.Ed
|
|
.Pp
|
|
Note that the gateways 12, 14, 15, 16 & 17 hops away
|
|
either don't send ICMP "time exceeded" messages or send them
|
|
with a TTL too small to reach us.
|
|
14 \- 17 are running the MIT
|
|
C Gateway code that doesn't send "time exceeded"s.
|
|
God only knows what's going on with 12.
|
|
.Pp
|
|
The silent gateway 12 in the above may be the result of a bug in
|
|
the 4.[23]
|
|
.Bx
|
|
network code (and its derivatives): 4.x (x <= 3)
|
|
sends an unreachable message using whatever TTL remains in the
|
|
original datagram.
|
|
Since, for gateways, the remaining TTL is zero, the ICMP
|
|
"time exceeded" is guaranteed to not make it back to us.
|
|
The behavior of this bug is slightly more interesting
|
|
when it appears on the destination system:
|
|
.Bd -literal -offset indent
|
|
1 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms
|
|
2 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 39 ms
|
|
3 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 39 ms 19 ms
|
|
4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 19 ms
|
|
5 ccn-nerif35.Berkeley.EDU (128.32.168.35) 39 ms 39 ms 39 ms
|
|
6 csgw.Berkeley.EDU (128.32.133.254) 39 ms 59 ms 39 ms
|
|
7 * * *
|
|
8 * * *
|
|
9 * * *
|
|
10 * * *
|
|
11 * * *
|
|
12 * * *
|
|
13 rip.Berkeley.EDU (128.32.131.22) 59 ms ! 39 ms ! 39 ms !
|
|
.Ed
|
|
.Pp
|
|
Notice that there are 12 "gateways" (13 is the final
|
|
destination) and exactly the last half of them are "missing".
|
|
What's really happening is that rip (a Sun-3 running Sun OS3.5)
|
|
is using the TTL from our arriving datagram as the TTL in its
|
|
ICMP reply.
|
|
So, the reply will time out on the return path
|
|
(with no notice sent to anyone since ICMPs aren't sent for ICMPs)
|
|
until we probe with a TTL that's at least twice the path
|
|
length.
|
|
That is, rip is really only 7 hops away.
|
|
A reply that returns with a TTL of 1 is a clue this problem exists.
|
|
.Nm
|
|
prints a "!" after the time if the TTL is <= 1.
|
|
Since vendors ship a lot of obsolete (DEC's Ultrix, Sun 3.x) or
|
|
non-standard (HP-UX) software, expect to see this problem
|
|
frequently and/or take care picking the target host of your
|
|
probes.
|
|
.Pp
|
|
Other possible annotations after the time are
|
|
.Sy !H ,
|
|
.Sy !N ,
|
|
.Sy !P
|
|
(got a host, network or protocol unreachable, respectively),
|
|
.Sy !A ,
|
|
.Sy !C
|
|
(access to the network or host, respectively, is prohibited),
|
|
.Sy !X
|
|
(communication administratively prohibited by filtering),
|
|
.Sy !S
|
|
or
|
|
.Sy !F
|
|
(source route failed or fragmentation needed \- neither of these should
|
|
ever occur and the associated gateway is busted if you see one),
|
|
.Sy !U
|
|
(destination network or host unknown),
|
|
.Sy !T
|
|
(destination network or host unreachable for TOS),
|
|
.Sy !<code>
|
|
(other ICMP unreachable code).
|
|
.Sy TOS=xxx!
|
|
(TOS bit in returned packet differs from last hop).
|
|
If almost all the probes result in some kind of unreachable,
|
|
.Nm
|
|
will give up and exit.
|
|
.Pp
|
|
.Dl $ traceroute -g 10.3.0.5 128.182.0.0
|
|
.Pp
|
|
will show the path from the Cambridge Mailbridge to PSC, while
|
|
.Pp
|
|
.Dl $ traceroute -g 192.5.146.4 -g 10.3.0.5 35.0.0.0
|
|
.Pp
|
|
will show the path from the Cambridge Mailbridge to Merit, using PSC to
|
|
reach the Mailbridge.
|
|
.Pp
|
|
This program 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
|
|
.Nm
|
|
during normal operations or from automated scripts.
|
|
.Sh SEE ALSO
|
|
.Xr ping 8 ,
|
|
.Xr route 8
|
|
.Sh HISTORY
|
|
The very first
|
|
.Nm
|
|
(never released) used ICMP ECHO_REQUEST
|
|
datagrams as probe packets.
|
|
During the first night of testing it was
|
|
discovered that more than half the router vendors of the time would
|
|
not return an ICMP TIME_EXCEEDED for an ECHO_REQUEST.
|
|
.Nm
|
|
was then changed to use UDP probe packets.
|
|
Most modern TCP/IP implementations will now generate an ICMP error
|
|
message to ICMP query messages, and the option to use ECHO_REQUEST probes
|
|
was re-implemented.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
command first appeared in
|
|
.Bx 4.3 Reno .
|
|
The
|
|
.Nm traceroute6
|
|
command first appeared in the WIDE Hydrangea IPv6 protocol stack kit.
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
Implemented by
|
|
.An Van Jacobson
|
|
from a suggestion by
|
|
.An Steve Deering .
|
|
Debugged
|
|
by a cast of thousands with particularly cogent suggestions or fixes from
|
|
.An C. Philip Wood ,
|
|
.An Tim Seaver ,
|
|
and
|
|
.An Ken Adelman .
|