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