X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=secnet.git;a=blobdiff_plain;f=README;h=564b216ce6d57a9a221d9e33f14837677852c58d;hp=35041831e5e83b17a39eec71129b44fbcb05484c;hb=b1a0f651d803e1c1ff50f559b50de5c2dd6236d4;hpb=3454dce4c6909648b711a59b57c5a527036b2a8e diff --git a/README b/README index 3504183..564b216 100644 --- a/README +++ b/README @@ -1,5 +1,20 @@ 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 portable snprintf implementation in snprintf.c is Copyright (C) +1999 Mark Martinec 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 @@ -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'. +* 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 +121,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 +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: - 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 +162,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,15 +199,68 @@ Defines: 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 + authbind (string): optional, path to authbind-helper program -** util +** log 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: integer[,dict] + arg1: buffer length + arg2: options: + lockdown (boolean): if True, mlock() the buffer + ** 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 - netlink (netlink closure) + link (netlink 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 - 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) @@ -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!) - 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 @@ -230,7 +312,7 @@ 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 @@ -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 + 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-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: @@ -260,21 +362,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. ** rsa @@ -309,3 +410,21 @@ Defines: 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.