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