chiark - git - mdw - tripe/blob - uslip/tripe-uslip.1.in

   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 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.
  16 .\"
  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
  20 .\" for more details.
  21 .\"
  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/>.
  24 .
  25 .\"--------------------------------------------------------------------------
  26 .so ../common/defs.man \" @@@PRE@@@
  27 .
  28 .\"--------------------------------------------------------------------------
  29 .TH tripe-uslip 1tripe "7 April 2008" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
  30 .
  31 .\"--------------------------------------------------------------------------
  32 .SH "NAME"
  33 .
  34 tripe-uslip \- fake SLIP interface for testing tripe
  35 .
  36 .\"--------------------------------------------------------------------------
  37 .SH "SYNOPSIS"
  38 .
  39 .B tripe-uslip
  40 .RB [ \-fgps ]
  41 .I socket
  42 .
  43 .\"--------------------------------------------------------------------------
  44 .SH "DESCRIPTION"
  45 .
  46 The
  47 .B tripe-uslip
  48 provides a mechanism for pushing packets of data into a
  49 .BR tripe (8)
  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"
  53 Testing the
  54 .BR tripe (8)
  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.)
  61 .PP
  62 The
  63 .B tripe-uslip
  64 program implements the interface required of a dynamic allocation script
  65 (see the
  66 .BR tripe (8)
  67 manual for details).  However, it doesn't actually make a network
  68 interface.
  69 .PP
  70 You use it by setting
  71 .IP
  72 .BI TRIPE_SLIPIF= dir /tripe-uslip
  73 .PP
  74 in the environment passed to the
  75 .BR tripe (8)
  76 server (and, typically, passing it the
  77 .B \-tslip
  78 command-line option).  When you add a new peer with the
  79 .B ADD
  80 .I peer
  81 .IR address ...
  82 administration command, the server runs
  83 .IB dir /tripe-uslip
  84 .IR peer ,
  85 which in turn creates a Unix-domain socket called
  86 .I peer
  87 in the server's current directory.  If you run
  88 .IP
  89 .B tripe-uslip
  90 .B \-p
  91 .I peer
  92 .BI < file
  93 .PP
  94 in this directory, then the contents of
  95 .I file
  96 are sent to
  97 .B tripe
  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
 102 .B tripe
 103 doesn't actually care that the data it receives is actually network
 104 packets: it can be absolutely anything you like.)
 105 .PP
 106 If you run
 107 .IP
 108 .B tripe-uslip
 109 .B \-g
 110 .I peer
 111 .BI > file
 112 .PP
 113 then the contents of the next network packet the server decrypts will be
 114 written to the
 115 .IR file .
 116 (Again, you can use pipes or whatever.)
 117 .PP
 118 The
 119 .B tripe-uslip
 120 program is fully nonblocking.  This means that you won't deadlock the
 121 server by attaching duff scripts to it via
 122 .BR tripe-uslip .
 123 .SS "Technical details"
 124 Without options,
 125 .B tripe-uslip
 126 performs the following actions.
 127 .hP \*o
 128 It creates a Unix-domain socket with name
 129 .I socket
 130 (which will typically be the name of the peer that
 131 .BR tripe (8)
 132 created this interface for).
 133 .hP \*o
 134 It writes the string
 135 .BI tripe-uslip- socket
 136 to its standard output, followed by a newline.
 137 .hP \*o
 138 It reads and discards up to two bytes with value 192 (SLIP
 139 .BR END )
 140 on stdin.
 141 .hP \*o
 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
 147 standard input.
 148 .PP
 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.
 153 .PP
 154 Clients connecting to the
 155 Unix-domain socket send an initial character
 156 .RB ` < '
 157 to read a packet or
 158 .RB ` > '
 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.
 162 .PP
 163 The command-line options allow
 164 .B tripe-uslip
 165 to be used from scripts to inject or collect packets.  They are as follows.
 166 .TP
 167 .B \-g, \-\-get
 168 Connect to
 169 .IR socket ,
 170 read a packet from the socket and write it to standard output.
 171 .TP
 172 .B \-p, \-\-put
 173 Connect to
 174 .IR socket ,
 175 read a packet from standard input and write it to the socket.
 176 .TP
 177 .B \-f, \-\-flood
 178 Connect to
 179 .IR 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.
 182 .TP
 183 .B \-s, \-\-sink
 184 Connect to
 185 .IR socket
 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
 191 .B tripe-uslip
 192 will attempt to consume all available memory, storing incoming packets
 193 until someone retrieves them.
 194 .
 195 .\"--------------------------------------------------------------------------
 196 .SH "BUGS"
 197 .
 198 The
 199 .B tripe-uslip
 200 program is intended as a tool for testing the
 201 .BR tripe (8)
 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
 207 .BR tripe 's
 208 behaviour under heavy loads.
 209 .PP
 210 If
 211 .B tripe-uslip
 212 turns out to be useful in other contexts then it might be improved.
 213 Patches are, of course, welcome.
 214 .PP
 215 The initial ignoring of
 216 .B END
 217 bytes is unpleasant but necessary to cope with the
 218 .BR tripe (8)
 219 server, which sends this sequence in order to ensure that it's properly
 220 synchronized with the SLIP interface.
 221 .
 222 .\"--------------------------------------------------------------------------
 223 .SH "SEE ALSO"
 224 .
 225 .BR tripe (8).
 226 .
 227 .\"--------------------------------------------------------------------------
 228 .SH "AUTHOR"
 229 .
 230 Mark Wooding, <mdw@distorted.org.uk>
 231 .
 232 .\"----- That's all, folks --------------------------------------------------