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