string_item_to_iaddr: Actually set port if !CONFIG_IPV6

[secnet.git] / README

diff --git a/README b/README
index 79b5447a6726ff5b6e8c7ed53a7e42a89b2e4405..414baee6caccaeb680e83617c455f176015660e6 100644 (file)
--- a/README
+++ b/README
@@ -1,5 +1,15 @@
 secnet - flexible VPN software
 
 secnet - flexible VPN software
 

+* Copying
+
+secnet is Copyright (C) 1995--2003 Stephen Early <steve@greenend.org.uk>
+It is distributed under the terms of the GNU General Public License,
+version 2 or later.  See the file COPYING for more information.
+
+The IP address handling library in ipaddr.py is Copyright (C)
+1996--2000 Cendio Systems AB, and is distributed under the terms of
+the GPL.
+

 * Introduction
 
 secnet allows large virtual private networks to be constructed
 * Introduction
 
 secnet allows large virtual private networks to be constructed


@@ -19,6 +29,20 @@ providing complete links between multiple sites to a simple
 laptop-to-host link), read the section in this file on 'Creating a
 VPN'.
 
 laptop-to-host link), read the section in this file on 'Creating a
 VPN'.
 

+* Mailing lists and bug reporting
+
+There are two mailing lists associated with secnet: an 'announce' list
+and a 'discuss' list.  Their addresses are:
+http://www.chiark.greenend.org.uk/mailman/listinfo/secnet-announce
+http://www.chiark.greenend.org.uk/mailman/listinfo/secnet-discuss
+
+The -announce list receives one message per secnet release.  The
+-discuss list is for general discussion, including help with
+configuration, bug reports, feature requests, etc.
+
+Bug reports should be sent to <steve@greenend.org.uk>; they will be
+forwarded to the -discuss list by me.
+

 * Creating a VPN
 
 XXX TODO
 * Creating a VPN
 
 XXX TODO


@@ -92,12 +116,6 @@ f is a dictionary:
 
 Note that f/g/e is NOT 4.
 
 
 Note that f/g/e is NOT 4.
 

