			SOSS Installation Guide
			-----------------------

Installing SOSS is a simple task which should only take a few minutes.
Before you get started, make sure you have the following items in
place:

	- A dedicated 80x86-based PC running DOS 3.3 or above (it
	  _may_ work with an 8088 and/or older version of DOS, but
	  in that event the performance will be quite lacking).
	- An Ethernet card supported by the Clarkson drivers package,
	  such as:
	    3Com 501, 503, 505, 523; ARCNET; AT&T StarLAN series;
	    BICC Isolan 4110; IBM token ring; NetBIOS; Novell NE1000,
	    NE2000; Racal/Interlan NI5010, NI5210, NI6510, NI9210;
	    SLIP8250; Tiara LANCARD/E; or Western Digital WD8003.
	- The Clarkson drivers package, as distributed in DRIVERS.ARC
	  via anonymous ftp on sun.soe.clarkson.edu.
	- The SOSS distribution kit itself, along with ZOO to
	  extract it.
	- An NFS client system connected to the PC on the same Ethernet.
	  SOSS has been tested against NFS running on several flavors
	  of Unix:  SCO Unix 3.2.2, AIX (RS/6000) 3.1, SunOs.  The
	  client must be capable of using 1024-byte (or smaller) read/
	  write operations.
	- If you want the best performance, you should install extended
	  memory (2-4 Mb) on the SOSS server PC and get a disk-caching
	  program such as PCKWIK.  SOSS itself does not use extended
	  memory.


Configuration Parameters
------------------------

To plan your installation, determine several configuration parameters:

	- Whether the PC is using thin- or thick-wire Ethernet;
	- The I/O address, DMA address, and hardware interrupt number
	  of the Ethernet LAN card;
	- The 4-byte IP address you will use for the PC;
	- The subnet mask of your TCP/IP network (for a typical
	  Class C network, you would use 255.255.255.0);
	- The directory trees you wish to make available for remote
	  mounting.
	- Your timezone.
	- The size of read/write operations (usually 1024).


Procedure
---------

1.  Configure your Ethernet LAN card if you haven't already been using
    it with the Clarkson drivers.  Make sure its interrupt vector,
    I/O base address, and DMA addresses don't conflict with other cards.

2.  Unpack the SOSS installation kit.  You've probably already done that
    in order to read this INSTALL file.  Here's an example:

	C:\>mkdir \soss
	C:\>cd \soss
	C:\SOSS>zoo x// a:soss

3.  Edit your CONFIG.SYS file to contain these two lines:

	FILES=15      (or greater)
	DEVICE=NETDEV

4.  Configure the PC/IP driver, using CUSTOM.EXE and NETDEV.SYS found
    in the EXE subdirectory.  Copy NETDEV.SYS to the root directory (or
    wherever you store your drivers) and run CUSTOM on this file:

	C:\>custom netdev.sys

    Go into the  "Site Customizations" menu and set the Internet
    address, the number of subnet bits, the domain name server(s)
    and time server addresses.  Note that the number of subnet bits
    you select is added to 8 (the minimum Class A network mask)
    to form the network mask, so this means you should specify a
    value of 16 to get a 24-bit Class C mask.

    Go into the hardware customization menu and set the interrupt
    vector number, DMA channel and address, and the I/O address.
    You should not need to set the hardware Ethernet addresses.

    Reboot the machine to load NETDEV into memory.  (If the machine
    fails to boot, make sure your copy of NETDEV.SYS was downloaded in
    binary mode and is 599 bytes long.  Don't laugh--this problem
    _has_ happened.)

6.  Invoke the packet driver using the appropriate parameters.  An
    example for the Racal/Interlan NI-5210 card, using hardware vector
    number 5, I/O address 300 and DMA address D000 is:

	C:\>ni5210 -n 0x7e 5 0x300 0xd000

    Note that SOSS uses software interrupt 7E.  If it loads correctly,
    it should display the following after the copyright message:

	Packet driver loaded at segment xxxx
	TDR Ok
	Interrupt number 0x5 (5)
	I/O port 0x300 (768)
	Memory address 0xD000 (53248)
	My Ethernet address is xx:xx:xx:xx:xx

7.  Load NetWare, if you are using it in conjunction with SOSS.  A
    program called IPXPDI (from BYU) is provided with SOSS to allow you
    to do this.  Run IPXPDI after the packet driver and before NET3 or
    NET4.  NetWare-386 server versions 3.10 and 3.11 are compatible
    with SOSS off-the-shelf; you will probably have to ECONFIG the
    server to ignore 802.3 packets if you have an older version of
    NetWare.
		NOTE
    SOSS does _not_ at present run as an NLM (NetWare Loadable Module)
    on the same PC as the Novell server software; you have to have a
    separate PC.  SOSS can thus provide NFS clients access to files on
    Novell servers, using a gateway approach, but at significantly
    lower performance than would an NLM.

