usr.sbin/traceroute/traceroute.8

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