Setting up the license service (organization mode)

This page is for whoever administers your organization’s infrastructure (systems team, or the IBM i server administrator) — you don’t need to read it to program in WARP. It covers the one-time setup of the service that hands out licenses across your whole development team. People who just use Warpgate get three final values (Host, Port, Fingerprint) from the administrator and put them in their @License — see Licensing.

1. Download

• license-service (administers the service): Linux · Windows
• license-gui (visual query tool, optional — see section 5): Linux · Windows
• Checksums: SHA256SUMS.txt

On Linux, make them executable: chmod +x license-service license-gui.

2. Request the organization license

On the server where the service will run:

license-service create-request --license-id "<Your organization's name>" --out request.json
license-service gen-hwid

The second command prints several machine details; copy the primary_os_id value (a 32-character string). Send to warpgate@softwarehouse.pe:

• The request.json file.
• The primary_os_id value.
• How many simultaneous seats your team needs.

Software House replies with a license.json file for that server, valid for 90 days and renewable — same free-of-charge model as the individual license, see Licensing.

3. Install the service

Windows, with the license-gui window (recommended)

The license-gui window is only available in Spanish. Its tabs and buttons are written here exactly as they appear on screen, with a translation in parentheses the first time.

1. Keep license-gui.exe and license-service.exe in the same folder (for example C:\license). The service is registered pointing to that folder: don’t move it afterwards.

2. Open license-gui.exe with right click → Run as administrator. On the connection screen, click Servidor local: instalar y mantener… (“Local server: install and maintain”).

3. The window has these tabs:

   • 1. Solicitar licencia (request the license): enter the license identifier and click Crear solicitud (create request). It generates request.json and a request-hwid.txt with the machine identifier (with a Copiar (copy) button). Send both files to Software House (see section 2).

   • 2. Instalar servidor (install server): choose the received license.json and fill in:

     • Nombre del servidor (server name): by default, the computer’s full name.
     • Puerto (port): 7443 by default.
     • Red de usuarios (firewall) (users’ network): LocalSubnet or a range (for example 192.168.0.0/24). The firewall rule is only created if Windows Firewall is active in some profile.
     • Consultar con la GUI desde (query with the GUI from): networks allowed to query remotely (see section 7).

     Then click Instalar servicio y arrancar (install service and start). In order, the window registers the service, installs the license, generates the certificate, adjusts the permissions of the data directory (only SYSTEM and Administrators), creates the firewall rule if applicable, starts the service and checks that it is listening. At the end it shows the fingerprint and the @License block ready to copy to the clients.

     There is also Desinstalar servicio… (uninstall service): it stops and removes the service and removes the firewall rule. An optional checkbox also deletes the data (license, certificate, seats database and log); by default they are kept.

   • 3. Certificado TLS (TLS certificate): to use the organization’s certificate (see section 6).

   • 4. Log del servicio (service log): refreshes by itself every 3 seconds; it has Copiar and Limpiar log… (clear log) (empties the file without deleting it; the service keeps writing).

The Windows service is named WarpgateLicense and starts automatically. Its data lives in C:\ProgramData\license-service\:

