SHADETREE-INSTALL(1)	   Cinema Graphics, Inc.	SHADETREE-INSTALL(1)

NAME
    shadetree-install - Directions for how to install ShadeTree

CONTENTS
    The basic steps for installing ShadeTree are as follows. See the
    sections that pertain to you for your installation:

	1. ACQUIRING THE DISTRIBUTION 

		Download the distribution from the cinegrfx.com web site, 
		or acquire a ShadeTree distribution tape.

	2. SIMPLE INSTALLATION OF LICENSE MANAGER

		In many cases, just running /usr/local/shadetree/etc/INSTALL
		will handle everything.

	3. ADVANCED INSTALLATION OF LICENSE MANAGER

		Ignore this section if you do the simple installation.
		In special cases, such as installations for large facilities,
		custom installation is necessary. These instructions point out
		topics to consider for custom setups.

	4. SETTING UP USER ENVIRONMENTS

		Invoke the software, and do some test renders in a typical
		user's own environment.

	5. DEBUGGING PROBLEMS

		Refer to the Frequently Asked Questions manual page in 
		/usr/local/shadetree/man/cat1/shadetree-faq.1, or refer to 
		the 'up-to-the-minute' FAQ on the cinegrfx.com web page.

    What follows are the distribution installation instructions. 
    Please follow each step carefully. If you encounter errors in
    this documentation, please send mail to '[email protected]'.

			- - -  END OF CONTENTS  - - -


1. Acquiring The Distribution
-----------------------------

    Netscape/Internet Distributions
    - - - - - - - - - - - - - - - -

    If you have netscape, and access to the Internet, that is all you need:

        1) Connect to 'cinegrfx.com'.

	2) Enter the FTP menu

	3) Download the latest distribution to the directory you'll be 
	   installing the software into.

	4) Extract the distribution tar file. For example:

                crypt PASSWORD < shadetree-prman.1.0.2.tar.gz.enc \
                             > shadetree-prman.1.0.2.tar.gz

		gunzip shadetree-prman.1.0.2.tar.gz
		tar xvfp shadetree-prman.1.0.2.tar

	   NOTE: Contact [email protected] for the correct PASSWORD.

    Exabyte Distributions
    - - - - - - - - - - -

    If you don't have access to the internet, and want an exabyte tape
    distribution, contact Cinema Graphics to receive a tape by mail:

	Cinema Graphics, Inc.
	22516 Lassen Street
	Chatsworth, CA 91311

	Phone: (818) 718-6320
	  Fax: (818) 718-6321
	Email: [email protected]

    To extract the tape, follow the instructions enclosed with the tape.
    Normally, extraction is something like:

	cd /usr/local		# or where ever you're installing the software
	tar xvp

2. Simple Install Instructions
------------------------------
    Most people use this procedure. Normally, setup involves logging in as
    'root' and running:

	/usr/local/shadetree/etc/INSTALL

    ..and invoking the menu options. Here is a literal example:

	1) Login as root.

	2) Run the INSTALL program:

	      /usr/local/shadetree/etc/INSTALL

	3) Choose 'Install Daemon'. 
	
	      The license daemon should install, and start running.  
	      You should see all 'OK:' messages, and you should 
	      definitely not see any 'FAIL:' messages.

	      Run this on each machine that needs to act as a license server.

	4) Choose 'Install Key'

	      You will be prompted for a license key, which you will either 
	      have already, or you will need to contact Cinema Graphics to 
	      get your license key.

	      A literal example would be:

        Elan License Manager - Copyright 1989-1996 Elan Computer Group, Inc.

        On how many hosts will you run the license server? (default=1): 1
                                                                       ^^^
        Code for "empire" is:  1215/7199 9730 8243 6371 0
        Please enter your key: 9345 5053 7401 3381 6929 6130 4114 5673 7371 1
                               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

	      It is highly recommended that you record your key somewhere 
	      on hard copy, such as a system administrator's log.

	5) Choose 'Test' to bring up the software. 
	
	      The interface should come up, without any 'DEMO MODE' warnings.
	      If you get DEMO MODE warnings, the license manager isn't working.
	      See the manual page "shadetree-faq.1" for debugging instructions.

