--- /dev/null
+.\" -*-nroff-*-
+.\"
+.\" Documentation for uslip
+.\"
+.\" (c) 2008 Straylight/Edgeware.
+.\"
+
+.\"----- Licensing notice ---------------------------------------------------
+.\"
+.\" This file is part of Trivial IP Encryption (TrIPE).
+.\"
+.\" TrIPE is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 2 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" TrIPE is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with TrIPE; if not, write to the Free Software Foundation,
+.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+.
+.\"--------------------------------------------------------------------------
+.so ../defs.man.in \" @@@PRE@@@
+.
+.\"--------------------------------------------------------------------------
+.TH tripe-uslip 1 "7 April 2008" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
+.
+.\"--------------------------------------------------------------------------
+.SH "NAME"
+.
+tripe-uslip \- fake SLIP interface for testing tripe
+.
+.\"--------------------------------------------------------------------------
+.SH "SYNOPSIS"
+.
+.B tripe-uslip
+.RB [ \-gp ]
+.I socket
+.
+.\"--------------------------------------------------------------------------
+.SH "DESCRIPTION"
+.
+The
+.B tripe-uslip
+provides a mechanism for pushing packets of data into a
+.BR tripe (8)
+server, and extracting them. This is useful for testing the server; it
+isn't useful in a production environment.
+.SS "Overview and theory of operation"
+Testing the
+.BR tripe (8)
+server is difficult: configuring network interfaces and creating tunnels
+requires root privileges (undesirable for a program under development!)
+and testing that it successfully transports network packets needs two
+separate instances running on separate machines. (If both ends of a
+tunnel are on the same host then the packets won't actually go over the
+tunnel: the kernel will just loop them back internally.)
+.PP
+The
+.B tripe-uslip
+program implements the interface required of a dynamic allocation script
+(see the
+.BR tripe (8)
+manual for details). However, it doesn't actually make a network
+interface.
+.PP
+You use it by setting
+.IP
+.BI TRIPE_SLIPIF= dir /tripe-uslip
+.PP
+in the environment passed to the
+.BR tripe (8)
+server (and, typically, passing it the
+.B \-tslip
+command-line option). When you add a new peer with the
+.B ADD
+.I peer
+.IR address ...
+administration command, the server runs
+.IB dir /tripe-uslip
+.IR peer ,
+which in turn creates a Unix-domain socket called
+.I peer
+in the server's current directory. If you run
+.IP
+.B tripe-uslip
+.B \-p
+.I peer
+.BI < file
+.PP
+in this directory, then the contents of
+.I file
+are sent to
+.B tripe
+as if they were a network packet to be encrypted and transmitted over
+its tunnel. (Any method of providing the data on standard input is
+acceptable: it doesn't have to be a regular file. In particular, pipes
+are fine. Note also that
+.B tripe
+doesn't actually care that the data it receives is actually network
+packets: it can be absolutely anything you like.)
+.PP
+If you run
+.IP
+.B tripe-uslip
+.B \-g
+.I peer
+.BI > file
+.PP
+then the contents of the next network packet the server decrypts will be
+written to the
+.IR file .
+(Again, you can use pipes or whatever.)
+.PP
+The
+.B tripe-uslip
+program is fully nonblocking. This means that you won't deadlock the
+server by attaching duff scripts to it via
+.BR tripe-uslip .
+.SS "Technical details"
+Without options,
+.B tripe-uslip
+performs the following actions.
+.hP \*o
+It creates a Unix-domain socket with name
+.I socket
+(which will typically be the name of the peer that
+.BR tripe (8)
+created this interface for).
+.hP \*o
+It writes the string
+.BI tripe-uslip- socket
+to its standard output, followed by a newline.
+.hP \*o
+It reads and discards up to two bytes with value 192 (SLIP
+.BR END )
+on stdin.
+.hP \*o
+It enters its main loop, during which it accepts and processes client
+connections, and reads and writes SLIP-encoded packets on standard input
+and output. Unless a fatal error occurs, the main loop continues until
+it (a) has no connected clients, (b) has no packets queued for output to
+clients or to standard output, and (c) has seen end-of-file on its
+standard input.
+.PP
+The main loop works as follows. When a SLIP-encoded packet arrives on
+standard input, it is decoded and placed on a queue waiting to be read
+from a client. If a client connects and writes a packet, the packet is
+SLIP-encoded and written to standard output.
+.PP
+Clients connecting to the
+Unix-domain socket send an initial character
+.RB ` < '
+to read a packet or
+.RB ` > '
+to write. Packets, as far as clients are concerned, consist of
+uninterpreted strings of octets and continue until end-of-file. It is
+not possible to read or write more than one packet in a single connection.
+.PP
+The command-line options allow
+.B tripe-uslip
+to be used from scripts to inject or collect packets. They are as follows.
+.TP
+.B \-g, \-\-get
+Connect to
+.IR socket ,
+read a packet from the socket and write it to standard output.
+.TP
+.B \-p, \-\-put
+Connect to
+.IR socket ,
+read a packet from standard input and write it to the socket.
+.
+.\"--------------------------------------------------------------------------
+.SH "BUGS"
+.
+The
+.B tripe-uslip
+program is intended as a tool for testing the
+.BR tripe (8)
+server. It is not expected to be useful in production environments. In
+particular, it intentionally imposes no limits on queue lengths or
+packet sizes, and its internals and interface (one packet per client
+connection) are not well-suited for high performance.
+.PP
+If
+.B tripe-uslip
+turns out to be useful in other contexts then it might be improved.
+Patches are, of course, welcome.
+.PP
+The initial ignoring of
+.B END
+bytes is unpleasant but necessary to cope with the
+.BR tripe (8)
+server, which sends this sequence in order to ensure that it's properly
+synchronized with the SLIP interface.
+.
+.\"--------------------------------------------------------------------------
+.SH "SEE ALSO"
+.
+.BR tripe (8).
+.
+.\"--------------------------------------------------------------------------
+.SH "AUTHOR"
+.
+Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
~mdw / tripe / blobdiff