# 
# $Copyright
# Copyright 1993, 1994 , 1995 Intel Corporation
# INTEL CONFIDENTIAL
# The technical data and computer software contained herein are subject
# to the copyright notices; trademarks; and use and disclosure
# restrictions identified in the file located in /etc/copyright on
# this system.
# Copyright$
# 
 
			VSTNC


This document describes how to use VSTNC -- Verification Suite for
Transparent Network Computing.

o	QUICK INCANTATION FOR USERS EXPERIENCED WITH VSTNC

1) On the build machine build the whole server/emulator/user tree.

2) The OBJECT tree named "user/test/tnc/VSTNC" on the build machine is the
   precise directory structure required on the test machine.  Copy directory
   "VSTNC" and all its contents to the test machine using rcp -r, tar plus ftp,
   or what have you.  Be certain you copy the OBJECT tree, not the source tree.
   You may locate the directory wherever you would like on the test machine.
   NOTE: The "user/test/tnc/VSTNC/etc" directory contains soft links to the
   the commands being tested, so if "tar" is used to copy the VSTNC directory
   then use the "-h" command in the tar call.  For example:
	 $ cd user/test/tnc
	 $ tar -cvhf vstnc.tar VSTNC

3) To run the tests login as root to the test machine or have available to
   you a "root" command.  Enter the VSTNC directory and type "run_tests &"
   (or "root run_tests &").  If you do not have environment variables set
   for "MYNODE" and "NODELIST" you will be told how to set them up and
   asked to re-issue your "run_tests &" or "root run_tests &" command.
   Also, the environment variable "VSTNCETC" may be used to test different
   versions of the "user/etc" commands.  The default value for "VSTNCETC"
   is "`pwd`/etc" because the run_tests script is executed from within the
   VSTNC directory.

4) The tests take less than a half-hour to complete.   Results will be in the
   file "VSTNC/results/full.report".  You may search this file for the word
   "FAIL" by typing "grep FAIL results/full.report".  You may also inspect
   the entire full.report file to glean more information about the tests.


o	Installation

The entire test suite is rooted at a single directory named "VSTNC".
You must copy the entire contents of directory "VSTNC" from the OBJECT
branch of the build tree onto the test platform.  (For example, from
the directory above VSTNC on the build machine you could type "rcp -r
VSTNC testmachine:" and the whole hierarchy would be copied to your
home directory.)


o	Building the tests

The tests build as part of the main build.  You may also enter the
(source) VSTNC directory and type make from there, but there are some
required include files that are set up only during the build of the
server.  So you must build the server first, and this is best done from
the top of the build tree.


o	Configuration

Before you can run the tests you must provide them with configuration data.
Most of this is done automatically but you will be required to set two
environment variables: $NODELIST and $MYNODE .  The former is the list of
nodes configured; the latter is the node on which the test suite is run.

The remainder of the configuration variables are initialized to sensible
default values which are printed on your terminal when you initiate the
tests.  If you want different values, stop the tests and change the file
"config_data".  Your new values will be respected.  Automatic configuration
information is only generated when the "config_data" file is absent.

Each line in the "config_data" file starts with a keyword, followed by an
'=' sign, followed by the proper data.  Whitespace (space and tab characters)
is ignored.  Lines beginning with a '#' sign are ignored as comments.  A
detailed description of the configuration keywords is found at the end of
this document.


o	Running the tests

Use the "cd" command to enter the VSTNC directory and type the command
"run_tests".  You must be root, the super-user, to execute the tests.
The file "full.report" will be created in the "results" directory.  You
can also request just an error report by using the command "run_tests -e".
The file "error.report" will be created in the "results" directory.  If
no errors are found by the tests then this file will be zero length.


CONFIGURATION DATA FILE "config_data"

The keywords and the expected data are summarized below:

Keyword	  =	Description of data
-----------------------------------

mynode	  =	In decimal, the number of the node from which the tests
		are run.  If this is not accurate, some of the "node_self()"
		tests will fail.

nodelist  =	A _complete_ list of all the node numbers in decimal.  The
		list can consist of whitespace-separated numbers (like
		"1 2 3 4") and number ranges (like "1-4" or "1 - 4").
		These can be combined on the same line (like "1 3 5-9").
		Use as many "nodelist = " lines as you need to provide a
		complete list.  If this is not accurate, some of the "table()"
		tests will fail.

goodnode  =	In decimal, a valid node number, other than node 0.  This
		node number must also appear in your nodelist.

badnode	  =	In decimal, an invalid node number, other than 0.  This must
		be a non-negative number and it must not appear in your
		nodelist.

userid1	  =	In decimal, the numeric value of a userid other than 0.
		(0 is the numeric value of userid root.)  This is required
		for some of the signal-sending tests.

userid2	  =	In decimal, the numeric value of a second userid other than 0.
		Userid2 must be different from userid1.

TZ	  =	The string value of the TZ (timezone) environment variable to
		be used by the tests.  Both leading and trailing whitespace
		is ignored.

PATH	  =	The string value of the PATH environment variable to be used
		by the tests.  Both leading and trailing whitespace is ignored.

badaddr   =	An invalid user address on the particular architecture.  User
		programs accessing this address should expect to receive a
		bus error.

