| blob | 1f2dcc1fcf6ce38506d3554205ab29fd95ff4d2e |
1 '\" te
2 .\" Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH TRACEROUTE 1M "Sep 18, 2008"
7 .SH NAME
8 traceroute \- print the route packets take to network host
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBtraceroute\fR [\fB-adFIlnSvx\fR] [\fB-A\fR \fIaddr_family\fR] [\fB-c\fR \fItraffic_class\fR]
13 [\fB-f\fR \fIfirst_hop\fR] [\fB-g\fR \fIgateway\fR [\fB-g\fR \fIgateway\fR...] | \fB-r\fR]
14 [\fB-i\fR \fIiface\fR] [\fB-L\fR \fIflow_label\fR] [\fB-m\fR \fImax_hop\fR]
15 [\fB-P\fR \fIpause_sec\fR] [\fB-p\fR \fIport\fR] [\fB-Q\fR \fImax_timeout\fR]
16 [\fB-q\fR \fInqueries\fR] [\fB-s\fR \fIsrc_addr\fR] [\fB-t\fR \fItos\fR] [\fB-w\fR \fIwait_time\fR] host
17 [\fIpacketlen\fR]
18 .fi
20 .SH DESCRIPTION
21 .sp
22 .LP
23 The Internet is a large and complex aggregation of network hardware, connected
24 by gateways. Tracking the route a packet follows can be difficult. The utility
25 \fBtraceroute\fR traces the route that an \fBIP\fR packet follows to another
26 internet host.
27 .sp
28 .LP
29 The \fBtraceroute\fR utility utilizes the both the IPv4 and IPv6 protocols. Use
30 the \fB-A\fR option to override the default behavior. \fBtraceroute\fR uses the
31 IPv4 protocol \fIttl\fR (time to live) field or the IPv6 field \fIhop limit\fR.
32 It attempts to elicit an \fBICMP\fR or \fBICMP6\fR \fBTIME_EXCEEDED\fR response
33 from each \fIgateway\fR along the path, and a \fBPORT_UNREACHABLE\fR(or
34 \fBECHO_REPLY\fR if \fB-I\fR is used) response from the destination host. It
35 starts by sending probes with a \fIttl\fR or \fIhop limit\fR of \fB1\fR and
36 increases by \fB1\fR until it either gets to the host, or it hits the maximum
37 \fImax_hop\fR. The default maximum \fImax_hop\fR is 30 hops, but this can be
38 set by the \fB-m\fR option.
39 .sp
40 .LP
41 Three probes are sent at each \fIttl\fR (\fIhop limit\fR) setting, and a line
42 is printed showing the \fIttl\fR (\fIhop limit\fR), the hostname and the
43 address of the gateway, and the \fIrtt\fR (round trip time) of each probe. The
44 number of probes may be specifically set using the \fB-q\fR option. If the
45 probe answers come from different gateways, the hostname and the address of
46 each responding system will be printed. If there is no response within a 5
47 second timeout interval, an asterisk (\fB*\fR) is displayed for that probe. The
48 \fB-w\fR option may be used to set the timeout interval. Other possible
49 annotations that may appear after the time are:
50 .sp
51 .ne 2
52 .na
53 \fB\fB!\fR\fR
54 .ad
55 .sp .6
56 .RS 4n
57 the \fIttl\fR (\fIhop limit\fR) value in the received packet is \fB<= 1\fR\&.
58 .RE
60 .sp
61 .ne 2
62 .na
63 \fB\fB!H\fR\fR
64 .ad
65 .sp .6
66 .RS 4n
67 host unreachable.
68 .RE
70 .sp
71 .ne 2
72 .na
73 \fB\fB!X\fR\fR
74 .ad
75 .sp .6
76 .RS 4n
77 communication administratively prohibited.
78 .RE
80 .sp
81 .ne 2
82 .na
83 \fB\fB<!N>\fR\fR
84 .ad
85 .sp .6
86 .RS 4n
87 \fBICMP\fR (\fBICMP6\fR) unreachable code N.
88 .RE
90 .sp
91 .LP
92 The following annotations appear only for IPv4:
93 .sp
94 .ne 2
95 .na
96 \fB\fB!F\fR\fR
97 .ad
98 .sp .6
99 .RS 4n
100 fragmentation needed. This should never occur. If this is seen, the associated
101 gateway is broken.
102 .RE
104 .sp
105 .ne 2
106 .na
107 \fB\fB!N\fR\fR
108 .ad
109 .sp .6
110 .RS 4n
111 network unreachable.
112 .RE
114 .sp
115 .ne 2
116 .na
117 \fB\fB!P\fR\fR
118 .ad
119 .sp .6
120 .RS 4n
121 protocol unreachable.
122 .RE
124 .sp
125 .ne 2
126 .na
127 \fB\fB!S\fR\fR
128 .ad
129 .sp .6
130 .RS 4n
131 source route failed. It is likely that the gateway does not support source
132 routing.
133 .RE
135 .sp
136 .ne 2
137 .na
138 \fB\fB!T\fR\fR
139 .ad
140 .sp .6
141 .RS 4n
142 unreachable for the specified tos (type-of-service).
143 .RE
145 .sp
146 .ne 2
147 .na
148 \fB\fB!U\fR\fR
149 .ad
150 .sp .6
151 .RS 4n
152 source host isolated or precedence problem.
153 .RE
155 .sp
156 .LP
157 The following annotations appear only for IPv6:
158 .sp
159 .ne 2
160 .na
161 \fB\fB!A\fR\fR
162 .ad
163 .sp .6
164 .RS 4n
165 host unreachable for a reason other than lack of an entry in the routing table.
166 .RE
168 .sp
169 .ne 2
170 .na
171 \fB\fB!B\fR\fR
172 .ad
173 .sp .6
174 .RS 4n
175 packet too big.
176 .RE
178 .sp
179 .ne 2
180 .na
181 \fB\fB!E\fR\fR
182 .ad
183 .sp .6
184 .RS 4n
185 destination is not a neighbor.
186 .RE
188 .sp
189 .ne 2
190 .na
191 \fB\fB!R\fR\fR
192 .ad
193 .sp .6
194 .RS 4n
195 unrecognized next header.
196 .RE
198 .sp
199 .LP
200 If almost all the probes result in some kind of unreachable code, then
201 \fBtraceroute\fR gives up and exits.
202 .sp
203 .LP
204 The destination \fIhost\fR is not supposed to process the \fBUDP\fR probe
205 packets, so the destination \fIport\fR default is set to an unlikely value.
206 However, if some application on the destination is using that value, the value
207 of \fIport\fR can be changed with the \fB-p\fR option.
208 .sp
209 .LP
210 The only mandatory parameter is the destination \fIhost\fR name or \fBIP\fR
211 number. The default probe datagram length is 40 bytes (60 bytes for IPv6), but
212 this may be increased by specifying a packet length (in bytes) after the
213 destination \fIhost\fR name.
214 .sp
215 .LP
216 All integer arguments to \fBtraceroute\fR can be specified in either decimal or
217 hexadecimal notation. For example, \fIpacketlen\fR can be specified either as
218 \fB256\fR or \fB0x100\fR.
219 .SH OPTIONS
220 .sp
221 .ne 2
222 .na
223 \fB\fB-A\fR\ \fIaddr_family\fR\fR
224 .ad
225 .sp .6
226 .RS 4n
227 Specify the address family of the target host. \fIaddr_family\fR can be either
228 \fBinet\fR or \fBinet6\fR. Address family determines which protocol to use. For
229 an argument of \fBinet\fR, IPv4 is used. For \fBinet6\fR, IPv6 is used.
230 .sp
231 By default, if the name of a host is provided, not the literal \fBIP\fR
232 address, and a valid IPv6 address exists in the name service database,
233 \fBtraceroute\fR will use this address. Otherwise, if the name service database
234 contains an IPv4 address, it will try the IPv4 address.
235 .sp
236 Specify the address family \fBinet\fR or \fBinet6\fR to override the default
237 behavior. If the argument specified is \fBinet\fR, \fBtraceroute\fR will use
238 the IPv4 address associated with the hostname. If none exists, \fBtraceroute\fR
239 will state that the host is unknown and exit. It will not try to determine if
240 an IPv6 address exists in the name service database.
241 .sp
242 If the specified argument is \fBinet6\fR, \fBtraceroute\fR will use the IPv6
243 address that is associated with the hostname. If none exists, \fBtraceroute\fR
244 will state that the host is unknown and exit.
245 .RE
247 .sp
248 .ne 2
249 .na
250 \fB\fB-a\fR\fR
251 .ad
252 .sp .6
253 .RS 4n
254 Probe all of the addresses of a multi-homed destination. The output looks like
255 \fBtraceroute\fR has been run once for each \fBIP\fR address of the
256 destination. If this option is used together with \fB-A\fR, \fBtraceroute\fR
257 probes only the addresses that are of the specified address family. While
258 probing one of the addresses of the destination, user can skip to the next
259 address by sending a \fBSIGINT\fR, or exit \fBtraceroute\fR by sending a
260 \fBSIGQUIT\fR signal. See \fBsignal\fR(3C)
261 .RE
263 .sp
264 .ne 2
265 .na
266 \fB\fB-c\fR\ \fItraffic_class\fR\fR
267 .ad
268 .sp .6
269 .RS 4n
270 Specify the traffic class of probe packets. The value must be an integer in the
271 range from 0 to 255. Gateways along the path may route the probe packet
272 differently depending upon the value of \fItraffic_class\fR set in the probe
273 packet. This option is valid only on IPv6.
274 .RE
276 .sp
277 .ne 2
278 .na
279 \fB\fB-d\fR\fR
280 .ad
281 .sp .6
282 .RS 4n
283 Set the \fBSO_DEBUG\fR socket option.
284 .RE
286 .sp
287 .ne 2
288 .na
289 \fB\fB-F\fR\fR
290 .ad
291 .sp .6
292 .RS 4n
293 Set the "don't fragment" bit. This option is valid only on IPv4. When specified
294 from within a shared-IP zone, this option has no effect as the "don't fragment"
295 bit is always set in this case.
296 .RE
298 .sp
299 .ne 2
300 .na
301 \fB\fB-f\fR \fIfirst_hop\fR\fR
302 .ad
303 .sp .6
304 .RS 4n
305 Set the starting \fIttl\fR ( \fIhop limit\fR) value to \fIfirst_hop\fR, to
306 override the default value \fB1\fR. \fBtraceroute\fR skips processing for those
307 intermediate gateways which are less than \fIfirst_hop\fR hops away.
308 .RE
310 .sp
311 .ne 2
312 .na
313 \fB\fB-g\fR \fIgateway\fR\fR
314 .ad
315 .sp .6
316 .RS 4n
317 Specify a loose source route \fIgateway\fR. The user can specify more than one
318 \fIgateway\fR by using \fB-g\fR for each gateway. The maximum number of
319 gateways is 8 for IPv4 and 127 for IPv6. Note that some factors such as the
320 link \fBMTU\fR can further limit the number of gateways for IPv6. This option
321 cannot be used with the \fB-r\fR option.
322 .sp
323 Only users with the \fB{PRIV_NET_RAWACCESS}\fR privilege can specify a loose
324 source route with this option.
325 .RE
327 .sp
328 .ne 2
329 .na
330 \fB\fB-I\fR\fR
331 .ad
332 .sp .6
333 .RS 4n
334 Use \fBICMP\fR (\fBICMP6\fR) \fBECHO\fR instead of \fBUDP\fR datagrams.
335 .RE
337 .sp
338 .ne 2
339 .na
340 \fB\fB-i\fR \fIiface\fR\fR
341 .ad
342 .sp .6
343 .RS 4n
344 For IPv4, this option specifies a network interface to obtain the source
345 \fBIP\fR address. This is normally only useful on a multi-homed host. The
346 \fB-s\fR option is also another way to do this. For IPv6, it specifies the
347 network interface on which probe packets are transmitted. The argument can be
348 either an interface index, for example, \fB1\fR, \fB2\fR, or an interface name,
349 for example, \fBeri0\fR, \fBhme0\fR.
350 .RE
352 .sp
353 .ne 2
354 .na
355 \fB\fB-L\fR\ \fIflow_label\fR\fR
356 .ad
357 .sp .6
358 .RS 4n
359 Specify the flow label of probe packets. The value must be an integer in the
360 range from 0 to 1048575. This option is valid only on IPv6.
361 .RE
363 .sp
364 .ne 2
365 .na
366 \fB\fB-l\fR\fR
367 .ad
368 .sp .6
369 .RS 4n
370 Print the value of the \fIttl\fR (\fIhop limit\fR) field in each packet
371 received.
372 .RE
374 .sp
375 .ne 2
376 .na
377 \fB\fB-m\fR \fImax_hop\fR\fR
378 .ad
379 .sp .6
380 .RS 4n
381 Set the maximum \fIttl\fR (\fIhop limit\fR) used in outgoing probe packets. The
382 default is 30 hops, which is the same default used for \fBTCP \fR connections.
383 .RE
385 .sp
386 .ne 2
387 .na
388 \fB\fB-n\fR\fR
389 .ad
390 .sp .6
391 .RS 4n
392 Print hop addresses numerically rather than symbolically and numerically. This
393 saves a nameserver address-to-name lookup for each gateway found on the path.
394 .RE
396 .sp
397 .ne 2
398 .na
399 \fB\fB-P\fR \fIpause_sec\fR\fR
400 .ad
401 .sp .6
402 .RS 4n
403 Specify a delay, in seconds, to pause between probe packets. This may be
404 necessary if the final destination does not accept undeliverable packets in
405 bursts. By default, \fBtraceroute\fR sends the next probe as soon as it has
406 received a reply. Note that \fIpause_sec\fR is a real number.
407 .RE
409 .sp
410 .ne 2
411 .na
412 \fB\fB-p\fR \fIport\fR\fR
413 .ad
414 .sp .6
415 .RS 4n
416 Set the base \fBUDP\fR \fIport\fR number used in probes.The default is 33434.
417 \fBtraceroute\fR hopes that nothing is listening on \fBUDP\fR \fIports\fR
418 \fB(base+(nhops-1)*nqueries)\fR to \fB(base+(nhops*nqueries)-1)\fRat the
419 destination host, so that an \fBICMP\fR (\fBICMP6\fR) \fBPORT_UNREACHABLE\fR
420 message will be returned to terminate the route tracing. If something is
421 listening on a \fIport\fR in the default range, this option can be used to
422 select an unused \fIport\fR range. \fBnhops\fR is defined as the number of hops
423 between the source and the destination.
424 .RE
426 .sp
427 .ne 2
428 .na
429 \fB\fB-Q\fR \fImax_timeout\fR\fR
430 .ad
431 .sp .6
432 .RS 4n
433 Stop probing this hop after \fImax_timeout\fR consecutive timeouts are
434 detected. The default value is 5. Useful in combination with the \fB-q\fR
435 option if you have specified a large \fInqueries\fR probe count.
436 .RE
438 .sp
439 .ne 2
440 .na
441 \fB\fB-q\fR \fInqueries\fR\fR
442 .ad
443 .sp .6
444 .RS 4n
445 Set the desired number of probe queries. The default is 3.
446 .RE
448 .sp
449 .ne 2
450 .na
451 \fB\fB-r\fR\fR
452 .ad
453 .sp .6
454 .RS 4n
455 Bypass the normal routing tables and send directly to a host on an attached
456 network. If the host is not on a directly-attached network, an error is
457 returned. This option can be used to send probes to a local host through an
458 interface that has been dropped by the router deamon. See \fBin.routed\fR(1M).
459 You cannot use this option if the \fB-g\fR option is used.
460 .RE
462 .sp
463 .ne 2
464 .na
465 \fB\fB-S\fR\fR
466 .ad
467 .sp .6
468 .RS 4n
469 Display a summary of how many probes were not answered for each hop.
470 .RE
472 .sp
473 .ne 2
474 .na
475 \fB\fB-s\fR \fIsrc_addr\fR\fR
476 .ad
477 .sp .6
478 .RS 4n
479 Use the following address, which usually is given as a literal \fBIP\fR
480 address, not a hostname, as the source address in outgoing probe packets. On
481 multi-homed hosts, those with more than one \fBIP\fR address, this option can
482 be used to force the source address to be something other than the \fBIP\fR
483 address \fBtraceroute\fR picks by default. If the \fBIP\fR address is not one
484 of this machine's interface addresses, an error is returned and nothing is
485 sent. For IPv4, when used together with the \fB-i\fR option, the given \fBIP\fR
486 address should be configured on the specified interface. Otherwise, an error
487 will be returned. In the case of IPv6, the interface name and the source
488 address do not have to match.
489 .RE
491 .sp
492 .ne 2
493 .na
494 \fB\fB-t\fR \fItos\fR\fR
495 .ad
496 .sp .6
497 .RS 4n
498 Set the \fItos\fR(type-of-service) in probe packets to the specified value. The
499 default is zero. The value must be an integer in the range from 0 to 255.
500 Gateways along the path may route the probe packet differently depending upon
501 the \fItos\fR value set in the probe packet. This option is valid only on IPv4.
502 .RE
504 .sp
505 .ne 2
506 .na
507 \fB\fB-v\fR\fR
508 .ad
509 .sp .6
510 .RS 4n
511 Verbose output. For each hop, the size and the destination of the response
512 packets is displayed. Also \fBICMP\fR (\fBICMP6\fR) packets received other than
513 \fBTIME_EXCEEDED\fR and \fBUNREACHABLE\fR are listed as well.
514 .RE
516 .sp
517 .ne 2
518 .na
519 \fB\fB-w\fR \fIwaittime\fR\fR
520 .ad
521 .sp .6
522 .RS 4n
523 Set the time, in seconds, to wait for a response to a probe. The default is 5
524 seconds.
525 .RE
527 .sp
528 .ne 2
529 .na
530 \fB\fB-x\fR\fR
531 .ad
532 .sp .6
533 .RS 4n
534 Prevent \fBtraceroute\fR from calculating checksums. Checksums are usually
535 required for the last hop when using \fBICMP\fR \fBECHO\fR probes. This option
536 is valid only on IPv4. See the \fB-I\fR option.
537 .sp
538 When specified from within a shared-IP zone, this option has no effect as the
539 checksum is always calculated by the operating system in this case.
540 .RE
542 .SH OPERANDS
543 .sp
544 .LP
545 The following operands are supported:
546 .sp
547 .ne 2
548 .na
549 \fB\fIhost\fR\fR
550 .ad
551 .sp .6
552 .RS 4n
553 The network host.
554 .RE
556 .SH EXAMPLES
557 .LP
558 \fBExample 1 \fRSample Output From the \fBtraceroute\fR Utility
559 .sp
560 .LP
561 Some sample output from the \fBtraceroute\fR utility might be:
563 .sp
564 .in +2
565 .nf
566 istanbul% \fBtraceroute london\fR
567 traceroute: Warning: london has multiple addresses; \e
568 using 4::114:a00:20ff:ab3d:83ed
569 traceroute: Warning: Multiple interfaces found; \e
570 using 4::56:a00:20ff:fe93:8dde @ eri0:2
571 traceroute to london (4::114:a00:20ff:ab3d:83ed), 30 hops max, \e
572 60 byte packets
573 1 frbldg7c-86 (4::56:a00:20ff:fe1f:65a1) 1.786 ms 1.544 ms 1.719 ms
574 2 frbldg7b-77 (4::255:0:0:c0a8:517) 2.587 ms 3.001 ms 2.988 ms
575 3 london (4::114:a00:20ff:ab3d:83ed) 3.122 ms 2.744 ms 3.356 ms
576 .fi
577 .in -2
578 .sp
580 .sp
581 .LP
582 The target host, london, has both IPv4 and IPv6 addresses in the name service
583 database. According to the default behavior, \fBtraceroute\fR uses IPv6 address
584 of the destination host.
586 .LP
587 \fBExample 2 \fRUsing the \fBtraceroute\fR Utility For a Host Which has Only
588 IPv4 Addresses
589 .sp
590 .LP
591 In the following examples, \fBtraceroute\fR is tracking the route to host
592 sanfrancisco, which has only IPv4 addresses in the name service database.
593 Therefore traceroute uses only IPv4 addresses. The following shows the 7-hop
594 path that a packet would follow from the host istanbul to the host
595 sanfrancisco.
597 .sp
598 .in +2
599 .nf
600 istanbul% \fBtraceroute sanfrancisco\fR
601 traceroute: Warning: Multiple interfaces found; using 172.31.86.247 @eri0
602 traceroute to sanfrancisco (172.29.64.39), 30 hops max, 40 byte packets
603 1 frbldg7c-86 (172.31.86.1) 1.516 ms 1.283 ms 1.362 ms
604 2 bldg1a-001 (172.31.1.211) 2.277 ms 1.773 ms 2.186 ms
605 3 bldg4-bldg1 (172.30.4.42) 1.978 ms 1.986 ms 13.996 ms
606 4 bldg6-bldg4 (172.30.4.49) 2.655 ms 3.042 ms 2.344 ms
607 5 ferbldg11a-001 (172.29.1.236) 2.636 ms 3.432 ms 3.830 ms
608 6 frbldg12b-153 (172.29.153.72) 3.452 ms 3.146 ms 2.962 ms
609 7 sanfrancisco (172.29.64.39) 3.430 ms 3.312 ms 3.451 ms
610 .fi
611 .in -2
612 .sp
614 .LP
615 \fBExample 3 \fRUsing the \fBtraceroute\fR Utility With Source Routing
616 .sp
617 .LP
618 The following example shows the path of a packet that goes from istanbul to
619 sanfrancisco through the hosts cairo and paris, as specified by the \fB-g\fR
620 option. The \fB-I\fR option makes \fBtraceroute\fR send \fBICMP\fR \fBECHO\fR
621 probes to the host sanfrancisco. The \fB-i\fR options sets the source address
622 to the \fBIP\fR address configured on the interface \fBqe0\fR.
624 .sp
625 .in +2
626 .nf
627 istanbul% \fBtraceroute -g cairo -g paris -i qe0 -q 1 -I sanfrancisco\fR
628 traceroute to sanfrancisco (172.29.64.39), 30 hops max, 56 byte packets
629 1 frbldg7c-86 (172.31.86.1) 2.012 ms
630 2 flrbldg7u (172.31.17.131) 4.960 ms
631 3 cairo (192.168.163.175) 4.894 ms
632 4 flrbldg7u (172.31.17.131) 3.475 ms
633 5 frbldg7c-017 (172.31.17.83) 4.126 ms
634 6 paris (172.31.86.31) 4.086 ms
635 7 frbldg7b-82 (172.31.82.1) 6.454 ms
636 8 bldg1a-001 (172.31.1.211) 6.541 ms
637 9 bldg6-bldg4 (172.30.4.49) 6.518 ms
638 10 ferbldg11a-001 (172.29.1.236) 9.108 ms
639 11 frbldg12b-153 (172.29.153.72) 9.634 ms
640 12 sanfrancisco (172.29.64.39) 14.631 ms
643 .fi
644 .in -2
645 .sp
647 .SH EXIT STATUS
648 .sp
649 .LP
650 The following exit values are returned:
651 .sp
652 .ne 2
653 .na
654 \fB\fB0\fR\fR
655 .ad
656 .sp .6
657 .RS 4n
658 Successful operation.
659 .RE
661 .sp
662 .ne 2
663 .na
664 \fB>\fB0\fR\fR
665 .ad
666 .sp .6
667 .RS 4n
668 An error occurred.
669 .RE
671 .SH SEE ALSO
672 .sp
673 .LP
674 \fBnetstat\fR(1M), \fBsignal\fR(3C), \fBping\fR(1M), \fBattributes\fR(5),
675 \fBprivileges\fR(5), \fBzones\fR(5)
676 .SH WARNINGS
677 .sp
678 .LP
679 This utility is intended for use in network testing, measurement and
680 management. It should be used primarily for manual fault isolation. Because of
681 the load it could impose on the network, it is unwise to use
682 \fBtraceroute\fR(1M) during normal operations or from automated scripts.