Sentinel License Management

In addition to single-workstation license based on a hardware dongle, MICROEJ SDK supports floating licenses based on Thales Sentinel LDK solution.

This chapter contains instructions that will allow you to setup Sentinel environment and activate your license.

There are two installation flows:

If you are a System Administrator, setup the Sentinel Floating License Server on a host machine.
If you are a Developer, proceed with the setup of the Sentinel client for the SDK.

Note

Floating License requires Architecture 8.1.0 or higher (Production only).

Setup the Sentinel Floating License Server

This section contains instructions for the System Administrator to setup the Sentinel Floating License Server.

Choose a machine to host the Sentinel Floating License Server. The host machine must be chosen with care, as its fingerprint will be required to generate the license file. Especially, you have to choose a host machine that is accessible through the network to all your developer workstations.

Install the Sentinel LDK Run-time Environment (RTE) for License Server

Sentinel LDK Run-time Environment enables your protected software to run by communicating with Sentinel protection keys.

First, download Sentinel_RTE_Installation-1.1.0.zip file. It contains installer for Windows, macOS and Linux.

Get haspdinst_37102.exe file
Type haspdinst_37102.exe -i in the command line. The installation or upgrade process is performed automatically. A message is displayed informing you that the Sentinel LDK Run-time Environment was successfully installed

Note

To uninstall Sentinel RTE, type haspdinst_37102.exe -r in the command line. A message is displayed informing you that the Sentinel LDK Run-time Environment was successfully removed.

Note

All install/uninstall commands must be executed with root rights. On Ubuntu, prefix the commands with the sudo command. On other Linux distributions, use the su utility to become root in the terminal window.

Get aksusbd_37102-10.12.1.tar.gz file and extract it. The installation packages are in the directory pkg, as root enter the following command:

For RedHat, SUSE, or CentOS 64-bit Intel systems: rpm -i aksusbd-10.12.1.x86_64.rpm
For Ubuntu or Debian 64-bit Intel systems: dpkg -i aksusbd_10.12-1_amd64.deb
Copy aksusbd-10.12.1/haspvlib_37102.so and aksusbd-10.12.1/haspvlib_x86_64_37102.so to /var/hasplm directory

Configure the License Server

On the host machine, open a web browser.
Browse http://<server-ip-address>:1947 to open the Sentinel Admin Control Center.
Go to Sentinel Keys tab and click on Fingerprint button to download the *.c2v file.
The *.c2v file stands for Customer to Vendor. Send this file to your MicroEJ sales representative.
Wait until MicroEJ prepares your license key. Then you will receive a .v2c file. The *.v2c file stands for Vendor to Customer.
On the host machine, go back to the Sentinel Admin Control Center.
Click on Update/Attach tab.
Click on Select File… button and browse the .v2c file.
Click on Apply File button.

In Sentinel Keys tab, you should see the successfully installed license key:

../_images/sentinel_rte_server_installed_license.png

Go to Configuration > Access from Remote Clients and check All licenses are accessible without need of identity. Save your change with the Submit button.
Go to Configuration > Detachable Licenses > Automatic Detaching of Licenses, check Enabled and set Allowed Offline Duration to 4 hours.
Click on Submit button.

Configure the host machine to open the IP port 1947 for TCP, UDP, TCP6, UDP6.
Optionally, you can set a printable name for the Sentinel Floating License Server that will be displayed on the Developer workstation license list.
- Go to Configuration > Basic Settings tab.
- Update the Machine Name text field (e.g. central-sentinel-server).
- Click on Submit button.

Your Sentinel Floating License Server is successfully configured. All you have to do is to share the host machine IP address to your MicroEJ Developers.

Setup the Developer Workstation

This section contains instructions for the MicroEJ Developer to setup its workstation in order to connect a Sentinel Floating License Server.

First, download Sentinel_RTE_Installation-1.1.0.zip file. It contains installer for Windows, macOS and Linux. Sentinel LDK Run-time Environment enables your protected software to run by communicating with Sentinel protection keys.

