chiark / gitweb /
README: Rewrite.
authorMark Wooding <mdw@distorted.org.uk>
Mon, 19 Apr 2010 21:00:59 +0000 (22:00 +0100)
committerMark Wooding <mdw@distorted.org.uk>
Mon, 19 Apr 2010 21:43:19 +0000 (22:43 +0100)
The old version was almost completely useless.  The new one is much more
informative, though maybe a little on the chatty side.

README

diff --git a/README b/README
index 1a9e12e..9d77a0e 100644 (file)
--- a/README
+++ b/README
-TRIPE
 
-Installation notes
+                       _____    ___ ____  _____
+                      |_   _| _|_ _|  _ \| ____|
+                        | || '__| || |_) |  _|
+                        | || |  | ||  __/| |___
+                        |_||_| |___|_|   |_____|
 
-       Standard GNU Autoconf fare.
+                         Trivial IP Encryption
 
-               ./configure
-               make
-               make install
 
-       I've now added a startup script, `tripe-init'.  The Makefile
-       doesn't install it anywhere, but if you want to use it in your
-       boot sequence:
+* Brief introduction
 
-         * If you use a SysV-like init, drop `tripe-init' in as
-           `/etc/init.d/tripe' (or wherever -- Tru64 users and similar
-           will want `/sbin/init.d/tripe'; RedHat users want
-           `/etc/rc.d/init.d/tripe' for some bizarre reason), and put
-           in symlinks to make it run, just after your networking
-           starts up.
+** What TrIPE does
 
-           On my Debian box, I used
+TrIPE is a fairly simple network protocol for securely transferring IP
+packets over hostile networks, using cryptography to ensure their
+secrecy and authenticity.  It is used to construct `virtual private
+networks', which securely connect geographically separated hosts and
+physical networks into a single virtual network.  The name stands for
+`Trivial IP Encryption'.
 
-             update-rc.d tripe defaults 15 85
+The tripe suite, of which this file is part, consists of a server which
+implements this protocol, together with a number of utilities, scripts
+and ancillary services which assist in configuring and maintaining the
+server.
 
-           to set up the links.
+** Supported operating systems
 
-         * If you use a BSD-like init, put `tripe-init' in /usr/sbin,
-           and run
+The main server ought to build on more or less any Unix-like operating
+system.  The author only has Linux readily to hand, so it doesn't get
+tested much on other systems, but porting should be easy.  The only
+nonportable aspect is the use of tunnel interfaces, though the server
+can fall back to using SLIP, which almost every Unix ought to be able to
+cope with.  There is code already for dealing with Linux's TUN/TAP
+driver, and *BSD's tunnels (and an obsolete tun-like device the author
+wrote for Linux a long time ago).  If other systems have similar
+devices, it should be easy to add support.
 
-             /usr/sbin/tripe-init start
+A Windows port is a more daunting prospect.  The author is currently
+considering a lash-up port using Cygwin and the OpenVPN Win32-tun
+driver, but hasn't started work.
 
-           from the init script at some appropriate time.
+Other parts of the system are a bit more Linux specific.  For example,
+the interface configuration script `tripe-ifup' exists only in a
+Linux-specific version.  (Writing a new version for some other system is
+very straightforward, though.)  The `pathmtu' utility is more
+problematic: I don't know how to do this well for *BSD, for example.
+Contributions are welcome!
 
-       Automake is a bit crap and won't have set the execute bit on
-       `tripe-init', so you'll need to do that.  Sorry.
+** Licence
 
-       Also, it's a good idea to copy `tripe.conf' into
-       `/etc/tripe.conf'.  Then fill in the options that you want.
+The TrIPE suite is free software.  You may modify and/or redistribute
+it, under the terms of the GNU General Public License, either version 2
+or, at your option, any later version.  There should be a copy of this
+licence included in the source distribution.  Pre-built binary packages,
+e.g., for Debian GNU/Linux, may not include it, on the assumption that
+Debian already has a copy in /usr/share/common-licenses/GPL-2.
 
-       Finally, populate the directory `/var/lib/tripe/peers' with
-       scripts to set up peers.  This kind of thing is all that's
-       needed:
+There are no restrictions on the use of the network protocol.
 
