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$
  26 .\"
  27 .\"
  28 .de EX          \"Begin example
  29 .ne 5
  30 .if n .sp 1
  31 .if t .sp .5
  32 .nf
  33 .in +.5i
  34 ..
  35 .de EE
  36 .fi
  37 .in -.5i
  38 .if n .sp 1
  39 .if t .sp .5
  40 ..
  41 .TH SCSPD 8 "1998-08-21" "HARP"
  42
  43 .SH NAME
  44 scspd \- SCSP daemon
  45 .SH SYNOPSIS
  46 .B scspd
  47 [\fB-f\fP <cfg-file>]
  48 [\fB-d\fP]
  49 [\fB-T\fP<options>]
  50
  51 .SH DESCRIPTION
  52 \fIScspd\fP is an implementation of the Server Cache Synchronization
  53 Protocol (SCSP) for the Host ATM Research Platform (HARP)
  54 networking software.
  55 \fIScspd\fP synchronizes the cache(s) of server(s)
  56 running on a host with the caches of servers on remote hosts.
  57 SCSP is defined for a number of different protocols, but the present
  58 version of \fIscspd\fP only supports ATMARP.
  59 .PP
  60 By using \fIscspd\fP and \fIatmarpd\fP, one can provide multiple
  61 ATMARP servers in a single ATM LIS.
  62 This might be useful, for example, when a LIS consists of a number of
  63 local-area ATM networks connected by long-distance links.
  64 Each local-area network could have its own ATMARP server, with all the
  65 servers' caches being synchronized by SCSP.
  66 Then, if a long-distance link fails, hosts on a local-area network
  67 will still have connectivity to other local hosts (since they all use
  68 the local ATMARP server);  when the long-distance link is restored,
  69 SCSP will re-synchronize the servers' caches, restoring
  70 connectivity to remote hosts.
  71 Both \fIscspd\fP and \fIatmarpd\fP must be running before any ATMARP
  72 cache synchronization can take place.
  73 .PP
  74 \fIScspd\fP implements SCSP as specified in RFC 2334, \fIServer Cache
  75 Synchronization Protocol (SCSP)\fP and
  76 draft-ietf-ion-scspd-atmarpd-00.txt, \fIA Distributed ATMARP Service
  77 using SCSP\fP.
  78
  79 When \fIscspd\fP starts, it parses its command line and puts
  80 itself into the background.
  81
  82 .SH TERMINOLOGY
  83 Some of the vocabulary associated with SCSP can be confusing.
  84 In this document, the following definitions are used:
  85
  86 \fBClient server\fP or \fBlocal server\fP means the server running on
  87 the same host as \fIscspd\fP whose cache is to be synchronized with that
  88 of one or more remote servers.
  89 When the word \fBserver\fP is used alone, it means "client server".
  90
  91 \fBRemote server\fP means a server running on some host other than
  92 the one where \fIscspd\fP is running.
  93
  94 \fBDirectly Connected Server\fP (DCS) means a remote server that
  95 \fIscspd\fP communicates with directly.
  96 The remote server will also be running an implementation of SCSP.
  97
  98 \fBCache Alignment\fP (CA) has two meanings.
  99 The Cache Alignment protocol is a part of the SCSP protocol
 100 specification, and the Cache Alignment finite state machine (FSM)
 101 is a finite state machine that implements the Cache Alignment
 102 protocol.
 103
 104 .SH OPTIONS
 105 The command-line options are:
 106 .IP "\fB-f\fP <cfg-file>" 15
 107 Specifies the name of the configuration file.
 108 If this option is not specified, \fIscspd\fP looks for the
 109 file /etc/scspd.conf.
 110 .IP "\fB-d\fP" 15
 111 Specifies that \fIscspd\fP is to be run in debug mode.
 112 In debug mode, the daemon is not put into the background.
 113 Log messages are written to standard output instead of to
 114 the log file specified in the configuration file.
 115 .IP "\fB-T\fP<options>" 15
 116 Specifies that \fIscspd\fP will trace specified events and messages
 117 as it executes.
 118 The \fB-T\fP flag is followed by one or more of the following
 119 options:
 120 .in +4
 121 .ti -4
 122 \fBc\fP\ -\ trace \fIscspd\fP's CA Finite State Machine (FSM),
 123 .ti -4
 124 \fBh\fP\ -\ trace \fIscspd\fP's Hello FSM,
 125 .ti -4
 126 \fBi\fP\ -\ trace \fIscspd\fP's Client Interface FSM,
 127 .ti -4
 128 \fBC\fP\ -\ trace CA, CSUS, CSU Request, and CSU Reply messages,
 129 .ti -4
 130 \fBH\fP\ -\ trace Hello messages,
 131 .ti -4
 132 \fBI\fP\ -\ trace interface messages to and from \fIscspd\fP's
 133 clients.
 134 .in -4
 135 .SH CONFIGURATION
 136
 137 The configuration file consists of a sequence of configuration
 138 statements.
 139 These statements specify information about the servers,
 140 both local and remote, whose
 141 caches are to be synchronized by \fIscspd\fP.
 142 RFC 2334, \fIServer Cache
 143 Synchronization Protocol (SCSP)\fP and
 144 draft-ietf-ion-scspd-atmarpd-00.txt, \fIA Distributed ATMARP Service
 145 using SCSP\fP
 146 will be valuable in understanding how to configure \fIscspd\fP.
 147
 148 A configuration statement other than a comment is terminated by a
 149 semicolon.
 150 Some statements contain blocks, delimited by braces ("{" and "}").
 151 Configuration statement keywords are not case-sensitive,
 152 but some parameters (e.g. interface names) are.
 153 Configuration statments can span multiple lines.
 154
 155 .SS Comments
 156 Three types of comments are allowed:
 157
 158 \fB# comments\fP:
 159 any characters from "#" to the end of the line are ignored.
 160
 161 \fBC comments\fP:
 162 any characters between "/*" and "*/" are ignored.
 163
 164 \fBC++ comments\fP:
 165 any characters from "//" to the end of the line are ignored.
 166
 167 .SS "Statements"
 168 The configuration statements recognized by \fIscspd\fP are:
 169
 170 Server <name> {
 171 .in +5
 172 Protocol <protocol ID>;
 173 .br
 174 Netif <if_name>;
 175 .br
 176 ServerGroupID <ID>;
 177 .br
 178 FamilyID <ID>;
 179 .br
 180 DCS {
 181 .in +5
 182 ATMaddr <ATM address>;
 183 .br
 184 ID <host>;
 185 .br
 186 CAReXmitInt <int>;
 187 .br
 188 CSUSReXmitInt <int>;
 189 .br
 190 CSUReXmitInt <int>;
 191 .br
 192 CSUReXmitMax <cnt>;
 193 .br
 194 HelloDead <cnt>;
 195 .br
 196 HelloInt <int>;
 197 .br
 198 Hops <cnt>;
 199 .in -5
 200 };
 201 .in -5
 202 };
 203 .sp
 204 Log {
 205 .in +5
 206 File <file name>;
 207 .br
 208 Syslog;
 209 .in -5
 210 };
 211 .PP
 212 Where a host address needs to be specified in the configuration file,
 213 either a DNS name or an IP address in dotted decimal format can
 214 be used.
 215 .PP
 216 ATM addresses are specified as strings of hex digits, with an
 217 optional leading "0x".
 218 Fields within the address may be separated by periods, but periods
 219 are for readability only and are ignored.
 220 ATM addresses are 20 bytes long.
 221 The full address, including any leading zeroes, must be given.
 222 For example:
 223 .in +5
 224 0x47.0005.80.ffe100.0000.f21a.0170.0020481a0170.00
 225 .in -5
 226
 227 .SS "Server Statement"
 228 The \fBserver\fP statement specifies a client server whose cache
 229 to be synchronized with the caches of other servers
 230 running on remote hosts.
 231 There will be one \fBserver\fP statement in the configuration file
 232 for each client server whose cache is to be synchronized by \fIscspd\fP.
 233 The format of the \fBserver\fP statement is:
 234 .ti +5
 235 \fBServer <name> { <statements> };\fP
 236
 237 A name must be specified on the \fBserver\fP statement, but it is
 238 not used by \fIscspd\fP.
 239 It is expected to give a brief description of the server's purpose.
 240
 241 The \fBserver\fP statement has several sub-statements
 242 that specify the details of the \fIscspd\fP's configuration.
 243 They are:
 244 .IP "\fBProtocol ATMARP;\fP" 5
 245 The only protocol supported by the current version of \fIscspd\fP
 246 is ATMARP.
 247 The \fBprotocol\fP statement must always be specified.
 248 .IP "\fBNetif <intf>;\fP" 5
 249 The \fBnetif\fP statement specifies the name of the ATM network
 250 interface on which a client server is providing service.
 251 The \fBnetif\fP statement must always be specified.
 252 .IP "\fBServerGroupID <ID>;\fP" 5
 253 The \fBServerGroupID\fP statement specifies an identifier for the
 254 group of servers being synchronized by \fIscspd\fP.
 255 The ID is specified as a decimal number in the range 0 - 65,535.
 256 The server group ID must be the same for all servers whose caches
 257 are being synchronized by an SCSP session.
 258 That is, the server group ID for a host must be the same for all
 259 Directly Connected Servers (DCSs) pointed to within a
 260 \fBserver\fP statement.
 261 The \fBServerGroupID\fP statement must always be specified.
 262 .IP "\fBFamilyID <ID>;\fP" 5
 263 The \fBfamilyID\fP statement specifies an identifier for a family
 264 of parallel SCSP sessions running between a group of hosts (i.e. a
 265 set of SCSP sessions with different protocol IDs but the same set
 266 of servers).
 267 The ID is specified as a decimal number in the range 0 - 65,535.
 268 The family ID is currently not used by \fIscspd\fP.
 269
 270 .SS "DCS Statement"
 271 The \fBDCS\fP statement is a sub-statement of the \fBserver\fP statement
 272 that specifies the characteristics of a Directly Connected Server (DCS).
 273 The \fBserver\fP statement will have one \fBDCS\fP statement for
 274 each DCS that \fIscspd\fP is to exchange information with.
 275 The \fBDCS\fP statement has a number of sub-statements that specify the
 276 details of the configuration for the DCS.  They are:
 277 .IP "\fBATMaddr <ATM address>;\fP" 5
 278 The \fBATMaddr\fP statement specifies the ATM address of the DCS.
 279 The \fBATMaddr\fP statement must always be specified.
 280 .IP "\fBID <host>;\fP" 5
 281 The \fBID\fP statement specifies the SCSP identifier of the DCS.
 282 For ATMARP, the ID is the IP address or DNS name associated with the
 283 ATM interface of the DCS.
 284 The \fBID\fP statement must always be specified.
 285 .IP "\fBCAReXmitInt <int>;\fP" 5
 286 The \fBCAReXmitInt\fP statement specifies the interval that is
 287 allowed to elapse between retransmissions of CA messages.
 288 If a CA message is sent and an acknowledgement is not received within
 289 CAReXmitInt seconds, the message will be retransmitted.
 290 The default value for \fBCAReXmitInt\fP is 3 seconds.
 291 .IP "\fBCSUSReXmitInt <int>;\fP" 5
 292 The \fBCSUSReXmitInt\fP statement specifies the interval that is
 293 allowed to elapse between retransmissions of CSU Solicit messages.
 294 When a CSUS message is sent, any Cache State Advertisements (CSAs)
 295 requested by the CSUS that have
 296 not been received within CSUSReXmitInt seconds will be requested
 297 again by another CSUS message.
 298 The default value for \fBCSUSReXmitInt\fP is 3 seconds.
 299 Be careful not to confuse \fBCSUSReXmitInt\fP and \fBCSUReXmitInt\fP.
 300 .IP "\fBCSUReXmitInt <int>;\fP" 5
 301 The \fBCSUReXmitInt\fP statement specifies the interval that is
 302 allowed to elapse between retransmissions of CSU Request messages.
 303 When a CSU Request message is sent, any CSAs that are not acknowledged
 304 by a CSU Reply message within CSUReXmitInt seconds will
 305 be retransmitted.
 306 The default value for \fBCSUReXmitInt\fP is 2 seconds.
 307 Be careful not to confuse \fBCSUReXmitInt\fP and \fBCSUSReXmitInt\fP.
 308 .IP "\fBCSUReXmitMax <cnt>;\fP" 5
 309 The \fBCSUReXmitMax\fP statement specifies the number of times that
 310 a CSA will be retransmitted as described above before SCSP gives up
 311 on the CSA and discards it.
 312 The default value for \fBCSUReXmitMax\fP is 5.
 313 .IP "\fBHelloDead <cnt>;\fP" 5
 314 The \fBHelloDead\fP statement specifies the Hello Dead Factor that
 315 will be sent to the DCS in Hello messages.
 316 A "DCS down" condition will be detected when nothing is received from
 317 a DCS in HelloDead * HelloInt seconds.
 318 The default value for \fBHelloDead\fP is 3.
 319 .IP "\fBHelloInt <int>;\fP" 5
 320 The \fBHelloInt\fP statement specifies the Hello Interval that
 321 will be sent to the DCS in Hello messages.
 322 The default value for \fBHelloInt\fP is 3 seconds.
 323 .IP "\fBHops <cnt>;\fP" 5
 324 The \fBHops\fP statement specifies the number of hops (DCS to DCS)
 325 that will be specified in CSAs originating from the local server.
 326 This number must be at least as large as the diameter of the
 327 server group.
 328 That is, it must be large enough for a CSA to be propagated from
 329 server to server all the way across the server group.
 330 The default value for \fBHops\fP is 3.
 331
 332 .SS "Log Statement"
 333 The \fBlog\fP statement specifies how \fIscspd\fP is to log
 334 information about its operation.
 335 \fIScspd\fP can write log information to a file, to the system log,
 336 or both.
 337 .IP "\fBFile <file name>;\fP" 5
 338 The \fBfile\fP statement specifies that \fIscspd\fP is to write
 339 its log messages to the named file.
 340 Log messages will be appended to the end of the file if
 341 it already exists.
 342 .IP "\fBSyslog;\fP" 5
 343 The \fBsyslog\fP statement specifies that \fIscspd\fP is to write
 344 its log messages to the syslog facility.
 345 \fIScspd\fP writes its messages to syslog with a facility code
 346 of LOG_DAEMON.
 347
 348 .in -5
 349 If no \fBlog\fP statement is specified, \fIscspd\fP writes log
 350 messages to the system log.
 351 If both \fBfile\fP and \fBsyslog\fP are specified, \fIscspd\fP will
 352 write log messages to both the named file and the system log.
 353
 354 .SS Examples
 355
 356 An example of a simple configuration file for \fIscspd\fP might be:
 357 .in +5
 358 server atmarp_ni0 {
 359 .in +5
 360 protocol ATMARP;
 361 .br
 362 netif ni0;
 363 .br
 364 ServerGroupID 23;
 365 .br
 366 DCS {
 367 .in +5
 368 .br
 369 ID 10.1.1.2;
 370 .br
 371 ATMaddr 0x47.0005.80.ffdc00.0000.0002.0001.002048061de7.00;
 372 .br
 373 hops 2;
 374 .in -5
 375 };
 376 .in -5
 377 };
 378 .in -5
 379
 380 This configuration would synchronize the cache of the ATMARP server
 381 operating on network interface ni0 with the cache of a second server
 382 running on a host whose IP address is 10.1.1.2.
 383 Log messages would be written to the system log.
 384
 385
 386 .SH SIGNAL PROCESSING
 387 The following signals can be used to control \fIscspd\fP:
 388
 389 .IP \fBSIGHUP\fP 10
 390 Reread the configuration file and restart \fIscspd\fP.
 391
 392 .IP \fBSIGINT\fP 10
 393 Dump debugging information to a file.
 394 When it receives a SIGINT signal, \fIscspd\fP dumps a summary of
 395 its control blocks to a text file (see "\fBFILES\fP").
 396
 397 .SH FILES
 398
 399 .IP "/etc/scspd.conf"
 400 \fIScspd\fP default configuration file name.
 401 A different file name can be specified with the \fB-f\fP command-line
 402 option.
 403
 404 .IP "/tmp/scspd.<pid>.<seq>.out"
 405 Debugging information dump file name.
 406 \fIScspd\fP writes a summary of its control blocks to this file
 407 when it receives a SIGINT signal.
 408 <pid> is the process ID of the daemon and <seq> is a sequence
 409 number which is incremented every time a dump is taken.
 410
 411 .IP "/tmp/scspd.<pid>.trace"
 412 Trace file.
 413 \fIScspd\fP writes trace information to this file if the \fB-T\fP
 414 option is specified on the command line.
 415
 416 .SH "SEE ALSO"
 417 \fIatm\fP (8);
 418 \fIatmarpd\fP (8);
 419 RFC 2334, \fIServer Cache Synchronization Protocol (SCSP)\fP;
 420 draft-ietf-ion-scsp-atmarpd-00.txt, \fIA Distributed ATMARP Service
 421 Using SCSP\fP.
 422
 423
 424 .SH BUGS
 425 If \fIscspd\fP terminates and is restarted, there will be a period of
 426 instability while previously-synchronized cache entries time out and are
 427 refreshed.
 428
 429 Please report any bugs to harp-bugs@magic.net.
 430
 431 .SH COPYRIGHT
 432 Copyright (c) 1994-1998, Network Computing Services, Inc.
 433
 434 .SH AUTHORS
 435 John Cavanaugh, Network Computing Services, Inc.
 436 .br
 437 Mike Spengler, Network Computing Services, Inc.
 438 .br
 439 Joe Thomas, Network Computing Services, Inc.
 440 .fi
 441 .SH ACKNOWLEDGMENTS
 442 This software was developed with the support of the Defense
 443 Advanced Research Projects Agency (DARPA).