[tripe] / svc / conntrack.8.in

.\" -*-nroff-*-
.\".
.\" Manual for the conntrack service
.\"
.\" (c) 2010 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 conntrack 8tripe "8 January 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
.
.\"--------------------------------------------------------------------------
.SH "NAME"
.
conntrack \- tripe service to start/stop peers depending on external connectivity
.
.\"--------------------------------------------------------------------------
.SH "SYNOPSIS"
.
.B conntrack
.RB [ \-a
.IR socket ]
.RB [ \-d
.IR dir ]
.RB [ \-f
.IR file ]
.br
\&	\c
.RB [ \-\-daemon ]
.RB [ \-\-debug ]
.RB [ \-\-startup ]
.
.\"--------------------------------------------------------------------------
.SH "DESCRIPTION"
.
The
.B conntrack
service watches D-Bus network management services like
.BR NetworkManager (8)
and Nokia's
.BR ICd ,
bringing peers up and down automatically.  It's designed to be useful on
a mobile device, such as a laptop; I expect servers to stay where
they're put and be configured statically.
.SS "Configuration"
The
.B conntrack
service reads a configuration file, by default
.BR conntrack.conf ,
explaining which peers to bring up under which circumstances.  The
configuration file is automatically re-read if it's changed.
.PP
The
configuration is split into sections, each describing a
.IR "peer group" . 
A section begins with the peer group name in square brackets:
.IP
.BI [ group ]
.PP
The group name is entirely arbitrary, and affects nothing else.  This is
followed by peer definitions, each of which looks like this:
.IP
.I tag
.B =
.RI [ remote-addr ]
.IB network / mask
.PP
This means that the peer
.I tag
should be selected if the host's current IP address is within the
network indicated by
.IB network / mask \fR.  
Here,
.I network
is an IP address in dotted-quad form, and
.I mask
is a netmask, either in dotted-quad form, or as a number of 1-bits.
Only one peer in each group may be connected at any given time; if a
change is needed, any existing peer in the group is killed before
connecting the new one.  If no match is found in a particular group,
then no peers in the group are connected.  Strange and unhelpful things
will happen if you put the same peer in several different groups.
.PP
The tags
.B down
and
.BI down/ anything
are special and mean that no peer from the group should be active.  This
is useful for detecting a `home' network, where a VPN is unnecessary
(or, worse, break routing completely).
.PP
The notion of `current IP address' is somewhat vague.  The
.B conntrack
service calculates it as the source address that the host would put on
an IP packet sent to an arbitrarily chosen remote address.  The default
remote address is 1.2.3.4 (which is unlikely ever to be assigned); this
should determine an IP address on the network interface closest to the
default gateway.  You can influence this process in two ways.  Firstly,
you can change the default remote address used by adding a line
.IP
.B "test-addr ="
.I remote-addr
.PP
before the first peer group section.  Secondly, you can specify a
particular
.I remote-addr
to use when checking whether a particular peer is applicable.
.PP
The peer definitions can be in any order.  They are checked
most-specific first, and searching stops as soon as a match is found.
Therefore a default definition can be added as
.IP
.I tag
.B =
.B 0/0
.PP
without fear of overriding any more specific definitions.  For avoidance
of doubt, one peer definition is
.I more specific
than another if either the former has a specified
.I remote-addr
and the latter has not, or the former is wholly contained within the
latter.  (Overlapping definitions are not recommended, and will be
processed in an arbitrary order.)
.PP
Peers are connected using the
.BR connect (8)
service:
.IP
.B SVCSUBMIT connect active
.I peer
.SS "Command line"
In addition to the standard options described in
.BR tripe-service (7),
the following command-line options are recognized.
.TP
.BI "\-f, \-\-config=" file
Use
.I file
as the configuration file.  In the absence of this option, the
file named
.B conntrack.conf
in the current working directory is used instead.
.
.\"--------------------------------------------------------------------------
.SH "SERVICE COMMAND REFERENCE"
.
.\"* 10 Service commands
The commands provided by the service are as follows.
.SP
.BI "up " reason\fR...
Informs the service that the network connection has been established:
peer groups should be connected.  The
.I reason
is quoted in the status notification.
.SP
.BI "down " reason\fR...
Informs the service that the network connection has been lost:
peer groups should be disconnected.  The
.I reason
is quoted in the status notification.
.
.\"--------------------------------------------------------------------------
.SH "NOTIFICATIONS"
.
.\"* 30 Notification broadcasts (NOTE codes)
All notifications issued by
.B conntrack
begin with the tokens
.BR "USER conntrack" .
.SP
.BI "USER conntrack dbus-connection " status
The service's connection to D-Bus has changed state.  The
.I status
is one of the following.
.RS
.TP
.B startup
Initially trying to connect.
.TP
.B connected
Successfully established a connection to the bus.
.TP
.B lost
A connection has been lost.
.TP
.BI state= label
The service's internal state machine is confused.
.RE
.SP
.BI "USER conntrack " up \fR| down " " group = peer\fR... " " reason\fR...
The network connection has apparently gone up or down, and
.B conntrack
is about to kill and/or connect peers accordingly: for each group, the
selected peer is listed; if a group is not listed, then either the group
is to be brought down, or no matching peer was found.  The
.I reason
is one of the following.
.RS
.TP
.B "nm initially-connected"
NetworkManager was detected on startup, and has an active network
connection.
.TP
.B "nm initially-disconnected"
NetworkManager was detected on startup, and has no active network
connection.
.TP
.B "nm connected"
NetworkManager has acquired an active network connection.
.TP
.B "nm disconnected"
NetworkManager has lost its active network connection.
.TP
.B "nm default-connection-change"
NetworkManager has changed its default route.
.TP
.BI "icd initially-connected " iap
Maemo ICd was detected on startup, and has an active network connection
identified by
.IR iap .
.TP
.B "icd initially-disconnected"
Maemo ICd was detected on startup, and has no active network connection.
.TP
.BI "icd connected " iap
Maemo ICd has acquired an active network connection, identified by
.IR iap .
.TP
.B "icd idle"
Maemo ICd has lost its active network connection.
.TP
.B interval-timer
A change was detected during
.BR conntrack 's
periodic status check.  This usually means that the network connection
was reconfigured manually without informing
.BR conntrack .
.TP
.BI "manual " reason\fR...
The connection status was changed manually, using the
.B up
or
.B down
service command.
.RE
.
.\"--------------------------------------------------------------------------
.SH "WARNINGS"
.
.\"* 40 Warning broadcasts (WARN codes)
All warnings issued by
.B conntrack
begin with the tokens
.BR "USER conntrack" .
.SP
.BI "USER conntrack config-file-error " exception " " error-text
The configuration file is invalid.  The
.I exception
token names a Python exception; the
.I error-text
describes the problem encountered, though it may not be very useful.
.SP
.BI "USER conntrack connect-failed " peer " " tokens\fR...
An attempt to connect the named
.I peer
failed; the error message is given by the
.IR tokens .
.
.\"--------------------------------------------------------------------------
.SH "SUMMARY"
.
.\"= summary
.
.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
.
.BR tripe-service (7),
.BR peers.in (5),
.BR watch (8),
.BR tripe (8).
.
.\"--------------------------------------------------------------------------
.SH "AUTHOR"
.
Mark Wooding, <mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------
Commit	Line	Data
2ec90437 MW	1	.\" --nroff--
	2	.\".
	3	.\" Manual for the conntrack service
	4	.\"
	5	.\" (c) 2010 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.
