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.\"
36.Dd June 26, 2020
37.Dt TRACEROUTE 8
38.Os
39.Sh NAME
40.Nm traceroute
41.Nd print the route packets take to network host
42.Sh SYNOPSIS
43.Nm
44.Bk -words
45.Op Fl cdDIlMnrSv
46.Op Fl f Ar first_ttl
47.Op Fl g Ar gateway_addr
48.Op Fl m Ar max_ttl
49.Op Fl p Ar port
50.Op Fl P Ar proto
51.Op Fl q Ar nqueries
52.Op Fl s Ar src_addr
53.Op Fl t Ar tos
54.Op Fl w Ar waittime
55.Ar host
56.Op Ar packetsize
57.Ek
58.Sh DESCRIPTION
59The Internet is a large and complex aggregation of
60network hardware, connected together by gateways.
61Tracking the route one's packets follow (or finding the miscreant
62gateway that's discarding your packets) can be difficult.
63.Nm
64utilizes the IP protocol `time to live' field and attempts to elicit an
65.Tn ICMP
66.Dv TIME_EXCEEDED
67response from each gateway along the path to some
68host.
69.Pp
70The only mandatory parameter is the destination host name or IP number.
71The default probe datagram length is 38 bytes, but this may be increased
72by specifying a packet size (in bytes) after the destination host
73name.
74.Pp
75The options are as follows:
76.Bl -tag -width Ds
77.It Fl c
78Do not increment the destination port number in successive UDP packets.
79Rather, all UDP packets will have the same destination port, as set via the
80.Fl p
81flag (or 33434 if none is specified).
82.It Fl d
83Turn on socket-level debugging.
84.It Fl D
85Dump the packet data to standard error before transmitting it.
86.It Fl f Ar first_ttl
87Set the first time-to-live used in outgoing probe packets. The effect is that
88the first first_ttl - 1 hosts will be skipped in the output of
89.Nm .
90The default value is 1 (skip no hosts).
91.It Fl g Ar gateway_addr
92Add
93.Ar gateway_addr
94to the list of addresses in the IP Loose Source Record Route (LSRR)
95option.
96If no gateways are specified, the LSRR option is omitted.
97.It Fl I
98Equivalent to
99.Fl P
1001.
101Used for compatibility with other OSes.
102.It Fl l
103Display the ttl value of the returned packet.
104This is useful for checking for asymmetric routing.
105.It Fl m Ar max_ttl
106Set the max time-to-live (max number of hops) used in outgoing probe
107packets.
108The default is the value of the system's
109.Va net.inet.ip.ttl
110MIB variable, which defaults to 64.
111.It Fl M
112If found, show the MPLS Label and the Experimental (EXP) bit for the hop.
113.It Fl n
114Print hop addresses numerically rather than symbolically and numerically
115(saves a nameserver address-to-name lookup for each gateway found on the
116path).
117.It Fl p Ar port
118Set the base
119.Tn UDP
120.Ar port
121number used in probes (default is 33434).
122.Nm
123hopes that nothing is listening on
124.Tn UDP
125ports
126.Em base
127to
128.Em base+nhops*nqueries-1
129at the destination host (so an
130.Tn ICMP
131.Dv PORT_UNREACHABLE
132message will
133be returned to terminate the route tracing).
134If something is
135listening on a port in the default range, this option can be used
136to pick an unused port range.
137.It Fl P Ar proto
138Change the protocol being used from
139.Tn UDP
140to a numeric protocol or a name as specified in
141.Pa /etc/protocols .
142This will not work reliably for most protocols.
143If set to 1 (ICMP), then
144ICMP Echo Request messages will be used (same as
145.Xr ping 8 ) .
146.It Fl q Ar nqueries
147Set the number of probes per ``ttl'' to
148.Ar nqueries
149(default is three probes).
150.It Fl r
151Bypass the normal routing tables and send directly to a host on an attached
152network.
153If the host is not on a directly attached network,
154an error is returned.
155This option can be used to ping a local host through an interface
156that has no route through it (e.g., after the interface was dropped by
157.Xr routed 8 ) .
158.It Fl s Ar src_addr
159Use the following IP address
160(which must be given as an IP number, not
161a hostname) as the source address in outgoing probe packets.
162On hosts with more than one IP address, this option can be used to
163force the source address to be something other than the IP address
164of the interface the probe packet is sent on.
165If the IP address
166is not one of this machine's interface addresses and the user is
167not the superuser, an error is returned and nothing is sent.
168.It Fl S
169Print how many probes were not answered for each hop.
170.It Fl t Ar tos
171Set the
172.Em type-of-service
173in probe packets to the following value (default zero).
174The value must be a decimal integer in the range 0 to 255.
175This option can be used to
176see if different types-of-service result in different paths.
177(If you are not running a
178.Bx 4.3 tahoe
179or later system, this may be academic since the normal network
180services like telnet and ftp don't let you control the
181.Dv TOS ) .
182Not all values of
183.Dv TOS
184are legal or
185meaningful \- see the IP spec for definitions.
186Useful values are probably
187.Ql -t 16
188(low delay) and
189.Ql -t 8
190(high throughput).
191.It Fl v
192Verbose output.
193Received
194.Tn ICMP
195packets other than
196.Dv TIME_EXCEEDED
197and
198.Dv UNREACHABLE Ns s
199are listed.
200.It Fl w Ar waittime
201Set the time (in seconds) to wait for a response to a probe (default 3).
202.El
203.Pp
204This program attempts to trace the route an IP packet would follow to some
205internet host by launching
206.Tn UDP
207probe
208packets with a small ttl (time to live) then listening for an
209.Tn ICMP
210"time exceeded" reply from a gateway.
211We start out probes with a ttl of one and increase by one until we get an
212.Tn ICMP
213"port unreachable"
214(which means we got to "host") or hit a max (which
215defaults to 64 hops and can be changed with the
216.Fl m
217flag).
218Three probes (changed with
219.Fl q
220flag) are sent at each ttl setting and a
221line is printed showing the ttl, address of the gateway and
222round trip time of each probe.
223If the probe answers come from
224different gateways, the address of each responding system will
225be printed.
226If there is no response within a 5 sec. timeout
227interval (changed with the
228.Fl w
229flag), a "*" is printed for that
230probe.
231.Pp
232We don't want the destination
233host to process the
234.Tn UDP
235probe packets so the destination port is set to an
236unlikely value (if some clod on the destination is using that
237value, it can be changed with the
238.Fl p
239flag).
240.Pp
241A sample use and output might be:
242.Bd -literal -offset indent
243$ traceroute nis.nsf.net.
244traceroute to nis.nsf.net (35.1.1.48), 64 hops max, 56 byte packet
2451  helios.ee.lbl.gov (128.3.112.1)  19 ms  19 ms  0 ms
2462  lilac-dmc.Berkeley.EDU (128.32.216.1)  39 ms  39 ms  19 ms
2473  lilac-dmc.Berkeley.EDU (128.32.216.1)  39 ms  39 ms  19 ms
2484  ccngw-ner-cc.Berkeley.EDU (128.32.136.23)  39 ms  40 ms  39 ms
2495  ccn-nerif22.Berkeley.EDU (128.32.168.22)  39 ms  39 ms  39 ms
2506  128.32.197.4 (128.32.197.4)  40 ms  59 ms  59 ms
2517  131.119.2.5 (131.119.2.5)  59 ms  59 ms  59 ms
2528  129.140.70.13 (129.140.70.13)  99 ms  99 ms  80 ms
2539  129.140.71.6 (129.140.71.6)  139 ms  239 ms  319 ms
25410  129.140.81.7 (129.140.81.7)  220 ms  199 ms  199 ms
25511  nic.merit.edu (35.1.1.48)  239 ms  239 ms  239 ms
256.Ed
257.Pp
258Note that lines 2 & 3 are the same.
259This is due to a buggy
260kernel on the 2nd hop system \- lilac-dmc.Berkeley.EDU \- that forwards
261packets with a zero ttl (a bug in the distributed version
262of 4.3
263.Tn BSD ) .
264Note that you have to guess what path
265the packets are taking cross-country since the
266.Tn NSFNET
267(129.140)
268doesn't supply address-to-name translations for its
269.Tn NSS Ns es .
270.Pp
271A more interesting example is:
272.Bd -literal -offset indent
273$ traceroute allspice.lcs.mit.edu.
274traceroute to allspice.lcs.mit.edu (18.26.0.115), 64 hops max
2751  helios.ee.lbl.gov (128.3.112.1)  0 ms  0 ms  0 ms
2762  lilac-dmc.Berkeley.EDU (128.32.216.1)  19 ms  19 ms  19 ms
2773  lilac-dmc.Berkeley.EDU (128.32.216.1)  39 ms  19 ms  19 ms
2784  ccngw-ner-cc.Berkeley.EDU (128.32.136.23)  19 ms  39 ms  39 ms
2795  ccn-nerif22.Berkeley.EDU (128.32.168.22)  20 ms  39 ms  39 ms
2806  128.32.197.4 (128.32.197.4)  59 ms  119 ms  39 ms
2817  131.119.2.5 (131.119.2.5)  59 ms  59 ms  39 ms
2828  129.140.70.13 (129.140.70.13)  80 ms  79 ms  99 ms
2839  129.140.71.6 (129.140.71.6)  139 ms  139 ms  159 ms
28410  129.140.81.7 (129.140.81.7)  199 ms  180 ms  300 ms
28511  129.140.72.17 (129.140.72.17)  300 ms  239 ms  239 ms
28612  * * *
28713  128.121.54.72 (128.121.54.72)  259 ms  499 ms  279 ms
28814  * * *
28915  * * *
29016  * * *
29117  * * *
29218  ALLSPICE.LCS.MIT.EDU (18.26.0.115)  339 ms  279 ms  279 ms
293.Ed
294.Pp
295Note that the gateways 12, 14, 15, 16 & 17 hops away
296either don't send
297.Tn ICMP
298"time exceeded" messages or send them
299with a ttl too small to reach us.
30014 \- 17 are running the
301.Tn MIT
302C Gateway code that doesn't send "time exceeded"s.
303God only knows what's going on with 12.
304.Pp
305The silent gateway 12 in the above may be the result of a bug in
306the 4.[23]
307.Tn BSD
308network code (and its derivatives):  4.x (x \(<= 3)
309sends an unreachable message using whatever ttl remains in the
310original datagram.
311Since, for gateways, the remaining ttl is zero, the
312.Tn ICMP
313"time exceeded" is guaranteed to not make it back to us.
314The behavior of this bug is slightly more interesting
315when it appears on the destination system:
316.Bd -literal -offset indent
3171  helios.ee.lbl.gov (128.3.112.1)  0 ms  0 ms  0 ms
3182  lilac-dmc.Berkeley.EDU (128.32.216.1)  39 ms  19 ms  39 ms
3193  lilac-dmc.Berkeley.EDU (128.32.216.1)  19 ms  39 ms  19 ms
3204  ccngw-ner-cc.Berkeley.EDU (128.32.136.23)  39 ms  40 ms  19 ms
3215  ccn-nerif35.Berkeley.EDU (128.32.168.35)  39 ms  39 ms  39 ms
3226  csgw.Berkeley.EDU (128.32.133.254)  39 ms  59 ms  39 ms
3237  * * *
3248  * * *
3259  * * *
32610  * * *
32711  * * *
32812  * * *
32913  rip.Berkeley.EDU (128.32.131.22)  59 ms !  39 ms !  39 ms !
330.Ed
331.Pp
332Notice that there are 12 "gateways" (13 is the final
333destination) and exactly the last half of them are "missing".
334What's really happening is that rip (a Sun-3 running Sun OS3.5)
335is using the ttl from our arriving datagram as the ttl in its
336.Tn ICMP
337reply.
338So, the reply will time out on the return path
339(with no notice sent to anyone since
340.Tn ICMP's
341aren't sent for
342.Tn ICMP's )
343until we probe with a ttl that's at least twice the path
344length.
345i.e., rip is really only 7 hops away.
346A reply that returns with a ttl of 1 is a clue this problem exists.
347.Nm
348prints a "!" after the time if the ttl is \(<= 1.
349Since vendors ship a lot of obsolete
350.Pf ( Tn DEC Ns \'s
351Ultrix, Sun 3.x) or
352non-standard
353.Pq Tn HP-UX
354software, expect to see this problem
355frequently and/or take care picking the target host of your
356probes.
357.Pp
358Other possible annotations after the time are
359.Sy !H ,
360.Sy !N ,
361.Sy !P
362(got a host, network or protocol unreachable, respectively),
363.Sy !A ,
364.Sy !C
365(access to the network or host, respectively, is prohibited),
366.Sy !X
367(communication administratively prohibited by filtering),
368.Sy !S
369or
370.Sy !F
371(source route failed or fragmentation needed \- neither of these should
372ever occur and the associated gateway is busted if you see one),
373.Sy !U
374(destination network or host unknown),
375.Sy !T
376(destination network or host unreachable for TOS),
377.Sy !<code>
378(other ICMP unreachable code).
379If almost all the probes result in some kind of unreachable,
380.Nm
381will give up and exit.
382.Pp
383.Dl $ traceroute -g 10.3.0.5 128.182.0.0
384.Pp
385will show the path from the Cambridge Mailbridge to PSC, while
386.Pp
387.Dl $ traceroute -g 192.5.146.4 -g 10.3.0.5 35.0.0.0
388.Pp
389will show the path from the Cambridge Mailbridge to Merit, using PSC to
390reach the Mailbridge.
391.Pp
392This program is intended for use in network testing, measurement
393and management.
394It should be used primarily for manual fault isolation.
395Because of the load it could impose on the network, it is unwise to use
396.Nm
397during normal operations or from automated scripts.
398.Sh SEE ALSO
399.Xr netstat 1 ,
400.Xr ping 8 ,
401.Xr ping6 8 ,
402.Xr traceroute6 8
403.Sh HISTORY
404The very first
405.Nm
406(never released) used ICMP ECHO_REQUEST
407datagrams as probe packets.  During the first night of testing it was
408discovered that more than half the router vendors of the time would
409not return an ICMP TIME_EXCEEDED for an ECHO_REQUEST.
410.Nm
411was then changed to use UDP probe packets.
412Most modern TCP/IP implementations will now generate an ICMP error
413message to ICMP query messages, and the option to use ECHO_REQUEST probes
414was re-implemented.
415.Pp
416The
417.Nm
418command first appeared in
419.Bx 4.4 .
420.Sh AUTHORS
421Implemented by Van Jacobson from a suggestion by Steve Deering.
422Debugged
423by a cast of thousands with particularly cogent suggestions or fixes from
424C. Philip Wood, Tim Seaver and Ken Adelman.
425