Command Reference

traceroute

Use the traceroute command to display a hop-by-hop path through an IP network from the Catalyst 5000 series switch to a specific destination host.
traceroute [-n] [-w wait_time] [-i initial_ttl] [-m max_ttl] [-p dest_port] [-q nqueries] [-t tos] host [data_size]

Syntax Description

-n (Optional) Option that prevents traceroute from performing a DNS lookup for each hop on the path. Only numerical IP addresses are printed.

-w wait_time (Optional) Option used to specify the amount of time (in seconds) that traceroute will wait for an ICMP response message. The allowed range for wait_time is 1 to 300 seconds; the default is 5 seconds.

-i initial_ttl (Optional) Option that causes traceroute to send ICMP datagrams with a TTL value equal to initial_ttl instead of the default TTL of 1. This causes traceroute to skip processing for hosts that are less than initial_ttl hops away.

-m max_ttl (Optional) Option used to specify the maximum TTL value for outgoing ICMP datagrams. The allowed range for max_ttl is 1 to 255; the default value is 30.

-p dest_port (Optional) Option used to specify the base UDP destination port number used in traceroute datagrams. This value is incremented each time a datagram is sent. The allowed range for dest_port is 1 to 65535; the default base port is 33434. Use this option in the unlikely event that the destination host is listening to a port in the default traceroute port range.

-q nqueries (Optional) Option used to specify the number of datagrams to send for each TTL value. The allowed range for nqueries is 1 to 1000; the default is 3.

-t tos (Optional) Option used to specify the TOS to be set in the IP header of the outgoing datagrams. The allowed range for tos is 0 to 255; the default is 0. Use this option to see if different types of service cause routes to change.

host IP alias or IP address in dot notation (a.b.c.d) of the destination host.

data_size (Optional) Number of bytes, in addition to the default of 40 bytes, of the outgoing datagrams. The allowed range is 0 to 1420; the default is 0.

Default

Entering the traceroute host command without options sends three 40-byte ICMP datagrams with an initial TTL of 1, a maximum TTL of 30, a timeout period of 5 seconds, and a TOS specification of 0 to destination UDP port number 33434. For each host in the processed path, the initial TTL for each host and the destination UDP port number for each packet sent are incremented by one.

Command Type

Switch command.

Command Mode

Privileged.

Usage Guidelines

To interrupt traceroute after the command has been issued, press Ctrl-C.

The traceroute command uses the TTL field in the IP header to cause routers and servers to generate specific return messages. Traceroute starts by sending a UDP datagram to the destination host with the TTL field set to 1. If a router finds a TTL value of 1 or 0, it drops the datagram and sends back an ICMP "time exceeded" message to the sender. The traceroute facility determines the address of the first hop by examining the source address field of the ICMP time-exceeded message.

To identify the next hop, traceroute again sends a UDP packet but this time with a TTL value of 2. The first router decrements the TTL field by 1 and sends the datagram to the next router. The second router sees a TTL value of 1, discards the datagram, and returns the time-exceeded message to the source. This process continues until the TTL is incremented to a value large enough for the datagram to reach the destination host (or until the maximum TTL is reached).

To determine when a datagram has reached its destination, traceroute sets the UDP destination port in the datagram to a very large value that the destination host is unlikely to be using. When a host receives a datagram with an unrecognized port number, it sends an ICMP "port unreachable" error to the source. This message indicates to the traceroute facility that it has reached the destination.

Catalyst 5000 series switches can participate as the source or destination of the traceroute command. However, because they are Layer 2 devices, Catalyst 5000 series switches do not examine the TTL field in the IP header and therefore do not decrement the TTL field or send ICMP time-exceeded messages. Thus, a Catalyst 5000 series switch does not appear as a hop in the traceroute command output.

Example

This example shows how to use the traceroute command to determine the path from the source to the destination host server10:
Console> (enable) traceroute server10
traceroute to server10.company.com (172.16.22.7), 30 hops max, 40 byte packets
 1  engineering-1.company.com (172.31.192.206)  2 ms  1 ms  1 ms
 2  engineering-2.company.com (172.31.196.204)  2 ms  3 ms  2 ms
 3  gateway_a.company.com (172.16.1.201)  6 ms  3 ms  3 ms
 4  server10.company.com (172.16.22.7)  3 ms  *  2 ms
Console> (enable)
  
Table 5-1 describes the fields in the traceroute command output.

Table 5-1: traceroute Command Output Fields

