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

   1 .\" -*-nroff-*-
   2 .\".
   3 .\" Manual for the simple packet streamer
   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 pkstream 1 "23 April 2003" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
  31 .
  32 .\"--------------------------------------------------------------------------
  33 .SH "NAME"
  34 .
  35 pkstream \- forward UDP packets over streams
  36 .
  37 .\"--------------------------------------------------------------------------
  38 .SH "SYNOPSIS"
  39 .
  40 .B pkstream
  41 .RB [ \-l
  42 .IR port ]
  43 .RB [ \-p
  44 .IR addr ]
  45 .RB [ \-b
  46 .IR addr ]
  47 .RB [ \-c
  48 .IR addr \c
  49 .BR : \c
  50 .IR port ]
  51 .br
  52         \c
  53 .IB addr : port
  54 .IB addr : port
  55 .
  56 .\"--------------------------------------------------------------------------
  57 .SH "DESCRIPTION"
  58 .
  59 The
  60 .B pkstream
  61 program forwards UDP packets over some kind of reliable stream.  It
  62 understands TCP sockets natively; anything else has to be fudged up
  63 using some kind of port forwarder like
  64 .BR fwd (1),
  65 .BR ssh (1),
  66 .BR stunnel (1),
  67 etc.  It's intended, among other things, to provide a transport for
  68 .BR tripe (8)
  69 packets where there are annoying firewalls in the way.
  70 .SS "Command-line arguments"
  71 The two
  72 .RI ` addr \c
  73 .BR : \c
  74 .IR port '
  75 pairs on the command-line are respectively the UDP port that
  76 .B pkstream
  77 should listen on, and the port which it should receive packets from and
  78 send them to.
  79 .PP
  80 By default,
  81 .B pkstream
  82 will parse packets from the stream attached to its standard input and
  83 send them to its UDP peer; and it will write packets it reads from its
  84 UDP port to the stream attached to its standard output.  The program
  85 will quit when its input stream closes.
  86 .PP
  87 This behaviour can be modified by passing suitable options:
  88 .TP
  89 .B "\-h, \-\-help"
  90 Writes a brief description of the command-line options available to
  91 standard output and exits with status 0.
  92 .TP
  93 .B "\-v, \-\-version"
  94 Writes
  95 .BR tripe 's
  96 version number to standard output and exits with status 0.
  97 .TP
  98 .B "\-u, \-\-usage"
  99 Writes a brief usage summary to standard output and exits with status 0.
 100 .TP
 101 .BI "\-l, \-\-listen=" port
 102 Listen for connections on the given TCP
 103 .IR port .
 104 Only one connection is allowed at a time.  When a connection is
 105 accepted, forward UDP packets over the TCP stream until it closes; then
 106 wait for another connection.
 107 .TP
 108 .BI "\-p, \-\-peer=" addr
 109 Only accept TCP connections from
 110 .IR addr .
 111 This option only makes sense in conjunction with
 112 .BR \-l .
 113 .TP
 114 .BI "\-b, \-\-bind=" addr
 115 When listening (see
 116 .B \-l
 117 above), only listen on the local address
 118 .IR addr .
 119 When making a connection (see
 120 .B \-c
 121 below), use
 122 .I addr
 123 as the source address rather than letting the kernel choose the address
 124 automatically.  This is useful when the other end will only accept
 125 connections from a particular address and you get the wrong one otherwise.
 126 .TP
 127 .BI "\-c, \-\-connect=" addr : port
 128 Connect to the given
 129 .I addr
 130 and
 131 .I port
 132 and forward packets over the TCP connection rather than using stdin and
 133 stdout.
 134 .
 135 .\"--------------------------------------------------------------------------
 136 .SH "Protocol"
 137 .
 138 The stream protocol is very simple.  Each packet is preceded by a
 139 two-octet length field in network byte order.  The length is number of
 140 octets in the following packet (i.e., it does
 141 .I not
 142 include the length field itself).  There is no padding between packets.
 143 The only way a stream can be invalid is if it stops in the middle of a
 144 packet.
 145 .
 146 .\"--------------------------------------------------------------------------
 147 .SH "BUGS"
 148 .
 149 The code hasn't been audited.  It may contain security bugs.  If you
 150 find one, please inform the author
 151 .IR immediately .
 152 .
 153 .\"--------------------------------------------------------------------------
 154 .SH "SEE ALSO"
 155 .
 156 .BR fwd (1),
 157 .BR ssh (1),
 158 .BR stunnel (1),
 159 .BR tripe (8).
 160 .
 161 .\"--------------------------------------------------------------------------
 162 .SH "AUTHOR"
 163 .
 164 Mark Wooding, <mdw@distorted.org.uk>
 165 .
 166 .\"----- That's all, folks --------------------------------------------------