Document the accepted MVP and retire superseded development plans
Rust development slice / linux (push) Failing after 14s
Rust development slice / linux (push) Failing after 14s
This commit is contained in:
+18
-269
@@ -1,277 +1,26 @@
|
||||
# Linux agent/helper bootstrap contract (not a VM acceptance)
|
||||
# Linux-Agent betreiben
|
||||
|
||||
**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.
|
||||
Der Linux-Client für `x86_64-unknown-linux-gnu` meldet sich ausgehend per mTLS am Gerätegateway. Als Systembenutzer `rmm-discovery` liefert er Heartbeats und Inventar, holt genehmigte Shell-Skripte ab und meldet Ausgabe und Exitcode zurück. Der optionale Root-Helper gehört zur gleichen signierten Releaseversion wie der Agent.
|
||||
|
||||
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.
|
||||
## Installation
|
||||
|
||||
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.
|
||||
1. In der WebUI den Zielkunden wählen, **Gerät aufnehmen** öffnen und einen Einmalcode erzeugen.
|
||||
2. Auf dem x86-64-Linux-Gerät mit systemd und Python 3 den dort angezeigten Linux-Befehl ausführen. Er lädt `/install/linux.sh` über HTTPS und ruft es mit `sudo sh` und dem Bootstrap-Ursprung des Servers auf. Den Einmalcode am verdeckten Prompt eingeben.
|
||||
3. Für Root-Skripte die Administratoroption der WebUI wählen. Sie ergänzt `--enable-admin-scripts`. Auf einem bereits eingeschriebenen Gerät lässt sich der Installer mit demselben Ursprung und dieser Option erneut ausführen. Die Geräteidentität bleibt erhalten.
|
||||
4. Im Gerätedetail Hostname, Kunde, Agentversion und letzten authentisierten Kontakt kontrollieren. Für einen Root-Auftrag braucht das Gerät den gemeldeten Root-Kontext und eine passende zentrale Geräteregel. Ein MCP-Token benötigt zusätzlich die passenden Rechte für diesen Kunden. [MCP-Zugang](../../docs/public-access.md)
|
||||
|
||||
## Built artifacts and process configuration
|
||||
## Selbstupdate und Diagnose
|
||||
|
||||
Planned build command (the debug test/build commands actually executed are listed
|
||||
in `tests/agent_jobs/README.md`):
|
||||
`rmm-discovery-update.timer` ruft den Releasebestand nach dem Booten und anschließend alle fünf Minuten mit einer zufälligen Verzögerung von bis zu 20 Sekunden ab. Vor dem Wechsel prüft der Updater das signierte Paket und die Auftragsjournale. Eine neue Generation wird durch den frischen Kontakt des Agenten bestätigt. Scheitert die Aktivierung, wählt der Updater den Vorgänger. Ein über den Installer aktivierter Helper wechselt zusammen mit dem Agenten. [Installer und Aktualisierungslogik](../../crates/server/src/bootstrap/lifecycle.py)
|
||||
|
||||
```sh
|
||||
cargo build --release -p rmm-agent -p rmm-privileged-helper
|
||||
```
|
||||
| Am Gerät prüfen | Befehl oder Pfad |
|
||||
| --- | --- |
|
||||
| Agent und letzter Update-Lauf | `systemctl status rmm-discovery-agent.service rmm-discovery-update.timer` und `journalctl -u rmm-discovery-update.service -n 50` |
|
||||
| Installierter Root-Helper | `systemctl status rmm-discovery-managed-script-helper.service` |
|
||||
| Aktive Generation | `readlink -f /opt/rust-discovery-client/current` |
|
||||
| Zustand und Identität | `/var/lib/rmm-discovery` gehört dem Dienstkonto. Bei einem Binärwechsel bleiben Gerätedaten, Schlüssel und Journal erhalten. |
|
||||
| Tatsächlicher Neustart | `cat /proc/sys/kernel/random/boot_id` vor und nach dem Neustart vergleichen. Anschließend denselben Agenten am Gateway und das Ergebnis eines nachfolgenden Skripts prüfen. |
|
||||
|
||||
Both binaries are environment-configured, **not** positional-argument CLIs.
|
||||
Die Bibliotheksrevision „Linux neu starten“ kündigt den Neustart mit einer Minute Vorlauf an. Eine Datei unter `/tmp` kann beim Booten gemäß lokaler Systemkonfiguration verschwinden. Für die Beurteilung eines Auftrags zählt die Ausgabe seines konkreten Versuchs. [Native MCP-Abnahme](../../docs/evidence/mcp-scoped-script-requests-20261118.json)
|
||||
|
||||
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.
|
||||
Für einen neuen Release oder eine direkte Entwicklungsbereitstellung den gemeinsamen [Entwicklungsweg](../../docs/development.md) verwenden.
|
||||
|
||||
Reference in New Issue
Block a user