Field Description

30 hops max, 40 byte packets Maximum TTL value and the size of the ICMP datagrams being sent.

2 ms 1 ms 1 ms Total time (in milliseconds) for each ICMP datagram to reach the router or host plus the time it took for the ICMP time-exceeded message to return to the host.
An exclamation point following any of these values (for example, 20 ms !) indicates that the port-unreachable message returned by the destination had a TTL of 0 or 1. This typically occurs when the destination uses the TTL value from the arriving datagram as the TTL in its ICMP reply. The reply does not arrive at the source until the destination receives a traceroute datagram with a TTL equal to the number of hops between the source and destination.

3 ms * 2 ms "*" indicates that the timeout period (default of 5 seconds) expired before an ICMP time-exceeded message was received for the datagram.

If traceroute receives an ICMP error message other than a time-exceeded or port-unreachable message, it prints one of the error codes shown in Table 5-2 instead of the round-trip time or an asterisk (*).

Table 5-2: traceroute Error Messages

ICMP Error Message Meaning

ICMP_UNREACH_NET No route to host. The network is unreachable.

ICMP_UNREACH_HOST No route to host. The host is unreachable.

ICMP_UNREACH_PROTOCOL Connection refused. The protocol is unreachable.

ICMP_UNREACH_NEEDFRAG Fragmentation needed but do not fragment (DF) bit was set.

ICMP_UNREACH_SRCFAIL Source route failed.

ICMP_UNREACH_ADMIN Communication administratively prohibited.

Related Command

ping

-n	(Optional) Option that prevents traceroute from performing a DNS lookup for each hop on the path. Only numerical IP addresses are printed.
-w wait_time	(Optional) Option used to specify the amount of time (in seconds) that traceroute will wait for an ICMP response message. The allowed range for wait_time is 1 to 300 seconds; the default is 5 seconds.
-i initial_ttl	(Optional) Option that causes traceroute to send ICMP datagrams with a TTL value equal to initial_ttl instead of the default TTL of 1. This causes traceroute to skip processing for hosts that are less than initial_ttl hops away.
-m max_ttl	(Optional) Option used to specify the maximum TTL value for outgoing ICMP datagrams. The allowed range for max_ttl is 1 to 255; the default value is 30.
-p dest_port	(Optional) Option used to specify the base UDP destination port number used in traceroute datagrams. This value is incremented each time a datagram is sent. The allowed range for dest_port is 1 to 65535; the default base port is 33434. Use this option in the unlikely event that the destination host is listening to a port in the default traceroute port range.
-q nqueries	(Optional) Option used to specify the number of datagrams to send for each TTL value. The allowed range for nqueries is 1 to 1000; the default is 3.
-t tos	(Optional) Option used to specify the TOS to be set in the IP header of the outgoing datagrams. The allowed range for tos is 0 to 255; the default is 0. Use this option to see if different types of service cause routes to change.
host	IP alias or IP address in dot notation (a.b.c.d) of the destination host.
data_size	(Optional) Number of bytes, in addition to the default of 40 bytes, of the outgoing datagrams. The allowed range is 0 to 1420; the default is 0.

Field	Description
30 hops max, 40 byte packets	Maximum TTL value and the size of the ICMP datagrams being sent.
2 ms 1 ms 1 ms	Total time (in milliseconds) for each ICMP datagram to reach the router or host plus the time it took for the ICMP time-exceeded message to return to the host. An exclamation point following any of these values (for example, 20 ms !) indicates that the port-unreachable message returned by the destination had a TTL of 0 or 1. This typically occurs when the destination uses the TTL value from the arriving datagram as the TTL in its ICMP reply. The reply does not arrive at the source until the destination receives a traceroute datagram with a TTL equal to the number of hops between the source and destination.
3 ms * 2 ms	"*" indicates that the timeout period (default of 5 seconds) expired before an ICMP time-exceeded message was received for the datagram.

ICMP Error Message	Meaning
ICMP_UNREACH_NET	No route to host. The network is unreachable.
ICMP_UNREACH_HOST	No route to host. The host is unreachable.
ICMP_UNREACH_PROTOCOL	Connection refused. The protocol is unreachable.
ICMP_UNREACH_NEEDFRAG	Fragmentation needed but do not fragment (DF) bit was set.
ICMP_UNREACH_SRCFAIL	Source route failed.
ICMP_UNREACH_ADMIN	Communication administratively prohibited.