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

   1 .\" -*-nroff-*-
   2 .\".
   3 .de hP
   4 .IP
   5 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
   6 ..
   7 .de VS
   8 .sp 1
   9 .RS
  10 .nf
  11 .ft B
  12 ..
  13 .de VE
  14 .ft R
  15 .fi
  16 .RE
  17 .sp 1
  18 ..
  19 .ie t \{\
  20 .  ds o \(bu
  21 .  ds ss \s8\u
  22 .  ds se \d\s0
  23 .  if \n(.g \{\
  24 .    fam P
  25 .  \}
  26 .\}
  27 .el \{\
  28 .  ds o o
  29 .  ds ss ^
  30 .  ds se
  31 .\}
  32 .TH pkstream 1 "23 April 2003" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
  33 .SH "NAME"
  34 pkstream \- forward UDP packets over streams
  35 .SH "SYNOPSIS"
  36 .B pkstream
  37 .RB [ \-l
  38 .IR port ]
  39 .RB [ \-p
  40 .IR addr ]
  41 .RB [ \-c
  42 .IR addr \c
  43 .BR : \c
  44 .IR port ]
  45 .br
  46
  47 .IB addr : port
  48 .IB addr : port
  49 .SH "DESCRIPTION"
  50 The
  51 .B pkstream
  52 program forwards UDP packets over some kind of reliable stream.  It
  53 understands TCP sockets natively; anything else has to be fudged up
  54 using some kind of port forwarder like
  55 .BR fw (1),
  56 .BR ssh (1),
  57 .BR stunnel (1),
  58 etc.  It's intended, among other things, to provide a transport for
  59 .B tripe (8)
  60 packets where there are annoying firewalls in the way.
  61 .SS "Command-line arguments"
  62 The two
  63 .RI ` addr \c
  64 .BR : \c
  65 .IR port '
  66 pairs on the command-line are respectively the UDP port that
  67 .B pkstream
  68 should listen on, and the port which it should receive packets from and
  69 send them to.
  70 .PP
  71 By default,
  72 .B pkstream
  73 will parse packets from the stream attached to its standard input and
  74 send them to its UDP peer; and it will write packets it reads from its
  75 UDP port to the stream attached to its standard output.  The program
  76 will quit when its input stream closes.
  77 .PP
  78 This behaviour can be modified by passing suitable options:
  79 .TP
  80 .B "\-h, \-\-help"
  81 Writes a brief description of the command-line options available to
  82 standard output and exits with status 0.
  83 .TP
  84 .B "\-v, \-\-version"
  85 Writes
  86 .BR tripe 's
  87 version number to standard output and exits with status 0.
  88 .TP
  89 .B "\-u, \-\-usage"
  90 Writes a brief usage summary to standard output and exits with status 0.
  91 .TP
  92 .BI "\-l, \-\-listen=" port
  93 Listen for connections on the given TCP
  94 .IR port .
  95 Only one connection is allowed at a time.  When a connection is
  96 accepted, forward UDP packets over the TCP stream until it closes; then
  97 wait for another connection.
  98 .BI "\-p, \-\-peer=" addr
  99 Only accept TCP connections from
 100 .IR addr .
 101 This option only makes sense in conjunction with
 102 .BR \-l .
 103 .TP
 104 .BI "\-c, \-\-connect=" addr : port
 105 Connect to the given
 106 .I addr
 107 and
 108 .I port
 109 and forward packets over the TCP connection rather than using stdin and
 110 stdout.
 111 .SH "Protocol"
 112 The stream protocol is very simple.  Each packet is preceded by a
 113 two-octet length field in network byte order.  The length is number of
 114 octets in the following packet (i.e., it does
 115 .I not
 116 include the length field itself).  There is no padding between packets.
 117 The only way a stream can be invalid is if it stops in the middle of a
 118 packet.
 119 .SH "BUGS"
 120 The code hasn't been audited.  It may contain security bugs.  If you
 121 find one, please inform the author
 122 .IR immediately .
 123 .SH "SEE ALSO"
 124 .BR fw (1),
 125 .BR ssh (1),
 126 .BR stunnel (1),
 127 .BR tripe (8).
 128 .SH "AUTHOR"
 129 Mark Wooding, <mdw@nsict.org>