-In a future version of secnet it will also be permissible to list
-other dictionaries before a dictionary definition,
-eg. <defaults,otherdefaults>{definitions}.  These will be searched in
-order for keys, before the lexical parent.  (This is not yet
-implemented)
-

 Elements that are lists are inserted into lists in definitions, not
 referenced by them (i.e. you can't have lists of lists).
 
 Elements that are lists are inserted into lists in definitions, not
 referenced by them (i.e. you can't have lists of lists).
 


@@ -111,11 +129,14 @@ closure { definitions } is short for closure({definitions}).
 The main body of secnet, and all the additional modules, predefine
 some keys in the root dictionary.  The main ones are:
 
 The main body of secnet, and all the additional modules, predefine
 some keys in the root dictionary.  The main ones are:
 

-  yes, true, True, TRUE:   the boolean value True
-  no, false, False, FALSE: the boolean value False
+  yes, true, True, TRUE, on:   the boolean value True
+  no, false, False, FALSE, off: the boolean value False

   makelist:   turns a dictionary (arg1) into a list of definitions
               (ignoring the keys)
   readfile:   reads a file (arg1) and returns it as a string
   makelist:   turns a dictionary (arg1) into a list of definitions
               (ignoring the keys)
   readfile:   reads a file (arg1) and returns it as a string

+  map:        applies the closure specified as arg1 to each of the
+              remaining elements in the list in turn.  Returns a list
+              made up of the outputs of the closure.

 
 Keys defined by modules are described below, in the module
 documentation.
 
 Keys defined by modules are described below, in the module
 documentation.


@@ -136,7 +157,17 @@ in configuration space to tell it what to do:
 
 * secnet command line options
 
 
 * secnet command line options
 

-XXX TODO
+Usage: secnet [OPTION]...
+
+  -f, --silent, --quiet   suppress error messages
+  -w, --nowarnings        suppress warnings
+  -v, --verbose           output extra diagnostics
+  -c, --config=filename   specify a configuration file
+  -j, --just-check-config stop after reading configfile
+  -n, --nodetach          do not run in background
+  -d, --debug=item,...    set debug options
+      --help              display this help and exit
+      --version           output version information and exit

 
 * secnet builtin modules
 
 
 * secnet builtin modules
 


@@ -163,9 +194,83 @@ Defines:
   udp (closure => comm closure)
 
 udp: dict argument
   udp (closure => comm closure)
 
 udp: dict argument

+  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
   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
 
 
 ** log
 


@@ -232,29 +337,36 @@ Defines:
 site: dict argument
   local-name (string): this site's name for itself
   name (string): the name of the site's peer
 site: dict argument
   local-name (string): this site's name for itself
   name (string): the name of the site's peer

-  netlink (netlink closure)
-  comm (comm closure)
+  link (netlink closure)
+  comm (one or more comm closures): if there is more than one, the
+   first one will be used for any key setups initiated by us using the
+   configured address.  Others are only used if our peer talks to
+   them.

   resolver (resolver closure)
   random (randomsrc closure)
   local-key (rsaprivkey closure)
   resolver (resolver closure)
   random (randomsrc closure)
   local-key (rsaprivkey closure)

-  address (string): optional, DNS name used to find our peer
+  address (string list): optional, DNS name(s) used to find our peer;
+    address literals are supported too if enclosed in `[' `]'.

   port (integer): mandatory if 'address' is specified: the port used
     to contact our peer
   port (integer): mandatory if 'address' is specified: the port used
     to contact our peer

-  networks (string list): networks that our peer may claim traffic for

   key (rsapubkey closure): our peer's public key
   transform (transform closure): how to mangle packets sent between sites
   dh (dh closure)
   hash (hash closure)
   key (rsapubkey closure): our peer's public key
   transform (transform closure): how to mangle packets sent between sites
   dh (dh closure)
   hash (hash closure)

-  key-lifetime (integer): max lifetime of a session key, in ms [one hour]
+  key-lifetime (integer): max lifetime of a session key, in ms
+    [one hour; mobile: 2 days]

   setup-retries (integer): max number of times to transmit a key negotiation
   setup-retries (integer): max number of times to transmit a key negotiation

-    packet [5]
+    packet [5; mobile: 30]

   setup-timeout (integer): time between retransmissions of key negotiation
   setup-timeout (integer): time between retransmissions of key negotiation

-    packets, in ms [1000]
+    packets, in ms [2000; mobile: 1000]

   wait-time (integer): after failed key setup, wait this long (in ms) before
   wait-time (integer): after failed key setup, wait this long (in ms) before

-    allowing another attempt [20000]
+    allowing another attempt [20000; mobile: 10000]

   renegotiate-time (integer): if we see traffic on the link after this time
   renegotiate-time (integer): if we see traffic on the link after this time

-    then renegotiate another session key immediately [depends on key-lifetime]
-  keepalive (bool): if True then attempt always to keep a valid session key
+    then renegotiate another session key immediately (in ms)
+    [half key-lifetime, or key-lifetime minus 5 mins (mobile: 12 hours),
+     whichever is longer].
+  keepalive (bool): if True then attempt always to keep a valid session key.
+    Not actually currently implemented. [false]

   log-events (string list): types of events to log for this site
     unexpected: unexpected key setup packets (may be late retransmissions)
     setup-init: start of attempt to setup a session key
   log-events (string list): types of events to log for this site
     unexpected: unexpected key setup packets (may be late retransmissions)
     setup-init: start of attempt to setup a session key


@@ -266,15 +378,61 @@ site: dict argument
     packet-drop: whenever we throw away an outgoing packet
     dump-packets: every key setup packet we see
     errors: failure of name resolution, internal errors
     packet-drop: whenever we throw away an outgoing packet
     dump-packets: every key setup packet we see
     errors: failure of name resolution, internal errors

+    peer-addrs: changes to sets of peer addresses (interesting for mobile peers)

     all: everything (too much!)
     all: everything (too much!)

-  netlink-options (string list): options to pass to netlink device when
-    registering remote networks
-    soft: create 'soft' routes that go away when there's no key established
-      with the peer
-    allow-route: allow packets from our peer to be sent down other tunnels,
-      as well as to the host
+  mobile (bool): if True then peer is "mobile" ie we assume it may
+    change its apparent IP address and port number without either it
+    or us being aware of the change; so, we remember the last several
+    port/addr pairs we've seen and send packets to all of them
+    (subject to a timeout).  We maintain one set of addresses for key
+    setup exchanges, and another for data traffic. Two communicating
+    peers must not each regard the other as mobile, or all the traffic
+    in each direction will be triplicated (strictly, transmitted
+    mobile-peers-max times) and anyway two peers whose public contact
+    address may suddenly change couldn't communicate reliably because
+    their contact addresses might both change at once. [false]
+  mobile-peers-max (integer): Maximum number of peer port/addr pairs we
+    remember and send to.  Must be at least 1 and no more than 5.
+    [4 if any address is configured, otherwise 3]
+  static-peers-max (integer): Maximum number of peer port/addr pairs
+    we can try for a static site.  Must be at least 1 and no more
+    than 5.  [4 or 3, as above]
+  mobile-peer-expiry (integer): For "mobile" peers only, the length
+    of time (in seconds) for which we will keep sending to multiple
+    address/ports from which we have not seen incoming traffic. [120]
+  local-mobile (bool): if True then other peers have been told we are
+    "mobile".  This should be True iff the peers' site configurations
+    for us have "mobile True" (and if we find a site configuration for
+    ourselves in the config, we insist on this).  The effect is to
+    check that there are no links both ends of which are allegedly
+    mobile (which is not supported, so those links are ignored) and
+    to change some of the tuning parameter defaults. [false]
+  mtu-target (integer): Desired value of the inter-site MTU for this
+    peering.  This value will be advertised to the peer (which ought
+    to affect incoming packets), and if the peer advertises an MTU its
+    value will be combined with this setting to compute the inter-site
+    MTU.  (secnet will still accept packets which exceed the
+    (negotiated or assumed) inter-site MTU.)  Setting a lower
+    inter-site MTU can be used to try to restrict the sizes of the
+    packets sent over the underlying public network (e.g. to work
+    around network braindamage).  It is not normally useful to set a
+    larger value for mtu-target than the VPN's general MTU (which
+    should be reflected in the local private interface MTU, ie the mtu
+    parameter to netlink).  If this parameter is not set, or is set
+    to 0, the default is to use the local private link mtu.
+
+Links involving mobile peers have some different tuning parameter
+default values, which are generally more aggressive about retrying key
+setup but more relaxed about using old keys.  These are noted with
+"mobile:", above, and apply whether the mobile peer is local or
+remote.
+
+** transform-eax
+
+Defines:
+   eax-serpent (closure => transform closure)

 
 