3. Advanced Custom License Installation
---------------------------------------

    If you have done the Simple Installation, and everything works,
    YOU SHOULD IGNORE this section. 

    These are instructions ONLY for advanced installers who need to 
    make a custom installation of the ShadeTree license manager.

    Essentials: Things you MUST do for licenses to work
    - - - - - - - - - - - - - - - - - - - - - - - - - -
    If you are doing a custom installation, you probably just want to know 
    the bare necessities, confident you can handle the rest.

    	o At minimum, the license manager daemon (etc/elm/elmd-shadetree)
	  needs to be running on all machines acting as license servers.
	  Usually only three servers are needed to manage a large network.
	  
	  It is highly recommended the daemon live in a local directory 
	  on each server, eg. /etc/elmd-shadetree. The daemon should 
	  be configured to start whenever the machine boots.

	o The daemon MUST have:
    
	    -e to specify the directory where the daemon's license file(s)
	       should be stored. Normally this is under /var/adm.

	    -l to specify the full path to the daemon's log file. This should
	       be on a local disk, and is normally /var/adm/elmd-shadetree.log.

	    -m specifies the maximum size of the daemon log file. When this
	       size is reached, the daemon rotates the log automatically.

        o When keying the software, you run etc/elm/elmadmin. This program does
	  two important things:

	    > Tells you the Code for the machine it's running on. This
	      code needs to be supplied to Cinema Graphics before they
	      can give you a license key.

	    > Prompts for a license key. When you enter the license key,
	      it contacts the daemon, and creates a key file.

	o The elmadmin program usually needs:

	    -e to specify the directory where it will save a license file.
	       This should be THE SAME PATH specified for the daemon's -e
	       flag.

	    -c to indicate the creation of a license, or to find out
	       the Code for the local host, which is supplied to Cinema
	       Graphics.

        o To test if the license server can be 'seen' from a host, run:
  
                elmadmin -s
  
          This sends a broadcast to the network, which will be responded to
          by the license server. Or, if STREE_ELMHOST is specified (if your
          network does not route broadcasts), it will directly contact those 
          host(s) specified.
  
    GOOD PRACTICE
    - - - - - - -
    These are optional procedures, but are highly recommended for correctness.

        o The daemon and ShadeTree executables use port 1743 by default 
	  for its UDP communication. This port number was assigned to 
	  Cinema Graphics by IANA. 
	  
	  The software and license system will work without an entry in 
	  /etc/services, and will therefore use 1743 by default. However,
	  it is recommended that for completeness, all services files contain
	  the entry:

stree_elmd      1743/udp                        #ShadeTree Elan License Manager

	  If you are using NIS (Yellow Pages), you should add the entry
	  to the master services file.

	  You may change the port number, but only if you do so FOR ALL 
	  MACHINES, including the clients. This will be the only way
	  user invocations of the software will know to use your custom
	  port number.

	o Avoid putting the daemon, or any of the files it refers to,
	  on an NFS mounted directory. Always use a local disk for the
	  daemon executable, and the logs and license files it creates.

	o Keep a hard copy of the license around. If you ever remove or
	  corrupt the license files, you will need to re-enter your key
	  with the elmadmin program.

	  NOTE: Your key is the first line of numbers in the license file,
	  eg, /var/adm/shadetree/01.lic:

!
# DO NOT EDIT/COPY/MOVE/TOUCH THIS FILE!
# DOING SO WILL INVALIDATE THE KEY!
9147792167138913246936630265329243025		<-- this is your key
[..]

	  You may not recognize the key without the spaces, but it's the
	  same number. You may have received it in the form:

	      9147 7921 6713 8913 2469 3663 0265 3292 4302 5

4. Setting Up User Environments
-------------------------------
    The bare minimum a user will need in their .login files is:

	setenv STREE_DIR /usr/local/shadetree	# or where ever it's installed
	set path = ( $STREE_DIR/bin $path )

    For a sample login environment file with all the trimmings, please refer
    to the file:

	/usr/local/shadetree/login/.shadetree

    Setting of STREE_ELMHOST should be avoided, but if your network does 
    not support routing broadcasts, you may find it necessary to setup.
    See ENVIRONMENT in the shadetree man page for examples.

    If you are the manager of a large facility, you should use this file
    as a basis for your user environment setup.

    To test the software, login as a user, and:

	1) Bring up the software by typing:

		st

	2) The interface should appear. 
    
		If you see a dialog warning about 'DEMO MODE', then
		something is wrong with the license key. See the 'faq'
		(Frequently Asked Questions) under the section INSTALLATION
		PROBLEMS.

		The FAQ is available both in the 'man' directory as
		'shadetree-faq.1' which came with your distribution, but can
		also be found in the FAQ section on the cinegrfx.com web
		site.

	3) Load one of the example 'stree' files.

		o Choose Open -> File from the main menu, pick 'chromy.stree'

		o Choose Render -> Render It from the main menu.

		o You should see an image rendering.

		  If you don't see an image render, or see a pop up window
		  warning of a failure, check your TTY window for error 
		  messages. This almost always means the user's environment 
		  is not properly setup for the renderer in question 
		  (Renderman or Mental Ray). 
		  
		  ShadeTree needs the user's environment correctly setup 
		  for the rendering software. Please refer to your renderer's
		  installation instructions.

5. Debugging Installation Problems
----------------------------------
   If you can't bring up the software, can't load the 'chromy.stree' example,
   or can't render an image, see the FAQ man page 'man/cat1/shadetree-faq.1'.

AUTHOR
    Greg Ercolano

COPYRIGHT
    (C) Copyright 1996 Cinema Graphics, Inc. All Rights Reserved.

SUPPORT
    If you encounter errors in this document, email [email protected].
    Please supply the name of the file or manpage, enclose clippings of
    the erroneous text, and describe the error.