chiark / gitweb /
Build: Fix construction of manual pages.
[tripe] / pkstream / pkstream.1.in
CommitLineData
07212ba4 1.\" -*-nroff-*-
2.\".
fc916a09
MW
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
13.\" it under the terms of the GNU General Public License as published by
14.\" the Free Software Foundation; either version 2 of the License, or
15.\" (at your option) any later version.
16.\"
17.\" TrIPE is distributed in the hope that it will be useful,
18.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
19.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20.\" GNU General Public License for more details.
21.\"
22.\" You should have received a copy of the GNU General Public License
23.\" along with TrIPE; if not, write to the Free Software Foundation,
24.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
25.
26.\"--------------------------------------------------------------------------
e99aedcf 27.so ../common/defs.man \" @@@PRE@@@
fc916a09
MW
28.
29.\"--------------------------------------------------------------------------
07212ba4 30.TH pkstream 1 "23 April 2003" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
fc916a09
MW
31.
32.\"--------------------------------------------------------------------------
07212ba4 33.SH "NAME"
fc916a09 34.
07212ba4 35pkstream \- forward UDP packets over streams
fc916a09
MW
36.
37.\"--------------------------------------------------------------------------
07212ba4 38.SH "SYNOPSIS"
fc916a09 39.
07212ba4 40.B pkstream
41.RB [ \-l
42.IR port ]
43.RB [ \-p
44.IR addr ]
ef4a1ab7 45.RB [ \-b
46.IR addr ]
07212ba4 47.RB [ \-c
48.IR addr \c
49.BR : \c
50.IR port ]
51.br
e04c2d50 52
07212ba4 53.IB addr : port
54.IB addr : port
fc916a09
MW
55.
56.\"--------------------------------------------------------------------------
07212ba4 57.SH "DESCRIPTION"
fc916a09 58.
07212ba4 59The
60.B pkstream
61program forwards UDP packets over some kind of reliable stream. It
62understands TCP sockets natively; anything else has to be fudged up
63using some kind of port forwarder like
bd7248fa 64.BR fwd (1),
07212ba4 65.BR ssh (1),
66.BR stunnel (1),
67etc. It's intended, among other things, to provide a transport for
ef4a1ab7 68.BR tripe (8)
07212ba4 69packets where there are annoying firewalls in the way.
70.SS "Command-line arguments"
71The two
72.RI ` addr \c
73.BR : \c
74.IR port '
75pairs on the command-line are respectively the UDP port that
76.B pkstream
77should listen on, and the port which it should receive packets from and
78send them to.
79.PP
80By default,
81.B pkstream
82will parse packets from the stream attached to its standard input and
83send them to its UDP peer; and it will write packets it reads from its
84UDP port to the stream attached to its standard output. The program
85will quit when its input stream closes.
86.PP
87This behaviour can be modified by passing suitable options:
88.TP
89.B "\-h, \-\-help"
90Writes a brief description of the command-line options available to
91standard output and exits with status 0.
92.TP
93.B "\-v, \-\-version"
94Writes
95.BR tripe 's
96version number to standard output and exits with status 0.
97.TP
98.B "\-u, \-\-usage"
99Writes a brief usage summary to standard output and exits with status 0.
100.TP
101.BI "\-l, \-\-listen=" port
102Listen for connections on the given TCP
103.IR port .
104Only one connection is allowed at a time. When a connection is
105accepted, forward UDP packets over the TCP stream until it closes; then
106wait for another connection.
ef4a1ab7 107.TP
07212ba4 108.BI "\-p, \-\-peer=" addr
109Only accept TCP connections from
110.IR addr .
111This option only makes sense in conjunction with
112.BR \-l .
113.TP
ef4a1ab7 114.BI "\-b, \-\-bind=" addr
115When making a connection (see
116.B \-c
117below), use
118.I addr
119as the source address rather than letting the kernel choose the address
120automatically. This is useful when the other end will only accept
121connections from a particular address and you get the wrong one otherwise.
122.TP
07212ba4 123.BI "\-c, \-\-connect=" addr : port
124Connect to the given
125.I addr
126and
127.I port
128and forward packets over the TCP connection rather than using stdin and
129stdout.
fc916a09
MW
130.
131.\"--------------------------------------------------------------------------
07212ba4 132.SH "Protocol"
fc916a09 133.
07212ba4 134The stream protocol is very simple. Each packet is preceded by a
135two-octet length field in network byte order. The length is number of
136octets in the following packet (i.e., it does
137.I not
138include the length field itself). There is no padding between packets.
139The only way a stream can be invalid is if it stops in the middle of a
140packet.
fc916a09
MW
141.
142.\"--------------------------------------------------------------------------
07212ba4 143.SH "BUGS"
fc916a09 144.
07212ba4 145The code hasn't been audited. It may contain security bugs. If you
146find one, please inform the author
147.IR immediately .
fc916a09
MW
148.
149.\"--------------------------------------------------------------------------
07212ba4 150.SH "SEE ALSO"
fc916a09 151.
bd7248fa 152.BR fwd (1),
07212ba4 153.BR ssh (1),
154.BR stunnel (1),
155.BR tripe (8).
fc916a09
MW
156.
157.\"--------------------------------------------------------------------------
07212ba4 158.SH "AUTHOR"
fc916a09 159.
d36eda2a 160Mark Wooding, <mdw@distorted.org.uk>
fc916a09
MW
161.
162.\"----- That's all, folks --------------------------------------------------