Files
2026-11-14 17:42:44 +01:00
..

Linux agent/helper bootstrap contract (not a VM acceptance)

Current integrated runtime contract: 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. 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):

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):

{
  "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):

{
  "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:

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.

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.