sunfish-admin
12d2179c20
Ship Magisk like GOLDEN; KernelSU optional recycle only; parallel to sunfish-a16-rom standby.
199 lines
10 KiB
Markdown
199 lines
10 KiB
Markdown
# 007 — KernelSU-Next on sunfish (LAB runbook)
|
||
|
||
**LAB only**: serial `11231JEC207477` — never GOLDEN `11071JEC203839`
|
||
**Host**: `rom-dev01` — artifacts `/srv/rom/artifacts/007-kernelsu/`, logs
|
||
`/srv/rom/logs/007-build/`
|
||
**Managed profile**: **Island** (current LAB/GOLDEN vehicle; historical
|
||
“Insular” docs are workflow reference only)
|
||
|
||
## Latest LAB results
|
||
|
||
**2026-09-16:** SusFS DEBUG bring-up **PASS** (matched vendor); banks still
|
||
**FAIL** (Talsec `-69` / root lock). Full write-up:
|
||
[`docs/007-lab-results-20260916.md`](007-lab-results-20260916.md).
|
||
|
||
## Hard-gates
|
||
|
||
| Gate | Rule |
|
||
|------|------|
|
||
| Yuh (`com.yuh`) | **PASS** usable session in Island on the tested stack |
|
||
| Swissquote (`com.swissquote.android`) | **PASS** usable session in Island on the **same** stack |
|
||
| Root | Banks **never** receive root; hide/umount **verified** (not toggle-only) |
|
||
| Magisk | Not production |
|
||
|
||
If either bank fails after SusFS/attestation experiments → **cancel root**
|
||
(Phase 9): keep incomplete / withdraw KSU; pivot to native `008`/`009` + optional
|
||
stock phone. Do **not** ship “root without both banks”.
|
||
|
||
## Sequencing (constitution 0.2.1)
|
||
|
||
- `006` rootless PASS gate is **deferred**.
|
||
- Before first rooted flash: **T039** rootless snapshot of *this* LAB ROM
|
||
(`pre-root/`). FAIL allowed; record facts.
|
||
- Then KSU → verified hide → SusFS → attestation → both-bank PASS.
|
||
- **Pins:** always refresh to newest compatible ReSukiSU/manager (non-shallow);
|
||
record tag + `KSU_VERSION` before `mka`. Never rebuild from a stale host copy.
|
||
|
||
## `002` KeyMint / Yuh evidence (index)
|
||
|
||
| Source | What | Path / doc |
|
||
|--------|------|------------|
|
||
| GOLDEN AXP+Magisk | Yuh FAIL — HA / “certificate invalid”; KeyMint `HARDWARE_TYPE_UNAVAILABLE` | `docs/002-golden-inventory.md` §Compatibility; host refs under `/srv/rom/references/axp/golden/…` when present |
|
||
| LAB iodé A16 (no Magisk, BL locked) | Same KeyMint/RKP class on Yuh open | `docs/002-lab-iodes-baseline.md`; host `…/lab/2026-09-13-iodes-baseline/yuh-…` |
|
||
| Contracts | Hide + both-bank gate | `specs/007-kernelsu-sunfish/contracts/` |
|
||
|
||
## Manager UI is **not** in the ROM zip
|
||
|
||
Kernel root (KSU-Next / ReSukiSU) does **not** ship a visible Settings tile.
|
||
After flash: install the matching **spoofed manager APK** (version ≤ kernel
|
||
`KSU_VERSION`), then modules (TEESimulator-RS / Zygisk / PIF, etc.). Same on
|
||
torukk’s MicroG zip — ResukiSU/KSU is kernel-only until the manager is installed
|
||
(see XDA #41; our pin: `.local-artifacts/007-kernelsu/ReSukiSU_*spoofed_*.apk`).
|
||
|
||
## Host policy
|
||
|
||
**All heavy work on `rom-dev01` only** (kernel clone, integrate, `mka`, image
|
||
staging). Laptop = thin client (adb/fastboot, Spec Kit, docs). Do not run kernel
|
||
builds or multi‑GB clones on the laptop.
|
||
|
||
**Long jobs must be detached on the host** — never leave `mka`/`ninja` on a
|
||
laptop SSH pipe (Wi‑Fi drops kill the build). Prefer **tmux** via
|
||
`/srv/rom/artifacts/bin/rom-detach` (falls back to screen / nohup):
|
||
|
||
```bash
|
||
/srv/rom/artifacts/bin/rom-detach 007-boot -- bash -lc \
|
||
'cd /srv/rom/src/lineage && source build/envsetup.sh && lunch lineage_sunfish-bp4a-userdebug && mka bootimage -j$(nproc)'
|
||
cat /srv/rom/artifacts/detach-007-boot.status
|
||
tmux ls # attach: tmux attach -t 007-boot
|
||
```
|
||
|
||
Agents: start detached, then only poll `detach-*.status` / logs with short SSH.
|
||
|
||
| Path on host | Role |
|
||
|--------------|------|
|
||
| `/srv/rom/src/lineage/kernel/google/msm-4.14` | Our LOS kernel (integrate here) |
|
||
| `/srv/rom/src/lineage/kernel/google/msm-4.14/KernelSU-Next` | setup.sh checkout @ `a54e4fa…` |
|
||
| `/srv/rom/references/kernelsu-next/` | KernelSU-Next `legacy` mirror (setup source) |
|
||
| `/srv/rom/references/abu-msm-4.14-ksu/` | abu-adm `ksu-susfs-23.0` **reference only** |
|
||
| `/srv/rom/artifacts/007-kernelsu/abu-reference/` | Owner-supplied abu `boot-abu.img` + `dtbo-abu.img` + SHA256 |
|
||
| `/srv/rom/artifacts/007-kernelsu/` | Our outs / evidence |
|
||
| `/srv/rom/logs/007-build/` | Build logs |
|
||
|
||
### Integration status (2026-09-16)
|
||
|
||
- **Production root fork for LAB:** **ReSukiSU** (symlink `drivers/kernelsu` →
|
||
`/srv/rom/references/resukisu/kernel`, full non-shallow clone). KernelSU-Next
|
||
remains historical learning only.
|
||
- Manual hooks (`CONFIG_KSU_MANUAL_HOOK`): `fs/open.c`, `fs/exec.c`, `fs/stat.c`,
|
||
`fs/read_write.c`, `drivers/input/input.c`, `kernel/sys.c` (`setresuid`),
|
||
`kernel/reboot.c`
|
||
- `sunfish_defconfig`: `CONFIG_KSU=y`, `CONFIG_KSU_MANUAL_HOOK=y`, all three
|
||
`AUTO_*` hooks **on** for 4.14, SusFS options as addon (not XOR). See
|
||
`docs/007-abu-vs-ours-susfs.md`.
|
||
- **Our boots (use these — not Downloads):**
|
||
|
||
| Role | Artifact |
|
||
|------|----------|
|
||
| Penúltimo (ReSukiSU, no SusFS) | `boot-resukisu-our-20260915T183729Z.img` / `boot-resukisu-our-latest.img` |
|
||
| Último (ReSukiSU + SusFS) | `boot-resukisu-susfs-20260916T004038Z.img` / `…-susfs-latest.img` (sha `455a77a6…`) |
|
||
|
||
- SusFS: **built** (API bridge 4.14 ↔ ReSukiSU ioctl). **Not claimed** on LAB —
|
||
trial only; US2 hide not finished before build. See
|
||
`docs/session-20260916-handoff.md`.
|
||
|
||
## Community / abu — **reference archive only**
|
||
|
||
Same problem space (sunfish + microG + hide + banks). **Not** our flash path.
|
||
Do not install abu/torukk ROMs or `~/Downloads/boot-sunfish-resukisu*.img` as
|
||
“our” kernel.
|
||
|
||
| Topic | Useful reference | Our action |
|
||
|-------|------------------|------------|
|
||
| Root fork | ReSukiSU for hard banks (XDA) | We already build **our** ReSukiSU boot |
|
||
| Attestation | TEESimulator-RS | Prefer over TrickyStore when modules resume |
|
||
| Modules | Zygisk Next + PIF inject | Documented exception if bank gate needs it |
|
||
| SusFS / kernel | abu `ksu-susfs` trees, `abu-reference/` imgs | Diff / port ideas only |
|
||
| Their full ROM | torukk 22.2 MicroG / abu A15 | **Ignore for day-to-day** — restore always = our 23.2 bacon |
|
||
|
||
Host refs: `/srv/rom/references/abu-msm-4.14-ksu/`,
|
||
`/srv/rom/artifacts/007-kernelsu/abu-reference/` (`boot-abu` / `dtbo-abu`).
|
||
|
||
```bash
|
||
# LAB — our penúltimo (preferred after ROM sideload)
|
||
# Always flash BOTH slots after a failed SusFS/bootloop trial — bootloader may
|
||
# mark the other slot unbootable and leave current-slot on the bad one.
|
||
fastboot flash boot_a .local-artifacts/007-kernelsu/boot-resukisu-our-20260915T183729Z.img
|
||
fastboot flash boot_b .local-artifacts/007-kernelsu/boot-resukisu-our-20260915T183729Z.img
|
||
fastboot --set-active=a # or the slot that last ran our 23.2 bacon successfully
|
||
fastboot reboot
|
||
# host: /srv/rom/artifacts/007-kernelsu/boot-resukisu-our-20260915T183729Z.img
|
||
|
||
# Emergency (no KSU): bacon stock boot
|
||
# fastboot flash boot_a|boot_b .local-artifacts/007-kernelsu/boot-005-known-good.img
|
||
```
|
||
|
||
**Slot lesson (2026-09-16):** SusFS bootloop left `current-slot:b` and
|
||
`slot-unbootable:a:yes`. Flashing only `boot` (→ active slot) could not revive
|
||
LAB; `boot-005` on **both** slots + `--set-active=a` recovered. Before any
|
||
kernel trial: `fastboot getvar current-slot` / `slot-unbootable:*`. After
|
||
failure: flash rollback to **boot_a and boot_b**, then set the known-good slot.
|
||
|
||
## Pin table (2026-09-16)
|
||
|
||
| Component | Revision | Status | Notes |
|
||
|-----------|----------|--------|-------|
|
||
| ReSukiSU | host `/srv/rom/references/resukisu` (non-shallow; match manager) | **active** | record tag + `KSU_VERSION` before each `mka` |
|
||
| KernelSU-Next | `a54e4fa…` (`legacy`) | archived | learning only |
|
||
| LOS sunfish kernel | `28f9290ae067…` + dirty SusFS/hooks | tree | `msm-4.14` |
|
||
| SusFS | bridged in-tree (trial) | **rebuild** | `T004038Z` hung (no MANUAL_HOOK); `T091211Z` logo-reboot (MANUAL+SUSFS but **AUTO_* hooks off**); next: AUTO_*=y + SusFS |
|
||
| Attestation stack | — | pending | TEESimulator-RS first candidate |
|
||
|
||
## Kernel inventory (T005)
|
||
|
||
| Item | Value |
|
||
|------|--------|
|
||
| Source | `/srv/rom/src/lineage/kernel/google/msm-4.14` |
|
||
| Device makefile | `device/google/sunfish/BoardConfigLineage.mk` → `TARGET_KERNEL_SOURCE := kernel/google/msm-4.14` |
|
||
| Defconfig | `arch/arm64/configs/sunfish_defconfig` |
|
||
| Boot image name | `Image.lz4` |
|
||
|
||
## KernelSU-Next choice (T006–T007) — amended by community 2026-08
|
||
|
||
**Earlier decision**: KernelSU-Next `legacy` + manual hooks for first in-tree POC.
|
||
|
||
**Amended (owner + torukk XDA 2026-08-22)**: For **hard-bank** detection
|
||
(Revolut-class; our gate is Yuh/Swissquote), community evidence favors
|
||
**ReSukiSU** + **TEESimulator-RS** (+ Zygisk Next + PIF inject) over Next+TrickyStore.
|
||
Keep Next work as learning / optional A/B; **do not** treat Next-only as the
|
||
banking solution if ResukiSU PoC is available.
|
||
|
||
**LAB PoC order (current, 2026-09-16):**
|
||
1. ~~Foreign ResukiSU / abu boots~~ — reference only; wrong for our A16 tree
|
||
2. **Done**: our ReSukiSU → `boot-resukisu-our-20260915T183729Z.img` (penúltimo)
|
||
3. **Done (build)**: SusFS trial → `boot-resukisu-susfs-20260916T004038Z.img` —
|
||
flash/claim **after** US2; prefer penúltimo on LAB until then
|
||
4. Manager + TEESimulator-RS ± Zygisk/PIF → bank gate
|
||
|
||
## Integration notes (T008)
|
||
|
||
Work on host tree; flash only our `boot-resukisu-our-*` / `boot-resukisu-susfs-*`
|
||
artifacts (never `~/Downloads/boot-sunfish-resukisu*`):
|
||
|
||
1. Wire ReSukiSU as **`drivers/kernelsu` → `/srv/rom/references/resukisu/kernel`** (full git clone lives *outside* the msm tree). Do **not** keep a `KernelSU/` directory inside `msm-4.14`: this tree’s `scripts/setlocalversion` walks nested `.git` dirs and appends `KernelSU-gHASH` into `uname -r` (easy bank detection).
|
||
2. Always use a **non-shallow** ReSukiSU clone so `KSU_VERSION = 30000 + rev-list + 700` matches the manager (≥35080). Shallow depth=1 produced bogus **30701**.
|
||
3. Enable `CONFIG_KSU=y` + `CONFIG_KSU_MANUAL_HOOK` (+ AUTO_* on 4.14).
|
||
4. Patch syscall hook sites per https://resukisu.org/guide/manual-integrate.html.
|
||
5. Build `mka bootimage`; verify `uname -r` has **no** `KernelSU` string before bank testing.
|
||
6. SusFS: built as trial; **do not claim** until US1–US2 green and T019 boots clean.
|
||
|
||
References: ReSukiSU manual integrate; abu/XDA only as SusFS/module oracle
|
||
(`docs/reference-sources.md` §8; `docs/session-20260916-handoff.md`).
|
||
|
||
## Rootless snapshot (T039)
|
||
|
||
See `/srv/rom/artifacts/007-kernelsu/pre-root/OUTCOMES.txt` and `preflight.txt`.
|
||
|
||
Recorded on `23.2-20260915-UNOFFICIAL-sunfish`: microG + Phonesky + spoof ON;
|
||
Island user 10 present; **no su**. Yuh/Swissquote **not installed** at snapshot
|
||
time (N/A outcomes). Reinstall via Aurora→Island before US5 banking gate.
|