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