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