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 .PP
 252 Similarly, if the database record has a
 253 .B disconnect
 254 entry, then
 255 .B watch
 256 will use this to give the peer explicit notification that its services
 257 are no longer needed.  The value f the
 258 .B disconnect
 259 key is invoked as a Bourne shell command.  This ought to result in a
 260 .B KILL
 261 command being issued to the peer's server.
 262 .SS "Operation"
 263 On startup,
 264 .B watch
 265 requests a list of current peers from the
 266 .BR tripe (8)
 267 server, and adopts any eligible peers.  If the
 268 .B \-\-startup
 269 flag was passed on the command line,
 270 the newly adopted peers have their interfaces configured and connection
 271 attempts are made.
 272 .PP
 273 Adopted peers are pinged at regular intervals (using the
 274 .B PING
 275 administrative command; see
 276 .BR tripe-admin (5)).
 277 This process can be configured by assigning values to keys in the peer's
 278 database record.  Some of these parameters are time intervals,
 279 expressed as a nonnegative integer followed optionally by
 280 .BR d ,
 281 .BR h ,
 282 .BR m ,
 283 or
 284 .B s
 285 for days, hours, minutes, or seconds, respectively; if no suffix is
 286 given, seconds are assumed.
 287 .PP
 288 The parameters are as follows.
 289 .TP
 290 .B every
 291 A time interval: how often to ping the peer to ensure that it's still
 292 alive.  The default is 2 minutes.
 293 .TP
 294 .B timeout
 295 A time interval: how long to wait for a reply before retrying or giving
 296 up.  The default is 10 seconds.
 297 .TP
 298 .B retries
 299 An integer: how many failed attempts to make before deciding that the
 300 peer is unreachable and taking action.  The default is 5 attempts.
 301 .PP
 302 The algorithm is as follows.  Send up to
 303 .I retries
 304 pings; if a reply is received before the
 305 .I timeout
 306 then the peer is alive; wait
 307 .I every
 308 and check again.  If no reply is received within the
 309 .IR timeout ,
 310 then try again up to
 311 .I retries
 312 times.  If no attempt succeeds, the peer is declared unreachable.  If
 313 the peer has a
 314 .B connect
 315 command (i.e., it connects dynamically) then another connection attempt
 316 is made.  Otherwise the peer is killed.
 317 .
 318 .\"--------------------------------------------------------------------------
 319 .SH "SERVICE COMMAND REFERENCE"
 320 .
 321 .\"* 10 Service commands
 322 The commands provided by the service are as follows.
 323 .SP
 324 .B adopted
 325 For each peer being tracked by the
 326 .B watch
 327 service, write a line
 328 .B INFO
 329 .IR name .
 330 (Compatibility note: it's possible that further information will be
 331 provided about each peer, in the form of subsequent tokens.  Clients
 332 should be prepared to ignore such tokens.)
 333 .SP
 334 .BI "kick " peer
 335 If
 336 .I peer
 337 is currently added, and its record in the peer database contains a
 338 .B connect
 339 key (see
 340 .BR peers.in )
 341 then force a reconnection attempt.  See
 342 .BR "Dynamic connection" .
 343 .
 344 .\"--------------------------------------------------------------------------
 345 .SH "NOTIFICATIONS"
 346 .
 347 .\"* 30 Notification broadcasts (NOTE codes)
 348 All notifications issued by
 349 .B watch
 350 begin with the tokens
 351 .BR "USER watch" .
 352 .SP
 353 .B "USER watch peerdb-update"
 354 The peer database has changed.  Other interested clients should reopen
 355 the database.
 356 .SP
 357 .BI "USER watch ping-failed " peer " " error\fR...
 358 An attempt to
 359 .B PING
 360 the named
 361 .I peer
 362 failed; the server replied
 363 .B FAIL
 364 .IR error ...
 365 .SP
 366 .BI "USER watch " process\fR... " stdout " line
 367 The
 368 .I process
 369 spawned by the
 370 .B watch
 371 service unexpectedly wrote
 372 .I line
 373 to its standard output.
 374 .
 375 .\"--------------------------------------------------------------------------
 376 .SH "WARNINGS"
 377 .
 378 .\"* 40 Warning broadcasts (WARN codes)
 379 All warnings issued by
 380 .B watch
 381 begin with the tokens
 382 .BR "USER watch" .
 383 .SP
 384 .BI "USER watch ping-ok " peer
 385 A reply was received to a
 386 .B PING
 387 sent to the
 388 .IR peer ,
 389 though earlier attempts had failed.
 390 .SP
 391 .BI "USER watch ping-timeout " peer " attempt " i " of " n
 392 No reply was received to a
 393 .B PING
 394 sent to the
 395 .IR peer .
 396 So far,
 397 .I i
 398 .BR PING s
 399 have been sent; if a total of
 400 .I n
 401 consecutive attempts time out, the
 402 .B watch
 403 service will take further action.
 404 .SP
 405 .B "USER watch reconnecting " peer
 406 The dynamically connected
 407 .I peer
 408 seems to be unresponsive.  The
 409 .B watch
 410 service will attempt to reconnect.
 411 .SP
 412 .BI "USER watch " process\fR... " stderr " line
 413 The
 414 .I process
 415 spawned by the
 416 .B watch
 417 service wrote
 418 .I line
 419 to its standard error.
 420 .SP
 421 .BI "USER watch " process\fR... " exit-nonzero " code
 422 The
 423 .I process
 424 spawned by the
 425 .B watch
 426 service exited with the nonzero status
 427 .IR code .
 428 .SP
 429 .BI "USER watch " process\fR... " exit-signal S" code
 430 The
 431 .I process
 432 spawned by the
 433 .B watch
 434 service was killed by signal
 435 .IR code .
 436 Here,
 437 .I code
 438 is the numeric value of the fatal signal.
 439 .SP
 440 .BI "USER watch " process\fR... " exit-unknown " status
 441 The
 442 .I process
 443 spawned by the
 444 .B watch
 445 service exited with an unknown
 446 .IR status .
 447 Here,
 448 .I status
 449 is the raw exit status, as returned by
 450 .BR waitpid (2),
 451 in hexadecimal.
 452 .
 453 .\"--------------------------------------------------------------------------
 454 .SH "CHILD PROCESS IDENTIFIERS"
 455 .
 456 .\"* 50 Child process identifiers
 457 Some of the warnings and notifications refer to processes spawned by
 458 .B watch
 459 under various circumstances.  The process identifiers are as follows.
 460 .SP
 461 .BI "connect " peer
 462 A child spawned in order to establish a dynamic connection with
 463 .IR peer .
 464 .SP
 465 .BI "disconnect " peer
 466 A child spawned in order to shut down a dynamic connection with
 467 .IR peer .
 468 .SP
 469 .BI "ifdown " peer
 470 A child spawned to deconfigure the network interface for
 471 .IR peer .
 472 .SP
 473 .BI "ifup " peer
 474 A child spawned to configure the network interface for
 475 .IR peer .
 476 .
 477 .\"--------------------------------------------------------------------------
 478 .SH "SUMMARY"
 479 .
 480 .\"= summary
 481 .
 482 .\"--------------------------------------------------------------------------
 483 .SH "SEE ALSO"
 484 .
 485 .BR tripe-service (7),
 486 .BR peers.in (5),
 487 .BR connect (8),
 488 .BR tripe (8).
 489 .
 490 .\"--------------------------------------------------------------------------
 491 .SH "AUTHOR"
 492 .
 493 Mark Wooding, <mdw@distorted.org.uk>
 494 .
 495 .\"----- That's all, folks --------------------------------------------------