10. Floating License Management System

10.1. xGT Licensing

xGT licensed products support both floating and node-locked licenses based on either socket or core counts. The following page describes in detail floating license management. For information about node-locked licenses see: License Management System.

If using a floating license, each running xGT server will check out a certain number of licensed sockets or cores from a central license manager in order to become licensed.

To run xGT, it is necessary to first set up and run a license manager. Once set up, each running instance of an xGT server at the licensed installation site will connect to the license manager to check out licensed cores. An xGT server instance can run on the same machine as the license manager or on a different machine. Unless otherwise specified, all instructions and file locations described on this page are on the machine that runs the license manager.

This section explains how the xGT Licensing Model works.

10.1.1. Socket and Core Based Licensing

Socket and cores are the unit of the xGT licensing system. Each license will contain a resource count that can be shared among xGT products. This resource count can represent either sockets or cores. This can be thought of as a pool from which applications can draw. Licensing is a three-step process that occurs during a license checkout:

  1. Ask for a number of resources that represent either sockets or cores

  2. Verification

  3. Receive that number of resources

When the xGT server begins running it will check out a license. During checkout the xGT server will ask for a number of sockets or cores from the license manager. Then, the license manager will verify the availability of sockets or cores in the license pool. If there are sufficient socket or cores, the license manager will allocate these to the program reducing the available count for other programs. By default a program will ask for the number of socket or cores that it detects that a system has, but it may be configured to a different value.

On a program exit, it will return the checked out resources back to the license pool for other programs to use.

When resources are checked out, the license system will calculate the number of threads available based on the socket or core count. For information about how the license system determines thread count see: Socket and Core Based Licensing.

10.2. License Management System Components

The license management system for xGT products is X-Formation’s LM-X license manager suite.

The main components of this system are:

  • License server (lmx-serv)

  • Configuration file (lmx-serv.cfg)

  • Service file (lmx.service)

  • License file (xgtd.lic)

  • Supplied utilities (lmxendutil)

When the phrase license manager is used in the documentation, it refers to the whole license management system: a running instance of lmx-serv supported by the other components.

This section discusses the license server, the configuration file, and the license file.

10.2.1. LM-X License Server

The LM-X license server (lmx-serv) is a program that serves network licenses. It will also be referred to as simply license server.

It runs on a server machine that can be reached by network clients. It is typically set up to start at machine boot time and to communicate via a specific TCP/IP port. The default port is 6200. The file lmx-serv.cfg contains data for configuring the license server.

Multiple LM-X license servers from different vendors may run on a single machine by specifying different ports. An LM-X based server may also be run side-by-side with the licensing systems of other vendors. However, you cannot run two versions of LM-X from the same vendor on the same machine.

10.2.2. License Server Configuration File

The configuration file contains information used to start the license server. During installation, the default configuration file lmx-serv.cfg is placed in /etc/xgtd/. The systemd script used to start the license server will look for the configuration file in this location.

This file contains information that designates the location of the license file, the location in which to place the log files and which TCP/IP port to listen on for client connections. It also provides other information used to configure the server. The file contains all the options available for the license server and may be customized.

10.2.3. License File

The license file contains license information. Each block of text in the file is known as a feature block. Each feature block has information about the license that is in plain text. This information is typically the pool size, expiration date, and license type (cores or sockets), but may contain other information. The pool size can be identified by the keyword COUNT=value. The license type can be identified by the keyword LicenseType=value where value will be either cores or sockets. This indicates if the pool count represents cores or sockets. The default name that xGT products use for this license file is xgtd.lic. Detailed information on the license file contents is provided in License File Format.

10.2.4. Using the LM-X License Manager

In order for a running instance of xGT to use the license manager, the xGT application configuration value license.location must be set to an appropriate location. This configuration is different from the license server configuration file. For more information on setting xGT configuration values, please see Configuring the Server.

The configuration value license.location should contain one or more network paths that will be used by the xGT server to find a valid license manager.

The proper format for a network path is port@hostname. The port used in the xGT server configuration should be the same port that the license manager is listening on. Multiple license paths are allowed and should be separated by a colon (:). If multiple paths are given, local licenses will be preferred over network licenses. Local license paths will contain the exact location of the license file, whereas network license paths will contain just the port and URL.

A few examples of network license paths:

A few examples of node-locked license paths:

  • /etc/xgtd/licenses/xgtd.lic

  • /etc/xgtd/licenses/xgtd.lic:/etc/xgtd/licenses/xgtd-alt.lic

In addition, the configuration values for license.core_count or license.socket_count can be used to check out a specific number of cores or sockets from the system depending on the license type. These variables can only be set for a specific license type. So if the license type is for cores, setting license.socket_count will result in an error. Moreover if the license type is for sockets, setting license.core_count will result in an error. If neither are set, it will use the default core count or socket count on system depending on the license type.

10.3. Preparing to Install

This section summarizes the procedures needed to install and successfully run the xGT license system.

