usr.sbin/atm/scspd/scspd.8

   1 .\"
   2 .\" ===================================
   3 .\" HARP  |  Host ATM Research Platform
   4 .\" ===================================
   5 .\"
   6 .\"
   7 .\" This Host ATM Research Platform ("HARP") file (the "Software") is
   8 .\" made available by Network Computing Services, Inc. ("NetworkCS")
   9 .\" "AS IS".  NetworkCS does not provide maintenance, improvements or
  10 .\" support of any kind.
  11 .\"
  12 .\" NETWORKCS MAKES NO WARRANTIES OR REPRESENTATIONS, EXPRESS OR IMPLIED,
  13 .\" INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY
  14 .\" AND FITNESS FOR A PARTICULAR PURPOSE, AS TO ANY ELEMENT OF THE
  15 .\" SOFTWARE OR ANY SUPPORT PROVIDED IN CONNECTION WITH THIS SOFTWARE.
  16 .\" In no event shall NetworkCS be responsible for any damages, including
  17 .\" but not limited to consequential damages, arising from or relating to
  18 .\" any use of the Software or related support.
  19 .\"
  20 .\" Copyright 1994-1998 Network Computing Services, Inc.
  21 .\"
  22 .\" Copies of this Software may be made, however, the above copyright
  23 .\" notice must be reproduced on all copies.
  24 .\"
  25 .\" @(#) $FreeBSD: src/usr.sbin/atm/scspd/scspd.8,v 1.2.2.3 2003/03/11 21:13:48 trhodes Exp $
  26 .\" @(#) $DragonFly: src/usr.sbin/atm/scspd/scspd.8,v 1.2 2003/06/17 04:29:52 dillon Exp $
  27 .\"
  28 .\"
  29 .Dd August 21, 1998
  30 .Dt SCSPD 8
  31 .Os
  32 .Sh NAME
  33 .Nm scspd
  34 .Nd "SCSP daemon"
  35 .Sh SYNOPSIS
  36 .Nm
  37 .Op Fl f Aq Ar cfg\-file
  38 .Op Fl d
  39 .Op Fl T Ns Aq Ar options
  40 .Sh DESCRIPTION
  41 The
  42 .Nm
  43 utility is an implementation of the Server Cache Synchronization
  44 Protocol (SCSP) for the Host ATM Research Platform (HARP)
  45 networking software.
  46 The
  47 .Nm
  48 utility synchronizes the cache(s) of server(s)
  49 running on a host with the caches of servers on remote hosts.
  50 SCSP is defined for a number of different protocols, but the present
  51 version of
  52 .Nm
  53 only supports ATMARP.
  54 .Pp
  55 By using
  56 .Nm
  57 and
  58 .Xr atmarpd 8 ,
  59 one can provide multiple
  60 ATMARP servers in a single ATM LIS.
  61 This might be useful, for example, when a LIS consists of a number of
  62 local-area ATM networks connected by long-distance links.
  63 Each local-area network could have its own ATMARP server, with all the
  64 servers' caches being synchronized by SCSP.
  65 Then, if a long-distance link fails, hosts on a local-area network
  66 will still have connectivity to other local hosts (since they all use
  67 the local ATMARP server); when the long-distance link is restored,
  68 SCSP will re-synchronize the servers' caches, restoring
  69 connectivity to remote hosts.
  70 Both
  71 .Nm
  72 and
  73 .Xr atmarpd 8
  74 must be running before any ATMARP
  75 cache synchronization can take place.
  76 .Pp
  77 The
  78 .Nm
  79 utility implements SCSP as specified in RFC 2334,
  80 .%T "Server Cache Synchronization Protocol (SCSP)"
  81 and
  82 .Pa draft\-ietf\-ion\-scspd\-atmarpd\-00.txt ,
  83 .%T "A Distributed ATMARP Service using SCSP" .
  84 .Pp
  85 When
  86 .Nm
  87 starts, it parses its command line and puts
  88 itself into the background.
  89 .Sh TERMINOLOGY
  90 Some of the vocabulary associated with SCSP can be confusing.
  91 In this document, the following definitions are used:
  92 .Pp
  93 .Em "Client server"
  94 or
  95 .Em "local server"
  96 means the server running on
  97 the same host as
  98 .Nm
  99 whose cache is to be synchronized with that
 100 of one or more remote servers.
 101 When the word
 102 .Em server
 103 is used alone, it means
 104 .Em "client server" .
 105 .Pp
 106 .Em "Remote server"
 107 means a server running on some host other than
 108 the one where
 109 .Nm
 110 is running.
 111 .Pp
 112 .Em "Directly Connected Server"
 113 (DCS) means a remote server that
 114 .Nm
 115 communicates with directly.
 116 The remote server will also be running an implementation of SCSP.
 117 .Pp
 118 .Em "Cache Alignment"
 119 (CA) has two meanings.
 120 The Cache Alignment protocol is a part of the SCSP protocol
 121 specification, and the Cache Alignment finite state machine (FSM)
 122 is a finite state machine that implements the Cache Alignment
 123 protocol.
 124 .Sh OPTIONS
 125 The command-line options are:
 126 .Bl -tag -width "-f <cfg\-file>"
 127 .It Fl f Aq Ar cfg\-file
 128 Specifies the name of the configuration file.
 129 If this option is not specified,
 130 .Nm
 131 looks for the
 132 file
 133 .Pa /etc/scspd.conf .
 134 .It Fl d
 135 Specifies that
 136 .Nm
 137 is to be run in debug mode.
 138 In debug mode, the daemon is not put into the background.
 139 Log messages are written to standard output instead of to
 140 the log file specified in the configuration file.
 141 .It Fl T Ns Aq Ar options
 142 Specifies that
 143 .Nm
 144 will trace specified events and messages
 145 as it executes.
 146 The
 147 .Fl T
 148 flag is followed by one or more of the following
 149 options:
 150 .Pp
 151 .Bl -tag -width 4n -compact
 152 .It Cm c
 153 trace
 154 .Nm Ns 's
 155 CA Finite State Machine (FSM),
 156 .It Cm h
 157 trace
 158 .Nm Ns 's
 159 Hello FSM,
 160 .It Cm i
 161 trace
 162 .Nm Ns 's
 163 Client Interface FSM,
 164 .It Cm C
 165 trace CA, CSUS, CSU Request, and CSU Reply messages,
 166 .It Cm H
 167 trace Hello messages,
 168 .It Cm I
 169 trace interface messages to and from
 170 .Nm Ns 's
 171 clients.
 172 .El
 173 .El
 174 .Sh CONFIGURATION
 175 The configuration file consists of a sequence of configuration
 176 statements.
 177 These statements specify information about the servers,
 178 both local and remote, whose
 179 caches are to be synchronized by
 180 .Nm .
 181 RFC 2334,
 182 .%T "Server Cache Synchronization Protocol (SCSP)"
 183 and
 184 .Pa draft\-ietf\-ion\-scspd\-atmarpd\-00.txt ,
 185 .%T "A Distributed ATMARP Service using SCSP"
 186 will be valuable in understanding how to configure
 187 .Nm .
 188 .Pp
 189 A configuration statement other than a comment is terminated by a
 190 semicolon.
 191 Some statements contain blocks, delimited by braces
 192 .No ( Dq Li {
 193 and
 194 .Dq Li } ) .
 195 Configuration statement keywords are not case-sensitive,
 196 but some parameters (e.g. interface names) are.
 197 Configuration statements can span multiple lines.
 198 .Ss Comments
 199 Three types of comments are allowed:
 200 .Bl -hang
 201 .It Sy "# comments" :
 202 any characters from
 203 .Dq Li #
 204 to the end of the line are ignored.
 205 .It Sy "C comments" :
 206 any characters between
 207 .Dq Li /*
 208 and
 209 .Dq Li */
 210 are ignored.
 211 .It Sy "C++ comments" :
 212 any characters from
 213 .Dq Li //
 214 to the end of the line are ignored.
 215 .El
 216 .Ss Statements
 217 The configuration statements recognized by
 218 .Nm
 219 are:
 220 .Bd -literal
 221 Server <name> {
 222         Protocol <protocol ID>;
 223         Netif <if_name>;
 224         ServerGroupID <ID>;
 225         FamilyID <ID>;
 226         DCS {
 227                 ATMaddr <ATM address>;
 228                 ID <host>;
 229                 CAReXmitInt <int>;
 230                 CSUSReXmitInt <int>;
 231                 CSUReXmitInt <int>;
 232                 CSUReXmitMax <cnt>;
 233                 HelloDead <cnt>;
 234                 HelloInt <int>;
 235                 Hops <cnt>;
 236         };
 237 };
 238
 239 Log {
 240         File <file name>;
 241         Syslog;
 242 };
 243 .Ed
 244 .Pp
 245 Where a host address needs to be specified in the configuration file,
 246 either a DNS name or an IP address in dotted decimal format can
 247 be used.
 248 .Pp
 249 ATM addresses are specified as strings of hex digits, with an
 250 optional leading
 251 .Dq Li 0x .
 252 Fields within the address may be separated by periods, but periods
 253 are for readability only and are ignored.
 254 ATM addresses are 20 bytes long.
 255 The full address, including any leading zeroes, must be given.
 256 For example:
 257 .Pp
 258 .Dl "0x47.0005.80.ffe100.0000.f21a.0170.0020481a0170.00"
 259 .Ss "Server Statement"
 260 The
 261 .Ic server
 262 statement specifies a client server whose cache
 263 to be synchronized with the caches of other servers
 264 running on remote hosts.
 265 There will be one
 266 .Ic server
 267 statement in the configuration file
 268 for each client server whose cache is to be synchronized by
 269 .Nm .
 270 The format of the
 271 .Ic server
 272 statement is:
 273 .Bd -ragged -offset indent
 274 .Ic Server
 275 .Aq Ar name
 276 {
 277 .Aq Ar statements
 278 };
 279 .Ed
 280 .Pp
 281 A
 282 .Ar name
 283 must be specified on the
 284 .Ic server
 285 statement, but it is
 286 not used by
 287 .Nm .
 288 It is expected to give a brief description of the server's purpose.
 289 .Pp
 290 The
 291 .Ic server
 292 statement has several sub-statements
 293 that specify the details of the
 294 .Nm Ns 's
 295 configuration.
 296 They are:
 297 .Bl -tag -width indent
 298 .It Ic Protocol Cm ATMARP ;
 299 The only protocol supported by the current version of
 300 .Nm
 301 is
 302 .Cm ATMARP .
 303 The
 304 .Ic protocol
 305 statement must always be specified.
 306 .It Ic Netif Aq Ar intf ;
 307 The
 308 .Ic netif
 309 statement specifies the name of the ATM network
 310 interface on which a client server is providing service.
 311 The
 312 .Ic netif
 313 statement must always be specified.
 314 .It Ic ServerGroupID Aq Ar ID ;
 315 The
 316 .Ic ServerGroupID
 317 statement specifies an identifier for the
 318 group of servers being synchronized by
 319 .Nm .
 320 The
 321 .Ar ID
 322 is specified as a decimal number in the range 0 - 65,535.
 323 The server group ID must be the same for all servers whose caches
 324 are being synchronized by an SCSP session.
 325 That is, the server group ID for a host must be the same for all
 326 Directly Connected Servers (DCSs) pointed to within a
 327 .Ic server
 328 statement.
 329 The
 330 .Ic ServerGroupID
 331 statement must always be specified.
 332 .It Ic FamilyID Aq Ar ID ;
 333 The
 334 .Ic familyID
 335 statement specifies an identifier for a family
 336 of parallel SCSP sessions running between a group of hosts (i.e. a
 337 set of SCSP sessions with different protocol IDs but the same set
 338 of servers).
 339 The
 340 .Ar ID
 341 is specified as a decimal number in the range 0 - 65,535.
 342 The family ID is currently not used by
 343 .Nm .
 344 .El
 345 .Ss "DCS Statement"
 346 The
 347 .Ic DCS
 348 statement is a sub-statement of the
 349 .Ic server
 350 statement
 351 that specifies the characteristics of a Directly Connected Server (DCS).
 352 The
 353 .Ic server
 354 statement will have one
 355 .Ic DCS
 356 statement for
 357 each DCS that
 358 .Nm
 359 is to exchange information with.
 360 The
 361 .Ic DCS
 362 statement has a number of sub-statements that specify the
 363 details of the configuration for the DCS.
 364 They are:
 365 .Bl -tag -width indent
 366 .It Ic ATMaddr Aq Ar ATM\ address ;
 367 The
 368 .Ic ATMaddr
 369 statement specifies the ATM address of the DCS.
 370 The
 371 .Ic ATMaddr
 372 statement must always be specified.
 373 .It Ic ID Aq Ar host ;
 374 The
 375 .Ic ID
 376 statement specifies the SCSP identifier of the DCS.
 377 For ATMARP, the ID is the IP address or DNS name associated with the
 378 ATM interface of the DCS.
 379 The
 380 .Ic ID
 381 statement must always be specified.
 382 .It Ic CAReXmitInt Aq Ar int ;
 383 The
 384 .Ic CAReXmitInt
 385 statement specifies the interval that is
 386 allowed to elapse between retransmissions of CA messages.
 387 If a CA message is sent and an acknowledgement is not received within
 388 .Ic CAReXmitInt
 389 seconds, the message will be retransmitted.
 390 The default value for
 391 .Ic CAReXmitInt
 392 is 3 seconds.
 393 .It Ic CSUSReXmitInt Aq Ar int ;
 394 The
 395 .Ic CSUSReXmitInt
 396 statement specifies the interval that is
 397 allowed to elapse between retransmissions of CSU Solicit messages.
 398 When a CSUS message is sent, any Cache State Advertisements (CSAs)
 399 requested by the CSUS that have
 400 not been received within
 401 .Ic CSUSReXmitInt
 402 seconds will be requested
 403 again by another CSUS message.
 404 The default value for
 405 .Ic CSUSReXmitInt
 406 is 3 seconds.
 407 Be careful not to confuse
 408 .Ic CSUSReXmitInt
 409 and
 410 .Ic CSUReXmitInt .
 411 .It Ic CSUReXmitInt Aq Ar int ;
 412 The
 413 .Ic CSUReXmitInt
 414 statement specifies the interval that is
 415 allowed to elapse between retransmissions of CSU Request messages.
 416 When a CSU Request message is sent, any CSAs that are not acknowledged
 417 by a CSU Reply message within
 418 .Ic CSUReXmitInt
 419 seconds will
 420 be retransmitted.
 421 The default value for
 422 .Ic CSUReXmitInt
 423 is 2 seconds.
 424 Be careful not to confuse
 425 .Ic CSUReXmitInt
 426 and
 427 .Ic CSUSReXmitInt .
 428 .It Ic CSUReXmitMax Aq Ar cnt ;
 429 The
 430 .Ic CSUReXmitMax
 431 statement specifies the number of times that
 432 a CSA will be retransmitted as described above before SCSP gives up
 433 on the CSA and discards it.
 434 The default value for
 435 .Ic CSUReXmitMax
 436 is 5.
 437 .It Ic HelloDead Aq Ar cnt ;
 438 The
 439 .Ic HelloDead
 440 statement specifies the Hello Dead Factor that
 441 will be sent to the DCS in Hello messages.
 442 A
 443 .Dq "DCS down"
 444 condition will be detected when nothing is received from
 445 a DCS in
 446 .Ic HelloDead No * Ic HelloInt
 447 seconds.
 448 The default value for
 449 .Ic HelloDead
 450 is 3.
 451 .It Ic HelloInt Aq Ar int ;
 452 The
 453 .Ic HelloInt
 454 statement specifies the Hello Interval that
 455 will be sent to the DCS in Hello messages.
 456 The default value for
 457 .Ic HelloInt
 458 is 3 seconds.
 459 .It Ic Hops Aq Ar cnt ;
 460 The
 461 .Ic Hops
 462 statement specifies the number of hops (DCS to DCS)
 463 that will be specified in CSAs originating from the local server.
 464 This number must be at least as large as the diameter of the
 465 server group.
 466 That is, it must be large enough for a CSA to be propagated from
 467 server to server all the way across the server group.
 468 The default value for
 469 .Ic Hops
 470 is 3.
 471 .El
 472 .Ss "Log Statement"
 473 The
 474 .Ic log
 475 statement specifies how
 476 .Nm
 477 is to log
 478 information about its operation.
 479 The
 480 .Nm
 481 utility can write log information to a file, to the system log,
 482 or both.
 483 .Bl -tag -width indent
 484 .It Ic File Aq Ar file\ name ;
 485 The
 486 .Ic file
 487 statement specifies that
 488 .Nm
 489 is to write
 490 its log messages to the named file.
 491 Log messages will be appended to the end of the file if
 492 it already exists.
 493 .It Ic Syslog ;
 494 The
 495 .Ic syslog
 496 statement specifies that
 497 .Nm
 498 is to write
 499 its log messages to the syslog facility.
 500 The
 501 .Nm
 502 utility writes its messages to syslog with a facility code
 503 of
 504 .Dv LOG_DAEMON .
 505 .El
 506 .Pp
 507 If no
 508 .Ic log
 509 statement is specified,
 510 .Nm
 511 writes log
 512 messages to the system log.
 513 If both
 514 .Ic file
 515 and
 516 .Ic syslog
 517 are specified,
 518 .Nm
 519 will
 520 write log messages to both the named file and the system log.
 521 .Ss Examples
 522 An example of a simple configuration file for
 523 .Nm
 524 might be:
 525 .Bd -literal -offset indent
 526 server atmarp_ni0 {
 527      protocol ATMARP;
 528      netif ni0;
 529      ServerGroupID 23;
 530      DCS {
 531           ID 10.1.1.2;
 532           ATMaddr 0x47.0005.80.ffdc00.0000.0002.0001.002048061de7.00;
 533           hops 2;
 534      };
 535 };
 536 .Ed
 537 .Pp
 538 This configuration would synchronize the cache of the ATMARP server
 539 operating on network interface ni0 with the cache of a second server
 540 running on a host whose IP address is 10.1.1.2.
 541 Log messages would be written to the system log.
 542 .Sh SIGNAL PROCESSING
 543 The following signals can be used to control
 544 .Nm :
 545 .Bl -tag -width indent
 546 .It Dv SIGHUP
 547 Reread the configuration file and restart
 548 .Nm .
 549 .It Dv SIGINT
 550 Dump debugging information to a file.
 551 When it receives a
 552 .Dv SIGINT
 553 signal,
 554 .Nm
 555 dumps a summary of
 556 its control blocks to a text file (see
 557 .Sx FILES ) .
 558 .El
 559 .Sh FILES
 560 .Bl -tag -width indent
 561 .It Pa /etc/scspd.conf
 562 .Nm
 563 default configuration file name.
 564 A different file name can be specified with the
 565 .Fl f
 566 command-line
 567 option.
 568 .It Xo
 569 .Sm off
 570 .Pa /tmp/scspd.
 571 .Aq Ar pid
 572 .Pa \&.
 573 .Aq Ar seq
 574 .Pa .out
 575 .Sm on
 576 .Xc
 577 debugging information dump file name.
 578 The
 579 .Nm
 580 utility writes a summary of its control blocks to this file
 581 when it receives a
 582 .Dv SIGINT
 583 signal.
 584 .Aq Ar pid
 585 is the process ID of the daemon and
 586 .Aq Ar seq
 587 is a sequence
 588 number which is incremented every time a dump is taken.
 589 .It Xo
 590 .Sm off
 591 .Pa /tmp/scspd.
 592 .Aq Ar pid
 593 .Pa .trace
 594 .Sm on
 595 .Xc
 596 trace file.
 597 The
 598 .Nm
 599 utility writes trace information to this file if the
 600 .Fl T
 601 option is specified on the command line.
 602 .El
 603 .Sh SEE ALSO
 604 .Xr atm 8 ,
 605 .Xr atmarpd 8
 606 .Rs
 607 .%O "RFC 2334"
 608 .%T "Server Cache Synchronization Protocol (SCSP)"
 609 .Re
 610 .Rs
 611 .%O "draft\-ietf\-ion\-scsp\-atmarpd\-00.txt"
 612 .%T "A Distributed ATMARP Service Using SCSP"
 613 .Re
 614 .Sh BUGS
 615 If
 616 .Nm
 617 terminates and is restarted, there will be a period of
 618 instability while previously-synchronized cache entries time out and are
 619 refreshed.
 620 .Pp
 621 Please report any bugs to
 622 .Aq harp\-bugs@magic.net .
 623 .Sh COPYRIGHT
 624 Copyright (c) 1994-1998, Network Computing Services, Inc.
 625 .Sh AUTHORS
 626 .An John Cavanaugh ,
 627 Network Computing Services, Inc.
 628 .An Mike Spengler ,
 629 Network Computing Services, Inc.
 630 .An Joe Thomas ,
 631 Network Computing Services, Inc.
 632 .Sh ACKNOWLEDGMENTS
 633 This software was developed with the support of the Defense
 634 Advanced Research Projects Agency (DARPA).