Install the appliance¶
The repository installer is the authoritative recovery and deployment path. It validates the selected profile, builds native and browser components, runs tests, installs static assets, and updates systemd units. It never imports host secrets from Git.
Synthetic example; explicit customization
example provides a Pi 5 hardware template with reserved network identity.
Customize serials, topology, RF routes and policy in a private copy. See
profile and identity setup.
Inspect first¶
Start by checking the synthetic profile in your checkout. Its USB topology, serials and RF paths will need to match your own wiring before installation.
Review the profile and live host configuration before replacing an existing
appliance. The live /etc/rtl_tcp/*.conf, /etc/rfsentry/routes.d/*.conf,
/etc/rfsentry/appliance.conf and unrelated api.conf policy are authoritative
when they differ from an old document. Compare the selected profile to installed
inventory, routes and health/USB policy. Upgrades preserve the installed files;
fresh installs require a reviewed private profile.
--check installs no appliance files, but enables the checkout's Git hooks.
The check uses the gateway’s inventory, route and spur validators. It can
compile them with gcc alone, or use a built or installed gateway. Correct
an invalid route before installing. If neither compiler nor validator is
available, --check reports incomplete coverage and exits with status 2.
The full installer checks again with the built gateway before stopping services.
Network access on first installation¶
Place the appliance on a trusted local network. The example below uses the default gateway ports and the first receiver in the synthetic profile. Verify your actual port assignments and restrict access from untrusted networks.
| Listener | Example | Who can connect and what controls access |
|---|---|---|
| Web UI and control | TCP 8443 | The gateway defaults to all IPv4 interfaces. HTTPS protects transport. Browser authentication defaults to disabled; configure account policy for shared networks. Machine credentials have separate grants. |
| Browser IQ stream | TCP 8444 | On the gateway listener address. A browser needs an allowed origin and the per-session IQ token obtained through control. |
| Raw RTL-TCP demand port | TCP 1234 for the first receiver | Listens on all IPv4 interfaces. A reachable RTL-TCP client can request the receiver. Restrict these ports to intended LAN clients with network/firewall policy; web authentication does not govern them. |
| Private RTL-TCP backend | TCP 11234 for that receiver | Loopback only (BIND=127.0.0.1). The demand manager owns this connection and starts the backend on demand. |
See appliance identity and browser accounts for the configured UI and streaming origins.
Build and install¶
For a new device, first prepare a private profile following
hardware profiles and upgrades, then copy/edit
the profile's .example into ignored
config/local/appliance.conf; see Appliance identity and TLS.
cd ~/rfsentry
./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
For an upgrade using the existing installed identity:
No .example identity is automatically consumed. The explicit identity wins
over the installed file; without it, installed identity wins over a deliberate
profile seed. A fresh install without any selected identity fails rather than
guessing. Normal upgrades preserve installed hardware/health settings, explicit API policy
and existing QoS choices. They still update software, service units and managed
integration files; see the preservation contract.
The installer checks required documentation sources and detectable operator-home destination errors before packages or service interruption. It stages convenience Markdown links against the complete built local site before stopping services. Filesystem races, later I/O faults and full live upgrade behavior still require normal operational safeguards; fixture tests are not a universal safety proof.
Choose a maintenance window before starting a full installation. The installer warns if it finds active SDR clients and proceeds even if they are still connected.
- While the existing services are running, the installer prepares dependencies, builds and checks the browser assets and local manual as needed, then tests the gateway and validates the selected configuration with the staged binary.
- It checks for active clients again, then stops the gateway, decoder and demand service. It installs the new binaries, static files and service units while acquisition is interrupted.
- On normal startup the demand service starts first, followed by the decoder
and gateway. Enabled continuous jobs resume and disabled jobs stay disabled.
Reconnect interactive clients and check jobs with
sudo rfsentry-jobctl list.
This is not a live hot-deploy. --no-start suppresses final startup but still
writes/enables files and can stop existing services; it is not a dry run or an
acquisition-safe workaround. --no-web-toolchain requires a complete matching
prebuilt dist, including documentation. See the
build/install boundaries.
The docs are static output. MkDocs is a build dependency, not a service on the
appliance. At runtime the existing rfsentry-api process serves both the
application and /docs/.
Installed paths¶
| Purpose | Path |
|---|---|
| Gateway | /usr/local/sbin/rfsentry-api |
| Gateway policy | /etc/rfsentry/api.conf |
| Public identity / TLS policy | /etc/rfsentry/appliance.conf |
| Receiver inventory | /etc/rtl_tcp/*.conf |
| Route policies | /etc/rfsentry/routes.d/*.conf |
| Detector exclusions | /etc/rfsentry/spurs.d/*.conf |
| Static app and docs | /usr/local/share/rfsentry-web/ |
| TLS private key | /etc/rfsentry/tls/server.key |
| Operator/job credential; optional browser authentication | /etc/rfsentry/auth.token |
The TLS key and token are host-only state. Never copy their content into a repository, issue, build log, or documentation page.
Verify¶
Open /healthz and /docs/ on the canonical configured HTTPS origin, using
the configured API port and normal certificate validation. In the preferred
off-grid private-ca mode, open the appliance's responsive /trust/ page and
install its public root once on each client. Verify the displayed SHA-256 value
against sudo rfsentry-config trust; do not bypass validation
or assume loopback is an authorized certificate name. UI/API/control uses the
API listener (8443 default), while the client discovers the dedicated WSS IQ
listener (8444 default). Neither number is a fixed requirement.
Open the canonical configured origin in a browser. Alternate fixed-IP and DNS origins may work, but browser storage is origin-scoped; use one canonical origin for durable FCC/FAA/product/archive state.
Offline behavior¶
The built docs contain the Material theme, search index, Mermaid renderer, icons, CSS, and JavaScript. They do not require a CDN. Basemap tiles or dataset updates may have their own separately documented network behavior, but opening and searching this documentation does not.