License server
The CONNECT license server shares a customer’s CONNECT licences across writing sessions in the local network. It runs as a separate service without gateway, HMI or PLC connections and needs no CONNECT licence of its own. From three CONNECT licences of one customer, the licences are automatically floating: the pool size is the number of CONNECT licences. There is no separate floating article. Activate the server-bound floating token supplied by the portal.
The license server runs on your own premises, like realvirtual itself, which runs locally in the browser and not as a cloud service. Clients reach it only inside your network; the portal is used only for activation, and an offline activation works without internet access on the server.
Install on Windows
Section titled “Install on Windows”Keep the complete Windows CONNECT distribution in a permanent directory, for example
C:\Program Files\realvirtual\CONNECT. Keep realvirtual-connect-cli.exe beside
realvirtual-Connect.exe, including all supplied runtime files. Always use the console CLI shim
for commands on Windows.
Open PowerShell as administrator in that directory:
.\realvirtual-connect-cli.exe license-server install-service.\realvirtual-connect-cli.exe license-server service-status$env:RV_CONNECT_LICENSE_SERVER_DIR = "$env:ProgramData\realvirtual\license-server".\realvirtual-connect-cli.exe license status --target license-serverInstallation starts an automatic service named realvirtual-license-server under LocalService,
grants that account access to its dedicated data directory, and configures restart recovery.
SCM executes the shim’s license-server run command. The shim forwards service stop to the server
and waits for shutdown. Running installation again with the same settings is safe. A conflicting
service is left unchanged. Installation/removal without elevation exits 1 with
CLI_ELEVATION_REQUIRED.
Optional settings:
.\realvirtual-connect-cli.exe license-server install-service --port 5110 --admin-port 5111 --data-dir "D:\CONNECT-license-data" --name plant-license-serverSet RV_CONNECT_LICENSE_SERVER_DIR to the selected data directory in each management shell.
For custom ports, also set RV_CONNECT_LICENSE_SERVER_PORT and
RV_CONNECT_LICENSE_SERVER_ADMIN_PORT, or pass --port and --admin-port to license commands.
Run management commands elevated so they can read the service’s protected runtime identity.
Use a dedicated data directory; installation assigns private permissions to its existing contents.
The service account also needs read/execute access to the distribution directory.
The installer prints a firewall rule suggestion; it does not apply one. Allow inbound TCP 5110 from the intended client network. TCP 5111 is the separate loopback admin listener; keep it local. These are the defaults; substitute custom ports where configured.
Stop/start with sc.exe stop <name> / sc.exe start <name>. Change installation settings by
uninstalling and reinstalling with the same data directory. Uninstall retains keys, certificates,
tokens and the lease journal:
.\realvirtual-connect-cli.exe license-server uninstall-service --name realvirtual-license-serverFor foreground operation, stop the service first, then run the same host through the shim:
.\realvirtual-connect-cli.exe license-server run --license-dir "$env:ProgramData\realvirtual\license-server" --port 5110 --admin-port 5111Install on Linux
Section titled “Install on Linux”Place the Linux CONNECT distribution in /opt/realvirtual-license-server. Install the supplied
deploy/linux/realvirtual-license-server.service unit:
sudo useradd --system --home-dir /var/lib/realvirtual-license-server --shell /usr/sbin/nologin realvirtual-license-serversudo install -m 0644 deploy/linux/realvirtual-license-server.service /etc/systemd/system/sudo systemctl daemon-reloadsudo systemctl enable --now realvirtual-license-serversudo -u realvirtual-license-server /opt/realvirtual-license-server/realvirtual-Connect license status --target license-serverCreate the account only if it does not already exist. systemd creates the private state directory
/var/lib/realvirtual-license-server; the unit sets RV_CONNECT_LICENSE_SERVER_DIR to that path,
LAN port 5110 and loopback admin port 5111. Optional overrides go in
/etc/realvirtual-connect/license-server.env. Run the CLI as the service user, including when
the service is stopped. For foreground operation use
realvirtual-Connect license-server run --license-dir /var/lib/realvirtual-license-server as that
user. Use journalctl -u realvirtual-license-server for startup failures.
Docker
Section titled “Docker”The Dockerfile uses a self-contained linux-x64 publish directory as its build context:
dotnet publish src/Connect/Connect.csproj -c Release -f net8.0 -r linux-x64 --self-contained true -p:PublishSingleFile=true -p:EmbedWebUi=false -o artifacts/license-server-linuxdocker build -f deploy/docker/license-server/Dockerfile -t realvirtual-license-server artifacts/license-server-linuxcd deploy/docker/license-serverdocker compose up -ddocker compose exec license-server /opt/realvirtual-license-server/realvirtual-Connect license status --target license-servercompose.yml persists /var/lib/realvirtual-license-server in license-data and publishes only
5110. Admin commands run inside the container with docker compose exec. Transfer token/request
files using docker compose cp. The image runs as UID 1654; a bind-mounted directory must be
writable by that UID.
Container activation is conditional on hardware identification. A container can expose fewer
than two usable fingerprint sources. A persistent volume does not fix that. If activation reports
LICENSE_FINGERPRINT_UNAVAILABLE, use a physical host or VM with at least two stable, accessible
machine-id/DMI/disk sources, or contact support. This package provides no container fingerprint
workaround. Do not assume a token activated elsewhere is transferable.
Activate the floating token
Section titled “Activate the floating token”Examples below use the Windows shim. On Linux substitute realvirtual-Connect and run as the
service user; inside Docker prefix that command with docker compose exec license-server and its
full executable path. Use the server’s data directory and ports throughout.
Online activation:
.\realvirtual-connect-cli.exe license activate <CONNECT-key> --target license-server.\realvirtual-connect-cli.exe license seatsOffline activation:
.\realvirtual-connect-cli.exe license activate <CONNECT-key> --offline -o floating-request.txt --target license-server# Alternatively create a server-bound request without a key:.\realvirtual-connect-cli.exe license offline-request -o floating-request.txt --target license-server# Redeem the request in the portal on an internet-connected computer, then bring back the signed token:.\realvirtual-connect-cli.exe license import floating-token.txt --target license-serverActivation/import validates the floating token’s signature, customer, server signing key and hardware binding. A node-locked or community token cannot populate this server. The server can start without a token and then has zero seats. Status, activation, offline requests and import also work while stopped under an exclusive data-directory lock.
Pair a CONNECT client
Section titled “Pair a CONNECT client”On the server, create a one-time code and obtain the displayed certificateSha256:
.\realvirtual-connect-cli.exe license pair --name production-cellOn the client computer, stop all CONNECT gateways sharing its licence directory. Use its usual gateway port and licence directory for both pairing and startup:
.\realvirtual-connect-cli.exe license client set https://lic-srv:5110 --pair-code <code> --cert-sha256 <64-hex-pin> --port 5100.\realvirtual-connect-cli.exe --license-mode client --port 5100Obtain the pin directly from the server administrator; it is 64 hexadecimal characters without
colons. Pair codes expire after ten minutes, work once, and are invalidated by a server restart.
Stored client configuration also selects client mode automatically. Use --license-dir when the
client uses a custom directory; this is the client’s directory, separate from the server data.
Pairing binds a private client key to that installation and port.
To disable a client’s key, run license unpair <clientKeyId> on the server. Read the ClientKeyId
field from that client’s protected lease-client-<port>.json in its licence directory; do not
share the secret ClientKey field. Its holders are
revoked; reservations remain until timeout. To return a stopped client to local licensing, run
license client clear on that client and restart it. Clearing local configuration does not unpair
the server key.
Seats and timeouts
Section titled “Seats and timeouts”Only writing sessions hold seats. Read-only tabs and display-only CONNECT instances use an entitlement without occupying a seat. Each writing holder, including a headless writing configuration, needs its own seat. Normal release follows confirmed fencing and draining of writes.
Defaults are a 60-second heartbeat and a five-minute server timeout. A crashed client frees its reservation after timeout. During a network interruption, retries occur every 15 seconds; the client’s conservative deadline is request start plus signed TTL minus ten seconds. Offline grace never extends beyond the server timeout. After the deadline writing is blocked.
license release <leaseId> manually revokes a holder. Its seat becomes reusable after the client
acknowledges that writes have drained, or at the server deadline shown in license leases.
It is not an immediate forced reuse of a potentially active writer’s seat. A server restart
conservatively reserves persisted leases for a full timeout.
A newer imported token that shrinks a pool below current occupancy is rejected as
LEASE_POOL_SHRINK_BUSY (exit 8). Wait until occupancy fits, or explicitly use
license import <file> --target license-server --force. This revokes the newest surplus holders;
their reservations persist until acknowledgement or timeout. --force also applies to online
floating activation.
CLI reference
Section titled “CLI reference”Prefix each command with realvirtual-connect-cli.exe on Windows, or realvirtual-Connect on
Linux. Management commands seats, leases, release, pair, unpair and logs default to the
server. Use --target license-server for status, activate, offline-request and import.
| Command | Purpose |
|---|---|
license-server run [--license-dir <dir>] [--port <p>] [--admin-port <p>] [--json] | Run the separate host in the foreground. |
license-server install-service [--port <p>] [--admin-port <p>] [--data-dir <dir>] [--name <name>] | Install/start the Windows service; elevation required. |
license-server uninstall-service [--name <name>] | Stop/remove the Windows service, keeping its data; elevation required. |
license-server service-status [--name <name>] | Read SCM status; absent service exits 6. |
license status --target license-server | Show capacity, entitlement status, ports and certificate pin. |
license seats | Inspect pool capacity. |
license leases | List holders, reservations and deadlines. |
license release <leaseId> | Revoke one holder, respecting drain/deadline reservations. |
license pair [--name <name>] | Create a one-time code and display the TLS certificate pin. |
license unpair <clientKeyId> | Disable a client key and revoke its holders. Use ClientKeyId from the client’s pairing configuration. |
license logs [--follow] [--since 10m] | Read the running server’s bounded recent operational log; Ctrl+C stops following. |
license client set <https-origin> --pair-code <code> --cert-sha256 <pin> | Pair a stopped gateway installation. |
license client clear | Clear local pairing configuration; restart the gateway. |
License commands accept --json (schema version 1), --quiet, --license-dir, --port and
--admin-port where applicable. Service helpers accept --json. --since supports s, m, h,
d, up to seven days. Seats, leases, release, pair, unpair and logs require a running server.
| Exit | Meaning |
|---|---|
| 0 | Success. |
| 1 | General, storage or permission error, including missing elevation. |
| 2 | Invalid command, option or argument. |
| 3 | No usable licence/entitlement. |
| 4 | Portal or target service unreachable. |
| 5 | All seats occupied. |
| 6 | Required service not running or installed. |
| 7 | Fewer than two usable hardware fingerprint sources. |
| 8 | Rejected key/token/request, including a busy pool shrink. |
Troubleshooting
Section titled “Troubleshooting”| Symptom | Action |
|---|---|
LEASE_SEATS_EXHAUSTED | Inspect license leases; wait, end an unused writing session, or revoke its lease. Read-only tabs remain free. |
LEASE_SERVER_UNREACHABLE | Check service status, DNS/address, TLS pin, routing and TCP 5110. Writes stop at the conservative client deadline. |
LICENSE_FINGERPRINT_UNAVAILABLE | Provide at least two stable usable machine-id/DMI/disk sources on a supported host/VM, or contact support. Containers may not qualify. |
| Certificate pin mismatch / TLS connection failure | Compare with license status --target license-server on the trusted server. Verify any intended certificate change, then pair with a fresh code and the correct pin. The client reports a transport/TLS failure rather than a separate pin-mismatch code. |
| Firewall / ports 5110 and 5111 | Allow clients to reach TLS 5110; keep admin 5111 on server loopback. Check both configured ports for conflicts. Docker publishes only 5110; use exec for administration. |
CLI_ELEVATION_REQUIRED / CLI_PERMISSION_DENIED | Use an elevated Windows terminal, or the Linux service user, and the correct data directory. |
CLI_TARGET_MISMATCH | Match the running service’s --license-dir/environment and ports. |
LEASE_POOL_SHRINK_BUSY | Wait for occupancy to decrease or explicitly import with --force. |
Keep a protected backup of the entire server data directory. Its signing key and certificate are part of the installation identity; preserve them across upgrades. Do not run cloned copies of the same activated server simultaneously.