[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 $ flags [ host ]
is replaced by the IP address of the named
.IR host .
Note that
.I host
may itself contain
.BI $( key )
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 "@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 --------------------------------------------------
Commit	Line	Data
6005ef9b MW	1	.\" --nroff--
	2	.\".
	3	.\" Manual for the peer configuration file
	4	.\"
	5	.\" (c) 2008 Straylight/Edgeware
	6	.\"
	7	.
	8	.\"----- Licensing notice ---------------------------------------------------
	9	.\"
	10	.\" This file is part of Trivial IP Encryption (TrIPE).
	11	.\"
11ad66c2 MW	12	.\" TrIPE is free software: you can redistribute it and/or modify it under
	13	.\" the terms of the GNU General Public License as published by the Free
	14	.\" Software Foundation; either version 3 of the License, or (at your
	15	.\" option) any later version.
6005ef9b	16	.\"
11ad66c2 MW	17	.\" TrIPE is distributed in the hope that it will be useful, but WITHOUT
	18	.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	19	.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	20	.\" for more details.
6005ef9b MW	21	.\"
6005ef9b MW	22	.\" You should have received a copy of the GNU General Public License
11ad66c2	23	.\" along with TrIPE. If not, see <https://www.gnu.org/licenses/>.
6005ef9b MW	24	.
6005ef9b MW	25	.\"--------------------------------------------------------------------------
cd450424	26	.so ../common/defs.man \"@@@PRE@@@
6005ef9b MW	27	.
6005ef9b MW	28	.\"--------------------------------------------------------------------------
0647ba7c	29	.TH peers.in 5tripe "27 March 2008" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
6005ef9b MW	30	.
	31	.\"--------------------------------------------------------------------------
	32	.SH "NAME"
	33	.
	34	peers.in \- source form for TrIPE peer database
	35	.
	36	.\"--------------------------------------------------------------------------
	37	.SH "DESCRIPTION"
	38	.
	39	The
	40	.B peers.in
	41	file is a plain text configuration file. It is read by
	42	.BR tripe-newpeers (8)
	43	in order to produce the
	44	.BR tripe.cdb (8)
	45	database used by services and other tools.
d64ce4ae	46	.
6005ef9b MW	47	.SS "General structure"
	48	The configuration file is line-oriented. Blank lines are ignored; lines
	49	beginning with a hash
	50	.RB ` # '
	51	or semicolon
	52	.RB ` ; '
	53	are ignored. The file is divided into sections by section headers,
	54	which are lines of the form
	55	.IP
	56	.BI [ name ]
	57	.PP
	58	Within each section are a number of assignments, of the form
	59	.IP
	60	.IB key " = " value
	61	.PP
	62	or (entirely equivalent)
	63	.IP
	64	.IB key ": " value
	65	.PP
	66	The
	67	.I key
	68	must start in the left hand column. The
	69	.I value
	70	may span multiple lines if subsequent lines begin with whitespace, in
	71	the manner of RFC822 headers.
	72	.PP
	73	There is a special case to be aware of: if a section doesn't specify a
	74	value for the key
	75	.B name
	76	then the section's own name is used as a default.
	77	.PP
	78	The following substitutions are made in the body of a value.
	79	.hP \*o
	80	An occurrence of
	81	.BI $( key )
	82	is replaced by the value assigned to the given
	83	.IR key .
	84	.hP \*o
	85	An occurrence of
ef7d7afb	86	.BI $ flags [ host ]
6005ef9b MW	87	is replaced by the IP address of the named
	88	.IR host .
	89	Note that
	90	.I host
	91	may itself contain
	92	.BI $( key )
ef7d7afb MW	93	substitutions. The
	94	.I flags
	95	consist of zero or more of the following characters:
cc72e4b3 MW	96	.RB ` 4 '
	97	looks up the
	98	.IR host 's
	99	IPv4 address(es);
97567475 MW	100	.RB ` 6 '
	101	looks up the
	102	.IR host 's
	103	IPv6 address(es);
	104	and
ef7d7afb MW	105	.RB ` * '
ef7d7afb MW	106	returns all of the found addresses, separated by spaces, rather than
97567475 MW	107	just the first one. If neither address family is requested, then
97567475 MW	108	.RB ` 46 '
bf495093 MW	109	is assumed. IPv6 address lookup of names, rather than address literals,
	110	depends on the external
	111	.BR adnshost (1)
	112	program; if it is not present then only IPv4 lookups will be performed.
6005ef9b MW	113	.PP
	114	There is a simple concept of
	115	.I inheritance
	116	for sections. If a section contains an assignment
	117	.IP
833bdc38	118	.BI "@inherit = " parent
bd3db76c MW	119	.RB [[,]
	120	.I parent
	121	\&...]
6005ef9b MW	122	.PP
6005ef9b MW	123	then any lookups which can't be satisfied in that section will be
bd3db76c	124	satisfied instead from its
6005ef9b	125	.I parent
bd3db76c MW	126	sections (and, if necessary, their parents in turn, and so on).
	127	.PP
	128	.hP \*o
	129	If a value can be found for a key via multiple parents then all of them
	130	must report the
	131	.I same
	132	value. This restriction may be relaxed somewhat, if it turns out that a
	133	more flexible notion of multiple inheritance is useful.
	134	.hP \*o
	135	It's not allowed for a section to inherit, possibly indirectly, from
	136	itself. Currently errors of this kind are only diagnosed when a cycle
	137	is encountered while looking up a key and none of the sections on the
	138	path from the original section up to and round the cycle define a value
	139	for it. Future versions of this program might be more picky.
	140	.PP
	141	Note that
6005ef9b MW	142	.BI $( key )
6005ef9b MW	143	substitutions in the resulting value will be satisfied from the original
bd3db76c	144	section (though falling back to scanning parent sections). For
6005ef9b MW	145	example, given the sections
	146	.VS
	147	[parent]
f08fe72e	148	detail = in $(name)
6005ef9b	149	blurb = expand $(detail)
f08fe72e MW	150
	151	[child]
	152	@inherit = parent
2273401c	153	.VE
f08fe72e MW	154	the key
	155	.B blurb
	156	takes the value
	157	.RB ` "expand in parent" '
	158	in section
	159	.BR parent ,
	160	and
	161	.RB ` "expand in child" '
	162	in section
	163	.BR child .
	164	.PP
6005ef9b	165	Apart from its effect on lookups, as just described, the
833bdc38	166	.B @inherit
6005ef9b MW	167	key is entirely ignored. In particular, it is never written to the
6005ef9b MW	168	database.
d64ce4ae	169	.
6005ef9b MW	170	.SS "Standard keys and their meanings"
	171	The following keys have meanings to programs in the TrIPE suite. Other
	172	keys may be used by separately distributed extensions or for local use.
	173	The descriptions given are summaries only; see the references for
	174	details.
	175	.TP
	176	.B auto
	177	If true, include the peer in the
	178	.B %AUTO
	179	record. Used by
a62f8e8a MW	180	.BR connect (8)
a62f8e8a MW	181	and
6005ef9b MW	182	.BR tripe-newpeers (8);
	183	described below.
	184	.TP
a62f8e8a MW	185	.B connect
a62f8e8a MW	186	Shell command for initiating connection to this peer. Used by
d64ce4ae	187	.BR connect (8).
a62f8e8a MW	188	.TP
a62f8e8a MW	189	.B cork
6411163d	190	Don't initiate immediate key exchange. Used by
a62f8e8a MW	191	.BR connect (8).
a62f8e8a MW	192	.TP
d3731285 MW	193	.B disconnect
d3731285 MW	194	Shell command for closing down connection to this peer. Used by
d64ce4ae	195	.BR connect (8).
d3731285	196	.TP
067aa5f0 MW	197	.B ephemeral
	198	Mark the peer as ephemeral: see
	199	.BR tripe-admin (5)
	200	for what this means. Used by
	201	.BR connect (8).
	202	.TP
a62f8e8a MW	203	.B every
a62f8e8a MW	204	Interval for checking that the peer is still alive and well. Used by
d64ce4ae	205	.BR connect (8).
a62f8e8a MW	206	.TP
	207	.B ifdown
	208	Script to bring down tunnel interface connected to the peer. Used by
d64ce4ae	209	.BR connect (8).
a62f8e8a MW	210	.TP
	211	.B ifname
	212	Interface name to set for the tunnel interface to the peer. Used by
	213	.BR tripe-ifup (8).
	214	.TP
	215	.B ifup
	216	Script to bring up tunnel interface connected to the peer. Used by
d64ce4ae	217	.BR connect (8).
a62f8e8a MW	218	.TP
	219	.B ifupextra
	220	Script containing additional interface setup. Used by
	221	.BR tripe-ifup (8).
	222	.TP
	223	.B laddr
	224	Local address for the tunnel interface to the peer. Used by
	225	.BR tripe-ifup (8).
	226	.TP
	227	.B keepalive
	228	Interval for sending keepalive pings. Used by
	229	.BR connect (8).
	230	.TP
48b84569 MW	231	.B key
	232	Key tag to use to authenticate the peer. Used by
	233	.BR connect (8).
	234	.TP
8362ac1c MW	235	.B knock
	236	Knock string to send when establishing a dynamic connection. Used by
	237	.BR connect (8).
	238	.TP
6411163d MW	239	.B mobile
	240	Peer's IP address is highly volatile. Used by
	241	.BR connect (8).
	242	.TP
a62f8e8a MW	243	.B mtu
	244	Maximum transmission unit for the tunnel interface. Used by
	245	.BR tripe-ifup (8).
	246	.TP
	247	.B nets
	248	Networks to be routed over the tunnel interface. Used by
	249	.BR tripe-ifup (8).
	250	.TP
	251	.B peer
	252	Network address for this peer, or
	253	.BR PASSIVE .
	254	Used by
	255	.BR connect (8).
	256	.TP
fe2a5dcf MW	257	.B priv
fe2a5dcf MW	258	Tag of the private key to use when communicating with the peer.
d64ce4ae MW	259	Used by
d64ce4ae MW	260	.BR connect (8).
fe2a5dcf	261	.TP
a62f8e8a MW	262	.B raddr
	263	Remote address for the tunnel interface to the peer. Used by
	264	.BR tripe-ifup (8).
	265	.TP
	266	.B retries
	267	Number of failed ping attempts before attempting reconnection. Used by
d64ce4ae	268	.BR connect (8).
a62f8e8a MW	269	.TP
	270	.B timeout
	271	Timeout for ping probes. Used by
d64ce4ae	272	.BR connect (8).
a62f8e8a MW	273	.TP
	274	.B tunnel
	275	Tunnel driver to use when adding the peer. Used by
	276	.BR connect (8)).
	277	.TP
