		 	==================
			Coda Release 4.6.5
			==================

date: 09/14/98

These are partial instructions on how to setup and configure the Coda
filesystem.  For further information, refer to the manual in
/usr/local/share/doc/coda-doc-4.6.5

I. 		========
		LICENSE:
		======== 

TBD

II.		========
		WARNING: 
		========

CODA IS BARELY READY FOR PRODUCTION USE. THIS RELEASE IS JUST FOR
THOSE INTERESTED IN EXPLORING THOSE FEATURES WHICH WORK. IT CONTAINS
KERNEL CODE, AND SERVERS RUNNING WITH ROOT PRIVILEGES, AND COULD LEAD
TO DATA LOSS.

III.	Venus -- the client

1. Initializing before running Venus:

The venus-setup script does all the hard work, it will setup the coda
control files, create /dev/cfs0 to communicate with the kernel, ...
It also initializes a directory for cache files.  The cache size
should be at least 10Meg, typically 60-100Meg is used (ie. 60000 or
100000 in venus-setup [below]).  DO NOT GO ABOVE 200-300Meg.  All the
files created will be placed under /usr/coda.  You should make sure
that there is enough space in the file system that /usr/coda resides
on to hold a fully populated cache.

venus-setup <comma_separated_host_list> <cache_size_in_kb>

venus-setup and venus (below) are in sbin/.  Make sure that sbin is in
your path or that you use fully qualified pathnames.  We strongly
recommend that you try testserver.coda.cs.cmu.edu as the
<comma_separated_host_list> first.

NOTE:
venus-setup will edit /etc/services to add some additional services.)
NOTE:
YOU MUST HAVE A KERNEL ENABLED WITH VENUS SUPPORT TO PROCEED.  The
INSTALL document and the BUILD document explain how to get a
VENUS capable kernel.

2. Running Venus:

The following assumes you are running X-Window.  However, you could
run these commands from virtual consoles as well, but omitting the
"xterm -e" in front of the commands below.

Start Venus with:
	venus &

An -init flag can be given when venus is started; it flushes the local
cache contents.  It should be used whenever venus is connected to a
different server.  (venus-setup essentially forces an init to happen
when venus is first started.)

Observe the venus log with:
	xterm -e tail -f /usr/coda/etc/console
It will tell you when venus has started and give status.

Type:
    xterm -e codacon &
to see the communications between the Venus and Vice.

It is possible to see the upcalls from the kernel to Venus by turning
up logging in Venus, but they are not very interesting.  (To turn on
minimal debugging, type:
	vutil -d 1
and then tail -f /usr/coda/coda.cache/venus.log.)

NOTE:
Remember, make sure your have enough free space on the filesystem in
which /usr/coda/venus.cache resides for the cachesize indicated.  That
is, if you specify 20000 for for twenty-thousand kilobytes, this means
you must have at least 20MB of free on the partition containing
venus.cache.

To halt venus, type:
	vutil shutdown
(Or you can kill -9 "venus", if you must.)

IV.	Codasrv -- the server

1. Initializing before running Vice:

NOTE: that running a server seriously dips into your virtual memory.
Running a server _and_ a client and X11 needs slightly over 64M of
available VM.

To set up an SCM server, you need to have the following resources:
  1)	an empty directory (viz  /vicepa) where the fileserver will
	put files.  There must be as much free space on this filesystem
	as the data you wish to store in Coda.
  2)	a raw partition for RVM metadata (you can use a file but it 
	will be quite slow on a decent size server). This partition
	must be around 4% of the total size of the files you wish 
	to store under /vicepa (e.g. on a 2GB server we use around
	80M of rvm data). Consider 10M to be the minimum. 
  3)	a LOG partition, preferably on a disk by itself. This 
	needs not be large. 
  4)	two secret tokens of _exactly_ 8 characters (eg elephant).

The RVM files are used for the journalling/transactional aspects of Coda.

Then run:
     vice-setup

and answer its questions.

2. Running Vice:

Start the rpc2portmap server, update server, client and the auth
server, as well as the fileserver by typing:

	etc/rc.vice start

Now observe the log:
	xterm -e tail -f  /vice/srv/SrvLog & 

Determine with ps that codasrv, rpc2portmap, updatesrv and updateclnt
are running.  The SrvLog should show "File Server started".  If not,
you have a problem.

3: Making Volumes

Make a root volume (coda:root [below] should be the name you gave to
vice-setup for the root volume name): 

	createvol_rep coda:root E0000100 /vicepa

NOTE:
E0000100 is the Volume Storage Group set up for you by
vice-setup. With more servers you can define other groups in
/vice/db/VSGDB -- see the Coda User Manual.

Now you are ready to point a Venus (client) at this server. 

The vice-setup program installed an administrative user on the server,
named admin.  It has a uid you chose and has been assigned password
changeme.  You may clog into Coda with this uid.

Read section 7.7 in the Coda Manual to find out how to set up another
user and password database (such users must be installed on clients
too, but need not be in /etc/passwd on the servers).

From the coda client side, the root volume will appear under /coda.

V. Common Tasks

1. Normal server startup:
	startserver &

it comes up at boot time from rc.vice, unless you said "No" to
automatic startup, OR if the there is a file /vice/srv/CRASH exists,
which indicates the fileserver crashed. Howver you need the update
server and client for system administration and the authserver for
authentication -- see /usr/pkg/etc/rc.vice.

2. Re-run venus-setup and point your server to your own server.

* make sure the server is up _AND_ you have made root volumes*
Do a venus-setup and use your own server as the
<comma_separated_host_list>

start venus with 
     venus -init &
     xterm -e tail -f /usr/coda/venus.cache/venus.log
     xterm -e tail -f /usr/coda/etc/console
     xterm -e codacon

When the server is up cd to /coda and start playing.  You won't run
-init the next time you start venus.  The flag is necessary in this
case since we are switching the server venus is talking to.
(Currently, venus does not support Cells.)


3. Restarting a server:

     volutil shutdown
shuts down the server.  Restart as above.

4. Restarting a client.

The official procedure is to:
	vutil shutdown

kill -9 <venus> works equally well.  Then restart as stated above.

5. Troubleshooting the Server

If the server crashes before you have used it through /coda, do rm -rf
/vice and start all over. At the minimum you must do before you
restart.

Remember: first clean, then startserver, then make rootvolumes, but ...

If your server doesn't come up, ask for help on
linux-coda@coda.cs.cmu.edu.  It is Likely cleaning will reproduce the
same problem.

6. Troubleshooting the Client

If venus comes up but hangs or crashes, check for zombie venus
processes.  Also read the etc/console file and see if venus has an
assertion failure.  If these happen, rebooting may help.

If you are having repeatable difficulties starting venus, try starting
venus with:
	venus -init
Occasionally, bad state is left in the cache and this will clear it out.
