chiark - git - mdw - tripe/blob - pathmtu/pathmtu.1.in

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