1. Install the hlserver files. See below for OS specific instructions.
   
   
2. Using the sample provided, create hlserver.conf. You should at least change the IP range for "GROUP lan" to reflect your local setup. See below for an explanation of the hlserver config file.
   
   
3. Put the keys provided into .keys (Linux/OS X) or keys.txt (Windows). See below for an explanation of the key strings.
   
   
4. Start hlserver up. See the following chapter, Running the Server for OS specific instructions.
   
   
5. Pass on to your users the information in Application Config so they can configure their software installs to access the floating license server.

If your users encounter any problems accessing the floating licenses, see Trouble Shooting for steps you can follow to track down the problem.

Linux Install

Typically you'll want be root and extract the TGZ file into /usr/local though that's not a strict requirement. If you install into somewhere other than /usr/local/headus, you'll need to change the HEADUS_HOME variable in etc/hlserver.run.

The following files make up the Linux license server installation:

etc/hlserver 

This is the server application. It need not be run with any special privileges unless the PORT used (see below) is under 1027.

etc/hlserver.conf 

The contents of this file, explained in detail below, controls the behavior of the server.

etc/hlserver.log 

This is a series of date stamped log messages from the server showing, amongst other things, who is grabbing which licenses.

etc/hlserver.run 

This is a script that can be used to start the server on boot, and stop it on shutdown. Installation instructions are in the file.

etc/hlmanager 

This is the manager application. See "The Manager" chapter for details.

lib/.keys 

This file holds the floating license keys.

OS X Install

Select or create a new user that will be used to run the hlserver daemon. Login as that user, open up a shell window, extract the TGZ file into a temporary directory, change to that directory and run the setup script ...

 tar xvfoz hlserver-osx-??????.tgz --directory=/tmp
 cd /tmp/hlserver
 ./setup

First you'll be asked to edit the config file; you should at least change the IP range for "GROUP lan" to reflect your local setup.

Next the keys file is checked; if you have your license keys already, cut'n'paste them into the .keys file, otherwise email the 5 code strings to your vendor for some license keys.

Re-run the setup script and you'll be asked for an installation location. by default the script will want to put the binaries and config files into /usr/local/hlserver, but you can type in a different path at the prompt if you wish.

If the setup script runs smoothly, hlserver will be started and hlmanager is run as a final check. hlserver will be automatically restarted whenever the system is rebooted, and you can stop and start it via the launchctl command.

The following files make up the OS X license server installation:

hlserver 

This is the server application.

hlserver.conf 

The contents of this file, explained in detail below, controls the behavior of the server.

hlserver.log 

This is a series of date stamped log messages from the server showing, amongst other things, who is grabbing which licenses.

hlmanager 

This is the manager application. See "The Manager" chapter for details.

.keys 

This file holds the floating license keys.

Windows Install

Login as a user with Administrator privileges, and run the EXE file.

The following files make up the Windows license server installation:

hlserver.exe 

This is the server application. It need not be run with any special privileges unless the PORT used (see below) is under 1027.

hlserver.conf 

The contents of this file, explained in detail below, controls the behavior of the server.

hlserver.log 

This is a series of date stamped log messages from the server showing, amongst other things, who is grabbing which licenses.

hlserver.ini 

Edit this file to change the server start-up command line arguments.

hlmanager.exe 

This is the manager application. See "The Manager" chapter for details.

keys.txt 

This file holds the floating license keys.

Configuration

The config file is used to control access to the server and licenses. The simplest config file looks like this:

PORT              11668
LOG               1
ACC               0
IDLE              0
 
GROUP   lan       192.168.0.*
GROUP   Manager   root@lan
 
PRODUCT cyslicev3 lan

PORT 

The server will listen at this port for license requests. There is no restriction on what this number is apart from the obvious one, that it doesn't conflict with ports used by other installed software.

LOG 

Set the level of verbosity of the log files.

ACC 

Set the level of access to hlmanager for normal users. See The Manager: User Mode for details.

IDLE 

