X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/tripe/blobdiff_plain/e99aedcf9373b3305c32e510c086bf3357b4736a..ddb384f1ac7fbaed5a4dbb02ddc37d0713727be4:/pathmtu/pathmtu.1.in

diff --git a/pathmtu/pathmtu.1.in b/pathmtu/pathmtu.1.in
index aca6bd20..a1eedf76 100644
--- a/pathmtu/pathmtu.1.in
+++ b/pathmtu/pathmtu.1.in
@@ -4,7 +4,7 @@
 .\"
 .\" (c) 2008 Straylight/Edgeware.
 .\"
-
+.
 .\"----- Licensing notice ---------------------------------------------------
 .\"
 .\" This file is part of Trivial IP Encryption (TrIPE).
@@ -38,10 +38,20 @@ pathmtu \- discover path MTU to a given host
 .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 ]
 .
@@ -65,11 +75,29 @@ 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
-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
@@ -84,25 +112,62 @@ Writes tripe's version number to standard output and exits with status
 .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"