Skip to content

Appliance identity and certificates

/etc/rfsentry/appliance.conf is the authority for public hostnames, addresses, API/stream ports, and TLS policy. It contains no credentials. Identity fields in api.conf are generated outputs, not a second authority. Receiver inventory, routes, authentication, network settings, and QoS profiles retain their own files.

Installed configuration and services

Purpose Installed authority or asset
Public identity, origins, ports, TLS policy /etc/rfsentry/appliance.conf
Gateway settings / generated identity fields /etc/rfsentry/api.conf
Receiver inventory /etc/rtl_tcp/*.conf
RF route policy /etc/rfsentry/routes.d/*.conf
Detector exclusions /etc/rfsentry/spurs.d/*.conf
Demand deadlines / USB domains / accessories /etc/sdr-demand.conf, /etc/sdr-demand/
IQ priority policy /etc/rfsentry/qos.conf
Gateway executable / systemd service /usr/local/sbin/rfsentry-api, rfsentry-api.service
Static app and documentation /usr/local/share/rfsentry-web/, including docs/
Machine auth token / TLS credentials /etc/rfsentry/auth.token, /etc/rfsentry/tls/

Inspect installed configuration before replacing it. Keep deployed command and service names stable unless an explicit migration is approved. Tokens, private keys, credentials, client recordings, and session state must not enter Git, logs, or documentation. Check permissions without printing secret contents.

Identity examples are deliberately confined to profiles. Runtime defaults, documentation links, workstation launchers, and debug tools must not compile a particular appliance hostname, IP address, or SSH account into their behavior.

First installation or replacement hardware

Synthetic example; operator customization required

profiles/example contains a synthetic Pi 5 hardware and network example. Customize a private copy for actual serials, topology, RF routes and policy. Store real identity privately. The default example selector is not hardware detection; fresh installs require a reviewed private --profile-dir.

Prepare a private hardware profile first as described in hardware profiles and upgrades. Copy the selected profile's etc/rfsentry/appliance.conf.example into ignored config/local/appliance.conf and edit it for the actual device. An example is not automatically used. Receiver serials may be unchanged while USB paths and model-specific firmware policy differ. Check topology rather than blindly reusing the old profile. A minimal synthetic identity example:

PUBLIC_HOST=radio.example
PUBLIC_ALIASES=192.0.2.10,2001:db8::10
API_PORT=8443
STREAM_PORT=8444
TLS_MODE=private-ca
PKI_DIRECTORY=/etc/rfsentry/pki
PKI_ALLOWED_DNS_SUFFIXES=radio.example
PKI_ALLOWED_IP_RANGES=192.0.2.0/24
DISCOVERY_ENABLED=yes
DISCOVERY_INTERFACES=

These reserved names/IPs are placeholders, not live endpoints. Aliases are comma-separated DNS names or IPv4/IPv6 addresses, not URLs. Loopback aliases must be explicitly listed if wanted. Both listeners use the same TLS identity. No discovered interface address is automatically authorized. This file does not change the OS hostname, DNS, DHCP, or NetworkManager.

Discovery uses a C++ Avahi/DNS-SD advertisement on permitted appliance interfaces; an empty interface list means all, or use comma-separated names such as eth0. DISCOVERY_ENABLED=no removes only rfSentry's advertisement, never unrelated Avahi publishers. The installer provisions the shared daemon when enabled, but does not unmask administrator policy. Advertisements carry public UUID, canonical HTTPS origin and pairing version, never secrets, and do not wake a receiver. The Server discovers on its own local link; multicast may be blocked, so manual canonical HTTPS entry remains available. Long origins exceeding TXT bounds are reported for manual entry rather than truncated.

# Check the same reviewed private inputs you will install.
./install.sh --check --profile-dir config/local/hardware-profile --appliance-config config/local/appliance.conf
sudo ./install.sh --install --profile-dir config/local/hardware-profile --appliance-config config/local/appliance.conf

An explicit identity file takes precedence over /etc/rfsentry/appliance.conf. On a fresh installation you can also provide the identity inside your private profile at etc/rfsentry/appliance.conf. Without identity, --check checks the hardware profile; installation fails with instructions rather than guessing. Old api.conf identity is not silently imported. Upgrades preserve installed identity and unrelated API policy.

Hardware upgrades validate and preserve installed inventory, routes, USB, health and firmware policy. Fresh installation requires a reviewed private --profile-dir; see hardware profiles. --check does not install appliance files, but does enable the repository's Git hooks.

Inspect and change

rfsentry-config show
sudoedit /etc/rfsentry/appliance.conf
sudo rfsentry-config apply
sudo rfsentry-config trust

The helper stages/validates settings and TLS before publication, replaces only derived API fields, and creates one .rfsentry.bak per replaced file. Files use same-directory atomic replacements; ordinary publication failures roll back. Identical runs reuse valid certificates and do not rewrite unchanged files. No daemon or automatic service restart is introduced.

When safe to disconnect browser sessions, activate changes:

sudo systemctl restart rfsentry-api.service
sudo systemctl reload rfsentry-qos.service

Restarting the gateway to activate identity, port or TLS changes interrupts acquisition. A full install also proceeds after warning about connected clients. For a QoS profile change alone, use the live QoS procedure.

Changing a browser hostname or API port changes its OPFS/IndexedDB origin; history remains at the old origin, not automatically migrated. Replacement self-signed certificates may require renewed client trust. Removed aliases are removed from allowed origins and managed certificate SANs.

TLS modes

  • private-ca: the preferred off-grid mode. Create one appliance-local root trust anchor, a constrained issuing intermediate and a proper server leaf. The appliance and paired Servers share this root without sharing their leaf private keys. Ordinary upgrades and renewals preserve the root.
  • self-signed: create exact configured SANs; renew for changed names or fewer than 30 days remaining. Reuse the private key where possible. Never overwrite a CA-issued certificate.
  • provided: validate the existing certificate/key, SAN coverage, and remaining validity; do not generate or overwrite it.

Optional TLS_CERTIFICATE / TLS_PRIVATE_KEY specify absolute paths, defaulting to /etc/rfsentry/tls/server.crt / server.key. Supplied files must be readable by the unprivileged gateway. Keys and tokens remain host-only, never in profiles, logs, exports, or Git. Clients never bypass TLS validation.

Local rfsentry-jobctl and rfsentry-record-client commands use the generated PKI_ROOT_CERTIFICATE when PKI_APPLIANCE_TRUST_ACTIVE=yes. This trust is explicit; installing the root in the appliance's global OS trust store is not required. Legacy TLS modes retain their existing TLS_CERTIFICATE trust path. A missing root fails closed and identifies the unreadable public trust file.

The v0.6.9-phase7-q2 clients still selected the leaf/issuer bundle and can fail with unable to get issuer certificate after switching to private-CA mode. Upgrade both appliance CLI binaries to the corrected source; do not change the real TLS_CERTIFICATE setting to the root, which would break gateway HTTPS.

Appliance-owned private trust

Fresh private-ca provisioning creates a 20-year root, a 10-year issuing intermediate and a one-year appliance HTTPS leaf. The issuer rotates beneath the same root when its policy changes or one year remains. Clients therefore install only the root and do not repeat manual trust for ordinary leaf or issuer renewal. X.509 path length and name constraints limit the issuer to the appliance identities plus the explicitly configured DNS suffixes/private IP ranges. Do not configure a suffix or CIDR broader than the Server identities this appliance should be allowed to certify.

Every configured Server administration alias participates in enrollment. For example, a suffix of example.net permits archive.example.net, but not the short alias archive. The Server shows the requested certificate names before connecting and reports the rejected name and relevant allowed policy. Review the Server's administration names or the appliance's explicit issuance policy; enrollment never silently removes an alias or broadens CA authority. Policy/CSR/signing failures appear with safe error codes in the issuer journal and authenticated pairing response, without private key or credential output.

The root key is mode 0600 and root-only. The socket-activated rfsentry-pki-issuer account can read only the constrained intermediate key; it has no network access. The gateway can submit bounded CSRs through the local Unix socket but cannot read either signing key. Issued appliance/Server leaves are CA:FALSE with serverAuth. CSR extensions are never copied blindly.

rfsentry-pki-renew.timer checks the appliance leaf twice daily with jitter. Renewal is local and requires no Internet service. Successful publication sends SIGHUP to the gateway; libwebsockets replaces the TLS contexts used for new connections while established receiver/control sessions remain intact.

Install trust on a client

Open /trust/ at the canonical appliance origin. This intentionally compact, responsive page detects Android, iPhone/iPad, macOS, Windows or Linux and puts that platform's exact steps first. It provides:

  • DER .crt for Android and Windows;
  • an Apple .mobileconfig containing only the public root;
  • PEM for macOS/Linux and advanced use;
  • the complete SHA-256 fingerprint and a desktop QR handoff to a phone.

An upgraded installation that still selects self-signed or provided can publish the root for paired Servers, but the page labels that its appliance leaf is still legacy/provided. Change deliberately to TLS_MODE=private-ca, apply and reload before expecting that root to validate the appliance itself.

Before granting trust, compare the page fingerprint with the out-of-band result:

sudo rfsentry-config trust

The browser cannot silently add a trust anchor. Android requires its certificate installer/device PIN. iPhone/iPad requires installing the downloaded profile and then enabling the root under Certificate Trust Settings. Afterward, fully restart the browser, confirm the certificate warning is gone, and use Install rfSentry or the platform's Add to Home Screen action. Only public material is served. No private key, backup or signing operation is available through HTTP. Chrome's integrated Android WebAPK may contact its platform minting service; when that is unavailable off-grid, Create shortcut remains the local fallback.

Backup and recovery

Back up the trust domain explicitly to operator-controlled storage:

sudo rfsentry-config backup-pki \
  --backup-file /mounted/backup/rfsentry-pki.enc

The command requires a passphrase (or a root-only --passphrase-file) and writes an AES-256-CBC/PBKDF2 encrypted, mode-0600 archive with a root-signed content manifest. Restore verifies that signature and every file hash. It contains private keys; handle it accordingly and never put it in the repository. Restore is deliberately explicit:

sudo rfsentry-config restore-pki \
  --backup-file /mounted/backup/rfsentry-pki.enc --yes
sudo rfsentry-config apply
sudo systemctl reload rfsentry-api.service

A backup with a different root is refused unless --replace-root --yes is also given. Replacing the root requires every client to trust the replacement first; it is not routine recovery. Restore preserves one .rfsentry.bak copy of each replaced PKI file and never retrieves keys through the browser.

Browser accounts and source access

The configured no-auth mode is immediately usable, including discovery, existing job inventory and record delivery. It is labeled Local access · authentication disabled, without claiming a verified person. Protected browser operation uses rfSentry-managed local accounts through Account & access, with normal username/password sign-in, role enforcement, logout and expiry recovery. Linux and SSH accounts remain separate. Existing machine credentials retain their own independent permissions.

See Browser record sources for account policy persistence, Server discovery/trust onboarding, automatic scoped readers and the compact GOES source controls. Server authentication remains independent of appliance authentication; discovery alone authorizes neither endpoint.

Workstation and support tools

The workstation client guide covers URL bootstrap, saved preferences, Standard/Workstation modes, profiles and uninstall. There is no compiled appliance URL or SSH account. A workstation needs an initial URL or local public identity file; it cannot read the Pi's /etc before connecting. Doctor reports TLS-verified canonical metadata or an explicit unverified result, never a guessed host or silent redirect.

Browser support covers the separate reusable/disposable debug profiles, operator-controlled SSH tunnel, central-config versus explicit CDP origin selection, and destructive cache cleanup. Both DevTools endpoints remain loopback-only. Selecting an installer/debug URL does not add certificate names or gateway allowed origins; those still belong to this identity file.

Repository hygiene and recovery

Installation writes identity/TLS outside the checkout. config/local/ is ignored. Public recovery examples may be deliberately checked in under profiles/. Tests/docs use reserved synthetic identities. Static /docs/ links are portable, not built against a device hostname.

To roll back, restore a reviewed identity backup, rerun apply, and activate when safe. Certificate trust may also need restoring; protect TLS backups. Failed staging leaves the running configuration untouched. Atomic replacement is not a multi-file power-loss transaction: rerun apply after an interrupted publication before restarting the gateway.