Set up an on-premises license server (Icarus)¶

Icarus is SciTools' license server that you host on your own network. Normally Understand verifies licenses against SciTools' cloud server (Helios, at licensing.scitools.com); Icarus is a drop-in replacement for closed labs and other environments that can't reach it. It speaks the same HTTPS/REST protocol, so as far as Understand is concerned there is no difference — clients just point at your server instead.

Icarus hands out seats keyed to the requesting username, whatever machine the user is on, and denies requests once the seat cap or concurrent-use limit is reached. A web GUI shows who is using what and lets an administrator deregister users, free stuck seats, and pull usage reports.

Requirements¶

Set up must be done by a user with admin privileges (also required to register the service).
Two incoming ports open — 443 and 80 by default (both configurable).
A 64-bit OS: Windows 7+, macOS 10.12+, RHEL/CentOS 7.4+, or Ubuntu 16.04+.

The -service feature doesn't cover RHEL or macOS

The service library Icarus uses can't register a service on some RHEL systems or on macOS. Icarus itself runs fine there as root. On RHEL, set up the service yourself — see Run Icarus as a systemd service on RHEL. On macOS, arrange your own startup script or system service to launch it at boot.

Install and license the server¶

Locate icarus.zip and extract it on the server machine. On Windows, select the Offline License Server (Icarus) component in the installer's Advanced Install (it's off by default); the Linux and macOS kits ship icarus.zip in the same directory as the und executable. It is also available from licensing.scitools.com/download-all (log in, then switch the product selector to Icarus).
In a terminal running as administrator, from the extracted directory:
```
icarus -service install
icarus -service start
```
(The other service commands are stop, restart, and uninstall.) On RHEL, set up the service with systemd instead.
Open a browser to the server (https://localhost from the machine itself). The page shows an InstanceId.
Send the InstanceId to SciTools or your regional distributor; you'll receive an icarus.dat license file in return.
Upload icarus.dat through the web GUI (Add Icarus License). Seats are served immediately.

Run Icarus as a systemd service on RHEL¶

icarus -service install doesn't work on some RHEL systems. On those, register Icarus as a systemd service by hand instead. These steps were tested on RHEL 8.10.

Run every command below as root. Start a root shell with:

sudo -i

Install Icarus under /opt/icarus¶

Put Icarus under /opt/icarus, not in a home directory. SELinux doesn't let systemd run programs stored under /home, so a service pointing there fails with status=203/EXEC.

mkdir -p /opt/icarus
cp -r <extracted-icarus-dir>/* /opt/icarus/
chmod +x /opt/icarus/icarus
restorecon -Rv /opt/icarus
/opt/icarus/icarus -version

The last command prints the Icarus version, which confirms the copy worked.

If you must use a different directory (for example under /data), give it a label that lets systemd run programs from it, then use that path instead of /opt/icarus in the rest of this section:

semanage fcontext -a -t bin_t "<dir>(/.*)?"
restorecon -Rv <dir>

Create the service¶

Create the unit file in place with the command below. Copy and paste the whole block, from cat through the final EOF:

cat > /etc/systemd/system/icarus.service <<'EOF'
[Unit]
Description=Icarus License Server
After=network-online.target

[Service]
ExecStart=/opt/icarus/icarus
WorkingDirectory=/opt/icarus
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

Create the file where it lives

Don't write the unit file somewhere else and mv it into /etc/systemd/system. A moved file keeps its old SELinux label, and systemctl then reports Unit file icarus.service does not exist even though the file is there.

Then set its permissions and label, and start the service:

chmod 644 /etc/systemd/system/icarus.service
restorecon -v /etc/systemd/system/icarus.service
systemctl daemon-reload
systemctl enable --now icarus
systemctl status icarus

systemctl status should show active (running). enable --now also starts Icarus automatically at every boot.

Check the ports¶

On Linux, Icarus 1.4 (builds from October 2026 on) keeps its settings, logs and certificates in /.config/SciTools/Icarus/, whichever user runs it.

On first start, Icarus creates settings.dat there with the default ports: Port and SecureWebport 443, Webport 80. If another service already uses the license port (Port), Icarus can't start, and systemctl status icarus shows activating (auto-restart). settings.dat has still been created, so edit the ports in it (see Configuration: settings.dat), then restart:

systemctl restart icarus

If only Webport (or a SecureWebport that differs from Port) is taken, Icarus keeps running without it and writes Could not redirect from port or Could not listen on to err.log. Change that port the same way.

Port 80 stays open unless you move it

With EnableWebport 0, Icarus still listens on Webport, but only to redirect browsers to the secure port. To keep port 80 closed, set Webport to a port nothing else uses.

Open the firewall¶

RHEL turns on firewalld by default. It blocks incoming connections even while Icarus is listening. Open every port Icarus uses — repeat the first command for each one:

firewall-cmd --permanent --add-port=<port>/tcp
firewall-cmd --reload

With the default settings, that's ports 443 and 80.

To check, first confirm Icarus is listening on the server:

ss -ltnp | grep icarus

Each port should show as *:<port> or 0.0.0.0:<port>. Then test from another machine:

curl -vk https://<server>:<port>

On Windows, use curl.exe -vk https://<server>:<port>, or in PowerShell Test-NetConnection <server> -Port <port>. A test run on the server itself goes through localhost, so it doesn't prove other machines can connect.

Once Icarus is reachable, continue from step 3 of Install and license the server.

Manage the service¶

To	Run
See whether Icarus is running	`systemctl status icarus`
Start, stop or restart it	`systemctl start icarus` (or `stop`, `restart`)
Read its output, including crash messages	`journalctl -u icarus`

Let systemd be the only thing that starts Icarus — don't also launch it from a shell or a wrapper script. A copy started from an SSH session can be killed when the session ends, and its error output is lost when the terminal closes.

Troubleshoot the service¶

Symptom	Fix
`Unit file icarus.service does not exist`	Run `chmod 644` and `restorecon -v` on `/etc/systemd/system/icarus.service`, then `systemctl daemon-reload`.
`status=203/EXEC`	Icarus is in a home directory or has the wrong SELinux label (see Install Icarus under /opt/icarus), or isn't executable (`chmod +x /opt/icarus/icarus`).
activating (auto-restart)	Another service is using Icarus's license port — see Check the ports.
Running, but other machines can't connect	firewalld is blocking the port — see Open the firewall.

To look for anything else SELinux has blocked recently:

ausearch -m avc -ts recent

Point Understand at your server¶

On each client (or once in a deployed image):

und -setlicenseserver <hostname-or-IP-or-URL>

Add :<port> if you changed the license port from its default 443 (e.g. und -setlicenseserver license01:9000). You can also pass a full URL (e.g. und -setlicenseserver https://license01.example.com). The UNDERSTAND_LICENSE_SERVER environment variable does the same per-run, which is handy on CI runners — see Licensing from the command line, the und licensing reference, and Licensing without internet. Understand uses the system proxy, so a proxy rule may be needed for clients to reach Icarus.

Configuration: settings.dat¶

On first launch Icarus writes settings.dat next to its logs:

OS	Location
Windows	`C:\Windows\System32\config\systemprofile\AppData\Roaming\SciTools\Icarus`
Linux	`/.config/SciTools/Icarus` for Icarus 1.4 builds from October 2026 on, whichever user runs it; older versions use `$HOME/.config/SciTools/Icarus`
macOS	`/Library/Application Support/SciTools/Icarus`

Key	Default	What it does
`Port`	443	HTTPS port Understand connects to for licenses. May equal `SecureWebport`.
`SecureWebport`	443	HTTPS port for the web GUI. May equal `Port`.
`EnableWebport`	0	Enables (`1`) the unencrypted web GUI on `Webport` — for users who can't bypass the self-signed-certificate warning. With `0`, Icarus still listens on `Webport`, but only to redirect to the secure port.
`Webport`	80	Unencrypted web-GUI port (GUI only — Understand can't license through it).
`AllowTLS12`	0	Accept TLS 1.2 in addition to TLS 1.3 (see below).
`AuthName` / `UserHash`	—	Optional single web-GUI login username (plain text, or SHA-256 hash). Use one, not both. Newer builds support any number of admins — see Manage web GUI admins.
`AuthPass` / `AuthHash`	—	Optional single web-GUI login password (plain text, or SHA-256 hash). Use one, not both.
`InstanceId`, `MachineId`, `Hash`	—	Generated identifiers — never edit these, Icarus stops working.

Every change requires an Icarus restart. Setting both an auth name and password makes the web GUI prompt for a login; use it over SecureWebport, since on Webport the credentials travel in plain text. On builds that support -admin, these keys still work and count as one more admin. Icarus generates a self-signed cert.pem/key.pem pair — browsers will warn until you bypass the warning or replace the pair with your own certificate and key (same filenames).

Manage web GUI admins¶

Icarus 1.4 builds from October 2026 on support any number of web GUI admins, so the lab isn't locked out when one admin is unavailable. Admins are stored in admins.dat, next to settings.dat, and managed from the command line. Run these from the directory containing Icarus, in a terminal running as administrator (Windows) or as root (Linux, macOS):

To	Run
Add an admin	`icarus -admin add <username>`
Add an admin, storing the username as a SHA-256 hash	`icarus -admin add <username> -hashuser`
List admins	`icarus -admin list`
Delete an admin	`icarus -admin delete <username>`

add asks for the password twice without showing it. To script an install, pipe the password in instead (for example echo <password> | icarus -admin add <username>). Usernames and passwords are case-sensitive; a username containing spaces must use -hashuser.

With -hashuser, admins.dat holds only a hash of the username. list shows such an admin as the first 8 characters of its hash (more if two hashes start the same way), and delete accepts either that short hash or the username itself:

> icarus -admin list
Admins ( C:\Windows\System32\config\systemprofile\AppData\Roaming\SciTools\Icarus\admins.dat ):
  "kyle"
  81b637d8             ( hashed username )

> icarus -admin delete 81b637d8

Changes take effect immediately — Icarus doesn't need to be restarted. While any admin exists, every page and action in the web GUI requires a login; with none, the web GUI is open to anyone who can reach it. Deleting the last admin therefore requires -force. An admin defined by the AuthName/AuthPass keys in settings.dat appears in list as from settings.dat; to remove it, delete those keys and restart Icarus.

Each command prints the full path of the file it changed. On Windows, the Icarus service and a copy of Icarus started by hand keep separate configuration folders, so the commands pick one:

Icarus service installed — they update the service's folder (C:\Windows\System32\config\systemprofile\AppData\Roaming\SciTools\Icarus), which requires a command prompt opened with Run as administrator.
Service not installed — they update %APPDATA%\SciTools\Icarus for the current user, the folder Icarus uses when that user launches it directly, and say so.

On Linux and macOS there is only one folder (see Configuration: settings.dat).

admins.dat can also be edited by hand. Each admin is one line, UserName <username> <password hash> or UserHash <username hash> <password hash>, with SHA-256 hashes in hex; blank lines and lines starting with # are ignored.

TLS compatibility¶

Icarus requires TLS 1.3 by default. If a client can't negotiate it — most commonly Understand on macOS, whose TLS backend only offers TLS 1.2 — set AllowTLS12 1 in settings.dat and restart. Understand builds 1078 and newer speak TLS 1.3 and work with every Icarus version; if you're running much older Understand builds, contact support for the compatibility matrix (builds older than 934 can't use Icarus at all).

Manage users and seats¶

In the web GUI, the In Use view is a live snapshot of available seats and active users; the Users view lists everyone who has ever connected, where you can deregister a user or free a seat that's stuck in use. Users are added automatically on first connection.

Restrict who can take a seat (whitelist)¶

To restrict who may take a seat, give Icarus a whitelist. When the whitelist has any users, only those users can check out a license; when it's empty, everyone can. There are two ways to manage it:

Web GUI — upload a text file with one username per line via Add User Whitelist. The upload replaces the whole whitelist.
Command line (Icarus 1.4 builds from October 2026 on) — add or remove individual users without replacing the list. Run as administrator or root, as for admins; on Windows the commands choose the folder the same way.

To	Run
Add users	`icarus -whitelist add <username> [<username> ...]`
List whitelisted users	`icarus -whitelist list`
Delete users	`icarus -whitelist delete <username> [<username> ...]`

Command-line changes take effect immediately, without restarting Icarus. Adding the first user to an empty whitelist locks out everyone else, and the command warns you when it does. Deleting the last user opens Icarus to everyone again, so it requires -force.

Usernames are case-insensitive and may only contain letters and digits. Both the upload and the commands store names the same way Icarus compares them, so other characters are dropped: John.Doe is stored as johndoe, and add tells you when it changes a name. (In older builds, uploaded names containing special characters never matched, and names with capitals matched only after Icarus restarted.) whitelist.dat contains a checksum, so don't edit it by hand — Icarus won't start with a modified file.

Reports¶

Generate Report produces a signed usage report for a date range (Validate Report checks one hasn't been altered), and daily per-user usage accumulates in a downloadable CSV. For the cloud-licensing equivalent of this workflow, see Manage a team — seats and usage.

Logs and troubleshooting¶

Icarus writes three logs beside settings.dat: err.log (errors) and event.log (registrations, start/stop — the two to attach to a support ticket), plus web.log (access log). Like Understand, Icarus follows a live-service model — if you hit an issue, try the latest build first. Two known gotchas: upgrading across a minor version (e.g. 1.1.x → 1.2.x) usually needs a new icarus.dat from your distributor, and Nessus vulnerability scans have been known to terminate the Icarus service unexpectedly. Questions: [email protected].