.\"
.\" (c) 2008 Straylight/Edgeware.
.\"
-
+.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of Trivial IP Encryption (TrIPE).
.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
.
.\"--------------------------------------------------------------------------
-.so ../defs.man.in \" @@@PRE@@@
+.so ../common/defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH pathmtu 1 "29 December 2008" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
.SH "SYNOPSIS"
.
.B pathmtu
-.RB [ \-t
-.IR timeout ]
.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 ]
.
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
-If the local host or some intermediate router is configured to drop ICMP
-fragmentation-required errors then the discovery attempt will silently
-fail. It is likely that TCP connections with the destination host will
-fail in unexpected ways if this is the case. Don't drop
-fragmentation-required errors!
+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 "\-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 the attempt to send a
-packet was successful. The timeout can be fractional; the default is
-five seconds.
+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. The default
-packet contents are a fixed pseudorandomly-generated block of data.
+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
-.B pathmtu
-program currently only works on Linux. Code for other operating systems
-is welcome.
+The whole business of probing path MTUs is rather unpleasant.
.
.\"--------------------------------------------------------------------------
.SH "AUTHOR"
~mdw / tripe / blobdiff