aboutsummaryrefslogtreecommitdiff
path: root/docs/design/2026-08-07-podman-socket-and-camera-udev.md
blob: 7eb99e8438b59a9a70dde73c7c4181428d1e81ba (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
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.