7. License systems¶
To use AGX Dynamics, a valid license must be present.
The first license system (see old license system) used by AGX required manual handling of hardware identifiers for node locked licenses and had very limited options for users to manage their own licenses.
Therefore a new license system has been introduced which simplifies license activation as well as allows for users to manage their own licenses.
7.1. License system¶
The new license system used by AGX is based upon online activation instead of mailing hardware identifiers to Algoryx and then receiving license file(s) via e-mail.
A license is acquired via an activation process where a license id and activation password are used to perform an online activation that will result in a local license file.
The activation request will contain hashed hardware ids and the issued license file will contain the same hashed hardware ids. One part of the validation of the license file is to read hardware identifiers of the local machine, hash them and compare with the values in the license file. Hence a license is only valid on the machine where the activation was performed.
AGX will search for a local license file just like before and that file will be generated during the activation process.
To help with the activation, a License Manager utility using Python is included with AGX. If PySide and Qt are available locally, the utility provides a GUI. If not, the utility can still be used as a command-line-interface (CLI) tool.
The utility, LicenseManager.py is located in <agx-install-dir>/bin/${ARCH} where
ARCH is either x64, x86 or empty - depending on operating system. The utility can
also be launched via the start menu in Windows.
7.1.1. License file location¶
By default, AGX will look for a license file named agx.lfx. AGX will try to
locate the file automatically via the RESOURCE_PATH and those directories
are initialized from the environment variable AGX_FILE_PATH. This setup is done
via the provided setup_env scripts.
AGX could be installed where the current user does not have write permissions.
This could be under the c:\Program Files directory in Windows or under
/opt/Algoryx/ in Linux. Therefor AGX also searches in a per-user-directory
for license files.
In Windows this is the Algoryx\agx subdirectory to the current users
LocalAppData folder (%USERPROFILE%\AppData\Local). Full path example:
C:\Users\<MyUsername>\AppData\Local\Algoryx\agx\.
In Linux the XDG specification
is followed and the directory ${XDG_CONFIG_HOME}/agx/ is used as per-user directory.
If that environment variable is not defined, ~/.config/ is used
in its place resulting in e.g. /home/<MyUsername>/.config/agx/.
More details about locating files is available in Locating files with agxIO::Environment.
7.1.2. License Activation and Deactivation¶
Launch the LicenseManager utility. The output license file will default to agx.lfx placed in the per-user-directory.
Fill in the license id
Fill in the activation password
Change the output path if needed
Click activate to generate a license file that unlocks AGX Dynamics on the computer/hardware where the activation took place.
A license can be activated a limited number of times. The activation information should be handled with care.
Different license types have different policies. In general, runtime license can not be deactivated by the user. A runtime license does therefor normally not have to validate again online after the first activation.
A developer license can have a policy so that the user is allowed to deactivate the license on one machine and activate it instead on another machine. License types that can be deactivated normally have a policy indicating how often they require an online heartbeat.
After a successful license activation the License Manager will show information for the license including which modules that are enabled and how long the license is valid.
If the license has been updated, e.g. a subscription extended or new modules purchased, there is also an option to perform a “refresh” where updated license information is fetched online. This option is only needed when you know that the license is updated and the local information in the LicenseManager does not reflect this.
7.1.3. Runtime deployment¶
This section describes a workflow for providing an AGX License to an end user.
When deploying an application using AGX, activation must be performed on the end user machine. We do not recommend embedding of any plain text information in your application. We therefore provide a way to encrypt the runtime activation information.
Selecting File > Encrypt runtime… opens the following dialog:
The build directory is where your built application resides. The reference file should be a relative path to a static file that is part of your application. Using the button … to browse for directory and file will fill in a path relative the build directory.
The static file is used during the activation. If the static file is changed, the encrypted runtime has to be regenerated to be usable. When clicking generate, the file agx.rtlfx will be saved to the build directory.
Note
The runtime activation id and activation password are not tested online when generating the encrypted runtime information. Make sure to enter the information correctly.
This file can then be used with the
agx::Runtime::activateEncryptedRuntime( rtflx_path, output_license_path ) method.
Example code:
auto runtime = agx::Runtime::instance();
if ( runtime->isValid() ) {
// We have a valid license already.
return;
}
agx::String rtflxPath = .... ;
agx::String outputLicensePath = ... ;
bool status = runtime->activateEncryptedRuntime( rtflxPath, outputLicensePath );
if ( !status ) {
LOGGER_WARNING() << "Could not activate runtime: " << rt->getStatus() << LOGGER_ENDL();
}
else {
LOGGER_INFO() << "Runtime license: " << outputLicensePath << LOGGER_ENDL();
}
7.1.4. Offline Activation¶
Activating AGX and receiving a license is an online process. It is still possible to activate without internet.
Part one:
Start the license manager
Fill in license id
Fill in activation password
Select File > Offline activation > Generate activation request…
Fill in a filename for the activation request that will be stored to file.
Part two:
Take the generated request file on a USB stick to another computer that has internet access.
Upload the file or its contents to the manual request activation site.
Save the response to a new file on the USB stick.
Part three:
Fill in or change the Output file field in the License Manager
Select File > Offline activation > Process activation response…
Select the file with the activation response on the USB stick.
A license file should be created locally for futher use.
The license will be tied to the machine that created the offline activation request.
7.1.5. Using AGX in Docker containers¶
To use AGX, a license is required and this license is acquired via the activation process. As mentioned in an earlier section, the activation request will contain hashed hardware information and the issued license will contain the same identifiers.
If AGX is being activated from within a docker container, then container information will be part of the hashed hardware information. One can therefore not move license files between different docker containers since the hardware information will not match. It is also not possible to move a license while from the host machine into the container or vice versa.
7.2. Old License system¶
An application built with AGX requires a valid license to run. AGX can either be licensed with a runtime-license, or a developer license. A runtime-license usually does not have a time limit, but needs to be tied to a network adapter in your computer.
License information for a node-locked license is generated through a four step process:
Download the license executable available for all platforms here.
Next, execute the RuntimeKeyGenerator that correspond to your platform. This will generate a number of Hardware ID:s based on the available network adaptors (NIC).
Copy the list of the Hardware ID:s and send the following information to support@algoryx.se:
User/company name
Contact/email
HardwareID (select one whole line from the output of RuntimeKeyGenerator)
Url (Personal or your company’s)
You will receive a file in email which should be named agx.lic that you should place in the installation directory of AGX Dynamics, or one of the directories specified by the environment variable AGX_FILE_PATH, or with the AGX API call
agxIO::Environment::getFilePath(agx::Environment::RESOURCES)(see Section 31).
7.2.2. Sample Linux session¶
Output from a typical Linux session:
johnd@ubuntu:~$ ~/Downloads/RuntimeKeyGenerator-amd64-ubuntu-20.04
Available unique ids:
TYPE Hardware ID Comment
------------------------------------------------------------------------------
NIC 36A55A36955110F55967514527F8FFD3 wlo1
One of these Hardware Id value(s) should be used when acquiring
a license from Algoryx
johnd@ubuntu:~$
7.2.3. License deployment¶
This section describes the workflow for shipping the license with your end-user application.
When deploying an application based on AGX Dynamics, the application must be accompanied by a valid license issued from Algoryx. This license must be a commercial valid runtime license intended for the application as written in the AGX Dynamics license agreement. A Subscription or Developer license must NOT be used for deploying applications to third-party customers.
7.2.3.1. License file¶
To be able to run an application with AGX Dynamics a valid license is required. This license file is distributed as a text file agx.lic as part of the licensing procedure. During internal development, an OEM/Developer license can/should be used. Usually the license file (agx.lic) is placed into a directory where AGX can locate it (see Section 6.5). A license file contains a number of fields:
User: Name of the user/company/scope
Contact: email address to the licensee
EndDate: Last date when this license is valid
HwKey: List of hardware keys for which this license is valid
Modules: List of AGX modules
Version: For which version of AGX this license is valid
EndOfUpdate: Compared to the build date of AGX Dynamics and specifies the last date for which this license is valid.
7.2.3.2. Runtime license deployment¶
When an application is being deployed, we recommend that you do not ship the agx.lic on disk. The main reason for this is to avoid leaking the license file in clear text on the internet. A runtime license usually has the following properties:
EndDate: None - meaning it will be valid forever
EndOfUpdate - If set, it indicates that this is a runtime license with maintenance/update period.
A specified AGX version: indicates which version of AGX is being utilized in the application. For example: “2.25.0.3”
Note
To reduce the risk of having a license file distributed over the internet, we strongly recommends that an obfuscated license file is used.
7.2.3.3. Validate using obfuscated license file¶
The process of obfscating a license is where you take the original content of a license file and run it through a tool which generates a long string which represents the license information.
To convert a license file into an obfuscated license string you use the RuntimeKeyGenerator executable which is available for all platforms at the following link. For version 2.26.0.0 and later it is also available in your AGX installation. To obfuscate a license file you use the command:
> RuntimeKeyGenerator --obfuscate agx.lic obfuscated.txt
The content of obfuscated.txt can now be copy-pasted into your source code and used as an argument to the verifyAndUnlock method of the Runtime class:
const char* licenseStr = “rF3pUP9LX+m0lP6IFoYOMBaLIq8RvYmPFro0vjjdCjP6WK+rFoXVB6k0cMb0kw2iZa9NoA2irw7PgcwAN1YF46P/Wh3623cjEuXZ8/coslPalc5e/p+Z8G/DAPzI+IvwwxXBg4yzPTsE9CVKm9x5wYLoDQysHdALjiz4fdYsYhYGpOpFb3V2h0c4K/7V0PiLXzICK4jskYUGwP6tNfXzbl4L7aYW0PdiBzeo4JhOpTMuXLtI1Lagk+ZbZhmFbvY5ZejLqlQiohJf4zfl6cWAOgkMkKrnh2PZIMR7pnCPbWktGVTdhNPD1wmJEW/+kMs9999Z6EmaKAlHqvienW22um1LNCMZdgykbtZCWvsgH/qUrfUZrl/QXtbyY83xNrlFUj7zKZjTUbE1TxMdVwNBNxVapjJSxgBqbHakl229wvhi3ZPd3zph6DWNucKdM1a0gqHb4XsVxx6buBnJgm+3jV7AW2A59Go5BCdhLQLrmGjWGz7QrUmptMu//yQKsxsE0HT0ZABr/Hu7CCQIxnVE8mEsQ3ZtcwShrpa9mzq/trS5Zl/LYwIN5G1ayKxTy+UXzriMCC4NPRcpN6YuOzcicqf/Ont5ZCcDCGUcGef2HzBH8GDkHH3umUMeVSfpF8Tvk-/qmArdimyxPzy9SGsz2Zd/PZiu2KgMA5Nca38p0j8ulV4tASpXqCpKY8nWH5xCWe4kfO7pWZaJH+s0FghHx9H+fwc71kC2AAeyr8N+PPUnfnNprV3FIuaTdnaj1mCjVqXcVusWmYqF7JhcPffVPE9rkVdNO2qTNkpywwSGwfhyZmmJASByEqq4qp35AavGi3/twWTnWep1kt9ADcZlCG6fewsg5VrHBb7DDgNmcCWVLE1ew5D8bIpq1aukd8tl3hBqaDcgkdATEA369WJlg==”;
// Unlock AGX dynamics with the obfuscated license
bool isValid = agx::Runtime::instance()->verifyAndUnlock(licenseStr);
7.2.4. Validating using license in clear text¶
The second way of validating a license file is to use the text in the license file without obfuscating. However we do not recommend using this as the license text will be embedded in the binary as text strings.
// Read the content of the license file into a string variable
std::string licenseFileContent = read_license_file_content();
// Unlock using the text string containing the license file
bool valid = agx::Runtime::instance()->unlock( licenseFileContent.c_str() );
if (valid)
// We got a valid license file