Merge pull request #27 from LobsterTrap/fix/podman-socket-error-message

fix(bootstrap): improve error message when Podman socket is not active

Author: maxamillion

crates/openshell-bootstrap/src/container_runtime.rs

@@ -228,7 +228,7 @@ fn current_uid() -> Option<u32> {
 }
 
 /// Check whether a binary is on PATH.
-fn has_binary(name: &str) -> bool {
+pub(crate) fn has_binary(name: &str) -> bool {
     std::process::Command::new(name)
         .arg("--version")
         .stdout(std::process::Stdio::null())

crates/openshell-bootstrap/src/docker.rs

@@ -315,11 +315,36 @@ fn runtime_not_reachable_error(
                 "No container runtime socket found and {} is not set.",
                 host_env
             ));
-            hints.push(format!(
-                "Install and start {}. See the support matrix \
-                 in the OpenShell docs for tested configurations.",
-                runtime.display_name()
-            ));
+            // Check if the binary is installed but the socket is missing —
+            // this typically means the systemd socket unit needs activation.
+            if crate::container_runtime::has_binary(runtime.binary_name()) {
+                match runtime {
+                    ContainerRuntime::Podman => {
+                        hints.push(
+                            "Podman is installed but its API socket is not active.\n\n  \
+                             Enable the Podman socket with:\n\n    \
+                             sudo systemctl enable --now podman.socket\n\n  \
+                             For rootless Podman, run as your regular user:\n\n    \
+                             systemctl --user enable --now podman.socket"
+                                .to_string(),
+                        );
+                    }
+                    ContainerRuntime::Docker => {
+                        hints.push(
+                            "Docker is installed but its daemon is not running.\n\n  \
+                             Start Docker with:\n\n    \
+                             sudo systemctl start docker"
+                                .to_string(),
+                        );
+                    }
+                }
+            } else {
+                hints.push(format!(
+                    "Install and start {}. See the support matrix \
+                     in the OpenShell docs for tested configurations.",
+                    runtime.display_name()
+                ));
+            }
         } else {
             // Found sockets for possibly a different runtime
             let socket_list: Vec<String> = alt_sockets
@@ -1508,6 +1533,43 @@ mod tests {
         );
     }
 
