uslip/uslip.c: Be consistent about `VERB_NOUN' function naming.

[tripe] / peerdb / peers.in.5.in

diff --git a/peerdb/peers.in.5.in b/peerdb/peers.in.5.in
index e31d0e37973a28b884b8da4245ae7a2a385ad292..9ce9561c3c60e01ae28a124bc78dcdc3235d29c1 100644 (file)
--- a/peerdb/peers.in.5.in
+++ b/peerdb/peers.in.5.in
@@ -27,7 +27,7 @@
 .so ../defs.man.in \"@@@PRE@@@
 .
 .\"--------------------------------------------------------------------------
 .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"
 .
 .\"--------------------------------------------------------------------------
 .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.
 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
 .SS "General structure"
 The configuration file is line-oriented.  Blank lines are ignored; lines
 beginning with a hash


@@ -96,15 +97,33 @@ There is a simple concept of
 .I inheritance
 for sections.  If a section contains an assignment
 .IP
 .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
 .PP
 then any lookups which can't be satisfied in that section will be

-satisfied instead from the
+satisfied instead from its

 .I parent
 .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
 .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]
 example, given the sections
 .VS
 [parent]


@@ -112,9 +131,10 @@ detail = in parent
 blurb = expand $(detail)
 .VE
 Apart from its effect on lookups, as just described, the
 blurb = expand $(detail)
 .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.
 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.
 .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.


@@ -132,7 +152,7 @@ described below.
 .TP
 .B connect
 Shell command for initiating connection to this peer.  Used by
 .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
 .TP
 .B cork
 Don't initiate immediate key exchange.  Used by


@@ -140,15 +160,15 @@ Don't initiate immediate key exchange.  Used by
 .TP
 .B disconnect
 Shell command for closing down connection to this peer.  Used by
 .TP
 .B disconnect
 Shell command for closing down connection to this peer.  Used by

-.BR watch (8).
+.BR connect (8).

 .TP
 .B every
 Interval for checking that the peer is still alive and well.  Used by
 .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
 .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
 .TP
 .B ifname
 Interface name to set for the tunnel interface to the peer.  Used by


@@ -156,7 +176,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
 .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
 .TP
 .B ifupextra
 Script containing additional interface setup.  Used by


@@ -194,6 +214,8 @@ Used by
 .TP
 .B priv
 Tag of the private key to use when communicating with the peer.
 .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
 .TP
 .B raddr
 Remote address for the tunnel interface to the peer.  Used by


@@ -201,11 +223,11 @@ Remote address for the tunnel interface to the peer.  Used by
 .TP
 .B retries
 Number of failed ping attempts before attempting reconnection.  Used by
 .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
 .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
 .TP
 .B tunnel
 Tunnel driver to use when adding the peer.  Used by


@@ -219,6 +241,7 @@ Used by
 and
 .BR tripe-newpeers (8);
 described below.
 and
 .BR tripe-newpeers (8);
 described below.

+.

 .SS "Conversion"
 This section describes how the textual
 .B peers.in
 .SS "Conversion"
 This section describes how the textual
 .B peers.in


@@ -232,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
 .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
 key).
 .hP \*o
 Sections whose names have the form


@@ -240,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
 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
 key) are stored in the record using
 .B form-urlencoding
 as defined in RFC1822, except that the key-value pairs are separated by


@@ -249,7 +272,7 @@ semicolons
 rather than ampersands
 .RB ` & '.
 The
 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
 key-value pair is not written to the database.
 .hP \*o
 Other sections are written to peer-type database records, named


@@ -286,7 +309,6 @@ is created whose contents is the section name.
 .BR tripe-newpeers (8),
 .BR peers.cdb (5),
 .BR connect (8),
 .BR tripe-newpeers (8),
 .BR peers.cdb (5),
 .BR connect (8),

-.BR watch (8),

 .BR tripe-ifup (8).
 .
 .\"--------------------------------------------------------------------------
 .BR tripe-ifup (8).
 .
 .\"--------------------------------------------------------------------------