Return to traceroute.8 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / usr.sbin / traceroute

Annotation of 43BSDReno/usr.sbin/traceroute/traceroute.8, revision 1.1

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

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.