BSD 4_3_Net_2 release

[unix-history] / usr / src / sys / tests / nfs / unix-tests / README

#
#	@(#)README	1.11 90/01/03 NFS Rev 2 Testsuite
#
NFS and Connectathon are trademarks of Sun Microsystems, Inc.



Introduction to the NFS Revision 2 Testsuites
---------------------------------------------

These directories contain programs that can be used to test an implementation
 of Revision 2 of the NFS Protocol.  The tests run on a UNIX client and test 
server and client functions.  They are divided into three groups:

	basic   - basic NFS operations tests 
	general - general file system tests
	special - tests that poke certain common problem areas

This README is divided into six sections.  The first section is the introd-
uction,  which you are reading now.  That is followed by a description of 
what you have to do before you run the testsuites on your machine.  Then 
comes a description of how the testsuites are run in general followed by a 
description of how they are used at Connectathon.  The last sections describes 
what each test does in detail.

This testsuite should run on both BSD and System V based systems.
The System V port of the Connectathon Testsuite is provided courtesy
of the Software Technologies Group, INTERACTIVE Systems Corporation,
1901 N. Naper Blvd., Naperville, IL. 60563


Preparing to run the Testsuites
-------------------------------

To prepare to run the testsuites on your machine,  change directories to the 
highest level testsuite directory (it should be the same one that contains 
this README file),  and type "make" to compile the test programs.  If you are 
not sure your are in the correct directory,  type "ls -F" and you should see 
the following files and directories:

Makefile    Testitems   domount.c   getopt.c    server*     tests.init
README      basic/      general/    runtests*   special/    tools/

The "server" script uses "getopt" and a source file of a public-domain 
version is included in the directory.  The makefile will compile it for you.

Changes may be required to the Makefile depending on the type of system
you are testing on and what version of NFS you are testing.  Change the 
COMPAT variable if you are running NFS3.2 to:

	COMPAT = -DNFS3_2

If you are running on a System V based system (SVR3) you will need to change:

	SYSTYPE=-DSVR3
	LIBS=-lrpc

If you are running Lachman NFS for System V Release 3, you should set the 
compatability variable to:

	COMPAT =  -DSVR3

Lachman NFS is based on NFS3.2, but you should not set NFS3_2.  That symbol 
is used only for vnode-based systems, not FSS-based systems.

If you are testing on a BSD based system SYSTYPE and LIBS should not be
set to anything.  Be sure and check the COMPAT variable if running 
release 3.2 of NFS. 

Two special targets are included in the Makefiles: copy and dist. The command 
"make copy DESTDIR="path"",  where "path" is the name of a directory, will 
cause the compiled tests to be copied to "path".  "make dist DESTDIR="path"", 
where "path" is the name of a directory,  will copy the test sources to 
"path".  DESTDIR must be specified on the make command line when making 
either of these targets.

Modifications may be required so the programs compile on your machine.  If 
that is so,  we would like to know what they are so that we can incorporate 
them into our distribution.  

When defaults are used,  the test programs expect /mnt to exist on the client 
and /server to exist on the server.    These defaults can be overridden at 
run time.  Read about how to run the testsuites for a description of how this 
is done.

NOTE:  When running any of the tests, you should save stdout and stderr
       output in a file for future reference.




How to run the Testsuites
-------------------------

There are two ways to run the tests: (1) use the server shell script or 
(2) mount, run the tests yourself,  and unmount.  We recommend you use the 
server script to run the tests.



The server script:

The server script executes the basic and general tests. (It runs the 
special tests only if use the -s option.)  It is set up to mount, 
run tests using the runtests program, and unmount.  It will attempt to unmount 
anything mounted on the mount point before attempting to mount the server file 
system. 

server uses the domount program to mount and unmount the test file systems.  
Since mount can only be executed by root,  domount must have root permission.  
The Makefile will attempt to setuid the domount program to root.  The server 
script can be run as a nonprivileged user. Alternately, you may login as root 
before you run server.



