mdw@git.distorted.org.uk Git - 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 IP address in dotted-quad form, and
  98 .I mask
  99 is a netmask, either in dotted-quad form, or as a number of 1-bits.
 100 Only one peer in each group may be connected at any given time; if a
 101 change is needed, any existing peer in the group is killed before
 102 connecting the new one.  If no match is found in a particular group,
 103 then no peers in the group are connected.  Strange and unhelpful things
 104 will happen if you put the same peer in several different groups.
 105 .PP
 106 The tags
 107 .B down
 108 and
 109 .BI down/ anything
 110 are special and mean that no peer from the group should be active.  This
 111 is useful for detecting a `home' network, where a VPN is unnecessary
 112 (or, worse, break routing completely).
 113 .PP
 114 The notion of `current IP address' is somewhat vague.  The
 115 .B conntrack
 116 service calculates it as the source address that the host would put on
 117 an IP packet sent to an arbitrarily chosen remote address.  The default
 118 remote address is 1.2.3.4 (which is unlikely ever to be assigned); this
 119 should determine an IP address on the network interface closest to the
 120 default gateway.  You can influence this process in two ways.  Firstly,
 121 you can change the default remote address used by adding a line
 122 .IP
 123 .B "test-addr ="
 124 .I remote-addr
 125 .PP
 126 before the first peer group section.  Secondly, you can specify a
 127 particular
 128 .I remote-addr
 129 to use when checking whether a particular peer is applicable.
 130 .PP
 131 The peer definitions in each group are checked in the order given, and
 132 searching stops as soon as a match is found.
 133 .PP
 134 Peers are connected using the
 135 .BR connect (8)
 136 service:
 137 .IP
 138 .B SVCSUBMIT connect active
 139 .I peer
 140 .SS "Command line"
 141 In addition to the standard options described in
 142 .BR tripe-service (7),
 143 the following command-line options are recognized.
 144 .TP
 145 .BI "\-f, \-\-config=" file
 146 Use
 147 .I file
 148 as the configuration file.  In the absence of this option, the
 149 file named
 150 .B conntrack.conf
 151 in the current working directory is used instead.
 152 .
 153 .\"--------------------------------------------------------------------------
 154 .SH "SERVICE COMMAND REFERENCE"
 155 .
 156 .\"* 10 Service commands
 157 The commands provided by the service are as follows.
 158 .SP
 159 .BI "up " reason\fR...
 160 Informs the service that the network connection has been established:
 161 peer groups should be connected.  The
 162 .I reason
 163 is quoted in the status notification.
 164 .SP
 165 .BI "down " reason\fR...
 166 Informs the service that the network connection has been lost:
 167 peer groups should be disconnected.  The
 168 .I reason
 169 is quoted in the status notification.
 170 .
 171 .\"--------------------------------------------------------------------------
 172 .SH "NOTIFICATIONS"
 173 .
 174 .\"* 30 Notification broadcasts (NOTE codes)
 175 All notifications issued by
 176 .B conntrack
 177 begin with the tokens
 178 .BR "USER conntrack" .
 179 .SP
 180 .BI "USER conntrack dbus-connection " status
 181 The service's connection to D-Bus has changed state.  The
 182 .I status
 183 is one of the following.
 184 .RS
 185 .TP
 186 .B startup
 187 Initially trying to connect.
 188 .TP
 189 .B connected
 190 Successfully established a connection to the bus.
 191 .TP
 192 .B lost
 193 A connection has been lost.
 194 .TP
 195 .BI state= label
 196 The service's internal state machine is confused.
 197 .RE
 198 .SP
 199 .BI "USER conntrack " up \fR| down " " group = peer\fR... " " reason\fR...
 200 The network connection has apparently gone up or down, and
 201 .B conntrack
 202 is about to kill and/or connect peers accordingly: for each group, the
 203 selected peer is listed; if a group is not listed, then either the group
 204 is to be brought down, or no matching peer was found.  The
 205 .I reason
 206 is one of the following.
 207 .RS
 208 .TP
 209 .BI "connman initially-" state
 210 ConnMan was detected on startup, and is in the given
 211 .I state
 212 \(en see below.
 213 .TP
 214 .BI "connman " state
 215 ConnMan has transitioned to
 216 .IR state .
 217 The possible states are:
 218 .B offline
 219 (the network is turned off by user request);
 220 .B idle
 221 (no network interfaces are active);
 222 .B ready
 223 (an interface is up but not fully configured); and
 224 .B online
 225 (an interface is up and configured).
 226 .TP
 227 .BI "icd connected " iap
 228 Maemo ICd has acquired an active network connection, identified by
 229 .IR iap .
 230 .TP
 231 .B "icd idle"
 232 Maemo ICd has lost its active network connection.
 233 .TP
 234 .BI "icd initially-connected " iap
 235 Maemo ICd was detected on startup, and has an active network connection
 236 identified by
 237 .IR iap .
 238 .TP
 239 .B "icd initially-disconnected"
 240 Maemo ICd was detected on startup, and has no active network connection.
 241 .TP
 242 .B interval-timer
 243 A change was detected during
 244 .BR conntrack 's
 245 periodic status check.  This usually means that the network connection
 246 was reconfigured manually without informing
 247 .BR conntrack .
 248 .TP
 249 .BI "manual " reason\fR...
 250 The connection status was changed manually, using the
 251 .B up
 252 or
 253 .B down
 254 service command.
 255 .TP
 256 .B "nm connected"
 257 NetworkManager has acquired an active network connection.
 258 .TP
 259 .B "nm default-connection-change"
 260 NetworkManager has changed its default route.
 261 .TP
 262 .B "nm disconnected"
 263 NetworkManager has lost its active network connection.
 264 .TP
 265 .B "nm initially-connected"
 266 NetworkManager was detected on startup, and has an active network
 267 connection.
 268 .TP
 269 .B "nm initially-disconnected"
 270 NetworkManager was detected on startup, and has no active network
 271 connection.
 272 .RE
 273 .
 274 .\"--------------------------------------------------------------------------
 275 .SH "WARNINGS"
 276 .
 277 .\"* 40 Warning broadcasts (WARN codes)
 278 All warnings issued by
 279 .B conntrack
 280 begin with the tokens
 281 .BR "USER conntrack" .
 282 .SP
 283 .BI "USER conntrack config-file-error " exception " " error-text
 284 The configuration file is invalid.  The
 285 .I exception
 286 token names a Python exception; the
 287 .I error-text
 288 describes the problem encountered, though it may not be very useful.
 289 .SP
 290 .BI "USER conntrack connect-failed " peer " " tokens\fR...
 291 An attempt to connect the named
 292 .I peer
 293 failed; the error message is given by the
 294 .IR tokens .
 295 .
 296 .\"--------------------------------------------------------------------------
 297 .SH "SUMMARY"
 298 .
 299 .\"= summary
 300 .
 301 .\"--------------------------------------------------------------------------
 302 .SH "SEE ALSO"
 303 .
 304 .BR tripe-service (7),
 305 .BR peers.in (5),
 306 .BR watch (8),
 307 .BR tripe (8).
 308 .
 309 .\"--------------------------------------------------------------------------
 310 .SH "AUTHOR"
 311 .
 312 Mark Wooding, <mdw@distorted.org.uk>
 313 .
 314 .\"----- That's all, folks --------------------------------------------------