chiark / gitweb /
Merge branch 'mdw/backoff'
[tripe] / svc / conntrack.8.in
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 tags
105 .B down
106 and
107 .BI down/ anything
108 are special and mean that no peer from the group should be active.  This
109 is useful for detecting a `home' network, where a VPN is unnecessary
110 (or, worse, break routing completely).
111 .PP
112 The notion of `current IP address' is somewhat vague.  The
113 .B conntrack
114 service calculates it as the source address that the host would put on
115 an IP packet sent to an arbitrarily chosen remote address.  The default
116 remote address is 1.2.3.4 (which is unlikely ever to be assigned); this
117 should determine an IP address on the network interface closest to the
118 default gateway.  You can influence this process in two ways.  Firstly,
119 you can change the default remote address used by adding a line
120 .IP
121 .B "test-addr ="
122 .I remote-addr
123 .PP
124 before the first peer group section.  Secondly, you can specify a
125 particular
126 .I remote-addr
127 to use when checking whether a particular peer is applicable.
128 .PP
129 The peer definitions can be in any order.  They are checked
130 most-specific first, and searching stops as soon as a match is found.
131 Therefore a default definition can be added as
132 .IP
133 .I tag
134 .B =
135 .B 0/0
136 .PP
137 without fear of overriding any more specific definitions.  For avoidance
138 of doubt, one peer definition is
139 .I more specific
140 than another if either the former has a specified
141 .I remote-addr
142 and the latter has not, or the former is wholly contained within the
143 latter.  (Overlapping definitions are not recommended, and will be
144 processed in an arbitrary order.)
145 .PP
146 Peers are connected using the
147 .BR connect (8)
148 service:
149 .IP
150 .B SVCSUBMIT connect active
151 .I peer
152 .SS "Command line"
153 In addition to the standard options described in
154 .BR tripe-service (7),
155 the following command-line options are recognized.
156 .TP
157 .BI "\-f, \-\-config=" file
158 Use
159 .I file
160 as the configuration file.  In the absence of this option, the
161 file named
162 .B conntrack.conf
163 in the current working directory is used instead.
164 .
165 .\"--------------------------------------------------------------------------
166 .SH "SERVICE COMMAND REFERENCE"
167 .
168 .\"* 10 Service commands
169 The commands provided by the service are as follows.
170 .SP
171 .BI "up " reason\fR...
172 Informs the service that the network connection has been established:
173 peer groups should be connected.  The
174 .I reason
175 is quoted in the status notification.
176 .SP
177 .BI "down " reason\fR...
178 Informs the service that the network connection has been lost:
179 peer groups should be disconnected.  The
180 .I reason
181 is quoted in the status notification.
182 .
183 .\"--------------------------------------------------------------------------
184 .SH "NOTIFICATIONS"
185 .
186 .\"* 30 Notification broadcasts (NOTE codes)
187 All notifications issued by
188 .B conntrack
189 begin with the tokens
190 .BR "USER conntrack" .
191 .SP
192 .BI "USER conntrack dbus-connection " status
193 The service's connection to D-Bus has changed state.  The
194 .I status
195 is one of the following.
196 .RS
197 .TP
198 .B startup
199 Initially trying to connect.
200 .TP
201 .B connected
202 Successfully established a connection to the bus.
203 .TP
204 .B lost
205 A connection has been lost.
206 .TP
207 .BI state= label
208 The service's internal state machine is confused.
209 .SP
210 .BI "USER conntrack " up \fR| down " " reason\fR...
211 The network connection has apparently gone up or down, and
212 .B conntrack
213 is about to kill and/or connect peers accordingly.  The
214 .I reason
215 is one of the following.
216 .RS
217 .TP
218 .B "nm initially-connected"
219 NetworkManager was detected on startup, and has an active network
220 connection.
221 .TP
222 .B "nm initially-disconnected"
223 NetworkManager was detected on startup, and has no active network
224 connection.
225 .TP
226 .B "nm connected"
227 NetworkManager has acquired an active network connection.
228 .TP
229 .B "nm disconnected"
230 NetworkManager has lost its active network connection.
231 .TP
232 .B "nm default-connection-change"
233 NetworkManager has changed its default route.
234 .TP
235 .BI "icd initially-connected " iap
236 Maemo ICd was detected on startup, and has an active network connection
237 identified by
238 .IR iap .
239 .TP
240 .B "icd initially-disconnected"
241 Maemo ICd was detected on startup, and has no active network connection.
242 .TP
243 .BI "icd connected " iap
244 Maemo ICd has acquired an active network connection, identified by
245 .IR iap .
246 .TP
247 .B "icd idle"
248 Maemo ICd has lost its active network connection.
249 .TP
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.
263 .RE
264 .
265 .\"--------------------------------------------------------------------------
266 .SH "WARNINGS"
267 .
268 .\"* 40 Warning broadcasts (WARN codes)
269 All warnings issued by
270 .B conntrack
271 begin with the tokens
272 .BR "USER conntrack" .
273 .SP
274 .BI "USER conntrack config-file-error " exception " " error-text
275 The configuration file is invalid.  The
276 .I exception
277 token names a Python exception; the
278 .I error-text
279 describes the problem encountered, though it may not be very useful.
280 .SP
281 .BI "USER conntrack connect-failed " peer " " tokens\fR...
282 An attempt to connect the named
283 .I peer
284 failed; the error message is given by the
285 .IR tokens .
286 .
287 .\"--------------------------------------------------------------------------
288 .SH "SUMMARY"
289 .
290 .\"= summary
291 .
292 .\"--------------------------------------------------------------------------
293 .SH "SEE ALSO"
294 .
295 .BR tripe-service (7),
296 .BR peers.in (5),
297 .BR watch (8),
298 .BR tripe (8).
299 .
300 .\"--------------------------------------------------------------------------
301 .SH "AUTHOR"
302 .
303 Mark Wooding, <mdw@distorted.org.uk>
304 .
305 .\"----- That's all, folks --------------------------------------------------