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 | .\" | |
11ad66c2 MW |
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. | |
fc916a09 | 16 | .\" |
11ad66c2 MW |
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. | |
fc916a09 MW |
21 | .\" |
22 | .\" You should have received a copy of the GNU General Public License | |
11ad66c2 | 23 | .\" along with TrIPE. If not, see <https://www.gnu.org/licenses/>. |
fc916a09 MW |
24 | . |
25 | .\"-------------------------------------------------------------------------- | |
e99aedcf | 26 | .so ../common/defs.man \" @@@PRE@@@ |
fc916a09 MW |
27 | . |
28 | .\"-------------------------------------------------------------------------- | |
07212ba4 | 29 | .TH pkstream 1 "23 April 2003" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" |
fc916a09 MW |
30 | . |
31 | .\"-------------------------------------------------------------------------- | |
07212ba4 | 32 | .SH "NAME" |
fc916a09 | 33 | . |
07212ba4 | 34 | pkstream \- forward UDP packets over streams |
fc916a09 MW |
35 | . |
36 | .\"-------------------------------------------------------------------------- | |
07212ba4 | 37 | .SH "SYNOPSIS" |
fc916a09 | 38 | . |
07212ba4 | 39 | .B pkstream |
e7fb7115 | 40 | .RB [ \-46 ] |
07212ba4 | 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 | |
e7fb7115 MW |
101 | .B "\-4" |
102 | Look up hostnames only as IPv4 addresses. | |
103 | .TP | |
104 | .B "\-6" | |
105 | Look up hostnames only as IPv6 addresses. | |
106 | .TP | |
07212ba4 | 107 | .BI "\-l, \-\-listen=" port |
108 | Listen for connections on the given TCP | |
109 | .IR port . | |
110 | Only one connection is allowed at a time. When a connection is | |
111 | accepted, forward UDP packets over the TCP stream until it closes; then | |
112 | wait for another connection. | |
ef4a1ab7 | 113 | .TP |
07212ba4 | 114 | .BI "\-p, \-\-peer=" addr |
115 | Only accept TCP connections from | |
116 | .IR addr . | |
117 | This option only makes sense in conjunction with | |
118 | .BR \-l . | |
119 | .TP | |
ef4a1ab7 | 120 | .BI "\-b, \-\-bind=" addr |
30678daa MW |
121 | When listening (see |
122 | .B \-l | |
123 | above), only listen on the local address | |
124 | .IR addr . | |
ef4a1ab7 | 125 | When making a connection (see |
126 | .B \-c | |
127 | below), use | |
128 | .I addr | |
129 | as the source address rather than letting the kernel choose the address | |
130 | automatically. This is useful when the other end will only accept | |
131 | connections from a particular address and you get the wrong one otherwise. | |
132 | .TP | |
07212ba4 | 133 | .BI "\-c, \-\-connect=" addr : port |
134 | Connect to the given | |
135 | .I addr | |
136 | and | |
137 | .I port | |
138 | and forward packets over the TCP connection rather than using stdin and | |
139 | stdout. | |
fc916a09 MW |
140 | . |
141 | .\"-------------------------------------------------------------------------- | |
07212ba4 | 142 | .SH "Protocol" |
fc916a09 | 143 | . |
07212ba4 | 144 | The stream protocol is very simple. Each packet is preceded by a |
145 | two-octet length field in network byte order. The length is number of | |
146 | octets in the following packet (i.e., it does | |
147 | .I not | |
148 | include the length field itself). There is no padding between packets. | |
149 | The only way a stream can be invalid is if it stops in the middle of a | |
150 | packet. | |
fc916a09 MW |
151 | . |
152 | .\"-------------------------------------------------------------------------- | |
07212ba4 | 153 | .SH "BUGS" |
fc916a09 | 154 | . |
07212ba4 | 155 | The code hasn't been audited. It may contain security bugs. If you |
156 | find one, please inform the author | |
157 | .IR immediately . | |
fc916a09 MW |
158 | . |
159 | .\"-------------------------------------------------------------------------- | |
07212ba4 | 160 | .SH "SEE ALSO" |
fc916a09 | 161 | . |
bd7248fa | 162 | .BR fwd (1), |
07212ba4 | 163 | .BR ssh (1), |
164 | .BR stunnel (1), | |
165 | .BR tripe (8). | |
fc916a09 MW |
166 | . |
167 | .\"-------------------------------------------------------------------------- | |
07212ba4 | 168 | .SH "AUTHOR" |
fc916a09 | 169 | . |
d36eda2a | 170 | Mark Wooding, <mdw@distorted.org.uk> |
fc916a09 MW |
171 | . |
172 | .\"----- That's all, folks -------------------------------------------------- |