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 | .\" |
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 |
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 |
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" |
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 -------------------------------------------------- |