4.4BSD/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:

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.

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.