54 lines
2.4 KiB
Markdown
54 lines
2.4 KiB
Markdown
# fleet-hostapi — workstation host-info agent
|
|
|
|
A tiny **read-only, loopback-only** Go HTTP service that runs on the diskless
|
|
workstation and reports facts about the machine the kiosk renders on. It is the
|
|
OS-side implementation of the contract in [`../../HOST-API.md`](../../HOST-API.md)
|
|
(authored alongside the kiosk-app SPA that consumes it).
|
|
|
|
```
|
|
GET http://localhost:9099/v1/host -> application/json (os, hardware, net, kiosk, agent)
|
|
GET http://localhost:9099/healthz -> 200 ok
|
|
```
|
|
|
|
## Properties (and why)
|
|
|
|
- **Loopback only.** Binds `127.0.0.1`; refuses to start on any routable address.
|
|
Host facts must never reach the boot LAN.
|
|
- **Read only.** No endpoint mutates anything; it reads `/proc`, `/sys`,
|
|
`/etc/os-release`, and the build-time facts file.
|
|
- **No per-host state baked in** (invariant #1). Host-specific fields (kernel,
|
|
hostname, IP, MAC, board, uptime) are read at **runtime**. The only baked facts
|
|
are image-generic — image version + weston/chromium versions — written to
|
|
`/etc/fleet-hostinfo.json` by the build provisioner.
|
|
- **Stdlib only → reproducible build** (the verity hash is a security property).
|
|
Built `CGO_ENABLED=0 -trimpath -buildvcs=false -ldflags=-buildid=`; identical
|
|
bytes across builds with the same Go toolchain.
|
|
- **CORS + Private Network Access.** The SPA is cross-origin and the fetch is a
|
|
Chromium private-network request, so responses carry
|
|
`Access-Control-Allow-Private-Network: true`. The matching browser-side
|
|
allowance is in `files/kiosk/chromium-kiosk-policy.json`
|
|
(`InsecurePrivateNetworkRequestsAllowedForUrls`, scoped to the kiosk origin).
|
|
|
|
## Build / install
|
|
|
|
Done by the `2b-hostapi` provisioner in `diskless.pkr.hcl`: installs the Go
|
|
toolchain, builds the static binary to `/usr/local/bin/fleet-hostapi`, writes the
|
|
facts file, installs + enables `fleet-hostapi.service`, and adds the binary to
|
|
fapolicyd trust (2c-STIG-postfix). The toolchain is removed in 2d hygiene — only
|
|
the static binary ships.
|
|
|
|
Local build:
|
|
|
|
```bash
|
|
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -buildvcs=false \
|
|
-ldflags '-s -w -buildid=' -o fleet-hostapi .
|
|
```
|
|
|
|
## Config (env, set in the unit)
|
|
|
|
| Var | Default | Notes |
|
|
|---|---|---|
|
|
| `FLEET_HOSTAPI_ADDR` | `127.0.0.1:9099` | must be loopback |
|
|
| `FLEET_HOSTAPI_ALLOW_ORIGIN` | `*` | tighten to the kiosk origin in prod |
|
|
| `FLEET_HOSTAPI_FACTS` | `/etc/fleet-hostinfo.json` | build-time facts |
|