Skip to content

Add docs for running rootless Podman as a non-root user #50

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
poupryc wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add docs for running rootless Podman as a non-root user #50

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 51 additions & 1 deletion readme-vars.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ full_custom_readme: |

## Application Setup

This container is conceptually based on [https://github.com/Tecnativa/docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy) and as such does not follow our usual container conventions. It *does not* support mods or custom scripts/services, or running as a user other than root (or the docker user in a rootless environment). It is designed to act as a drop-in replacement for the Tecnativa container.
This container is conceptually based on [https://github.com/Tecnativa/docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy) and as such does not follow our usual container conventions. It *does not* support mods or custom scripts/services. It is designed to act as a drop-in replacement for the Tecnativa container.

The container should be run on the same docker network as the service(s) using it. Most containers that would normally connect to a mounted docker.sock can have their endpoint overridden using the `DOCKER_HOST` environment variable if they do not offer the option in their configuration; it should typically be pointed to `tcp://socket-proxy:2375`.

Expand All @@ -87,6 +87,56 @@ full_custom_readme: |

Point the exporter at `tcp://socket-proxy:2375` using `CONTAINER_HOST`. `LIBPOD_PING` and `LIBPOD_VERSION` are enabled by default (like their Docker-compat counterparts `PING` and `VERSION`).

### Rootless Podman as a non-root user

Under rootless Podman the container process runs as `root` *inside its user namespace* by default. You can go a step further and drop root inside the container as well, running the proxy as an unprivileged user such as `nobody` (UID/GID `65534`). Two things need to be handled for this to work:

* **Socket ownership.** The rootless Podman socket (`$XDG_RUNTIME_DIR/podman/podman.sock`) is owned by your host user. That user maps to `root` inside the container's namespace, so a non-root user in the container cannot read it. Use `--userns=keep-id:uid=65534,gid=65534` to map your host user onto UID/GID `65534` inside the container, so `nobody` owns the socket and can proxy it.
* **A writable `/run`.** The entrypoint renders the HAProxy config into `/run/haproxy` at startup, so `/run` must be writable by the non-root user. Mount it as a tmpfs with `mode=1777` (this also satisfies read-only operation).

Example `podman run`:

```bash
podman run -d \
--name=socket-proxy \
--user 65534:65534 \
--userns=keep-id:uid=65534,gid=65534 \
-e CONTAINERS=1 `#optional` \
-e LIBPOD_CONTAINERS=1 `#optional` \
-e POST=0 `#optional` \
-v $XDG_RUNTIME_DIR/podman/podman.sock:/var/run/docker.sock:ro \
-p 2375:2375 \
--read-only \
--tmpfs /run:rw,mode=1777 \
--restart unless-stopped \
lscr.io/linuxserver/socket-proxy:latest
```

Or as a rootless [Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html) unit (`~/.config/containers/systemd/socket-proxy.container`), started with `systemctl --user daemon-reload && systemctl --user start socket-proxy`:

```ini
[Container]
ContainerName=socket-proxy
Image=lscr.io/linuxserver/socket-proxy:latest
User=65534:65534
UserNS=keep-id:uid=65534,gid=65534
Environment=CONTAINERS=1
Environment=LIBPOD_CONTAINERS=1
Environment=POST=0
Volume=%t/podman/podman.sock:/var/run/docker.sock:ro
PublishPort=2375:2375
ReadOnly=true
Tmpfs=/run:rw,mode=1777

[Install]
WantedBy=default.target
```

(`%t` expands to `$XDG_RUNTIME_DIR`.) Enable the socket first with `systemctl --user enable --now podman.socket`.

> [!NOTE]
> On SELinux-enforcing hosts (e.g. Fedora/RHEL), add `--security-opt label=disable` to the `podman run` (or `SecurityLabelDisable=true` to the Quadlet) so the container can access the mounted socket.

## Read-Only Operation

This image can be run with a read-only container filesystem. For details please [read the docs](https://docs.linuxserver.io/misc/read-only/).
Expand Down