Configuration

Taken from crates/nearglass-control-api (src/bin/nearglass-control-api.rs, deploy/), relay/ (the unit, the sysctl file, scope.example.json), crates/nearglass-ingest/src/cli.rs and the moq-relay-ietf --help of the relay package, on commit 79b96c7 of the SDK repository. The flag tables for the relay and the gateway are what the built binaries print.

On the managed service you configure none of this: you hold keys and call the control API. This page is for a deployment you run yourself. Command line flags for nearglass itself are in the CLI reference.

Every service runs as a systemd unit on a Linux host, with TLS ended in front of the control API (by tailscale serve or your own front). There are no containers.

The control APICopy Anchor Link

nearglass-control-api serve reads its settings from the environment. Under systemd that is an EnvironmentFile= named control-api.env under /etc, mode 600, owned by root. Hashes and file paths only: no key is ever written there. A bad value stops the service at start with a message that names the variable.

nearglass-control-api serve
nearglass-control-api keygen secret|ingest|publishable|operator|meter

keygen prints a new key once, and the SHA-256 line that the environment file takes. The service never sees a secret or ingest key in plain text.

Not every deployment installs this binary: the managed service runs it for you.

RequiredCopy Anchor Link

The service refuses to start without these.

Network and keysCopy Anchor Link

Tokens and relaysCopy Anchor Link

Without NEARGLASS_API_RELAY_ADMIN_URL the API logs a warning: a lost seat's open sessions then run until the relay's watch grace ends.

Addresses shown to customersCopy Anchor Link

Tenants and limitsCopy Anchor Link

A tenant's relay-scope max_sessions is twice its viewer cap plus 20.

Fleet and operator alertsCopy Anchor Link

NEARGLASS_API_OPERATOR_ALERT_URL (the URL itself, in the environment) is refused at start, so a secret is never in a process environment.

The unitCopy Anchor Link

crates/nearglass-control-api/deploy/nearglass-control-api.service runs the binary from /opt/nearglass-control-api/ as a dynamic user with no extra privileges, a read-only system, a private /tmp and no home. The signing key and the relay admin key are root-owned files that systemd hands to the service with LoadCredential, so the service reads them from $CREDENTIALS_DIRECTORY (/run/credentials/nearglass-control-api.service/). It restarts on failure after 2 s.

systemctl daemon-reload && systemctl enable --now nearglass-control-api

A minimal environment file for one tenant:

NEARGLASS_API_LISTEN=127.0.0.1:8790
NEARGLASS_API_STATE_FILE=/var/lib/nearglass-control-api/state.json
NEARGLASS_API_ISSUER_KEY_FILE=/run/credentials/nearglass-control-api.service/issuer.key.pem
NEARGLASS_API_SECRET_KEY_SHA256=<sha256 from keygen secret>
NEARGLASS_API_INGEST_KEY_SHA256=<sha256 from keygen ingest>
NEARGLASS_API_PUBLISHABLE_KEYS=<pk_ from keygen publishable>
NEARGLASS_API_RELAYS=https://relay.nearglass.com:443/
NEARGLASS_API_RELAY_ADMIN_URL=http://127.0.0.1:4480
NEARGLASS_API_RELAY_ADMIN_KEY_FILE=/run/credentials/nearglass-control-api.service/relay-admin.key
NEARGLASS_API_RTMP_URL=rtmp://ingest.nearglass.com:1935/live
NEARGLASS_API_SRT_URL=srt://ingest.nearglass.com:9000
NEARGLASS_API_WATCH_GRACE=600
NEARGLASS_API_TRUST_FORWARDED=1

The relayCopy Anchor Link

The relay is moq-relay-ietf with Nearglass's patches, installed by the nearglass-relay Debian package into /opt/nearglass-relay/moq-relay-ietf. The package installs, and does not start, these files:

Before it starts it needs /etc/nearglass-relay/cert.pem, key.pem and scope.json, then systemctl enable --now nearglass-relay. It needs inbound UDP on its port (QUIC and WebTransport). It reads only public keys: the signing key stays with the control API.

Relay flagsCopy Anchor Link

From moq-relay-ietf --help. Flags marked "Nearglass" are patches this package adds to the upstream relay.

The relay ignores SIGINT: stop it with SIGTERM.

Environment variables the relay also reads:

The relay unitCopy Anchor Link

/lib/systemd/system/nearglass-relay.service as the package installs it. Copy it to /etc/systemd/system/ to adjust the paths and the bind address.

[Service]
ExecStart=/opt/nearglass-relay/moq-relay-ietf \
  --bind 0.0.0.0:443 \
  --tls-cert /etc/nearglass-relay/cert.pem --tls-key /etc/nearglass-relay/key.pem \
  --scope-config /etc/nearglass-relay/scope.json \
  --coordinator-file /run/nearglass-relay/coordinator.json \
  --max-request-id 1000000 \
  --cache-idle-timeout 30 \
  --metrics-addr 127.0.0.1:9090
