X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/tripe/blobdiff_plain/6005ef9bfba49124a25825a5b044d4f4cbf02792..75ed082dd96059e3949491d43544d0353f1502ad:/peerdb/peers.in.5.in

diff --git a/peerdb/peers.in.5.in b/peerdb/peers.in.5.in
index 7b0127b1..9ce9561c 100644
--- a/peerdb/peers.in.5.in
+++ b/peerdb/peers.in.5.in
@@ -27,7 +27,7 @@
 .so ../defs.man.in \"@@@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 +44,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
@@ -96,26 +97,44 @@ 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
 blurb = expand $(detail)
-
-.PP
+.VE
 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.
@@ -126,15 +145,103 @@ details.
 If true, include the peer in the
 .B %AUTO
 record.  Used by
+.BR connect (8)
+and
 .BR tripe-newpeers (8);
 described below.
 .TP
+.B connect
+Shell command for initiating connection to this peer.  Used by
+.BR connect (8).
+.TP
+.B cork
+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 every
+Interval for checking that the peer is still alive and well.  Used by
+.BR connect (8).
+.TP
+.B ifdown
+Script to bring down tunnel interface connected to the peer.  Used by
+.BR connect (8).
+.TP
+.B ifname
+Interface name to set for the tunnel interface to the peer.  Used by
+.BR tripe-ifup (8).
+.TP
+.B ifup
+Script to bring up tunnel interface connected to the peer.  Used by
+.BR connect (8).
+.TP
+.B ifupextra
+Script containing additional interface setup.  Used by
+.BR tripe-ifup (8).
+.TP
+.B laddr
+Local address for the tunnel interface to the peer.  Used by
+.BR tripe-ifup (8).
+.TP
+.B keepalive
+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 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).
+.TP
+.B nets
+Networks to be routed over the tunnel interface.  Used by
+.BR tripe-ifup (8).
+.TP
+.B peer
+Network address for this peer, or
+.BR PASSIVE .
+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 connect (8).
+.TP
+.B timeout
+Timeout for ping probes.  Used by
+.BR connect (8).
+.TP
+.B tunnel
+Tunnel driver to use when adding the peer.  Used by
+.BR connect (8)).
+.TP
 .B user
 Peer will make active connection as
 .IR user .
 Used by
+.BR connect (8)
+and
 .BR tripe-newpeers (8);
 described below.
+.
 .SS "Conversion"
 This section describes how the textual
 .B peers.in
@@ -148,7 +255,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
@@ -156,7 +263,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
@@ -165,7 +272,7 @@ semicolons
 rather than ampersands
 .RB ` & '.
 The
-.B @inherits
+.B @inherit
 key-value pair is not written to the database.
 .hP \*o
 Other sections are written to peer-type database records, named
@@ -201,6 +308,7 @@ is created whose contents is the section name.
 .PP
 .BR tripe-newpeers (8),
 .BR peers.cdb (5),
+.BR connect (8),
 .BR tripe-ifup (8).
 .
 .\"--------------------------------------------------------------------------