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