-** transform
+** transform-cbcmac

 
 Defines:
   serpent256-cbc (closure => transform closure)
 
 Defines:
   serpent256-cbc (closure => transform closure)


@@ -282,21 +440,33 @@ Defines:
 ** netlink
 
 Defines:
 ** netlink
 
 Defines:

-  null-netlink (closure => netlink closure)
+  null-netlink (closure => closure or netlink closure)

 
 null-netlink: dict argument
   name (string): name for netlink device, used in log messages
   networks (string list): networks on the host side of the netlink device
 
 null-netlink: dict argument
   name (string): name for netlink device, used in log messages
   networks (string list): networks on the host side of the netlink device

-  exclude-remote-networks (string list): networks that may never be claimed
-    by any remote site using this netlink device
+  remote-networks (string list): networks that may be claimed
+    by the remote site using this netlink device

   local-address (string): IP address of host's tunnel interface
   secnet-address (string): IP address of this netlink device
   ptp-address (string): IP address of the other end of a point-to-point link
   mtu (integer): MTU of host's tunnel interface
 
   local-address (string): IP address of host's tunnel interface
   secnet-address (string): IP address of this netlink device
   ptp-address (string): IP address of the other end of a point-to-point link
   mtu (integer): MTU of host's tunnel interface
 

-Only one of secnet-address or ptp-address may be specified. If
-point-to-point mode is in use then precisely one tunnel must register
-with the netlink device.
+Only one of secnet-address or ptp-address may be specified.  If
+point-to-point mode is in use then the "routes" option must also be
+specified, and netlink returns a netlink closure that should be used
+directly with the "link" option to the site closure.  If
+point-to-point mode is not in use then netlink returns a closure that
+may be invoked using a dict argument with the following keys to yield
+a netlink closure:
+  routes (string list): networks reachable down the tunnel attached to
+    this instance of netlink
+  options (string list):
+    allow-route: allow packets coming from this tunnel to be routed to
+      other tunnels as well as the host (used for mobile devices like laptops)
+    soft: remove these routes from the host's routing table when
+      the tunnel link quality is zero
+  mtu (integer): MTU of host's tunnel interface

 
 Netlink will dump its current routing table to the system/log on
 receipt of SIGUSR1.
 
 Netlink will dump its current routing table to the system/log on
 receipt of SIGUSR1.


@@ -320,24 +490,20 @@ Defines:
   tun-old (closure => netlink closure)
 
 tun: dict argument
   tun-old (closure => netlink closure)
 
 tun: dict argument

+  flavour (string): optional, type of TUN interface to use
+    ("guess","linux","bsd","streams")

   device (string): optional, path of TUN/TAP device file ["/dev/net/tun"]
   interface (string): optional, name of tunnel network interface
   ifconfig-path (string): optional, path to ifconfig command
   route-path (string): optional, path to route command
   device (string): optional, path of TUN/TAP device file ["/dev/net/tun"]
   interface (string): optional, name of tunnel network interface
   ifconfig-path (string): optional, path to ifconfig command
   route-path (string): optional, path to route command

+  ifconfig-type (string): optional, how to perform ifconfig
+  route-type (string): optional, how to add and remove routes
+   types are: "guess", "ioctl", "bsd", "linux", "solaris-2.5"

   buffer (buffer closure): buffer for host->secnet packets
  plus generic netlink options, as for 'null-netlink'
 
   buffer (buffer closure): buffer for host->secnet packets
  plus generic netlink options, as for 'null-netlink'
 

-tun-old: dict argument
-  device (string): optional, path of TUN/TAP device file ["/dev/tun*"]
-  interface (string): optional, name of tunnel network interface
-  interface-search (bool): optional, whether to search for a free tunnel
-    interface (True if 'device' not specified, otherwise False)
-  ifconfig-path (string): optional, path to ifconfig command
-  route-path (string): optional, path to route command
- plus generic netlink options, as for 'null-netlink'
-
- I recommend you don't specify the 'interface' option unless you're
- doing something that requires the interface name to be constant.
+I recommend you don't specify the 'interface' option unless you're
+doing something that requires the interface name to be constant.

 
 ** rsa
 
 
 ** rsa