server [-a|-b|-g|-s] [-|-f|-t|-n] [-o mnt_options] [-p server_path] [-m mntpoint] server_name


-a|-b|-g|-s - will be passed on to the runtests scripts.  This argument is
	      optional.  The default is read from the initialization file,
	      tests.init.
	      This argument selects which tests to run:
		-a	run basic and general tests
		-b	run basic tests only
		-g	run general tests only
		-s	run special tests only
-f|-t|-n    - will be passed on to the runtests scripts.  This argument is
	      optional.  The default is read from the initialization file,
	      tests.init.
mnt_options - will be passed on to the mount command. This argument is
	      optional.  The default is read from the initialization file,
	      tests.init.
server_path - specifies a directory on the server to mount.  This argument
	      is optional.  The default is read from the initialization file,
	      tests.init.
mntpoint    - specifies a mount point on your client. This argument is
	      optional.  The default is read from the initialization file,
	      tests.init.
server_name - the server you want to exercise.  This is the only required 
	      argument. 

The test programs create a sub-directory in the mntpoint directory with the 
name 'hostname'.test (where 'hostname' is the name of the machine on which 
you run the tests).  This name can not be overridden if you use the server 
script although it can be if you use runtests directly.  

Example:  (the client machine is eddie)

eddie% server -o hard,intr,rw slartibartfarst
Start tests on path /mnt/eddie.test [y/n]? y
<output from tests>
         :
         :
All tests completed
eddie%

See the script for more details.

 

Run tests yourself:

There is a runtest script in the highest level directory (the master runtests) 
which uses tests.init to set up the test environment and then executes runtest 
scripts in the basic, general,  and/or special sub-directories. 


 runtests [-a|-b|-g|-s] [-f|-n|-t] [test-directory]


-a	       - Run the basic and general tests.  This is the default.
-b	       - Run the basic tests.
-g	       - Run the general tests. 
-s	       - Run the special tests.
-f	       - Set parameters for a quick functional test. This is the 
	         default.  It applies only to basic tests.
-n             - Suppress directory operations (mkdir and rmdir) on the 
		 test-directory.  See descriptions of basic tests for more
		 details.  
-t	       - Run full-length test with running time statistics. It only 
          	 applies to basic tests. You will want to rerun with "-t" after 
		 all the "-f" (default option) tests run successfully.


test-directory - The name of test directory that the test programs create 
		 on the client.   runtests executes the basic tests in place 
		 and they work on the test directory.  The general tests are 
		 copied over to the test directory and executed there.  When 
		 the -n flag is used, the test directory is assumed to already 
		 exist.

		 The default test-directory is /mnt/'hostname'.test (where 
		 'hostname' is the name of the machine on which you are 
		 running the tests). There are three ways to override the 
		 default test directory name.  One it to put the 
		 test_directory on the command line.  Another way is to set 
		 the environment variable NFSTESTDIR equal to the directory 
		 name.  The command line method overrides setting the 
		 environment variable.  The third way can only be used
		 for the tests in the basic sub-directory.  There you
		 can set the TESTDIR variable in tests.h.  The command
		 line and environment variable both override this
		 method.

Running the tests without mounting your NFS server on /mnt will run the tests 
locally (if /mnt is local disk).  We recommend that you do this once to make 
sure the testsuites run properly before you use them to test NFS.

The runtests in sub-directories: basic, general, and special,  may be invoked 
with the same arguments as the master runtests if you wish to run each suite 
separately.




How to run the Testsuites at Connectathon
-----------------------------------------


The tests should be run in the following order:  basic,  general, and special.
The basic tests should be passed completely before other tests are attempted.

The NFS Test Suite should be run in three phases:

Phase 1 - Run test programs locally.

Phase 2 - Run the tests against a Sun.  Run them on your machine using the
          Sun as the server and then run them on the Sun using your machine
          as the server.

