.\"
.\" 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"
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
.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.
+.
.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.
.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
.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 watch (8).
+.BR connect (8).
.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 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
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 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 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
-.BR watch (8).
+.BR connect (8).
.TP
.B tunnel
Tunnel driver to use when adding the peer. Used by
and
.BR tripe-newpeers (8);
described below.
+.
.SS "Conversion"
This section describes how the textual
.B peers.in
.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
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
.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,
.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 tripe-newpeers (8),
.BR peers.cdb (5),
.BR connect (8),
-.BR watch (8),
.BR tripe-ifup (8).
.
.\"--------------------------------------------------------------------------
~mdw / tripe / blobdiff