# License server ## Hex-Rays License Server Administrator Guide ## Introduction {% hint style="info" %} To ensure proper functionality, we recommend that the **License Server version match the IDA Pro version**. For the latest installers, visit the [Download Center](https://my.hex-rays.com/dashboard/download-center) in My Hex-Rays portal. {% endhint %} This manual describes the installation, management, and interaction with a Hex-Rays License Server deployment.\ It is primarily intended for administrators, and will focus on the setup and management of the Hex-Rays License Server. While we will (at least superficially) make use of the command-line client used to access/manage the server, this manual will not offer a detailed explanation of its usage, although there is a dedicated section for [essential lsadm commands](#lsadm-tool-quick-guide) ### Let's get started The first step is to install the Hex-Rays License Server, which is the central component of the deployment. ## Installing the Hex-Rays License Server ### Prerequisites After your purchase of a Hex-Rays product with floating licenses, go to the [customer portal](https://my.hex-rays.com/dashboard/download-center/downloads), where you will find: * an installer for the Hex-Rays License Server * the installer for the product you have purchased * a `license_server_.hexlic` (where \ is your license ID) and the certificate bundle will be available after License Server activation, under [Licenses](https://my.hex-rays.com/dashboard/licenses) tab All those will be necessary, so please go ahead and download them. You will also need `root` access on the host where you will be installing the server. ### Installation This chapter explains how to install the Hex-Rays License Server. #### Installing clients The command-line client `lsadm` is bundled with the Hex-Rays License Server installer. To install both Hex-Rays License Server and `lsadm`, simply run the installer and follow the instructions. Every Hex-Rays product using floating licenses, such as IDA, is also a client of Hex-Rays License Server. For installation instructions for these products, please refer to their documentation. #### Installing the server The Hex-Rays License Server can be installed on x64 Linux servers. We have tested it on Debian and Ubuntu, but other major flavors of Linux should be fine too. To install the server, run the Hex-Rays License Server installer as `root` and follow the instructions (the server will not require `root` permissions; only the installer does.) {% hint style="info" %} If your Linux system is based on `systemd` (e.g., Debian/Ubuntu, Red-Hat, CentOS, ...​), it is recommended to let the installer create systemd units so that the server will start automatically at the next reboot. {% endhint %} #### Activating the server license In order for the Hex-Rays License Server license to be activated, it must be bound to a Host ID (an Ethernet MAC address.)\ From a command prompt, run `/sbin/ifconfig`, and lookup the "ether" address for the network interface through which the server will be accessible. ``` >/sbin/ifconfig enp4s0: flags=4163 mtu 1500 [...snipped...] ether bf:e2:91:10:58:d2 txqueuelen 1000 (Ethernet) [...snipped...] ``` In this case, our MAC address is: `bf:e2:91:10:58:d2` Go to [Hex-Rays customer portal](https://my.hex-rays.com) and [activate your license for license server](https://docs.hex-rays.com/8.5/getting-started/licensing#license-server-activation-for-admins). During that process, you will need to provide the MAC address of the device where the license server will be running. Once the activation is complete, you'll be able to download the following files: * license server certificate bundle * `license_server_.hexlic` (license key) Those need to be copied in the Hex-Rays License Server installation directory. As `root`: ``` >cd /opt/hexlicsrv >cp .../path/to/hexlicsrv.crt . >cp .../path/to/hexlicsrv.key . >cp .../path/to/license_server*.hexlic . >chown hexlicsrv:hexlicsrv hexlicsrv.crt hexlicsrv.key license_server*.hexlic >chmod 640 hexlicsrv.crt hexlicsrv.key license_server*.hexlic ``` #### Creating the initial database At this point, the server should be ready to run. {% hint style="info" %} If your system is already in production, skip this section. Using the `--recreate-schema` option as in the example below, will re-create an empty database. {% endhint %} On the first install, you will need to initialize the database the server will use: ``` >sudo -u hexlicsrv ./license_server --config-file hexlicsrv.conf \ --recreate-schema >2024-04-14 14:30:28 License Server v1.0 Hex-Rays (c) 2024 >2024-04-14 14:30:28 Database initialized; exiting. ``` **Testing the server** Now that the server is installed and has a database to work with, we can test that it works: ``` >sudo -u hexlicsrv ./license_server --config-file hexlicsrv.conf \ --certchain-file hexlicsrv.crt \ --privkey-file hexlicsrv.key \ --license-file license_server_.hexlic >2024-04-14 14:35:47 License Server v1.0 Hex-Rays (c) 2024 >2024-04-14 14:35:47 Using a license with 1 seats >2024-04-14 14:35:47 Listening on 0.0.0.0:65434... ``` Good, the server appears to run! If you are observing more worrying messages than this one, please refer to the [troubleshooting](#troubleshooting) section. At this point, you may want to either let the server run, or stop it (`Ctrl+C` will do) and restart it using systemd: ``` >systemctl restart hexlicsrv.service ``` ...​and make sure it runs: ``` >ps aux | grep license_server hexlicsrv 58246 0.0 0.0 ... ``` If you don't see a running `license_server` process, please refer to the `systemd` diagnostic tools (e.g., `journalctl`) for more info. ### Management This chapter explains in detail how to perform regular administrator tasks. #### Backup and restore Currently, there is no dedicated procedure to back up the Hex-Rays License Server database. It can be done by temporarily stopping the Hex-Rays License Server and making a copy of the sqlite3 database. The server must be stopped only during the backup of the sqlite3 database and then can be immediately restarted. Alternatively, it is possible to use sqlite3 backup functionality to make a backup of the database. #### Upgrading the server Switching to the newest versions of the Hex-Rays License Server is recommended in order for the team to benefit from its improvements and new features. The upgrade procedure consists of the following steps: 1. Stop the server. For example, if you are using `systemd` to manage the server: `sudo systemctl stop hexlicsrv` 2. Perform a [backup](#backup-and-restore) of the database 3. Launch the installer 4. Follow the on-screen instructions 5. Upgrade the database with `./license_server --config-file hexlicsrv.conf --upgrade-schema` 6. Restart the server. E.g., `sudo systemctl start hexlicsrv` #### Hex-Rays License Server command-line options ``` -p ...​ (\--port-number ...​) Port number (default 65434) -i ...​ (\--ip-address ...​) IP address to bind to (default to any) -c ...​ (\--certchain-file ...​) TLS certificate chain file -k ...​ (\--privkey-file ...​) TLS private key file -v (\--verbose) Verbose mode (\--upgrade-schema) Upgrade database schema; then quit -C ...​ (\--connection-string ...​) Connection string -l ...​ (\--log-file ...​) Log file -L ...​ (\--license-file ...​) License file -f ...​ (\--config-file ...​) Config file (\--recreate-schema) Drop & re-create schema; then quit **THIS WILL ERASE ALL DATA** ``` ### Troubleshooting This chapter explains how to solve typical problems with the Hex-Rays License Server. #### Connection issues By default, the Hex-Rays License Server listens on the TCP port 65434 on all interfaces. Please ensure that this port is enabled in your firewalls. The Hex-Rays License Server uses secure TLS connections with the clients. The TLS layer requires the certificate (.crt) and private key (.key) files. Usually, they are attached to the email message with the activation information. #### The server complains about a "world-accessible" file, and exits The following files shouldn't be readable by everyone on the system, but only by `root` and `hexlicsrv`: * `hexlicsrv.conf`: this file file holds the connection string to the database the server will use, and might contain credentials. * `hexlicsrv.crt`: the certificate chain * `hexlicsrv.key`: the private key file * `license_server_.hexlic`: the license file As a precaution, the Hex-Rays License Server will refuse to start if these files are readable by unauthorized users. Please make sure they: * have `hexlicsrv:hexlicsrv` ownership: `chown hexlicsrv:hexlicsrv hexlicsrv.crt hexlicsrv.key licensesrv.hexlic hexlicsrv.conf` * are not world-accessible: `chmod 640 hexlicsrv.crt hexlicsrv.key license_server_.hexlic hexlicsrv.conf` #### Licensing The licensesrv.hexlic file is tied to the MAC address of the first network interface. If they do not match, the server will not start. To change the MAC address, please contact [support](mailto:support@hex-rays.com) #### "Error: Failed to list licenses" This error means that the currently installed license server license file (hexlic) content is incorrect. More precisly, the "licenses" list does not contain an entry with the following items: ``` ... "product_id": "IDAPRO", "edition_id": "ida-pro", ... ``` or that the activation end date in the same section has expired. Make sure to activate all the floating license plans owned by the license server **before** downloading the license server hexlic file. #### Restoring from backups There are no special precautions to take: restoring the sqlite3 database from a backup should be enough. ### lsadm Tool Quick Guide This quick manual presents the basic common commands for lsadm tool. **Note**: Replace `:` with your actual server address and port. #### List All Licenses ``` ./lsadm -h : list ``` This command shows: * Licensed products and their IDs (IDA, License server, Teams Server or Lumina Server) * Add-ons/decompilers associated with each license * License start and expiration dates * Available and total seats * License owner information #### Example Output Structure ``` Licenses (assigned to admin@example.com, ): License: License ID: 96-C43F-B0F4-96 Product: IDAPRO Add-ons: HEXX86: License ID: 97-DCD8-46B5-86 Owner ID: 96-C43F-B0F4-96 Start: 2024-10-07 Expiration: 2025-10-07 Features: Start: 2024-10-07 Expiration: 2025-10-07 Available seats: 32 Total seats: 35 License: License ID: 96-E735-E78D-9B Product: LICENSE_SERVER Add-ons: Features: Start: 2024-10-08 Expiration: 2025-10-08 Available seats: 1 Total seats: 1 ``` ### Check Active and Borrowed Licenses ``` ./lsadm -h : active ``` This command shows: * currently used licenses * users using those licenses (both online and borrowed) * end dates for borrowed licenses #### Example Output Structure ``` Active licenses: 96-C43F-B0F4-96 IDAPRO (HEXX86, HEXX64, HEXARM, HEXMIPS, HEXARM64, HEXMIPS64, HEXPPC, HEXPPC64, HEXARC, HEXRV, TEAMS, LUMINA, HEXRV64): used 3 out of 35 seat(s) Expires: 2025-10-07 Online users: root@secrethost (192.168.0.131): 1 instance(s) Borrowed by: bob@chronos until 2025-03-14 17:10:32 alice@badger until 2025-10-01 00:00:00 ``` #### Display Server Information ``` ./lsadm -h : info ``` This command shows: * Server version * MAC address * Connected client details and session timestamp #### Example Output Structure ``` Server info: Version: v1.0 MAC address: AA:BB:CC:DD:EE:FF Client: Name: 192.168.0.104 Session ID: 187 Established: 2025-02-10 17:37:35 ```