----------------------------------------------------------------------
The Confluent License Server

Last update: 24 July 1998

Confluent Technical Notes
Copyright (c) 1995 Confluent, Inc.  All rights reserved.
Suggestions or questions to 415-764-1000 or vthought@confluent.com.
----------------------------------------------------------------------

This technical note describes the Confluent license server, its
interaction with Visual Thought, and its use in special system
configurations.


License Directory
-----------------
The following license directory is created during installation of
Visual Thought (assuming Visual Thought has been installed in the
default location):

  UNIX:

    /usr/local/confluent/license

  Windows:

    C:\Program Files\Confluent\Visual Thought...\license

Visual Thought and all licensing utilities will use these directories
for storage and retrieval of licensing information.


License Keys
------------
On UNIX, license keys for Visual Thought are installed with:

  confluent_a key vthought

On Windows, license keys are installed with either the Admin or
Admin_server program.  These programs are run from the
"Start->Programs->Visual Thought..." menu or by double-clicking the
program icons in the folder or program group created by the Visual
Thought installer.  Admin and Admin_server display windows with the
title "ConfluentLM: Create Key File".

Installation of a license key creates a license key file (e.g.,
01.lic) in the license directory.  The key file contains the name of
the license server host on which the key was installed.

Visual Thought and the license server use license key files to
determine information such as authorized license server hosts, number
of authorized licenses, and license expiration.


License Server Communication
----------------------------
When Visual Thought runs, it attempts to request a license from either
a local or remote license server.  Communication between Visual
Thought and the license server is accomplished using UDP messages via
port number 1484.

Port 1484 should be unique to the Confluent license server.  It was
obtained from the Internet Assigned Numbers Authority (IANA).
However, if this port is already used, an alternate port number can be
used on UNIX by adding the following line to the /etc/services file:

  confluent_elmd  xxxx/udp

where "xxxx" is the port number.  The port number must be greater than
1024.

WARNING: You cannot successfully use an alternate port number on UNIX
by changing the confluent_a script to add the "-p" option to the
confluent_lm command.  This merely tells confluent_lm to use an
alternate port number.  It has no effect on the port number used by
Visual Thought to request a license from the license server.


Evaluation Licenses on UNIX
---------------------------
On UNIX, for an evaluation license (i.e., the type supplied for
purposes of product evaluation), Visual Thought always assumes that
the license server is running on the local host.  If it is not
running, Visual Thought starts it automatically with:

  confluent_a start

Visual Thought attempts to request a license from a license server
running on the local host.

The following is required to set up the license server for an
evaluation license:

  1. Install the license key on any host with:

       confluent_a key vthought

     The host must have write access to the license directory.

  2. Start the license server on the host where Visual Thought will be
     running with:

       confluent_a start

     This step is optional, since Visual Thought will automatically start
     the license server if it is not running.


Evaluation Licenses on Windows
------------------------------
On Windows, for an evaluation license (i.e., the type supplied for
purposes of product evaluation), a license server is not used.

The following is required to set up an evaluation license:

 1. Install the license key as follows:

    Run the Admin program.

    Type the license key into the "Key:" field.

    Click the OK button to install your key and terminate the program.


Permanent Licenses
------------------
For a permanent license (i.e., the type supplied when Visual Thought
is purchased), the license key is only valid for installation on a
single host machine.  The valid host is specified through the host
server code.


Permanent Licenses on UNIX
--------------------------
On UNIX, the host server code is obtained by executing the following
on the host:

  confluent_a code

The host server code must be provided to Confluent to obtain a
permanent license key.

Visual Thought obtains the name of the license server host from the
license key file.  If this host is the local host and the license
server is not running, Visual Thought starts it automatically with:

  confluent_a start

Visual Thought attempts to request a license from a license server
running on the local or remote host, as specified by the license key
file.

The following is required to set up the license server for a permanent
license:

  1. Kill all currently running license servers with:

       confluent_a kill all

     This will kill license servers started on the local and remote
     hosts for any previously installed evaluation and permanent licenses.
     This step is important to prevent license servers for evaluation
     licenses from creating problems locating the license server for the
     permanent license.

  2. Install the license key on the license server host with:

       confluent_a key vthought

     The host must have write access to the license directory.

  3. Start the license server on the license server host with:

       confluent_a start

     For convenience, this operation can be placed in /etc/rc.local.


Permanent Personal Licenses on Windows
--------------------------------------
On Windows, the host server code for a permanent personal license is
obtained as follows:

 1. Run the Admin program.

    The "Server Code:" field contains the host server code for the
    machine.

The host server code must be provided to Confluent to obtain a
permanent license key.

The following is required to set up a permanent personal license:

 1. Install the license key as follows:

    Run the Admin program.

    Type the license key into the "Key:" field.

    Click the OK button to install your key and terminate the program.


Permanent Floating Licenses on Windows
--------------------------------------
On Windows, the host server code for a permanent floating license is
obtained as follows:

 1. Run the Admin_server program.

    The "Server Code:" field contains the host server code for the
    machine.

The host server code must be provided to Confluent to obtain a
permanent license key.