Phase 3 - NxN Testing.  Run the tests on your machine using every other
	  machine as a server,  one at a time.  After the tests are 
	  successfully completed using a particular server,  log that
	  with the electronic board software provided. Check the electronic
	  board to make sure that the tests run successfully on 
	  every other machine that uses your machine as a server.


Test Descriptions
-----------------

System and library calls that are used by the testsuites are included in paren-
theses.  Look at the source if you are interested in how time statistics are 
recorded since that is not included in this description.




- BASIC TESTS:   

Many of the programs listed below have optional calling parameters that can be 
used to override existing parameters.  These are not used at this time so they 
are not described.  


test1: File and Directory Creation Test

This program creates the test directory (mkdir)  on the client and changes 
directories (chdir) to it,  unless the -n flag is used in which case it simply 
changes directories to the test directory.  Then it builds a directory tree  
N levels deep, where each directory (including the test directory) has M 
files and P directories (creat, close, chdir, and mkdir).  For the -f 
option N = 2, M = 2,  and P = 2 so a total of six files and six directories 
are created.  For other options N = 5, M = 5, and P = 2.  The files that are 
created are given names that begin with "file." and directories with names 
that begin with "dir.".



test2: File and directory removal test

This program changes directory to the test directory (chdir and/or mkdir) and 
removes the directory tree (unlink, chdir,  and rmdir) that was just created 
by test1.  The number of levels, files, and directories,  and the name pre-
fixes, are the same as in test1.

This routine will not remove a file or directory that was not created by test1 
and will fail if it finds one.  It determines this by looking at the prefix on 
the name of the object it's trying to remove.



test3: Lookups across mount point

This program changes directory to the test directory (chdir and/or mkdir) and 
gets the file status of the working directory (getwd and stat).    


test4: setattr, getattr, and lookup

This program changes directory to the test directory (chdir and/or mkdir) and 
creates ten files (creat).    Then the permissions are changed (chmod) and the 
file status is retrieved (stat) twice for each file. 


test4a:  getattr, and lookup

This test exists but is not called as part of the testsuite.  You can edit
runtests in the basic directory so this test is called.

This program changes directory to the test directory (chdir and/or mkdir) and 
creates ten files (creat).    Then the file status is retrieved (stat) for 
each file. 



test5: read and write
	         
This program changes directory to the test directory (chdir and/or mkdir) and 
then: 

1) Creates a file (creat) 
2) Gets status of file (fstat)
3) Checks size of file
4) Writes 1048576 bytes into the file (write) in 8192 byte buffers.  
5) Closes file (close)
6) Gets status of file (stat)
7) Checks the size of the file

Then the file is opened (open) and read (read) in 8192 byte buffers.  It's 
contents are compared with what was written.  The file is then closed (close).

Then the file is then re-opened (open) and re-read (read) before it is removed 
(unlink).

test5a: write

This test exists but is not called as part of the testsuite.  You can edit
runtests in the basic directory so this test is called.

This program changes directory to the test directory (chdir and/or mkdir) and 
then: 

1) Creates a file (creat) 
2) Gets status of file (fstat)
3) Checks size of file
4) Writes 1048576 bytes into the file (write) in 8192 byte buffers.  
5) Closes file (close)
6) Gets status of file (stat)
7) Checks the size of the file


test5b: read

This test exists but is not called as part of the testsuite.  You can edit
runtests in the basic directory so this test is called.

The file created in test5a is opened (open) and read (read) in 8192 byte 
buffers.  It's contents are compared with what was written.  The file is 
then closed (close) and removed (unlink).



test6: readdir

This program changes directory to the test directory (chdir and/or mkdir) and 
creates 200 files (creat).  The current directory is opened (opendir), the 
beginning is found (rewinddir), and the directory is read (readdir) in a loop 
until the end is found.  Errors flagged are:

1) No entry for "."
2) No entry for ".."
3) Duplicate entry
4) Filename that doesn't begin with "file."
5) The suffix of the filename is out of range
6) An entry is returned for an unlinked file. (This error can only be
   found when the test is run with an option other than -f.   For other
   options the readdir loop is done multiple times and a file is unlinked
   each time).  

