traceroute(1M)						  System Administration Commands					    traceroute(1M)

NAME

       traceroute - print the route packets take to network host

SYNOPSIS

       traceroute [-adFIlnSvx] [-A addr_family] [-c traffic_class] [-f first_hop] [ -g gateway	[ -g gateway...] | -r]	[-i iface] [-L flow_label]
       [-m max_hop] [-P pause_sec] [-p port] [-Q max_timeout] [-q nqueries] [-s src_addr] [-t tos] [-w wait_time] host [packetlen]

DESCRIPTION

       The Internet is a large and complex aggregation of network hardware, connected by gateways. Tracking the route a packet follows can be dif-
       ficult. The utility traceroute traces the route that an IP packet follows to another internet host.

       The  traceroute	utility utilizes the both the IPv4 and IPv6 protocols. Use the -A option to override the default behavior. traceroute uses
       the IPv4 protocol ttl (time to live) field or the IPv6 field hop limit. It attempts to elicit an ICMP or ICMP6 TIME_EXCEEDED response  from
       each  gateway  along the path, and a PORT_UNREACHABLE(or ECHO_REPLY if -I is used) response from the destination host. It starts by sending
       probes with a ttl or hop limit of 1 and increases by 1 until it either gets to the host, or it hits the maximum max_hop.  The default maxi-
       mum max_hop is 30 hops, but this can be set by the -m option.

       Three  probes  are sent at each ttl (hop limit) setting, and a line is printed showing the ttl (hop limit), the hostname and the address of
       the gateway, and the rtt (round trip time) of each probe. The number of probes may be specifically set using the -q option.  If	the  probe
       answers	come  from  different  gateways,  the  hostname and the address of each responding system will be printed. If there is no response
       within a 5 second timeout interval, a "*" is printed for that probe. The -w option may be used to set the timeout interval. Other  possible
       annotations that may appear after the time are:

       !

	   the ttl (hop limit) value in the received packet is <= 1.

       !H

	   host unreachable.

       !X

	   communication administratively prohibited.

       <!N>

	   ICMP (ICMP6) unreachable code N.

       The following annotations appear only for IPv4:

       !F

	   fragmentation needed. This should never occur. If this is seen, the associated gateway is broken.

       !N

	   network unreachable.

       !P

	   protocol unreachable.

       !S

	   source route failed. It is likely that the gateway does not support source routing.

       !T

	   unreachable for the specified tos (type-of-service).

       !U

	   source host isolated or precedence problem.

       The following annotations appear only for IPv6:

       !A

	   host unreachable for a reason other than lack of an entry in the routing table.

       !B

	   packet too big.

       !E

	   destination is not a neighbor.

       !R

	   unrecognized next header.

       If almost all the probes result in some kind of unreachable code, then traceroute gives up and exits.

       The  destination  host  is not supposed to process the UDP probe packets, so the destination port default is set to an unlikely value. How-
       ever, if some application on the destination is using that value, the value of port can be changed with the -p option.

       The only mandatory parameter is the destination host name or IP number. The default probe datagram length is 40 bytes (60 bytes for  IPv6),
       but this may be increased by specifying a packet length (in bytes) after the destination host name.

       All  integer  arguments	to  traceroute can be specified in either decimal or hexadecimal notation. For example, packetlen can be specified
       either as 256 or 0x100.

