Chapter 4 - Server Service, Security, and STDA
This chapter discusses three important services that are closely related to the StreetTalk Directory service: Server service, VINES Security service, and STDA. The purpose of each service discussed in this chapter is as follows:
VINES Security service - Governs password security on the server. When a user logs in, VSS queries StreetTalk to verify that the user exists, and that the user has entered the correct password. VSS files are maintained in /disk1/banyan/vs.
Server service - Monitors services on the server, and starts and stops services as appropriate. Its files are maintained in the /disk1/banyan/ss directory.
STDA - Collects names from the StreetTalk database and maintains those names in a database that is quickly accessible by users. STDA collects names from StreetTalk according to a schedule established by the server administrator. STDA service files are maintained in /disk1/banyan/stda. Database files for the service are maintained in a user-configurable data area.
The VINES Security Service is responsible for the following:
User security Password security Client authentication Internetwork security User profile access
The /disk1/banyan/vs directory contains the VINES Security service. The files in the this directory are as follows:
usld (ASCII)
User license information.
van.err (ASCII)
Contains VINES Security service error text.
VS (Executable)
VINES Security service executable.
vsanly (Executable)
VINES Security service database analyzer.
vsclient (Executable)
Tests the VINES Security Service API functions.
VSses.db (Database)
Contains session database records. This file allows for recovery of sessions across Vines Security service restarts.
VSses.db# (Database)
Temporary file created at startup.
amsevents.map (Database)
Standard Banyan service file, as explained in Table 1-2.
cleanup (Script)
Standard Banyan service file, as explained in Table 1-2.
cores (Directory)
Standard Banyan service directory, as explained in Table 1-2.
dumpscript (Script)
Standard Banyan service file, as explained in Table 1-2.
startup (Script)
Standard Banyan service file, as explained in Table 1-2.
svclogn (ASCII)
Standard Banyan service file, as explained in Table 1-2.
SvcLogs (ASCII)
Standard Banyan service file, as explained in Table 1-2.
VS0.log (ASCII)
Standard Banyan service file, as explained in Table 1-2.
VS1.log (ASCII)
Standard Banyan service file, as explained in Table 1-2.
Troubleshooting the VINES Security Service
The VINES Security service has proven over time to be a solid and reliable piece of software. Typically, the only part of the service that causes problems is the VSses.db file. When this file is corrupted, the VINES Security service becomes inoperative.
To solve this problem, delete VSSess.db and restart services. The VINES Security service rebuilds the session database during initialization. VS should then run without difficulty.
Server service is a Banyan network service that has the following responsibilities:
Starts services after the server reboots Restarts services that die unexpectedly Creates, destroys, starts, and stops services Maintains network time
Server service files reside in the directory /disk1/banyan/ss and its subdirectories.
The directory structure for /disk1/banyan/ss is shown in Figure 4-1.
The contents of /disk1/banyan/ss are as follows:
addafpscript (Script)
Adds an AFP service. This script installs the service name in the StreetTalk database and adds a line to svc3.db.
addatascript (Script)
Adds an Appletalk Agent service. This script installs the service name in the StreetTalk database and adds a line to svc3.db.
addevsscript (Script)
Adds an Event Management service. This script installs the service name in the StreetTalk database and adds a line to svc3.db.
addnmsscript (Script)
Adds a Network Management service. This script installs the service name in the StreetTalk database and adds a line to svc3.db.
addsnmscript (Script)
Adds a revision 5.00 Network Management service. This script installs the service name in the StreetTalk database and adds a line to svc3.db.
addsvclog (ASCII)
Log file for all of the add???script files. It shows the stclient dialogue that adds each service to the StreetTalk database.
addsvcscript (Script)
This script runs when the server is booted for the first time. It calls other add scripts in this directory to add the basic Banyan services to the server.
addvpascript (Script)
Adds a VINES Proxy Agent. This script installs the service name in the StreetTalk database and adds a line to svc3.db.
addwanscript (Script)
Adds the Wide Area Network service. This script installs the name in the StreetTalk database and adds a line to svc3.db.
chgvsscript (Script)
Renames the Vanguard service to VS. This occurs during upgrades of the Banyan server from earlier revisions.
conlock (ASCII)
Contains the word "locked" if server console locking is in effect. Contains the word "unlocked" if no console locking is in effect.
errstart (Script)
Starts the error daemon, and writes the process ID of the daemon process to the file /errpid.
masterdump (Script)
Template that can be used to create customized dump scripts. Every service area should have a dump script, which is a script that copies cores and other service information to a tape.
PATCH (Executable)
Runs whenever someone runs the patch.exe program from a client.
patches (Directory)
Contains files that describe the site-specific patch history for the server.
pgms3.bak (Database)
Backup copy of pgms3.db.
pgms3.db (Database)
Contains a list of all services on the system, along with management parameters for Server service.
printer.cnf (ASCII)
Contains all configured printer destinations, whether local (serial and parallel ports) or remote.
reboot (Executable)
Called by Server service after a patch to reboot the server.
remlogin (Executable)
Remote login program. This is used by the Banyan Support Center to dial in to a server.
ser.err (ASCII)
Server service error file.
setterm (Executable)
Sets the operator console terminal type.
ss (Executable)
Server service executable.
ssclient (Executable)
Client program used to test calls to Server service.
ssname (ASCII)
Contains the name of the server.
startss (Script)
Starts Server service, and performs a number of tasks necessary for upgrades from earlier versions of Banyan software.
SvcAttrs (ASCII)
Contains the names of all services on the system, along with the service log mask for each service.
svc.db (Database)
Obsolete. The working database file for Server service is svc3.db.
svc3.db (Database)
Contains names and operating parameters of each service configured on the server. This is used by Server service to determine which services to initialize during the server initialization.
sftopts.db
Database for software option codess configured on the server.
sysopts.db (Database)
Database of all options configured on the server.
termclr (ASCII)
Used by bmenu and other scripts to clear the server console.
termtype (ASCII)
Contains the name of the terminal type used for the system console.
termtype.sav (ASCII)
Backup copy of the system console terminal type.
watchdog (Executable)
Monitors activity with LAN cards in the bus, and starts scheduled system backups.
watchdog31d356 (Database)
Watchdog dump file.
amsevents.map (Database)
Standard Banyan service file, as described in Table 1-2.
cleanup (Script)
Standard Banyan service file, as described in Table 1-2.
cores (Directory)
Standard Banyan service directory, as described in Table 1-2.
dumpscript (Script)
Standard Banyan service file, as described in Table 1-2.
startup (Script)
Standard Banyan service file, as described in Table 1-2.
svclogn (ASCII)
Standard Banyan service file, as described in Table 1-2.
SvcLogs (ASCII)
Standard Banyan service file, as described in Table 1-2.
The pgms3.db file contains a line describing each type of service you can install on the server. Each line in the file can contain up to eleven fields.
The first six fields within the pgms3.db database are required, The last five fields are optional. The fields in the pgms3.db file are as follows:
type - An acronym of the service name.
category - A unique number for the service assigned in category.mm
limit - The number of services of this type that can be started on the server. You can create more, but only this number can be running at any one time.
description - The product name.
home dir - The home directory of the service.
base - (Y or N) Whether or not this is a base service.
visible - (Y or N) Whether or not the service is visible to users via OPERATE and MSERVICE. All services should be visible through MNET.
rpc - (Y or N) Whether or not the service responds to RPCs necessary to report status.
maxcreate - The number of services of this type that can be created on a server.
dumpable - (Y or N) Whether this service is backed up during a full or incremental backup.
changeuser - (Y or N) Whether or not the user can change the UNIX user this service runs as. This applies to ENS for UNIX servers only.
Server service manages other services on a Banyan server. On a server reboot, Server service is launched by the /.profile script. It can also be started from the System Maintenance menu on the console. Server service is started with the following command line:
startss
When the system starts, Server service performs the following tasks:
1. Initializes in-memory versions of pgms3.db and svc3.db.
2. Reads error codes and help files in the /disk1/BFS/VINESFiles directory.
3. Starts StreetTalk and the VINES Security service.
If either if these services does not start, Server service aborts with an appropriate message.
4. Initializes the Time service. This is internal to Server service, and is used to synchronize the time between servers on the network.
5. Starts remaining services based on their state records in svc3.db.
6. Reads /disk1/local/svc.db and incorporates it into svc3.db. The /disk1/local/svc.db file contains parameters for third-party services running on the system. The structure and purpose of this file is explained in the Banyan Applications Toolkit documentation.
7. Reads /disk1/local/pgms.db and incorporates it into pgms3.db. The /disk1/local/pgms.db file contains parameters for third-party services running on the system. The structure and purpose of this file is explained in the Banyan Applications Toolkit documentation.
Managing Services with Server Service
Each service directory contains three scripts that Server service uses to manage services:
create - Used in adding a service
destroy - Used in deleting a service
startup - Used in starting a service
These functions are controlled from MSERVICE, and they differ slightly from service to service.
Adding a Service
When a server administrator adds a service to a server, this procedure occurs:
1. MSERVICE adds the new service StreetTalk name and any configuration data to the StreetTalk database.
2. MSERVICE calls Server service with a request to create a new service.
3. Server service scans an internal version of pgms3.db to ensure that the type of service created exists and is enabled.
4. Server service forks a UNIX shell to execute the create script that resides in the home directory of the service.
5. The create script initializes the service and its instance data. Most services allow you to run more than one instance of the service per server. For example, you can have many Banyan File services on a single server.
The create script also maintains the SvcTable file, which maps between the service home directory and its data directory. It is used to pass a service's data directory to its executable at startup. It is also used by backup/restore to find a service's data.
6. Server service updates svc3.db to include information on the new service.
Deleting a Service
When a server administrator deletes a service, this procedure occurs:
1. MSERVICE calls Server service with a request to delete the StreetTalk name and StreetTalk data for that service.
2. Server service forks a UNIX shell to execute the destroy script that resides in the home directory of the service.
3. The destroy script deletes the service instance data. It also deletes the entry for the service from the SvcTable file.
4. Server service removes the service from svc3.db.
5. MSERVICE removes the StreetTalk name from the StreetTalk database.
Starting a Service
When a server administrator starts a service, this procedure occurs:
1. MSERVICE calls Server service with a request to start the service.
2. Server service forks a UNIX shell to execute the startup script that resides in the home directory of the service.
3. The startup script run the service executable with the appropriate switches.
4. Server service changes the status of the service in svc3.db to "running".
StreetTalk Directory Assistance
StreetTalk Directory Assistance is a Banyan service that collects StreetTalk data and makes it quickly available to Banyan users. This section discussed the structure of STDA service and data directories, and a utility called xda that allows you to examine STDA data files.
STDA has a service directory (/disk1/banyan/stda) and a data directory area (/diskn/STDA). The structure of the STDA directories is shown in Figure 4-2.
/disk1/banyan/stda
There are two important executables in /disk1/banyan/stda:
stda - This is the service executable.
getnames - This executable performs downloads from other STDA services, and builds the local databases that STDA uses to respond to client requests. These local databases are called STDA display databases. They reside in /diskn/STDA/DB.
The files in /disk1/banyan/stda are as follows:
get0.log (ASCII)
Rolling log file for the getname process.
get1.log (ASCII)
Rolling log file for the getname process.
getnames (Executable)
Gathers naming information to be used for display data.
stda (Executable)
STDA executable.
stdaclient (Executable)
Tests the STDA API functions. Many of these functions are described in the Banyan Applications Toolkit.
stdaconv (Executable)
Converts STDA database files from Revision 4.xx to Revision 5.5x.
stdasort (Executable)
Sorts the names collected from other STDA services or StreetTalk. This program is called by getnames.
Upgrade (Script)
Upgrades STDA from a Revision 4.11 or 5.00 service to a 5.5x service.
xda (Executable)
Reads and writes STDA database files, such as the /diskn/STDA/CNG/1.wrk file. This is a menu-driven STDA analysis tool.
amsevents.map (Script)
Standard Banyan service file, as described in Table 1-2.
cleanup (Script)
Standard Banyan service file, as described in Table 1-2.
cores (Directory)
Standard Banyan service directory, as described in Table 1-2.
create (Script)
Standard Banyan service file, as described in Table 1-2.
destroy (Script)
Standard Banyan service file, as described in Table 1-2.
dumpscript (Script)
Standard Banyan service file, as described in Table 1-2.
stda0.log (ASCII)
Standard Banyan service file, as described in Table 1-2.
stda1.log (ASCII)
Standard Banyan service file, as described in Table 1-2.
startup (Script)
Standard Banyan service file, as described in Table 1-2.
svccdLog (ASCII)
Standard Banyan service file, as described in Table 1-2.
svclogn (ASCII)
Standard Banyan service file, as described in Table 1-2.
SvcLogs (ASCII)
Standard Banyan service file, as described in Table 1-2.
SvcTable (ASCII)
Standard Banyan service file, as described in Table 1-2.
/diskn/STDA
The data directory /diskn/STDA contains two directories: /diskn/STDA/CNG and /diskn/STDA/DB.
/diskn/STDA/CNG
The /diskn/STDA/CNG directory is used by the getnames program as a work area. On a satellite STDA service, files are downloaded from other STDA services, then compiled in six .wrk files. A .hsh file is generated for each .wrk file. The .hsh file is used for quickly searching data in the .wrk files.
In addition to the .hsh and .wrk files, there are other files that are downloaded from the server specified when the service was created. These files have the following naming structure:
a.b.sernum.C [seqnum] | R
where:
a is the STDA class number for the data. This is a number from 0 to 5, as follows:
0 indicates users. 1 indicates lists. 2 indicates printers. 3 indicates File services. 4 indicates other services. 5 indicates nicknames.
b is the namespace. 0 indicates StreetTalk data. 1 indicates inclusions.
sernum is the serial number of the machine that collected the information from StreetTalk. On an STDA Master service, this number is always 0.
C indicates that the file contains incremental changes to the initial network view of the data.
seqnum is a sequence number from 0 to 7f hexadecimal.
R indicates that this information is the initial network view of the data.
Figure 4-3 shows an example of a downloaded data file you might find in the /diskn/STDA/CNG directory:
In addition, there are rebuild hash files that increase the performance of a rebuild. These have names of the form:
a.b.sernum.rhsh
The files in /diskn/STDA/CNG are as follows:
0.wrk, 0.hsh (Database)
Database files of users. The 0.wrk file is the database constructed by getnames of all the individual users downloaded from the download server. The 0.hsh file helps to speed searches for records in the .wrk file.
1.wrk, 1.hsh (Database)
Database files of StreetTalk lists.
2.wrk, 2.hsh (Database)
Database files of Print services.
3.wrk ,3.hsh (Database)
Database files of File services.
4.wrk, 4.hsh (Database)
Database files of services other than File and Print services.
5.wrk, 5.hsh (Database)
Database files of StreetTalk nicknames.
Grptable.db (Database)
Contains groups enumerated by the master service, when they were enumerated, and the servers where those groups reside. This file is populated on STDA Master services, and is empty on STDA satellite services.
/diskn/STDA/DB
The files in /diskn/STDA/DB are used to present information to client programs, such as the Intelligent Messaging client. These are often referred to as front-end databases, because they contain data formatted for presentation to users.
The files in /diskn/STDA/DB are as follows:
All.db (Database)
Contains a formatted view of all the data that the STDA service can display.
All.dx (Database)
Index into All.db. This file is used for rapid database searches.
AllAttr.db (Database)
All attributes that the STDA service can display.
AllAttr.dx (Database)
Index into AllAttr.db. This file is used for rapid database searches.
Allattr1.dx (Database)
Index into the StreetTalk attributes collected by the STDA service. This file is used for rapid searches on pre-indexed attributes.
AllItem.dx (Database)
Index into all the StreetTalk item names in All.db.
sort.log
A temporary file used during sorting.
The xda utility analyzes STDA data files, and allows you to examine the data collected by the STDA service. This utility resides in /disk1/banyan/stda.
When you enter xda at the command line, this menu appears:
STDA Database Analyzer Rev. 6.00(a)
Can't get StreetTalk session. (1)
usage: xda -# [filename/service name]
Possible Commands are:
[1] Examine a file [x] Dump item adds
[2] Modify a file [y] Dump item mods
[3] Create and initialize a file [z] Dump item deletes
[4] Modify a file header
[5] Dump local control file
[6] Dump local Group file
[7] Check local group chains
[8] Dump a local group file (names only)
[9] Dump a file name (names only)
[a] Dump INFO blocks (servicename)
[b] Add INFO blocks (servicename)
[c] Del/Mod INFO block (servicename)
[C] Change database name/serial#
[t] Convert a timestamp to formatted time
[q]======> Quit
The options on this menu are discussed in the sections that follow. Some options are reserved for use by the Banyan Engineering staff.
[1] Examine a file
This option analyzes any of the files in the /diskn/STDA/CNG directory except the hash files (*.hsh). Change files, rebuild files, and work files can be analyzed.
Output from this option is divided into eight fields, and a set of vendor/attribute pairs, which are marked by the prefix v/a=. Figure 4-4 shows an example of this output.
The fields shown in Figure 4-4 are as follows:
item name
A StreetTalk item name or an inclusion name.
Note: An inclusion name is an STDA item which does not adhere to the StreetTalk naming convention. These items can be names formatted according to another directory service convention, such as an internet mailing address. For more information on inclusion names, refer to Managing Users and StreetTalk.
item class
This is the STDA class of the item. The class is one of the following:
0 = Users.
1 = lists.
2 = Printer services.
3 = File services.
4 = database files other than File and Print services.
5 = nicknames.
item name space
This field contains either 0x0 or 0x1. The value 0x0 indicates that this is a StreetTalk name. The value 0x1 indicates that this is an inclusion name.
item source
If this name is an inclusion name, the item source represents the serial number of the server to which this name was submitted through MSERVICE.
If this name is a StreetTalk name, the item source represents the serial number of the server that enumerated the name directly from the StreetTalk directory.
item attrs
This field indicates the offset of attributes associated with the item. A value of 0xFFFFFFFFindicates that there are no attributes associated with this item.
item nextName
This field is a file offset pointer to the next entry in the data file.
item misc
This field is application-dependent. It is sometimes used to differentiate between identical inclusion names.
item status
This field contains bit flags used to indicate addition (0x6), deletion (0x1) or modification (0xa) of this entry.
v/a
These fields show the vendor/attribute pairs that are associated with each name. There can be many vendor/attribute pairs associated with each name.
[2] Modify a File
This option is reserved for reserved for use by Banyan personnel.
[3] Create and initialize a file
This option is reserved for reserved for use by Banyan personnel.
[4] Modify a file header
This option is reserved for reserved for use by Banyan personnel.
[5] Dump local control file
This option analyzes the /diskn/STDA/control.DB file, and dumps STDA control structures. You must run this option from /disk1/STDA. An example of the output is shown in Figure 4-5.
Control structures are used internally by the STDA service. Each control structure determines:
The target services from which the local STDA service will download information. What data this STDA service collects.
[6] Dump local Group file
This option analyzes the /diskn/STDA/CNG/Grptable.DB file. This file contains the groups enumerated by the STDA Master service. The Grptable.DB file is zero-length on an STDA satellite service. A sample of the output from this command is shown in Figure 4-6.
Each field in this output is described in the sections that follow.
status - The status field can indicate that the group has been deleted from the StreetTalk database, but has yet to be purged from STDA.
file pos - This is the byte offset to the current record.
group name - This field contains the name of the StreetTalk group that was enumerated by the Master STDA service.
server name - This field shows the server on which the group resides.
timestamp - This field indicates the time at which STDA last successfully enumerated the group.
namespace - This option is currently not used.
location - This value is always 0x0, indicating that the location is the local server.
source - This field contains the local server serial number.
Change ID - This is a change sequence number as received from the StreetTalk service.
Enum Status - This field lists six integers indicating the enumeration status of each STDA class. The status is either 0, indicating that this class is waiting for a successful enumeration, or 1041, indicating that this class has been successfully enumerated.
[7] Check local group chains
This option dumps all the names in the STDA database, sorted by groupname and by STDA class.
[8] Dump a local group file (names only)
This option lists the StreetTalk names of the groups maintained on this server. It reads the /diskn/STDA/CNG/Grptable.db file. You must change your current directory to /diskn/STDA/CNG before you run xda with this option. Follow these steps:
1. Log in to UNIX on the server and change directory to /diskn/STDA/CNG.
2. Enter this command line:
/disk1/banyan/stda/xda -8 > out
This command directs the output of the command to the file /diskn/STDA/CNG/out.
[9] Dump a file name (names only)
This option prints all of the names collected in a .wrk file. For example, the following command writes all StreetTalk list names in the file 1.wrk to a file named out:
/disk1/banyan/stda/xda -9 /disk1/STDA/CNG/1.wrk > out
[a] Dump INFO blocks (servicename)
This option dumps info blocks for a service. Info blocks are the control structures that govern STDA downloads.
To Capture Info Blocks in a Disk File
1. Be sure your user name appears on the adminlist for your server:
2. Log in to UNIX on the server and change directory to /diskn/STDA.
3. Run xda, using this command line:
/disk1/banyan/stda/xda -a > out
This prompt appears:
STDA database analyzer Rev 5.50(e)
Can't get StreetTalk session. (1)
service name :?
4. Enter the name of the service whose info blocks you wish to analyze. This prompt appears:
VINES User name?
5. Enter your StreetTalk user name. This prompt appears:
VINES User password?
6. Enter your StreetTalk password.
The xda utility dumps the info blocks for the service into the output file, and returns to the xda main menu. The info blocks generated by this option look like Figure 4-7.
[b] Add INFO blocks (servicename)
This option is reserved for reserved for use by Banyan personnel.
[c] Del/Mod INFO block (servicename)
This option is reserved for reserved for use by Banyan personnel.
[C] Change database name/serial#
This option is reserved for reserved for use by Banyan personnel.
[t] Convert a timestamp to formatted time
This option translates the timestamp into a formatted ASCII string. The timestamp is a 32-bit UNIX GMT time. The timestamp "0x2ec6e15f" translates to "Sun Nov 13 23:02:39 1994".
[q]======>Quit
This option returns you to the UNIX prompt.
[x] Dump item adds
This option lists items added to StreetTalk since the last time the STDA database was rebuilt. These changes should be added to the STDA database after the next rebuild.
To list Item Adds to an output file
1. Log in to UNIX and change directory to /disk1/STDA/CNG.
2. Enter the following command at the UNIX prompt:
/disk1/banyan/stda/xda -x > out
This prompt appears:
STDA database analyzer Rev 5.50(e)
Can't get StreetTalk session. (1)
Enter new file name to use: ()?
3. Enter the name of the .wrk file or the change file that you want to analyze. Possible responses follow:
0.wrk - Lists user names added to the database during the last STDA rebuild.
1.wrk - Lists StreetTalk list names added to the database during the last STDA rebuild.
2.wrk - Lists StreetTalk Print service names added to the database during the last STDA rebuild.
3.wrk - Lists StreetTalk File service names added to the database during the last STDA rebuild.
4.wrk - Lists StreetTalk service names, other than File and Print services, that were added to the database during the last STDA rebuild.
5.wrk - Lists StreetTalk StreetTalk nicknames added to the database during the last STDA rebuild.
Any change file - lists all of the items in the change file that were added to the database during the last STDA rebuild.
[y] Dump item mods
This option lists items modified in StreetTalk since the last time the STDA database was rebuilt. These changes should be added to the STDA database after the next rebuild. Use the same procedure as for option x (Dump item adds), using -y on the command line in place of -x.
[z] Dump item deletes
This option lists items deleted from StreetTalk since the last time the STDA database was rebuilt. These changes should be added to the STDA database after the next rebuild. Use the same procedure as for option x (Dump item adds), using -z on the command line in place of -x.
