/*
- * 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
~ian / userv-utils.git / blobdiff