Add new `knock' protocol.

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

diff --git a/peerdb/peers.in.5.in b/peerdb/peers.in.5.in
index c92dabb..89eb777 100644 (file)
--- 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).
 .\"
 .\"
 .\" 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
 .\"
 .\" 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"
 .
 .\"--------------------------------------------------------------------------
 .SH "NAME"


@@ -98,20 +97,52 @@ There is a simple concept of
 for sections.  If a section contains an assignment
 .IP
 .BI "@inherit = " parent
 for sections.  If a section contains an assignment
 .IP
 .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]

-detail = in parent
+detail = in $(name)

 blurb = expand $(detail)
 blurb = expand $(detail)

+
+[child]
+@inherit = parent

 .VE
 .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 @inherit
 key is entirely ignored.  In particular, it is never written to the
 Apart from its effect on lookups, as just described, the
 .B @inherit
 key is entirely ignored.  In particular, it is never written to the


@@ -176,6 +207,10 @@ Interval for sending keepalive pings.  Used by
 Key tag to use to authenticate the peer.  Used by
 .BR connect (8).
 .TP
 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).
 .B mobile
 Peer's IP address is highly volatile.  Used by
 .BR connect (8).


@@ -253,9 +288,9 @@ semicolons
 .RB ` ; '
 rather than ampersands
 .RB ` & '.
 .RB ` ; '
 rather than ampersands
 .RB ` & '.

-The
-.B @inherit
-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,
 .hP \*o
 Other sections are written to peer-type database records, named
 .BI P name \fR,