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