[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 2 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, write to the Free Software Foundation,
.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
.
.\"--------------------------------------------------------------------------
.so ../defs.man.in \"@@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH peers.in 5 "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 "@inherits = " parent
.PP
then any lookups which can't be satisfied in that section will be
satisfied instead from the
.I parent
section (and, if necessary, its parent in turn, and so on).  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
example, given the sections
.VS
[parent]
detail = in parent
blurb = expand $(detail)
.VE
Apart from its effect on lookups, as just described, the
.B @inherits
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 watch (8).
.TP
.B cork
Don't initiate immediate key exchange.  Used by
.BR connect (8).
.TP
.B every
Interval for checking that the peer is still alive and well.  Used by
.BR watch (8).
.TP
.B ifdown
Script to bring down tunnel interface connected to the peer.  Used by
.BR watch (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 watch (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 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.
.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 watch (8).
.TP
.B timeout
Timeout for ping probes.  Used by
.BR watch (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 @inherits
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 @inherits
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 ` & '.
The
.B @inherits
key-value pair is 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 watch (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	.\"
	12	.\" TrIPE is free software; you can redistribute it and/or modify
	13	.\" it under the terms of the GNU General Public License as published by
	14	.\" the Free Software Foundation; either version 2 of the License, or
	15	.\" (at your option) any later version.
	16	.\"
	17	.\" TrIPE is distributed in the hope that it will be useful,
	18	.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
	19	.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	20	.\" GNU General Public License for more details.
	21	.\"
	22	.\" You should have received a copy of the GNU General Public License
	23	.\" along with TrIPE; if not, write to the Free Software Foundation,
	24	.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
	25	.
	26	.\"--------------------------------------------------------------------------
	27	.so ../defs.man.in \"@@@PRE@@@
	28	.
	29	.\"--------------------------------------------------------------------------
	30	.TH peers.in 5 "27 March 2008" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
	31	.
	32	.\"--------------------------------------------------------------------------
	33	.SH "NAME"
	34	.
	35	peers.in \- source form for TrIPE peer database
	36	.
	37	.\"--------------------------------------------------------------------------
	38	.SH "DESCRIPTION"
	39	.
	40	The
	41	.B peers.in
	42	file is a plain text configuration file. It is read by
	43	.BR tripe-newpeers (8)
	44	in order to produce the
	45	.BR tripe.cdb (8)
	46	database used by services and other tools.
	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
86	.BI $[ host ]
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 )
93	substitutions.
94	.PP
95	There is a simple concept of
96	.I inheritance
97	for sections. If a section contains an assignment
98	.IP
99	.BI "@inherits = " parent
100	.PP
101	then any lookups which can't be satisfied in that section will be
102	satisfied instead from the
103	.I parent
104	section (and, if necessary, its parent in turn, and so on). Note that
105	.BI $( key )
106	substitutions in the resulting value will be satisfied from the original
107	section (though falling back to scanning the parent section). For
108	example, given the sections
109	.VS
110	[parent]
111	detail = in parent
112	blurb = expand $(detail)
2273401c	113	.VE
6005ef9b MW	114	Apart from its effect on lookups, as just described, the
	115	.B @inherits
	116	key is entirely ignored. In particular, it is never written to the
	117	database.
	118	.SS "Standard keys and their meanings"
	119	The following keys have meanings to programs in the TrIPE suite. Other
	120	keys may be used by separately distributed extensions or for local use.
	121	The descriptions given are summaries only; see the references for
	122	details.
	123	.TP
	124	.B auto
	125	If true, include the peer in the
	126	.B %AUTO
	127	record. Used by
a62f8e8a MW	128	.BR connect (8)
a62f8e8a MW	129	and
6005ef9b MW	130	.BR tripe-newpeers (8);
	131	described below.
	132	.TP
a62f8e8a MW	133	.B connect
	134	Shell command for initiating connection to this peer. Used by
	135	.BR watch (8).
	136	.TP
	137	.B cork
6411163d	138	Don't initiate immediate key exchange. Used by
a62f8e8a MW	139	.BR connect (8).
	140	.TP
	141	.B every
	142	Interval for checking that the peer is still alive and well. Used by
	143	.BR watch (8).
	144	.TP
	145	.B ifdown
	146	Script to bring down tunnel interface connected to the peer. Used by
	147	.BR watch (8).
	148	.TP
	149	.B ifname
	150	Interface name to set for the tunnel interface to the peer. Used by
	151	.BR tripe-ifup (8).
	152	.TP
	153	.B ifup
	154	Script to bring up tunnel interface connected to the peer. Used by
	155	.BR watch (8).
	156	.TP
	157	.B ifupextra
	158	Script containing additional interface setup. Used by
	159	.BR tripe-ifup (8).
	160	.TP
	161	.B laddr
	162	Local address for the tunnel interface to the peer. Used by
	163	.BR tripe-ifup (8).
	164	.TP
	165	.B keepalive
	166	Interval for sending keepalive pings. Used by
	167	.BR connect (8).
	168	.TP
48b84569 MW	169	.B key
	170	Key tag to use to authenticate the peer. Used by
	171	.BR connect (8).
	172	.TP
6411163d MW	173	.B mobile
	174	Peer's IP address is highly volatile. Used by
	175	.BR connect (8).
	176	.TP
a62f8e8a MW	177	.B mtu
	178	Maximum transmission unit for the tunnel interface. Used by
	179	.BR tripe-ifup (8).
	180	.TP
	181	.B nets
	182	Networks to be routed over the tunnel interface. Used by
	183	.BR tripe-ifup (8).
	184	.TP
	185	.B peer
	186	Network address for this peer, or
	187	.BR PASSIVE .
	188	Used by
	189	.BR connect (8).
	190	.TP
fe2a5dcf MW	191	.B priv
	192	Tag of the private key to use when communicating with the peer.
	193	.TP
a62f8e8a MW	194	.B raddr
	195	Remote address for the tunnel interface to the peer. Used by
	196	.BR tripe-ifup (8).
	197	.TP
	198	.B retries
	199	Number of failed ping attempts before attempting reconnection. Used by
	200	.BR watch (8).
	201	.TP
	202	.B timeout
	203	Timeout for ping probes. Used by
	204	.BR watch (8).
	205	.TP
	206	.B tunnel
	207	Tunnel driver to use when adding the peer. Used by
	208	.BR connect (8)).
	209	.TP
6005ef9b MW	210	.B user
	211	Peer will make active connection as
	212	.IR user .
	213	Used by
a62f8e8a MW	214	.BR connect (8)
a62f8e8a MW	215	and
6005ef9b MW	216	.BR tripe-newpeers (8);
	217	described below.
	218	.SS "Conversion"
	219	This section describes how the textual
	220	.B peers.in
	221	file is converted into the
	222	.BR peers.cdb (5)
	223	database.
	224	.PP
	225	The handling of each section depends on its name.
	226	.hP \*o
	227	Sections whose names have the form
	228	.BI @ whatever
	229	are ignored (though their contents may be relevant if the section is
	230	named in another section's
	231	.B @inherits
	232	key).
	233	.hP \*o
	234	Sections whose names have the form
	235	.BI $ whatever
	236	are written to local-type database records with the same name. The keys
	237	and values defined in the section (and its parent section, if it
	238	contains an
	239	.B @inherits
	240	key) are stored in the record using
	241	.B form-urlencoding
	242	as defined in RFC1822, except that the key-value pairs are separated by
	243	semicolons
	244	.RB ` ; '
	245	rather than ampersands
	246	.RB ` & '.
	247	The
	248	.B @inherits
	249	key-value pair is not written to the database.
	250	.hP \*o
	251	Other sections are written to peer-type database records, named
	252	.BI P name \fR,
	253	in exactly the same way as for local-type records. However, two special
	254	actions are also taken.
	255	.IP
	256	Firstly, if there is a key
	257	.B auto
	258	in the section (or in its parent, etc.), and the value is
	259	.BR y ,
	260	.BR yes .
	261	.BR t ,
	262	.BR true ,
	263	.BR 1 ,
	264	or
	265	.BR on ,
	266	then the section's name is added in the special
	267	.B %AUTO
	268	record.
	269	.IP
	270	Secondly, if there is a key
	271	.B user
	272	in the section (or in its parent, etc.), then a user record
	273	.BI U user
	274	is created whose contents is the section name.
	275	.
	276	.\"--------------------------------------------------------------------------
	277	.SH "SEE ALSO"
	278	.
	279	.BR cdb (5),
280	.BR tripe (8).
281	.PP
282	.BR tripe-newpeers (8),
283	.BR peers.cdb (5),
a62f8e8a MW	284	.BR connect (8),
a62f8e8a MW	285	.BR watch (8),
6005ef9b MW	286	.BR tripe-ifup (8).
	287	.
	288	.\"--------------------------------------------------------------------------
	289	.SH "AUTHOR"
	290	.
	291	Mark Wooding, <mdw@distorted.org.uk>
	292	.
	293	.\"----- That's all, folks --------------------------------------------------