The general procedures for installing and activating the license management system are:

  1. Determine the servers for the license manager

  2. Download the proper package

  3. Install the license system on the machines

  4. Obtain a valid license file for the machines

Requirements:

  • Access to xGT website

  • LM-X RPM provided by Trovares

  • A valid HostID of the server machine

  • License file (generally received via email)

  • Supported platform

10.3.1. Download and Platforms

A link to the xGT version of LM-X will be provided by Trovares.

The LM-X package is built on Rocky 8 with GCC for x64. It targets RHEL 8, but is generally compatible with other types of Linuxes.

You cannot run two instances of the xGT LM-X license manager on the same server.

10.3.2. Selecting a Server

When selecting a server, you need to consider disk space, socket usage, CPU usage, memory, and network bandwidth.

In general, the usage of these resources will be low. The most important thing to consider is disk space for log files, but we will go through each of the above.

10.3.2.1. Disk Usage

The installation size of the LM-X license manager is around 20MB. However, it will produce log files that will vary in size depending on activity. The file system should have sufficient space to store log files. Typically these logs will contain information about check-outs and check-ins, so their size will vary by the volume of these.

10.3.2.2. Sockets

Each application that connects to an LM-X license manager will use some sockets. The number of sockets in use per program is limited typically. If a large number of applications connect at the same time, then a large number of sockets will be used. The limit should be changed appropriately, or multiple licenses could be issued for different servers.

10.3.2.3. CPU

Typically, the CPU load should be minimal since the server just checks-out/checks-in licenses. However, if a high volume of these operations occur the CPU could see significant load. In such a case an appropriate CPU that can handle this should be considered.

10.3.2.4. Memory

The memory usage should be under 10MB but may be higher depending on the platform.

10.3.2.5. Network Bandwidth

The program uses a single port for communication with TCP/IP. The amount of data sent is small. It should run without issue on Ethernet.

10.3.3. HostID

Trovares provides the utility lmxendutil in the RPM to obtain a HostID from the license manager machine. Only ETHERNET values are valid for licensing.

10.4. Installing

In order to install you will need this RPM package provided by Trovares. In order to install as a daemon process, you will need appropriate privileges.

10.4.1. Install License Manager Software

Installing the package is fairly straight forward. On the server intended to be used for the license manager:

  1. Download the packages

  2. Install the packages

These can be summarized as:

Download the license manager package from the link provided by Trovares (typically provided by email). Then install it on the license server:

sudo yum install xgt-license-manager-X.Y.Z-1.x86_64.rpm

  • The package will install to /opt/xgtd/.

  • It will install systemd scripts to /etc/systemd/system/.

  • It will store configs in /etc/xgtd/.

  • It will store logs in /var/log/xgtd/.

  • It will by default look for a license at /etc/xgtd/licenses/xgtd.lic.

  • It will create a xgtd user on the system to run the application as a daemon.

Download the xGT server package provided as link by Trovares (typically provided by email). Then install it on the machines intended to connect to the license server:

sudo dnf install xgt-server-X.Y.Z-1.x86_64.rpm

Configure the servers to point to the license server. See Using the LM-X License Manager.

10.4.2. Install a License File

You will need a license supplied by Trovares, to complete the licensing process. If you do not have a license, contact gettingstarted@trovares.com with your request and provide a HostID value of the license manager machine.

On the license manager machine do the following steps:

  1. To obtain the HostID run /opt/xgtd/bin/lmxendutil -hostid. This will list all the hostids of the machine. You should choose one listed as Ethernet that is a permanent interface. Some interfaces will be for VPNs. Do not use VPNs.

    A sample output from such a run:

    /opt/xgtd/bin/lmxendutil -hostid
LM-X End-user Utility v5.0
Copyright (C) 2002-2021 X-Formation. All rights reserved.

ETHERNET: ens3
HostID: 000C2BC32G83

ETHERNET: ens4
HostID: 0A42F8D4C3F0

HOSTNAME: wyvern
HostID: wyvern

USERNAME: jacob
HostID: jacob

IPADDRESS: 192.128.121.148
HostID: 192.128.121.148

IPADDRESS: 192.138.111.*
HostID: 192.138.111.*

IPADDRESS: 192.118.*.*
HostID: 192.118.*.*

  2. When you receive your license file place it in /etc/xgtd/licenses/. By default, it should be named xgtd.lic.

  3. Change the setting in lmx-serv.cfg to point to your new license file, if necessary.

10.4.3. Interacting with the License Daemon

The installer will place a systemd script at /etc/systemd/system/lmx.service. It accepts typical systemd commands such as start, stop, restart, enable and status.

systemctl start lmx

To enable the license server to run on boot do:

systemctl enable lmx

By default, this script installs and runs as the xgtd user.

If you do not want this:

  1. Remove the user.

  2. chown the files/directories listed in Install License Manager Software to the desired user.

  3. Modify the lmx.service file to run as the desired user.

Once the license manager is installed, you should be able to run the xGT servers on their respective nodes:

