TRUEGRID UNIX INSTALLATION/LICENSING/UPGRADE 1. Initial UNIX Installation & Licensing 2. Upgrading a Perpetual License Authorization 3. Upgrading TrueGrid 4. Using the Network License in UNIX 5. Moving the TrueGrid License Manager ================================================================= 1. Initial UNIX Installation & Licensing ================================================================= a. General Notes All of the TrueGrid files are packaged into one file. You must obtain the appropriate file for your system either from the TrueGrid distribution CD/DVD or from the TrueGrid download page on the web. The component files will only be extracted from this file when your computer has been authorized to run TrueGrid. You must obtain an authorization code from XYZ Scientific Applications to authorize your computer. A license Manager will be installed on your computer to complete the authorization process. The License Manager and authorization process are very picky. For example, "XYZ " is a different company name than "XYZ", even though the final space does not show. Do not bother saving the authorization code since it is only good once. If you try to reuse it, it will destroy any existing valid authorization. You may have a firewall that blocks unauthorized communications between processes, such as between TrueGrid (tg.exe) and the TrueGrid License manager (tglm.exe). You must grant permissions so that these two processes can communicate. The procedure for allowing such communications varies between the different firewalls and you may have to check the documentation for the appropriate method. You may also wish to use the TGPORTS feature described in the TrueGrid License Manager User's Manual. b. Choose a Machine to run the TrueGrid License Manager First, decide which machine will run the TrueGrid License Manager. This machine should be reliable. The TrueGrid License Manager will be node-locked to this machine, while TrueGrid maybe run from any machine which is able to communicate, via TCP/IP, with this machine. Then, log on (as SuperUser) to this machine. Choose an installation directory. In a homogeneous network, the easiest way is to share TrueGrid with other similar machines by exporting the TrueGrid directory and mounting it on each of the client machines. In this case, the user's path to the TrueGrid executable is the same on all machines and no additional work is required. c. Create an Installation Directory Once you have decided how to best install TrueGrid in your local environment, go to the directory where you wish to install TrueGrid. If you only want to install the TrueGrid License Manager software on this machine, then choose some directory which can later be deleted, e.g. "/tmp/truegrid" or "/var/tmp/truegrid". During the authorization process you will be prompted to specify a location for the license files. At that time, you may specify any directory on your local machine. After the installation is complete, simply delete the temporary directory and all the files it contains. Secure environments will want to take advantage of this capability to have only the license manager programs owned by the SuperUser. However, in a typical small-business installation, most users just go ahead and install the software along with the TrueGrid License Manager. /usr/TrueGrid is the default location. With a time restricted license, you may NOT move the installation directory after authorization. d. Execute the Setup Program As indicated above, you must be SuperUser on the local machine, in order to install the TrueGrid License Manager. You may use the tgperms utility to alter permissions after installation. For further information about the features in the TrueGrid License Manager, see the TrueGrid License Manager Manual. Contact XYZ Scientific Applications for a copy of the this manual. If you have a CD or DVD and it has been mounted on your system, then run the setup program designed for your machine. For example, if the CD or DVD is mounted on /cdrom and you are installing on a SUN computer, then run /cdrom/tg*_sun10.exe where * is replaced by the version number. If you have been instructed to download an executable from our web page, then you should download the file appropriate file for your machine. After downloading the file, you will need to add execute permissions to this file. Run this file. If you see a message that a log file cannot be created, then Ctrl-c out of the program. This message means that you do not have write permission in the current working directory. This must be corrected before you can proceed. You will be asked the following questions by this program: Step 1. Choose number 1 to create a new installation. INSTALLATION OPTON - NEW OR UPGRADE 1 - Create a new installation 2 - Upgrade an existing version 1 or 2: Step 2: The default directory is /usr/TrueGrid. If you choose anything different, you will also have to set the TGHOME environment variable. Enter the Directory where you wish to install TrueGrid Directory: Step 3. If the directory does not exist, you must grant permission to create it. In the example below, assume that /usr/TrueGrid was chosen as the directory asked for above. The directory for a trial or annual license cannot be changed later. The license files created in the license directory must not be altered by any user or by any backup system. Some backup systems change times on files in order to track unaccessed files; such backup systems will disable the license. You must not rename, move, link to, change permissions on, or change the ownerships of the license files created during authorization. For a reinstallation, please contact XYZ Scientific Applications, Inc.(info@truegrid.com) for a new key. Perpetual license holders will be able to move their installations and even restore them from backup without any adverse effects. Directory "/usr/TrueGrid" does not exist. Do you want to create this directory? y or n: Step 4. It is possible to store the authorization file in a directory different from the other TrueGrid data files. This directory must be local. The authorization file and license programs will be copied to this directory. In most cases, type the enter key for the default. LOCATION OF AUTHORIZATION FILES Enter the directory where the authorization will be kept (Default is "/usr/TrueGrid") Directory: Step 5. Identify the computer that will be licensed. In this example, XYZ1 is the computer name. You may need to choose a different host name (an IP address is okay, too) if remote machines do not know the default host name. This is the case when the host name is not fully-qualified and remote users will be on different networks. HOST NAME OF DESIGNATED TrueGrid SERVER Enter the host name (or IP address) of the machine on which the TrueGrid License Manager will reside. (Default is "XYZ1") Host Name: Step 6. Enter a company name. There is no default. What ever you enter will appear on the screen whenever the program is run. NAME OF COMPANY Enter the name of your company or organization Company Name:XYZ e. Obtain an Authorization Key Step 7. E-mail XYZ at info@truegrid.com or call at (925) 373-0628 for an authorization key. If you are installing from the tgauth program in an existing installation, then you may leave the authorization program running until your receive the key, or kill it using Ctrl-c or Ctrl-d. If you do kill the program, then you will need to re-enter the above information in exactly the same way, once you get the authorization key from XYZ Scientific Applications, Inc. If you are installing from CD or DVD or executing an archive file that you have downloaded from our web page, then you may NOT use the Ctrl-c shortcut. Every time that you re-execute the archive file, the installation program acts as if you are initiating a new authorization! Your e-mail should include the following information: 1. The machine type (IBM, DEC, SGI, SUN, or HP), 2. the company name that you have entered, 3. the machine ID, 4. the associated checksum (or check), 5. the license duration (trial, annual, perpetual) OBTAIN AN AUTHORIZATION CODE FROM: XYZ Scientific Applications, Inc. 1324 Concannon Boulevard Livermore, CA 94550 PHONE (925) 373-0628 FAX (925) 373-6326 REPORT THIS INFORMATION TO XYZ Company Name: XYZ Machine ID: 12345678 Checksum: B 5432112345 Number of Users Authorization Type (perpetual, trial or special) ENTER YOUR AUTHORIZATION CODE Authorization Code: f. Entering the Authorization Code Step 8. If you killed tgauth, start it again and follow the steps above. Enter the Authorization code exactly. Sometimes the first character is not alphabetical. The rest are upper case. There is no space between every five characters. ENTER YOUR AUTHORIZATION CODE Authorization Code: Step 9. Enter the check sum you received. There are no spaces. Checksum: If authorization does not succeed, then DO NOT REINSTALL TrueGrid! This will not help, as the checksum changes after each authorization attempt. There are two common problems listed below. Please report any other kind of error directly to XYZ Scientific Applications, Inc. (Info@truegrid.com) Please report any confusion resulting from reading this document to the same people. If there is a checksum error, make sure that you have entered the authorization code correctly. Leading or trailing spaces can cause errors. Hidden characters can also cause problems. Also, keep in mind that the authorization code contains no digits; so make sure that O's are not entered as zeroes. Cutting and pasting each item from the e-mail is your best guarantor of accuracy. Note, also, that this message can mean that the company name used to generate the key is different than the one you entered. A subtle way that the company name can differ is that there is an extra space after the company name. You can check and change the company name in the .tgauth file directly and use ./start_tg to start the TrueGrid License Manager. If you still see the error, then verify whether or not the original information you reported to XYZ Scientific Applications has changed. If so, then you will need to obtain a new authorization key (unless this is a permanent license). For permanent authorizations, just use a "0" checksum. You may get the message "this machine is not authorized" when you try to start the license manager. Strictly speaking, this means that the machine ID that the software is reading from the local machine does not match the machine ID that has been encoded in the authorization code. The most common reason for this message is that you are not actually on the TrueGrid License Manager machine, but are instead attempting to install from a mounted directory on another machine. g. Starting the TrueGrid License Manager Step 10. Typically you want to start the license manager so that you can begin running TrueGrid. START THE LICENSE MANAGER DAEMON NOW (y or n)? Otherwise, you can start the license manager by running ./start_tg. The TrueGrid License Manager must be restarted whenever the operating system is re-booted. This can be done with the ./start_tg file, or you can configure the machine to automatically restart the license manager whenever the machine is re-booted. This is done by adding a line to the /etc/inittab file (or /etc/rc file). For example: tglm:23:once:/usr/TrueGrid/LM/tglm /usr/TrueGrid The latter part of this line is found in the start_tg file. You will need to be root to make these modifications to the inittab (rc) file and you should know what you are doing. Consult the tgauth.log file or the TrueGrid License Manager Manual for further information about how to configure the machine to automatically restart the TrueGrid license manager when the operating system is re-booted. If you decide to configure the machine to automatically start the License Manager, then keep in mind that programs started from rc files or from inittab are started with root permission. So make sure that the LM/tglm executable cannot be modified or moved by anyone other than a root user. This may require modifying permissions on LM/tglm and/or permissions on LM. h. Set the User's Path Add the TrueGrid directory to the user's path variables, or tell users how to do this. No environment variables need be set, unless a component of the path to the TrueGrid installation directory is hidden. In such a case, set the environment variable TGHOME equal to the name of the directory where TrueGrid is installed. This name must be specified relative to the user's point-of-view and the full path name should be used. i. Make the Documentation Available Copy the TGMAN.pdf, EXAMPLES.pdf, TGOUT.pdf, and TGTUT.pdf files from the DOCUMENTS directory of the installation disk or from the download page at the TrueGrid web site to a location where users can find them. Let users know where these documents are and how to view them. ================================================================= 2. Upgrading a Perpetual License Authorization ================================================================= a. Maintenance If you have a perpetual license, then at some point, the TrueGrid License Manager will not allow you to run newer versions of TrueGrid until you upgrade your license authorization key held in the .tgauth file found in the TrueGrid directory. If the maintenance for your perpetual license is current, you can contact XYZ Scientific Applications, Inc. for a new authorization code. If your maintenance has lapsed, you must first purchase additional maintenance before obtaining a new authorization key. If you are not sure, contact XYZ Scientific Applications, Inc. to determine your maintenance status. b. Acquiring a TrueGrid Authorization Code Upgrade You will probably have to be root to upgrade the license. Run the tgauth program found in the TrueGrid directory. The default directory and host name is usually the correct choice. The company name should be UPGRADE. You might see something like the following when you run tgauth: Step 1. This is typically the same directory you used when you installed TrueGrid for the first time. Type Enter for the default. LOCATION OF AUTHORIZATION FILES Enter the directory where the authorization will be kept (Default is "/usr/TrueGrid/mb") Directory: Step 2. The default is usually correct and in this case, just type Enter. HOST NAME OF DESIGNATED TrueGrid SERVER Enter the host name (or IP address) of the machine on which the TrueGrid License Manager will reside. (Default is "xyz1") Host Name: Step 3. You should use the same name used when you first installed Truegrid. If you change the name, then all clients will have to get a new copy of the .tgauth file. The easiest method is to use the name UPGRADE, which automatically uses the name you used previously. NAME OF COMPANY Enter the name of your company or organization Company Name:UPGRADE Step 4. Report the company name as UPGRADE, the machine ID, and the Check sum. The number of users and authorization type will already be know by the person receiving your request, unless these things have changed since the last time an authorization code was send. You can also send this request by email to info@truegrid.com. OBTAIN AN AUTHORIZATION CODE FROM: XYZ Scientific Applications, Inc. 1324 Concannon Boulevard Livermore, CA 94550 PHONE (925) 373-0628 FAX (925) 373-6326 REPORT THIS INFORMATION TO XYZ Company Name: UPGRADE Machine ID: 123456789 Checksum: B 123456789 Number of Users Authorization Type (perpetual, trial or special) ENTER YOUR AUTHORIZATION CODE c. Installing an Authorization Code Upgrade This next step cannot be performed until XYZ Scientific Applications, Inc. has issued you a new authorization code and a new check sum. There is no need to stop the TrueGrid License Manager. If you killed tgauth in the step above, then re-run the tgauth program and make the same choices you made the first time you tgauth. When you get to the stage where the new authorization code and check sum are needed, enter them exactly as they were received. Step 5. Enter the Authorization code exactly. Sometimes the first character is not alphabetical. The rest are upper case. There is no space between every five characters. ENTER YOUR AUTHORIZATION CODE Authorization Code:ABCDE FGHIJ KLMNO PQRST UVWXY Z Checksum:B 123456789 If you make a mistake, you will receive an error message such as: Checksum Error ENTER YOUR AUTHORIZATION CODE Authorization Code: Try entering the authorization code and check sum again. If you continue to have difficulties, contact XYZ Scientific Applications, Inc. If everything goes well, you should see the following: AUTHORIZATION ENTRY SAVED TO /usr/TrueGrid/mb/.tgauth UPDATED START UP FILE "start_tg" IN "/usr/TrueGrid/mb" START THE LICENSE MANAGER DAEMON NOW (y or n)?n TrueGrid License Manager Started If the TrueGrid License Manager is running, be sure to answer no to starting the TrueGrid License Manager daemon. Then notify the TrueGrid License Manager that the file .tgauth file has been modified by running LM/tgperms. If the TrueGrid License Manager was killed before you began the authorization procedure, then answer yes to this question and it will be started. Do not bother saving the authorization code since it is only good once. If you try to reuse it, it will destroy any existing valid authorization. ================================================================= 3. Upgrading TrueGrid ================================================================= When you upgrade to a new version of TrueGrid, be sure that you are licensed to run it. If you are not sure if you are licensed to run this new version, contact XYZ Scientific Applications first to be sure. If you need to upgrade your license, see the section above. If you wish to experiment, be sure to make a backup copy of tg.exe, the *.data?, and menudesc.? files where * and ? are the usual wildcards. When you follow these upgrade procedures, the authorization file, .tgauth, will not be modified. If you have a TrueGrid distribution CD or DVD mounted on your system, then change to the directory where TrueGrid is currently installed. Execute the appropriate setup program on the CD or DVD using a full path name to the executable. For example, if the CD or DVD is mounted on /cdrom and if you are upgrading an IBM RS/6000 version of the software, then you would execute /cdrom/tg*_ibm.exe where * is replaced by the version number. NOTE: If you see the name of the CD's or DVD's installation file as, for example, "tg*_ibm.exe;1", then the CD or DVD has not been properly mounted See your system's man pages for the proper mount flags. If you have been instructed to download an executable from our web page, then you should know that it is the same file as just described. After downloading the file, you will need to add execute permissions. Then, you should run this file. Step 1. Choose the upgrade option (2) INSTALLATION OPTON - NEW OR UPGRADE 1 - Create a new installation 2 - Upgrade an existing version 1 or 2: Step 2. Answer with "." as the name of the directory where TrueGrid is currently installed. Enter the directory where TrueGrid was last installed. (Default is /usr/TrueGrid) Directory: Step 3. The usual answer to this question is no (n). If you have set up a separate license directory, then you must indicate this in order for the license directory to be upgraded as well. LOCATION OF AUTHORIZATION DIRECTORY Have you set up a separate authorization directory that is different from the location of the current TrueGrid Release Directory? y or n: Step 4. You can choose to install the new TrueGrid in a different location, but it is best to install in the same location. LOCATION OF NEW INSTALLATION Do you want the new version to be placed in the same location as the old version (this does not mean you must overwrite the old version)? y or n: Step 5. Choosing the option to save the existing installation will simply rename the current installation directory by appending a digit to its name. OPTION TO BACK UP THE OLD VERSION Do you want to save the old version of TrueGrid? y or n: Copy the TrueGrid manuals in PDF format from the DOCUMENTS directory of the installation disk or from the download page at the TrueGrid web site to a location where users can find them. Let users know where these documents are and how to view them. ================================================================= 4. Using the Network License in UNIX ================================================================= To be able to use the network license, TrueGrid must first be installed on a machine other than the machine running the TrueGrid License Manager. The machine running the TrueGrid License Manager can be another UNIX system, a WINDOWS system, a LINUX system, or a MAC system. To install TrueGrid on a machine other than the machine running the TrueGrid License Manager, create a directory where you wish to install TrueGrid. Change to that directory. Copy the .tgauth authorization file from the machine running the TrueGrid License Manager to this new directory. If you have a Truegrid distribution CD or DVD mounted on your system, then run the appropriate setup program on the CD or DVD using a full path name to the executable. For example, if the CD or DVD is mounted on /cdrom and if you are upgrading an IBM RS/6000 version of the software, then you would run /cdrom/tg*_ibm.exe where * is replaced by the version number. If you have been instructed to download an executable from our web page, then you should know that it is the same file as just described. After downloading the file, you will need to add execute permissions. Then, you should run this file. Choose the upgrade option (2). Ignore the warning about files about to be overwritten. Copy the TrueGrid manuals in PDF format from the DOCUMENTS directory of the installation disk or from the download pageat the TrueGrid web site to a location where users can find them. Let users know where these documents are and how to view them. ================================================================= 5. Moving the TrueGrid License Manager ================================================================= You must contact XYZ Scientific Applications to move the TrueGrid License Manager to a different machine. You will be asked to document the removal of the TrueGrid License Manager from the old computer before you can receive a new authorization code for another computer. This will require the same procedures as a new installation. If a line was added to the /etc/inittab file (or /etc/rc file) so that the TrueGrid License Manager restarted automatically when the system boots up, then that line should be removed. An example of such a line is: tglm:23:once:/usr/TrueGrid/LM/tglm /usr/TrueGrid