2ec90437	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.
2ec90437 MW	21	.\"
2ec90437 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/>.
2ec90437 MW	24	.
	25	.\"--------------------------------------------------------------------------
	26	.so ../common/defs.man \"@@@PRE@@@
	27	.
	28	.\"--------------------------------------------------------------------------
0647ba7c	29	.TH conntrack 8tripe "8 January 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
2ec90437 MW	30	.
	31	.\"--------------------------------------------------------------------------
	32	.SH "NAME"
	33	.
	34	conntrack \- tripe service to start/stop peers depending on external connectivity
	35	.
	36	.\"--------------------------------------------------------------------------
	37	.SH "SYNOPSIS"
	38	.
	39	.B conntrack
	40	.RB [ \-a
	41	.IR socket ]
	42	.RB [ \-d
	43	.IR dir ]
	44	.RB [ \-f
	45	.IR file ]
	46	.br
	47	\& \c
	48	.RB [ \-\-daemon ]
	49	.RB [ \-\-debug ]
	50	.RB [ \-\-startup ]
	51	.
	52	.\"--------------------------------------------------------------------------
	53	.SH "DESCRIPTION"
	54	.
	55	The
	56	.B conntrack
	57	service watches D-Bus network management services like
	58	.BR NetworkManager (8)
	59	and Nokia's
	60	.BR ICd ,
	61	bringing peers up and down automatically. It's designed to be useful on
	62	a mobile device, such as a laptop; I expect servers to stay where
	63	they're put and be configured statically.
	64	.SS "Configuration"
	65	The
	66	.B conntrack
	67	service reads a configuration file, by default
	68	.BR conntrack.conf ,
	69	explaining which peers to bring up under which circumstances. The
	70	configuration file is automatically re-read if it's changed.
	71	.PP
	72	The
	73	configuration is split into sections, each describing a
	74	.IR "peer group" .
	75	A section begins with the peer group name in square brackets:
	76	.IP
	77	.BI [ group ]
	78	.PP
	79	The group name is entirely arbitrary, and affects nothing else. This is
	80	followed by peer definitions, each of which looks like this:
	81	.IP
	82	.I tag
	83	.B =
	84	.RI [ remote-addr ]
	85	.IB network / mask
	86	.PP
	87	This means that the peer
	88	.I tag
	89	should be selected if the host's current IP address is within the
	90	network indicated by
	91	.IB network / mask \fR.
	92	Here,
	93	.I network