-               #! /bin/sh
+** Finding out more
 
-               set -e
-               tripectl add PEER PEER-ADDR 4070
-               ifname=`tripectl ifname PEER`
-               ifconfig $ifname LOCAL pointopoint REMOTE mtu 1429
-               route add -net RNET netmask RMASK gw REMOTE
+There is fairly extensive documentation on the various components of the
+TrIPE suite.  The tripe.7 manpage aims to provide an overview of the
+system, so it may be a good place to start reading.
+
+* Building the tripe suite from a source distribution
+
+** Prerequisites
+
+In order to compile the tripe suite, you must have a number of other
+packages already installed.
+
+       Package name            Version         Needed for
+
+       mLib                    2.5.0           S K V M +
+       Catacomb                2.1.0           S K
+       Python                  2.4               K V M
+       mLib-Python             1.0.0               V M
+       Catacomb-Python         1.0.0             K
+       PyGTK                   2.12.0                M
+       python-cdb              0.32                V
+
+Key:
+       S: server (you really need this)
+       K: key management utility
+       V: peer connection services
+       M: graphical monitor
+       +: various other utilities
+
+The mLib and Catacomb libraries, and their Python bindings, are probably
+available from the same place you found this.
+
+** Building and installing
+
+The source distribution should contain a `configure' script.  In theory,
+it should be sufficient to run
+
+       $ ./configure
+       $ make
+       $ make check
+       $ sudo make install
+
+(or use your preferred means of attaining superuser privileges).  If you
+don't want to clutter the source tree with object files, change to a
+clean directory and run
+
+         $ SRCDIR/.configure
+         $ make
+
+etc., where SRCDIR is where you put the sources.
+
+The configure script should make sensible choices about the tunnel
+devices available on your system.  If it doesn't, you can force its hand
+by saying something like
+
+       $ ./configure --with-tunnel="linux slip"
+
+There are also configure-time options for choosing default directories
+and filenames (e.g., where to find configuration files, where to write
+logs).  These can all be overridden using command line options if
+necessary.
+
+For full details about the configure-time options, run
+
+       $ ./configure --help
+
+A script to start and stop the server is generated as part of the build,
+as init/tripe-init.  If you have a System V-style init, you can drop
+this script into /etc/init.d (or your equivalent), and link it into the
+relevant /etc/rc.d directories.
+
+** Building from Git
+
+This section is mainly relevant to those who wish to participate in
+TrIPE development.  If you just want to use the tripe suite, you're
+probably best off using a source distribution tarball.
+
+The author maintains the tripe sources using Git.  The files checked
+into Git omit many files provided in distribution tarballs, because
+they're really maintained in separate projects.  The first thing you
+need to do, then, is reconstruct these files.  You need the following:
+
+       cfd 1.3.4
+       Autoconf 2.61
+       Automake 1.8
+       Autoconf-archive 2007-05-12
+
+Make sure that the `aclocal' program can find the macros in the Autoconf
+archive.  Then run
+
+       $ mdw-setup
+
+This ought, magically, to construct the `configure' script and all the
+Makefile.in files.  You should now be able to build the system as if you
+had sources.
+
+The only thing which will still be missing is the `RELEASE' file, which
+just contains the package version number.  Instead, tripe's build system
+will work this out by looking at your Git repository.
+
+* Contacting the author
+
+If you need want to complain about bugs, build problems, or missing
+features, or suggest improvements, or ask about how things work, send
+email to
+
+      Mark Wooding <mdw@distorted.org.uk>
+
+Currently there is no mailing list for discussion of TrIPE development.
+If there seems to be sufficient interest, I'll set one up.
+
+\f
+Local variables:
+mode: outline
+fill-column: 72
+End: