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

   1 .\" -*-nroff-*-
   2 .\".
   3 .\" Manual for the watch service
   4 .\"
   5 .\" (c) 2008 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 ../defs.man.in \"@@@PRE@@@
  28 .
  29 .\"--------------------------------------------------------------------------
  30 .TH watch 8 "11 December 2007" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
  31 .
  32 .\"--------------------------------------------------------------------------
  33 .SH "NAME"
  34 .
  35 watch \- tripe service handle addition and removal of peers
  36 .
  37 .\"--------------------------------------------------------------------------
  38 .SH "SYNOPSIS"
  39 .
  40 .B watch
  41 .RB [ \-a
  42 .IR socket ]
  43 .RB [ \-d
  44 .IR dir ]
  45 .RB [ \-p
  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 watch
  58 service tracks associations with peers and performs various actions at
  59 appropriate stages in the assocations' lifecycles.
  60 .PP
  61 For example:
  62 .hP \*o
  63 When a peer is added, it arranges to configure the corresponding network
  64 interface correctly, and (if necessary) to initiate a dynamic
  65 connection.
  66 .hP \*o
  67 When a peer is removed, it arranges to bring down the network interface.
  68 .hP \*o
  69 While the peer is known, it
  70 .BR PING s
  71 it at regular intervals.  If the peer fails to respond, it can be
  72 removed or reconnected.
  73 .SS "Command line"
  74 In addition to the standard options described in
  75 .BR tripe-service (7),
  76 the following command-line options are recognized.
  77 .TP
  78 .BI "\-p, \-\-peerdb=" file
  79 Use
  80 .I file
  81 as the (CDB format) peer database.  In the absence of this option, the
  82 file named by the
  83 .B TRIPEPEERDB
  84 environment variable is used; if that's not set either, then the default
  85 default of
  86 .B peers.cdb
  87 in the current working directory is used instead.
  88 .
  89 .\"--------------------------------------------------------------------------
  90 .SH "BEHAVIOUR"
  91 .
  92 .SS "Adoption"
  93 The
  94 .B watch
  95 service maintains a list of peers which it has adopted.  A peer is
  96 .I eligible for adoption
  97 if it has a record in the peer database
  98 .BR peers.cdb (5)
  99 in which the
 100 .B watch
 101 key is assigned the value
 102 .BR t ,
 103 .BR true ,
 104 .BR y ,
 105 .BR yes ,
 106 or
 107 .BR on .
 108 .PP
 109 The service pings adopted peers periodically in order to ensure that
 110 they are alive, and takes appropriate action if no replies are received.
 111 .PP
 112 A peer is said to be
 113 .I adopted
 114 when it is added to this list, and
 115 .I disowned
 116 when it removed.
 117 .SS "Configuring interfaces"
 118 The
 119 .B watch
 120 service configures network interfaces by invoking an
 121 .B ifup
 122 script.  The script is invoked as
 123 .IP
 124 .I script
 125 .IR args ...
 126 .I peer
 127 .I ifname
 128 .IR addr ...
 129 .PP
 130 where the elements are as described below.
 131 .TP
 132 .IR script " and " args
 133 The peer's database record is retrieved; the value assigned to the
 134 .B ifup
 135 key is split into words (quoting is allowed; see
 136 .BR tripe-admin (5)
 137 for details).  The first word is the
 138 .IR script ;
 139 subsequent words are gathered to form the
 140 .IR args .
 141 .TP
 142 .I peer
 143 The name of the peer.
 144 .TP
 145 .I ifname
 146 The name of the network interface associated with the peer, as returned
 147 by the
 148 .B IFNAME
 149 administration command (see
 150 .BR tripe-admin (5)).
 151 .TP
 152 .I addr
 153 The network address of the peer's TrIPE server, in the form output by
 154 the
 155 .B ADDR
 156 administration command (see
 157 .BR tripe-admin (5)).
 158 The first word of
 159 .I addr
 160 is therefore a network address family, e.g.,
 161 .BR INET .
 162 .PP
 163 The
 164 .B watch
 165 service deconfigures interfaces by invoking an
 166 .B ifdown
 167 script, in a similar manner.  The script is invoked as
 168 .IP
 169 .I script
 170 .IR args ...
 171 .I peer
 172 .PP
 173 where the elements are as above, except that
 174 .I script
 175 and
 176 .I args
 177 are formed by splitting the value associated with the peer record's
 178 .B ifdown
 179 key.
 180 .PP
 181 In both of the above cases, if the relevant key (either
 182 .B ifup
 183 or
 184 .BR ifdown )
 185 is absent, no action is taken.
 186 .PP
 187 The key/value pairs in the peer's database record and the server's
 188 response to the
 189 .B ALGS
 190 administration command (see
 191 .BR tripe-admin (5))
 192 are passed to the
 193 .B ifup
 194 and
 195 .B ifdown
 196 scripts as environment variables.  The environment variable name
 197 corresponding to a key is determined as follows:
 198 .hP \*o
 199 Convert all letters to upper-case.
 200 .hP \*o Convert all sequences of one or more non-alphanumeric characters
 201 to an underscore
 202 .RB ` _ '.
 203 .hP \*o Prefix the resulting name by
 204 .RB ` P_ '
 205 or
 206 .RB ` A_ '
 207 depending on whether it came from the peer's database record or the
 208 .B ALGS
 209 output respectively.
 210 .PP
 211 For example,
 212 .B ifname
 213 becomes
 214 .BR P_IFNAME ;
 215 and
 216 .B cipher-blksz
 217 becomes
 218 .BR A_CIPHER_BLKSZ .
 219 .SS "Dynamic connection"
 220 If a peer's database record assigns a value to the
 221 .B connect
 222 key, then the
 223 .B watch
 224 service will attempt to establish a connection dynamically with the
 225 peer.  The value of the
 226 .B connect
 227 key is invoked as a Bourne shell command, i.e.,
 228 .IP
 229 .B /bin/sh \-c
 230 .I connect
 231 .PP
 232 is executed.  The command is expected to contact the remote server and
 233 report, on standard output, a challenge string.  The
 234 .B watch
 235 service reads this challenge, and submits the command
 236 .IP
 237 .B GREET
 238 .I peer
 239 .I challenge
 240 .PP
 241 Typically, the
 242 .B connect
 243 command will issue a command such as
 244 .IP
 245 .B SVCSUBMIT connect passive
 246 .I our-name
 247 .PP
 248 where
 249 .I our-name
 250 is the remote peer's name for this host.
 251 .SS "Operation"
 252 On startup,
 253 .B watch
 254 requests a list of current peers from the
 255 .BR tripe (8)
 256 server, and adopts any eligible peers.  If the
 257 .B \-\-startup
 258 flag was passed on the command line,
 259 the newly adopted peers have their interfaces configured and connection
 260 attempts are made.
 261 .PP
 262 Adopted peers are pinged at regular intervals (using the
 263 .B PING
 264 administrative command; see
 265 .BR tripe-admin (5)).
 266 This process can be configured by assigning values to keys in the peer's
 267 database record.  Some of these parameters are time intervals,
 268 expressed as a nonnegative integer followed optionally by
 269 .BR d ,
 270 .BR h ,
 271 .BR m ,
 272 or
 273 .B s
 274 for days, hours, minutes, or seconds, respectively; if no suffix is
 275 given, seconds are assumed.
 276 .PP
 277 The parameters are as follows.
 278 .TP
 279 .B every
 280 A time interval: how often to ping the peer to ensure that it's still
 281 alive.  The default is 2 minutes.
 282 .TP
 283 .B timeout
 284 A time interval: how long to wait for a reply before retrying or giving
 285 up.  The default is 10 seconds.
 286 .TP
 287 .B retries
 288 An integer: how many failed attempts to make before deciding that the
 289 peer is unreachable and taking action.  The default is 5 attempts.
 290 .PP
 291 The algorithm is as follows.  Send up to
 292 .I retries
 293 pings; if a reply is received before the
 294 .I timeout
 295 then the peer is alive; wait
 296 .I every
 297 and check again.  If no reply is received within the
 298 .IR timeout ,
 299 then try again up to
 300 .I retries
 301 times.  If no attempt succeeds, the peer is declared unreachable.  If
 302 the peer has a
 303 .B connect
 304 command (i.e., it connects dynamically) then another connection attempt
 305 is made.  Otherwise the peer is killed.
 306 .
 307 .\"--------------------------------------------------------------------------
 308 .SH "SERVICE COMMAND REFERENCE"
 309 .
 310 .\"* 10 Service commands
 311 The commands provided by the service are as follows.
 312 .SP
 313 .B adopted
 314 For each peer being tracked by the
 315 .B watch
 316 service, write a line
 317 .B INFO
 318 .IR name .
 319 (Compatibility note: it's possible that further information will be
 320 provided about each peer, in the form of subsequent tokens.  Clients
 321 should be prepared to ignore such tokens.)
 322 .SP
 323 .BI "kick " peer
 324 If
 325 .I peer
 326 is currently added, and its record in the peer database contains a
 327 .B connect
 328 key (see
 329 .BR peers.in )
 330 then force a reconnection attempt.  See
 331 .BR "Dynamic connection" .
 332 .
 333 .\"--------------------------------------------------------------------------
 334 .SH "NOTIFICATIONS"
 335 .
 336 .\"* 30 Notification broadcasts (NOTE codes)
 337 All notifications issued by
 338 .B watch
 339 begin with the tokens
 340 .BR "USER watch" .
 341 .SP
 342 .B "USER watch peerdb-update"
 343 The peer database has changed.  Other interested clients should reopen
 344 the database.
 345 .SP
 346 .BI "USER watch ping-failed " peer " " error\fR...
 347 An attempt to
 348 .B PING
 349 the named
 350 .I peer
 351 failed; the server replied
 352 .B FAIL
 353 .IR error ...
 354 .SP
 355 .BI "USER watch " process\fR... " stdout " line
 356 The
 357 .I process
 358 spawned by the
 359 .B watch
 360 service unexpectedly wrote
 361 .I line
 362 to its standard output.
 363 .
 364 .\"--------------------------------------------------------------------------
 365 .SH "WARNINGS"
 366 .
 367 .\"* 40 Warning broadcasts (WARN codes)
 368 All warnings issued by
 369 .B watch
 370 begin with the tokens
 371 .BR "USER watch" .
 372 .SP
 373 .BI "USER watch ping-ok " peer
 374 A reply was received to a
 375 .B PING
 376 sent to the
 377 .IR peer ,
 378 though earlier attempts had failed.
 379 .SP
 380 .BI "USER watch ping-timeout " peer " attempt " i " of " n
 381 No reply was received to a
 382 .B PING
 383 sent to the
 384 .IR peer .
 385 So far,
 386 .I i
 387 .BR PING s
 388 have been sent; if a total of
 389 .I n
 390 consecutive attempts time out, the
 391 .B watch
 392 service will take further action.
 393 .SP
 394 .B "USER watch reconnecting " peer
 395 The dynamically connected
 396 .I peer
 397 seems to be unresponsive.  The
 398 .B watch
 399 service will attempt to reconnect.
 400 .SP
 401 .BI "USER watch " process\fR... " stderr " line
 402 The
 403 .I process
 404 spawned by the
 405 .B watch
 406 service wrote
 407 .I line
 408 to its standard error.
 409 .SP
 410 .BI "USER watch " process\fR... " exit-nonzero " code
 411 The
 412 .I process
 413 spawned by the
 414 .B watch
 415 service exited with the nonzero status
 416 .IR code .
 417 .SP
 418 .BI "USER watch " process\fR... " exit-signal S" code
 419 The
 420 .I process
 421 spawned by the
 422 .B watch
 423 service was killed by signal
 424 .IR code .
 425 Here,
 426 .I code
 427 is the numeric value of the fatal signal.
 428 .SP
 429 .BI "USER watch " process\fR... " exit-unknown " status
 430 The
 431 .I process
 432 spawned by the
 433 .B watch
 434 service exited with an unknown
 435 .IR status .
 436 Here,
 437 .I status
 438 is the raw exit status, as returned by
 439 .BR waitpid (2),
 440 in hexadecimal.
 441 .
 442 .\"--------------------------------------------------------------------------
 443 .SH "CHILD PROCESS IDENTIFIERS"
 444 .
 445 .\"* 50 Child process identifiers
 446 Some of the warnings and notifications refer to processes spawned by
 447 .B watch
 448 under various circumstances.  The process identifiers are as follows.
 449 .SP
 450 .BI "connect " peer
 451 A child spawned in order to establish a dynamic connection with
 452 .IR peer .
 453 .SP
 454 .BI "ifdown " peer
 455 A child spawned to deconfigure the network interface for
 456 .IR peer .
 457 .SP
 458 .BI "ifup " peer
 459 A child spawned to configure the network interface for
 460 .IR peer .
 461 .
 462 .\"--------------------------------------------------------------------------
 463 .SH "SUMMARY"
 464 .
 465 .\"= summary
 466 .
 467 .\"--------------------------------------------------------------------------
 468 .SH "SEE ALSO"
 469 .
 470 .BR tripe-service (7),
 471 .BR peers.in (5),
 472 .BR connect (8),
 473 .BR tripe (8).
 474 .
 475 .\"--------------------------------------------------------------------------
 476 .SH "AUTHOR"
 477 .
 478 Mark Wooding, <mdw@distorted.org.uk>
 479 .
 480 .\"----- That's all, folks --------------------------------------------------