-----------------------------------------------------
README: License Info Gathering for Q-Chem
-----------------------------------------------------

What is in this README?
------------------------------------------------------------

Here is a list of the different sections of this README.

1) Introduction
2) Single Node Licensing
3) Multi-Node Licensing
4) Troubleshooting
5) Manually Gathering License Info


1. Introduction
-----------------------------------------------------------
Q-Chem utilizes a node-locked licensing scheme. This means
that all computers must be uniquely licensed in order for
Q-Chem to successfully run on it. Our licensing is based on
the unique host id on your network card.

Under most circumstances, succesful completion of the
installation procedure will provide you with the file
license.data which will contain all of the information we
need to issue you a license. Once this file is completed,
e-mail it to license@q-chem.com and a license will be
forthcoming.

Here is a description of how the licensing works.

2. Single Node Licensing
-------------------------------------------------------------

Licensing a computer to use a the single node version of Q-Chem
is very simple. Q-Chem provides a program, $QC/bin/license_info,
that should be run, and the result will be placed in the file
$QC/license.data. The installation script will automatically run
this program. If it becomes necessary to run this program
post-installation the usage is as follows:

$QC/bin/license_info <file_for_output>

3. Multi-Node Licensing
------------------------------------------------------------

When an installation requires several computers to use the
same installation of Q-Chem, the multi-node licensing scheme
should be used.

Several requirements are necessary for this type of licensing
to be effective:

1) Each computer must have the Q-Chem installation available
to them. e.g. on an NFS mounted directory.

2) The path to this installation should be the same on all
computers.

3) The user must have the permission to view the license
file, $QC/aux/license/qchem.license.dat.

Q-Chem comes with a program that is capable of obtaining
licensing information for several remote computers with one
command. This program is $QC/bin/cluster_license.sh and its
usage is as follows:

$QC/bin/cluster_license.sh <file_for_output>

As with the license_info program, cluster_license.sh is run at
installation if a version of Parallel Q-Chem is being installed.

cluster_license.sh utilizes either rsh or ssh to remotely run
the proper licensing commands on the clusters machines. It
obtains the list of machines from a simple text file containing
all of their names. Typically, the .rhosts file that is set up
for rsh can be used for this purpose, but any text file with the
list of hostnames can be used.

This also means that the user running this program will need to
be able to run remote commands without passwords. How to implement
this on a cluster of machines is beyond the scope of this document.

4. Troubleshooting
--------------------------------------------------------------------

Here are the error messages that you can recieve in the licensing
process and some solutions to the problems.

When running cluster_license.sh

1) The file <file_name> does not exist or is not a file.

This indicates that you have specified an incorrect machine
list file. Make sure that you are including the full path
to the file and that the file indeed does exist and try again.

2) Failed to find a remote shell protocol.

This indicates that the program has searched for some rsh or
ssh program in your path, and could not find one. Check to make
sure that you have access to one of these protocols and try
the program again.

3) Calling Unsupported Platform, <PLATFORM NAME>, with
parse_remote_command.

This indicates that you are trying to run the cluster_licensing
program on an unsupported platform. This means that you will have
log into each individual machine and run the license_info program
to obtain the proper information.

When running Q-Chem

1) ReadLicense failed.

This is indicating that the license file,
$QC/aux/license/qchem.license.dat is not readable by the
current user. First try actually just looking at this file with
any text editor. If you cannot view it or it is not there, then
you will have to ask your administrator for help in obtaining the
correct file and setting the proper permissions.

2) Test failed. Failure reason code: 1

This error message indicates that there are no actual licenses in
$QC/aux/license/qchem.license.dat file. Check the file to make sure
there are license numbers in it and it is not blank.

3) Test failed. Failure reason code: 2

The license file that you have is outdate and your license has expired.
Contact Q-Chem to obtain a new license for your program.

5. Manually Gathering License Info
------------------------------------------------------------

1) Why you would be reading this.

If you have gone through the installation process and have
either determined that your setup is not capable of
utilizing the automatic procedure (scripts) for gathering
licenses, or you have tried the automatic procedure and it
has not worked.

2) How should you proceed.

First off if you are almost sure that your local setup will
is capable of performing the automatic installation, we urge
you to try it. It really cannot hurt and might save you some
time. You can invoke the automatic process by the following
command ($QC is the directory in which you set Q-Chem up):

$QC/bin/cluster_license.csh >> $QC/license.data

If this fails, then proceed with the process outlined below.

3) REQUIREMENTS

1. The $QC directory must be mounted and visible to all of the
computers for which you wish to obtain a license. It also
must be available to the user that you are installing Q-Chem
under.

4) PROCEDURE

1. Log into the machine for which you want to obtain a license
using what ever protocol you want (rsh, ssh, telnet, etc...).

2. Run the license collecting program:

For Linux: $QC/bin/get_hostid
For AIX: uname -m | cut -c 3-8
For DEC: $QC/bin/get_hostid
For HP_UX: /usr/bin/uname -i
For others: $QC/bin/license_info

3. The output of this file will look something like this:

sid 02B30A2468

If you had an architecture in which you must run the license_info
program, you will have to obtain the number from the $QC/license.data
file created.

4. If you have not already done so, create a file called license.data.man
somewhere you have write permission. This file will continually
be added to for each machine in the process, so you may want to
open it in another window and keep it open for editing.

If you already created the file, skip to step 5.

5. Create or add to a file called license.data the following line:

<hostname of the computer> <the sid number from get_hostid>

Example:

mycomputer.q-chem.com 02B30A2468

Put each new node on a new line.

6. Repeat steps 1-3 and 5 for each computer that needs a license.

7. E-mail the license.data file to support@q-chem.com, shortly an e-mail will be returned to you with the license file and further instructions
for installation of the license.

QUESTIONS and SUPPORT

If you have any questions about the installation procedure,
please contact support@q-chem.com for further assistance.

Q-Chem, Inc.
website: http://www.q-chem.com

updated July 31, 2003