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