License Server User Guide

6. License Server with a Dongle

A license server can validate licenses through a hardware dongle. Only a server with the designated dongle inserted can run the licensed software, ensuring license security and uniqueness.

This deployment is intended for site licensing. A customer can privately deploy a license server with a dongle to centrally manage and distribute licenses without collecting a machine fingerprint for every server.

6.1 Deploying a License Server with a Dongle

Before deployment, obtain an authorized Feitian ROCKEY-ARM USB dongle from DolphinDB.

  • Insert the dongle into the Linux server. Windows is not supported. Only one dongle can be connected to a server, and DolphinDB uses device 0.
  • Install the udev rule with root privileges so that a non-root user can read the USB device. DolphinDB reports an error at startup if the rule is missing.
cp ft.rules /etc/udev/rules.d/
udevadm control --reload-rules && udevadm trigger
  • Set licenseFromDongle=true in the DolphinDB configuration file. DolphinDB then reads only the license stored in the dongle, even if a local license file exists. To start in license server mode, also set isLicenseServer=true.
  • Start DolphinDB. Permission checks and dongle access usually add 1–2 seconds to startup.

Search for dongle in the log to check startup, shutdown, and lease renewal, which runs every 60 seconds.

Normal startup:
Reading license from ROCKEY-ARM dongle for license server...
Dongle share memory not initialized, acquiring lock.
Acquired dongle license server lock, leaseExpire=2026-03-30 12:00:00
Successfully read license from ROCKEY-ARM dongle.

Normal shutdown:
[DongleLease] Shutdown flag detected, stopping renewer.
[DongleLease] Releasing dongle lock...
[DongleLease] Lock released successfully (share memory cleared).
[DongleLease] Lease renewer thread terminated.

Renewal failure:
[DongleLease] Failed to open dongle for renewal.
[DongleLease] Renewal failed, failCount=1/3
[DongleLease] Renewal failed, failCount=2/3
[DongleLease] Renewal failed, failCount=3/3
[DongleLease] Max retries reached. Shutting down license server.

Lock takeover:
[DongleLease] Lock lost! Another process took over. License server must exit.
[DongleLease] Lock taken by another process. Shutting down immediately.

6.2 Querying License Allocation and Usage

The license server provides the following functions to query the daily maximum allocation and actual usage for the past 408 days:

  • getDongleAllocStats: Returns the maximum CPU cores, memory, and nodes allocated through registerLicenseServerUser or setLicenseServerUserResource.
  • getDongleUsageStats: Returns the maximum CPU cores, memory, and nodes actually used by online nodes.

The system records the previous day's data at midnight and records the current day's data when the license server shuts down.

6.3 Notes

  • License data is written to the dongle by DolphinDB and cannot be modified by users.
  • The dongle must remain connected to the license server. Removing it or failing three consecutive lease renewals shuts down the service.
  • Only one license server process can use the dongle at a time. A normal shutdown releases the lock. After an abnormal exit, a new process may need to wait up to 60 seconds before taking over.
  • The license server process itself is limited to 2 CPU cores and 4 GB of memory. The specifications in the license server license indicate the resources that can be allocated to clients.