The FLEXlm license system

Table of Contents

Introduction

In order to run QuantumWise programs Virtual NanoLab (VNL) and Atomistix ToolKit (ATK), you must have a valid license. QuantumWise uses the well-known FLEXlm license system from Macrovision, which supports many different solutions for managing licenses.

Installing licenses is a straightforward process, and will be covered below in step-by-step instructions. Links to further information about FLEXlm licenses and support can be found at the end of this page.

Obtaining the license file

These instructions will assume that you already have obtained a valid license file from QuantumWise. If you have not, please visit the QuantumWise web site for more details on how to apply for and obtain a license.

The license file may be of either of two types:

  • Node-locked licenses are uncounted, i.e. they support an unlimited number of simultaneous processes, but these processes are limited to run on a particular computer with a single CPU. QuantumWise only issues node-locked license files for trial licenses.

  • Floating licenses are counted, i.e. there is a limitation to the number of simultaneous processes. On the other hand, these processes can be launched on any computer in your network that has access to the license server managing the floating license, or on a multi-CPU/core machine. All purchased licenses from QuantumWise are floating licenses, but also trial licenses can be obtained as floating, if so desired. If you want to run parallel calculations with ATK, it is necessary to use a floating license (of the type ATKslave).

Installing the license file

The detailed steps for installing the license file are somewhat different for Linux and Windows, and also different depending on if the license file is floating or node-locked.

Uncounted node-locked license

An uncounted node-locked license can only be used on the host specified in the license file. It can not be used for parallel computations, and does not require the installation of a license server.

Linux

FLEXlm stores the information about licenses in a text file called .flexlmrc in the user's home directory (note the initial dot in the file name; use the command ls -a to display it in a directory listing). This file contains a line of the form

VENDOR_LICENSE_FILE=/path/to/license.lic

for each installed license. It is possible to have several licenses defined in the .flexlmrc file simultaneously (also from the same vendor), and if you are running other applications such as Matlab or Maple, you may already have this file in your home directory. Licenses from QuantumWise are identified by our vendor id ATOMIST.

First of all, it is recommended to uninstall all older QuantumWise FLEXlm licenses first. The latest license file received from QuantumWise will always contain all licenses that you have purchased and which are still valid, so there is no need to retain older license files.

To uninstall all QuantumWise FLEXlm licenses, edit the .flexlmrc file and remove lines starting with ATOMIST. If you have no other applications on your system that use FLEXlm, you could of course just delete the whole file.

A safe way to remove all references to QuantumWise licenses in the .flexlmrc file is to run the script flexlm_cleanup.sh provided in the same directory as the program binary itself.

Place your license file in a suitable location. This could be anywhere on your system, as long as you remember the actual location.

It is possible to install, remove or deactivate licenses by editing the .flexlmrc file directly. To install a new node-locked license, simply add the line (or edit it, if it already exists)

ATOMIST_LICENSE_FILE=/path/to/license.lic

to the file, where /path/to/ symbolizes the name of the directory where the license file (here assumed to be called license.lic) is located.

Alternatively, one can type the following in a terminal window

export ATOMIST_LICENSE_FILE=/path/to/license.lic

where /path/to/license.lic again symbolizes the full path of the license file license.lic.

Now, try to run the program

atk --version

which, if your license file has been correctly specified, will display the version number of the program.

The information about the license file should now automatically have been entered in the FLEXlm resource file, and the installation of the license file is completed!

Windows

The instructions that follow assume that your have administrator privileges on your computer. If you do not, it is still possible to install the license file, but you should then skip this section and move on to the section Windows - Installing without administrator rights.

The easiest way to proceed is to make sure that you start with a clean license environment. This is achieved by running the small registry script provided in the program distribution. It can be found in the same directory as the program binary, i.e. in the bin directory in the installation directory, and is called flexlm_cleanup.reg. Double-click this file, then click Yes in the dialog window that pops up, and finally click OK.

Place the obtained license file in a suitable location. This could be anywhere on your system, but make sure you place it in a location where you can easily find it again.

The simplest way to install the license file is to just launch ATK.

FLEXlm could not find a license and asks for the location

The program will now ask for the location of the license file (see figure). Select Specify the License File and click Next. On the next screen, type in the full name (including path) of the license file, or click Browse to locate it. Once the license file has been specified, click Next; if the license file was accepted, a message appears stating that The FLEXnet license finder has completed. Click the Finish button.

FLEXlm license procedure has completed.

After completing these steps, the location of the license file is stored in the Windows registry key ATOMIST_LICENSE_FILE filed under

