X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/tripe/blobdiff_plain/a62f8e8a94bf56194539f7140a1215bc74309b36..HEAD:/peerdb/peers.in.5.in diff --git a/peerdb/peers.in.5.in b/peerdb/peers.in.5.in index fbc7c5c5..c128a4ed 100644 --- a/peerdb/peers.in.5.in +++ b/peerdb/peers.in.5.in @@ -9,25 +9,24 @@ .\" .\" This file is part of Trivial IP Encryption (TrIPE). .\" -.\" TrIPE is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License as published by -.\" the Free Software Foundation; either version 2 of the License, or -.\" (at your option) any later version. +.\" TrIPE is free software: you can redistribute it and/or modify it under +.\" the terms of the GNU General Public License as published by the Free +.\" Software Foundation; either version 3 of the License, or (at your +.\" option) any later version. .\" -.\" TrIPE is distributed in the hope that it will be useful, -.\" but WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License for more details. +.\" TrIPE is distributed in the hope that it will be useful, but WITHOUT +.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. .\" .\" You should have received a copy of the GNU General Public License -.\" along with TrIPE; if not, write to the Free Software Foundation, -.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +.\" along with TrIPE. If not, see . . .\"-------------------------------------------------------------------------- -.so ../defs.man.in \"@@@PRE@@@ +.so ../common/defs.man \"@@@PRE@@@ . .\"-------------------------------------------------------------------------- -.TH peers.in 5 "27 March 2008" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" +.TH peers.in 5tripe "27 March 2008" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" . .\"-------------------------------------------------------------------------- .SH "NAME" @@ -44,6 +43,7 @@ file is a plain text configuration file. It is read by in order to produce the .BR tripe.cdb (8) database used by services and other tools. +. .SS "General structure" The configuration file is line-oriented. Blank lines are ignored; lines beginning with a hash @@ -83,39 +83,90 @@ is replaced by the value assigned to the given .IR key . .hP \*o An occurrence of -.BI $[ host ] +.BI $ flags [ host ] is replaced by the IP address of the named .IR host . Note that .I host may itself contain .BI $( key ) -substitutions. +substitutions. The +.I flags +consist of zero or more of the following characters: +.RB ` 4 ' +looks up the +.IR host 's +IPv4 address(es); +.RB ` 6 ' +looks up the +.IR host 's +IPv6 address(es); +and +.RB ` * ' +returns all of the found addresses, separated by spaces, rather than +just the first one. If neither address family is requested, then +.RB ` 46 ' +is assumed. IPv6 address lookup of names, rather than address literals, +depends on the external +.BR adnshost (1) +program; if it is not present then only IPv4 lookups will be performed. .PP There is a simple concept of .I inheritance for sections. If a section contains an assignment .IP -.BI "@inherits = " parent +.BI "@inherit = " parent +.RB [[,] +.I parent +\&...] .PP then any lookups which can't be satisfied in that section will be -satisfied instead from the +satisfied instead from its .I parent -section (and, if necessary, its parent in turn, and so on). Note that +sections (and, if necessary, their parents in turn, and so on). +.PP +.hP \*o +If a value can be found for a key via multiple parents then all of them +must report the +.I same +value. This restriction may be relaxed somewhat, if it turns out that a +more flexible notion of multiple inheritance is useful. +.hP \*o +It's not allowed for a section to inherit, possibly indirectly, from +itself. Currently errors of this kind are only diagnosed when a cycle +is encountered while looking up a key and none of the sections on the +path from the original section up to and round the cycle define a value +for it. Future versions of this program might be more picky. +.PP +Note that .BI $( key ) substitutions in the resulting value will be satisfied from the original -section (though falling back to scanning the parent section). For +section (though falling back to scanning parent sections). For example, given the sections .VS [parent] -detail = in parent +detail = in $(name) blurb = expand $(detail) +[child] +@inherit = parent +.VE +the key +.B blurb +takes the value +.RB ` "expand in parent" ' +in section +.BR parent , +and +.RB ` "expand in child" ' +in section +.BR child . .PP Apart from its effect on lookups, as just described, the -.B @inherits +.B @inherit key is entirely ignored. In particular, it is never written to the database. +. .SS "Standard keys and their meanings" The following keys have meanings to programs in the TrIPE suite. Other keys may be used by separately distributed extensions or for local use. @@ -133,19 +184,29 @@ described below. .TP .B connect Shell command for initiating connection to this peer. Used by -.BR watch (8). +.BR connect (8). .TP .B cork -Don't initiate immediate key exchange.. Used by +Don't initiate immediate key exchange. Used by +.BR connect (8). +.TP +.B disconnect +Shell command for closing down connection to this peer. Used by +.BR connect (8). +.TP +.B ephemeral +Mark the peer as ephemeral: see +.BR tripe-admin (5) +for what this means. Used by .BR connect (8). .TP .B every Interval for checking that the peer is still alive and well. Used by -.BR watch (8). +.BR connect (8). .TP .B ifdown Script to bring down tunnel interface connected to the peer. Used by -.BR watch (8). +.BR connect (8). .TP .B ifname Interface name to set for the tunnel interface to the peer. Used by @@ -153,7 +214,7 @@ Interface name to set for the tunnel interface to the peer. Used by .TP .B ifup Script to bring up tunnel interface connected to the peer. Used by -.BR watch (8). +.BR connect (8). .TP .B ifupextra Script containing additional interface setup. Used by @@ -167,6 +228,18 @@ Local address for the tunnel interface to the peer. Used by Interval for sending keepalive pings. Used by .BR connect (8). .TP +.B key +Key tag to use to authenticate the peer. Used by +.BR connect (8). +.TP +.B knock +Knock string to send when establishing a dynamic connection. Used by +.BR connect (8). +.TP +.B mobile +Peer's IP address is highly volatile. Used by +.BR connect (8). +.TP .B mtu Maximum transmission unit for the tunnel interface. Used by .BR tripe-ifup (8). @@ -181,17 +254,22 @@ Network address for this peer, or Used by .BR connect (8). .TP +.B priv +Tag of the private key to use when communicating with the peer. +Used by +.BR connect (8). +.TP .B raddr Remote address for the tunnel interface to the peer. Used by .BR tripe-ifup (8). .TP .B retries Number of failed ping attempts before attempting reconnection. Used by -.BR watch (8). +.BR connect (8). .TP .B timeout Timeout for ping probes. Used by -.BR watch (8). +.BR connect (8). .TP .B tunnel Tunnel driver to use when adding the peer. Used by @@ -205,6 +283,7 @@ Used by and .BR tripe-newpeers (8); described below. +. .SS "Conversion" This section describes how the textual .B peers.in @@ -218,7 +297,7 @@ Sections whose names have the form .BI @ whatever are ignored (though their contents may be relevant if the section is named in another section's -.B @inherits +.B @inherit key). .hP \*o Sections whose names have the form @@ -226,7 +305,7 @@ Sections whose names have the form are written to local-type database records with the same name. The keys and values defined in the section (and its parent section, if it contains an -.B @inherits +.B @inherit key) are stored in the record using .B form-urlencoding as defined in RFC1822, except that the key-value pairs are separated by @@ -234,9 +313,9 @@ semicolons .RB ` ; ' rather than ampersands .RB ` & '. -The -.B @inherits -key-value pair is not written to the database. +Keys whose names begin with +.RB ` @ ' +are not written to the database. .hP \*o Other sections are written to peer-type database records, named .BI P name \fR, @@ -247,7 +326,7 @@ Firstly, if there is a key .B auto in the section (or in its parent, etc.), and the value is .BR y , -.BR yes . +.BR yes , .BR t , .BR true , .BR 1 , @@ -272,7 +351,6 @@ is created whose contents is the section name. .BR tripe-newpeers (8), .BR peers.cdb (5), .BR connect (8), -.BR watch (8), .BR tripe-ifup (8). . .\"--------------------------------------------------------------------------