6005ef9b MW	278	.B user
	279	Peer will make active connection as
	280	.IR user .
	281	Used by
a62f8e8a MW	282	.BR connect (8)
a62f8e8a MW	283	and
6005ef9b MW	284	.BR tripe-newpeers (8);
6005ef9b MW	285	described below.
d64ce4ae	286	.
6005ef9b MW	287	.SS "Conversion"
	288	This section describes how the textual
	289	.B peers.in
	290	file is converted into the
	291	.BR peers.cdb (5)
	292	database.
	293	.PP
	294	The handling of each section depends on its name.
	295	.hP \*o
	296	Sections whose names have the form
	297	.BI @ whatever
	298	are ignored (though their contents may be relevant if the section is
	299	named in another section's
833bdc38	300	.B @inherit
6005ef9b MW	301	key).
	302	.hP \*o
	303	Sections whose names have the form
	304	.BI $ whatever
	305	are written to local-type database records with the same name. The keys
	306	and values defined in the section (and its parent section, if it
	307	contains an
833bdc38	308	.B @inherit
6005ef9b MW	309	key) are stored in the record using
	310	.B form-urlencoding
	311	as defined in RFC1822, except that the key-value pairs are separated by
	312	semicolons
	313	.RB ` ; '
	314	rather than ampersands
	315	.RB ` & '.
