user/traceroute/traceroute.8

   1 .\" Copyright (c) 1989, 1995, 1996, 1997, 1999, 2000
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms are permitted
   5 .\" provided that the above copyright notice and this paragraph are
   6 .\" duplicated in all such forms and that any documentation,
   7 .\" advertising materials, and other materials related to such
   8 .\" distribution and use acknowledge that the software was developed
   9 .\" by the University of California, Berkeley.  The name of the
  10 .\" University may not be used to endorse or promote products derived
  11 .\" from this software without specific prior written permission.
  12 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
  13 .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
  14 .\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  15 .\"
  16 .\"     $Id: traceroute.8,v 1.2 2007-06-26 13:01:51 gerg Exp $
  17 .\"
  18 .TH TRACEROUTE 8 "21 September 2000"
  19 .UC 6
  20 .SH NAME
  21 traceroute \- print the route packets take to network host
  22 .SH SYNOPSIS
  23 .na
  24 .B traceroute
  25 [
  26 .B \-dFInrvx
  27 ] [
  28 .B \-f
  29 .I first_ttl
  30 ] [
  31 .B \-g
  32 .I gateway
  33 ]
  34 .br
  35 .ti +8
  36 [
  37 .B \-i
  38 .I iface
  39 ] [
  40 .B \-m
  41 max_ttl
  42 ] [
  43 .B \-p
  44 .I port
  45 ]
  46 .br
  47 .ti +8
  48 [
  49 .B \-q
  50 .I nqueries
  51 ] [
  52 .B \-s
  53 .I src_addr
  54 ] [
  55 .B \-t
  56 .I tos
  57 ]
  58 .br
  59 .ti +8
  60 [
  61 .B \-w
  62 .I waittime
  63 ] [
  64 .B \-z
  65 .I pausemsecs
  66 ]
  67 .br
  68 .ti +8
  69 .I host
  70 [
  71 .I packetlen
  72 ]
  73 .ad
  74 .SH DESCRIPTION
  75 The Internet is a large and complex aggregation of
  76 network hardware, connected together by gateways.
  77 Tracking the route one's packets follow (or finding the miscreant
  78 gateway that's discarding your packets) can be difficult.
  79 .I Traceroute
  80 utilizes the IP protocol `time to live' field and attempts to elicit an
  81 ICMP TIME_EXCEEDED response from each gateway along the path to some
  82 host.
  83 .PP
  84 The only mandatory parameter is the destination host name or IP number.
  85 The default probe datagram length is 40 bytes, but this may be increased
  86 by specifying a packet length (in bytes) after the destination host
  87 name.
  88 .PP
  89 Other options are:
  90 .TP
  91 .B \-f
  92 Set the initial time-to-live used in the first outgoing probe packet.
  93 .TP
  94 .B \-F
  95 Set the "don't fragment" bit.
  96 .TP
  97 .B \-d
  98 Enable socket level debugging.
  99 .TP
 100 .B \-g
 101 Specify a loose source route gateway (8 maximum).
 102 .TP
 103 .B \-i
 104 Specify a network interface to obtain the source IP address for
 105 outgoing probe packets. This is normally only useful on a multi-homed
 106 host. (See the
 107 .B \-s
 108 flag for another way to do this.)
 109 .TP
 110 .B \-I
 111 Use ICMP ECHO instead of UDP datagrams.
 112 .TP
 113 .B \-m
 114 Set the max time-to-live (max number of hops) used in outgoing probe
 115 packets.  The default is 30 hops (the same default used for TCP
 116 connections).
 117 .TP
 118 .B \-n
 119 Print hop addresses numerically rather than symbolically and numerically
 120 (saves a nameserver address-to-name lookup for each gateway found on the
 121 path).
 122 .TP
 123 .B \-p
 124 Set the base UDP port number used in probes (default is 33434).
 125 Traceroute hopes that nothing is listening on UDP ports
 126 .I base
 127 to
 128 .I base + nhops - 1
 129 at the destination host (so an ICMP PORT_UNREACHABLE message will
 130 be returned to terminate the route tracing).  If something is
 131 listening on a port in the default range, this option can be used
 132 to pick an unused port range.
 133 .TP
 134 .B \-r
 135 Bypass the normal routing tables and send directly to a host on an attached
 136 network.
 137 If the host is not on a directly-attached network,
 138 an error is returned.
 139 This option can be used to ping a local host through an interface
 140 that has no route through it (e.g., after the interface was dropped by
 141 .IR routed (8C)).
 142 .TP
 143 .B \-s
 144 Use the following IP address (which usually is given as an IP number, not
 145 a hostname) as the source address in outgoing probe packets.  On
 146 multi-homed hosts (those with more than one IP
 147 address), this option can be used to
 148 force the source address to be something other than the IP address
 149 of the interface the probe packet is sent on.  If the IP address
 150 is not one of this machine's interface addresses, an error is
 151 returned and nothing is sent. (See the
 152 .B \-i
 153 flag for another way to do this.)
 154 .TP
 155 .B \-t
 156 Set the
 157 .I type-of-service
 158 in probe packets to the following value (default zero).  The value must be
 159 a decimal integer in the range 0 to 255.  This option can be used to
 160 see if different types-of-service result in different paths.  (If you
 161 are not running 4.4bsd, this may be academic since the normal network
 162 services like telnet and ftp don't let you control the TOS).
 163 Not all values of TOS are legal or
 164 meaningful \- see the IP spec for definitions.  Useful values are
 165 probably
 166 .RB ` -t
 167 .IR 16 '
 168 (low delay) and
 169 .RB ` -t
 170 .IR 8 '
 171 (high throughput).
 172 .TP
 173 .B \-v
 174 Verbose output.  Received ICMP packets other than TIME_EXCEEDED and
 175 UNREACHABLEs are listed.
 176 .TP
 177 .B \-w
 178 Set the time (in seconds) to wait for a response to a probe (default 5
 179 sec.).
 180 .TP
 181 .B \-x
 182 Toggle ip checksums. Normally, this prevents traceroute from calculating
 183 ip checksums. In some cases, the operating system can overwrite parts of
 184 the outgoing packet but not recalculate the checksum (so in some cases
 185 the default is to not calculate checksums and using
 186 .B \-x
 187 causes them to be calcualted). Note that checksums are usually required
 188 for the last hop when using ICMP ECHO probes
 189 .RB ( \-I ).
 190 So they are always calculated when using ICMP.
 191 .TP
 192 .B \-z
 193 Set the time (in milliseconds) to pause between probes (default 0).
 194 Some systems such as Solaris and routers such as Ciscos rate limit
 195 icmp messages. A good value to use with this this is 500 (e.g. 1/2 second).
 196 .PP
 197 This program attempts to trace the route an IP packet would follow to some
 198 internet host by launching UDP probe
 199 packets with a small ttl (time to live) then listening for an
 200 ICMP "time exceeded" reply from a gateway.  We start our probes
 201 with a ttl of one and increase by one until we get an ICMP "port
 202 unreachable" (which means we got to "host") or hit a max (which
 203 defaults to 30 hops & can be changed with the
 204 .B \-m
 205 flag).  Three
 206 probes (change with
 207 .B \-q
 208 flag) are sent at each ttl setting and a
 209 line is printed showing the ttl, address of the gateway and
 210 round trip time of each probe.  If the probe answers come from
 211 different gateways, the address of each responding system will
 212 be printed.  If there is no response within a 5 sec. timeout
 213 interval (changed with the
 214 .B \-w
 215 flag), a "*" is printed for that
 216 probe.
 217 .PP
 218 We don't want the destination
 219 host to process the UDP probe packets so the destination port is set to an
 220 unlikely value (if some clod on the destination is using that
 221 value, it can be changed with the
 222 .B \-p
 223 flag).
 224 .PP
 225 A sample use and output might be:
 226
 227 .RS
 228 .nf
 229 [yak 71]% traceroute nis.nsf.net.
 230 traceroute to nis.nsf.net (35.1.1.48), 30 hops max, 38 byte packet
 231  1  helios.ee.lbl.gov (128.3.112.1)  19 ms  19 ms  0 ms
 232  2  lilac-dmc.Berkeley.EDU (128.32.216.1)  39 ms  39 ms  19 ms
 233  3  lilac-dmc.Berkeley.EDU (128.32.216.1)  39 ms  39 ms  19 ms
 234  4  ccngw-ner-cc.Berkeley.EDU (128.32.136.23)  39 ms  40 ms  39 ms
 235  5  ccn-nerif22.Berkeley.EDU (128.32.168.22)  39 ms  39 ms  39 ms
 236  6  128.32.197.4 (128.32.197.4)  40 ms  59 ms  59 ms
 237  7  131.119.2.5 (131.119.2.5)  59 ms  59 ms  59 ms
 238  8  129.140.70.13 (129.140.70.13)  99 ms  99 ms  80 ms
 239  9  129.140.71.6 (129.140.71.6)  139 ms  239 ms  319 ms
 240 10  129.140.81.7 (129.140.81.7)  220 ms  199 ms  199 ms
 241 11  nic.merit.edu (35.1.1.48)  239 ms  239 ms  239 ms
 242 .fi
 243 .RE
 244
 245 Note that lines 2 & 3 are the same.  This is due to a buggy
 246 kernel on the 2nd hop system \- lbl-csam.arpa \- that forwards
 247 packets with a zero ttl (a bug in the distributed version
 248 of 4.3BSD).  Note that you have to guess what path
 249 the packets are taking cross-country since the NSFNet (129.140)
 250 doesn't supply address-to-name translations for its NSSes.
 251 .PP
 252 A more interesting example is:
 253
 254 .RS
 255 .nf
 256 [yak 72]% traceroute allspice.lcs.mit.edu.
 257 traceroute to allspice.lcs.mit.edu (18.26.0.115), 30 hops max
 258  1  helios.ee.lbl.gov (128.3.112.1)  0 ms  0 ms  0 ms
 259  2  lilac-dmc.Berkeley.EDU (128.32.216.1)  19 ms  19 ms  19 ms
 260  3  lilac-dmc.Berkeley.EDU (128.32.216.1)  39 ms  19 ms  19 ms
 261  4  ccngw-ner-cc.Berkeley.EDU (128.32.136.23)  19 ms  39 ms  39 ms
 262  5  ccn-nerif22.Berkeley.EDU (128.32.168.22)  20 ms  39 ms  39 ms
 263  6  128.32.197.4 (128.32.197.4)  59 ms  119 ms  39 ms
 264  7  131.119.2.5 (131.119.2.5)  59 ms  59 ms  39 ms
 265  8  129.140.70.13 (129.140.70.13)  80 ms  79 ms  99 ms
 266  9  129.140.71.6 (129.140.71.6)  139 ms  139 ms  159 ms
 267 10  129.140.81.7 (129.140.81.7)  199 ms  180 ms  300 ms
 268 11  129.140.72.17 (129.140.72.17)  300 ms  239 ms  239 ms
 269 12  * * *
 270 13  128.121.54.72 (128.121.54.72)  259 ms  499 ms  279 ms
 271 14  * * *
 272 15  * * *
 273 16  * * *
 274 17  * * *
 275 18  ALLSPICE.LCS.MIT.EDU (18.26.0.115)  339 ms  279 ms  279 ms
 276 .fi
 277 .RE
 278
 279 Note that the gateways 12, 14, 15, 16 & 17 hops away
 280 either don't send ICMP "time exceeded" messages or send them
 281 with a ttl too small to reach us.  14 \- 17 are running the
 282 MIT C Gateway code that doesn't send "time exceeded"s.  God
 283 only knows what's going on with 12.
 284 .PP
 285 The silent gateway 12 in the above may be the result of a bug in
 286 the 4.[23]BSD network code (and its derivatives):  4.x (x <= 3)
 287 sends an unreachable message using whatever ttl remains in the
 288 original datagram.  Since, for gateways, the remaining ttl is
 289 zero, the ICMP "time exceeded" is guaranteed to not make it back
 290 to us.  The behavior of this bug is slightly more interesting
 291 when it appears on the destination system:
 292
 293 .RS
 294 .nf
 295  1  helios.ee.lbl.gov (128.3.112.1)  0 ms  0 ms  0 ms
 296  2  lilac-dmc.Berkeley.EDU (128.32.216.1)  39 ms  19 ms  39 ms
 297  3  lilac-dmc.Berkeley.EDU (128.32.216.1)  19 ms  39 ms  19 ms
 298  4  ccngw-ner-cc.Berkeley.EDU (128.32.136.23)  39 ms  40 ms  19 ms
 299  5  ccn-nerif35.Berkeley.EDU (128.32.168.35)  39 ms  39 ms  39 ms
 300  6  csgw.Berkeley.EDU (128.32.133.254)  39 ms  59 ms  39 ms
 301  7  * * *
 302  8  * * *
 303  9  * * *
 304 10  * * *
 305 11  * * *
 306 12  * * *
 307 13  rip.Berkeley.EDU (128.32.131.22)  59 ms !  39 ms !  39 ms !
 308 .fi
 309 .RE
 310
 311 Notice that there are 12 "gateways" (13 is the final
 312 destination) and exactly the last half of them are "missing".
 313 What's really happening is that rip (a Sun-3 running Sun OS3.5)
 314 is using the ttl from our arriving datagram as the ttl in its
 315 ICMP reply.  So, the reply will time out on the return path
 316 (with no notice sent to anyone since ICMP's aren't sent for
 317 ICMP's) until we probe with a ttl that's at least twice the path
 318 length.  I.e., rip is really only 7 hops away.  A reply that
 319 returns with a ttl of 1 is a clue this problem exists.
 320 Traceroute prints a "!" after the time if the ttl is <= 1.
 321 Since vendors ship a lot of obsolete (DEC's Ultrix, Sun 3.x) or
 322 non-standard (HPUX) software, expect to see this problem
 323 frequently and/or take care picking the target host of your
 324 probes.
 325
 326 Other possible annotations after the time are
 327 .BR !H ,
 328 .BR !N ,
 329 or
 330 .B !P
 331 (host, network or protocol unreachable),
 332 .B !S
 333 (source route failed),
 334 .B !F\-<pmtu>
 335 (fragmentation needed \- the RFC1191 Path MTU Discovery value is displayed),
 336 .B !X
 337 (communication administratively prohibited),
 338 .B !V
 339 (host precedence violation),
 340 .B !C
 341 (precedence cutoff in effect), or
 342 .B !<num>
 343 (ICMP unreachable code <num>).
 344 These are defined by RFC1812 (which supersedes RFC1716).
 345 If almost all the probes result in some kind of unreachable, traceroute
 346 will give up and exit.
 347 .PP
 348 This program is intended for use in network testing, measurement
 349 and management.
 350 It should be used primarily for manual fault isolation.
 351 Because of the load it could impose on the network, it is unwise to use
 352 .I traceroute
 353 during normal operations or from automated scripts.
 354 .SH SEE ALSO
 355 pathchar(8), netstat(1), ping(8)
 356 .SH AUTHOR
 357 Implemented by Van Jacobson from a suggestion by Steve Deering.  Debugged
 358 by a cast of thousands with particularly cogent suggestions or fixes from
 359 C. Philip Wood, Tim Seaver and Ken Adelman.
 360 .LP
 361 The current version is available via anonymous ftp:
 362 .LP
 363 .RS
 364 .I ftp://ftp.ee.lbl.gov/traceroute.tar.gz
 365 .RE
 366 .SH BUGS
 367 Please send bug reports to traceroute@ee.lbl.gov.