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 .PP
  89 This means that the peer
  90 .I tag
  91 should be selected if the host's current IP address is within the
  92 network indicated by
  93 .IB network / mask \fR.
  94 Here,
  95 .I network
  96 is an IP address in dotted-quad form, and
  97 .I mask
  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.
 104 .PP
 105 The tags
 106 .B down
 107 and
 108 .BI down/ anything
 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).
 112 .PP
 113 The notion of `current IP address' is somewhat vague.  The
 114 .B conntrack
 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
 121 .IP
 122 .B "test-addr ="
 123 .I remote-addr
 124 .PP
 125 before the first peer group section.  Secondly, you can specify a
 126 particular
 127 .I remote-addr
 128 to use when checking whether a particular peer is applicable.
 129 .PP
 130 The peer definitions can be in any order.  They are checked
 131 most-specific first, and searching stops as soon as a match is found.
 132 Therefore a default definition can be added as
 133 .IP
 134 .I tag
 135 .B =
 136 .B 0/0
 137 .PP
 138 without fear of overriding any more specific definitions.  For avoidance
 139 of doubt, one peer definition is
 140 .I more specific
 141 than another if either the former has a specified
 142 .I remote-addr
 143 and the latter has not, or the former is wholly contained within the
 144 latter.  (Overlapping definitions are not recommended, and will be
 145 processed in an arbitrary order.)
 146 .PP
 147 Peers are connected using the
 148 .BR connect (8)
 149 service:
 150 .IP
 151 .B SVCSUBMIT connect active
 152 .I peer
 153 .SS "Command line"
 154 In addition to the standard options described in
 155 .BR tripe-service (7),
 156 the following command-line options are recognized.
 157 .TP
 158 .BI "\-f, \-\-config=" file
 159 Use
 160 .I file
 161 as the configuration file.  In the absence of this option, the
 162 file named
 163 .B conntrack.conf
 164 in the current working directory is used instead.
 165 .
 166 .\"--------------------------------------------------------------------------
 167 .SH "SERVICE COMMAND REFERENCE"
 168 .
 169 .\"* 10 Service commands
 170 The commands provided by the service are as follows.
 171 .SP
 172 .BI "up " reason\fR...
 173 Informs the service that the network connection has been established:
 174 peer groups should be connected.  The
 175 .I reason
 176 is quoted in the status notification.
 177 .SP
 178 .BI "down " reason\fR...
 179 Informs the service that the network connection has been lost:
 180 peer groups should be disconnected.  The
 181 .I reason
 182 is quoted in the status notification.
 183 .
 184 .\"--------------------------------------------------------------------------
 185 .SH "NOTIFICATIONS"
 186 .
 187 .\"* 30 Notification broadcasts (NOTE codes)
 188 All notifications issued by
 189 .B conntrack
 190 begin with the tokens
 191 .BR "USER conntrack" .
 192 .SP
 193 .BI "USER conntrack dbus-connection " status
 194 The service's connection to D-Bus has changed state.  The
 195 .I status
 196 is one of the following.
 197 .RS
 198 .TP
 199 .B startup
 200 Initially trying to connect.
 201 .TP
 202 .B connected
 203 Successfully established a connection to the bus.
 204 .TP
 205 .B lost
 206 A connection has been lost.
 207 .TP
 208 .BI state= label
 209 The service's internal state machine is confused.
 210 .RE
 211 .SP
 212 .BI "USER conntrack " up \fR| down " " group = peer\fR... " " reason\fR...
 213 The network connection has apparently gone up or down, and
 214 .B conntrack
 215 is about to kill and/or connect peers accordingly: for each group, the
 216 selected peer is listed; if a group is not listed, then either the group
 217 is to be brought down, or no matching peer was found.  The
 218 .I reason
 219 is one of the following.
 220 .RS
 221 .TP
 222 .BI "connman initially-" state
 223 ConnMan was detected on startup, and is in the given
 224 .I state
 225 \(en see below.
 226 .TP
 227 .BI "connman " state
 228 ConnMan has transitioned to
 229 .IR state .
 230 The possible states are:
 231 .B offline
 232 (the network is turned off by user request);
 233 .B idle
 234 (no network interfaces are active);
 235 .B ready
 236 (an interface is up but not fully configured); and
 237 .B online
 238 (an interface is up and configured).
 239 .TP
 240 .BI "icd connected " iap
 241 Maemo ICd has acquired an active network connection, identified by
 242 .IR iap .
 243 .TP
 244 .B "icd idle"
 245 Maemo ICd has lost its active network connection.
 246 .TP
 247 .BI "icd initially-connected " iap
 248 Maemo ICd was detected on startup, and has an active network connection
 249 identified by
 250 .IR iap .
 251 .TP
 252 .B "icd initially-disconnected"
 253 Maemo ICd was detected on startup, and has no active network connection.
 254 .TP
 255 .B interval-timer
 256 A change was detected during
 257 .BR conntrack 's
 258 periodic status check.  This usually means that the network connection
 259 was reconfigured manually without informing
 260 .BR conntrack .
 261 .TP
 262 .BI "manual " reason\fR...
 263 The connection status was changed manually, using the
 264 .B up
 265 or
 266 .B down
 267 service command.
 268 .TP
 269 .B "nm connected"
 270 NetworkManager has acquired an active network connection.
 271 .TP
 272 .B "nm default-connection-change"
 273 NetworkManager has changed its default route.
 274 .TP
 275 .B "nm disconnected"
 276 NetworkManager has lost its active network connection.
 277 .TP
 278 .B "nm initially-connected"
 279 NetworkManager was detected on startup, and has an active network
 280 connection.
 281 .TP
 282 .B "nm initially-disconnected"
 283 NetworkManager was detected on startup, and has no active network
 284 connection.
 285 .RE
 286 .
 287 .\"--------------------------------------------------------------------------
 288 .SH "WARNINGS"
 289 .
 290 .\"* 40 Warning broadcasts (WARN codes)
 291 All warnings issued by
 292 .B conntrack
 293 begin with the tokens
 294 .BR "USER conntrack" .
 295 .SP
 296 .BI "USER conntrack config-file-error " exception " " error-text
 297 The configuration file is invalid.  The
 298 .I exception
 299 token names a Python exception; the
 300 .I error-text
 301 describes the problem encountered, though it may not be very useful.
 302 .SP
 303 .BI "USER conntrack connect-failed " peer " " tokens\fR...
 304 An attempt to connect the named
 305 .I peer
 306 failed; the error message is given by the
 307 .IR tokens .
 308 .
 309 .\"--------------------------------------------------------------------------
 310 .SH "SUMMARY"
 311 .
 312 .\"= summary
 313 .
 314 .\"--------------------------------------------------------------------------
 315 .SH "SEE ALSO"
 316 .
 317 .BR tripe-service (7),
 318 .BR peers.in (5),
 319 .BR watch (8),
 320 .BR tripe (8).
 321 .
 322 .\"--------------------------------------------------------------------------
 323 .SH "AUTHOR"
 324 .
 325 Mark Wooding, <mdw@distorted.org.uk>
 326 .
 327 .\"----- That's all, folks --------------------------------------------------