Add notion of `ephemeral' associations and a goodbye protocol.

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

.\" -*-nroff-*-
.\".
.\" Manual for the peer configuration file
.\"
.\" (c) 2008 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" 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 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.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with TrIPE.  If not, see <https://www.gnu.org/licenses/>.
.
.\"--------------------------------------------------------------------------
.so ../common/defs.man \"@@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH peers.in 5tripe "27 March 2008" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
.
.\"--------------------------------------------------------------------------
.SH "NAME"
.
peers.in \- source form for TrIPE peer database
.
.\"--------------------------------------------------------------------------
.SH "DESCRIPTION"
.
The
.B peers.in
file is a plain text configuration file.  It is read by
.BR tripe-newpeers (8)
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
.RB ` # '
or semicolon
.RB ` ; '
are ignored.  The file is divided into sections by section headers,
which are lines of the form
.IP
.BI [ name ]
.PP
Within each section are a number of assignments, of the form
.IP
.IB key " = " value
.PP
or (entirely equivalent)
.IP
.IB key ": " value
.PP
The
.I key
must start in the left hand column.  The
.I value
may span multiple lines if subsequent lines begin with whitespace, in
the manner of RFC822 headers.
.PP
There is a special case to be aware of: if a section doesn't specify a
value for the key
.B name
then the section's own name is used as a default.
.PP
The following substitutions are made in the body of a value.
.hP \*o
An occurrence of
.BI $( key )
is replaced by the value assigned to the given
.IR key .
.hP \*o
An occurrence of
.BI $[ host ]
is replaced by the IP address of the named
.IR host .
Note that
.I host
may itself contain
.BI $( key )
substitutions.
.PP
There is a simple concept of
.I inheritance
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
satisfied instead from its
.I parent
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 parent sections).  For
example, given the sections
.VS
[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 @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.
The descriptions given are summaries only; see the references for
details.
.TP
.B auto
If true, include the peer in the
.B %AUTO
record.  Used by
.BR connect (8)
and
.BR tripe-newpeers (8);
described below.
.TP
.B connect
Shell command for initiating connection to this peer.  Used by
.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 connect (8).
.TP
.B ifdown
Script to bring down tunnel interface connected to the peer.  Used by
.BR connect (8).
.TP
.B ifname
Interface name to set for the tunnel interface to the peer.  Used by
.BR tripe-ifup (8).
.TP
.B ifup
Script to bring up tunnel interface connected to the peer.  Used by
.BR connect (8).
.TP
.B ifupextra
Script containing additional interface setup.  Used by
.BR tripe-ifup (8).
.TP
.B laddr
Local address for the tunnel interface to the peer.  Used by
.BR tripe-ifup (8).
.TP
.B keepalive
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).
.TP
.B nets
Networks to be routed over the tunnel interface.  Used by
.BR tripe-ifup (8).
.TP
.B peer
Network address for this peer, or
.BR PASSIVE .
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
.BR connect (8).
.TP
.B timeout
Timeout for ping probes.  Used by
.BR connect (8).
.TP
.B tunnel
Tunnel driver to use when adding the peer.  Used by
.BR connect (8)).
.TP
.B user
Peer will make active connection as
.IR user .
Used by
.BR connect (8)
and
.BR tripe-newpeers (8);
described below.
.
.SS "Conversion"
This section describes how the textual
.B peers.in
file is converted into the
.BR peers.cdb (5)
database.
.PP
The handling of each section depends on its name.
.hP \*o
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 @inherit
key).
.hP \*o
Sections whose names have the form
.BI $ whatever
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 @inherit
key) are stored in the record using
.B form-urlencoding
as defined in RFC1822, except that the key-value pairs are separated by
semicolons
.RB ` ; '
rather than ampersands
.RB ` & '.
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,
in exactly the same way as for local-type records.  However, two special
actions are also taken.
.IP
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 t ,
.BR true ,
.BR 1 ,
or
.BR on ,
then the section's name is added in the special
.B %AUTO
record.
.IP
Secondly, if there is a key
.B user
in the section (or in its parent, etc.), then a user record
.BI U user
is created whose contents is the section name.
.
.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
.
.BR cdb (5),
.BR tripe (8).
.PP
.BR tripe-newpeers (8),
.BR peers.cdb (5),
.BR connect (8),
.BR tripe-ifup (8).
.
.\"--------------------------------------------------------------------------
.SH "AUTHOR"
.
Mark Wooding, <mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------