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
  13 .\" it under the terms of the GNU General Public License as published by
  14 .\" the Free Software Foundation; either version 2 of the License, or
  15 .\" (at your option) any later version.
  16 .\"
  17 .\" TrIPE is distributed in the hope that it will be useful,
  18 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 .\" GNU General Public License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU General Public License
  23 .\" along with TrIPE; if not, write to the Free Software Foundation,
  24 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  25 .
  26 .\"--------------------------------------------------------------------------
  27 .so ../common/defs.man \"@@@PRE@@@
  28 .
  29 .\"--------------------------------------------------------------------------
  30 .TH connect 8 "8 January 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
  31 .
  32 .\"--------------------------------------------------------------------------
  33 .SH "NAME"
  34 .
  35 conntrack \- tripe service to start/stop peers depending on external connectivity
  36 .
  37 .\"--------------------------------------------------------------------------
  38 .SH "SYNOPSIS"
  39 .
  40 .B conntrack
  41 .RB [ \-a
  42 .IR socket ]
  43 .RB [ \-d
  44 .IR dir ]
  45 .RB [ \-f
  46 .IR file ]
  47 .br
  48 \&      \c
  49 .RB [ \-\-daemon ]
  50 .RB [ \-\-debug ]
  51 .RB [ \-\-startup ]
  52 .
  53 .\"--------------------------------------------------------------------------
  54 .SH "DESCRIPTION"
  55 .
  56 The
  57 .B conntrack
  58 service watches D-Bus network management services like
  59 .BR NetworkManager (8)
  60 and Nokia's
  61 .BR ICd ,
  62 bringing peers up and down automatically.  It's designed to be useful on
  63 a mobile device, such as a laptop; I expect servers to stay where
  64 they're put and be configured statically.
  65 .SS "Configuration"
  66 The
  67 .B conntrack
  68 service reads a configuration file, by default
  69 .BR conntrack.conf ,
  70 explaining which peers to bring up under which circumstances.  The
  71 configuration file is automatically re-read if it's changed.
  72 .PP
  73 The
  74 configuration is split into sections, each describing a
  75 .IR "peer group" .
  76 A section begins with the peer group name in square brackets:
  77 .IP
  78 .BI [ group ]
  79 .PP
  80 The group name is entirely arbitrary, and affects nothing else.  This is
  81 followed by peer definitions, each of which looks like this:
  82 .IP
  83 .I tag
  84 .B =
  85 .RI [ remote-addr ]
  86 .IB network / mask
  87 .PP
  88 This means that the peer
  89 .I tag
  90 should be selected if the host's current IP address is within the
  91 network indicated by
  92 .IB network / mask \fR.
  93 Here,
  94 .I network
  95 is an IP address in dotted-quad form, and
  96 .I mask
  97 is a netmask, either in dotted-quad form, or as a number of 1-bits.
  98 Only one peer in each group may be connected at any given time; if a
  99 change is needed, any existing peer in the group is killed before
 100 connecting the new one.  If no match is found in a particular group,
 101 then no peers in the group are connected.  Strange and unhelpful things
 102 will happen if you put the same peer in several different groups.
 103 .PP
 104 The notion of `current IP address' is somewhat vague.  The
 105 .B conntrack
 106 service calculates it as the source address that the host would put on
 107 an IP packet sent to an arbitrarily chosen remote address.  The default
 108 remote address is 1.2.3.4 (which is unlikely ever to be assigned); this
 109 should determine an IP address on the network interface closest to the
 110 default gateway.  You can influence this process in two ways.  Firstly,
 111 you can change the default remote address used by adding a line
 112 .IP
 113 .B "test-addr ="
 114 .I remote-addr
 115 .PP
 116 before the first peer group section.  Secondly, you can specify a
 117 particular
 118 .I remote-addr
 119 to use when checking whether a particular peer is applicable.
 120 .PP
 121 The peer definitions can be in any order.  They are checked
 122 most-specific first, and searching stops as soon as a match is found.
 123 Therefore a default definition can be added as
 124 .IP
 125 .I tag
 126 .B =
 127 .B 0/0
 128 .PP
 129 without fear of overriding any more specific definitions.  For avoidance
 130 of doubt, one peer definition is
 131 .I more specific
 132 than another if either the former has a specified
 133 .I remote-addr
 134 and the latter has not, or the former is wholly contained within the
 135 latter.  (Overlapping definitions are not recommended, and will be
 136 processed in an arbitrary order.)
 137 .PP
 138 Peers are connected using the
 139 .BR connect (8)
 140 service:
 141 .IP
 142 .B SVCSUBMIT connect active
 143 .I peer
 144 .SS "Command line"
 145 In addition to the standard options described in
 146 .BR tripe-service (7),
 147 the following command-line options are recognized.
 148 .TP
 149 .BI "\-f, \-\-config=" file
 150 Use
 151 .I file
 152 as the configuration file.  In the absence of this option, the
 153 file named
 154 .B conntrack.conf
 155 in the current working directory is used instead.
 156 .
 157 .\"--------------------------------------------------------------------------
 158 .SH "SERVICE COMMAND REFERENCE"
 159 .
 160 .\"* 10 Service commands
 161 The commands provided by the service are as follows.
 162 .SP
 163 .BI "up " reason\fR...
 164 Informs the service that the network connection has been established:
 165 peer groups should be connected.  The
 166 .I reason
 167 is quoted in the status notification.
 168 .SP
 169 .BI "down " reason\fR...
 170 Informs the service that the network connection has been lost:
 171 peer groups should be disconnected.  The
 172 .I reason
 173 is quoted in the status notification.
 174 .
 175 .\"--------------------------------------------------------------------------
 176 .SH "NOTIFICATIONS"
 177 .
 178 .\"* 30 Notification broadcasts (NOTE codes)
 179 All notifications issued by
 180 .B conntrack
 181 begin with the tokens
 182 .BR "USER conntrack" .
 183 .SP
 184 .BI "USER conntrack dbus-connection " status
 185 The service's connection to D-Bus has changed state.  The
 186 .I status
 187 is one of the following.
 188 .RS
 189 .TP
 190 .B startup
 191 Initially trying to connect.
 192 .TP
 193 .B connected
 194 Successfully established a connection to the bus.
 195 .TP
 196 .B lost
 197 A connection has been lost.
 198 .TP
 199 .BI state= label
 200 The service's internal state machine is confused.
 201 .SP
 202 .BI "USER conntrack " up \fR| down " " reason\fR...
 203 The network connection has apparently gone up or down, and
 204 .B conntrack
 205 is about to kill and/or connect peers accordingly.  The
 206 .I reason
 207 is one of the following.
 208 .RS
 209 .TP
 210 .B "nm initially-connected"
 211 NetworkManager was detected on startup, and has an active network
 212 connection.
 213 .TP
 214 .B "nm initially-disconnected"
 215 NetworkManager was detected on startup, and has no active network
 216 connection.
 217 .TP
 218 .B "nm connected"
 219 NetworkManager has acquired an active network connection.
 220 .TP
 221 .B "nm disconnected"
 222 NetworkManager has lost its active network connection.
 223 .TP
 224 .B "nm default-connection-change"
 225 NetworkManager has changed its default route.
 226 .TP
 227 .BI "icd initially-connected " iap
 228 Maemo ICd was detected on startup, and has an active network connection
 229 identified by
 230 .IR iap .
 231 .TP
 232 .B "icd initially-disconnected"
 233 Maemo ICd was detected on startup, and has no active network connection.
 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 .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 .RE
 256 .
 257 .\"--------------------------------------------------------------------------
 258 .SH "WARNINGS"
 259 .
 260 .\"* 40 Warning broadcasts (WARN codes)
 261 All warnings issued by
 262 .B conntrack
 263 begin with the tokens
 264 .BR "USER conntrack" .
 265 .SP
 266 .BI "USER conntrack config-file-error " exception " " error-text
 267 The configuration file is invalid.  The
 268 .I exception
 269 token names a Python exception; the
 270 .I error-text
 271 describes the problem encountered, though it may not be very useful.
 272 .
 273 .\"--------------------------------------------------------------------------
 274 .SH "SUMMARY"
 275 .
 276 .\"= summary
 277 .
 278 .\"--------------------------------------------------------------------------
 279 .SH "SEE ALSO"
 280 .
 281 .BR tripe-service (7),
 282 .BR peers.in (5),
 283 .BR watch (8),
 284 .BR tripe (8).
 285 .
 286 .\"--------------------------------------------------------------------------
 287 .SH "AUTHOR"
 288 .
 289 Mark Wooding, <mdw@distorted.org.uk>
 290 .
 291 .\"----- That's all, folks --------------------------------------------------