portability: use socklen_t for argument to recvfrom

[secnet.git] / README

diff --git a/README b/README
index 35041831e5e83b17a39eec71129b44fbcb05484c..564b216ce6d57a9a221d9e33f14837677852c58d 100644 (file)
--- a/README
+++ b/README
@@ -1,5 +1,20 @@
 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 portable snprintf implementation in snprintf.c is Copyright (C)
+1999 Mark Martinec <mark.martinec@ijs.si> and is distributed under the
+terms of the Frontier Artistic License.  You can find the standard
+version of snprintf.c at http://www.ijs.si/software/snprintf/
+
+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 +34,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 +121,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 +134,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 +162,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,15 +199,68 @@ Defines:
   udp (closure => comm closure)
 
 udp: dict argument
   udp (closure => comm closure)
 
 udp: dict argument

+  address (string): IP address to listen and send on

   port (integer): UDP port to listen and send on
   buffer (buffer closure): buffer for incoming packets
   port (integer): UDP port to listen and send on
   buffer (buffer closure): buffer for incoming packets

+  authbind (string): optional, path to authbind-helper program

 
 

-** util
+** log

 
 Defines:
   logfile (closure => log closure)
 
 Defines:
   logfile (closure => log closure)

+  syslog (closure => log closure)
+
+logfile: dict argument
+  filename (string): where to log to
+  class (string list): what type of messages to log
+    { "debug-config", M_DEBUG_CONFIG },
+    { "debug-phase", M_DEBUG_PHASE },
+    { "debug", M_DEBUG },
+    { "all-debug", M_DEBUG|M_DEBUG_PHASE|M_DEBUG_CONFIG },
+    { "info", M_INFO },
+    { "notice", M_NOTICE },
+    { "warning", M_WARNING },
+    { "error", M_ERROR },
+    { "security", M_SECURITY },
+    { "fatal", M_FATAL },
+    { "default", M_WARNING|M_ERROR|M_SECURITY|M_FATAL },
+    { "verbose", M_INFO|M_NOTICE|M_WARNING|M_ERROR|M_SECURITY|M_FATAL },
+    { "quiet", M_FATAL }
+
+logfile will close and reopen its file upon receipt of SIGHUP.
+
+syslog: dict argument
+  ident (string): include this string in every log message
+  facility (string): facility to log as
+    { "authpriv", LOG_AUTHPRIV },
+    { "cron", LOG_CRON },
+    { "daemon", LOG_DAEMON },
+    { "kern", LOG_KERN },
+    { "local0", LOG_LOCAL0 },
+    { "local1", LOG_LOCAL1 },
+    { "local2", LOG_LOCAL2 },
+    { "local3", LOG_LOCAL3 },
+    { "local4", LOG_LOCAL4 },
+    { "local5", LOG_LOCAL5 },
+    { "local6", LOG_LOCAL6 },
+    { "local7", LOG_LOCAL7 },
+    { "lpr", LOG_LPR },
+    { "mail", LOG_MAIL },
+    { "news", LOG_NEWS },
+    { "syslog", LOG_SYSLOG },
+    { "user", LOG_USER },
+    { "uucp", LOG_UUCP }
+
+** util
+
+Defines:

   sysbuffer (closure => buffer closure)
 
   sysbuffer (closure => buffer closure)
 

+sysbuffer: integer[,dict]
+  arg1: buffer length
+  arg2: options:
+    lockdown (boolean): if True, mlock() the buffer
+

 ** site
 
 Defines:
 ** site
 
 Defines:


@@ -180,7 +269,7 @@ 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)
+  link (netlink closure)

   comm (comm closure)
   resolver (resolver closure)
   random (randomsrc closure)
   comm (comm closure)
   resolver (resolver closure)
   random (randomsrc closure)


@@ -188,7 +277,6 @@ site: dict argument
   address (string): optional, DNS name used to find our peer
   port (integer): mandatory if 'address' is specified: the port used
     to contact our peer
   address (string): optional, DNS name used to find 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)
   key (rsapubkey closure): our peer's public key
   transform (transform closure): how to mangle packets sent between sites
   dh (dh closure)


@@ -215,12 +303,6 @@ site: dict argument
     dump-packets: every key setup packet we see
     errors: failure of name resolution, internal errors
     all: everything (too much!)
     dump-packets: every key setup packet we see
     errors: failure of name resolution, internal errors
     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

 
 ** transform
 
 
 ** transform
 


@@ -230,7 +312,7 @@ 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
 
 null-netlink: dict argument
   name (string): name for netlink device, used in log messages


@@ -239,8 +321,28 @@ null-netlink: dict argument
     by any 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
     by any 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
 
   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 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-route: remove these routes from the host's routing table when
+      the tunnel link quality is zero
+  mtu (integer): default MTU over this link; may be updated by tunnel code
+
+Netlink will dump its current routing table to the system/log on
+receipt of SIGUSR1.
+

 ** slip
 
 Defines:
 ** slip
 
 Defines:


@@ -260,21 +362,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.

 
 ** rsa
 
 
 ** rsa
 


@@ -309,3 +410,21 @@ Defines:
 
 Defines:
   sha1 (hash closure)
 
 Defines:
   sha1 (hash closure)

+
+** conffile
+
+Defines:
+  makelist (dictionary => list of definitions)
+  readfile (string => string)
+  map (closure,list => list)
+
+makelist: dictionary
+  returns a list consisting of the definitions in the dictionary. The keys
+  are discarded.
+
+readfile: string
+  reads the named file and returns its contents as a string
+
+map:
+  applies the closure specified as arg1 to each of the elements in the list.
+  Returns a list made up of the outputs of the closure.