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