Get haspdinst_37102.exe file
Type haspdinst_37102.exe -i in the command line. The installation or upgrade process is performed automatically. A message is displayed informing you that the Sentinel LDK Run-time Environment was successfully installed
Put MicroEJ_library\hasp_windows_x64_37102.dll file in the system folder (%SystemRoot%\system32) if you have administrator rights on your machine. Otherwise drop the hasp_windows_x64_37102.dll file beside java.exe executable of the Java Development Kit (JDK) used to run the SDK.

Note

To restart RTE, go to Services window and restart Sentinel LDK License Manager service. To uninstall Sentinel RTE, type haspdinst_37102.exe -r in the command line. A message is displayed informing you that the Sentinel LDK Run-time Environment was successfully removed.

Warning

All install/uninstall commands must be executed with root rights. On Ubuntu, prefix the commands with the sudo command. On other Linux distributions, use the su utility to become root in the terminal window.

Get aksusbd_37102-10.12.1.tar.gz file and extract it. The installation packages are in the directory pkg, as root enter the following command:

For RedHat, SUSE, or CentOS 64-bit Intel systems: rpm -i aksusbd-10.12.1.x86_64.rpm
For Ubuntu or Debian 64-bit Intel systems: dpkg -i aksusbd_10.12-1_amd64.deb
Copy aksusbd-10.12.1/haspvlib_37102.so and aksusbd-10.12.1/haspvlib_x86_64_37102.so to /var/hasplm directory
Get MicroEJ_library/libhasp_linux_x86_64_37102.so file and copy it in a directory of your choice
Set LD_LIBRARY_PATH variable with command export LD_LIBRARY_PATH=<directory_of_libhasp_file>:$LD_LIBRARY_PATH (just the directory, not with the file name). This modification has to be setup at session startup (e.g: using ~/.bashrc or ~/.profile files) to ensure that OS is properly configured before running the SDK.

Note

If you use the Sentinel RTE on WSL (Windows Subsystem for Linux):

You can set the service to start on boot by creating the file /etc/wsl.conf and add these lines to it:
[boot]
command="service aksusbd start"
You can check the service status with the command sudo service aksusbd status.

When executing a Gradle task from your favorite IDE, set the LD_LIBRARY_PATH environment variable in the launche. For example for IntelliJ IDEA:

Get Sentinel_Runtime_37102.tar file and extract it to a working directory
In SentinelRuntimeInstaller.framework/Versions/A/Resources/, double-click Sentinel_Runtime.pkg to launch the installer wizard
Follow the instructions of the installer wizard until the installation is complete
Get MicroEJ_library/hasp_darwin_37102.dylib file and copy it to a directory of your choice
Set LD_LIBRARY_PATH variable with command export LD_LIBRARY_PATH=<your_directory>:$LD_LIBRARY_PATH. This modification has to be set up at session startup (e.g. using .zshrc file) to ensure that the OS is properly configured before running the SDK.
macOS may quarantine the .dylib after download, which prevents it from loading. If you see a Gatekeeper warning or the library fails to load with no obvious cause, remove the quarantine attribute:
sudo xattr -rd com.apple.quarantine /path/to/hasp_darwin_37102.dylib

Warning

On macOS with System Integrity Protection (SIP) enabled, LD_LIBRARY_PATH may be stripped from child processes of system-protected binaries. If the SDK cannot locate the library despite the variable being set, launch the SDK from a shell where the variable is exported, or place the .dylib in a standard search path.

Note

To restart the daemons, on a terminal, go to /Library/LaunchDaemons/ and run:

sudo launchctl bootstrap system com.aladdin.aksusbd.plist
sudo launchctl bootstrap system com.aladdin.hasplmd.plist

Then you can continue with the Remote Floating License Server section.

Add Remote Floating License Server

From Sentinel Admin Control Center

