mirror of
https://github.com/freebsd/freebsd-src
synced 2024-07-22 18:56:38 +00:00
9b7a920a12
traceroute hasn't had a vendor import since 2002, while since then it's had several significant FreeBSD-specific commits. Since it's unlikely another vendor import will happen, and to make the merge of traceroute6 into traceroute easier, import traceroute into usr.sbin. Reviewed by: imp Pull Request: https://github.com/freebsd/freebsd-src/pull/1100
404 lines
15 KiB
Groff
404 lines
15 KiB
Groff
.\" Copyright (c) 1989, 1995, 1996, 1997, 1999, 2000
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms are permitted
|
|
.\" provided that the above copyright notice and this paragraph are
|
|
.\" duplicated in all such forms and that any documentation,
|
|
.\" advertising materials, and other materials related to such
|
|
.\" distribution and use acknowledge that the software was developed
|
|
.\" by the University of California, Berkeley. The name of the
|
|
.\" University may not be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
|
|
.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
|
|
.\"
|
|
.\" $Id: traceroute.8,v 1.19 2000/09/21 08:44:19 leres Exp $
|
|
.\"
|
|
.Dd November 17, 2023
|
|
.Dt TRACEROUTE 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm traceroute
|
|
.Nd "print the route packets take to network host"
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Bk -words
|
|
.Op Fl adDeEFISnrvx
|
|
.Op Fl A Ar as_server
|
|
.Op Fl f Ar first_ttl
|
|
.Op Fl g Ar gateway
|
|
.Op Fl i Ar iface
|
|
.Op Fl m Ar max_ttl
|
|
.Op Fl M Ar first_ttl
|
|
.Op Fl p Ar port
|
|
.Op Fl P Ar proto
|
|
.Op Fl q Ar nprobes
|
|
.Op Fl s Ar src_addr
|
|
.Op Fl t Ar tos
|
|
.Op Fl w Ar waittime
|
|
.Op Fl z Ar pausemsecs
|
|
.Ar host
|
|
.Op Ar packetlen
|
|
.Ek
|
|
.Sh DESCRIPTION
|
|
The Internet is a large and complex aggregation of network hardware, connected
|
|
together by gateways.
|
|
Tracking the route one's packets follow (or finding the miscreant gateway
|
|
that's discarding your packets) can be difficult.
|
|
.Nm
|
|
utilizes the IP protocol `time to live' field and attempts to elicit an ICMP
|
|
TIME_EXCEEDED response from each gateway along the path to some host.
|
|
.Pp
|
|
The only mandatory parameter is the destination host name or IP number.
|
|
The default probe datagram length is 40 bytes, but this may be increased by
|
|
specifying a packet length (in bytes) after the destination host name.
|
|
.Pp
|
|
Other options are:
|
|
.Bl -tag -width Ds
|
|
.It Fl a
|
|
Turn on AS# lookups for each hop encountered.
|
|
.It Fl A Ar as_server
|
|
Turn on AS# lookups and use the given server instead of the default.
|
|
.It Fl d
|
|
Enable socket level debugging.
|
|
.It Fl D
|
|
When an ICMP response to our probe datagram is received, print the differences
|
|
between the transmitted packet and the packet quoted by the ICMP response.
|
|
A key showing the location of fields within the transmitted packet is printed,
|
|
followed by the original packet in hex, followed by the quoted packet in hex.
|
|
Bytes that are unchanged in the quoted packet are shown as underscores.
|
|
Note, the IP checksum and the TTL of the quoted packet are not expected to
|
|
match.
|
|
By default, only one probe per hop is sent with this option.
|
|
.It Fl e
|
|
Firewall evasion mode.
|
|
Use fixed destination ports for UDP, UDP-Lite, TCP and SCTP probes.
|
|
The destination port does NOT increment with each packet sent.
|
|
.It Fl E
|
|
Detect ECN bleaching.
|
|
Set the
|
|
.Em IPTOS_ECN_ECT1
|
|
Explicit Congestion Notification (ECN) bits
|
|
.Pq Dv 01 ,
|
|
and report if the hop has bleached
|
|
.Pq Dv 00
|
|
or mangled
|
|
.Pq Dv 10
|
|
them, or if it is experiencing congestion
|
|
.Pq Dv 11 .
|
|
Otherwise, report that it passed the bits appropriately.
|
|
If
|
|
.Fl t
|
|
is also specified, the corresponding ECN bits will be replaced.
|
|
.It Fl f Ar first_ttl
|
|
Set the initial time-to-live used in the first outgoing probe packet.
|
|
.It Fl F
|
|
Set the "don't fragment" bit.
|
|
.It Fl g Ar gateway
|
|
Specify a loose source route gateway (8 maximum).
|
|
.It Fl i Ar iface
|
|
Specify a network interface to obtain the source IP address for outgoing probe
|
|
packets.
|
|
This is normally only useful on a multi-homed host.
|
|
(See the
|
|
.Fl s
|
|
flag for another way to do this).
|
|
.It Fl I
|
|
Use ICMP ECHO instead of UDP datagrams.
|
|
(A synonym for "-P icmp").
|
|
.It Fl m Ar max_ttl
|
|
Set the max time-to-live (max number of hops) used in outgoing probe packets.
|
|
The default is the value of the
|
|
.Va net.inet.ip.ttl
|
|
.Xr sysctl 8
|
|
(the same default used for TCP connections).
|
|
.It Fl M Ar first_ttl
|
|
Set the initial time-to-live value used in outgoing probe packets.
|
|
The default is 1, i.e., start with the first hop.
|
|
.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 port
|
|
Protocol specific.
|
|
For UDP, UDP-Lite, TCP and SCTP, sets the base
|
|
.Ar port
|
|
number used in probes (default is 33434).
|
|
Traceroute hopes that nothing is listening on UDP ports (or UDP-Lite ports
|
|
if used by
|
|
.Nm
|
|
and supported by the peer)
|
|
.Em port + 1
|
|
to
|
|
.Em port + (max_ttl - first_ttl + 1) * nprobes
|
|
at the destination host (so an ICMP 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 P Ar proto
|
|
Send packets of specified IP protocol.
|
|
The currently supported protocols
|
|
are: UDP, UDP-Lite, TCP, SCTP, GRE and ICMP.
|
|
Other protocols may also be specified (either by name or by number), though
|
|
.Nm
|
|
does not implement any special knowledge of their packet formats.
|
|
This option is useful for determining which router along a path may be blocking
|
|
packets based on IP protocol number.
|
|
But see BUGS below.
|
|
.It Fl q Ar nprobes
|
|
Set the number of probes per hop (default is 3, unless
|
|
.Fl D
|
|
is specified,
|
|
when it is 1).
|
|
.It Fl r
|
|
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 ping a local host through an interface that has no
|
|
route through it (e.g., after the interface was dropped by
|
|
.Xr routed 8 .
|
|
.It Fl s Ar src_addr
|
|
Use the following IP address (which usually is given as an IP number, not a
|
|
hostname) as the source address in outgoing probe packets.
|
|
On multi-homed hosts (those with more than one IP address), this option can be
|
|
used to force the source address to be something other than the IP address of
|
|
the interface the probe packet is sent on.
|
|
If the IP address is not one of this machine's interface addresses, an error is
|
|
returned and nothing is sent.
|
|
(See the
|
|
.Fl i
|
|
flag for another way to do this).
|
|
.It Fl S
|
|
Print a summary of how many probes were not answered for each hop.
|
|
.It Fl t Ar tos
|
|
Set the
|
|
.Em type-of-service
|
|
in probe packets to the following value (default zero).
|
|
The value must be a decimal integer in the range 0 to 255.
|
|
This option can be used to see if different types-of-service result in
|
|
different paths.
|
|
The upper six bits are the Differentiated Services Codepoint (RFC4594).
|
|
The lower two bits are the Explicit Congestion Notification field (RFC3168).
|
|
.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 (default 5 sec.).
|
|
.It Fl x
|
|
Toggle ip checksums.
|
|
Normally, this prevents traceroute from calculating ip checksums.
|
|
In some cases, the operating system can overwrite parts of the outgoing packet
|
|
but not recalculate the checksum (so in some cases the default is to not
|
|
calculate checksums and using
|
|
.Fl x
|
|
causes them to be calculated).
|
|
Note that checksums are usually required for the last hop when using ICMP ECHO
|
|
probes
|
|
.Pq Fl I .
|
|
So they are always calculated when using ICMP.
|
|
.It Fl z Ar pausemsecs
|
|
Set the time (in milliseconds) to pause between probes (default 0).
|
|
Some systems such as Solaris and routers such as Ciscos rate limit ICMP
|
|
messages.
|
|
A good value to use with this is 500 (e.g., 1/2 second).
|
|
.El
|
|
.Pp
|
|
This program attempts to trace the route an IP packet would follow to some
|
|
internet host by launching UDP probe packets with a small TTL (time to live)
|
|
then listening for an ICMP "time exceeded" reply from a gateway.
|
|
We start our probes with a TTL of one and increase by one until we get an ICMP
|
|
"port unreachable" (which means we got to "host") or hit a max (which defaults
|
|
to the amount of hops specified by the
|
|
.Va net.inet.ip.ttl
|
|
.Xr sysctl 8
|
|
and can be changed with the
|
|
.Fl m
|
|
flag).
|
|
Three probes (change with
|
|
.Fl q
|
|
flag) are sent at each TTL setting and a line is printed showing the TTL,
|
|
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 5 sec. timeout interval (changed with the
|
|
.Fl w
|
|
flag), a "*" is printed for that probe.
|
|
.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 with the
|
|
.Fl p
|
|
flag).
|
|
.Pp
|
|
A sample use and output might be:
|
|
.Bd -literal -offset 4n
|
|
% traceroute nis.nsf.net.
|
|
traceroute to nis.nsf.net (35.1.1.48), 64 hops max, 40 byte packets
|
|
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 \- lilac-dmc.Berkeley.EDU \-
|
|
that forwards packets with a zero TTL (a bug in the distributed version of
|
|
4.3BSD).
|
|
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 4n
|
|
% traceroute allspice.lcs.mit.edu.
|
|
traceroute to allspice.lcs.mit.edu (18.26.0.115), 64 hops max, 40 byte packets
|
|
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]BSD
|
|
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 4n
|
|
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 ICMP's aren't sent for ICMP's) until we probe with a TTL that's at least
|
|
twice the path length.
|
|
I.e., 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
|
|
.Pf ( DEC Ns \'s
|
|
Ultrix, Sun 3.x) or
|
|
non-standard
|
|
.Pq 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:
|
|
.Bl -hang -offset indent -width 12n
|
|
.It Sy !H
|
|
Host unreachable.
|
|
.It Sy !N
|
|
Network unreachable.
|
|
.It Sy !P
|
|
Protocol unreachable.
|
|
.It Sy !S
|
|
Source route failed.
|
|
.It Sy !F\-<pmtu>
|
|
Fragmentation needed.
|
|
The RFC1191 Path MTU Discovery value is displayed.
|
|
.It Sy !U
|
|
Destination network unknown.
|
|
.It Sy !W
|
|
Destination host unknown.
|
|
.It Sy !I
|
|
Source host is isolated.
|
|
.It Sy !A
|
|
Communication with destination network administratively prohibited.
|
|
.It Sy !Z
|
|
Communication with destination host administratively prohibited.
|
|
.It Sy !Q
|
|
For this ToS the destination network is unreachable.
|
|
.It Sy !T
|
|
For this ToS the destination host is unreachable.
|
|
.It Sy !X
|
|
Communication administratively prohibited.
|
|
.It Sy !V
|
|
Host precedence violation.
|
|
.It Sy !C
|
|
Precedence cutoff in effect.
|
|
.It Sy !<num>
|
|
ICMP unreachable code <num>.
|
|
.El
|
|
.Pp
|
|
These are defined by RFC1812 (which supersedes RFC1716).
|
|
If almost all the probes result in some kind of unreachable,
|
|
.Nm
|
|
will give up and exit.
|
|
.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 netstat 1 ,
|
|
.Xr ping 8 ,
|
|
.Xr traceroute6 8
|
|
.Sh AUTHORS
|
|
Implemented by
|
|
.An Van Jacobson
|
|
from a suggestion by Steve Deering.
|
|
Debugged by a cast of thousands with particularly cogent suggestions or fixes
|
|
from C. Philip Wood, Tim Seaver and Ken Adelman.
|
|
.Sh BUGS
|
|
When using protocols other than UDP, functionality is reduced.
|
|
In particular, the last packet will often appear to be lost, because even
|
|
though it reaches the destination host, there's no way to know that because no
|
|
ICMP message is sent back.
|
|
In the TCP case,
|
|
.Nm
|
|
should listen for a RST from the destination host (or an intermediate router
|
|
that's filtering packets), but this is not implemented yet.
|
|
.Pp
|
|
The AS number capability reports information that may sometimes be inaccurate
|
|
due to discrepancies between the contents of the routing database server and
|
|
the current state of the Internet.
|