Upgrade licence to GPLv3+.

[tripe] / uslip / tripe-uslip.1.in

.\" -*-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 3 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, see <https://www.gnu.org/licenses/>.
.
.\"--------------------------------------------------------------------------
.so ../common/defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH tripe-uslip 1tripe "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 [ \-fgps ]
.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.
.TP
.B \-f, \-\-flood
Connect to
.IR socket ,
and send packets as fast as possible.  The packets sent aren't very
interesting, and there's no way to configure their contents.
.TP
.B \-s, \-\-sink
Connect to
.IR socket
and read packets as the become available.  The packets are discarded,
though if stdout is a terminal, a simple spinning-baton animation is
updated once for each group of packets.  If you are flooding one end of
a TrIPE connection, it's advisable to attach a sink to the other:
otherwise the destination
.B tripe-uslip
will attempt to consume all available memory, storing incoming packets
until someone retrieves them.
.
.\"--------------------------------------------------------------------------
.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.  That said, the
flood option has worked well enough to expose bugs in
.BR tripe 's
behaviour under heavy loads.
.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 --------------------------------------------------