LDAP certificates: the LDAP client (ldaps://) trusts the certificate authorities in the system store. If the domain controller uses an internal CA, that CA must be installed in the store of the machine running the service (on Windows, the Windows certificate store). Otherwise the LDAPS connection fails and the service denies access.

Windows, from the console (alternative)

license-service install-license --license license.json
license-service gen-tls-cert --subject-alt-name <server-host-or-domain>
license-service install-windows-service --bind 0.0.0.0:7443

This registers license-service as a regular Windows service (starts automatically, restarts itself on failure) — manage it from the Services console like any other. The second command prints the SHA-256 fingerprint on screen: that value is the Fingerprint needed by anyone connecting.

Linux, as a systemd service (recommended)

1. Copy the binary and create a dedicated user for the service:

   sudo install -m 0755 license-service /usr/local/bin/license-service
   sudo useradd --system --no-create-home --shell /usr/sbin/nologin warpgate-license
   sudo install -d -o warpgate-license -g warpgate-license -m 0700 /var/lib/license-service
   

2. Install the license and generate the certificate, as that user:

   sudo -u warpgate-license env LICENSE_SERVICE_DIR=/var/lib/license-service \
     license-service install-license --license /path/to/license.json
   sudo -u warpgate-license env LICENSE_SERVICE_DIR=/var/lib/license-service \
     license-service gen-tls-cert --subject-alt-name <server-host-or-domain>
   

   Write down the SHA-256 fingerprint the second command prints: that value is the Fingerprint.
3. Download the systemd unit file, copy it and enable the service:

   sudo cp license-service.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable --now license-service
   

This makes the service start on boot and restart itself on failure. Logs: journalctl -u license-service -f. Only open TCP port 7443 to the subnet of Warpgate users.

Linux, quick test (no systemd)

To test before installing it as a permanent service:

license-service install-license --license license.json
license-service gen-tls-cert --subject-alt-name <server-host-or-domain>
license-service run --bind 0.0.0.0:7443

Runs in the foreground; stops when you close the terminal. Useful to verify everything works before the step above.

4. Hand the values to your team

Each developer puts these three values in their project’s @License (see Licensing):

• Host: the server where the service runs.
• Port: 7443 (or whatever was set with --bind).
• Fingerprint: the one gen-tls-cert printed.

If the .warpcfg has a Host, the service takes precedence: there is no automatic fallback to the individual license file, so if the service goes down, generate/build/reverse fail. Host without Fingerprint is an error.

If your organization uses Active Directory, the service can require Kerberos authentication — contact Software House to enable it.

Mode without a domain (no auth.json)

If Kerberos is not configured, the identity of whoever takes a seat is the name the machine declares (not verified). In addition:

• Queries (license-gui, license-service query and also warpgate --action license-status in organization mode) are only accepted from the service’s own machine. From another PC, the service rejects the query: warpgate shows “Your user is not authorized to use the warpgate license. Ask the administrator for access.”, license-gui shows “no estás autorizado para esta operación” (“you are not authorized for this operation”), and the service logs consulta rechazada desde <IP> (“query rejected from” the client’s IP). To allow remote queries, see section 7.
• Taking a seat (generate, build, reverse) has no such restriction: it works from any PC that can reach the service.
• Installing or replacing licenses is always only done from the server (or by Kerberos administrators).

5. Checking the service with license-gui

license-gui is a separate window, no command line, for checking the license status without touching the seats in use (it doesn’t consume a seat): active license and expiry, seats in use and available, and each user’s session history (including whether a session closed normally or was lost).

On opening, it asks for the same three values as any client — Host, Port, Fingerprint — plus an optional SPN if the service requires Kerberos. Whoever administers the service can also install a new license from there, with no restart needed.

Its tabs are Usuarios, Licencias (installing a license is only allowed to administrators), Estadísticas and Log del servicio. From another PC it only works if remote queries were enabled (or with Kerberos).

6. TLS certificate

By default the service uses a self-signed certificate, valid from 1975 to 4096 (practically never expires). The client does not check dates, CA chain or name: it only compares the certificate’s SHA-256 fingerprint with the configured Fingerprint.

If security requires the organization’s certificate, it can be used from the 3. Certificado TLS tab of the window, choosing the type:

The window converts to the internal format and saves (the previous one is kept as tls_cert.der.previous and tls_key.der.previous), restarts the service if the option is checked, and shows the fingerprint (with a Copiar button) and the @License block. If the file contains the full chain, the server’s own certificate (the one matching the key) is used.

Errors explained by the window: key does not match the certificate, wrong PFX password, wrong type, and PEM key encrypted with a password (not supported: remove the password with openssl pkcs8 -in key.pem -out key-no-password.pem -nocrypt, or provide a PFX).

Important: changing the certificate changes the fingerprint, and it must be updated on all clients (@License and the license-gui connection screen). Renewing a corporate CA certificate changes it again.

Console equivalent (then restart the service):

license-service import-tls-cert --format pem|pfx|der --cert <file> [--key <file>] [--password-env VARIABLE]

7. Read-only remote queries

Without Kerberos, for license-gui and license-status to query from other PCs, create the auth.json file in the data directory (C:\ProgramData\license-service\auth.json; /var/lib/license-service/ with systemd):

{ "query_allowed_networks": ["192.168.0.10", "10.1.2.0/24"] }

• Accepts IPs or CIDR ranges, IPv4 and IPv6.
• Only applies without Kerberos and requires restarting the service.
• Create the file without BOM (strict JSON).
• From those networks, users, history, statistics and log are visible, but licenses cannot be installed and the Servidor local… button does not appear.
• Addresses are authorized, not people: keep the list short.

Shortcut: the Consultar con la GUI desde field on the 2. Instalar servidor tab writes this auth.json (it does not overwrite an existing one).

8. Connection limits

The service drops a new connection before TLS and notes it in the log with the IP (1 out of every 50 rejections). It does not affect anyone who already holds a seat.

• Total: seats × 2 + 20 (computed from the license).
• Without a session yet (handshake or authenticating): maximum 50.
• Per IP: 5 by default; configurable with "max_connections_per_ip": N in auth.json (0 = no limit). Connections from the service’s own machine are exempt from this cap.

Raise the per-IP value if many users share an IP (build server, remote desktop). Requires restarting the service.

9. Statistics and export

license-gui queries and administers without consuming a seat. The Estadísticas tab lets you choose the period (7, 30, 90 days or 1 year) and shows:

• Sessions and distinct users.
• Peak of simultaneous seats and when it happened.
• Percentage of usage time with all seats taken, and usage time.
• Rejections due to lack of seats (recorded only since this version; there is no earlier data).
• Charts of the peak per day and per hour of day (local time), and a per-day detail.
• A guiding reading: “consider expanding” if there were rejections; “at the limit” if the pool was full 5% or more of the usage time; “spare capacity” if the peak was half or less of what was contracted. It warns if there are fewer than 7 days with usage.

It helps decide whether to buy more seats.

The Exportar ▾ menu offers: Resumen de usuarios (CSV) (users summary), Historial de sesiones del período (CSV) (session history for the period), Log del servicio (texto) (service log, as text) and Estadísticas del período (CSV) (statistics for the period). The CSVs use ; and a UTF-8 BOM (they open correctly in Spanish-locale Excel) and neutralize values starting with =, +, - or @ (formula injection). History and log require being able to see all users.

10. Common problems