# Linux agent/helper bootstrap contract (not a VM acceptance) **Current integrated runtime contract:** [runtime-README.md](runtime-README.md). The module-only blockers and integration steps below record the earlier increments; they are historical and superseded by that runtime document. In particular Sync, HTTPS, rotation and authenticated helper apply are now wired in source, not VM- accepted. Use the current document and installed units for new bootstrap work. Dedicated APT runner, exact config/unit/CLI/readiness/agent-routing preflight: [`apt-helper-README.md`](apt-helper-README.md). This newer profile does not weaken the existing general/readiness helper unit. Native VM measurements remain open. No install/start/reboot command in this document has been executed on the VM. No RustDesk component is installed. Deploy only the artifacts/configuration for the explicitly agreed test; do not copy central signing/TLS private keys. ## Built artifacts and process configuration Planned build command (the debug test/build commands actually executed are listed in `tests/agent_jobs/README.md`): ```sh cargo build --release -p rmm-agent -p rmm-privileged-helper ``` Both binaries are environment-configured, **not** positional-argument CLIs. Agent: `RMM_AGENT_STATE` (default `devstate/agent`), `RMM_CA_FILE` (default `devstate/pki/ca.pem`), `RMM_CONNECT_ADDR` (default `127.0.0.1:18443`), `RMM_ENROLLMENT_TOKEN_FILE` (first registration only), and optional `RMM_JOB_BINDING_FILE`, plus optional `RMM_HELPER_SOCKET` for explicit-root grants. The TCP override never changes the TLS DNS/SNI name `rmm-dev.internal`. No proxy or invalid-certificate bypass. Without a binding, the agent remains passive. It refuses to advertise/execute actions as UID 0. Provision a dedicated unprivileged `rmm-agent` system account/group. Install the agent binary root-owned and non-writable by that account at `/usr/local/libexec/rmm-agent`. State must be owned by that account, mode 0700; its files are 0600. The sample service uses systemd `StateDirectory` and no ambient capabilities. Install only the public CA at `/etc/rmm/ca.pem`. An optional root-owned 0600 `/etc/rmm/agent.env` supplies the first-enrollment token **path**, never an inline token. Remove that bootstrap token after registration. Retain the enrolled VM-generated private device key on the VM. The operator must provision the job signing key over the authenticated bootstrap channel: authenticated `GET https://rmm-dev.internal:18443/api/v1/job-signing-key` using the verified CA, checking `algorithm == "Ed25519"`, `schema_version == 1`, 32-byte `public_key_hex` and `key_id == SHA256(raw_public_key)`. Do not trust a key sent alongside a job, use an unauthenticated GET, put bearer credentials in command arguments, or substitute TLS/update keys. This increment does not rotate this trust anchor. Optional automatic agent fetching is described below; the helper remains independently provisioned. The authenticated operator/bootstrap must also resolve the enrolled agent's tenant, asset, generation and assignment from server records, not accept an offer as identity provisioning. Agent binding JSON, owned by `rmm-agent`, 0600, in a root-owned configuration directory (replace every placeholder; invalid placeholders intentionally fail): ```json { "tenant_id": "PROVISIONED-TENANT-UUID", "asset_id": "ENROLLED-ASSET-UUID", "agent_id": "ENROLLED-AGENT-UUID", "enrollment_generation": 1, "assignment_version": 1, "public_key_hex": "AUTHENTICATED-32-BYTE-KEY-IN-HEX" } ``` The agent additionally compares asset/agent IDs to its enrollment response. Generation/assignment changes require an authenticated re-provisioning procedure, not an in-band config assertion. State lock, integrity check and journal capacity errors fail closed; never delete journal/consumption files to force a retry. ## Independent helper boundary Helper: `RMM_HELPER_CONFIG`, default `/etc/rmm/helper.json`. It requires UID 0, a root-owned 0600 config, root-owned private 0700 state directory, and a root-owned socket parent not writable by group/others. `/run/rmm-helper` may be 0750 with group `rmm-agent`. The root-owned socket is 0660 with the configured group; `SO_PEERCRED` additionally requires **exactly** the configured non-root agent UID. Group membership alone grants no execution authority. Example `/etc/rmm/helper.json` (root:root, 0600): ```json { "binding": { "tenant_id": "PROVISIONED-TENANT-UUID", "asset_id": "ENROLLED-ASSET-UUID", "agent_id": "ENROLLED-AGENT-UUID", "enrollment_generation": 1, "assignment_version": 1, "public_key_hex": "AUTHENTICATED-32-BYTE-KEY-IN-HEX" }, "agent_uid": 12345, "socket_gid": 12345, "socket": "/run/rmm-helper/control.sock", "state": "/var/lib/rmm-helper", "allowed_services": ["rmm-acceptance.service"], "allow_reboot": false, "allow_root_scripts": false } ``` Use the actual dedicated account's numeric UID/GID, not the example numbers. The helper re-verifies exact Ed25519 bytes, all identity/hash/action/parameter bindings, a <=60-second grant interval, synchronized bounded host clock, explicit `execution_identity:"root"`, local action policy and its **own** SQLite consumption ledger before invoking the typed OS provider. A request-provided bearer, key or identity assertion is never an authority. The config has a separate, default-off root-script permission; enabling it is consciously broad administration, still subject to the sample service sandbox. Only exact allowed service units with running/stopped state and >=180s runtime are accepted; restart is not silently rewritten as start. Reboot is default-off and never yields exit-code success. IPC framing: one big-endian u32 length plus JSON `Request` (<=512 KiB) per Unix connection. Fields are `job_bytes`, `permit_bytes`, `signature` (JSON byte arrays), `plan_hash`, `authorization_id`. Response has the same framing and an `Outcome`. Read/write deadlines are 5s. No request errors/secrets are echoed. The server process is serial; unknown effects retain its global device resource lock, even after restart. Duplicate consumed grants return stored evidence/unknown, never execute again. A new grant for an already consumed attempt is also refused. The helper refuses a preexisting socket; systemd removes its RuntimeDirectory on stop. Manual stale-socket recovery requires checking that no helper is alive, not blindly unlinking a path at startup. ## Explicit integration/acceptance blockers * Backend currently permits only `agent_service`. Network agent intentionally advertises only `run_script` and `refresh_inventory`, not privileged actions. Network-agent → Unix-helper invocation is wired for explicit-root signed jobs when `RMM_HELPER_SOCKET` is configured, with root socket/peer authentication. A backend-authorized explicit root identity plus helper capability negotiation must land before service/reboot/root-script E2E tests. Helper policy denies unconfigured actions independently; the agent never relabels a service-identity grant into root authority. * Real APT mutation remains unsupported. A simulation followed by `apt-get` cannot guarantee exact approved resolution under dpkg fcntl locks or suppress arbitrary maintainer-script reboots. Neither `ensure_package` nor `apply_updates` is advertised. No false flock-on-dpkg-lock implementation. * No backend SyncRequest/Response exists. Only the **first** authenticated session of a journal may start effects. On reconnect/restart new effects are blocked; in-flight reservations become unknown, durable evidence still replays and heartbeats remain fresh. No DB deletion/new-grant shortcut. Existing previously connected state also needs real synchronization before jobs can be enabled. * Running-script cancellation is recorded but not claimed as confirmed abort; bounded execution finishes and reports its real result. A reboot does not complete without authenticated new-boot evidence; automatic reboot recovery synchronization is not implemented. * Extended collectors now map to bounded per-source observations inside the existing `linux.base` JSON, not new protobuf scopes/tags. Enable only after backend JSON-extension acceptance is confirmed, as described below. * No VM deployment, systemd install, root action, package/update/reboot host effects or real UI approval were performed by this increment. ## Additional environment variables and bootstrap (second increment) * `RMM_JOB_SIGNING_KEY_BOOTSTRAP=1`: after enrollment, use **device mTLS** to GET `/api/v1/job-signing-key` over verified TLS. DNS/SNI remains `rmm-dev.internal`; `RMM_CONNECT_ADDR` changes TCP only. Built-in roots, proxies and redirects are disabled. The response is bounded to 4096 bytes and Ed25519/schema/key-hash checked. No bearer is copied into the agent. A preconfigured binding key must match; an empty key allows initial authenticated provisioning. The resulting `RMM_AGENT_STATE/job-signing-key.json` is private and create-only. A changed existing pin **fails**, never silently rotates. Keep the bootstrap flag enabled on subsequent starts when the binding's key is empty, so the endpoint is reauthenticated and checked against the cached pin. If the current backend endpoint accepts bearer identity only, bootstrap fails closed; backend must explicitly authorize the authenticated enrolled device at that endpoint. * Helper config optional `"signing_key_file":"/etc/rmm/helper-signing-key.json"`: root-owned 0600 JSON with `key_id`, `algorithm`, `schema_version`, `public_key_hex` in the GET response shape. Provision via the trusted operator bootstrap, **not** from an agent-provided file/path/request. If an inline helper binding key is present it must match. The helper has no network key-fetch or auto-replacement operation; agent cache changes cannot change helper trust. * `RMM_LOG_UNITS_FILE`: private, agent-owned 0600 JSON array of 1–128 exact `.service` names. `query_logs` is advertised only when this allowlist and a native journald executable/runtime exist. The signed action must bind an allowlisted unit, nonnegative UTC window <=24h, <=1000 lines, >=20s runtime and bounded output. No arbitrary paths or caller-defined journal arguments. Access/JSON/output failures retain quality/error metadata. The current action has **no cursor input field**; no cursor is fabricated or advanced. Results explicitly report `cursor_status:not_advanced_no_ack_contract` and partial coverage until a concrete durable cursor-ACK contract exists. * `RMM_EXTENDED_INVENTORY=1`: opt-in additive snapshot JSON fields `observations`, `collection_started_at`, `collection_completed_at`. Every observation has `scope`, source, real RFC3339 observation time, quality, completeness, truncation, error and data. CPU, memory, OS, interfaces, routes, DNS, volumes, installed packages, local update metadata and DMI are mapped; SMART remains explicitly unsupported. Per-scope output is <=32 KiB and entire data <=512 KiB. **Do not enable against a gateway deserializing the old deny-unknown-fields Inventory struct.** Confirm backend storage accepts these additive JSON fields first. Default remains compatible base JSON; no wire/protocol file changed. Passive collection now runs in one bounded-inflight blocking worker with a bounded completion channel, not inside the network/heartbeat loop. A reconnect does not spawn a second collector while one is already running. A refresh job still collects a **new** base observation for its signed `linux.base` scope; it never returns an old stored passive snapshot as a live measurement. Awaiting-reboot evidence now persists before effect: original native boot ID, exact signed request, reservation time and reconnect deadline in each process's own `execution_evidence` ledger. Awaiting/unknown outcomes persist without unlocking the consumed attempt. Neither exit code nor a process restart supplies authenticated new-boot completion. Cancellation arriving while a permit is outstanding is checked before effect; running cancellation remains conservative. An earlier future-scheduled job no longer starves later ready jobs. ## Offline package installer (not executed on VM) `deploy/linux/install.py` is create-only. Planned invocation: ```sh python3 deploy/linux/install.py --root /PATH/TO/STAGING \ --agent-binary target/release/rmm-agent \ --helper-binary target/release/rmm-privileged-helper --ca-file /PATH/TO/PUBLIC-CA.pem ``` Staging writes only the x86-64 ELF artifacts, public CA and unit files. A live installation additionally requires root, `--root / --install-live` and an already provisioned unprivileged `rmm-agent` account. It refuses overwrites, writable or symlinked install directories, non-x86-64 artifacts and private-key CA inputs. It does **not** create accounts/config/identities/state, call systemctl, enable or start anything, install packages, change the network or reboot. Configure trust and enrollment first; systemd StateDirectory/RuntimeDirectory creates the correct runtime state when a later explicitly authorized bootstrap starts the units. The units retain empty agent capabilities, NoNewPrivileges, private temp, read-only system/home protection and no privileged-shell bypass. Privileged scripts are separately default-off and remain subject to the helper sandbox. ## Concrete backend contracts needed next ### APT bridge increment (not installed or VM-tested) The helper's typed APT bridge is implemented at `crates/privileged-helper/src/apt.rs`, through its existing SO_PEERCRED/signature/ parent-consumption boundary. Root config has optional `apt_provider`; default is disabled. The exact schema-2 signed manifest, additive domain action fields, compile-time-known create-only provider installation, pre-grant sealed archive/ baseline layout, context/ledger mapping and conservative outcome contract are documented in [`../../tools/apt-transaction/HELPER-CONTRACT.md`](../../tools/apt-transaction/HELPER-CONTRACT.md). This does not remove the package-capability blocker: the domain must preserve the complete typed `action.apt_manifest`, validate the narrow fixture closure, and support dedicated `apt_native_acceptance`; the agent remains unchanged. Legacy package/update actions without this field fail closed. No RunScript conversion, arbitrary archive URL or unsigned IPC manifest is accepted. Planned root-only `rmm-privileged-helper --install-apt-provider` installs only embedded reviewed provider/hook bytes and fixed metadata, create-only. It does not start services, create grants, install .deb packages or create acceptance. `provision-fixture-store` prepares only the pinned fixture artifacts before any final grant. Neither command was executed in this increment. The existing helper unit's ProtectSystem=strict/other protections are **not** an APT write/setup profile. A reviewed native fixture runner/unit configuration and actual VM tests are still required; no unit restriction was relaxed here. Do not advertise APT merely because the Rust bridge and local tests compile. Before removing `begin_session`'s fail-closed reconnect gate, agree a versioned authenticated SyncRequest/Response carrying device identity/assignment and connection generation, journal identity/checkpoint, fixed job/attempt, payload hash, grant ID/bytes or reservation ambiguity, local revision/state, original boot ID, persisted outcomes and concrete durable event receipts. Server must return an explicit reconciled/fenced decision, not a blanket `ok`. Unknown or missing old reservations must retain resource locks; no response may authorize a new attempt or silently manufacture a replacement grant. Restored/mismatched generations must stay blocked. Reboot success requires authenticated current envelope boot ID different from persisted original boot and bound postconditions. Long-poll must deliver the same typed envelopes and concrete ACKs with one active generation, including late evidence ingestion; no new endpoint/wire assumption is implemented here. Root planning must bind explicit root identity and local helper capabilities/policy, never reinterpret `agent_service`. The public key GET must authorize enrolled device mTLS. Additive inventory JSON acceptance must be confirmed before enabling extended collection in a real agent.