| 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 -------------------------------------------------- |