Licensing


Installation	Appendix

Introduction

ATK uses the LM-X License Manager from X-Formation to ensure that the usage of the program complies with the terms in the license agreement. In this chapter, you can find basic information about LM-X regarding the points which are most relevant for the operation of ATK. For more detailed information, please refer to the LM-X End Users Guide.

	Note
	You can try ATK for a time-limited demo period without any license file. The information in this chapter primarily applies to the case where you have an actual license file (a purchased license, a prolonged trial license, etc).

To run ATK beyond the demo period, you must have a license file, and each computer that runs ATK (a "client") needs to be configured properly.

If you:

Need a trial license file: Please contact QuantumWise via the form available from QuantumWise web site ("Trial license" option).
Have a trial license file (or another standalone license file): See the instructions for configuring the client to allow ATK to locate the license file.
Have a floating license file (typically the case for a purchased license): See the instructions for configuring the license server.

	Tip
	If you are not sure whether your license file is floating or standalone, ask your QuantumWise contact person, or have a look inside the file itself (it's just a text file). If it contains lines with the keyword "COUNT", it is most likely a floating license.

Configuring a license server

Running ATK via a license server by using a floating license is very convenient, as it makes it possible to run the software on any machine on the network with minimal configuration of the clients.

Preparations

Before you can set up the license server, there are two steps of preparation:

Download the license server package for the relevant platform, and install it on the license server.
Determine the host ID of the license server and provide this information to QuantumWise in order to obtain a floating license file.

The following sections describe how to set up the license server on Windows and Linux.

Windows

Follow these steps to install the LM-X license server as a service on Windows.

Start the License Server Tool via the shortcut in the Start Menu under QuantumWise > ATK License Server. You can also run lmxconfigtool.exe from the command line.
When the tool starts up, open the tab "License Server Configuration" and click "New Server". In the dialog box that appears, give the service a suitable name (the default works fine). Then, for each of the four fields, click the "..." buttons to specify the location of the four different files:
- The license server binary (lmx-serv-quantum.exe)
- The configuration file (lmx-serv.cfg)
- The license file (which you should have received from QuantumWise)
- The log file (choose a suitable name for the file, like license_server.log).
The first two files can be found in the same directory as the license server tool itself (i.e. in the license subdirectory of the installation directory for the license tool package). It is also recommended to place the log file here.
Click "OK" to save the server configuration.
Start the license server by clicking "Start server". If successful, you should see the message "Service is running" under "Service status".

	Important
	If you are asked if the license server should be allowed to access the network, you must agree.

	Note
	The configuration file can be edited to define the port used for license communications and other options, as discussed in an Appendix. If you need to update the license file, first stop the server, then replace the license file, and then start the server again. To remove the license server, first stop it, then click "Remove Server".

Linux

Testing the license server setup

To test that things work properly, first start the license server in the foreground, from the command line.

Run, in a terminal window,

lmx-serv-quantum -l licensefile.lic

The license file can be located anywhere, as long as you specify it with full path.

The license server should start up with a message similar to the one below.

LM-X License Server v3.6 (Linux_x86)
Copyright (C) 2002-2011 X-Formation. All rights reserved.

[2010-05-28 09:53:43] LM-X License Server v3.6.3 build 1234 on localhost (Linux_x86)

[2010-05-28 09:53:43] Copyright (C) 2002-2011 X-Formation. All rights reserved.
[2010-05-28 09:53:43] Website: http://www.lm-x.com http://www.x-formation.com
[2010-05-28 09:53:43] License server has pid 6484.
[2010-05-28 09:53:43] Serving licenses for QUANTUM.
[2010-05-28 09:53:43]
[2010-05-28 09:53:43] License server using TCP IPv4 port 6200.
[2010-05-28 09:53:43] License server using TCP IPv6 port 6200.
[2010-05-28 09:53:43] License server using UDP IPv4 port 6200.
[2010-05-28 09:53:43] Reading licenses...
[2010-05-28 09:53:43] License file(s):
[2010-05-28 09:53:43] /home/user/license.lic
[2010-05-28 09:53:45] Serving following features:
[2010-05-28 09:53:45] atkpython (v12.2) (10 license(s)) license type: exclusive
[2010-05-28 09:53:45]
[2010-05-28 09:53:45] Log file path: Not set
[2010-05-28 09:53:45] Configuration file path: Not set
[2010-05-28 09:53:45] Minimum user remove time set to 120 seconds.
[2010-05-28 09:53:45] Ready to serve...

If all looks fine (i.e. there are no error messages and you see the daemon "serving" the relevant features), you should check that the license server can be reached from the client computers. A convenient way to do this is to run
```
lmxendutil -licstat
```
on the clients. If the client can reach the license server, it will print information about the server and the license usage:
```
++++++++++++++++++++++++++++++++++++++++
LM-X License Server on 6200@192.168.0.17:

Server version: v3.6.3 Uptime: 0 hour(s) 5 min(s) 18 sec(s)
----------------------------------------
Feature: atkpython Version: 12.2 Vendor: QUANTUM
Start date: NONE Expire date: 2012-12-31
Key type: EXCLUSIVE

0 of 1 license(s) used
```
You should also see a few messages on the license server about the client request.

	Important
	If the client is unable to automatically connect to the license server, the most likely reason is that the communication is blocked by firewall rules. To resolve this, open port number 6200 (TCP and UDP) in the firewall, both on the server and the clients, and possibly (but less likely) on any router or hardware firewall in between them.

Installing the license server permanently

It is convenient to have the license server start up automatically each time the server is rebooted, running as a background process or service.

Before proceeding, close down the license server by pressing Ctrl-C in the terminal window where it is running.

To run the license server in the background (for the current session only), you can use the command

lmx-serv-quantum -b -l /path/to/licensefile.lic -lf /opt/logs/lmxserver.log

	Note
	Use a log file (option `-lf`) to record any error messages from the server. All file names (like license file and log file) must be specified with absolute path.

To configure the server to start up automatically on reboot, you can use the startup script lmx-serv-run.sh enclosed in the license directory. Edit it to reflect your local conditions (like the path to the files, the user account that will run the server, etc), and install it in /etc/init.d (or the similar location relevant for your Linux distribution).

Important

The exact details of start-up scripts, and where to install them, can differ between different Linux distributions. If the provided script doesn't work on your system, please consult your system administration guide.
The startup script refers to a configuration file; make sure that this file exists in the specified location, and that you have configured it properly.
If you change the password to the server in the startup script (which is a good idea!), remember to change it also in the configuration file.
Do not run the license server as root! Also note that the user account that runs the service must have a writable home directory (shell access is however not required).

Host ID

Except for trial licenses, all ATK licenses are locked to a particular machine. There are two basic types of licenses:

Node-locked license: The license is tied to a particular machine. ATK can then only run on this computer.
Floating license: The license is tied to the machine hosting the license server. The software can run on any computer that can check out a license from the license server.

The host ID is really just the MAC address of the primary network interface of the machine. A few convenient utilities for extracting the host ID are installed with ATK, and also with the separate license server package. You could however just use the operating system functionality to extract the MAC address.

Command-line approach:

Run lmxendutil in a terminal window. To save the output, you can pipe it to a file:
```
lmxendutil -hostid > hostids.txt
```
GUI tool:

Start the ATK License Configuration Tool via the Start Menu under QuantumWise > Atomistix ToolKit 12.2.0 > Utilities or (on Linux, but also on Windows) from the command line as atk_license_config.

On the first screen which appears you will see all the host IDs of the system.

The host IDs thus obtained should be provided to QuantumWise, so that a license can be issued. You may remove any information you prefer not to share, but you must at least leave the ETHERNET specification of the LAN card (binding to a wireless network interface is discouraged, since it means ATK may not run if the wireless adapter is disabled).

Client side license management

Each client that will run ATK needs to be configured for licensing, whether using a license server or a standalone/node-locked license.

The license configuration can be managed in two ways:

Via the interactive license configuration tool provided with ATK. This is the recommended approach for most users.
By manually editing the environment variables which control the license configuration. This requires that you are familiar with editing environment variables.

Configuring the license interactively

To start the interactive license configuration tool, on a machine where ATK has been installed, you may type

atk_license_config

on the command line, or (on Windows) use the shortcut ATK License Configuration Tool in Start Menu under QuantumWise > Atomistix ToolKit 12.2.0 > Utilities.

The tool provides easy to follow step-by-step instructions for configuring the license environment. On the first page (after the startup screen), the tool will display the current license configuration, along with the host IDs of the machine. This can be helpful when troubleshooting license problems.

On the second page, you will be asked which type of license you have, standalone or floating. The tool can also be used to remove all license environment variables.

If you choose standalone, you will be asked for the location of the license file on the next page.
If you choose floating, you can on the next page optionally specify the location of the license server. Leave this field empty, unless you have already verified that the license server cannot be discovered automatically.

If for some reason the automatic discovery does not work, enter the hostname (or IP address) of the license server, for example licserv.mydomain.edu. Do not include the port number; if you also have changed the port, you will need to edit the environment variable manually.

	Note
	The license configuration is in reality controlled by environment variables, as described in the following section. The interactive tool is just a convenient way to edit these variables.

License configuration via environment variables

This section documents how the ATK license configuration is controlled by environment variables. If you are familiar with editing system and user environment variables, you can directly modify the license configuration by setting the variables to their desired values. In many cases, it is however easier and safer to use the interactive license configuration tool described in the previous section.

The license configuration is controlled by two environment variables:

QUANTUM_AUTOMATIC_SERVER_DISCOVERY

By setting this variable to 1, ATK will be able to automatically detect a license server over the network. In this case there is no need to set QUANTUM_LICENSE_PATH, and no additional configuration is typically needed on the client, except you may need to open the relevant ports, if software or hardware firewall rules prevent the automatic server detection.

The ATK installer will always set this variable to 1; thus, no additional client configuration is actually needed to use a floating license server.

QUANTUM_LICENSE_PATH

For standalone licenses (node-locked or demo/trial licenses), this variable should point to the complete, absolute name of the license file, or a directory in which to look for license files (files with extension .lic).

In the unusual case that automatic server discovery does not work, this variable can alternatively be used to defined the license server manually. In this case, set the variable to the hostname/IP address of the license server, using the following format:

[port]@hostname

where the port specification is optional and only needed if your server uses a different port than 6200.

	Important
	The "@" sign is required, even when using the default port!

Notes

For definiteness it is assumed below that your Linux shell is bash. The corresponding changes for tcsh and other less common shells should be obvious to experienced Linux users.

Network license servers have priority over local license files. Therefore, to switch from using a floating license server to a node-locked license file (e.g. if you receive a temporary, node-locked or demo license) you must unset the environment variable QUANTUM_AUTOMATIC_SERVER_DISCOVERY. Note that this variable is automatically set to 1 by the installer.
You can specify multiple servers and/or files/directories by separating them with a semicolon ";" (on Windows) or colon ":" (on Linux).

Example (Linux):
```
export QUANTUM_LICENSE_PATH=@server.abc.com:/home/user/licenses:@backupserver.abc.com
```

On Linux, the installer defines the license environment variables to two separate files in your home directory:

.profile (or possibly .bash_profile). This file defines the environment for the Desktop, but is not read if you connect via ssh for instance.
.bashrc. This file defines the environment for all terminal windows, and is read also on ssh login.

If you modify the license setup manually, it is recommended to remove the ATK environment variables from .profile and only define them in .bashrc, to avoid confusion. .profile normally anyway sources .bashrc, thus the changes will also apply to the Desktop environment.

	Important
	To activate changes in `.profile` (including those sourced from `.bashrc`) you must log out and log back in again. This really only affects the VNL desktop icon; changes in `.bashrc` take effect as soon as you open a new terminal window.