Gateway Licensing

Overview

LMC Exporter 0.19.x supports two licensing modes:

In Gateway mode, the exporter must receive the full requested entitlement before it creates the LMC shared-memory pool, starts workers, or opens the HTTP listener. license_file is not used in this mode.

Basic Configuration

This example uses one HTTPS Gateway with mutual TLS and two exporter targets:

license_mode = "gateway"
gateway_endpoints = ["https://gateway.example:8443"]
gateway_auth_mode = "mtls"
gateway_tls_ca_file = "/etc/lmc-exporter/gateway-ca.pem"
gateway_tls_cert_file = "/etc/lmc-exporter/client.pem"
gateway_tls_key_file = "/etc/lmc-exporter/client-key.pem"
gateway_state_directory = "/var/lib/lmc-exporter"

[[targets]]
app = "ads"
server_key = "82"
component_instance_id = "ads-primary"

[[targets]]
app = "adh"
server_key = "999"
component_instance_id = "adh-primary"

Gateway settings can appear at the TOML root or in [settings]. CLI options override TOML values. CLI names replace underscores with hyphens; for example, gateway_request_timeout_ms becomes --gateway-request-timeout-ms.

Gateway Settings

Supported authentication profiles are HTTP with none or bearer, and HTTPS with none or mtls. A bearer token must not be placed directly on the command line; configure the token file instead. Credential files are loaded at startup, so rotation requires a restart.

Component Identities and Entitlement Counts

Every selected target needs a component_instance_id in Gateway mode. This value identifies the licensed component and is separate from the target’s discovery instance selector.

Component IDs are case-sensitive, contain 1–128 ASCII characters, and must match [A-Za-z0-9][A-Za-z0-9._:-]{0,127}. Supported application names are adh, ads, ats, rtc, and rrcp_trans.

The exporter requests one unit for each distinct (app, component_instance_id) pair:

• Aliases that represent the same component can share an ID and count as one unit.
• Different component instances must use different IDs.
• Configured targets count even when their source is temporarily unavailable.
• The same ID used by different application types counts once for each application.

For a single global server_key, set component_instance_id. For multiple global keys, provide IDs in the same order:

app = "ads"
server_keys = ["82", "456"]
component_instance_ids = ["ads-primary", "ads-secondary"]

On the CLI, repeat --server-key and --component-instance-id in corresponding order. Embedded [[targets]] entries require their own component_instance_id; do not combine target-level IDs with the global ID settings.

RRCP Trans entitlement

Gateway licensing for app = "rrcp_trans" requires Keystone Gateway v0.2.1. Provision the matching rrcp_trans entitlement and assign a stable component_instance_id before restarting the exporter. Mixed workloads can contain all five application types.

Validate admission, renewal, and recovery with your Gateway before production rollout of RRCP Trans.

Persisted Installation Identity

gateway_state_directory stores a generated installation UUID in installation-id. The exporter reuses this identity after restarts so Gateway can reconcile the installation and its workload.

Prepare the directory as follows:

• Use an absolute path owned by the exporter service account.
• Set directory permissions to 0700.
• Place it on a local persistent filesystem that supports file locking, atomic publication, and fsync.
• Give each installation its own directory. Do not copy or share an installation identity between hosts.

The exporter creates installation-id with mode 0600 and holds installation-id.lock for its lifetime. A second process using the same state directory fails to start. Unsafe permissions, symlinks, malformed identity data, or storage and lock failures also block startup; the exporter does not replace an invalid identity automatically.

Lease and Shutdown Behavior

After acquisition, the exporter renews the lease in the background. Temporary renewal failures do not interrupt collection while the existing lease remains valid.

If the lease expires or Gateway establishes entitlement loss, the exporter permanently closes collection and output admission and exits with status 1. A later response cannot reopen the process. On a normal SIGINT or SIGTERM, the exporter stops output and attempts to release a valid lease within gateway_release_timeout_ms.

Gateway failover and retries preserve the logical request across configured endpoints. All endpoint URLs must use the same scheme. Gateway access remains an online requirement; the persisted installation ID is not an offline lease.

Security Guidance

• Bearer token and private-key files must be regular files owned by the service user or root, with no group or other permissions. Modes 0400 and 0600 are suitable.
• Use TLS 1.2 or later for HTTPS deployments.
• Configure gateway_tls_ca_file when the system trust store does not contain the deployment CA.
• Do not include credentials, query strings, or fragments in Gateway endpoint URLs.
• Restart the exporter after changing credentials, endpoints, targets, or entitlement quantities.