The directory is then closed (closedir) and the files that were created are 
removed (unlink). 



test7: link and rename

This program changes directory to the test directory (chdir and/or mkdir) and 
creates ten files.  For each of these files, the file is renamed (rename) and 
file statistics are retrieved (stat) for both the new and old names.  Errors 
that are flagged are:

1) Old file still exists
2) New file doesn't exist (can't stat)
3) The new file's number of links doesn't equal one

Then an attempt is made to link the new file to it's old name (link) and file 
stats are again retrieved (stat).  An error is flagged if:

1) Can't link
2) Stats on new file can't be retrieved after link  
3) The new file's number of links doesn't equal two
4) Stats on old file can't be retrieved after link  
5) The old file's number of links doesn't equal two
 
Then the new file is removed (unlink) and file stats are retrieved for the old 
file (stat).  An error is flagged if:

1) Stats on old file can't be retrieved after unlink
2) The old file's number of links doesn't equal one

Any files that remain at the end of the test are removed (unlink).

test7a: rename

This test exists but is not called as part of the testsuite.  You can edit
runtests in the basic directory so this test is called.

This program changes directory to the test directory (chdir and/or mkdir) and 
creates ten files.  For each of these files, the file is renamed (rename) and 
file statistics are retrieved (stat) for both the new and old names.  Errors 
that are flagged are:

1) Old file still exists
2) New file doesn't exist (can't stat)
3) The new file's number of links doesn't equal one

Any files that remain at the end of the test are removed (unlink).

test7b: link

This test exists but is not called as part of the testsuite.  You can edit
runtests in the basic directory so this test is called.

This program changes directory to the test directory (chdir and/or mkdir) and 
creates ten files.  A link (link) is done for each of these files, and file 
stats are retrieved for the old and new files (stat).  An error is flagged 
if:

1) Can't link
2) Stats on either file can't be retrieved after link
3) The either file's number of links doesn't equal two

This is followed by an unlink (unlink) of the new file.  An error is 
flagged if:

1) Stats on the old file can't be retrieved after unlink
2) The old file's number of links doesn't equal one

Any files that remain at the end of the test are removed (unlink).



test8: symlink and readlink

NOTE:   Not all operating systems support symlink and readlink.  If the
	errno EOPNOTSUPP is returned during test8, the test will be
	counted as passing.  For clients not supporting S_IFLNK, the
	test will not be attempted.

This program changes directory to the test directory (chdir and/or mkdir) and 
makes 10 symlinks (symlink).  It reads (readlink), and gets statistics for 
(lstat), each, and then removes them (unlink).  Errors flagged are:

1) Unsupported function
2) Can't get statistics (lstat failed)
3) The mode in the stats is not symlink
4) The value of the symlink is incorrect (returned from readlink)
5) The linkname is wrong
6) The unlink failed



test9: statfs

This program changes directory to the test directory (chdir and/or mkdir) and 
gets the file system status on the current directory (statfs).




- GENERAL:  General tests to look at server loading.

Runs a small compile, Tbl, Nroff and a Large Compile. Four simultaneous
large compiles are also run.




- SPECIAL:  Information specific to the special tests

The special directory is set up to test special problems that have
come up in the past.  These tests are meant to be advisory, ...
things to watch out for.  It is not required that you "pass" these
tests but we suggest you give them a try.

The tests try to:

      check for proper open/unlink operation
      check for proper open/chmod 0 operation
      check for lost reply on non-idempotent requests
      test exclusive create
      test negative seek
      test rename




- MISC:

'Testitems' is a list of NFS functionality that can be used for reference.

Programs in 'tools' are provided for your use as you see fit.  Please
feel free to add to this (or any other) directory!  If you do, please
make sure that Cathe Ray (sun!cathe or cathe@sun.com) at Sun gets a copy 
so we can add it to the master test distribution.