8.  Set up the EXPORT.US file.  An example is provided in the EXE
    subdirectory; you can start with a file simply containing:

	C:\

9.  Set the timezone environment variable to indicate how many hours
    past GMT your site is.  For example:

	C:\>set TZ=EST5EDT

10. Making sure you're 'cd'-ed to the directory containing EXPORT.US,
    run SOSS.  You should not need to use any command-line options.

11. On your client system, add the SOSS server PC's IP address to its
    host table, and give it a name (e.g., 'dosbox').  The procedures
    for doing this vary; check the documentation for your name daemon,
    if you're using it.

12. Make sure there is proper connectivity to the SOSS PC.  On a
    typical Unix client system, you can try these commands:

	$ showmount -e dosbox
	$ ping dosbox

    If these don't work, check your installation.  If you have another
    NFS server on the network, make sure the client system can talk
    to the other server before you begin to doubt the PC installation.
    You should then get PC/IP (from sun.soe.clarkson.edu), if you
    don't already have it, and use its debugging capabilities to find
    out why the interface isn't working.  A brief debugging section is
    presented at the end of this guide.

13. Create an empty directory on your client system to use as a mount
    point (e.g., /usr/soss).  From an appropriately privileged account,
    issue the mount command on your client system.  Again, this varies
    from system to system, so check your documentation.  For a System V
    Unix box, the following should work:

	# mount -f NFS,intr,rsize=1024,wsize=1024 dosbox:/c /usr/soss

    SOSS will work with read and write requests up to 1024 bytes.
    Many client systems assume up to 8192 bytes, so make sure you
    specify this parameter.

14. Test the installation by listing the top-level directory (/usr/soss)
    to make sure expected files are there and by creating and modifying
    new files.

15. Once you are satisfied with the installation, modify the AUTOEXEC.BAT
    file on your server to start up SOSS.  Here is an example:

	ni5210 -n 0x7e 5 0x300 0xd000	
	set tz=EST5EDT
	ipxpdi
	net3
	key-fake "login server/user" 13 "passwd" 13 "castoff all" 
	setclock
	cd \soss\run
	soss

    The KEY-FAKE program is provided to allow you to create scripts to
    answer prompts for passwords and the like.


Troubleshooting
---------------

The most common symptom of a faulty installation is simply that the
client system won't talk to the NFS server at all.  Once you can mount
the filesystems, SOSS will usually run correctly (aside from the
limitations discussed in the manual pages).  If you can't mount them,
check the following things:

	- Run 'ping' on your client system, giving it the SOSS server
	  address; make sure SOSS responds.
	- Shut down SOSS, and run PC/IP 'ping' on that PC, giving it
	  your client system's address.  If that doesn't work, try
	  other IP addresses on your network.  If it does, try
	  logging into the client system using PC/IP 'tn'.

If you can't do either of the above, you probably have a problem with
the LAN card installation or the parameters you gave the Clarkson
driver.  Double-check that you set up NETDEV with the correct parameters,
and check your LAN card's documentation to confirm the hardware
parameters against those you used to run the Clarkson driver.  Then
get a copy of the PC/IP distribution kit from sun.soe.clarkson.edu or
from your SOSS distributor and review its installation procedures.  If
the PC/IP utilities are not working, SOSS won't either.

If you have connectivity, do the following:

	- Issue the 'showmount -e dosbox' command on your client
	  system.  You should get output similar to the following:

		export list for dosbox:
		/c			everyone
		/h			everyone
		/c/soss/src		everyone

	- Make sure the mount command uses lower-case when naming
	  the remote filesystem; Unix commands are case-sensitive.
	- Check the mount command's documentation.  SunOs, for
	  example, uses the '-t' option to specify the filesystem
	  type, rather than '-f' given in the earlier example.
	- Make sure your client system is issuing read and write
	  requests small enough to fit in the 1024-byte limit.  If
	  it expects smaller values, you might want to use the '-b'
	  command line option to SOSS.
	- Check that SOSS is receiving I/O requests across the
	  network by running it with the '-v' command line option.
	- Turn on SOSS' debugging flags with a command like

		C:\>set nfsdebug=all

	  prior to running SOSS.  This will provide you with quite
	  a bit of trace information for every I/O request.
	- Using the debugging trace output as a guide, scan the
	  source code (provided with the SOSS distribution) to see
	  what the server is trying to do with your client requests.
	  The file nfs.c contains the top-level dispatcher and
	  request-handling routines.  You can recompile SOSS with
	  Microsoft C version 5.1; contact the authors for help in
	  making source code changes.

SOSS is designed for 24-hour unattended use, and should be able to run
for days or weeks at a time.  If you find problems with system crashes,
please contact the maintainer (rbraun@spdcc.com) via e-mail so they can
be corrected.
