~mdw / tripe / blame_incremental
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (non-incremental) | history | HEAD
server/admin.c: Remove spurious `ping' in usage message.
[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 [ \-46 ]
41.RB [ \-l
42.IR port ]
43.RB [ \-p
44.IR addr ]
45.RB [ \-b
46.IR addr ]
47.RB [ \-c
48.IR addr \c
49.BR : \c
50.IR port ]
51.br
52 \c
53.IB addr : port
54.IB addr : port
55.
56.\"--------------------------------------------------------------------------
57.SH "DESCRIPTION"
58.
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
64.BR fwd (1),
65.BR ssh (1),
66.BR stunnel (1),
67etc. It's intended, among other things, to provide a transport for
68.BR tripe (8)
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.B "\-4"
102Look up hostnames only as IPv4 addresses.
103.TP
104.B "\-6"
105Look up hostnames only as IPv6 addresses.
106.TP
107.BI "\-l, \-\-listen=" port
108Listen for connections on the given TCP
109.IR port .
110Only one connection is allowed at a time. When a connection is
111accepted, forward UDP packets over the TCP stream until it closes; then
112wait for another connection.
113.TP
114.BI "\-p, \-\-peer=" addr
115Only accept TCP connections from
116.IR addr .
117This option only makes sense in conjunction with
118.BR \-l .
119.TP
120.BI "\-b, \-\-bind=" addr
121When listening (see
122.B \-l
123above), only listen on the local address
124.IR addr .
125When making a connection (see
126.B \-c
127below), use
128.I addr
129as the source address rather than letting the kernel choose the address
130automatically. This is useful when the other end will only accept
131connections from a particular address and you get the wrong one otherwise.
132.TP
133.BI "\-c, \-\-connect=" addr : port
134Connect to the given
135.I addr
136and
137.I port
138and forward packets over the TCP connection rather than using stdin and
139stdout.
140.
141.\"--------------------------------------------------------------------------
142.SH "Protocol"
143.
144The stream protocol is very simple. Each packet is preceded by a
145two-octet length field in network byte order. The length is number of
146octets in the following packet (i.e., it does
147.I not
148include the length field itself). There is no padding between packets.
149The only way a stream can be invalid is if it stops in the middle of a
150packet.
151.
152.\"--------------------------------------------------------------------------
153.SH "BUGS"
154.
155The code hasn't been audited. It may contain security bugs. If you
156find one, please inform the author
157.IR immediately .
158.
159.\"--------------------------------------------------------------------------
160.SH "SEE ALSO"
161.
162.BR fwd (1),
163.BR ssh (1),
164.BR stunnel (1),
165.BR tripe (8).
166.
167.\"--------------------------------------------------------------------------
168.SH "AUTHOR"
169.
170Mark Wooding, <mdw@distorted.org.uk>
171.
172.\"----- That's all, folks --------------------------------------------------
Trivial IP Encryption: a simple VPN