[tripe] / pathmtu / pathmtu.1.in

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