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