diff options
Diffstat (limited to 'usr.sbin/atm/scspd/scspd.8')
| -rw-r--r-- | usr.sbin/atm/scspd/scspd.8 | 443 |
1 files changed, 443 insertions, 0 deletions
diff --git a/usr.sbin/atm/scspd/scspd.8 b/usr.sbin/atm/scspd/scspd.8 new file mode 100644 index 0000000..1a9b0ab --- /dev/null +++ b/usr.sbin/atm/scspd/scspd.8 @@ -0,0 +1,443 @@ +.\" +.\" =================================== +.\" HARP | Host ATM Research Platform +.\" =================================== +.\" +.\" +.\" This Host ATM Research Platform ("HARP") file (the "Software") is +.\" made available by Network Computing Services, Inc. ("NetworkCS") +.\" "AS IS". NetworkCS does not provide maintenance, improvements or +.\" support of any kind. +.\" +.\" NETWORKCS MAKES NO WARRANTIES OR REPRESENTATIONS, EXPRESS OR IMPLIED, +.\" INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY +.\" AND FITNESS FOR A PARTICULAR PURPOSE, AS TO ANY ELEMENT OF THE +.\" SOFTWARE OR ANY SUPPORT PROVIDED IN CONNECTION WITH THIS SOFTWARE. +.\" In no event shall NetworkCS be responsible for any damages, including +.\" but not limited to consequential damages, arising from or relating to +.\" any use of the Software or related support. +.\" +.\" Copyright 1994-1998 Network Computing Services, Inc. +.\" +.\" Copies of this Software may be made, however, the above copyright +.\" notice must be reproduced on all copies. +.\" +.\" @(#) $Id: scspd.1,v 1.2 1998/08/26 21:39:38 johnc Exp $ +.\" +.\" +.de EX \"Begin example +.ne 5 +.if n .sp 1 +.if t .sp .5 +.nf +.in +.5i +.. +.de EE +.fi +.in -.5i +.if n .sp 1 +.if t .sp .5 +.. +.TH SCSPD 8 "1998-08-21" "HARP" + +.SH NAME +scspd \- SCSP daemon +.SH SYNOPSIS +.B scspd +[\fB-f\fP <cfg-file>] +[\fB-d\fP] +[\fB-T\fP<options>] + +.SH DESCRIPTION +\fIScspd\fP is an implementation of the Server Cache Synchronization +Protocol (SCSP) for the Host ATM Research Platform (HARP) +networking software. +\fIScspd\fP synchronizes the cache(s) of server(s) +running on a host with the caches of servers on remote hosts. +SCSP is defined for a number of different protocols, but the present +version of \fIscspd\fP only supports ATMARP. +.PP +By using \fIscspd\fP and \fIatmarpd\fP, one can provide multiple +ATMARP servers in a single ATM LIS. +This might be useful, for example, when a LIS consists of a number of +local-area ATM networks connected by long-distance links. +Each local-area network could have its own ATMARP server, with all the +servers' caches being synchronized by SCSP. +Then, if a long-distance link fails, hosts on a local-area network +will still have connectivity to other local hosts (since they all use +the local ATMARP server); when the long-distance link is restored, +SCSP will re-synchronize the servers' caches, restoring +connectivity to remote hosts. +Both \fIscspd\fP and \fIatmarpd\fP must be running before any ATMARP +cache synchronization can take place. +.PP +\fIScspd\fP implements SCSP as specified in RFC 2334, \fIServer Cache +Synchronization Protocol (SCSP)\fP and +draft-ietf-ion-scspd-atmarpd-00.txt, \fIA Distributed ATMARP Service +using SCSP\fP. + +When \fIscspd\fP starts, it parses its command line and puts +itself into the background. + +.SH TERMINOLOGY +Some of the vocabulary associated with SCSP can be confusing. +In this document, the following definitions are used: + +\fBClient server\fP or \fBlocal server\fP means the server running on +the same host as \fIscspd\fP whose cache is to be synchronized with that +of one or more remote servers. +When the word \fBserver\fP is used alone, it means "client server". + +\fBRemote server\fP means a server running on some host other than +the one where \fIscspd\fP is running. + +\fBDirectly Connected Server\fP (DCS) means a remote server that +\fIscspd\fP communicates with directly. +The remote server will also be running an implementation of SCSP. + +\fBCache Alignment\fP (CA) has two meanings. +The Cache Alignment protocol is a part of the SCSP protocol +specification, and the Cache Alignment finite state machine (FSM) +is a finite state machine that implements the Cache Alignment +protocol. + +.SH OPTIONS +The command-line options are: +.IP "\fB-f\fP <cfg-file>" 15 +Specifies the name of the configuration file. +If this option is not specified, \fIscspd\fP looks for the +file /etc/scspd.conf. +.IP "\fB-d\fP" 15 +Specifies that \fIscspd\fP is to be run in debug mode. +In debug mode, the daemon is not put into the background. +Log messages are written to standard output instead of to +the log file specified in the configuration file. +.IP "\fB-T\fP<options>" 15 +Specifies that \fIscspd\fP will trace specified events and messages +as it executes. +The \fB-T\fP flag is followed by one or more of the following +options: +.in +4 +.ti -4 +\fBc\fP\ -\ trace \fIscspd\fP's CA Finite State Machine (FSM), +.ti -4 +\fBh\fP\ -\ trace \fIscspd\fP's Hello FSM, +.ti -4 +\fBi\fP\ -\ trace \fIscspd\fP's Client Interface FSM, +.ti -4 +\fBC\fP\ -\ trace CA, CSUS, CSU Request, and CSU Reply messages, +.ti -4 +\fBH\fP\ -\ trace Hello messages, +.ti -4 +\fBI\fP\ -\ trace interface messages to and from \fIscspd\fP's +clients. +.in -4 +.SH CONFIGURATION + +The configuration file consists of a sequence of configuration +statements. +These statements specify information about the servers, +both local and remote, whose +caches are to be synchronized by \fIscspd\fP. +RFC 2334, \fIServer Cache +Synchronization Protocol (SCSP)\fP and +draft-ietf-ion-scspd-atmarpd-00.txt, \fIA Distributed ATMARP Service +using SCSP\fP +will be valuable in understanding how to configure \fIscspd\fP. + +A configuration statement other than a comment is terminated by a +semicolon. +Some statements contain blocks, delimited by braces ("{" and "}"). +Configuration statement keywords are not case-sensitive, +but some parameters (e.g. interface names) are. +Configuration statments can span multiple lines. + +.SS Comments +Three types of comments are allowed: + +\fB# comments\fP: +any characters from "#" to the end of the line are ignored. + +\fBC comments\fP: +any characters between "/*" and "*/" are ignored. + +\fBC++ comments\fP: +any characters from "//" to the end of the line are ignored. + +.SS "Statements" +The configuration statements recognized by \fIscspd\fP are: + +Server <name> { +.in +5 +Protocol <protocol ID>; +.br +Netif <if_name>; +.br +ServerGroupID <ID>; +.br +FamilyID <ID>; +.br +DCS { +.in +5 +ATMaddr <ATM address>; +.br +ID <host>; +.br +CAReXmitInt <int>; +.br +CSUSReXmitInt <int>; +.br +CSUReXmitInt <int>; +.br +CSUReXmitMax <cnt>; +.br +HelloDead <cnt>; +.br +HelloInt <int>; +.br +Hops <cnt>; +.in -5 +}; +.in -5 +}; +.sp +Log { +.in +5 +File <file name>; +.br +Syslog; +.in -5 +}; +.PP +Where a host address needs to be specified in the configuration file, +either a DNS name or an IP address in dotted decimal format can +be used. +.PP +ATM addresses are specified as strings of hex digits, with an +optional leading "0x". +Fields within the address may be separated by periods, but periods +are for readability only and are ignored. +ATM addresses are 20 bytes long. +The full address, including any leading zeroes, must be given. +For example: +.in +5 +0x47.0005.80.ffe100.0000.f21a.0170.0020481a0170.00 +.in -5 + +.SS "Server Statement" +The \fBserver\fP statement specifies a client server whose cache +to be synchronized with the caches of other servers +running on remote hosts. +There will be one \fBserver\fP statement in the configuration file +for each client server whose cache is to be synchronized by \fIscspd\fP. +The format of the \fBserver\fP statement is: +.ti +5 +\fBServer <name> { <statements> };\fP + +A name must be specified on the \fBserver\fP statement, but it is +not used by \fIscspd\fP. +It is expected to give a brief description of the server's purpose. + +The \fBserver\fP statement has several sub-statements +that specify the details of the \fIscspd\fP's configuration. +They are: +.IP "\fBProtocol ATMARP;\fP" 5 +The only protocol supported by the current version of \fIscspd\fP +is ATMARP. +The \fBprotocol\fP statement must always be specified. +.IP "\fBNetif <intf>;\fP" 5 +The \fBnetif\fP statement specifies the name of the ATM network +interface on which a client server is providing service. +The \fBnetif\fP statement must always be specified. +.IP "\fBServerGroupID <ID>;\fP" 5 +The \fBServerGroupID\fP statement specifies an identifier for the +group of servers being synchronized by \fIscspd\fP. +The ID is specified as a decimal number in the range 0 - 65,535. +The server group ID must be the same for all servers whose caches +are being synchronized by an SCSP session. +That is, the server group ID for a host must be the same for all +Directly Connected Servers (DCSs) pointed to within a +\fBserver\fP statement. +The \fBServerGroupID\fP statement must always be specified. +.IP "\fBFamilyID <ID>;\fP" 5 +The \fBfamilyID\fP statement specifies an identifier for a family +of parallel SCSP sessions running between a group of hosts (i.e. a +set of SCSP sessions with different protocol IDs but the same set +of servers). +The ID is specified as a decimal number in the range 0 - 65,535. +The family ID is currently not used by \fIscspd\fP. + +.SS "DCS Statement" +The \fBDCS\fP statement is a sub-statement of the \fBserver\fP statement +that specifies the characteristics of a Directly Connected Server (DCS). +The \fBserver\fP statement will have one \fBDCS\fP statement for +each DCS that \fIscspd\fP is to exchange information with. +The \fBDCS\fP statement has a number of sub-statements that specify the +details of the configuration for the DCS. They are: +.IP "\fBATMaddr <ATM address>;\fP" 5 +The \fBATMaddr\fP statement specifies the ATM address of the DCS. +The \fBATMaddr\fP statement must always be specified. +.IP "\fBID <host>;\fP" 5 +The \fBID\fP statement specifies the SCSP identifier of the DCS. +For ATMARP, the ID is the IP address or DNS name associated with the +ATM interface of the DCS. +The \fBID\fP statement must always be specified. +.IP "\fBCAReXmitInt <int>;\fP" 5 +The \fBCAReXmitInt\fP statement specifies the interval that is +allowed to elapse between retransmissions of CA messages. +If a CA message is sent and an acknowledgement is not received within +CAReXmitInt seconds, the message will be retransmitted. +The default value for \fBCAReXmitInt\fP is 3 seconds. +.IP "\fBCSUSReXmitInt <int>;\fP" 5 +The \fBCSUSReXmitInt\fP statement specifies the interval that is +allowed to elapse between retransmissions of CSU Solicit messages. +When a CSUS message is sent, any Cache State Advertisements (CSAs) +requested by the CSUS that have +not been received within CSUSReXmitInt seconds will be requested +again by another CSUS message. +The default value for \fBCSUSReXmitInt\fP is 3 seconds. +Be careful not to confuse \fBCSUSReXmitInt\fP and \fBCSUReXmitInt\fP. +.IP "\fBCSUReXmitInt <int>;\fP" 5 +The \fBCSUReXmitInt\fP statement specifies the interval that is +allowed to elapse between retransmissions of CSU Request messages. +When a CSU Request message is sent, any CSAs that are not acknowledged +by a CSU Reply message within CSUReXmitInt seconds will +be retransmitted. +The default value for \fBCSUReXmitInt\fP is 2 seconds. +Be careful not to confuse \fBCSUReXmitInt\fP and \fBCSUSReXmitInt\fP. +.IP "\fBCSUReXmitMax <cnt>;\fP" 5 +The \fBCSUReXmitMax\fP statement specifies the number of times that +a CSA will be retransmitted as described above before SCSP gives up +on the CSA and discards it. +The default value for \fBCSUReXmitMax\fP is 5. +.IP "\fBHelloDead <cnt>;\fP" 5 +The \fBHelloDead\fP statement specifies the Hello Dead Factor that +will be sent to the DCS in Hello messages. +A "DCS down" condition will be detected when nothing is received from +a DCS in HelloDead * HelloInt seconds. +The default value for \fBHelloDead\fP is 3. +.IP "\fBHelloInt <int>;\fP" 5 +The \fBHelloInt\fP statement specifies the Hello Interval that +will be sent to the DCS in Hello messages. +The default value for \fBHelloInt\fP is 3 seconds. +.IP "\fBHops <cnt>;\fP" 5 +The \fBHops\fP statement specifies the number of hops (DCS to DCS) +that will be specified in CSAs originating from the local server. +This number must be at least as large as the diameter of the +server group. +That is, it must be large enough for a CSA to be propagated from +server to server all the way across the server group. +The default value for \fBHops\fP is 3. + +.SS "Log Statement" +The \fBlog\fP statement specifies how \fIscspd\fP is to log +information about its operation. +\fIScspd\fP can write log information to a file, to the system log, +or both. +.IP "\fBFile <file name>;\fP" 5 +The \fBfile\fP statement specifies that \fIscspd\fP is to write +its log messages to the named file. +Log messages will be appended to the end of the file if +it already exists. +.IP "\fBSyslog;\fP" 5 +The \fBsyslog\fP statement specifies that \fIscspd\fP is to write +its log messages to the syslog facility. +\fIScspd\fP writes its messages to syslog with a facility code +of LOG_DAEMON. + +.in -5 +If no \fBlog\fP statement is specified, \fIscspd\fP writes log +messages to the system log. +If both \fBfile\fP and \fBsyslog\fP are specified, \fIscspd\fP will +write log messages to both the named file and the system log. + +.SS Examples + +An example of a simple configuration file for \fIscspd\fP might be: +.in +5 +server atmarp_ni0 { +.in +5 +protocol ATMARP; +.br +netif ni0; +.br +ServerGroupID 23; +.br +DCS { +.in +5 +.br +ID 10.1.1.2; +.br +ATMaddr 0x47.0005.80.ffdc00.0000.0002.0001.002048061de7.00; +.br +hops 2; +.in -5 +}; +.in -5 +}; +.in -5 + +This configuration would synchronize the cache of the ATMARP server +operating on network interface ni0 with the cache of a second server +running on a host whose IP address is 10.1.1.2. +Log messages would be written to the system log. + + +.SH SIGNAL PROCESSING +The following signals can be used to control \fIscspd\fP: + +.IP \fBSIGHUP\fP 10 +Reread the configuration file and restart \fIscspd\fP. + +.IP \fBSIGINT\fP 10 +Dump debugging information to a file. +When it receives a SIGINT signal, \fIscspd\fP dumps a summary of +its control blocks to a text file (see "\fBFILES\fP"). + +.SH FILES + +.IP "/etc/scspd.conf" +\fIScspd\fP default configuration file name. +A different file name can be specified with the \fB-f\fP command-line +option. + +.IP "/tmp/scspd.<pid>.<seq>.out" +Debugging information dump file name. +\fIScspd\fP writes a summary of its control blocks to this file +when it receives a SIGINT signal. +<pid> is the process ID of the daemon and <seq> is a sequence +number which is incremented every time a dump is taken. + +.IP "/tmp/scspd.<pid>.trace" +Trace file. +\fIScspd\fP writes trace information to this file if the \fB-T\fP +option is specified on the command line. + +.SH "SEE ALSO" +\fIatm\fP (8); +\fIatmarpd\fP (8); +RFC 2334, \fIServer Cache Synchronization Protocol (SCSP)\fP; +draft-ietf-ion-scsp-atmarpd-00.txt, \fIA Distributed ATMARP Service +Using SCSP\fP. + + +.SH BUGS +If \fIscspd\fP terminates and is restarted, there will be a period of +instability while previously-synchronized cache entries time out and are +refreshed. + +Please report any bugs to harp-bugs@magic.net. + +.SH COPYRIGHT +Copyright (c) 1994-1998, Network Computing Services, Inc. + +.SH AUTHORS +John Cavanaugh, Network Computing Services, Inc. +.br +Mike Spengler, Network Computing Services, Inc. +.br +Joe Thomas, Network Computing Services, Inc. +.fi +.SH ACKNOWLEDGMENTS +This software was developed with the support of the Defense +Advanced Research Projects Agency (DARPA). |
