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 'firstname.lastname@example.org'. - - - 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@example.com 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: firstname.lastname@example.org 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@example.com. Please supply the name of the file or manpage, enclose clippings of the erroneous text, and describe the error.