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.