client/tripectl: Flush output after each line.

[tripe] / doc / tripe.8

diff --git a/doc/tripe.8 b/doc/tripe.8
index bcfdcbb4a94829c059ecdefe7b2db03e38b9bf12..f5fe5bf6dc5f0e4ecd06294762898a670b25ce1b 100644 (file)
--- a/doc/tripe.8
+++ b/doc/tripe.8
@@ -41,6 +41,8 @@ tripe \- a simple VPN daemon
 .IR addr ]
 .RB [ \-p
 .IR port ]
 .IR addr ]
 .RB [ \-p
 .IR port ]

+.RB [ \-n
+.IR tunnel ]

 .br
        
 .RB [ \-U
 .br
        
 .RB [ \-U


@@ -148,9 +150,9 @@ version number to standard output and exits with status 0.
 .B "\-u, \-\-usage"
 Writes a brief usage summary to standard output and exits with status 0.
 .TP
 .B "\-u, \-\-usage"
 Writes a brief usage summary to standard output and exits with status 0.
 .TP

-.B "\-\-tunnel"
-Writes a string to standard output describing the configured tunnelling
-method and exits with status 0.  This is intended for the use of the
+.B "\-\-tunnels"
+Writes to standard output a list of the configured tunnel drivers, one
+per line, and exits with status 0.  This is intended for the use of the

 start-up script, so that it can check that it will actually work.
 .TP
 .B "\-D, \-\-daemon"
 start-up script, so that it can check that it will actually work.
 .TP
 .B "\-D, \-\-daemon"


@@ -185,6 +187,9 @@ to tunnel through the VPN.
 Use the specified UDP port for all communications with peers, rather
 than an arbitarary kernel-assigned port.
 .TP
 Use the specified UDP port for all communications with peers, rather
 than an arbitarary kernel-assigned port.
 .TP

+.BI "\-n, \-\-tunnel=" tunnel
+Use the specified tunnel driver for new peers by default.
+.TP

 .BI "\-U, \-\-setuid=" user
 Set uid to that of
 .I user
 .BI "\-U, \-\-setuid=" user
 Set uid to that of
 .I user


@@ -259,19 +264,6 @@ gateway machine,
 has the addresses 10.0.1.1 and 200.0.1.1; site B's gateway is
 .B bob
 and has addresses 10.0.2.1 and 200.0.2.1.
 has the addresses 10.0.1.1 and 200.0.1.1; site B's gateway is
 .B bob
 and has addresses 10.0.2.1 and 200.0.2.1.

-.PP
-This isn't quite complicated enough.  Each of
-.B alice
-and
-.B bob
-needs an extra IP address which we'll use when setting up the
-point-to-point link.  These addresses need to be routable, at least
-within the virtual private network: unfortunately, you can't just use
-the same pair everywhere.  We'll assign
-.B alice
-the point-to-point address 192.168.0.1, and
-.B bob
-the address 192.168.0.2.

 .hP 1.
 Install
 .B tripe
 .hP 1.
 Install
 .B tripe


@@ -365,19 +357,18 @@ Start the
 servers up.  Run
 .RS
 .VS
 servers up.  Run
 .RS
 .VS

-tripectl \-slD \-S\-P23169
+tripectl \-slD \-S\-p22003

 .VE
 on each of
 .B alice
 and
 .BR bob .
 (The
 .VE
 on each of
 .B alice
 and
 .BR bob .
 (The

-.RB ` \-P23169 '
-forces the server to use UDP port 23169: use some other number if 23169
-is inappropriate for your requirements.  I chose it by reducing the
-RIPEMD160 hash of
-.RB ` tripe\-port\-number\e0 '
-modulo 2\*(ss16\*(se.)
+.RB ` \-p22003 '
+forces the server to use UDP port 22003: use some other number if 22003
+is inappropriate for your requirements.  I chose it by taking the first
+16 bits of the RIPEMD160 hash of
+.RB ` TrIPE '.

 .RE
 .hP 6.
 To get
 .RE
 .hP 6.
 To get


@@ -389,14 +380,12 @@ run this shell script (or one like it):
 .VS
 #! /bin/sh
 
 .VS
 #! /bin/sh
 

-tripectl add bob 200.0.2.1 23169
+tripectl add bob 200.0.2.1 22003

 ifname=`tripectl ifname bob`
 ifname=`tripectl ifname bob`

-ifconfig $ifname \e
-       192.168.0.1 \e
-       pointopoint 192.168.0.2
+ifconfig $ifname 10.0.1.1 pointopoint 10.0.2.1

 route add -net \e
        10.0.2.0 netmask 255.255.255.0 \e
 route add -net \e
        10.0.2.0 netmask 255.255.255.0 \e

-       gw 192.168.0.2
+       gw 10.0.2.1

 .VE
 Read
 .BR ifconfig (8)
 .VE
 Read
 .BR ifconfig (8)


@@ -482,29 +471,59 @@ Though not for the faint of heart, it is possible to get
 .B tripe
 to read and write network packets to a pair of file descriptors using
 SLIP encapsulation.  No fancy header compression of any kind is
 .B tripe
 to read and write network packets to a pair of file descriptors using
 SLIP encapsulation.  No fancy header compression of any kind is

-supported.  The intended use is that you allocate a pty pair, set the
-slave's line discipline to SLIP, and hand the
+supported.
+.PP
+Two usage modes are supported: a preallocation system, whereby SLIP
+interfaces are created and passed to the
+.B tripe
+server at startup; and a dynamic system, where the server runs a script
+to allocate a new SLIP interface when it needs one.  It is possible to
+use a mixture of these two modes, starting

 .B tripe
 .B tripe

-server the master end, though in fact any old file descriptors will do.
+with a few preallocated interfaces and having it allocate more
+dynamically as it needs them.
+.PP
+The behaviour of
+.BR tripe 's
+SLIP driver is controlled by the
+.B TRIPE_SLIPIF
+environment variable.  The server will not create SLIP tunnels if this
+variable is not defined.  The variable's value is a colon-delimited list
+of preallocated interfaces, followed optionally by the filename of a
+script to run to dynamically allocate more interfaces.

 .PP
 .PP

-The SLIP descriptors must be set up and running before the daemon is
-started, and you must inform it about the SLIP descriptors it's meant to
-use in an environment variable
-.BR TRIPE_SLIPIF ,
-whose value must be a colon-separated list of items of the form
+A static allocation entry has the form

 .IR infd [ \c
 .BI , outfd \c
 .RB ] \c
 .BI = \c
 .IR infd [ \c
 .BI , outfd \c
 .RB ] \c
 .BI = \c

-.IR ifname .
+.IR ifname ,

 If the
 .I outfd
 is omitted, the same file descriptor is used for input and output.
 .PP
 If the
 .I outfd
 is omitted, the same file descriptor is used for input and output.
 .PP

+The dynamic allocation script must be named by an absolute or relative
+pathname, beginning with 
+.RB ` / '
+or
+.RB ` . '.
+The server will pass the script an argument, which is the name of the
+peer for which the interface is being created.  The script should
+allocate a new SLIP interface (presumably by creating a pty pair),
+configure it appropriately, and write the interface's name to its
+standard output, followed by a newline.  It should then read and write
+SLIP packets on its stdin and stdout.  The script's stdin will be closed
+when the interface is no longer needed, and the server will attempt to
+send it a
+.B SIGTERM
+signal (though this may fail if the script runs with higher privileges
+than the server).
+.PP

 The output file descriptor should not block unless it really needs to:
 the
 .B tripe
 The output file descriptor should not block unless it really needs to:
 the
 .B tripe

-daemon assumes that it won't, and will get wait for it to accept output.
+daemon assumes that it won't, and will get wedged waiting for it to
+accept output.

 .SS "About the name"
 The program's name is
 .BR tripe ,
 .SS "About the name"
 The program's name is
 .BR tripe ,


@@ -523,4 +542,4 @@ find one, please inform the author
 .IR "The Trivial IP Encryption Protocol" ,
 .IR "The Wrestlers Protocol" .
 .SH "AUTHOR"
 .IR "The Trivial IP Encryption Protocol" ,
 .IR "The Wrestlers Protocol" .
 .SH "AUTHOR"

-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>