X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/tripe/blobdiff_plain/d64ce4ae05ad8250e08296af18d7d6ddcc5bbc9a..HEAD:/peerdb/peers.in.5.in

diff --git a/peerdb/peers.in.5.in b/peerdb/peers.in.5.in
index 240296e9..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 <https://www.gnu.org/licenses/>.
 .
 .\"--------------------------------------------------------------------------
-.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"
@@ -84,36 +83,87 @@ 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.
 .
@@ -144,6 +194,12 @@ Don't initiate immediate key exchange.  Used by
 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 connect (8).
@@ -176,6 +232,10 @@ Interval for sending keepalive pings.  Used by
 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).
@@ -237,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
@@ -245,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
@@ -253,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,
@@ -266,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 ,