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