traceroute.tproj/traceroute.8

   1 .\" Copyright (c) 1990, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" Van Jacobson.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. All advertising materials mentioning features or use of this software
  16 .\"    must display the following acknowledgement:
  17 .\"     This product includes software developed by the University of
  18 .\"     California, Berkeley and its contributors.
  19 .\" 4. Neither the name of the University nor the names of its contributors
  20 .\"    may be used to endorse or promote products derived from this software
  21 .\"    without specific prior written permission.
  22 .\"
  23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  33 .\" SUCH DAMAGE.
  34 .\"
  35 .\"     @(#)traceroute.8        8.2 (Berkeley) 6/1/94
  36 .\"
  37 .Dd June 1, 1994
  38 .Dt TRACEROUTE 8
  39 .Os BSD 4.3
  40 .Sh NAME
  41 .Nm traceroute
  42 .Nd print the route packets take to network host
  43 .Sh SYNOPSIS
  44 .Nm traceroute
  45 .Op Fl m Ar max_ttl
  46 .Op Fl n
  47 .Op Fl p Ar port
  48 .Op Fl q Ar nqueries
  49 .Op Fl r
  50 .Bk -words
  51 .Op Fl s Ar src_addr
  52 .Ek
  53 .Op Fl t Ar tos
  54 .Op Fl w Ar waittime
  55 .Ar host
  56 .Op Ar packetsize
  57 .Sh DESCRIPTION
  58 The Internet is a large and complex aggregation of
  59 network hardware, connected together by gateways.
  60 Tracking the route one's packets follow (or finding the miscreant
  61 gateway that's discarding your packets) can be difficult.
  62 .Nm Traceroute
  63 utilizes the IP protocol `time to live' field and attempts to elicit an
  64 .Tn ICMP
  65 .Dv TIME_EXCEEDED
  66 response from each gateway along the path to some
  67 host.
  68 .Pp
  69 The only mandatory parameter is the destination host name or IP number.
  70 The default probe datagram length is 38 bytes, but this may be increased
  71 by specifying a packet size (in bytes) after the destination host
  72 name.
  73 .Pp
  74 Other options are:
  75 .Bl -tag -width Ds
  76 .It Fl m Ar max_ttl
  77 Set the max time-to-live (max number of hops) used in outgoing probe
  78 packets.  The default is 30 hops (the same default used for
  79 .Tn TCP
  80 connections).
  81 .It Fl n
  82 Print hop addresses numerically rather than symbolically and numerically
  83 (saves a nameserver address-to-name lookup for each gateway found on the
  84 path).
  85 .It Fl p Ar port
  86 Set the base
  87 .Tn UDP
  88 .Ar port
  89 number used in probes (default is 33434).
  90 .Nm Traceroute
  91 hopes that nothing is listening on
  92 .Tn UDP
  93 ports
  94 .Em base
  95 to
  96 .Em base+nhops-1
  97 at the destination host (so an
  98 .Tn ICMP
  99 .Dv PORT_UNREACHABLE
 100 message will
 101 be returned to terminate the route tracing).  If something is
 102 listening on a port in the default range, this option can be used
 103 to pick an unused port range.
 104 .It Fl q Ar nqueries
 105 Set the number of probes per ``ttl'' to
 106 .Ar nqueries
 107 (default is three probes).
 108 .It Fl r
 109 Bypass the normal routing tables and send directly to a host on an attached
 110 network.
 111 If the host is not on a directly-attached network,
 112 an error is returned.
 113 This option can be used to ping a local host through an interface
 114 that has no route through it (e.g., after the interface was dropped by
 115 .Xr routed 8 ) .
 116 .It Fl s Ar src_addr
 117 Use the following IP address
 118 (which must be given as an IP number, not
 119 a hostname) as the source address in outgoing probe packets.  On
 120 hosts with more than one IP address, this option can be used to
 121 force the source address to be something other than the IP address
 122 of the interface the probe packet is sent on.  If the IP address
 123 is not one of this machine's interface addresses, an error is
 124 returned and nothing is sent.
 125 .ne 1i
 126 .It Fl t Ar tos
 127 Set the
 128 .Em type-of-service
 129 in probe packets to the following value (default zero).  The value must be
 130 a decimal integer in the range 0 to 255.  This option can be used to
 131 see if different types-of-service result in different paths.  (If you
 132 are not running a
 133 .Bx 4.3 tahoe
 134 or later system, this may be academic since the normal network
 135 services like telnet and ftp don't let you control the
 136 .Dv TOS ) .
 137 Not all values of
 138 .Dv TOS
 139 are legal or
 140 meaningful \- see the IP spec for definitions.  Useful values are
 141 probably
 142 .Ql \-t 16
 143 (low delay) and
 144 .Ql \-t 8
 145 (high throughput).
 146 .It Fl v
 147 Verbose output.  Received
 148 .Tn ICMP
 149 packets other than
 150 .Dv TIME_EXCEEDED
 151 and
 152 .Dv UNREACHABLE Ns s
 153 are listed.
 154 .It Fl w
 155 Set the time (in seconds) to wait for a response to a probe (default 3
 156 sec.).
 157 .El
 158 .Pp
 159 This program attempts to trace the route an IP packet would follow to some
 160 internet host by launching
 161 .Tn UDP
 162 probe
 163 packets with a small ttl (time to live) then listening for an
 164 .Tn ICMP
 165 "time exceeded" reply from a gateway.  We start our probes
 166 with a ttl of one and increase by one until we get an
 167 .Tn ICMP
 168 "port unreachable"
 169 (which means we got to "host") or hit a max (which
 170 defaults to 30 hops & can be changed with the
 171 .Fl m
 172 flag).  Three
 173 probes (changed with
 174 .Fl q
 175 flag) are sent at each ttl setting and a
 176 line is printed showing the ttl, address of the gateway and
 177 round trip time of each probe.  If the probe answers come from
 178 different gateways, the address of each responding system will
 179 be printed.  If there is no response within a 3 sec. timeout
 180 interval (changed with the
 181 .Fl w
 182 flag), a "*" is printed for that
 183 probe.
 184 .Pp
 185 We don't want the destination
 186 host to process the
 187 .Tn UDP
 188 probe packets so the destination port is set to an
 189 unlikely value (if some clod on the destination is using that
 190 value, it can be changed with the
 191 .Fl p
 192 flag).
 193 .Pp
 194 A sample use and output might be:
 195 .Bd -literal
 196 [yak 71]% traceroute nis.nsf.net.
 197 traceroute to nis.nsf.net (35.1.1.48), 30 hops max, 56 byte packet
 198 1  helios.ee.lbl.gov (128.3.112.1)  19 ms  19 ms  0 ms
 199 2  lilac-dmc.Berkeley.EDU (128.32.216.1)  39 ms  39 ms  19 ms
 200 3  lilac-dmc.Berkeley.EDU (128.32.216.1)  39 ms  39 ms  19 ms
 201 4  ccngw-ner-cc.Berkeley.EDU (128.32.136.23)  39 ms  40 ms  39 ms
 202 5  ccn-nerif22.Berkeley.EDU (128.32.168.22)  39 ms  39 ms  39 ms
 203 6  128.32.197.4 (128.32.197.4)  40 ms  59 ms  59 ms
 204 7  131.119.2.5 (131.119.2.5)  59 ms  59 ms  59 ms
 205 8  129.140.70.13 (129.140.70.13)  99 ms  99 ms  80 ms
 206 9  129.140.71.6 (129.140.71.6)  139 ms  239 ms  319 ms
 207 10  129.140.81.7 (129.140.81.7)  220 ms  199 ms  199 ms
 208 11  nic.merit.edu (35.1.1.48)  239 ms  239 ms  239 ms
 209
 210 .Ed
 211 Note that lines 2 & 3 are the same.  This is due to a buggy
 212 kernel on the 2nd hop system \- lbl-csam.arpa \- that forwards
 213 packets with a zero ttl (a bug in the distributed version
 214 of 4.3
 215 .Tn BSD ) .
 216 Note that you have to guess what path
 217 the packets are taking cross-country since the
 218 .Tn NSFNet
 219 (129.140)
 220 doesn't supply address-to-name translations for its
 221 .Tn NSS Ns es .
 222 .Pp
 223 A more interesting example is:
 224 .Bd -literal
 225 [yak 72]% traceroute allspice.lcs.mit.edu.
 226 traceroute to allspice.lcs.mit.edu (18.26.0.115), 30 hops max
 227 1  helios.ee.lbl.gov (128.3.112.1)  0 ms  0 ms  0 ms
 228 2  lilac-dmc.Berkeley.EDU (128.32.216.1)  19 ms  19 ms  19 ms
 229 3  lilac-dmc.Berkeley.EDU (128.32.216.1)  39 ms  19 ms  19 ms
 230 4  ccngw-ner-cc.Berkeley.EDU (128.32.136.23)  19 ms  39 ms  39 ms
 231 5  ccn-nerif22.Berkeley.EDU (128.32.168.22)  20 ms  39 ms  39 ms
 232 6  128.32.197.4 (128.32.197.4)  59 ms  119 ms  39 ms
 233 7  131.119.2.5 (131.119.2.5)  59 ms  59 ms  39 ms
 234 8  129.140.70.13 (129.140.70.13)  80 ms  79 ms  99 ms
 235 9  129.140.71.6 (129.140.71.6)  139 ms  139 ms  159 ms
 236 10  129.140.81.7 (129.140.81.7)  199 ms  180 ms  300 ms
 237 11  129.140.72.17 (129.140.72.17)  300 ms  239 ms  239 ms
 238 12  * * *
 239 13  128.121.54.72 (128.121.54.72)  259 ms  499 ms  279 ms
 240 14  * * *
 241 15  * * *
 242 16  * * *
 243 17  * * *
 244 18  ALLSPICE.LCS.MIT.EDU (18.26.0.115)  339 ms  279 ms  279 ms
 245
 246 .Ed
 247 Note that the gateways 12, 14, 15, 16 & 17 hops away
 248 either don't send
 249 .Tn ICMP
 250 "time exceeded" messages or send them
 251 with a ttl too small to reach us.  14 \- 17 are running the
 252 .Tn MIT
 253 C Gateway code that doesn't send "time exceeded"s.  God
 254 only knows what's going on with 12.
 255 .Pp
 256 The silent gateway 12 in the above may be the result of a bug in
 257 the 4.[23]
 258 .Tn BSD
 259 network code (and its derivatives):  4.x (x <= 3)
 260 sends an unreachable message using whatever ttl remains in the
 261 original datagram.  Since, for gateways, the remaining ttl is
 262 zero, the
 263 .Tn ICMP
 264 "time exceeded" is guaranteed to not make it back
 265 to us.  The behavior of this bug is slightly more interesting
 266 when it appears on the destination system:
 267 .Bd -literal
 268 1  helios.ee.lbl.gov (128.3.112.1)  0 ms  0 ms  0 ms
 269 2  lilac-dmc.Berkeley.EDU (128.32.216.1)  39 ms  19 ms  39 ms
 270 3  lilac-dmc.Berkeley.EDU (128.32.216.1)  19 ms  39 ms  19 ms
 271 4  ccngw-ner-cc.Berkeley.EDU (128.32.136.23)  39 ms  40 ms  19 ms
 272 5  ccn-nerif35.Berkeley.EDU (128.32.168.35)  39 ms  39 ms  39 ms
 273 6  csgw.Berkeley.EDU (128.32.133.254)  39 ms  59 ms  39 ms
 274 7  * * *
 275 8  * * *
 276 9  * * *
 277 10  * * *
 278 11  * * *
 279 12  * * *
 280 13  rip.Berkeley.EDU (128.32.131.22)  59 ms !  39 ms !  39 ms !
 281
 282 .Ed
 283 Notice that there are 12 "gateways" (13 is the final
 284 destination) and exactly the last half of them are "missing".
 285 What's really happening is that rip (a Sun-3 running Sun OS3.5)
 286 is using the ttl from our arriving datagram as the ttl in its
 287 .Tn ICMP
 288 reply.  So, the reply will time out on the return path
 289 (with no notice sent to anyone since
 290 .Tn ICMP's
 291 aren't sent for
 292 .Tn ICMP's )
 293 until we probe with a ttl that's at least twice the path
 294 length.  I.e., rip is really only 7 hops away.  A reply that
 295 returns with a ttl of 1 is a clue this problem exists.
 296 .Nm Traceroute
 297 prints a "!" after the time if the ttl is <= 1.
 298 Since vendors ship a lot of obsolete
 299 .Pf ( Tn DEC Ns \'s
 300 Ultrix, Sun 3.x) or
 301 non-standard
 302 .Pq Tn HPUX
 303 software, expect to see this problem
 304 frequently and/or take care picking the target host of your
 305 probes.
 306 Other possible annotations after the time are
 307 .Sy !H ,
 308 .Sy !N ,
 309 .Sy !P
 310 (got a host, network or protocol unreachable, respectively),
 311 .Sy !S
 312 or
 313 .Sy !F
 314 (source route failed or fragmentation needed \- neither of these should
 315 ever occur and the associated gateway is busted if you see one).  If
 316 almost all the probes result in some kind of unreachable,
 317 .Nm traceroute
 318 will give up and exit.
 319 .Pp
 320 This program is intended for use in network testing, measurement
 321 and management.
 322 It should be used primarily for manual fault isolation.
 323 Because of the load it could impose on the network, it is unwise to use
 324 .Nm traceroute
 325 during normal operations or from automated scripts.
 326 .Sh AUTHOR
 327 Implemented by Van Jacobson from a suggestion by Steve Deering.  Debugged
 328 by a cast of thousands with particularly cogent suggestions or fixes from
 329 C. Philip Wood, Tim Seaver and Ken Adelman.
 330 .Sh SEE ALSO
 331 .Xr netstat 1 ,
 332 .Xr ping 8
 333 .Sh HISTORY
 334 The
 335 .Nm
 336 command
 337 .Bt