KillSignal=SIGTERM
Restart=on-failure
RestartSec=2
RuntimeDirectory=nearglass-relay
DynamicUser=yes
AmbientCapabilities=CAP_NET_BIND_SERVICE
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
PrivateTmp=yes
LimitNOFILE=65536

The unit does not set --admin-addr, --admin-key-file or --session-log. The control API needs the admin port to close lost seats' sessions, and metering needs the session log, so add them for a deployment with seat limits:

  --admin-addr 127.0.0.1:4480 --admin-key-file /etc/nearglass-relay/admin.key \
  --session-log /var/lib/nearglass-relay/sessions.jsonl

The relay runs as a dynamic user, so give it a state directory (StateDirectory=nearglass-relay) for the log, and let it read the key file through LoadCredential.

sysctlCopy Anchor Link

/etc/sysctl.d/90-nearglass-relay.conf (applied on the next boot, or with sysctl --system):

net.core.wmem_max = 8388608
net.core.rmem_max = 8388608

The relay asks for large UDP buffers. Without CAP_NET_ADMIN the kernel caps each request at these two limits, 212992 bytes on a stock Debian or Ubuntu kernel. The relay logs a warning at start when a request was capped, and a UDP socket bound line with the requested and granted sizes.

The scope fileCopy Anchor Link

--scope-config names a JSON file of token policies, one per scope. A scope is the URL path a client connects on: https://relay.nearglass.com/tn_abc is the scope /tn_abc. The default entry covers every scope without its own. Scopes in the file require a valid token; the file is re-read for new sessions, so an edit applies once a scope's cached policy expires (ttl_secs). If the file later goes missing or invalid, a scope keeps its cached policy until it expires, then refuses new sessions rather than admitting without a token.

{
  "default": {
    "auth": {
      "keys": [{ "kid": "nearglass-2026-10", "alg": "ES256", "pem_file": "issuer.pub.pem" }],
      "issuers": ["nearglass-token"],
      "audiences": ["nearglass-relay"],
      "clock_skew_secs": 60,
      "ttl_secs": 300
    }
  },
  "scopes": {
    "/tn_abc": { "auth": { "...": "same fields" } }
  }
}

When the control API writes this file (NEARGLASS_API_SCOPE_FILE), it takes the operator's NEARGLASS_API_SCOPE_BASE (the default scope and others, with inline pem keys only: a pem_file path would be relative to the wrong directory) and adds one scope per tenant, /tn_<id>, with the tenant's key and limits. A base must not name a /tn_ scope. With no base, the default scope refuses every token, so a path that is not a tenant's is closed.

The admin portCopy Anchor Link

With --admin-addr and --admin-key-file, loopback only. Every request carries the key as Authorization: Bearer <key>.

A wrong or missing key is 401.

The session logCopy Anchor Link

One JSON line per closed token session, with these fields: scope, token_id, sub, role, start_ms, end_ms, bytes_out, token_exp and close (closed, error, ended, admin or expired). Refused sessions leave no record. nearglass-meter ships it to the control API.

Relay metricsCopy Anchor Link

With --metrics-addr, at /metrics. Names from the source: moq_relay_seat_refused_total{reason} (scope_full, token_id_in_use, token_closed), moq_relay_seat_sessions, moq_relay_seat_admin_closed_total, moq_relay_seat_expired_total, moq_relay_seat_lapsed_total, moq_relay_admin_denied_total, moq_relay_setup_refused_total and moq_relay_clock_synchronized.

The ingest gatewayCopy Anchor Link

nearglass ingest (flags in the CLI reference) takes encoders over RTMP, RTMPS, SRT and WHIP. On a self-hosted deployment run it as a systemd unit beside the relay, with its keys from one of two places:

Give exactly one. With --control-api the gateway starts with the API's list, so the first encoder is not refused for want of a sync.

Ports are whatever you pass: the API only shows customers the addresses in NEARGLASS_API_RTMP_URL and NEARGLASS_API_SRT_URL, so keep those equal to the gateway's --rtmp and --srt. RTMPS and WHIP need a certificate (--rtmps-cert, --rtmps-key, or --whip-cert, --whip-key).

The ingest keys fileCopy Anchor Link

nearglass ingest keygen prints the key and one entry. A keys file is JSON with a streams list:

{ "streams": [
  { "name": "studio-a", "key_sha256": "<64 hex>", "namespace": "warp/ingest/studio-a",
    "protocols": ["rtmp", "rtmps", "srt", "whip"] }
] }

One publisher holds a key at a time. A second may take over after the first has been silent for 5 s, which is an encoder reconnecting after a drop.

EnvironmentCopy Anchor Link

The gateway reads RUST_LOG and TLS_DISABLE_VERIFY only. Everything else is a flag.