chiark - git - mdw - tripe/blob - svc/conntrack.8.in

   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 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.
  16 .\"
  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.
  21 .\"
  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/>.
  24 .
  25 .\"--------------------------------------------------------------------------
  26 .so ../common/defs.man \"@@@PRE@@@
  27 .
  28 .\"--------------------------------------------------------------------------
  29 .TH conntrack 8tripe "8 January 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
  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
  58 .BR NetworkManager (8),
  59 .BR ConnMan
  60 .RB ( connmand (8)),
  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
  88 \&...
  89 .PP
  90 This means that the peer
  91 .I tag
  92 should be selected if the host's current IP address is within one of the
  93 networks indicated by
  94 .IB network / mask \fR.
  95 Here, a
  96 .I network
  97 is an IPv4 or IPv6 address in dotted-quad form, and
  98 .I mask
  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.
 106 .PP
 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
 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
 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
 125 .IP
 126 .B "test-addr ="
 127 .I remote-addr
 128 \&...
 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
 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
 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.)
 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
 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.
 205 .RE
 206 .SP
 207 .BI "USER conntrack " up \fR| down " " group = peer\fR... " " reason\fR...
 208 The network connection has apparently gone up or down, and
 209 .B conntrack
 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
 213 .I reason
 214 is one of the following.
 215 .RS
 216 .TP
 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
 235 .BI "icd connected " iap
 236 Maemo ICd has acquired an active network connection, identified by
 237 .IR iap .
 238 .TP
 239 .B "icd idle"
 240 Maemo ICd has lost its active network connection.
 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
 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.
 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.
 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.
 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 .
 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 --------------------------------------------------