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:
89 This means that the peer
91 should be selected if the host's current IP address is within the
93 .IB network / mask \fR.
96 is an IP address in dotted-quad form, and
98 is a netmask, either in dotted-quad form, or as a number of 1-bits.
99 Only one peer in each group may be connected at any given time; if a
100 change is needed, any existing peer in the group is killed before
101 connecting the new one. If no match is found in a particular group,
102 then no peers in the group are connected. Strange and unhelpful things
103 will happen if you put the same peer in several different groups.
109 are special and mean that no peer from the group should be active. This
110 is useful for detecting a `home' network, where a VPN is unnecessary
111 (or, worse, break routing completely).
113 The notion of `current IP address' is somewhat vague. The
115 service calculates it as the source address that the host would put on
116 an IP packet sent to an arbitrarily chosen remote address. The default
117 remote address is 1.2.3.4 (which is unlikely ever to be assigned); this
118 should determine an IP address on the network interface closest to the
119 default gateway. You can influence this process in two ways. Firstly,
120 you can change the default remote address used by adding a line
125 before the first peer group section. Secondly, you can specify a
128 to use when checking whether a particular peer is applicable.
130 The peer definitions in each group are checked in the order given, and
131 searching stops as soon as a match is found.
133 Peers are connected using the
137 .B SVCSUBMIT connect active
140 In addition to the standard options described in
141 .BR tripe-service (7),
142 the following command-line options are recognized.
144 .BI "\-f, \-\-config=" file
147 as the configuration file. In the absence of this option, the
150 in the current working directory is used instead.
152 .\"--------------------------------------------------------------------------
153 .SH "SERVICE COMMAND REFERENCE"
155 .\"* 10 Service commands
156 The commands provided by the service are as follows.
158 .BI "up " reason\fR...
159 Informs the service that the network connection has been established:
160 peer groups should be connected. The
162 is quoted in the status notification.
164 .BI "down " reason\fR...
165 Informs the service that the network connection has been lost:
166 peer groups should be disconnected. The
168 is quoted in the status notification.
170 .\"--------------------------------------------------------------------------
173 .\"* 30 Notification broadcasts (NOTE codes)
174 All notifications issued by
176 begin with the tokens
177 .BR "USER conntrack" .
179 .BI "USER conntrack dbus-connection " status
180 The service's connection to D-Bus has changed state. The
182 is one of the following.
186 Initially trying to connect.
189 Successfully established a connection to the bus.
192 A connection has been lost.
195 The service's internal state machine is confused.
198 .BI "USER conntrack " up \fR| down " " group = peer\fR... " " reason\fR...
199 The network connection has apparently gone up or down, and
201 is about to kill and/or connect peers accordingly: for each group, the
202 selected peer is listed; if a group is not listed, then either the group
203 is to be brought down, or no matching peer was found. The
205 is one of the following.
208 .BI "connman initially-" state
209 ConnMan was detected on startup, and is in the given
214 ConnMan has transitioned to
216 The possible states are:
218 (the network is turned off by user request);
220 (no network interfaces are active);
222 (an interface is up but not fully configured); and
224 (an interface is up and configured).
226 .BI "icd connected " iap
227 Maemo ICd has acquired an active network connection, identified by
231 Maemo ICd has lost its active network connection.
233 .BI "icd initially-connected " iap
234 Maemo ICd was detected on startup, and has an active network connection
238 .B "icd initially-disconnected"
239 Maemo ICd was detected on startup, and has no active network connection.
242 A change was detected during
244 periodic status check. This usually means that the network connection
245 was reconfigured manually without informing
248 .BI "manual " reason\fR...
249 The connection status was changed manually, using the
256 NetworkManager has acquired an active network connection.
258 .B "nm default-connection-change"
259 NetworkManager has changed its default route.
262 NetworkManager has lost its active network connection.
264 .B "nm initially-connected"
265 NetworkManager was detected on startup, and has an active network
268 .B "nm initially-disconnected"
269 NetworkManager was detected on startup, and has no active network
273 .\"--------------------------------------------------------------------------
276 .\"* 40 Warning broadcasts (WARN codes)
277 All warnings issued by
279 begin with the tokens
280 .BR "USER conntrack" .
282 .BI "USER conntrack config-file-error " exception " " error-text
283 The configuration file is invalid. The
285 token names a Python exception; the
287 describes the problem encountered, though it may not be very useful.
289 .BI "USER conntrack connect-failed " peer " " tokens\fR...
290 An attempt to connect the named
292 failed; the error message is given by the
295 .\"--------------------------------------------------------------------------
300 .\"--------------------------------------------------------------------------
303 .BR tripe-service (7),
308 .\"--------------------------------------------------------------------------
311 Mark Wooding, <mdw@distorted.org.uk>
313 .\"----- That's all, folks --------------------------------------------------