Accessing Podman from another WSL distribution

On Windows, Podman Desktop creates a Windows Subsystem for Linux (WSL) virtual machine: the Podman Machine. It also configures the Windows Podman client to communicate with the Podman Machine. However, it does not configure your other WSL distributions.

You might have other WSL distributions running, and want to access from there to your Podman Desktop containers.

This tutorial focuses on the most common context to walk you through the steps to configure your WSL distribution:

Ubuntu distribution of Linux.
Default Podman Machine.

In foldable details, you can find alternative steps for least common contexts:

Custom WSL distribution.
Custom Podman Machine.

Configuring your WSL distribution

Start a session in your WSL distribution:

> wsl --distribution your-distribution-name

To communicate with the remote Podman Machine, you need a Podman client.

To benefit from the latest features, such as podman kube subcommands, use a recent Podman version rather than the podman package from the distribution.

The Podman client is available with a full podman installation or with the podman-remote version 4.x and higher. On Ubuntu it is generally easier to install podman-remote.

With podman-remote you also enable the remote mode by default.

Check for the latest release which includes the podman-remote binary from the Podman releases page.

Download and unpack the binary:
```
$ wget https://github.com/containers/podman/releases/download/v4.9.1/podman-remote-static-linux_amd64.tar.gz
$ sudo tar -C /usr/local -xzf podman-remote-static-linux_amd64.tar.gz
```
Make this executable as podman with the following addition to .bashrc:
```
$ export PATH="$PATH:/usr/local/bin"
$ alias podman='podman-remote-static-linux_amd64'
```
Configure the Podman client in your WSL distribution to communicate with the remote Podman machine defined by Podman Desktop.

This will ensure consistency when you are working with Podman from all your different environments

Set the default Podman system connection to your Podman Machine (assuming Podman Desktop is configured with the default of Podman Machine enabled with root privileges):
```
$ podman system connection add --default podman-machine-default-root unix:///mnt/wsl/podman-sockets/podman-machine-default/podman-root.sock
```
On a custom Podman Machine, the remote Podman Machine destination might be different.
Two parameters can change:
- The machine name might differ from podman-machine-default.
- The socket name is different when the Podman machine has root privileges disabled (rootless mode).
Find your Podman Machine name and connection path:
Identify the sockets available in your WSL distribution.

The Podman machine shares sockets in a /mnt/wsl/podman-sockets/ subdirectory named after the Podman machine name.

In your WSL session, list the available sockets:

$ find /mnt/wsl/podman-sockets/ -name '*.sock'

Each Podman Machine has a socket for:

Rootful Podman: podman-root.sock

Rootless Podman: podman-user.sock

Sample output:

/mnt/wsl/podman-sockets/podman-machine-default/podman-root.sock /mnt/wsl/podman-sockets/podman-machine-default/podman-user.sock

Identify the socket that Podman Desktop uses.

Podman Desktop defaults to rootful Podman. However, consider identifying the active socket.

The active socket is the default Podman system connection in your Windows session.

Open a new Command Prompt, and list your Podman system connections:

> podman system connection list

The default connection line ends with true.

Identify your Podman Machine socket by its URI in Windows:

Rootful Podman: ssh://root@127.0.0.1:59292/run/podman/podman.sock

Rootless Podman: ssh://user@127.0.0.1:59292/run/user/1000/podman/podman.sock

Sample output:

Name URI Identity Default podman-machine-default ssh://user@127.0.0.1:59292/run/user/1000/podman/podman.sock C:\Users\Podman Desktop User\.ssh\podman-machine-default false podman-machine-default-root ssh://root@127.0.0.1:59292/run/podman/podman.sock C:\Users\Podman Desktop User\.ssh\podman-machine-default true

To define the Podman machine remote destination, prepend with unix:// the socket path that is available in your WSL, and corresponds to the Podman Desktop active socket:

For the default Podman machine:

Rootful Podman: unix:///mnt/wsl/podman-sockets/podman-machine-default/podman-root.sock

Rootless Podman: unix:///mnt/wsl/podman-sockets/podman-machine-default/podman-user.sock
The communication channel between your WSL distribution and the Podman Machine is a special file (a socket). The Podman Machine creates this file with specific permissions. To communicate with the Podman Machine from your WSL distribution your user must have write permissions for the socket.

To give access to the remote Podman machine to your user: create the group if necessary, assign group membership, and exit your session on the WSL distribution to apply the new group membership:
```
$ sudo usermod --append --groups 10 $(whoami)
$ exit
```

Testing the connection

Verify that, on your WSL distribution, the Podman CLI communicates with your Podman machine.

Start a session in your WSL distribution:
```
> wsl
```
Verify that your user is member of the group delivering access to the remote Podman Machine socket:
```
$ groups
```
On the default Ubuntu WSL, the list contains the uucp group.
On a custom WSL distribution, the group name might be different.
Find the required group name:
The required group id is the same on any WSL distribution.
However, the group name might be different on a custom WSL distribution.
On the Podman Machine, which runs on a Fedora distribution:

Rootful Podman: GID 10 name is wheel.

Rootless Podman: GID 1000 name is user.

On the Ubuntu distribution:

Rootful Podman: GID 10 name is uucp.

Rootless Podman: GID 1000 name is the same as the user name you chose when creating the WSL machine.

On a custom WSL distribution, find the group name for:

Rootful Podman:

$ getent group 10

Rootless Podman:

$ getent group 1000
Verify that Podman default system connections is set to your remote Podman machine:
```
$ podman system connection list
```

Verify that Podman has a Server version corresponding to your Podman Machine version:

$ podman version

Sample output:

Client:
Version:      3.4.4
API Version:  3.4.4
Go Version:   go1.18.1
Built:        Thu Jan 1 01:00:00 1970
OS/Arch:      linux/amd64

Server:
Version:      4.8.3
API Version:  4.8.3
Go Version:   go1.21.5
Built:        Wed Jan 3 15:11:40 2024
OS/Arch:      linux/amd64

info

On your environment, the Podman version might be different.

Verify that you can list running containers.

On your WSL distribution, start a container such as quay.io/podman/hello, and list the name of the last running container:
```
$ podman run quay.io/podman/hello
$ podman ps -a --no-trunc --last 1
```
On Podman Desktop > Containers, the output lists the same container (same name, same image).

Changing the connection

Podman Desktop only has visibility to either rootless or rootful containers but not both at the same time.

To change the active connection:

In your Windows terminal, change the connection:
- To set the connection to rootless:
```
$ podman machine set --rootful=false
```
- To set the connection to rootful:
```
$ podman machine set --rootful=true
```

In your WSL session, Change the Podman system connection configuration:

To set the connection to rootless:

$ podman system connection add --default podman-machine-default-user unix:///mnt/wsl/podman-sockets/podman-machine-default/podman-user.sock

To set the connection to rootful:

$ podman system connection add --default podman-machine-default-root unix:///mnt/wsl/podman-sockets/podman-machine-default/podman-root.sock

Next steps

From your WSL distribution, work with containers.

Configuring your WSL distribution​

Testing the connection​

Changing the connection​

Next steps​

Configuring your WSL distribution

Testing the connection

Changing the connection

Next steps