[tripe] / doc / pkstream.1

.\" -*-nroff-*-
.\".
.de hP
.IP
\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
..
.de VS
.sp 1
.RS
.nf
.ft B
..
.de VE
.ft R
.fi
.RE
.sp 1
..
.ie t \{\
.  ds o \(bu
.  ds ss \s8\u
.  ds se \d\s0
.  if \n(.g \{\
.    fam P
.  \}
.\}
.el \{\
.  ds o o
.  ds ss ^
.  ds se
.\}
.TH pkstream 1 "23 April 2003" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
.SH "NAME"
pkstream \- forward UDP packets over streams
.SH "SYNOPSIS"
.B pkstream
.RB [ \-l
.IR port ]
.RB [ \-p
.IR addr ]
.RB [ \-b
.IR addr ]
.RB [ \-c
.IR addr \c
.BR : \c
.IR port ]
.br
	
.IB addr : port
.IB addr : port
.SH "DESCRIPTION"
The
.B pkstream
program forwards UDP packets over some kind of reliable stream.  It
understands TCP sockets natively; anything else has to be fudged up
using some kind of port forwarder like
.BR fw (1),
.BR ssh (1),
.BR stunnel (1),
etc.  It's intended, among other things, to provide a transport for
.BR tripe (8)
packets where there are annoying firewalls in the way.
.SS "Command-line arguments"
The two
.RI ` addr \c
.BR : \c
.IR port '
pairs on the command-line are respectively the UDP port that
.B pkstream
should listen on, and the port which it should receive packets from and
send them to.
.PP
By default,
.B pkstream
will parse packets from the stream attached to its standard input and
send them to its UDP peer; and it will write packets it reads from its
UDP port to the stream attached to its standard output.  The program
will quit when its input stream closes.
.PP
This behaviour can be modified by passing suitable options:
.TP
.B "\-h, \-\-help"
Writes a brief description of the command-line options available to
standard output and exits with status 0.
.TP
.B "\-v, \-\-version"
Writes
.BR tripe 's
version number to standard output and exits with status 0.
.TP
.B "\-u, \-\-usage"
Writes a brief usage summary to standard output and exits with status 0.
.TP
.BI "\-l, \-\-listen=" port
Listen for connections on the given TCP
.IR port .
Only one connection is allowed at a time.  When a connection is
accepted, forward UDP packets over the TCP stream until it closes; then
wait for another connection.
.TP
.BI "\-p, \-\-peer=" addr
Only accept TCP connections from
.IR addr .
This option only makes sense in conjunction with
.BR \-l .
.TP
.BI "\-b, \-\-bind=" addr
When making a connection (see
.B \-c
below), use
.I addr
as the source address rather than letting the kernel choose the address
automatically.  This is useful when the other end will only accept
connections from a particular address and you get the wrong one otherwise.
.TP
.BI "\-c, \-\-connect=" addr : port
Connect to the given
.I addr
and
.I port
and forward packets over the TCP connection rather than using stdin and
stdout.
.SH "Protocol"
The stream protocol is very simple.  Each packet is preceded by a
two-octet length field in network byte order.  The length is number of
octets in the following packet (i.e., it does
.I not
include the length field itself).  There is no padding between packets.
The only way a stream can be invalid is if it stops in the middle of a
packet.
.SH "BUGS"
The code hasn't been audited.  It may contain security bugs.  If you
find one, please inform the author
.IR immediately .
.SH "SEE ALSO"
.BR fw (1),
.BR ssh (1),
.BR stunnel (1),
.BR tripe (8).
.SH "AUTHOR"
Mark Wooding, <mdw@nsict.org>
Commit	Line	Data
07212ba4	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 ]
ef4a1ab7	41	.RB [ \-b
ef4a1ab7	42	.IR addr ]
07212ba4	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
ef4a1ab7	61	.BR tripe (8)
07212ba4	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.
ef4a1ab7	100	.TP
07212ba4	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
ef4a1ab7	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
07212ba4	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@nsict.org>