Add PCICAP_{ID,NEXTPTR} to avoid using magic number
[dragonfly.git] / usr.sbin / traceroute / traceroute.8
CommitLineData
0382be72
JR
1.\" $OpenBSD: traceroute.8,v 1.36 2003/08/27 08:17:33 jmc Exp $
2.\" $NetBSD: traceroute.8,v 1.6 1995/10/12 03:05:50 mycroft Exp $
3.\"
4.\" Copyright (c) 1990, 1991, 1993
5.\" The Regents of the University of California. All rights reserved.
6.\"
7.\" This code is derived from software contributed to Berkeley by
8.\" Van Jacobson.
9.\"
10.\" Redistribution and use in source and binary forms, with or without
11.\" modification, are permitted provided that the following conditions
12.\" are met:
13.\" 1. Redistributions of source code must retain the above copyright
14.\" notice, this list of conditions and the following disclaimer.
15.\" 2. Redistributions in binary form must reproduce the above copyright
16.\" notice, this list of conditions and the following disclaimer in the
17.\" documentation and/or other materials provided with the distribution.
18.\" 3. Neither the name of the University nor the names of its contributors
19.\" may be used to endorse or promote products derived from this software
20.\" without specific prior written permission.
21.\"
22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32.\" SUCH DAMAGE.
33.\"
34.\" @(#)traceroute.8 8.1 (Berkeley) 6/6/93
35.\"
9b5a9965 36.\" $DragonFly: src/usr.sbin/traceroute/traceroute.8,v 1.6 2007/07/29 17:27:46 swildner Exp $
46877004 37.Dd May 22, 2007
0382be72
JR
38.Dt TRACEROUTE 8
39.Os
40.Sh NAME
41.Nm traceroute
42.Nd print the route packets take to network host
43.Sh SYNOPSIS
9b5a9965 44.Nm
0382be72 45.Bk -words
46877004 46.Op Fl cdDIlMnrSv
0382be72
JR
47.Op Fl f Ar first_ttl
48.Op Fl g Ar gateway_addr
49.Op Fl m Ar max_ttl
50.Op Fl p Ar port
51.Op Fl P Ar proto
52.Op Fl q Ar nqueries
53.Op Fl s Ar src_addr
54.Op Fl t Ar tos
55.Op Fl w Ar waittime
56.Ar host
57.Op Ar packetsize
58.Ek
59.Sh DESCRIPTION
60The Internet is a large and complex aggregation of
61network hardware, connected together by gateways.
62Tracking the route one's packets follow (or finding the miscreant
63gateway that's discarding your packets) can be difficult.
64.Nm
65utilizes the IP protocol `time to live' field and attempts to elicit an
66.Tn ICMP
67.Dv TIME_EXCEEDED
68response from each gateway along the path to some
69host.
70.Pp
71The only mandatory parameter is the destination host name or IP number.
72The default probe datagram length is 38 bytes, but this may be increased
73by specifying a packet size (in bytes) after the destination host
74name.
75.Pp
76The options are as follows:
77.Bl -tag -width Ds
78.It Fl c
79Do not increment the destination port number in successive UDP packets.
80Rather, all UDP packets will have the same destination port, as set via the
81.Fl p
82flag (or 33434 if none is specified).
83.It Fl d
84Turn on socket-level debugging.
85.It Fl D
86Dump the packet data to standard error before transmitting it.
87.It Fl f Ar first_ttl
88Set the first time-to-live used in outgoing probe packets. The effect is that
89the first first_ttl - 1 hosts will be skipped in the output of
9b5a9965 90.Nm .
0382be72
JR
91The default value is 1 (skip no hosts).
92.It Fl g Ar gateway_addr
93Add
94.Ar gateway_addr
95to the list of addresses in the IP Loose Source Record Route (LSRR)
96option.
97If no gateways are specified, the LSRR option is omitted.
98.It Fl I
99Equivalent to
100.Fl P
1011.
102Used for compatibility with other OSes.
103.It Fl l
104Display the ttl value of the returned packet.
105This is useful for checking for asymmetric routing.
106.It Fl m Ar max_ttl
107Set the max time-to-live (max number of hops) used in outgoing probe
108packets.
109The default is the value of the system's
e9c76aaf 110.Va net.inet.ip.ttl
0382be72 111MIB variable, which defaults to 64.
46877004
HT
112.It Fl M
113If found, show the MPLS Label and the Experimental (EXP) bit for the hop.
0382be72
JR
114.It Fl n
115Print hop addresses numerically rather than symbolically and numerically
116(saves a nameserver address-to-name lookup for each gateway found on the
117path).
118.It Fl p Ar port
119Set the base
120.Tn UDP
121.Ar port
122number used in probes (default is 33434).
123.Nm
124hopes that nothing is listening on
125.Tn UDP
126ports
127.Em base
128to
129.Em base+nhops*nqueries-1
130at the destination host (so an
131.Tn ICMP
132.Dv PORT_UNREACHABLE
133message will
134be returned to terminate the route tracing).
135If something is
136listening on a port in the default range, this option can be used
137to pick an unused port range.
138.It Fl P Ar proto
139Change the protocol being used from
140.Tn UDP
141to a numeric protocol or a name as specified in
142.Pa /etc/protocols .
143This will not work reliably for most protocols.
144If set to 1 (ICMP), then
145ICMP Echo Request messages will be used (same as
146.Xr ping 8 ) .
147.It Fl q Ar nqueries
148Set the number of probes per ``ttl'' to
149.Ar nqueries
150(default is three probes).
151.It Fl r
152Bypass the normal routing tables and send directly to a host on an attached
153network.
154If the host is not on a directly attached network,
155an error is returned.
156This option can be used to ping a local host through an interface
157that has no route through it (e.g., after the interface was dropped by
158.Xr routed 8 ) .
159.It Fl s Ar src_addr
160Use the following IP address
161(which must be given as an IP number, not
162a hostname) as the source address in outgoing probe packets.
163On hosts with more than one IP address, this option can be used to
164force the source address to be something other than the IP address
165of the interface the probe packet is sent on.
166If the IP address
167is not one of this machine's interface addresses and the user is
168not the superuser, an error is returned and nothing is sent.
169.It Fl S
170Print how many probes were not answered for each hop.
171.It Fl t Ar tos
172Set the
173.Em type-of-service
174in probe packets to the following value (default zero).
175The value must be a decimal integer in the range 0 to 255.
176This option can be used to
177see if different types-of-service result in different paths.
178(If you are not running a
179.Bx 4.3 tahoe
180or later system, this may be academic since the normal network
181services like telnet and ftp don't let you control the
182.Dv TOS ) .
183Not all values of
184.Dv TOS
185are legal or
186meaningful \- see the IP spec for definitions.
187Useful values are probably
188.Ql -t 16
189(low delay) and
190.Ql -t 8
191(high throughput).
192.It Fl v
193Verbose output.
194Received
195.Tn ICMP
196packets other than
197.Dv TIME_EXCEEDED
198and
199.Dv UNREACHABLE Ns s
200are listed.
201.It Fl w Ar waittime
202Set the time (in seconds) to wait for a response to a probe (default 3).
203.El
204.Pp
205This program attempts to trace the route an IP packet would follow to some
206internet host by launching
207.Tn UDP
208probe
209packets with a small ttl (time to live) then listening for an
210.Tn ICMP
211"time exceeded" reply from a gateway.
212We start out probes with a ttl of one and increase by one until we get an
213.Tn ICMP
214"port unreachable"
215(which means we got to "host") or hit a max (which
216defaults to 64 hops and can be changed with the
217.Fl m
218flag).
219Three probes (changed with
220.Fl q
221flag) are sent at each ttl setting and a
222line is printed showing the ttl, address of the gateway and
223round trip time of each probe.
224If the probe answers come from
225different gateways, the address of each responding system will
226be printed.
227If there is no response within a 5 sec. timeout
228interval (changed with the
229.Fl w
230flag), a "*" is printed for that
231probe.
232.Pp
233We don't want the destination
234host to process the
235.Tn UDP
236probe packets so the destination port is set to an
237unlikely value (if some clod on the destination is using that
238value, it can be changed with the
239.Fl p
240flag).
241.Pp
242A sample use and output might be:
243.Bd -literal -offset indent
244$ traceroute nis.nsf.net.
245traceroute to nis.nsf.net (35.1.1.48), 64 hops max, 56 byte packet
2461 helios.ee.lbl.gov (128.3.112.1) 19 ms 19 ms 0 ms
2472 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms
2483 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms
2494 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 39 ms
2505 ccn-nerif22.Berkeley.EDU (128.32.168.22) 39 ms 39 ms 39 ms
2516 128.32.197.4 (128.32.197.4) 40 ms 59 ms 59 ms
2527 131.119.2.5 (131.119.2.5) 59 ms 59 ms 59 ms
2538 129.140.70.13 (129.140.70.13) 99 ms 99 ms 80 ms
2549 129.140.71.6 (129.140.71.6) 139 ms 239 ms 319 ms
25510 129.140.81.7 (129.140.81.7) 220 ms 199 ms 199 ms
25611 nic.merit.edu (35.1.1.48) 239 ms 239 ms 239 ms
257.Ed
258.Pp
259Note that lines 2 & 3 are the same.
260This is due to a buggy
495d962a 261kernel on the 2nd hop system \- lilac-dmc.Berkeley.EDU \- that forwards
0382be72
JR
262packets with a zero ttl (a bug in the distributed version
263of 4.3
264.Tn BSD ) .
265Note that you have to guess what path
266the packets are taking cross-country since the
267.Tn NSFNET
268(129.140)
269doesn't supply address-to-name translations for its
270.Tn NSS Ns es .
271.Pp
272A more interesting example is:
273.Bd -literal -offset indent
274$ traceroute allspice.lcs.mit.edu.
275traceroute to allspice.lcs.mit.edu (18.26.0.115), 64 hops max
2761 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms
2772 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 19 ms 19 ms
2783 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 19 ms
2794 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 19 ms 39 ms 39 ms
2805 ccn-nerif22.Berkeley.EDU (128.32.168.22) 20 ms 39 ms 39 ms
2816 128.32.197.4 (128.32.197.4) 59 ms 119 ms 39 ms
2827 131.119.2.5 (131.119.2.5) 59 ms 59 ms 39 ms
2838 129.140.70.13 (129.140.70.13) 80 ms 79 ms 99 ms
2849 129.140.71.6 (129.140.71.6) 139 ms 139 ms 159 ms
28510 129.140.81.7 (129.140.81.7) 199 ms 180 ms 300 ms
28611 129.140.72.17 (129.140.72.17) 300 ms 239 ms 239 ms
28712 * * *
28813 128.121.54.72 (128.121.54.72) 259 ms 499 ms 279 ms
28914 * * *
29015 * * *
29116 * * *
29217 * * *
29318 ALLSPICE.LCS.MIT.EDU (18.26.0.115) 339 ms 279 ms 279 ms
294.Ed
295.Pp
296Note that the gateways 12, 14, 15, 16 & 17 hops away
297either don't send
298.Tn ICMP
299"time exceeded" messages or send them
300with a ttl too small to reach us.
30114 \- 17 are running the
302.Tn MIT
303C Gateway code that doesn't send "time exceeded"s.
304God only knows what's going on with 12.
305.Pp
306The silent gateway 12 in the above may be the result of a bug in
307the 4.[23]
308.Tn BSD
aa0d550a 309network code (and its derivatives): 4.x (x \(<= 3)
0382be72
JR
310sends an unreachable message using whatever ttl remains in the
311original datagram.
312Since, for gateways, the remaining ttl is zero, the
313.Tn ICMP
314"time exceeded" is guaranteed to not make it back to us.
315The behavior of this bug is slightly more interesting
316when it appears on the destination system:
317.Bd -literal -offset indent
3181 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms
3192 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 39 ms
3203 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 39 ms 19 ms
3214 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 19 ms
3225 ccn-nerif35.Berkeley.EDU (128.32.168.35) 39 ms 39 ms 39 ms
3236 csgw.Berkeley.EDU (128.32.133.254) 39 ms 59 ms 39 ms
3247 * * *
3258 * * *
3269 * * *
32710 * * *
32811 * * *
32912 * * *
33013 rip.Berkeley.EDU (128.32.131.22) 59 ms ! 39 ms ! 39 ms !
331.Ed
332.Pp
333Notice that there are 12 "gateways" (13 is the final
334destination) and exactly the last half of them are "missing".
335What's really happening is that rip (a Sun-3 running Sun OS3.5)
336is using the ttl from our arriving datagram as the ttl in its
337.Tn ICMP
338reply.
339So, the reply will time out on the return path
340(with no notice sent to anyone since
341.Tn ICMP's
342aren't sent for
343.Tn ICMP's )
344until we probe with a ttl that's at least twice the path
345length.
346i.e., rip is really only 7 hops away.
347A reply that returns with a ttl of 1 is a clue this problem exists.
348.Nm
aa0d550a 349prints a "!" after the time if the ttl is \(<= 1.
0382be72
JR
350Since vendors ship a lot of obsolete
351.Pf ( Tn DEC Ns \'s
352Ultrix, Sun 3.x) or
353non-standard
354.Pq Tn HP-UX
355software, expect to see this problem
356frequently and/or take care picking the target host of your
357probes.
358.Pp
359Other possible annotations after the time are
360.Sy !H ,
361.Sy !N ,
362.Sy !P
363(got a host, network or protocol unreachable, respectively),
364.Sy !A ,
365.Sy !C
366(access to the network or host, respectively, is prohibited),
367.Sy !X
368(communication administratively prohibited by filtering),
369.Sy !S
370or
371.Sy !F
372(source route failed or fragmentation needed \- neither of these should
373ever occur and the associated gateway is busted if you see one),
374.Sy !U
375(destination network or host unknown),
376.Sy !T
377(destination network or host unreachable for TOS),
378.Sy !<code>
379(other ICMP unreachable code).
380If almost all the probes result in some kind of unreachable,
381.Nm
382will give up and exit.
383.Pp
384.Dl $ traceroute -g 10.3.0.5 128.182.0.0
385.Pp
386will show the path from the Cambridge Mailbridge to PSC, while
387.Pp
388.Dl $ traceroute -g 192.5.146.4 -g 10.3.0.5 35.0.0.0
389.Pp
390will show the path from the Cambridge Mailbridge to Merit, using PSC to
391reach the Mailbridge.
392.Pp
393This program is intended for use in network testing, measurement
394and management.
395It should be used primarily for manual fault isolation.
396Because of the load it could impose on the network, it is unwise to use
397.Nm
398during normal operations or from automated scripts.
399.Sh SEE ALSO
400.Xr netstat 1 ,
401.Xr ping 8
402.Sh HISTORY
403The very first
404.Nm
405(never released) used ICMP ECHO_REQUEST
406datagrams as probe packets. During the first night of testing it was
407discovered that more than half the router vendors of the time would
408not return an ICMP TIME_EXCEEDED for an ECHO_REQUEST.
409.Nm
410was then changed to use UDP probe packets.
411Most modern TCP/IP implementations will now generate an ICMP error
412message to ICMP query messages, and the option to use ECHO_REQUEST probes
413was re-implemented.
414.Pp
415The
416.Nm
417command first appeared in
418.Bx 4.4 .
419.Sh AUTHORS
420Implemented by Van Jacobson from a suggestion by Steve Deering.
421Debugged
422by a cast of thousands with particularly cogent suggestions or fixes from
423C. Philip Wood, Tim Seaver and Ken Adelman.