X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=secnet.git;a=blobdiff_plain;f=README;h=414baee6caccaeb680e83617c455f176015660e6;hp=4d6f4e54e2ca54e930f75f569a84c76a077ea83c;hb=423936d35d7671fd017d2d611d418d1b8eeb6195;hpb=83dbdd3f25ac7edca6365ca7a299e4b8eee6b83e

diff --git a/README b/README
index 4d6f4e5..414baee 100644
--- a/README
+++ b/README
@@ -194,10 +194,83 @@ Defines:
   udp (closure => comm closure)
 
 udp: dict argument
-  address (string list): IPv6 or IPv4 addresses to listen and send on
+  address (string list): IPv6 or IPv4 addresses to listen and send on;
+   default is all local addresses
+  port (integer): UDP port to listen and send on; optional if you
+   don't need to have a stable address for your peers to talk to
+   (in which case your site ought probably to have `local-mobile true').
+  buffer (buffer closure): buffer for incoming packets
+  authbind (string): optional, path to authbind-helper program
+
+** polypath
+
+Defines:
+  polypath (closure => comm closure)
+
+polypath: dict argument
   port (integer): UDP port to listen and send on
   buffer (buffer closure): buffer for incoming packets
   authbind (string): optional, path to authbind-helper program
+  max-interfaces (number): optional, max number of different interfaces to
+   use (also, maximum steady-state amount of packet multiplication)
+  interfaces (string list): which interfaces to process; each entry is
+   optionally `!' or `+' followed by a glob pattern (which is applied to a
+   prospective interface using fnmatch with no flags).  If no list is
+   specified, or the list ends with a `!' entry, a default list is
+   used/appended: "!tun*","!tap*","!sl*","!userv*","!lo","*".  Patterns
+   which do not start with `*' or an alphanumeric need to be preceded
+   by `!' or `+'.
+  monitor-command (string list): Program to use to monitor appearance
+   and disappearance of addresses on local network interfaces.  Should
+   produce lines of the form `+|-<ifname> 4|6 <addr>' where <addr> is
+   an address literal.  Each - line should relate to a previously
+   printed + line.  On startup, should produce a + line for each
+   currently existing address.  secnet does filtering so there is no
+   need to strip out tun interfaces, multicast addresses, and so on.
+   The command is run as the user secnet is started as (not the one
+   which secnet may drop privilege to due to the configured `userid').
+   The default depends on the operating system.
+  permit-loopback (boolean): Normally, loopback IPv6 and IPv4
+   addresses on local interfaces are disregarded, because such
+   interfaces are not interesting for communicating with distant
+   hosts.  Setting this option will ignore that check, which can be
+   useful for testing.  Setting this option also removes "!lo*" from
+   the default interface pattern list.
+
+When using this comm, packets are sent out of every active interface
+on the host (where possible).  It is important that interfaces created
+by secnet itself are not included!  secnet's default filter list tries
+to do this.
+
+This comm only makes sense for sites which are mobile.  That is, the
+site closures used with this comm should all have the `local-mobile'
+parameter set to `true'.  When the local site site is not marked
+mobile the address selection machinery might fixate on an unsuitable
+address.
+
+For an interface to work with polypath, it must either have a suitable
+default route, or be a point-to-point interface.  In the general case
+this might mean that the host would have to have multiple default
+routes.  However in practice the most useful configuration is two
+interfaces being (1) wifi (2) mobile internet.
+
+I have had success on Linux by using network-manager for wifi and
+invoking ppp directly for mobile internet.  ppp sets up a
+point-to-point link, and does not add a default route if there already
+is one.  network-manager always sets up a default route.  The result
+is that the wifi always has a default route (so is useable); ppp
+(being a point-to-point link) does not need one.
+
+The use of polypath requires that secnet be started with root
+privilege, to make the setsockopt(,,SO_BINDTODEVICE,) calls.  If the
+configuration specifies that secnet should drop privilege (see
+`userid' above), secnet will keep a special process around for this
+purpose; that process will handle local network interface changes but
+does not deal with any packets, key exchange, etc.
+
+polypath support is only available when secnet is built against an
+IPv6-capable version of adns (because it wants features in the newer
+adns).
 
 ** log