6c2ee518 MW	316	Keys whose names begin with
	317	.RB ` @ '
	318	are not written to the database.
6005ef9b MW	319	.hP \*o
	320	Other sections are written to peer-type database records, named
	321	.BI P name \fR,
	322	in exactly the same way as for local-type records. However, two special
	323	actions are also taken.
	324	.IP
	325	Firstly, if there is a key
	326	.B auto
	327	in the section (or in its parent, etc.), and the value is
	328	.BR y ,
3c0f1c94	329	.BR yes ,
6005ef9b MW	330	.BR t ,
	331	.BR true ,
	332	.BR 1 ,
	333	or
	334	.BR on ,
	335	then the section's name is added in the special
	336	.B %AUTO
	337	record.
	338	.IP
	339	Secondly, if there is a key
	340	.B user
	341	in the section (or in its parent, etc.), then a user record
	342	.BI U user
	343	is created whose contents is the section name.
	344	.
	345	.\"--------------------------------------------------------------------------
	346	.SH "SEE ALSO"
	347	.
	348	.BR cdb (5),
	349	.BR tripe (8).
	350	.PP
	351	.BR tripe-newpeers (8),
	352	.BR peers.cdb (5),
a62f8e8a	353	.BR connect (8),
6005ef9b MW	354	.BR tripe-ifup (8).
	355	.
	356	.\"--------------------------------------------------------------------------
	357	.SH "AUTHOR"
	358	.
	359	Mark Wooding, <mdw@distorted.org.uk>
	360	.
	361	.\"----- That's all, folks --------------------------------------------------