My Computer\HKEY_LOCAL_MACHINE\SOFTWARE\FLEXlm License Manager

in the Windows registry.

Windows - Installing without administrator rights

When installing without Administrator rights, the license file cannot be set up automatically or using the FLEXlm utilities. Instead, it is necessary to install the license file manually through an environment variable. The following steps describe how to do this on a Windows 2000/XP system (English version):

  1. Open the Control Panel from the Start menu, and open the System tool. Note, the System tool might be located under Maintenance and Performance if your system uses the category view of tools.

  2. In the System window, choose the Advanced tab, and click the Environment variables button.

  3. Click New... in the upper panel (under user variables), and in the dialog that appears, enter ATOMIST_LICENSE_FILE as “Variable name”, and the complete file name (including path) of the license file as the value of the “Variable value”.

  4. Click OK and close all open windows.

This procedure can also be used if you have administrator rights should you prefer to store the license information in an environment variable rather than in the Windows registry.

Floating license

When using a floating license, the license file specifies the number of processes that can run simultaneously, and also how many nodes that can be used for a parallel calculation. The license is not tied to any specific node, but a specific machine in the network is chosen to be the license server, and run the FLEXlm license manager software lmgrd which handles license management. In a floating license environment, the license control is centralized to this license server, hence, all machines where the program (ATK or VNL) is installed must be connected to this machine through a network connection (TCP/IP) in order to run.

There are two separate tasks involved in setting up floating licenses:

  • setting up the license server

  • configuring the clients

First, make sure that, in addition to the license file, you have

  • The vendor daemon (atomist)

  • The license manager (lmgrd)

  • The FLEXlm utility (lmutil)

  • For Windows users: the end-user utility LMTOOLS (a graphical user interface program) (lmtools)

All these files are platform-dependent binaries, that must be downloaded using the links provided above. The compressed files for Linux/UNIX platforms have the extension .Z compressed, which can be extracted using the uncompress or gunzip commands.

Make sure you download the vendor daemon binary relevant to the machine architecture of your license server (it is not necessary to download or install any of these files on the clients that will run ATK).

It is recommended to place all relevant files, including the license file, in the same directory, on the license server.

Hostname

Before proceeding, take a moment to verify that the license server hostname given in the license file is correct. The hostname is specified on the SERVER line, which generally looks like

SERVER myhost 100FC280C5B3 27002

where myhost is the hostname of the computer. Alternatively, one could specify the IP number of the license server here, if it is fixed. If a DHCP server is used to assign the IP address, one must however use the hostname (with or without domain). Finding the hostname of your computer is simple:

On Linux, give the command

echo $HOSTNAME

in a terminal window.

On Windows, open a command terminal (e.g. the one installed with ATK, Start Menu Programs QuantumWise ATK 2008.10) and type

ipconfig /all

The first line of the output provides the value of the hostname variable.

The hostname, and the port (which is 27002 in the example above), are the only parameters of the license file that the user may modify freely; more information regarding the format of the license files is provided here.

Linux

We will first describe how to start the license server manager manually. Then, we will give an example of how it can be set up to start automatically at system start-up.

For security reasons, the user under which lmgrd is launched should not be the root user, but instead a less privileged user should be used.

Ensure that the programs lmgrd and atomist have been assigned the relevant permissions for the user that will launch lmgrd and that both files are executable. This is achieved by executing the commands

chown user_name atomist lmgrd
chmod +x atomist lmgrd

Of course, these commands must be given in the directory where the files are located. The first command should be given by the user that currently owns the files (or by root) and user_name should be replaced by the relevant user name.

To start the license server manually, use the following command:

./lmgrd -c license.lic -l log &

where the second (optional) option specifies where to store log messages. In this case, it will be located in the same directory as the lmgrd file and have the name log.

While testing, it can be useful to also specify the flag -z to prevent FLEXlm from demonizing.

In fact, it would be possible to give the full path of the license file, should it not be located in the same directory as lmgrd. The vendor daemon atomist must, however, still be located in the same directory as lmgrd, unless you modify your license file (see the section The format of the license files).

If the installation was successful, the log file could look like this

12:11:37 (lmgrd) License file(s): license.lic
12:11:37 (lmgrd) lmgrd tcp-port 27001
12:11:37 (lmgrd) Starting vendor daemons ...
12:11:37 (lmgrd) Started atomist (internet tcp_port 40372 pid 4752)
12:11:37 (atomist) FLEXnet Licensing version 10.1.3
12:11:37 (atomist) lmgrd version 10.8, atomist version 10.1
12:11:37 (atomist) Server started on localdomain for: f1