The following is required to set up the license server for a permanent
floating license:

 1. Install the license key as follows:

    Run the Admin_server program.

    Type the license key into the "Key:" field.

    Click the OK button to install your key and terminate the program.

 2. Start the license server as follows:

    Open up the Control Panel and run the "ConfluentLM" applet.

    The ConfluentLM applet displays a window with the title "Confluent
    License Manager".

    Click the "Launch" button if the panel says the server is stopped.

    Click the OK button to close the window.


Licensing Multiple Installations
--------------------------------
Visual Thought floating licenses can be used transparently across
multiple installations and all supported platforms.  For example, a
5-user floating license allows 5 concurrent users on any combination
of SunOS, Solaris, HP-UX, and Windows machines using the same license
key.

To serve floating licenses for Visual Thought 1.4 across multiple
installations (UNIX, Windows, or any combination thereof), the
important points to remember are:

 1. Normally, there should be exactly one license server process to
    serve all installations in the network.  If both UNIX and Windows
    versions of Visual Thought are used, it is highly recommended that the
    license server run on a UNIX workstation because of the greater
    robustness and reliability inherent in UNIX.

 2. The license directories of all installations must have identical
    copies of all license key files (e.g., 01.lic, 02.lic, etc.).  The
    license key files are installed in the license directory of the
    installation used by the license server.  They must be copied to the
    license directory of the other installations.


Searching for License Servers Outside the Network Broadcast Mask
----------------------------------------------------------------
If Visual Thought and Confluent license servers are running on
different subnetworks, the default method for locating a license
server may fail.

By default, license servers are located through a system broadcast
message.  The scope of the broadcast is limited to the broadcast mask,
which is normally restricted to the local subnetwork.  On UNIX, the
broadcast mask can be determined with:

  ifconfig -a

In order to locate license servers on systems outside the broadcast
mask, these systems must be specified with the CONFLUENT_ELMHOST
environment variable.  The value of CONFLUENT_ELMHOST is a
colon-separated list of hosts.  The hosts can be specified either by
name or IP address.

The list of hosts can be specified with CONFLUENT_ELMHOST in either
search mode or absolute mode.

In search mode, the list of hosts is added to the broadcast list for
the local subnetwork.  Messages are sent in parallel to the hosts in
the list and to all systems on the local subnetwork.  For example,
using

  setenv CONFLUENT_ELMHOST host1:host2

causes messages to be sent in parallel to host1, host2, and all
systems on the local subnetwork.

In absolute mode, no broadcast is done.  Only the hosts in the list
are tried.  If multiple hosts are listed, each is tried in turn until
the timeout period expires.  Absolute mode is specified by preceding
the host list with an at (@) sign.  For example, using

  setenv CONFLUENT_ELMHOST @host1:host2

causes messages to be sent in turn to host1 and host2.


Connecting to License Servers on a Slow Network
-----------------------------------------------
When a license server is required, Visual Thought must connect to the
license server to obtain a license and become fully functional.

On a very slow network or server, attempts to connect to a license
server may fail because of a timeout while waiting for a connection.
The timeout can be prevented by increasing the timeout period.

The default timeout period is 15 seconds.  This value can be changed
by setting the ELMTIMEOUT environment variable.  For example,

  setenv ELMTIMEOUT 30

changes the timeout value to 30 seconds.

For very severe network problems, it may also be necessary to change
the number of times a connection attempt is retried.  The default
number of retries is 2 (3 attempts are made to connect).  This value
can be changed by setting the ELMRETRIES environment variable.  For
example,

  setenv ELMRETRIES 4

changes the number of retries to 4.  It is very unlikely that it
should be necessary to change ELMRETRIES.

A total of ELMRETRIES+1 attempts are made to connect to a license
server, spaced ELMTIMEOUT/(ELMRETRIES+1) seconds apart.  Thus, by
default 3 attempts are made, 5 seconds apart.


Reasons for Failure to Obtain a License
---------------------------------------
The following are possible reasons why Visual Thought might be unable
to obtain a license.  These cases apply to both UNIX and Windows, but
the associated diagnostic and corrective commands apply only to UNIX.

In preparation for the following steps, change the working directory
to the Visual Thought installation directory with (assuming Visual
Thought has been installed in /usr/local/confluent):

  cd /usr/local/confluent

Modify the above directory path accordingly if Visual Thought was
installed in a different directory.

 1. The license directory is unreadable.

    Obtain the permissions for the license directory with:

      ls -ld license

    They should be "drwxrwxrwx" (i.e., all permissions for all users).
    This ensures that all license files are readable and log files in the
    license directory are writable.

    If the permissions for the license directory are not "drwxrwxrwx",
    set them with:

      chmod 777 license

 2. The license files are unreadable.

    Obtain the permissions for the license files with:

      ls -l license/*.lic

    They should be "-rw-r--r--", with at least read permission for all
    users.  If not, set the permissions for the license files with:

      chmod 644 license/*.lic

 3. No license files are present in the license directory.

    Obtain a list of the license files in the license directory with:

      ls license/*.lic

    The available keys can also be listed with:

      confluent_a keys

    This generates output of the form:

      ID Program  Server     Tokens Type  Starts   Expires 
      -- -------  ------     ------ ----  ------   ------- 
      01 vthought aspen          5  float    --       --   

    If there are no license files in the license directory, install
    them with:

      confluent_a key vthought

 4. Extra incorrect license directories.

    Determine the location of all license directories in the
    installation with:

      find . -name license -print

    The only output should be "./license".  Any other license
    directories located with the above command should be removed.
