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
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.
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.
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.
26 .\"--------------------------------------------------------------------------
27 .so ../defs.man.in \" @@@PRE@@@
29 .\"--------------------------------------------------------------------------
30 .TH tripe-uslip 1 "7 April 2008" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
32 .\"--------------------------------------------------------------------------
35 tripe-uslip \- fake SLIP interface for testing tripe
37 .\"--------------------------------------------------------------------------
44 .\"--------------------------------------------------------------------------
49 provides a mechanism for pushing packets of data into a
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"
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.)
65 program implements the interface required of a dynamic allocation script
68 manual for details). However, it doesn't actually make a network
73 .BI TRIPE_SLIPIF= dir /tripe-uslip
75 in the environment passed to the
77 server (and, typically, passing it the
79 command-line option). When you add a new peer with the
83 administration command, the server runs
86 which in turn creates a Unix-domain socket called
88 in the server's current directory. If you run
95 in this directory, then the contents of
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
104 doesn't actually care that the data it receives is actually network
105 packets: it can be absolutely anything you like.)
114 then the contents of the next network packet the server decrypts will be
117 (Again, you can use pipes or whatever.)
121 program is fully nonblocking. This means that you won't deadlock the
122 server by attaching duff scripts to it via
124 .SS "Technical details"
127 performs the following actions.
129 It creates a Unix-domain socket with name
131 (which will typically be the name of the peer that
133 created this interface for).
136 .BI tripe-uslip- socket
137 to its standard output, followed by a newline.
139 It reads and discards up to two bytes with value 192 (SLIP
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
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.
155 Clients connecting to the
156 Unix-domain socket send an initial character
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.
164 The command-line options allow
166 to be used from scripts to inject or collect packets. They are as follows.
171 read a packet from the socket and write it to standard output.
176 read a packet from standard input and write it to the socket.
178 .\"--------------------------------------------------------------------------
183 program is intended as a tool for testing the
185 server. It is not expected to be useful in production environments. In
186 particular, it intentionally imposes no limits on queue lengths or
187 packet sizes, and its internals and interface (one packet per client
188 connection) are not well-suited for high performance.
192 turns out to be useful in other contexts then it might be improved.
193 Patches are, of course, welcome.
195 The initial ignoring of
197 bytes is unpleasant but necessary to cope with the
199 server, which sends this sequence in order to ensure that it's properly
200 synchronized with the SLIP interface.
202 .\"--------------------------------------------------------------------------
207 .\"--------------------------------------------------------------------------
210 Mark Wooding, <mdw@distorted.org.uk>
212 .\"----- That's all, folks --------------------------------------------------
~mdw / tripe / blob