2.8. xGT License Management System

2.8.1. xGT Licensing

xGT licensed products use a licensing scheme based on core counts. Each running xGT server will check out a certain number of licensed 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.

2.8.1.1. Core Based Licensing

Compute cores are the unit of the xGT licensing system. Each license will contain a number of licensed cores that can be shared among xGT products. This can be thought of as a pool from which applications can draw. Core based licensing is a three step process that occurs during a license checkout:

  1. Ask for a number of cores

  2. Verification

  3. Receive a number cores

When the xGT server begins running it will check out a license. During checkout the xGT server will ask for a number of cores from the license manager. Then, the license manager will verify the availability of cores in the license pool. If there are sufficient 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 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 cores back to the license pool for other programs to use.

2.8.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.

2.8.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.

2.8.2.2. 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.

2.8.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 and expiration date, but may contain other information. The pool size can be identified by the keyword COUNT=value. 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.

2.8.2.4. Using the LM-X License Manager

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

The configuration value license.server 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 (:).

A few examples of license paths:

2.8.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 web site

  • LM-X RPM provided by Trovares

  • A valid HostID of the server machine

  • License file (generally received via email)

  • Supported platform

2.8.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 Centos 6 with gcc for x64. It targets RHEL 7, 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.

2.8.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.

2.8.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.

2.8.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.

2.8.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.

2.8.3.2.4. Memory

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

2.8.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.

2.8.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.

2.8.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.

2.8.4.1. Install Software

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

  1. Download the package

  2. Install the package

These can be summarized as:

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

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/license/xgtd.lic.

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

2.8.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/license/. 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.

2.8.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 Software to the desired user.

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

2.8.5. Operations and Maintenance

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

2.8.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.

2.8.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.

2.8.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.

2.8.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
  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.

2.8.8. LM-X Error Messages

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

For an exhausitive 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.