Linux: Starting lmgrd automatic

If you want lmgrd to start automatically at boot up (which is strongly recommended), you may write a startup script and put it in the /etc/init.d directory (or the equivalent location for your Linux distribution). Please consult your system administrator on how to write one, or use the sample script called flexlm_atomistix.rc (provided in the same directory as the program binary) as a template, and install it as a system service by issuing (as root)

chkconfig --add flexlm_atomistix.rc

Before attempting to install this script, it is crucial to check and modify e.g. the path to the license file to reflect your local conditions.

The above command is specific for Red Hat, and is just provided as an example. If you want to install the script using a different Linux distribution, you should adapt the script and use the appropriate command for your distribution.

Windows

Floating license servers on Windows should be set up using the FLEXlm utility LMTOOLS. This procedure must be performed by an Administrator.

Select Configuration using Services in the Service/Licence file tab of LMTOOLS

When LMTOOLS is launched, make sure to select Configuration using Services on the first tab; it is also recommended to tick the box to ignore license path environment variables.

Enter “Service Name” in the Config Services tab.
  1. Then select the tab Config Services, and enter a new Service Name (e.g. QuantumWise). Specify the path to the license file, to lmgrd, and a log file.

  2. The log file is optional but definitely recommended, especially when you set up the license server for the first time.

  3. Tick the boxes Use Services and Start Server at Power Up, if you want the license server to start each time you start Windows.

  4. Click Save Service, and click Yes to saving the service.

Start server in the Start/Stop/Reread tab.

Now go to the tab Start/Stop/Reread. Make sure the QuantumWise service is selected, and click Start Server.

Verify that server started.

Verify that the server started successfully by going to the tab Server Status and click the button Perform Status Inquiry. If all went fine, this should produce something like

Status
--------
Flexible License Manager status on Tue 11/7/2006 00:21
[Detecting lmgrd processes...]
License server status: 27002@192.168.1.101
    License file(s) on 192.168.1.101: license.lic:
192.168.1.101: license server UP (MASTER) v10.8
Vendor daemon status (on 192.168.1.101):
   atomist: UP v10.1
Feature usage info:
Users of ATKmaster:  (Total of 1 license issued;  Total of 0 licenses in use)
Users of ATKslave:  (Total of 10 licenses issued;  Total of 0 licenses in use)
Users of VNL:  (Total of 1 license issued;  Total of 0 licenses in use)

If instead there are error messages, please make sure that all the information in the license file is correct before attempting to restart the license server. In particular, make sure that the hostname or IP number is correct. There are typically more detailed error messages in the log file than in the status message; to view the log file, go to the Config Services tab and click the button View log.

If you are using a firewall, make sure it allows FLEXlm to communicate on the port specified in the license file.

Once the license server has been successfully started, the LMTOOLS program can be closed.

To close down a running license server, click the button Stop Server on the Start/Stop/Reread tab. To remove a license server, select the corresponding service on the Config Services tab and click Remove Service; you can also disable the server temporarily by just deselecting the two tick boxes at the bottom.

Configuring the clients

The final step is to configure the clients to use the floating license server. The procedure is basically identical to setting up a node-locked license, as described above, and the only difference is that instead of a license file, one should specify the port and hostname of the license server.

Linux

Follow the steps for a node-locked license above, but replace the export statement with the line

export ATOMIST_LICENSE_FILE=27000@licensehost

where licensehost is the hostname (or IP number) of the floating license server.

Alternatively, simply add this information (the same line, but without export) by hand to the .flexlmrc file in your home directory. If the license server is running on the local computer, one can use 27000@localhost. Make sure the port number (27000, in the example above) matches that specified in the floating license file.

Windows

On the clients, the only difference compared to the instructions for node-locked licenses is that instead of specifying a license file in the dialog box that appears when you attempt to start ATK or VNL, you should select Specify the License Server System, and then specify the port and the hostname of the license server.

Specify license server on the client machine.

For example, enter

27000@licensehost

where licensehost is the hostname (or IP number) of the floating license server.

If the license server is running on the local computer, one can use 27000@localhost. Make sure the port number (27000, in the example above) matches that specified in the floating license file.

Enter the right port number for the license server.

Testing the installation

To verify that the license is properly installed, make sure that the command

atk --version

runs without problems. For more information, we refer to the section Testing the installation in the installation guide.

The format of the license files

In this section we will present some technical details about the format of the license files. More details can be found in the FLEXlm End User Guide.

Node-locked license file

A generic node-locked license file from QuantumWise has the following general format:

FEATURE f1 atomist 1.1 permanent uncounted HOSTID=01030e10b1be \
    SIGN="1DFB 3E10 4DDE B571 46B0 5B09 EEC4 0CD6 3C20 6F69 \
    2C13 2C5E E6C6 38EE 1911 204D 983B 4D8D B5FF 5489 2D61 \
    19EE 2C13 1B91 13A8 4CE6 17C5 89C5 5D3E B6F1"
# Customer id: 000 # License id: 000

The order of some of the entries may be slightly different in your license file, and some additional entries may be present, including comments (which start with the # character).

Each line starting with the word FEATURE describes a particular license feature, which gives access to a certain functionality in the program. Note that the license file in this example only contains two lines, as a backslash (“\”) at the end of a line is a “continuation” character, meaning that the line continues on the next line. The line breaks are merely introduced to avoid very long lines in the file and to make it more readable.

The feature name appears as the second element on each feature line. In the example above, the feature is symbolically called f1; in a real QuantumWise license file, you can at present expect to find the following features:

  • ATKmaster - Master license for ATK.

  • ATKslave - Slave license for running ATK in parallel.

  • VNL - Virtual NanoLab license.

The third entry on each feature line is the the so-called vendor ID; it will always be ATOMIST for licenses from QuantumWise.

The fourth entry is the version number of the license feature. For instance, in order to run ATK 2008.10, it is necessary to have version 2008.10 of the ATKmaster feature (although in general the license version number actually has nothing to do with the version of the program that uses the license).

The fifth entry is the expiration date of the license, or the word permanent> if the license is perpetual (i.e. never expires).

The sixth entry is the number of licenses issued for this feature. For an uncounted node-locked license, this entry will be uncounted.

The final entry on each line is the host ID of the computer where this license is valid. As pointed out earlier, it is simply the network card address of that computer.

The final entry, SIGN, is the license key itself.

Note, a node-locked file may not be modified in any way, or it will cease to work. The only exception is that one may include comments (starting with #) and spaces and line breaks (remembering to include appropriate continuation characters) to improve the readability.

Floating license file

A typical floating license file from QuantumWise has the following general format:

SERVER license.server 1a3a3e4b89ed 27000
VENDOR atomist
FEATURE ATKmaster atomist 2.0 8-mar-2016 10 ISSUED=8-feb-2006 \
        SIGN="052A 68C5 C679 7E17 012E 9EA9 447C CCFB \
        4EEA 9A40 68DF 0707 BEEB E9AB B5DB 0B66 6E2E 2E12 2303 \
        D943 506B 05DA 21B1 FDE2 6D13 5EDF F55A 56B2 AFDE 69E8"
FEATURE ATKslave atomist 2.0 8-mar-2016 100 ISSUED=8-feb-2006 \
        SIGN="052A 68C5 C679 7E17 012E 9EA9 447C CCFB \
        4EEA 9A40 68DF 0707 BEEB E9AB B5DB 0B66 6E2E 2E12 2303 \
        D943 506B 05DA 21B1 FDE2 6D13 5EDF F55A 56B2 AFDE 69E8"
Customer id: 000 # License id: 000

The FEATURE blocks in the floating license files are identical to those that appear in the node-locked license files, except that they do not contain any reference to any host id; this is what makes the license floating. It is possible to mix floating and node-locked features in the same license file, if needed.

The first line contains information about the license server. The second entry on the first line is the hostname of the license server; this name can be freely changed, if needed. The third entry on the first line is the host ID of the license server, and the final entry is the port that will be used for the license daemon. The default value is 27000, but this may also be freely modified to suit local conditions. Remember to configure your clients to the new port value should if you change it.

The VENDOR line specifies the name of the vendor daemon, which is always ATOMIST for QuantumWise licenses.

If you need to place the vendor daemon in a different directory than where the lmgrd daemon is located, it is possible to modify this line by adding the full path (including the name of the vendor daemon) as a third argument. As an example, assuming that the daemon binary atomist is placed in /opt/quantumwise/license, the second line should be modified to read

VENDOR atomist /opt/quantumwise/license/atomist

Note, as with the node-locked license file, no other parts of the file should be modified, or the license file will cease to function.

Support

In order to find information, resources, and support specific for Macrovision's licensees, please refer to the Macrovision support.

Another good source of information is the FLEXlm End User Guide, which provides lots of details for configuring the FLEXlm license system.

You are of course always welcome to contact QuantumWise support via our Help Desk if you encounter or experience any problems when installing or running ATK.

In addition, you may also find some general advice about ATK on the QuantumWise web page.