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
  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 .\"--------------------------------------------------------------------------
  27 .so ../common/defs.man \" @@@PRE@@@
  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
  41 .RB [ \-t
  42 .IR timeout ]
  43 .RB [ \-H
  44 .IR header ]
  45 .I host
  46 .RI [ port ]
  47 .
  48 .\"--------------------------------------------------------------------------
  49 .SH "DESCRIPTION"
  50 .
  51 The
  52 .B pathmtu
  53 program discovers the size of the largest IP packet which can be sent to
  54 a given
  55 .I host
  56 (specified as a dotted-quad IP address or host name) without being
  57 fragmented.  This is useful information, particularly when setting up
  58 VPN tunnel interfaces.
  59 .PP
  60 The program works by sending UDP packets and finding out whether they
  61 get fragmented.  The packets are sent to a specified
  62 .I port
  63 (specified as a number or service name) on the destination host.  The
  64 destination does not need to be listening on the given port \(en indeed,
  65 it doesn't matter if the port is firewalled.  The default port is 7
  66 (echo), chosen because if it is active, we'll get an answer.
  67 .PP
  68 If the local host or some intermediate router is configured to drop ICMP
  69 fragmentation-required errors then the discovery attempt will silently
  70 fail.  It is likely that TCP connections with the destination host will
  71 fail in unexpected ways if this is the case.  Don't drop
  72 fragmentation-required errors!
  73 .PP
  74 Command-line options are as follows.
  75 .TP
  76 .B "\-h, \-\-help"
  77 Writes a brief description of the command-line options available to
  78 standard output and exits with status 0.
  79 .TP
  80 .B "\-v, \-\-version"
  81 Writes tripe's version number to standard output and exits with status
  82 0.
  83 .TP
  84 .B "\-u, \-\-usage"
  85 Writes a brief usage summary to standard output and exits with status 0.
  86 .TP
  87 .BI "\-t, \-\-timeout=" timeout
  88 Sets the time to wait for a reply, in seconds.  If no reply or error is
  89 received within the timeout, it is assumed that the attempt to send a
  90 packet was successful.  The timeout can be fractional; the default is
  91 five seconds.
  92 .TP
  93 .BI "\-H, \-\-header=" header
  94 Sets the packet header, in hexadecimal.  If you set an explicit port
  95 number, it may be worth setting the packet header too, so as not to
  96 alarm anything which might be listening on that port.  The default
  97 packet contents are a fixed pseudorandomly-generated block of data.
  98 .
  99 .\"--------------------------------------------------------------------------
 100 .SH "BUGS"
 101 .
 102 The
 103 .B pathmtu
 104 program currently only works on Linux.  Code for other operating systems
 105 is welcome.
 106 .
 107 .\"--------------------------------------------------------------------------
 108 .SH "AUTHOR"
 109 .
 110 Mark Wooding, <mdw@distorted.org.uk>
 111 .
 112 .\"----- That's all, folks --------------------------------------------------