OPTIONS

       -A addr_family

	   Specify the address family of the target host. addr_family can be either inet or inet6. Address family  determines  which  protocol	to
	   use. For an argument of inet, IPv4 is used. For inet6, IPv6 is used.

	   By  default,  if  the name of a host is provided, not the literal IP address, and a valid IPv6 address exists in the name service data-
	   base, traceroute will use this address. Otherwise, if the name service database contains an IPv4 address, it will try the IPv4 address.

	   Specify the address family inet or inet6 to override the default behavior. If the argument specified is inet, traceroute will  use  the
	   IPv4  address associated with the hostname. If none exists, traceroute will state that the host is unknown and exit. It will not try to
	   determine if an IPv6 address exists in the name service database.

	   If the specified argument is inet6, traceroute will use the IPv6 address that is associated with the hostname. If none exists,  tracer-
	   oute will state that the host is unknown and exit.

       -a

	   Probe  all of the addresses of a multi-homed destination. The output looks like traceroute has been run once for each IP address of the
	   destination. If this option is used together with -A, traceroute  probes only the addresses that are of the specified  address  family.
	   While  probing  one	of  the addresses of the destination, user can skip to the next address by sending a SIGINT, or exit traceroute by
	   sending a SIGQUIT signal.  See signal(3C)

       -c traffic_class

	   Specify the traffic class of probe packets. The value must be an integer in the range from 0 to 255. Gateways along the path may  route
	   the probe packet differently depending upon the value of traffic_class set in the probe packet. This option is valid only on IPv6.

       -d

	   Set the SO_DEBUG socket option.

       -F

	   Set	the  "don't  fragment"	bit.  This  option is valid only on IPv4. When specified from within a non-global zone, this option has no
	   effect as the "don't fragment" bit is always set in this case.

       -f first_hop

	   Set the starting ttl ( hop limit) value to first_hop, to override the default value 1. traceroute skips processing for those intermedi-
	   ate gateways which are less than first_hop hops away.

       -g gateway

	   Specify  a  loose  source route gateway. The user can specify more than one gateway by using -g for each gateway. The maximum number of
	   gateways is 8 for IPv4 and 127 for IPv6. Note that some factors such as the link MTU can further limit the number of gateways for IPv6.
	   This option cannot be used with the -r option.

	   Only users with the {PRIV_NET_RAWACCESS} privilege can specify a loose source route with this option.

       -I

	   Use ICMP (ICMP6) ECHO instead of UDP datagrams.

       -i iface

	   For	IPv4,  this  option  specifies	a network interface to obtain the source IP address. This is normally only useful on a multi-homed
	   host. The -s option is also another way to do this. For IPv6, it specifies the network interface on which probe packets  are  transmit-
	   ted. The argument can be either an interface index, for example, 1, 2, or an interface name, for example, eri0, hme0.

       -L flow_label

	   Specify  the  flow  label  of  probe packets. The value must be an integer in the range from 0 to 1048575. This option is valid only on
	   IPv6.

       -l

	   Print the value of the ttl (hop limit) field in each packet received.

       -m max_hop

	   Set the maximum ttl (hop limit) used in outgoing probe packets. The default is 30 hops, which is the same default used for TCP  connec-
	   tions.

       -n

	   Print hop addresses numerically rather than symbolically and numerically. This saves a nameserver address-to-name lookup for each gate-
	   way found on the path.

       -P pause_sec

	   Specify a delay, in seconds, to pause between probe packets. This may be necessary if the final destination does not accept	undeliver-
	   able  packets  in bursts. By default, traceroute sends the next probe as soon as it has received a reply. Note that pause_sec is a real
	   number.

       -p port

	   Set the base UDP port number used  in  probes.The  default  is  33434.  traceroute  hopes  that  nothing  is  listening  on	UDP  ports
	   (base+(nhops-1)*nqueries) to (base+(nhops*nqueries)-1)at the destination host, so that an ICMP (ICMP6) PORT_UNREACHABLE message will be
	   returned to terminate the route tracing. If something is listening on a port in the default range, this option can be used to select an
	   unused port range. nhops is defined as the number of hops between the source and the destination.

       -Q max_timeout

	   Stop  probing  this	hop after max_timeout consecutive timeouts are detected. The default value is 5. Useful in combination with the -q
	   option if you have specified a large nqueries probe count.

       -q nqueries

	   Set the desired number of probe queries. The default is 3.

       -r

	   Bypass the normal routing tables and send directly to a host on an attached network. If the host is not on a directly-attached network,
	   an  error  is returned. This option can be used to send probes to a local host through an interface that has been dropped by the router
	   deamon. See in.routed(1M). You cannot use this option if the -g option is used.

       -s src_addr

	   Use the following address, which usually is given as a literal IP address, not a hostname, as the  source  address  in  outgoing  probe
	   packets. On multi-homed hosts, those with more than one IP address, this option can be used to force the source address to be something
	   other than the IP address traceroute picks by default. If the IP address is not one of this machine's interface addresses, an error	is
	   returned  and nothing is sent. For IPv4, when used together with the -i option, the given IP address should be configured on the speci-
	   fied interface. Otherwise, an error will be returned. In the case of IPv6, the interface name and the source address  do  not  have	to
	   match.

       -t tos

	   Set	the  tos(type-of-service)  in probe packets to the specified value. The default is zero. The value must be an integer in the range
	   from 0 to 255. Gateways along the path may route the probe packet differently depending upon the tos value set  in  the  probe  packet.
	   This option is valid only on IPv4.

       -v

	   Verbose  output.  For  each	hop, the size and the destination of the response packets is displayed. Also ICMP (ICMP6) packets received
	   other than TIME_EXCEEDED and UNREACHABLE are listed as well.

       -w waittime

	   Set the time, in seconds, to wait for a response to a probe. The default is 5 seconds.

       -x

	   Prevent traceroute from calculating checksums. Checksums are usually required for the last hop when using ICMP ECHO probes. This option
	   is valid only on IPv4. See the -I option.

	   When  specified from within a non-global zone, this option has no effect as the checksum is always calculated by the operating     sys-
	   tem in this case.

