diff --git a/docs/arje-boot.md b/docs/arje-boot.md index 2d3f301..3a9edb8 100644 --- a/docs/arje-boot.md +++ b/docs/arje-boot.md @@ -26,6 +26,9 @@ El initrd es un **CPIO + gzip** (formato `newc`, estándar Linux). Su raíz: /usr/sbin/ente-echo /usr/sbin/ente-policy-provider /usr/sbin/ente-*-compat 13 shims D-Bus (logind, hostnamed, …) +/usr/bin/brahman-status CLI: snapshot del broker (sesiones + matches) +/usr/bin/busctl CLI: bus interno (list-entes, announce, …) +/usr/bin/brainctl CLI: cerebro (rules, entropy, crystals) /ente/seed.card.json Tarjeta Semilla canónica /bin/{sh,ls,mount,…} busybox-static /etc, /dev, /proc, /sys, /run mountpoints vacíos @@ -301,15 +304,63 @@ echo 'export RUST_LOG="trace"' >> wrapper ### 6b. Sockets de introspección (Unix, dentro del initrd) -| socket | servicio | -| ---------------------------- | ------------------------------------------------- | -| `/run/ente-bus.sock` | bus interno (postcard, `BusRequest::Invoke/...`) | -| `/run/brahman-init.sock` | handshake brahman | -| `/run/brahman-admin.sock` | snapshots de sesiones + matches | -| `/run/ente-brain.sock` | introspección del cerebro | +Sin `XDG_RUNTIME_DIR` ni `TMPDIR` en el env de PID 1 (caso del initrd), +los sockets caen al fallback `/tmp/`: -Conectar desde un Ente hijo: `socat - UNIX-CONNECT:/run/brahman-admin.sock`. -(El initrd debe tener `socat` o equivalente; agregalo con `EXTRA_BINS`.) +| socket | env override | servicio | +| ---------------------------- | ----------------------- | ----------------------------------------- | +| `/tmp/ente-bus-*.sock` | `ENTE_BUS_SOCK` | bus interno (Announce/Invoke/ListEntes) | +| `/tmp/brahman-init.sock` | `BRAHMAN_INIT_SOCKET` | handshake brahman | +| `/tmp/brahman-admin.sock` | `BRAHMAN_ADMIN_SOCKET` | snapshots de sesiones + matches | +| `/tmp/ente-brain.sock` | `ENTE_BRAIN_SOCK` | introspección del cerebro (rules, observer) | + +El initrd trae 3 CLI clients precompilados en `/usr/bin/`: + +```sh +brahman-status # snapshot completo: sesiones + matches + WIT + flows +busctl list-entes # entes anunciados en el bus +busctl announce # smoke test: anuncia una Card desde el shell +busctl power-off # apaga el fractal +brainctl list-rules # reglas crystallizadas + manuales +brainctl entropy # entropía del observer estadístico +brainctl top 10 # top-10 kinds por frecuencia +brainctl crystals # patrones detectados con auto-promote +brainctl crystal-json 0 # exporta un crystal específico como Rule JSON +``` + +Ejemplo de sesión típica dentro de la VM: + +```sh +arje# brahman-status +Init: server=0.1.0 protocol=0.1.0 attached=true +Context: (sin set) + +Sessions (3): + [ente] 01HQ5R2K… compat-logind lifecycle=Daemon priority=High + [ente] 01HQ5R2K… compat-hostnamed lifecycle=Daemon priority=Normal + [ente] 01HQ5R2K… echo-smoke lifecycle=Daemon priority=Low + +Matches (0): + (ninguno) + +arje# busctl list-entes +14 entes en el bus: + 01HQ… compat-logind provides=[LegacyLogind] + 01HQ… compat-journald provides=[Journal] + … + +arje# brainctl top 5 +spawn 14 +ente_died 0 +… +``` + +Si en cambio querés conectar crudo con `socat`/`nc`, agregalo con +`EXTRA_BINS=/usr/bin/socat-static scripts/build-arje-initrd.sh` y luego: + +```sh +arje# socat - UNIX-CONNECT:/tmp/brahman-admin.sock | jq . +``` ### 6c. Snapshot / restore diff --git a/scripts/build-arje-initrd.sh b/scripts/build-arje-initrd.sh index 350a7e7..e0cb350 100755 --- a/scripts/build-arje-initrd.sh +++ b/scripts/build-arje-initrd.sh @@ -110,7 +110,16 @@ cargo build --release --target "$TARGET" \ -p ente-binfmt-compat \ -p ente-policy-provider +# 1b. Build de las CLI de administración. Son `[[example]]` de sus crates +# respectivos — un solo binario cada una, sin estado propio. +echo "[build-initrd] cargo build --release --target $TARGET de CLIs admin" +cargo build --release --target "$TARGET" \ + --example brahman-status -p brahman-admin \ + --example busctl -p ente-bus \ + --example brainctl -p ente-brain + BIN_DIR="target/$TARGET/release" +EX_DIR="target/$TARGET/release/examples" # 2. Validar la seed. validate.sh corre el binario del host (release plain), # sólo verifica el schema — independiente del target. @@ -140,7 +149,7 @@ fi # 4. Stage root del initrd. STAGE="$(mktemp -d -t arje-initrd.XXXXXX)" trap 'rm -rf "$STAGE"' EXIT -mkdir -p "$STAGE"/{bin,sbin,usr/sbin,etc,ente,proc,sys,dev,run,tmp,sys/fs/cgroup} +mkdir -p "$STAGE"/{bin,sbin,usr/bin,usr/sbin,etc,ente,proc,sys,dev,run,tmp,sys/fs/cgroup} # 5. Copiar binarios arje. install -m 0755 "$BIN_DIR/ente-zero" "$STAGE/sbin/ente-zero" @@ -153,6 +162,11 @@ for b in ente-echo ente-policy-provider \ install -m 0755 "$BIN_DIR/$b" "$STAGE/usr/sbin/$b" done +# 5b. CLIs de administración → /usr/bin (no /usr/sbin: no son services). +for e in brahman-status busctl brainctl; do + install -m 0755 "$EX_DIR/$e" "$STAGE/usr/bin/$e" +done + # 6. Userspace mínimo. Con binarios musl-static no necesitamos vendorear # libc/ld-linux. Las dos rutas: # (a) busybox-static apuntado por $BUSYBOX_BIN → 1 binario, todo simlink.