server/admin.c: Remove spurious `ping' in usage message.

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

diff --git a/peerdb/peers.in.5.in b/peerdb/peers.in.5.in
index 59bee4543455efd91d0465fb78d8e90013317595..c128a4ed31d9df771af40db0cbc010120737f43e 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"


@@ -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.
 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


@@ -83,38 +83,90 @@ is replaced by the value assigned to the given
 .IR key .
 .hP \*o
 An occurrence of
 .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 )
 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
 .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
 .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
 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,19 +184,29 @@ 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
 .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 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
 .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


@@ -152,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
 .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


@@ -166,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
 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).
 .B mtu
 Maximum transmission unit for the tunnel interface.  Used by
 .BR tripe-ifup (8).


@@ -180,17 +254,22 @@ Network address for this peer, or
 Used by
 .BR connect (8).
 .TP
 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
 .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
 .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


@@ -204,6 +283,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


@@ -217,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
 .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


@@ -225,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
 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


@@ -233,9 +313,9 @@ semicolons
 .RB ` ; '
 rather than ampersands
 .RB ` & '.
 .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,
 .hP \*o
 Other sections are written to peer-type database records, named
 .BI P name \fR,


@@ -246,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 ,
 .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 ,
 .BR t ,
 .BR true ,
 .BR 1 ,


@@ -271,7 +351,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).
 .
 .\"--------------------------------------------------------------------------