keys.doc

speech signal process tools

                         ENTROPIC RESEARCH LABORATORY, INC.


       TECHNICAL MEMORANDUM

       SUBJECT: Living with the Entropic License Manager System

       ID: ETM-S-91-xx:rap

       VERSION: 1.2

       DATE: 1/22/93

       AUTHOR: Alan Parker

       1 .  Introduction

            Instead of requiring that a given software license be  associated
       permanently  with a given CPU, Entropic uses a floating license system
       that can assign software licenses dynamically as needed to any host on
       a  network.   This  document describes how this system works, provides
       guidelines for setting it up, and provides information to  help  solve
       common problems.

       1 .1 .  Goal of the License Manager System

            The license manager system is a technical means  of  implementing
       our  software  licensing  policy.    Our  current policy is to license
       waves+ on a per-user basis and ESPS on a per-host basis.   In the case
       of  waves+  the  license  manager will allow no more than the licensed
       number of waves+ to be running at any  one  time  on  the  network.  A
       waves+  license  is  checked out automatically when waves+ is run, and
       checked back in when waves+  terminates.   In  the  case  of  ESPS,  a
       license  must  be  checked out for a particular host before anyone can
       run ESPS programs on that host.  Until the license is checked back in,
       any  ESPS  programs  can  be  run on that host by any user (given that
       ordinary Unix file permissions are appropriate).  The ESPS license  is
       checked  out  for  a  host  in  one of two ways.  It can be explicitly
       checked out by the user by using the command echeckout, or  simply  by
       running an ESPS program.   If an ESPS program is run, and the required
       license is not checked out on the host, then the program will  attempt
       to  check  it out.  If that succeeds, then a license is checked out on
       that host until it is freed by the user.

            Our reasoning for the distinction between the  (per-user)  waves+
       licensing  and  the  (per-host)  ESPS licensing is as follows:  Unlike
       waves+, the typical ESPS program only runs for a short time period and
       does  not  provide  an  environment  in  which the user remains for an
       extended period.  Most ESPS programs are command line oriented and can
       be used in Unix shell scripts.  Therefore, if we had each ESPS program
       check out and free a license (as waves+ does) it would be possible for
       scripts  to  fail in unpredictable ways, since a license might a taken
       away between steps within the script.   Our solution  to  this  is  to










       ETM-S-91-xx:rap                                                 page 2


       have  a  program  which  checks out a license and one to free license.
       During the time that a license is checked out for a  given  host,  any
       ESPS  programs can be run on that host.    It does not matter how many
       users there are on that host or how many of those  users  are  running
       ESPS programs.

            The Entropic License Manager System  consists  of  the  following
       major components: elmd, elmadmin, echeckout, the license keys, and the
       various ESPS user programs.

       1 .2 .  How It Works

            The license manager daemon (elmd) is started and left running for
       as  long  as  any  Entropic programs are going to run.  It is normally
       started at boot time and simply left running forever.   When a  client
       program  requests  a license, the license manager checks the key files
       and determines if any licenses of the requested type remain.   If  so,
       then the count of available licenses is decremented and the requesting
       process is granted permission to continue.

            Client programs communicate with the  license  manager  with  the
       same  facility  used  by  the network file system (NFS), so any system
       that supports NFS should be able to run our license manager system.

            The client programs can be on a different host than the one  run-
       ning  the license manager daemon (elmd).  But in this case, the client
       programs must know which host is running elmd.   This  information  is
       passed  to  the  client  programs  via  the  Unix environment variable
       ELM_HOST.   It is simply set to the name of the network  host  running
       elmd.

            As mentioned earlier, waves+ checks out a license each time it is
       started  and  frees  that  license when it exits.   ESPS programs (all
       other programs except waves+ and its attachments) check to see  if  an
       ESPS license is checked out before they run, but they do not check out
       the license themselves.   The program echeckout  checks  out  an  ESPS
       license  and  then  holds  it (by putting itself into the background).
       The license is freed by causing echeckout to exit.   A program is pro-
       vided  to  do  this; efree.  Under certain conditions this program can
       fail to find echeckout.  In this case, someone will have to  find  the
       echeckout with ps and kill it manually.

       1 .3 .  Network Timeout

            The client programs (that is all ESPS programs and  waves+)  will
       timeout  in a default 10 second interval if they cannot get a response
       from the license manager daemon.   This should be enough time for  all
       but  the busiest networks.  However, we have provided a means to allow
       users to adjust  this  timeout  interval.   The  environment  variable
       ELM_TIMEOUT can be set to the desired timeout interval (integer values
       only).   So, for example, to set the timeout interval to 15 seconds do
       setenv ELM_TIMEOUT 15.  (Or whatever works with your shell.)



       Version 1.2                      ERL                           1/22/93







       ETM-S-91-xx:rap                                                 page 3


       1 .4 .  Waves Related ESPS Programs

            There is a set of ESPS programs that provide  conversion  support
       and  are included with the waves+ product.  These programs will run if
       a network has a valid waves license installed.   No  license  need  be
       explicitly  checked  out for these programs.  There is no limit to how
       many hosts these programs can be used on.  These programs are: addfea,
       addfeahd, addgen, bhd, btosps, comment, fea_element, featosd, formant,
       hditem,  hdshrink, ils_esps, mu2esps, pplain,  psps,  sdtofea,  sgram,
       sigtosd, testsd, splay, and tofspec.

       1 .5 .  User Written Programs

            User written programs compiled and linked with the ESPS libraries
       will  be  under  the Entropic license manager system.   These programs
       will only run if an ESPS license is checked out.   Also, if a site has
       a  source  license  to  ESPS and recompiles any of the above mentioned
       waves+ related programs, then they revert to the ESPS  license  rules;
       that is they will only run if an ESPS license is checked out.

       2 .  License Manager Setup

            The product installation instructions give sufficient information
       for  the  general  installation  of all of the software, including the
       license manager system.   Before installing  the  software,  you  must
       decide  which  host  is to run the license daemon (elmd).   While this
       can be any host that is reachable on  your  network,  there  might  be
       local  considerations  that make one host better or worse than others.
       Often the central server machine (if there  is  one)  is  the  logical
       choice.  Note  that  the license manager need not run on the same host
       which stores the ESPS files.   A poor choice of a machine to run  elmd
       on  would  be a machine behind several network bridges, one that tends
       to be down often, or one that might be considered a  personal  machine
       by a particular user.

            Once you decide which host will run elmd, you need  to  get  keys
       made  for  that  host.    Note that the keys are bound to a particular
       host, so that once the keys are made, they and elmd cannot be moved to
       another host (for obvious reasons).  Of course, if you have legitimate
       reasons for moving elmd and the keys to another host, we will give you
       new keys.   To install the keys, you must first run the program elmad-
       min -c which generates a server code that you provide to us.  We  take
       this  server  code,  along with the information about what you bought,
       and generate a key.

            The best way to communicate the server code to us is via email or
       FAX.   It  is best if an actual Unix script listing of the elmadmin -c
       output is sent.  This greatly reduces the chance for errors in copying
       the  server  code.   Voice telephone can be used, but it is more error
       prone.

            After the keys are installed echeckout and waves+ should run  (if
       the  proper  keys  were installed).   When running on a different host


       Version 1.2                      ERL                           1/22/93







       ETM-S-91-xx:rap                                                 page 4


       than elmd is running on, then the environment variable  ELM_HOST  must
       be set to the hostname of the host running elmd.

       2 .1 .  ELMD Initialization

            The license manager daemon, elmd, will  not  issue  licenses  for
       about  three  minutes after it first starts up.   If you try and run a
       program during this interval, you will get  a  message  informing  you
       that  the  daemon  is  initializing and to try again in a few minutes.
       The reason for this is to allow an instance of the daemon to  resynch,
       in the event that it restarts while licenses are checked out.

       2 .2 .  A Word About the ESPS Program Files

            One advantage of this license manager  system  is  that  you  can
       store  the  ESPS  program files on as many machines on your network as
       you see fit, since the number of copies stored is independent  of  how
       many  copies  may  run.   A  reason to store the files is to avoid NFS
       latencies resulting from dragging large binaries across  the  network.
       This  is   tradeoff of performance and disk usage that must be made at
       each site.  Also, individual users can choose to store copies of  cer-
       tain programs locally.

       3 .  Trouble Shooting Chart for License Keys

       3 .1 .  Errors When Entering Keys:  (Messages from elmadmin -c)