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