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