$ systemctl start xgtd

More information about interaction with xGT server can be found in Licensing.

10.5. Operations and Maintenance

Trovares provides the following LM-X administration tools and programs. These include lmxendutil and the license server itself.

10.5.1. lmx-serv

This program is the actual license server. The server can run without any configuration or options. It will look in the current working directory for a license. Everything except the configuration file location may be set in lmx-serv.cfg.

The options are:

-b
-background        Run license server in background.

-c
-config            <configfile>
                   Specify which optional config file to use.

-l
-licpath           <license path>
                   Specify optional license file or a path to directory with license file(s).

-lf
-logfile           <logfile>
                   Specify optional logfile.

-port              <port number>
                   Specify optional port number.

-h                 Show this help.

10.5.2. lmxendutil

This program provides multiple functions for querying and managing the LM-X license server. Trovares does not support all the options. Trovares does not support -readusagedb or all of the choices output by –hostid. The only type of HostID supported is ETHERNET.

The options Trovares supports are:

-hostid         Display HostIDs for this system.

-licstat        [-vendor <vendor_name> (-host <host> -port <port> | -hal <servers>) -network -borrow -grace -trial -denials]
-licstatxml     [-vendor <vendor_name> (-host <host> -port <port> | -hal <servers>) -network -borrow -grace -trial -denials]
                Display statistics as text or xml for license server on
                current or foreign host and for borrow, grace and trial
                licenses.
                By default, all information is included, but can be limited
                by specifying, for example, -borrow to include only
                borrow information.

-restartserver  [-host <host> -port <port> -password <password>]
-shutdownserver [-host <host> -port <port> -password <password>]
                Restart or stop a license server on current or
                foreign host.

-removeuser     -clientusername <user> -clienthostname <host>
                [-feature <feature> [-version <version>]]
                [-host <host> -port <port> -password <password>]
                Remove a specific user at a specific host from a
                license server on current or foreign host.

-help           Print this message.

10.6. Logging

By default, the daemon will store logs in /var/log/xgtd/. The default log is named lmx.log

The log file will track check-outs and check-ins by users. It will display the user, host and quantity of cores checked out.

In lmx-serv.cfg the logging can be customized to set rotation and extend the logging to include more information. See https://docs.x-formation.com/display/LMX/License+server+configuration+file.

10.7. License File Format

This section describes the basic format of the license file. The license file will look similar to below:

FEATURE xgtd
{
  VENDOR=TROVARES COUNT=8 KEYTYPE=EXCLUSIVE VERSION=1.6 END=2010-02-28 OPTIONS="LicenseType=cores"
  COMMENT="HOSTID=000AB2FC62785"
  KEY=5UgwnMBQLeLPii1ZVIMKAnU4MA8iEa1F8n]x8yp8gI8vzepVmYAN0BzxL7WhpKTWYhM1X25SIwEqELECf8ScPwdVnhwm2]fxII2f \
  coR8febhKKAwLv5R3r52cnMWYHJkad]bU1gIWzLv7uCHZDP78mBX6kLU4yIv]ShgQCa]wixHU61LBtLBBbr6EQKq90IK08A3mUM6 \
  sJPj5O]LGIJE5eaQpsotAPZE[1wddNqoYbOeQ0RKdDdMM]icS02SHZqUpJijyZquw1imAtfB1Dm4HA1w8d9DhWL8CEgT2XWCaKSS \
  e65xtGwybpq9c37BdeAIxMzTVk[HUQDjgy80wAJ86nAy4WxxpRuZmDqN[r[lUlw5dTPvja0Tb2[A88UOlWXhGoq9jcAJd]p1iSk8 \
  NpdnQGXJ3D7nBVsuAUERoQkzIJO3CEkTn]0KtOf3Wtxx610KjYeXzc7Guy6T0uy8Ri7CKMPR25E85FluI[7LrlgO42nMEnyxzUe[ \
  ABSwahyvfy7yalvFQrs8H6hH1NC1Z7jXYmR8Zd0icEM2obzGI6qNAUOk[VdEEVdxhQIXPblG
}

In this file count is the number of cores this license contains. Version is the version of xGT that this license is for. End is the expiration date of license. A comment may be preset to indicate other information such as MAC address.

10.8. LM-X Error Messages

The table below lists the most common error codes from the license server and their meanings.

For an exhaustive list see: Exhaustive List of LM-X Error Messages

Return Code #

Return Code

Description

0

LMX_SUCCESS

Operation successful.

3

LMX_NO_NETWORK

Unable to initialize network subsystem.

9

LMX_FEATURE_NOT_FOUND

Feature not found.

12

LMX_TOO_LATE_DATE

Software expired.

13

LMX_BAD_VERSION

Software version does not match license.

15

LMX_NO_NETWORK_HOST

Unable to connect to license server.

17

LMX_NOT_ENOUGH_LICENSES

Request for more licenses than available on license server.

20

LMX_VIRTUAL_DENY

Feature not allowed to run on a virtual machine.