X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=secnet.git;a=blobdiff_plain;f=README;h=414baee6caccaeb680e83617c455f176015660e6;hp=93730e97a2c9cbf687fbffb73959beb02bda4a29;hb=94ca562bb14422940ff1986ce8dfca87c222cb59;hpb=92a7d254975db245c3320855515bffc1aebda9e4 diff --git a/README b/README index 93730e9..414baee 100644 --- a/README +++ b/README @@ -194,10 +194,83 @@ Defines: udp (closure => comm closure) udp: dict argument - address (string): IP address to listen and send on + 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 + 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 `+|- 4|6 ' where 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 @@ -272,7 +345,8 @@ site: dict argument 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 key (rsapubkey closure): our peer's public key @@ -318,7 +392,11 @@ site: dict argument 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] + 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] @@ -329,6 +407,19 @@ site: dict argument 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 @@ -336,6 +427,11 @@ 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-cbcmac Defines: @@ -370,7 +466,7 @@ a netlink closure: 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 + mtu (integer): MTU of host's tunnel interface Netlink will dump its current routing table to the system/log on receipt of SIGUSR1.