Skip to content

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.

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:

Terminal window
.\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-server

Installation 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:

Terminal window
.\realvirtual-connect-cli.exe license-server install-service --port 5110 --admin-port 5111 --data-dir "D:\CONNECT-license-data" --name plant-license-server

Set 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:

Terminal window
.\realvirtual-connect-cli.exe license-server uninstall-service --name realvirtual-license-server

For foreground operation, stop the service first, then run the same host through the shim:

Terminal window
.\realvirtual-connect-cli.exe license-server run --license-dir "$env:ProgramData\realvirtual\license-server" --port 5110 --admin-port 5111

Place the Linux CONNECT distribution in /opt/realvirtual-license-server. Install the supplied deploy/linux/realvirtual-license-server.service unit:

Terminal window
sudo useradd --system --home-dir /var/lib/realvirtual-license-server --shell /usr/sbin/nologin realvirtual-license-server
sudo install -m 0644 deploy/linux/realvirtual-license-server.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now realvirtual-license-server
sudo -u realvirtual-license-server /opt/realvirtual-license-server/realvirtual-Connect license status --target license-server

Create 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.

The Dockerfile uses a self-contained linux-x64 publish directory as its build context:

Terminal window
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-linux
docker build -f deploy/docker/license-server/Dockerfile -t realvirtual-license-server artifacts/license-server-linux
cd deploy/docker/license-server
docker compose up -d
docker compose exec license-server /opt/realvirtual-license-server/realvirtual-Connect license status --target license-server

compose.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.

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:

Terminal window
.\realvirtual-connect-cli.exe license activate <CONNECT-key> --target license-server
.\realvirtual-connect-cli.exe license seats

Offline activation:

Terminal window
.\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-server

Activation/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.

On the server, create a one-time code and obtain the displayed certificateSha256:

Terminal window
.\realvirtual-connect-cli.exe license pair --name production-cell

On the client computer, stop all CONNECT gateways sharing its licence directory. Use its usual gateway port and licence directory for both pairing and startup:

Terminal window
.\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 5100

Obtain 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.

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.

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.

CommandPurpose
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-serverShow capacity, entitlement status, ports and certificate pin.
license seatsInspect pool capacity.
license leasesList 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 clearClear 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.

ExitMeaning
0Success.
1General, storage or permission error, including missing elevation.
2Invalid command, option or argument.
3No usable licence/entitlement.
4Portal or target service unreachable.
5All seats occupied.
6Required service not running or installed.
7Fewer than two usable hardware fingerprint sources.
8Rejected key/token/request, including a busy pool shrink.
SymptomAction
LEASE_SEATS_EXHAUSTEDInspect license leases; wait, end an unused writing session, or revoke its lease. Read-only tabs remain free.
LEASE_SERVER_UNREACHABLECheck service status, DNS/address, TLS pin, routing and TCP 5110. Writes stop at the conservative client deadline.
LICENSE_FINGERPRINT_UNAVAILABLEProvide 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 failureCompare 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 5111Allow 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_DENIEDUse an elevated Windows terminal, or the Linux service user, and the correct data directory.
CLI_TARGET_MISMATCHMatch the running service’s --license-dir/environment and ports.
LEASE_POOL_SHRINK_BUSYWait 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.