Commit | Line | Data |
---|---|---|
c64d8cd5 MW |
1 | .\" -*-nroff-*- |
2 | .\" | |
3 | .\" Documentation for pathmtu | |
4 | .\" | |
5 | .\" (c) 2008 Straylight/Edgeware. | |
6 | .\" | |
88510d86 | 7 | . |
c64d8cd5 MW |
8 | .\"----- Licensing notice --------------------------------------------------- |
9 | .\" | |
10 | .\" This file is part of Trivial IP Encryption (TrIPE). | |
11 | .\" | |
11ad66c2 MW |
12 | .\" TrIPE is free software: you can redistribute it and/or modify it under |
13 | .\" the terms of the GNU General Public License as published by the Free | |
14 | .\" Software Foundation; either version 3 of the License, or (at your | |
15 | .\" option) any later version. | |
c64d8cd5 | 16 | .\" |
11ad66c2 MW |
17 | .\" TrIPE is distributed in the hope that it will be useful, but WITHOUT |
18 | .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
19 | .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
20 | .\" for more details. | |
c64d8cd5 MW |
21 | .\" |
22 | .\" You should have received a copy of the GNU General Public License | |
11ad66c2 | 23 | .\" along with TrIPE. If not, see <https://www.gnu.org/licenses/>. |
c64d8cd5 MW |
24 | . |
25 | .\"-------------------------------------------------------------------------- | |
e99aedcf | 26 | .so ../common/defs.man \" @@@PRE@@@ |
c64d8cd5 MW |
27 | . |
28 | .\"-------------------------------------------------------------------------- | |
29 | .TH pathmtu 1 "29 December 2008" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" | |
30 | . | |
31 | .\"-------------------------------------------------------------------------- | |
32 | .SH "NAME" | |
33 | . | |
34 | pathmtu \- discover path MTU to a given host | |
35 | . | |
36 | .\"-------------------------------------------------------------------------- | |
37 | .SH "SYNOPSIS" | |
38 | . | |
39 | .B pathmtu | |
22062fb6 | 40 | .RB [ \-46v ] |
c64d8cd5 MW |
41 | .RB [ \-H |
42 | .IR header ] | |
88510d86 MW |
43 | .RB [ \-m |
44 | .IR method ] | |
45 | .br | |
46 | \c | |
47 | .RB [ \-r | |
48 | .IR retransmit ] | |
49 | .RB [ \-g | |
50 | .IR factor ] | |
51 | .RB [ \-t | |
52 | .IR timeout ] | |
53 | .br | |
54 | \c | |
c64d8cd5 MW |
55 | .I host |
56 | .RI [ port ] | |
57 | . | |
58 | .\"-------------------------------------------------------------------------- | |
59 | .SH "DESCRIPTION" | |
60 | . | |
61 | The | |
62 | .B pathmtu | |
63 | program discovers the size of the largest IP packet which can be sent to | |
64 | a given | |
65 | .I host | |
66 | (specified as a dotted-quad IP address or host name) without being | |
67 | fragmented. This is useful information, particularly when setting up | |
68 | VPN tunnel interfaces. | |
69 | .PP | |
70 | The program works by sending UDP packets and finding out whether they | |
71 | get fragmented. The packets are sent to a specified | |
72 | .I port | |
73 | (specified as a number or service name) on the destination host. The | |
74 | destination does not need to be listening on the given port \(en indeed, | |
75 | it doesn't matter if the port is firewalled. The default port is 7 | |
76 | (echo), chosen because if it is active, we'll get an answer. | |
77 | .PP | |
88510d86 MW |
78 | The |
79 | .B pathmtu | |
80 | program attempts to find a correct answer even if ICMP | |
81 | fragmentation-required packets are suppressed. It distinguishes between | |
82 | the remote host dropping packets and an intermediate router failing to | |
83 | report fragmentation-needed errors by sending a minimum-size packet and | |
84 | seeing whether it gets any response to that. | |
85 | .PP | |
86 | The | |
87 | .B pathmtu | |
88 | program (currently) contains two different methods for MTU probing. One | |
89 | uses the Linux-specific | |
90 | .B IP_MTU | |
91 | and | |
92 | .B IP_MTU_DISCOVER | |
93 | socket options; this works fine even as an unprivileged user. The other | |
94 | uses raw sockets, so it's fairly portable, but | |
95 | .B pathmtu | |
96 | must be installed setuid-root to work. (It attempts to create its raw | |
97 | sockets as its first action \(en before processing the command line \(en | |
98 | and drops privileges immediately afterwards, so the attack surface is | |
99 | very tiny.) The raw sockets method is very slightly more robust: | |
100 | specifically, it's much less likely to get confused by delayed errors. | |
c64d8cd5 MW |
101 | .PP |
102 | Command-line options are as follows. | |
103 | .TP | |
104 | .B "\-h, \-\-help" | |
105 | Writes a brief description of the command-line options available to | |
106 | standard output and exits with status 0. | |
107 | .TP | |
b13c3272 | 108 | .B "\-V, \-\-version" |
c64d8cd5 MW |
109 | Writes tripe's version number to standard output and exits with status |
110 | 0. | |
111 | .TP | |
112 | .B "\-u, \-\-usage" | |
113 | Writes a brief usage summary to standard output and exits with status 0. | |
114 | .TP | |
22062fb6 MW |
115 | .B "\-4" |
116 | Look up hostnames only as IPv4 addresses. | |
117 | .TP | |
118 | .B "\-6" | |
119 | Look up hostnames only as IPv6 addresses. | |
120 | .TP | |
88510d86 MW |
121 | .BI "\-g, \-\-growth=" factor |
122 | Sets the retransmit interval growth factor. Each time a packet is | |
123 | retransmitted, | |
124 | .B pathmtu | |
125 | increases the amount of time it waits before retransmitting again by | |
126 | this | |
127 | .IR factor . | |
128 | The default growth factor is 3. | |
129 | .TP | |
130 | .BI "\-m, \-\-method=" name | |
131 | Select the MTU probing method. The available methods are shown by | |
132 | .BR \-\-help . | |
133 | The | |
134 | .B linux | |
135 | method is Linux-specific and might be confused by delayed errors under | |
136 | some circumstances, but it's usable by unprivileged users; the | |
137 | .B raw | |
138 | method is portable but requires | |
139 | .B pathmtu | |
140 | to be installed setuid-root. | |
141 | .TP | |
142 | .BI "\-r, \-\-retransmit=" interval | |
143 | Sets the initial retransmit interval, in seconds. If no reply is | |
144 | received to a probe within the interval, then a second packet is sent, | |
145 | and the retransmit interval increased by the growth factor (see | |
146 | .BR \-g ). | |
147 | The default initial retransmit interval is 0.333 seconds. | |
148 | .TP | |
c64d8cd5 MW |
149 | .BI "\-t, \-\-timeout=" timeout |
150 | Sets the time to wait for a reply, in seconds. If no reply or error is | |
88510d86 MW |
151 | received within the timeout, it is assumed that no reply will be |
152 | forthcoming. If we've ever received a reply from the remote host in the | |
153 | past, then | |
154 | .B pathmtu | |
155 | assumes that a timeout indicates that the packet was too large, but the | |
156 | ICMP fragmentation-required error was suppressed as a result of | |
157 | administrative incompetence by someone responsible for an intermediate | |
158 | router. Otherwise, | |
159 | .B pathmtu | |
160 | sends a small packet to settle the question of where packets are being | |
161 | dropped: if it doesn't receive a response to this packet either, then it | |
162 | assumes that the timeout means that the remote host | |
163 | .I did | |
164 | receive the packet. The default timeout is 8 seconds. | |
c64d8cd5 | 165 | .TP |
a8f70fe1 MW |
166 | .B "\-v, \-\-verbose" |
167 | Write a running human-readable commentary to standard error about the | |
168 | progress of the operation. Usually, | |
169 | .B pathmtu | |
170 | does its job silently unless there are errors. | |
171 | .TP | |
c64d8cd5 MW |
172 | .BI "\-H, \-\-header=" header |
173 | Sets the packet header, in hexadecimal. If you set an explicit port | |
174 | number, it may be worth setting the packet header too, so as not to | |
88510d86 MW |
175 | alarm anything which might be listening on that port. A sequence number |
176 | (in order to disambiguate replies) and some pseudorandom data are | |
177 | appended to the header. The default header is empty. | |
c64d8cd5 MW |
178 | . |
179 | .\"-------------------------------------------------------------------------- | |
180 | .SH "BUGS" | |
181 | . | |
88510d86 | 182 | The whole business of probing path MTUs is rather unpleasant. |
c64d8cd5 MW |
183 | . |
184 | .\"-------------------------------------------------------------------------- | |
185 | .SH "AUTHOR" | |
186 | . | |
187 | Mark Wooding, <mdw@distorted.org.uk> | |
188 | . | |
189 | .\"----- That's all, folks -------------------------------------------------- |