Commit | Line | Data |
---|---|---|
49f86fe4 MW |
1 | .\" -*-nroff-*- |
2 | .\" | |
3 | .\" Documentation for uslip | |
4 | .\" | |
5 | .\" (c) 2008 Straylight/Edgeware. | |
6 | .\" | |
11ad66c2 | 7 | . |
49f86fe4 MW |
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. | |
49f86fe4 | 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. | |
49f86fe4 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/>. |
49f86fe4 MW |
24 | . |
25 | .\"-------------------------------------------------------------------------- | |
e99aedcf | 26 | .so ../common/defs.man \" @@@PRE@@@ |
49f86fe4 MW |
27 | . |
28 | .\"-------------------------------------------------------------------------- | |
0647ba7c | 29 | .TH tripe-uslip 1tripe "7 April 2008" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" |
49f86fe4 MW |
30 | . |
31 | .\"-------------------------------------------------------------------------- | |
32 | .SH "NAME" | |
33 | . | |
34 | tripe-uslip \- fake SLIP interface for testing tripe | |
35 | . | |
36 | .\"-------------------------------------------------------------------------- | |
37 | .SH "SYNOPSIS" | |
38 | . | |
39 | .B tripe-uslip | |
1e14551a | 40 | .RB [ \-fgps ] |
49f86fe4 MW |
41 | .I socket |
42 | . | |
43 | .\"-------------------------------------------------------------------------- | |
44 | .SH "DESCRIPTION" | |
45 | . | |
46 | The | |
47 | .B tripe-uslip | |
48 | provides a mechanism for pushing packets of data into a | |
49 | .BR tripe (8) | |
50 | server, and extracting them. This is useful for testing the server; it | |
51 | isn't useful in a production environment. | |
52 | .SS "Overview and theory of operation" | |
53 | Testing the | |
54 | .BR tripe (8) | |
55 | server is difficult: configuring network interfaces and creating tunnels | |
56 | requires root privileges (undesirable for a program under development!) | |
57 | and testing that it successfully transports network packets needs two | |
58 | separate instances running on separate machines. (If both ends of a | |
59 | tunnel are on the same host then the packets won't actually go over the | |
60 | tunnel: the kernel will just loop them back internally.) | |
61 | .PP | |
62 | The | |
63 | .B tripe-uslip | |
64 | program implements the interface required of a dynamic allocation script | |
65 | (see the | |
66 | .BR tripe (8) | |
67 | manual for details). However, it doesn't actually make a network | |
68 | interface. | |
69 | .PP | |
70 | You use it by setting | |
71 | .IP | |
72 | .BI TRIPE_SLIPIF= dir /tripe-uslip | |
73 | .PP | |
74 | in the environment passed to the | |
75 | .BR tripe (8) | |
76 | server (and, typically, passing it the | |
77 | .B \-tslip | |
78 | command-line option). When you add a new peer with the | |
79 | .B ADD | |
80 | .I peer | |
81 | .IR address ... | |
82 | administration command, the server runs | |
83 | .IB dir /tripe-uslip | |
84 | .IR peer , | |
85 | which in turn creates a Unix-domain socket called | |
86 | .I peer | |
87 | in the server's current directory. If you run | |
88 | .IP | |
89 | .B tripe-uslip | |
90 | .B \-p | |
91 | .I peer | |
92 | .BI < file | |
93 | .PP | |
94 | in this directory, then the contents of | |
95 | .I file | |
96 | are sent to | |
97 | .B tripe | |
98 | as if they were a network packet to be encrypted and transmitted over | |
99 | its tunnel. (Any method of providing the data on standard input is | |
100 | acceptable: it doesn't have to be a regular file. In particular, pipes | |
101 | are fine. Note also that | |
102 | .B tripe | |
103 | doesn't actually care that the data it receives is actually network | |
104 | packets: it can be absolutely anything you like.) | |
105 | .PP | |
106 | If you run | |
107 | .IP | |
108 | .B tripe-uslip | |
109 | .B \-g | |
110 | .I peer | |
111 | .BI > file | |
112 | .PP | |
113 | then the contents of the next network packet the server decrypts will be | |
114 | written to the | |
115 | .IR file . | |
116 | (Again, you can use pipes or whatever.) | |
117 | .PP | |
118 | The | |
119 | .B tripe-uslip | |
120 | program is fully nonblocking. This means that you won't deadlock the | |
121 | server by attaching duff scripts to it via | |
122 | .BR tripe-uslip . | |
123 | .SS "Technical details" | |
124 | Without options, | |
125 | .B tripe-uslip | |
126 | performs the following actions. | |
127 | .hP \*o | |
128 | It creates a Unix-domain socket with name | |
129 | .I socket | |
130 | (which will typically be the name of the peer that | |
131 | .BR tripe (8) | |
132 | created this interface for). | |
133 | .hP \*o | |
134 | It writes the string | |
135 | .BI tripe-uslip- socket | |
136 | to its standard output, followed by a newline. | |
137 | .hP \*o | |
138 | It reads and discards up to two bytes with value 192 (SLIP | |
139 | .BR END ) | |
140 | on stdin. | |
141 | .hP \*o | |
142 | It enters its main loop, during which it accepts and processes client | |
143 | connections, and reads and writes SLIP-encoded packets on standard input | |
144 | and output. Unless a fatal error occurs, the main loop continues until | |
145 | it (a) has no connected clients, (b) has no packets queued for output to | |
146 | clients or to standard output, and (c) has seen end-of-file on its | |
147 | standard input. | |
148 | .PP | |
149 | The main loop works as follows. When a SLIP-encoded packet arrives on | |
150 | standard input, it is decoded and placed on a queue waiting to be read | |
151 | from a client. If a client connects and writes a packet, the packet is | |
152 | SLIP-encoded and written to standard output. | |
153 | .PP | |
154 | Clients connecting to the | |
155 | Unix-domain socket send an initial character | |
156 | .RB ` < ' | |
157 | to read a packet or | |
158 | .RB ` > ' | |
159 | to write. Packets, as far as clients are concerned, consist of | |
160 | uninterpreted strings of octets and continue until end-of-file. It is | |
161 | not possible to read or write more than one packet in a single connection. | |
162 | .PP | |
163 | The command-line options allow | |
164 | .B tripe-uslip | |
165 | to be used from scripts to inject or collect packets. They are as follows. | |
166 | .TP | |
167 | .B \-g, \-\-get | |
168 | Connect to | |
169 | .IR socket , | |
170 | read a packet from the socket and write it to standard output. | |
171 | .TP | |
172 | .B \-p, \-\-put | |
173 | Connect to | |
174 | .IR socket , | |
175 | read a packet from standard input and write it to the socket. | |
1e14551a MW |
176 | .TP |
177 | .B \-f, \-\-flood | |
178 | Connect to | |
179 | .IR socket , | |
180 | and send packets as fast as possible. The packets sent aren't very | |
181 | interesting, and there's no way to configure their contents. | |
182 | .TP | |
183 | .B \-s, \-\-sink | |
184 | Connect to | |
185 | .IR socket | |
186 | and read packets as the become available. The packets are discarded, | |
187 | though if stdout is a terminal, a simple spinning-baton animation is | |
188 | updated once for each group of packets. If you are flooding one end of | |
189 | a TrIPE connection, it's advisable to attach a sink to the other: | |
190 | otherwise the destination | |
191 | .B tripe-uslip | |
192 | will attempt to consume all available memory, storing incoming packets | |
193 | until someone retrieves them. | |
49f86fe4 MW |
194 | . |
195 | .\"-------------------------------------------------------------------------- | |
196 | .SH "BUGS" | |
197 | . | |
198 | The | |
199 | .B tripe-uslip | |
200 | program is intended as a tool for testing the | |
201 | .BR tripe (8) | |
202 | server. It is not expected to be useful in production environments. In | |
203 | particular, it intentionally imposes no limits on queue lengths or | |
204 | packet sizes, and its internals and interface (one packet per client | |
1e14551a MW |
205 | connection) are not well-suited for high performance. That said, the |
206 | flood option has worked well enough to expose bugs in | |
207 | .BR tripe 's | |
208 | behaviour under heavy loads. | |
49f86fe4 MW |
209 | .PP |
210 | If | |
211 | .B tripe-uslip | |
212 | turns out to be useful in other contexts then it might be improved. | |
213 | Patches are, of course, welcome. | |
214 | .PP | |
215 | The initial ignoring of | |
216 | .B END | |
217 | bytes is unpleasant but necessary to cope with the | |
218 | .BR tripe (8) | |
219 | server, which sends this sequence in order to ensure that it's properly | |
220 | synchronized with the SLIP interface. | |
221 | . | |
222 | .\"-------------------------------------------------------------------------- | |
223 | .SH "SEE ALSO" | |
224 | . | |
225 | .BR tripe (8). | |
226 | . | |
227 | .\"-------------------------------------------------------------------------- | |
228 | .SH "AUTHOR" | |
229 | . | |
230 | Mark Wooding, <mdw@distorted.org.uk> | |
231 | . | |
232 | .\"----- That's all, folks -------------------------------------------------- |