Configure a Gateway license

Purpose

Install the vendor-signed Gateway license that authorizes a logical Gateway deployment and its component capacities.

Get the identity before issuance

Create and validate the intended configuration first. The identity is configuration, not a host or hardware fingerprint:

/opt/particle_horizon/keystone-gateway node-id --config /opt/particle_horizon/local_config/keystone-gateway/gateway.yaml

Example output:

{"gateway_id":"gw-acme-production","replica_id":"gateway-a"}

For standalone, send the gateway_id and the one replica_id to the license issuer. For Active/Standby, run the command with each replica’s configuration and submit one shared gateway_id plus both distinct replica IDs. The same configured values can be used after a VM rebuild; copying them to an unintended clone also authorizes that clone, so protect the configuration and license. Changing either value requires a replacement license. This V1 implementation does not bind a license to a machine UUID or disk.

Request, install, and verify

Provide the issuer with the Gateway ID, one or two replica IDs, requested expiry/term, and entitlement counts for PHOCOL and/or LMC Exporter components. When you receive gateway-license.json:

install -o keystone-gateway -g keystone-gateway -m 0600 gateway-license.json \
  /opt/particle_horizon/local_config/keystone-gateway/gateway-license.json
/opt/particle_horizon/keystone-gateway config validate --config /opt/particle_horizon/local_config/keystone-gateway/gateway.yaml
systemctl restart keystone-gateway
journalctl -u keystone-gateway -n 50 --no-pager

Successful startup logs Gateway license verified. Query authenticated GET /v1/license and GET /v1/entitlements to confirm expiry and capacity. These metadata endpoints return all entitlements in the Gateway license; a principal’s allowed_license_type scopes its lease operations rather than filtering these responses. Bearer authentication is restricted to lease paths and cannot query them. Gateway reads and validates the license only at startup; replacing the file requires a restart.

What the license contains

The signed JSON document contains schema_version: 1, license_type: "gateway", license_id, customer_id, gateway_id, permitted nodes (replica IDs), UTC expires, and entitlements. An entitlement is a non-negative concurrent capacity for a component under phocol or lmc_exporter. The signature and fingerprint protect these claims and are not returned by the API. A process starts only if schema, signature, expiry, Gateway ID, and its replica ID all validate.

Every configured authentication principal must select exactly one product type that appears in entitlements. The Gateway rejects startup if an allowed_license_type is absent from the verified license. A license containing both product types does not make one principal eligible for both; configure separate principals as described in client authentication.

For renewal and replacement—including capacity reductions—follow license renewal.