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