On the developer workstation, open a web browser.
Browse http://localhost:1947 to open the Sentinel Admin Control Center (if you work with WSL read note below).
Go to Configuration > Access to Remote License Managers.
Check Allow Access to Remote Licenses.
Uncheck Broadcast Search for Remote Licenses.
In Remote License Search Parameters, add the Floating License Server IP address that should have been shared by your System Administrator.
Click on Submit button.
Your computer should now have access to the licenses configured on the Floating License Server. In Sentinel Keys tab, you should see the license key provided by your Floating License Server (e.g. central-sentinel-server).

Note

If you use WSL (Windows Subsystem for Linux) localhost refers to your Windows localhost and not to your WSL instance. First, on WSL, create /etc/hasplm/hasplm.ini file and add accremote = 1 line to it. Then on WSL terminal, launch hostname -I command, copy the first IP address and use it instead of localhost in your browser (e.g. http://172.30.106.171:1947/).

From Command Line

On Linux: update or create the file hasplm.ini in /etc/hasplm or hasp_37102.ini in ~/.hasplm (if you have not installed RTE as root).
On Windows: edit %CommonProgramFiles(x86)%\Aladdin Shared\HASP\hasplm.ini file.

Then add to the .ini file the following lines:

[REMOTE]
broadcastsearch = 0
serversearchinterval = 30
serveraddr = <license_server_IP>

Restart the service.

Running in a container

If you want to configure a CI (Continuous integration) runner you can follow one of these two solutions:

Either create a Docker image with the RTE installed inside, see Installation for Linux section.

Or install and configure the RTE on the host and run the Docker container with these options:

-v /var/hasplm:/var/hasplm:ro -v /home/<host_user>/.hasplm:/home/<container_user>/.hasplm:ro -e LD_LIBRARY_PATH=/var/hasplm

Runtime Installation Instructions and Troubleshooting

Check Activation with the Command Line Tool

To verify access to the Sentinel license on the workstation where the SDK executes, run the debug tool as following:

Open a terminal
Change directory to a Production VEE Port (e.g. in your project build/vee directory).
Execute the command:
java -Djava.library.path=resources/os/[OS_NAME] -jar licenseManager/licenseManagerProduct.jar
with OS_NAME set to Windows64 for Windows OS, Linux64 for Linux OS, Mac for macOS x86_64 (Intel chip) or MacA64 for macOS aarch64 (M1 chip).

Note

On Windows, use Command Prompt terminal to run the command, instead of PowerShell. Also, specify the absolute path to the required resources to avoid errors, for example:

java -Djava.library.path="C:\MY_PATH\my-app\build\vee\resources\os\Windows64" -jar "C:\MY_PATH\my-app\build\vee\licenseManager\licenseManagerKeyHardware.jar"

If your Sentinel license has been properly activated, you should get the following output:

[DEBUG] ===== MicroEJ Sentinel Debug Tool =====
[DEBUG] => Detected Sentinel License Key ID: XXXXXXXXXXXXXXXX.
[DEBUG] => Detected MicroEJ License valid until YYYY-MM-DD.
[DEBUG] ===== SUCCESS =====

Troubleshooting

Sentinel API dynamic library not found (code 400)

The following error occurred when the library hasp_[os]_37102.[ext] has not been found. Please refer to Setup the Developer Workstation.

Specifically, if you are on Linux:

check the library is readable with the command file libhasp_linux_x86_64_37102.so.
check the LD_LIBRARY_PATH environment variable is properly set before launching MICROEJ SDK. If MICROEJ SDK is launched from a desktop application, it must have been set in the ~/.profile file.

Sentinel key not found (code 7)

The following error occurred when there is no Sentinel license available. Go to http://localhost:1947/int/devices.html and check your Sentinel licenses. You should see at least one installed license key:

Make sure you correctly configured the access to the Sentinel Floating License Server. Please refer to Add Remote Floating License Server.

No Administrator Privileges on Developer Workstation

Sentinel LDK RTE installation requires administrator privileges and facilitates the setup of the network server. However, it is not necessary to be installed on the developer workstation in case of floating licenses. See this documentation for more details. If you are in such situation, please contact our support team.

Error: Could not find or load main class .library.path=resources.os.Windows64

The following error occurs when running the command line from PowerShell on Windows. Use Command Prompt instead.