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