94	is an IP address in dotted-quad form, and
95	.I mask
96	is a netmask, either in dotted-quad form, or as a number of 1-bits.
97	Only one peer in each group may be connected at any given time; if a
98	change is needed, any existing peer in the group is killed before
99	connecting the new one. If no match is found in a particular group,
100	then no peers in the group are connected. Strange and unhelpful things
101	will happen if you put the same peer in several different groups.
102	.PP
f2bdb96e MW	103	The tags
	104	.B down
	105	and
	106	.BI down/ anything
	107	are special and mean that no peer from the group should be active. This
	108	is useful for detecting a `home' network, where a VPN is unnecessary
	109	(or, worse, break routing completely).
	110	.PP
2ec90437 MW	111	The notion of `current IP address' is somewhat vague. The
	112	.B conntrack
	113	service calculates it as the source address that the host would put on
	114	an IP packet sent to an arbitrarily chosen remote address. The default
	115	remote address is 1.2.3.4 (which is unlikely ever to be assigned); this
	116	should determine an IP address on the network interface closest to the
	117	default gateway. You can influence this process in two ways. Firstly,
	118	you can change the default remote address used by adding a line
	119	.IP
	120	.B "test-addr ="
	121	.I remote-addr
	122	.PP
	123	before the first peer group section. Secondly, you can specify a
	124	particular
	125	.I remote-addr
	126	to use when checking whether a particular peer is applicable.
	127	.PP
	128	The peer definitions can be in any order. They are checked
	129	most-specific first, and searching stops as soon as a match is found.
	130	Therefore a default definition can be added as
	131	.IP
	132	.I tag
	133	.B =
	134	.B 0/0
	135	.PP
	136	without fear of overriding any more specific definitions. For avoidance
	137	of doubt, one peer definition is
	138	.I more specific
	139	than another if either the former has a specified
	140	.I remote-addr
	141	and the latter has not, or the former is wholly contained within the
	142	latter. (Overlapping definitions are not recommended, and will be
	143	processed in an arbitrary order.)
	144	.PP
	145	Peers are connected using the
	146	.BR connect (8)
	147	service:
	148	.IP
	149	.B SVCSUBMIT connect active
	150	.I peer
	151	.SS "Command line"
	152	In addition to the standard options described in
	153	.BR tripe-service (7),
	154	the following command-line options are recognized.
	155	.TP
	156	.BI "\-f, \-\-config=" file
	157	Use
	158	.I file
	159	as the configuration file. In the absence of this option, the
	160	file named
	161	.B conntrack.conf
	162	in the current working directory is used instead.
	163	.
	164	.\"--------------------------------------------------------------------------
	165	.SH "SERVICE COMMAND REFERENCE"
	166	.
	167	.\"* 10 Service commands
	168	The commands provided by the service are as follows.
	169	.SP
	170	.BI "up " reason\fR...
	171	Informs the service that the network connection has been established:
	172	peer groups should be connected. The
	173	.I reason
	174	is quoted in the status notification.
