Configuration Information:
==========================

The distribution consists of several files and directories along
with internal symbolic links.  As part of setting up this test 
suite, you will need to install some of these files in the server's 
cgi-bin directory, and also install some file outside the server 
documentation directory tree, and create links from within the 
directory tree to these external files. 

The distribution contains of:

   CONFIGURE               Symbolic link to README
   README                  This file
   cgi-bin/                Programs to be copied to server's cgi-bin directory
   dir1/                   Directory containing most test documents
   test_script.cgi         Test cgi-program
   to_be_installed/        Files to be installed outside server document area
   tst_dummy.html          Dummy HTML document for include tests
    

Here is the installation and setup Procedure. You have already done steps
A and B since you needed to do those to unpack the tar file and create 
these documents!

Unpacking the Tar Archive
-------------------------

A. Create a directory under the server document directory into which you
   wish to place the test suite.  A good example name would be ssi-test/.

B. Move this tar archive ssi-test.tar into this test directory and unpack
   it using "tar -xvof ssi-test.tar". This will create the distribution
   described above.

C. You may also want to test the case where the installation directory is
   symbolically linked to the server tree, as several servers allow you to
   control exploitation of symbolic links depending on link ownership. To
   do this testyou can create a directory outside the server directory,
   for example in your home directory /your/home/ext-test/) and create a 
   symbolic link:

       ln -s /your/home/ext-test/ /path/to/serverdir/vssi-test/ 

   where I've used the "v" to indicate that the directory is only a symbolic
   link to the real home.

D. With NCSA-compatible servers, you will also want to test explicit user
   directories (using the tilde character). Install the files exactly as 
   with C, but instead of creating a symbolic link, you need to create
   a .htaccess file within your (the user's) home directory to map the
   ext-test/ directory  as the users personal server area. You can then
   use the .htaccess to enable all possible server parsing, and make sure
   that this does not override the settings set by the server's own
   configuration files.


Configuring the Test Suite 
--------------------------

1) The first step is to install the test gateway programs in the gateway
   program directory. To do this, you copy the contents of the 
   distribution's cgi-bin/ directory (test_script.cgi) into your 
   server's gatewway program directory -- I will assume this to 
   be named cgi-bin.

2) Change into the server's cgi-bin directory and mark the newly installed 
   program as executable: (the UNIX command is  chmod +x test_script.cgi)

3) You now need to create symbolic links within the server's cgi-bin/
   directory, to create 'virtual' gateway programs.   From within the 
   server's cgi-bin/ directory, create the following two links:
   
      ln -s test_script.cgi virt_test_script.cgi
      ln -s test_script.cgi virt_test_2


4) Now that you are finished with the cgi-bin material, you now need to
   install files that go *outside* the server document area -- this is 
   to test that the server cannot access files outside the allowed
   directory area.
   
   There are two files in the subdirectory to_be_installed/: the 
   script test_script.cgi and the parsed file parse1.shtml. These
   files must be copied to a location *outside* the document tree
   accessible to the server, but accessible to regular programs 
   running on the server.  Let us assume the path  is 
   /path/to/files (this  could be somewhere in your home directory). 
   Then the full paths to these files are:

     /path/to/file/test_script.cgi
     /path/to/file/parse1.shtml

   Note that the server should *only* be able to access these files
   if it has read access. Therefore, the files must be world readable,
   and test_script.cgi must be world executable. Note that the 
   directories above the file must also be accessible to the server.

4) Note the location of the current directory relative to the server
   root directory.  For example, suppose that the path, relative to 
   the root directory, is 

      ssi-test/

5) Now, change into the dir1/ subdirectory and edit the *shtml files:
   inc_file.shtml,  parse1.shtml and parse2.shtml to change the
   "virtual" paths so that the point to the correct locations. Currently
   these are coded as

      virtual="vtest/dir1/ ..."

   which, if the current directory were ssi-test/  would become

      virtual="ssi-test/dir1/ ..."

6) Also in the dir1/ subdirectory, you must create two links to the files
   installed at step (4). The links are:

      ln -s /path/to/file/test_script.cgi   virt2_test_script.cgi
      ln -s /path/to/file/parse1.shtml      lnk2_parse1.shtml

7) Lastly, you must make test that users cannot create links to nasty files
   you want to keep private (like /etc/passwd!). To test this, create the 
   following two symbolic links within the dir1/ subdirectory:

      ln -s /ext/passwd   nasty_link.html
      ln -s /ext/passwd   nasty_link.shtml

   Make sure to get rid of these  after the test! If you do not have a password
   file, use some other resource example.
      
8) And that's about it.  The files have been configured, and you are ready
   to run the test suite!


Using the Test Suite
--------------------

To start running the test suite, you simply point your browser at the 
file dir1/main.html -- using whatever URL is appropriate, given the
installation configuration you chose above. The main.htm program contains
links to all the test examples and pages. 

You should run the test suite using all possible variations of the
server configuration parameters. I find it easiest to print out each
example, and then write (yes, I know, old technology) at the top of 
the sheets the server configurattion settings applied to each page.
You can then go back and reflect on what is happening.

Good luck,

Ian Graham
