Debian Codegraph @

upstream/mageia-cauldron/man8/tracepath.8

raw
1 '\" t
2 .TH "TRACEPATH" "8" "" "iputils 20250605" "iputils"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 tracepath \- traces path to a network host discovering MTU along this path
24 .SH "SYNOPSIS"
25 .HP \w'\fBtracepath\fR\ 'u
26 \fBtracepath\fR [\fB\-4\fR] [\fB\-6\fR] [\fB\-n\fR] [\fB\-b\fR] [\fB\-l\ \fR\fB\fIpktlen\fR\fR] [\fB\-m\ \fR\fB\fImax_hops\fR\fR] [\fB\-p\ \fR\fB\fIport\fR\fR] [\fB\-V\fR] {destination}
27 .SH "DESCRIPTION"
28 .PP
29 It traces the network path to
30 \fIdestination\fR
31 discovering MTU along this path\&. It uses UDP port
32 \fIport\fR
33 or some random port\&. It is similar to
34 \fBtraceroute\fR\&. However, it does not require superuser privileges and has no fancy options\&.
35 .PP
36 \fBtracepath \-6\fR
37 is a good replacement for
38 \fBtraceroute6\fR
39 and classic example of application of Linux error queues\&. The situation with IPv4 is worse, because commercial IP routers do not return enough information in ICMP error messages\&. Probably, it will change, when they are updated\&. For now it uses Van Jacobson\*(Aqs trick, sweeping a range of UDP ports to maintain trace history\&.
40 .SH "OPTIONS"
41 .PP
42 \fB\-4\fR
43 .RS 4
44 Use IPv4 only\&.
45 .RE
46 .PP
47 \fB\-6\fR
48 .RS 4
49 Use IPv6 only\&.
50 .RE
51 .PP
52 \fB\-n\fR
53 .RS 4
54 Print primarily IP addresses numerically\&.
55 .RE
56 .PP
57 \fB\-b\fR
58 .RS 4
59 Print both: Host names and IP addresses\&.
60 .RE
61 .PP
62 \fB\-l\fR
63 .RS 4
64 Sets the initial packet length to
65 \fIpktlen\fR
66 instead of 65535 for
67 \fBIPv4\fR
68 or 128000 for
69 \fBIPv6\fR\&.
70 .RE
71 .PP
72 \fB\-m\fR
73 .RS 4
74 Set maximum hops (or maximum TTLs) to
75 \fImax_hops\fR
76 instead of 30\&.
77 .RE
78 .PP
79 \fB\-p\fR
80 .RS 4
81 Sets the initial destination port to use\&.
82 .RE
83 .PP
84 \fB\-V\fR
85 .RS 4
86 Print version and exit\&.
87 .RE
88 .SH "OUTPUT"
89 .sp
90 .if n \{\
91 .RS 4
92 .\}
93 .nf
94 root@mops:~ # tracepath \-6 3ffe:2400:0:109::2
95 1?: [LOCALHOST] pmtu 1500
96 1: dust\&.inr\&.ac\&.ru 0\&.411ms
97 2: dust\&.inr\&.ac\&.ru asymm 1 0\&.390ms pmtu 1480
98 2: 3ffe:2400:0:109::2 463\&.514ms reached
99 Resume: pmtu 1480 hops 2 back 2
100
101 .fi
102 .if n \{\
103 .RE
104 .\}
105 .PP
106 The first column shows the TTL of the probe, followed by colon\&. Usually the value of TTL is obtained from the reply from the network, but sometimes it does not contain the necessary information and we have to guess it\&. In this case the number is followed by ?\&.
107 .PP
108 The second column shows the network hop which replied to the probe\&. It is either the address of the router or the word [LOCALHOST], if the probe was not sent to the network\&.
109 .PP
110 The rest of the line shows miscellaneous information about the path to the corresponding network hop\&. It contains the value of RTT, and additionally it can show Path MTU when it changes\&. If the path is asymmetric or the probe finishes before it reaches the prescribed hop, the number of hops in return direction is shown next to the keyword "asymm"\&. This information is not reliable, e\&.g\&. the third line shows asymmetry of 1\&. This is because the first probe with TTL of 2 was rejected at the first hop due to Path MTU Discovery\&.
111 .PP
112 The last line summarizes information about all the paths to the destination\&. It shows detected Path MTU, amount of hops to the destination and our guess about the number of hops from the destination to us, which can be different when the path is asymmetric\&.
113 .SH "HANDLING ERRORS"
114 .PP
115 In case of errors
116 \fBtracepath\fR
117 prints short error code\&.
118 .TS
119 allbox tab(:);
120 lB lB lB.
121 T{
122 Output
123 T}:T{
124 Code
125 T}:T{
126 Meaning
127 T}
128 .T&
129 lB lB lB
130 lB lB lB
131 lB lB lB
132 lB lB lB
133 lB lB lB
134 lB lB lB
135 lB lB lB
136 lB lB lB.
137 T{
138 !A
139 T}:T{
140 EACCES
141 T}:T{
142 Communication administratively prohibited
143 T}
144 T{
145 !H
146 T}:T{
147 EHOSTUNREACH
148 T}:T{
149 Destination host unreachable
150 T}
151 T{
152 !N
153 T}:T{
154 ENETUNREACH
155 T}:T{
156 Destination network unreachable
157 T}
158 T{
159 !P
160 T}:T{
161 EPROTO
162 T}:T{
163 Destination protocol unreachable
164 T}
165 T{
166 pmtu N
167 T}:T{
168 EMSGSIZE
169 T}:T{
170 Message too long
171 T}
172 T{
173 reached
174 T}:T{
175 ECONNREFUSED
176 T}:T{
177 Connection refused
178 T}
179 T{
180 \ \&
181 T}:T{
182 ETIMEDOUT
183 T}:T{
184 Connection timed out
185 T}
186 T{
187 NET ERROR N
188 T}:T{
189 \ \&
190 T}:T{
191 Any other error
192 T}
193 .TE
194 .sp 1
195 .SH "SEE ALSO"
196 .PP
197 \fBtraceroute\fR(8),
198 \fBtraceroute6\fR(8),
199 \fBping\fR(8)\&.
200 .SH "AUTHOR"
201 .PP
202 \fBtracepath\fR
203 was written by Alexey Kuznetsov <kuznet@ms2\&.inr\&.ac\&.ru>\&.
204 .SH "SECURITY"
205 .PP
206 No security issues\&.
207 .PP
208 This lapidary deserves to be elaborated\&.
209 \fBtracepath\fR
210 is not a privileged program, unlike
211 \fBtraceroute\fR,
212 \fBping\fR
213 and other beasts of their kind\&.
214 \fBtracepath\fR
215 may be executed by everyone who has enough access to the network to send UDP datagrams to the desired destination using the given port\&.
216 .SH "AVAILABILITY"
217 .PP
218 \fBtracepath\fR
219 is part of
220 \fIiputils\fR
221 package\&.