+    #[test]
+    fn runtime_not_reachable_error_podman_socket_hint() {
+        // Verify that the Podman error message always contains the
+        // verification hint regardless of system state. Branch-specific
+        // assertions (socket hints, env var hints, systemctl suggestions)
+        // are avoided because other tests in this module mutate env vars
+        // concurrently, making branch selection non-deterministic.
+        //
+        // The new "binary installed but no socket" hint path is validated
+        // by code inspection: `has_binary()` is called and the Podman
+        // branch emits "systemctl enable --now podman.socket".
+        let err = runtime_not_reachable_error(
+            ContainerRuntime::Podman,
+            "no Podman socket found at standard locations",
+            "Failed to connect to Podman",
+        );
+        let msg = format!("{err:?}");
+
+        assert!(
+            msg.contains("Failed to connect to Podman"),
+            "should include the summary: {msg}"
+        );
+        assert!(
+            msg.contains("no Podman socket found"),
+            "should include the raw error detail: {msg}"
+        );
+        assert!(
+            msg.contains("podman info"),
+            "should always suggest 'podman info' verification: {msg}"
+        );
+        // The message must never be empty or missing help text
+        assert!(
+            msg.contains("help:") || msg.contains("Verify"),
+            "should include actionable help text: {msg}"
+        );
+    }
+
     #[test]
     fn runtime_not_reachable_error_with_env_var() {
         // Simulate: DOCKER_HOST is set but daemon unresponsive.

docs/get-started/install-podman-linux.md

@@ -103,20 +103,6 @@ Podman 4.0 or later is required.
 
 Rootless Podman runs containers without root privileges. This is the default mode on Fedora and RHEL 9+ and the recommended configuration for desktops and laptops.
 
-### Enable the Podman Socket
-
-OpenShell communicates with Podman through a Unix socket. Enable the rootless socket for your user:
-
-```console
-$ systemctl --user enable --now podman.socket
-```
-
-Verify the socket exists:
-
-```console
-$ ls $XDG_RUNTIME_DIR/podman/podman.sock
-```
-
 ### Configure Cgroup Delegation
 
 OpenShell runs an embedded k3s cluster inside the gateway container. k3s needs to manage cgroup controllers for pod resource isolation. Without cgroup delegation, the gateway fails to start.
@@ -140,41 +126,41 @@ $ cat /sys/fs/cgroup/user.slice/user-$(id -u).slice/cgroup.subtree_control
 
 The output should include `cpuset cpu io memory pids`.
 
-### Enable Login Lingering (Headless Systems)
+### Headless Systems Prerequisites
 
 :::{note}
-**Headless/SSH systems only.** Skip this step on desktops and laptops where you log in directly. On those systems, your user session persists and systemd user services stay running.
+**Headless/SSH systems only.** If you log in directly at a desktop session, skip ahead to [Enable the Podman Socket](#enable-the-podman-socket). Desktop sessions handle login lingering, `XDG_RUNTIME_DIR`, and the D-Bus session bus automatically via PAM.
 :::
 
-On headless systems accessed only over SSH, systemd terminates all user services when the last SSH session disconnects. This kills the Podman socket and any running gateway container. Login lingering tells systemd to keep your user services alive regardless of active sessions:
+On headless systems (accessed only over SSH, or when switching users with `su`/`sudo su`), three things must be configured before `systemctl --user` will work. Complete these steps in order.
+
+**Enable login lingering.** Without lingering, systemd does not start a user session manager for your account. This means there is no D-Bus session bus, no user socket directory, and `systemctl --user` cannot function:
 
 ```console
-$ loginctl enable-linger $USER
+$ sudo loginctl enable-linger $USER
 ```
 
-Verify:
+Verify lingering is active:
 
 ```console
 $ loginctl show-user $USER --property=Linger
 Linger=yes
 ```
 
-### Verify XDG_RUNTIME_DIR (Headless Systems)
-
-:::{note}
-**Headless/SSH systems only.** Desktop sessions set `XDG_RUNTIME_DIR` automatically via PAM. This step is only needed if you access the system exclusively over SSH.
-:::
+Lingering also keeps your user services alive when all SSH sessions disconnect, which prevents the Podman socket and gateway container from being killed.
 
-Some SSH configurations do not set `XDG_RUNTIME_DIR`, which prevents the rootless Podman socket from being found. Check whether it is set:
+**Set XDG_RUNTIME_DIR and DBUS_SESSION_BUS_ADDRESS.** `systemctl --user` needs these two environment variables to find the user session bus. Direct SSH logins with PAM enabled set them automatically. If you access the system via `su -` or `sudo su`, they are not set. Check whether they exist:
 
 ```console
 $ echo $XDG_RUNTIME_DIR
+$ echo $DBUS_SESSION_BUS_ADDRESS
 ```
 
-If the output is empty, add the following to your `~/.bashrc` (or equivalent shell profile):
+If either is empty, add the following to `~/.bashrc` (or equivalent shell profile):
 
 ```bash
 export XDG_RUNTIME_DIR=/run/user/$(id -u)
+export DBUS_SESSION_BUS_ADDRESS=unix:path=$XDG_RUNTIME_DIR/bus
 ```
 
 Then reload:
@@ -183,6 +169,26 @@ Then reload:
 $ source ~/.bashrc
 ```
 
+:::{warning}
+`DBUS_SESSION_BUS_ADDRESS` references `$XDG_RUNTIME_DIR` in its value. You must set `XDG_RUNTIME_DIR` first. If you run `export DBUS_SESSION_BUS_ADDRESS=unix:path=$XDG_RUNTIME_DIR/bus` when `XDG_RUNTIME_DIR` is empty, the path expands to `unix:path=/bus`, which is invalid. Always source both exports together (e.g., `source ~/.bashrc`), or set `XDG_RUNTIME_DIR` on its own line before `DBUS_SESSION_BUS_ADDRESS`.
+
+Login lingering must also be enabled before these variables are useful. The bus socket at `$XDG_RUNTIME_DIR/bus` is only created when systemd starts the user session manager, which requires lingering.
+:::
+
+### Enable the Podman Socket
+
+OpenShell communicates with Podman through a Unix socket. Enable the rootless socket for your user:
+
+```console
+$ systemctl --user enable --now podman.socket
+```
+
+Verify the socket exists:
+
+```console
+$ ls $XDG_RUNTIME_DIR/podman/podman.sock
+```
+
 ### Verify Subuid and Subgid
 
 Rootless containers require subordinate UID and GID ranges for user namespace mapping. Most distributions configure these automatically when a user account is created. Verify your entries exist:
@@ -338,22 +344,94 @@ Common causes:
 
 ### Podman socket not found
 
-If OpenShell reports that no container runtime is available:
+If OpenShell reports "Podman is installed but its API socket is not active," the Podman binary is present but the systemd socket unit that exposes its API is not running. This is common on fresh installs where `dnf install podman` or `apt install podman` does not enable the socket automatically.
 
-For rootless mode, verify the socket is running:
+For rootful mode, enable the system socket:
 
 ```console
-$ systemctl --user status podman.socket
-$ ls $XDG_RUNTIME_DIR/podman/podman.sock
+$ sudo systemctl enable --now podman.socket
 ```
 
-For rootful mode, verify the system socket:
+For rootless mode, enable the user socket:
 
 ```console
-$ sudo systemctl status podman.socket
-$ ls /run/podman/podman.sock
+$ systemctl --user enable --now podman.socket
+```
+
+If this fails with `$DBUS_SESSION_BUS_ADDRESS and $XDG_RUNTIME_DIR not defined` or `No such file or directory`, see the [systemctl --user fails](#systemctl-user-fails-with-not-defined-or-no-such-file-or-directory) section below.
+
+Verify the socket is active:
+
+```console
+$ systemctl --user status podman.socket   # rootless
+$ sudo systemctl status podman.socket     # rootful
+```
+
+After enabling the socket, retry `openshell gateway start`.
+
+### systemctl --user fails with "not defined" or "No such file or directory"
+
+`systemctl --user` can fail with two related errors:
+
+**Error: variables not defined**
+
+```
+Failed to connect to user scope bus via local transport: $DBUS_SESSION_BUS_ADDRESS and $XDG_RUNTIME_DIR not defined
+```
+
+Neither environment variable is set. This happens when you switch users with `su -` or `sudo su`, or when your SSH server does not run PAM session modules.
+
+**Error: No such file or directory**
+
+```
+Failed to connect to user scope bus via local transport: No such file or directory
 ```
 
+The variables are set but the D-Bus bus socket they point to does not exist. There are two common causes:
+
+- **`XDG_RUNTIME_DIR` was empty when `DBUS_SESSION_BUS_ADDRESS` was set.** Because the `DBUS_SESSION_BUS_ADDRESS` export references `$XDG_RUNTIME_DIR`, running `export DBUS_SESSION_BUS_ADDRESS=unix:path=$XDG_RUNTIME_DIR/bus` when `XDG_RUNTIME_DIR` is empty produces `unix:path=/bus`, which does not exist. Check the current value:
+
+  ```console
+  $ echo $DBUS_SESSION_BUS_ADDRESS
+  ```
+
+  If it shows `unix:path=/bus` (missing the `/run/user/<uid>` prefix), this is the problem.
+
+- **Login lingering is not enabled.** Without lingering, systemd does not start a user session manager, so the bus socket at `/run/user/<uid>/bus` is never created.
+
+**Fix for both errors:**
+
+Run these three steps in order. Each step depends on the one before it:
+
+1. Enable login lingering. This starts the systemd user session manager, which creates the bus socket:
+
+   ```console
+   $ sudo loginctl enable-linger $USER
+   ```
+
+2. Set `XDG_RUNTIME_DIR` **first**, then `DBUS_SESSION_BUS_ADDRESS`. The second variable references the first, so the order matters:
+
+   ```console
+   $ export XDG_RUNTIME_DIR=/run/user/$(id -u)
+   $ export DBUS_SESSION_BUS_ADDRESS=unix:path=$XDG_RUNTIME_DIR/bus
+   ```
+
+   To make this permanent, add both lines (in this order) to `~/.bashrc` or equivalent.
+
+3. Verify and retry:
+
+   ```console
+   $ echo $DBUS_SESSION_BUS_ADDRESS
+   unix:path=/run/user/1000/bus
+   $ systemctl --user enable --now podman.socket
+   ```
+
+   The `echo` output should show the full path including `/run/user/<uid>`. If it shows `unix:path=/bus`, go back to step 2.
+
+:::{tip}
+If you SSH directly as the target user (rather than `su` from root), most distributions set these variables automatically via PAM. If you still see this error after a direct SSH login, check that `UsePAM yes` is set in `/etc/ssh/sshd_config`.
+:::
+
 ### Permission denied in rootless mode
 
 If you see permission errors when starting containers, verify your subuid/subgid configuration: