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