3 .\" Manual for the conntrack service
5 .\" (c) 2010 Straylight/Edgeware
8 .\"----- Licensing notice ---------------------------------------------------
10 .\" This file is part of Trivial IP Encryption (TrIPE).
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.
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
22 .\" You should have received a copy of the GNU General Public License
23 .\" along with TrIPE. If not, see <https://www.gnu.org/licenses/>.
25 .\"--------------------------------------------------------------------------
26 .so ../common/defs.man \"@@@PRE@@@
28 .\"--------------------------------------------------------------------------
29 .TH conntrack 8tripe "8 January 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
31 .\"--------------------------------------------------------------------------
34 conntrack \- tripe service to start/stop peers depending on external connectivity
36 .\"--------------------------------------------------------------------------
52 .\"--------------------------------------------------------------------------
57 service watches D-Bus network management services like
58 .BR NetworkManager (8),
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.
69 service reads a configuration file, by default
71 explaining which peers to bring up under which circumstances. The
72 configuration file is automatically re-read if it's changed.
75 configuration is split into sections, each describing a
77 A section begins with the peer group name in square brackets:
81 The group name is entirely arbitrary, and affects nothing else. This is
82 followed by peer definitions, each of which looks like this:
90 This means that the peer
92 should be selected if the host's current IP address is within one of the
94 .IB network / mask \fR.
97 is an IPv4 or IPv6 address in dotted-quad form, and
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.
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).
115 The notion of `current IP address' is somewhat vague. The
117 service calculates it as the source address that the host would put on
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
130 before the first peer group section. Secondly, you can specify a
133 to use when checking whether a particular peer is applicable.
135 The peer definitions in each group are checked in the order given, and
136 searching stops as soon as a match is found. (In older versions of
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.)
142 Peers are connected using the
146 .B SVCSUBMIT connect active
149 In addition to the standard options described in
150 .BR tripe-service (7),
151 the following command-line options are recognized.
153 .BI "\-f, \-\-config=" file
156 as the configuration file. In the absence of this option, the
159 in the current working directory is used instead.
161 .\"--------------------------------------------------------------------------
162 .SH "SERVICE COMMAND REFERENCE"
164 .\"* 10 Service commands
165 The commands provided by the service are as follows.
167 .BI "up " reason\fR...
168 Informs the service that the network connection has been established:
169 peer groups should be connected. The
171 is quoted in the status notification.
173 .BI "down " reason\fR...
174 Informs the service that the network connection has been lost:
175 peer groups should be disconnected. The
177 is quoted in the status notification.
179 .\"--------------------------------------------------------------------------
182 .\"* 30 Notification broadcasts (NOTE codes)
183 All notifications issued by
185 begin with the tokens
186 .BR "USER conntrack" .
188 .BI "USER conntrack dbus-connection " status
189 The service's connection to D-Bus has changed state. The
191 is one of the following.
195 Initially trying to connect.
198 Successfully established a connection to the bus.
201 A connection has been lost.
204 The service's internal state machine is confused.
207 .BI "USER conntrack " up \fR| down " " group = peer\fR... " " reason\fR...
208 The network connection has apparently gone up or down, and
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
214 is one of the following.
217 .BI "connman initially-" state
218 ConnMan was detected on startup, and is in the given
223 ConnMan has transitioned to
225 The possible states are:
227 (the network is turned off by user request);
229 (no network interfaces are active);
231 (an interface is up but not fully configured); and
233 (an interface is up and configured).
235 .BI "icd connected " iap
236 Maemo ICd has acquired an active network connection, identified by
240 Maemo ICd has lost its active network connection.
242 .BI "icd initially-connected " iap
243 Maemo ICd was detected on startup, and has an active network connection
247 .B "icd initially-disconnected"
248 Maemo ICd was detected on startup, and has no active network connection.
251 A change was detected during
253 periodic status check. This usually means that the network connection
254 was reconfigured manually without informing
257 .BI "manual " reason\fR...
258 The connection status was changed manually, using the
265 NetworkManager has acquired an active network connection.
267 .B "nm default-connection-change"
268 NetworkManager has changed its default route.
271 NetworkManager has lost its active network connection.
273 .B "nm initially-connected"
274 NetworkManager was detected on startup, and has an active network
277 .B "nm initially-disconnected"
278 NetworkManager was detected on startup, and has no active network
282 .\"--------------------------------------------------------------------------
285 .\"* 40 Warning broadcasts (WARN codes)
286 All warnings issued by
288 begin with the tokens
289 .BR "USER conntrack" .
291 .BI "USER conntrack config-file-error " exception " " error-text
292 The configuration file is invalid. The
294 token names a Python exception; the
296 describes the problem encountered, though it may not be very useful.
298 .BI "USER conntrack connect-failed " peer " " tokens\fR...
299 An attempt to connect the named
301 failed; the error message is given by the
304 .\"--------------------------------------------------------------------------
309 .\"--------------------------------------------------------------------------
312 .BR tripe-service (7),
317 .\"--------------------------------------------------------------------------
320 Mark Wooding, <mdw@distorted.org.uk>
322 .\"----- That's all, folks --------------------------------------------------