.\" -*-nroff-*- .\". .\" Manual for the conntrack service .\" .\" (c) 2010 Straylight/Edgeware .\" . .\"----- Licensing notice --------------------------------------------------- .\" .\" This file is part of Trivial IP Encryption (TrIPE). .\" .\" TrIPE is free software; you can redistribute it and/or modify .\" it under the terms of the GNU General Public License as published by .\" the Free Software Foundation; either version 2 of the License, or .\" (at your option) any later version. .\" .\" TrIPE is distributed in the hope that it will be useful, .\" but WITHOUT ANY WARRANTY; without even the implied warranty of .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the .\" GNU General Public License for more details. .\" .\" You should have received a copy of the GNU General Public License .\" along with TrIPE; if not, write to the Free Software Foundation, .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. . .\"-------------------------------------------------------------------------- .so ../common/defs.man \"@@@PRE@@@ . .\"-------------------------------------------------------------------------- .TH connect 8 "8 January 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" . .\"-------------------------------------------------------------------------- .SH "NAME" . conntrack \- tripe service to start/stop peers depending on external connectivity . .\"-------------------------------------------------------------------------- .SH "SYNOPSIS" . .B conntrack .RB [ \-a .IR socket ] .RB [ \-d .IR dir ] .RB [ \-f .IR file ] .br \& \c .RB [ \-\-daemon ] .RB [ \-\-debug ] .RB [ \-\-startup ] . .\"-------------------------------------------------------------------------- .SH "DESCRIPTION" . The .B conntrack service watches D-Bus network management services like .BR NetworkManager (8) and Nokia's .BR ICd , bringing peers up and down automatically. It's designed to be useful on a mobile device, such as a laptop; I expect servers to stay where they're put and be configured statically. .SS "Configuration" The .B conntrack service reads a configuration file, by default .BR conntrack.conf , explaining which peers to bring up under which circumstances. The configuration file is automatically re-read if it's changed. .PP The configuration is split into sections, each describing a .IR "peer group" . A section begins with the peer group name in square brackets: .IP .BI [ group ] .PP The group name is entirely arbitrary, and affects nothing else. This is followed by peer definitions, each of which looks like this: .IP .I tag .B = .RI [ remote-addr ] .IB network / mask .PP This means that the peer .I tag should be selected if the host's current IP address is within the network indicated by .IB network / mask \fR. Here, .I network is an IP address in dotted-quad form, and .I mask is a netmask, either in dotted-quad form, or as a number of 1-bits. Only one peer in each group may be connected at any given time; if a change is needed, any existing peer in the group is killed before connecting the new one. If no match is found in a particular group, then no peers in the group are connected. Strange and unhelpful things will happen if you put the same peer in several different groups. .PP The tags .B down and .BI down/ anything are special and mean that no peer from the group should be active. This is useful for detecting a `home' network, where a VPN is unnecessary (or, worse, break routing completely). .PP The notion of `current IP address' is somewhat vague. The .B conntrack service calculates it as the source address that the host would put on an IP packet sent to an arbitrarily chosen remote address. The default remote address is 1.2.3.4 (which is unlikely ever to be assigned); this should determine an IP address on the network interface closest to the default gateway. You can influence this process in two ways. Firstly, you can change the default remote address used by adding a line .IP .B "test-addr =" .I remote-addr .PP before the first peer group section. Secondly, you can specify a particular .I remote-addr to use when checking whether a particular peer is applicable. .PP The peer definitions can be in any order. They are checked most-specific first, and searching stops as soon as a match is found. Therefore a default definition can be added as .IP .I tag .B = .B 0/0 .PP without fear of overriding any more specific definitions. For avoidance of doubt, one peer definition is .I more specific than another if either the former has a specified .I remote-addr and the latter has not, or the former is wholly contained within the latter. (Overlapping definitions are not recommended, and will be processed in an arbitrary order.) .PP Peers are connected using the .BR connect (8) service: .IP .B SVCSUBMIT connect active .I peer .SS "Command line" In addition to the standard options described in .BR tripe-service (7), the following command-line options are recognized. .TP .BI "\-f, \-\-config=" file Use .I file as the configuration file. In the absence of this option, the file named .B conntrack.conf in the current working directory is used instead. . .\"-------------------------------------------------------------------------- .SH "SERVICE COMMAND REFERENCE" . .\"* 10 Service commands The commands provided by the service are as follows. .SP .BI "up " reason\fR... Informs the service that the network connection has been established: peer groups should be connected. The .I reason is quoted in the status notification. .SP .BI "down " reason\fR... Informs the service that the network connection has been lost: peer groups should be disconnected. The .I reason is quoted in the status notification. . .\"-------------------------------------------------------------------------- .SH "NOTIFICATIONS" . .\"* 30 Notification broadcasts (NOTE codes) All notifications issued by .B conntrack begin with the tokens .BR "USER conntrack" . .SP .BI "USER conntrack dbus-connection " status The service's connection to D-Bus has changed state. The .I status is one of the following. .RS .TP .B startup Initially trying to connect. .TP .B connected Successfully established a connection to the bus. .TP .B lost A connection has been lost. .TP .BI state= label The service's internal state machine is confused. .SP .BI "USER conntrack " up \fR| down " " reason\fR... The network connection has apparently gone up or down, and .B conntrack is about to kill and/or connect peers accordingly. The .I reason is one of the following. .RS .TP .B "nm initially-connected" NetworkManager was detected on startup, and has an active network connection. .TP .B "nm initially-disconnected" NetworkManager was detected on startup, and has no active network connection. .TP .B "nm connected" NetworkManager has acquired an active network connection. .TP .B "nm disconnected" NetworkManager has lost its active network connection. .TP .B "nm default-connection-change" NetworkManager has changed its default route. .TP .BI "icd initially-connected " iap Maemo ICd was detected on startup, and has an active network connection identified by .IR iap . .TP .B "icd initially-disconnected" Maemo ICd was detected on startup, and has no active network connection. .TP .BI "icd connected " iap Maemo ICd has acquired an active network connection, identified by .IR iap . .TP .B "icd idle" Maemo ICd has lost its active network connection. .TP .B interval-timer A change was detected during .BR conntrack 's periodic status check. This usually means that the network connection was reconfigured manually without informing .BR conntrack . .TP .BI "manual " reason\fR... The connection status was changed manually, using the .B up or .B down service command. .RE . .\"-------------------------------------------------------------------------- .SH "WARNINGS" . .\"* 40 Warning broadcasts (WARN codes) All warnings issued by .B conntrack begin with the tokens .BR "USER conntrack" . .SP .BI "USER conntrack config-file-error " exception " " error-text The configuration file is invalid. The .I exception token names a Python exception; the .I error-text describes the problem encountered, though it may not be very useful. .SP .BI "USER conntrack connect-failed " peer " " tokens\fR... An attempt to connect the named .I peer failed; the error message is given by the .IR tokens . . .\"-------------------------------------------------------------------------- .SH "SUMMARY" . .\"= summary . .\"-------------------------------------------------------------------------- .SH "SEE ALSO" . .BR tripe-service (7), .BR peers.in (5), .BR watch (8), .BR tripe (8). . .\"-------------------------------------------------------------------------- .SH "AUTHOR" . Mark Wooding, . .\"----- That's all, folks --------------------------------------------------