175	.SP
176	.BI "down " reason\fR...
177	Informs the service that the network connection has been lost:
178	peer groups should be disconnected. The
179	.I reason
180	is quoted in the status notification.
181	.
182	.\"--------------------------------------------------------------------------
183	.SH "NOTIFICATIONS"
184	.
185	.\"* 30 Notification broadcasts (NOTE codes)
186	All notifications issued by
187	.B conntrack
188	begin with the tokens
189	.BR "USER conntrack" .
190	.SP
75d9c6fd MW	191	.BI "USER conntrack dbus-connection " status
	192	The service's connection to D-Bus has changed state. The
	193	.I status
	194	is one of the following.
	195	.RS
	196	.TP
	197	.B startup
	198	Initially trying to connect.
	199	.TP
	200	.B connected
	201	Successfully established a connection to the bus.
	202	.TP
	203	.B lost
	204	A connection has been lost.
	205	.TP
	206	.BI state= label
	207	The service's internal state machine is confused.
56d0fa7e	208	.RE
75d9c6fd	209	.SP
2d4998c4	210	.BI "USER conntrack " up \fR\| down " " group = peer\fR... " " reason\fR...
2ec90437 MW	211	The network connection has apparently gone up or down, and
2ec90437 MW	212	.B conntrack
2d4998c4 MW	213	is about to kill and/or connect peers accordingly: for each group, the
	214	selected peer is listed; if a group is not listed, then either the group
	215	is to be brought down, or no matching peer was found. The
2ec90437 MW	216	.I reason
	217	is one of the following.
	218	.RS
	219	.TP
	220	.B "nm initially-connected"
	221	NetworkManager was detected on startup, and has an active network
	222	connection.
	223	.TP
	224	.B "nm initially-disconnected"
	225	NetworkManager was detected on startup, and has no active network
	226	connection.
	227	.TP
	228	.B "nm connected"
	229	NetworkManager has acquired an active network connection.
	230	.TP
	231	.B "nm disconnected"
	232	NetworkManager has lost its active network connection.
	233	.TP
	234	.B "nm default-connection-change"
	235	NetworkManager has changed its default route.
	236	.TP
	237	.BI "icd initially-connected " iap
	238	Maemo ICd was detected on startup, and has an active network connection
	239	identified by
	240	.IR iap .
	241	.TP
	242	.B "icd initially-disconnected"
	243	Maemo ICd was detected on startup, and has no active network connection.
	244	.TP
	245	.BI "icd connected " iap
	246	Maemo ICd has acquired an active network connection, identified by
	247	.IR iap .
	248	.TP
	249	.B "icd idle"
	250	Maemo ICd has lost its active network connection.
	251	.TP
	252	.B interval-timer
	253	A change was detected during
	254	.BR conntrack 's
	255	periodic status check. This usually means that the network connection
	256	was reconfigured manually without informing
	257	.BR conntrack .
	258	.TP
	259	.BI "manual " reason\fR...
	260	The connection status was changed manually, using the
	261	.B up
	262	or
	263	.B down
	264	service command.
	265	.RE
	266	.
	267	.\"--------------------------------------------------------------------------
	268	.SH "WARNINGS"
	269	.
	270	.\"* 40 Warning broadcasts (WARN codes)
	271	All warnings issued by
	272	.B conntrack
	273	begin with the tokens
	274	.BR "USER conntrack" .
	275	.SP
	276	.BI "USER conntrack config-file-error " exception " " error-text
	277	The configuration file is invalid. The
	278	.I exception
	279	token names a Python exception; the
280	.I error-text
281	describes the problem encountered, though it may not be very useful.
cf2e4ea6 MW	282	.SP
	283	.BI "USER conntrack connect-failed " peer " " tokens\fR...
	284	An attempt to connect the named
	285	.I peer
	286	failed; the error message is given by the
	287	.IR tokens .
2ec90437 MW	288	.
	289	.\"--------------------------------------------------------------------------
	290	.SH "SUMMARY"
	291	.
	292	.\"= summary
	293	.
	294	.\"--------------------------------------------------------------------------
	295	.SH "SEE ALSO"
	296	.
	297	.BR tripe-service (7),
	298	.BR peers.in (5),
	299	.BR watch (8),
	300	.BR tripe (8).
	301	.
	302	.\"--------------------------------------------------------------------------
	303	.SH "AUTHOR"
	304	.
	305	Mark Wooding, <mdw@distorted.org.uk>
	306	.
	307	.\"----- That's all, folks --------------------------------------------------