X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=secnet.git;a=blobdiff_plain;f=README;h=4d6f4e54e2ca54e930f75f569a84c76a077ea83c;hp=79b5447a6726ff5b6e8c7ed53a7e42a89b2e4405;hb=ae5ae3bf5c5709938e3a2bb6203094ede8af45e6;hpb=c6f79b178fe27ee315055dccb371b63ca1a6183a diff --git a/README b/README index 79b5447..4d6f4e5 100644 --- a/README +++ b/README @@ -1,5 +1,15 @@ secnet - flexible VPN software +* Copying + +secnet is Copyright (C) 1995--2003 Stephen Early +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 @@ -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'. +* 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 ; they will be +forwarded to the -discuss list by me. + * Creating a VPN XXX TODO @@ -92,12 +116,6 @@ f is a dictionary: 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. {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). @@ -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: - 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 + 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. @@ -136,7 +157,17 @@ in configuration space to tell it what to do: * 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 @@ -163,6 +194,7 @@ Defines: udp (closure => comm closure) udp: dict argument + address (string list): IPv6 or IPv4 addresses 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 @@ -232,29 +264,36 @@ Defines: 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) - 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 - 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-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 - packet [5] + packet [5; mobile: 30] 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 - allowing another attempt [20000] + 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 [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 @@ -266,15 +305,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 + peer-addrs: changes to sets of peer addresses (interesting for mobile peers) 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) @@ -282,21 +367,33 @@ 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 - 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 -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. @@ -320,24 +417,20 @@ Defines: 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 + 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' -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