X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/tripe/blobdiff_plain/b9066fbb5c1c160eb305a33a3335b77d17e0f502..819018a97971abf10d03cb85ed13536475af2dd0:/doc/tripe.8 diff --git a/doc/tripe.8 b/doc/tripe.8 index bcfdcbb4..f5fe5bf6 100644 --- a/doc/tripe.8 +++ b/doc/tripe.8 @@ -41,6 +41,8 @@ tripe \- a simple VPN daemon .IR addr ] .RB [ \-p .IR port ] +.RB [ \-n +.IR tunnel ] .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 "\-\-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" @@ -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 +.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 @@ -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. -.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 @@ -365,19 +357,18 @@ Start the servers up. Run .RS .VS -tripectl \-slD \-S\-P23169 +tripectl \-slD \-S\-p22003 .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 @@ -389,14 +380,12 @@ run this shell script (or one like it): .VS #! /bin/sh -tripectl add bob 200.0.2.1 23169 +tripectl add bob 200.0.2.1 22003 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 - gw 192.168.0.2 + gw 10.0.2.1 .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 -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 -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 -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 ifname . +.IR ifname , 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 -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 , @@ -523,4 +542,4 @@ find one, please inform the author .IR "The Trivial IP Encryption Protocol" , .IR "The Wrestlers Protocol" . .SH "AUTHOR" -Mark Wooding, +Mark Wooding,