Add a man page.

[secnet.git] / README

diff --git a/README b/README
index 14b7ad3d874cf4eb2b1b00854f70da736c5edfe3..84bb3921b2bca567b929aafe0fc9c579e27fdaf0 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
 


@@ -145,27 +176,166 @@ XXX TODO
 Defines:
   adns (closure => resolver closure)
 
 Defines:
   adns (closure => resolver closure)
 

+adns: dict argument
+  config (string): optional, a resolv.conf for ADNS to use
+

 ** random
 
 Defines:
   randomsrc (closure => randomsrc closure)
 
 ** random
 
 Defines:
   randomsrc (closure => randomsrc closure)
 

+randomsrc: string[,bool]
+  arg1: filename of random source
+  arg2: if True then source is blocking
+

 ** udp
 
 Defines:
   udp (closure => comm closure)
 
 ** udp
 
 Defines:
   udp (closure => comm closure)
 

-** util
+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
+  authbind (string): optional, path to authbind-helper program
+
+** 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 (closure => site closure)
 
 ** site
 
 Defines:
   site (closure => site closure)
 

+site: dict argument
+  local-name (string): this site's name for itself
+  name (string): the name of the site's peer
+  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)
+  address (string): optional, DNS name used to find our peer
+  port (integer): mandatory if 'address' is specified: the port used
+    to contact our peer
+  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; mobile: 2 days]
+  setup-retries (integer): max number of times to transmit a key negotiation
+    packet [5; mobile: 30]
+  setup-timeout (integer): time between retransmissions of key negotiation
+    packets, in ms [2000; mobile: 1000]
+  wait-time (integer): after failed key setup, wait this long (in ms) before
+    allowing another attempt [20000; mobile: 10000]
+  renegotiate-time (integer): if we see traffic on the link after this time
+    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
+    setup-timeout: failure of attempt to setup a session key, through timeout
+    activate-key: activation of a new session key
+    timeout-key: deletion of current session key through age
+    security: anything potentially suspicious
+    state-change: steps in the key setup protocol
+    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!)
+  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.  [3]
+  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]
+
+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
 
 Defines:
 ** transform
 
 Defines:


@@ -173,11 +343,71 @@ Defines:
 
 ** netlink
 
 
 ** netlink
 

+Defines:
+  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
+  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
+
+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): 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:
   userv-ipif (closure => netlink closure)
 Defines:
   userv-ipif (closure => netlink closure)

+
+userv-ipif: dict argument
+  userv-path (string): optional, where to find userv ["userv"]
+  service-user (string): optional, username for userv-ipif service ["root"]
+  service-name (string): optional, name of userv-ipif service ["ipif"]
+  buffer (buffer closure): buffer for assembly of host->secnet packets
+ plus generic netlink options, as for 'null-netlink'
+
+** tun
+
+Defines:

   tun (closure => netlink closure) [only on linux-2.4]
   tun-old (closure => netlink closure)
   tun (closure => netlink closure) [only on linux-2.4]
   tun-old (closure => netlink closure)

-  null-netlink (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
+  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'
+
+I recommend you don't specify the 'interface' option unless you're
+doing something that requires the interface name to be constant.

 
 ** rsa
 
 
 ** rsa
 


@@ -185,12 +415,48 @@ Defines:
   rsa-private (closure => rsaprivkey closure)
   rsa-public (closure => rsapubkey closure)
 
   rsa-private (closure => rsaprivkey closure)
   rsa-public (closure => rsapubkey closure)
 

+rsa-private: string[,bool]
+  arg1: filename of SSH private key file (version 1, no password)
+  arg2: whether to check that the key is usable [default True]
+
+rsa-public: string,string
+  arg1: encryption key (decimal)
+  arg2: modulus (decimal)
+

 ** dh
 
 Defines:
   diffie-hellman (closure => dh closure)
 
 ** dh
 
 Defines:
   diffie-hellman (closure => dh closure)
 

+diffie-hellman: string,string[,bool]
+  arg1: modulus (hex)
+  arg2: generator (hex)
+  arg3: whether to check that the modulus is prime [default True]
+

 ** md5
 
 Defines:
   md5 (hash closure)
 ** md5
 
 Defines:
   md5 (hash closure)

+
+** sha1
+
+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.