@@ -1,8 +1,11 @@

 userv-utils (0.2.0) unstable; urgency=low

-  * ipif/INSTALL instructions &c improved, slattach patch included.
+  Improvements to ipif (tunnelling/VPN facility):
+  * INSTALL instructions much improved and README created.
+  * Patch to slattach included.
+  * Documentation comments improved.

- --
+ -- Ian Jackson <ian@davenant.greenend.org.uk>  Mon, 18 Sep 2000 01:31:01 +0100

 userv-utils (0.1.90) unstable; urgency=low

1 files changed, 77 insertions, 27 deletions

diff --git a/ipif/service.c b/ipif/service.c
index 97351e6..397740c 100644
--- a/ipif/service.c
+++ b/ipif/service.c
@@ -1,37 +1,87 @@
 /*
- * userv service (or standalone program)
- * for per-user IP subranges.
+ * userv service (or standalone program) for per-user IP subranges.
+ *
+ * When invoked appropriately, it creates a point-to-point network
+ * interface with specified parameters.  It arranges for packets sent out
+ * via that interface by the kernel to appear on its own stdout in SLIP or
+ * CSLIP encoding, and packets injected into its own stdin to be given to
+ * the kernel as if received on that interface.  Optionally, additional
+ * routes can be set up to arrange for traffic for other address ranges to
+ * be routed through the new interface.
+ *
+ * This is the service program, which is invoked as root from userv (or may
+ * be invoked firectly).
+ *
+ * Its arguments are supposed to be, in order, as follows:
+ *
+ *  The first two arguments are usually supplied by the userv
+ *  configuration.  See the file `ipif/ipif' in the source tree, which
+ *  is installed in /etc/userv/services.d/ipif by `make install':
  *
- * This is invoked as root, directly from userv.
- * Its arguments are supposed to be, in order:
  *  <config>
- *      Specifies address ranges and gids which own them.
- *  --  Indicates that the remaining arguments are user-supplied
- *      and therefore untrusted.
+ *
+ *      Specifies address ranges and gids which own them.  The default
+ *      configuration supplies /etc/userv/ipif-networks, which is then read
+ *      for a list of entries, one per line.
+ *
+ *  --
+ *      Serves to separate the user-supplied and therefore untrusted
+ *      arguments from the trusted first argument.
+ *
+ *  The remaining arguments are supplied by the (untrusted) caller:
+ *
  *  <local-addr>,<peer-addr>,<mtu>,<proto>
+ *
  *      As for slattach.  Supported protocols are slip, cslip, and
- *      adaptive.  Alternatively, set to `debug' to print debugging
- *      info.  <local-addr> is address of the interface on the local
- *      system; <peer-addr> is the address of the point-to-point peer.
+ *      adaptive.  Alternatively, set to `debug' to print debugging info
+ *      and exit.  <local-addr> is address of the interface to be created
+ *      on the local system; <peer-addr> is the address of the
+ *      point-to-point peer.  They must be actual addresses (not
+ *      hostnames).
+ *
  *  <prefix>/<mask>,<prefix>/<mask>,...
- *      List of additional routes to add for this interface.
- *      May be the empty argument, or `-' if this is problematic.
  *
- * <config> is either
- *    <gid>,[=]<prefix>/<len>[,<junk>]
- *      indicating that that gid may allocate addresses in
- *      the relevant subspace (<junk> is ignored)
- *      if `=' is specified then it's only allowed for the local
- *      endpoint address
- * or #...
- *      which is a comment
- * or /<config-file-name> or ./<config-file-name> or ../<config-file-name>
- *      which refers to a file which contains lines which
- *      are each <config>
- * or *
- *      which means that anything is permitted
- * 
- * Should be run from userv with no-disconnect-hup.
+ *      List of additional routes to add for this interface.  routes will
+ *      be set up on the local system arranging for packets for those
+ *      networks to be sent via the created interface.  <prefix> must be an
+ *      IPv4 address, and mask must be an integer (dotted-quad masks are
+ *      not supported).  If no additional routes are to be set up, use `-'
+ *      or supply an empty argument.
+ *
+ * Each <config> item - whether a line file such as
+ * /etc/userv/ipif-networks, or supplied on the service program
+ * command line - is one of:
+ *
+ *   /<config-file-name>
+ *   ./<config-file-name>
+ *   ../<config-file-name>
+ *
+ *      Reads a file which contains lines which are each <config>
+ *      items.
+ *
+ *   <gid>,[=]<prefix>/<len>[,<junk>]
+ *
+ *      Indicates that <gid> may allocate addresses in the relevant address
+ *      range (<junk> is ignored).  <gid> must be numeric.  To specify a
+ *      single host address, you must specify a mask of /32.  If `=' is
+ *      specified then the specific subrange is only allowed for the local
+ *      endpoint address, but not for remote addresses.
+ *
+ *   *
+ *      Means that anything is to be permitted.  This should not appear in
+ *      /etc/userv/ipif-networks, as that would permit any user on the
+ *      system to create any interfaces with any addresses and routes
+ *      attached.  It is provided so that root can usefully invoke the ipif
+ *      service program directly (not via userv), without needing to set up
+ *      permissions in /etc/userv/ipif-networks.
+ *
+ *   #...
+ *
+ *      Comment.  Blank lines are also ignored.
+ *
+ *   NB: Permission is granted if _any_ config entry matches the request.
+ *
+ * The service program should be run from userv with no-disconnect-hup.
  */
 /*
  * Copyright (C) 1999-2000 Ian Jackson