Number of hours to wait before killing idle TCP/IP connections. Idle connections will occur if a user hibernates or suspends their PC when a license is checked out, or the workstation or network has died, and can result in "zombie" licenses being checked out but not actually used by anyone. 20 hours is probably a safe value, allowing people to legitimately suspend their PCs over night, while also cleaning out zombie licenses at least once a day. Setting this value to "0" turns off the idle connection kill.

GROUP 

Each line of this section associates a single name with a list of hosts, prefixed with optional user names. In the above simplest case, lan is associated with the IP range for a local area network. The name lan can then be used to refer to all hosts in the LAN.

 

The * character is a shorthand way of saying 1-255; they both mean the same thing. The * character can also be used to extend to the beginning or end, as in 45-* (equivalent to 45-255) or *-66 (equivalent to 1-66).

 

The brace characters can be used to surround a list of alternatives, as in {*-45,47,49-*} (everything except 46 and 48).

 

Hostnames can be used in place of IP ranges, though the list could become quite long if you are serving a large number of hosts. IP ranges are more concise, and will avoid any possible domain name resolution problems.

 

The special group Manager defines the list of users that can be trusted to run the hlmanager application (see "The Manager" chapter for more details).

 

Usernames are case-sensitive, so the default Windows hlserver.conf, with "GROUP Manager Administrator@lan", wont give access to a user with an "administrator" login.




 

By the way, there's nothing stopping you from defining *.*.*.* as an IP range. The advantage of this is you don't have to think, but the disadvantage is that anyone who has access to your license server can grab one of your floating licenses. This includes anyone, anywhere in the world, if the server is connected to the internet.

PRODUCT 

In this section you should have a single line for each product that you have floating keys for. Follow the license name with a list of hostnames or group names that have access to that product. You can optionally prepend a username, in the form username@host/groupname to further restrict access. If a Windows username has spaces in it, replace those with underscore in the config file (e.g. login "Jill Smith" would need to be written as "Jill_Smith" in the config file).

The following shows a more complex example of a config file.

LOG               1
ACC               1
IDLE              6
PORT              11668
 
GROUP   cg-lab    192.168.0.1-23
GROUP   office    fred,barney
GROUP   offsite   112.56.22.{12-15,21}
GROUP   Manager   julie@office,jimbo@cg-lab,root@hlserver
 
PRODUCT cyslicev3 cg-lab,{phil,jill}@offsite
PRODUCT plyedit   jimbo@cg-lab

Anyone currently logged into a cg-lab machine can request a cyslicev3 license, but only phil or jill can from the handful of offsite machines. Whenever jimbo is logged into a cg-lab machine, he can request a cyslicev3 or plyedit license as well as run the license manager.

Keys

Floating licenses, stored in the .keys or keys.txt file, look something like this:

      <- 21 hex numbers ->   Product   System   Expire Ref#   Num
 #v2# 3a d6 ........ a9 42 # cysurf    690ca1ab never  0920 [001 3]
 #v2# 5d da ........ 32 6a # cyslicev3 690ca1ab never  0921 [001 1]
 #v2# 37 db ........ 71 5b # cyslicev3 690ca1ab 040216 0922 [002 1]

You might also receive license keys that look like this:

   Products            System         Expire        Num
 # hlserver,uvlayoutv1 sysid=690ca1ab expire=071226 [000 4]
 8MFP LCDY A0GZ 553N QQ6Z BLMB A1A6 GF1G # 6200
 74QX SEPD GEC4 AK1W QJK8 3E5N 2LLF 345C JQX5 24SA # 6201

These are shorter format email friendly keys that we are gradually phasing in, understood by hlserver v1.5+.

The Product names go into the config products section, System is the sysid of the license server, Expire is when each floating license runs out, Ref# is a database reference number used by the issuer, and Num is the sequence id and number of floating licenses in that key.

In the first example above, there is 1 cyslicev3 and 3 cysurf floating licenses that will never expire, and 1 additional cyslicev3 license that runs out on the 16th of Feb, 2004. Even though there are multiple cyslicev3 keys, you should have only one cyslicev3 access list in the config products section.

In the second example there are 4 uvlayoutv1 floating licenses.