3 .\" Documentation for uslip
5 .\" (c) 2008 Straylight/Edgeware.
8 .\"----- Licensing notice ---------------------------------------------------
10 .\" This file is part of Trivial IP Encryption (TrIPE).
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.
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
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/>.
25 .\"--------------------------------------------------------------------------
26 .so ../common/defs.man \" @@@PRE@@@
28 .\"--------------------------------------------------------------------------
29 .TH tripe-uslip 1tripe "7 April 2008" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
31 .\"--------------------------------------------------------------------------
34 tripe-uslip \- fake SLIP interface for testing tripe
36 .\"--------------------------------------------------------------------------
43 .\"--------------------------------------------------------------------------
48 provides a mechanism for pushing packets of data into a
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"
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.)
64 program implements the interface required of a dynamic allocation script
67 manual for details). However, it doesn't actually make a network
72 .BI TRIPE_SLIPIF= dir /tripe-uslip
74 in the environment passed to the
76 server (and, typically, passing it the
78 command-line option). When you add a new peer with the
82 administration command, the server runs
85 which in turn creates a Unix-domain socket called
87 in the server's current directory. If you run
94 in this directory, then the contents of
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
103 doesn't actually care that the data it receives is actually network
104 packets: it can be absolutely anything you like.)
113 then the contents of the next network packet the server decrypts will be
116 (Again, you can use pipes or whatever.)
120 program is fully nonblocking. This means that you won't deadlock the
121 server by attaching duff scripts to it via
123 .SS "Technical details"
126 performs the following actions.
128 It creates a Unix-domain socket with name
130 (which will typically be the name of the peer that
132 created this interface for).
135 .BI tripe-uslip- socket
136 to its standard output, followed by a newline.
138 It reads and discards up to two bytes with value 192 (SLIP
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
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.
154 Clients connecting to the
155 Unix-domain socket send an initial character
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.
163 The command-line options allow
165 to be used from scripts to inject or collect packets. They are as follows.
170 read a packet from the socket and write it to standard output.
175 read a packet from standard input and write it to the 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.
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
192 will attempt to consume all available memory, storing incoming packets
193 until someone retrieves them.
195 .\"--------------------------------------------------------------------------
200 program is intended as a tool for testing the
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
205 connection) are not well-suited for high performance. That said, the
206 flood option has worked well enough to expose bugs in
208 behaviour under heavy loads.
212 turns out to be useful in other contexts then it might be improved.
213 Patches are, of course, welcome.
215 The initial ignoring of
217 bytes is unpleasant but necessary to cope with the
219 server, which sends this sequence in order to ensure that it's properly
220 synchronized with the SLIP interface.
222 .\"--------------------------------------------------------------------------
227 .\"--------------------------------------------------------------------------
230 Mark Wooding, <mdw@distorted.org.uk>
232 .\"----- That's all, folks --------------------------------------------------