OPERANDS

       The following operands are supported:

       host

	   The network host.

EXAMPLES

       Example 1: Sample Output From the traceroute Utility

       Some sample output from the traceroute utility might be:

       istanbul% traceroute london
       traceroute: Warning: london has multiple addresses;  
	 using 4::114:a00:20ff:ab3d:83ed
       traceroute: Warning: Multiple interfaces found; 
	 using 4::56:a00:20ff:fe93:8dde @ eri0:2
       traceroute to london (4::114:a00:20ff:ab3d:83ed), 30 hops max, 
	 60 byte packets
       1  frbldg7c-86 (4::56:a00:20ff:fe1f:65a1)  1.786 ms  1.544 ms  1.719 ms
       2  frbldg7b-77 (4::255:0:0:c0a8:517)  2.587 ms 3.001 ms	2.988 ms
       3  london (4::114:a00:20ff:ab3d:83ed)  3.122 ms	2.744 ms  3.356 ms
       The target host, london, has both IPv4 and IPv6 addresses in the name service database. According to the default behavior, traceroute  uses
       IPv6 address of the destination host.

       Example 2: Using the traceroute Utility For a Host Which has Only IPv4 Addresses

       In  the	following examples, traceroute is tracking the route to host sanfrancisco, which has only IPv4 addresses in the name service data-
       base. Therefore traceroute uses only IPv4 addresses. The following shows the 7-hop path that a packet would follow from the  host  istanbul
       to the host sanfrancisco.

       istanbul% traceroute sanfrancisco
       traceroute: Warning: Multiple interfaces found; using 172.31.86.247 @ eri0
       traceroute to sanfrancisco (172.29.64.39), 30 hops max, 40 byte packets
       1  frbldg7c-86 (172.31.86.1)  1.516 ms  1.283 ms  1.362 ms
       2  bldg1a-001 (172.31.1.211)  2.277 ms  1.773 ms  2.186 ms
       3  bldg4-bldg1 (172.30.4.42)  1.978 ms  1.986 ms  13.996 ms
       4  bldg6-bldg4 (172.30.4.49)  2.655 ms  3.042 ms  2.344 ms
       5  ferbldg11a-001 (172.29.1.236)  2.636 ms  3.432 ms  3.830 ms
       6  frbldg12b-153 (172.29.153.72)  3.452 ms  3.146 ms  2.962 ms
       7  sanfrancisco (172.29.64.39)  3.430 ms  3.312 ms  3.451 ms

       Example 3: Using the traceroute Utility With Source Routing

       The following example shows the path of a packet that goes from istanbul to sanfrancisco through the hosts cairo and paris, as specified by
       the -g option. The -I option makes traceroute send ICMP ECHO probes to the host sanfrancisco. The -i options sets the source address to the
       IP address configured on the interface qe0.

       istanbul% traceroute -g cairo -g paris -i qe0 -q 1 -I sanfrancisco
       traceroute to sanfrancisco (172.29.64.39), 30 hops max, 56 byte packets
       1  frbldg7c-86 (172.31.86.1)  2.012 ms
       2  flrbldg7u (172.31.17.131)  4.960 ms
       3  cairo (192.168.163.175) 4.894 ms
       4  flrbldg7u (172.31.17.131)  3.475 ms
       5  frbldg7c-017 (172.31.17.83)  4.126 ms
       6  paris (172.31.86.31) 4.086 ms
       7  frbldg7b-82 (172.31.82.1)  6.454 ms
       8  bldg1a-001 (172.31.1.211)  6.541 ms
       9  bldg6-bldg4 (172.30.4.49)  6.518 ms
       10  ferbldg11a-001 (172.29.1.236)  9.108 ms
       11  frbldg12b-153 (172.29.153.72)  9.634 ms
       12  sanfrancisco (172.29.64.39)	14.631 ms

EXIT STATUS

       The following exit values are returned:

       0

	   Successful operation.

       >0

	   An error occurred.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWcsu			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       netstat(1M), signal(3C), ping(1M), attributes(5), privileges(5), zones(5)

WARNINGS

       This  utility  is  intended for use in network testing, measurement and management. It should be used primarily for manual fault isolation.
       Because of the load it could impose on the network, it is unwise to use traceroute(1M) during normal operations or from automated scripts.

SunOS 5.10							    24Nov 2003							    traceroute(1M)