From f88dfa7620a289f1aff63e446ebdd31853ac3d51 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sat, 8 Aug 2026 04:55:52 -0500 Subject: docs: add the post-install checklist and podman/camera-udev notes The checklist is the standing home for manual post-first-boot steps: bluetooth pairing and the Proton Bridge login start it. The podman-socket and camera-udev notes carry the evidence for the filed install-time task, including why uaccess alone can't grant a raw USB node. --- .../2026-08-07-podman-socket-and-camera-udev.md | 70 ++++++++++++++++++++++ docs/post-install-checklist.org | 48 +++++++++++++++ 2 files changed, 118 insertions(+) create mode 100644 docs/design/2026-08-07-podman-socket-and-camera-udev.md create mode 100644 docs/post-install-checklist.org diff --git a/docs/design/2026-08-07-podman-socket-and-camera-udev.md b/docs/design/2026-08-07-podman-socket-and-camera-udev.md new file mode 100644 index 0000000..7eb99e8 --- /dev/null +++ b/docs/design/2026-08-07-podman-socket-and-camera-udev.md @@ -0,0 +1,70 @@ +# Enable podman.socket at install time (and one related USB rule) + +From winvm, 2026-08-07 on ratio. + +## 1. The ask: enable the rootless podman socket + + systemctl --user enable --now podman.socket + +**What was wrong.** On ratio this was `disabled` / `inactive`, and +`$XDG_RUNTIME_DIR/podman/podman.sock` did not exist at all. Podman's CLI does +not need it, so nothing surfaces the gap until something speaks the REST API. + +**Why it matters.** Every podman GUI and API client connects over that socket +rather than by shelling out. I installed Pods (`com.github.marhkb.Pods`, +flathub) to manage the Windows VM container, and without the socket it opens to +an empty window with no useful error — it looks like the app is broken or has no +containers, when in fact there is nothing listening. That is a bad first-run +experience and a hard one to diagnose from the symptom. + +It is socket-activated, so enabling it costs nothing while idle: podman starts +on demand when a client connects, and `enable` brings the socket back on login +without a daemon sitting resident. This is the ordinary way to run the podman +API rootless. + +**Verified after enabling:** socket present at +`/run/user/1000/podman/podman.sock`, the API answers +`/v5.0.0/libpod/containers/json`, and it reported the `WinVM` container. + +**One Flatpak note worth recording**, because it looks like a problem and is +not. The Pods flatpak ships `xdg-run/podman:ro` in its filesystem permissions, +which reads as though a client could not connect. Tested from inside the +sandbox: the socket is visible, and both readable *and writable*, so the +read-only directory mount does not block the connection. No `flatpak override` +is needed. + +**Client-side, not your problem but context:** Pods stores connections in +`~/.var/app/com.github.marhkb.Pods/config/pods/` and only writes that file after +the user adds a connection through the UI, so it can't be pre-seeded from an +install script without inventing the format. The one-time step is adding +`unix:///run/user/1000/podman/podman.sock` as a connection; a +`last-used-connection` gsetting makes it stick after that. So the *socket* is +the part worth automating, and the connection is not. + +## 2. Related, same category — a udev rule for USB camera passthrough + +Filing this alongside because it is the same class of one-time machine-level +setup and it will bite on velox the same way. Take it or leave it separately +from item 1. + +`/etc/udev/rules.d/99-usb-passthrough-cameras.rules`: + + SUBSYSTEM=="usb", ATTR{idVendor}=="3564", ATTR{idProduct}=="ff02", GROUP="video", MODE="0660", TAG+="uaccess" + SUBSYSTEM=="usb", ATTR{idVendor}=="046d", ATTR{idProduct}=="085e", GROUP="video", MODE="0660", TAG+="uaccess" + +(3564:ff02 is the OBSBOT, 046d:085e the Logitech BRIO.) + +**Why.** Streaming a USB camera into the VM runs `usbredirect`, which must open +the device read-write to claim it and detach the kernel drivers. The node +defaults to `crw-rw-r-- root:root`, so a normal user has read but no write and +the attach fails with a bare "Failed to open device!". + +**The part worth writing down:** `TAG+="uaccess"` alone is NOT enough, though it +looks like the right answer and `udevadm test` confirms the tag is applied. +logind does not turn that tag into an ACL on a raw `/dev/bus/usb/*` node — it +manages ACLs for a narrower set of seat devices. The `GROUP`/`MODE` grant is +what actually works. The tag is kept because it is harmless and correct in +principle; it just isn't sufficient. I lost time on that, so it is recorded +rather than left to be rediscovered. + +Both items are live on ratio and neither exists on velox. diff --git a/docs/post-install-checklist.org b/docs/post-install-checklist.org new file mode 100644 index 0000000..fa704b6 --- /dev/null +++ b/docs/post-install-checklist.org @@ -0,0 +1,48 @@ +#+TITLE: Post-Install Checklist +#+AUTHOR: Craig Jennings +#+DATE: 2026-08-08 + +* About + +Manual steps a fresh archsetup install cannot automate — things that are +inherently interactive (pairing, account logins) or that need judgment on the +specific machine. Work through this after first boot. When a new manual step +is discovered during a machine setup, add it here rather than leaving it in a +session note; the installer's outro already points at the Proton Bridge steps, +and this file is the home for the rest. + +Steps that CAN be automated don't belong here — file them as installer tasks +instead. The 2026-04-10 velox setup notes were triaged exactly that way: +microcode, radio state, and the ZFS /tmp mask went into the installer; +bluetooth pairing landed below. + +* Checklist + +** Pair bluetooth peripherals + +Pairing is inherently interactive (scan, pick the device, confirm), so it +can't ride the installer. For a mouse (e.g. the Logi M650): + +#+begin_src sh +bluetoothctl +# inside the prompt: +# scan on — wait for the device to appear +# pair +# trust — trust makes it auto-reconnect at boot +# connect +# scan off +#+end_src + +Trusted devices reconnect on their own after reboot; if one doesn't, check +=rfkill list= first (radios should be unblocked — TLP owns radio state and +enables bluetooth/wifi at startup per =/etc/tlp.d/01-custom.conf=). + +** Proton Mail Bridge (cmail) + +The installer's completion message carries the steps; recorded here too so +the checklist is complete: + +1. Clone claude-templates to =~/projects/claude-templates= if missing. +2. Run =protonmail-bridge --cli=, log in, then quit. +3. Run =~/code/archsetup/scripts/cmail-setup-finish.sh=. +4. First mail sync: =mbsync cmail && mu index=. -- cgit v1.2.3