Podman: Difference between revisions

Latest revision as of 03:23, 24 September 2025

Podman is a utility provided as part of the libpod library. It can be used to create and maintain containers. Podman (Pod Manager) is a fully featured container engine that is a simple daemonless tool. In Alpine linux, Distrobox automatically installs and uses Podman.

Installation

Podman can be installed via podman package in the community repository:

# apk add podman

Configuration

To run podman with full functionality you'll need to enable the cgroups service in v2 or unified mode, which is the current default.

# rc-update add cgroups # rc-service cgroups start

The default storage driver setting in /etc/containers/storage.conf is overlay. If you're running podman inside a container or using Btrfs filesystem, change the storage driver to vfs or btrfs respectively.

You might need to restart your machine at this stage for the above changes to work properly.

Running as root

No further steps are required to run as root. Run an example container to verify everything works:

# podman run --rm hello-world

Running in rootless mode

To avoid permission problems with rootless podman, consider using Crun.

To run podman in rootless mode, run the following commands. Replace <USER> with your username in the following commands:

# modprobe tun # echo tun >>/etc/modules # echo <USER>:100000:65536 >/etc/subuid # echo <USER>:100000:65536 >/etc/subgid

Run an example container to verify everything works:

$ podman run --rm hello-world

Getting socket

To use the podman API or use podman remotely, you need podman socket. Socket is not needed, if podman CLI is used locally.

To get socket, start the podman service:

# rc-service podman start

The default location of the socket is /run/podman/podman.sock

Shared mount

Containers on linux might require filesystems to be mounted with different propagation than the kernel default of 'private'.

$ findmnt -o PROPAGATION /

will produce the following output:

PROPAGATION
private

This section explains few ways to mount your root(/) as shared for Distrobox to function. This is not needed when running in rootless mode.

Method1:

Fill in the file /etc/local.d/mount-rshared.start as follows:

Contents of /etc/local.d/mount-rshared.start

#!/bin/sh
mount --make-rshared /

Mark it as executable:

# chmod +x /etc/local.d/mount-rshared.start

Then enable the service to autostart through OpenRC.

# rc-update add local default # rc-service local start

Method2:

An alternate solution with OpenRC v0.54.2-r1 onwards, edit the file /etc/fstab and add shared option to the root partition such that:

Contents of /etc/fstab

...
/dev/sda2 / ext4 rw,relatime,shared 0 1
...

For both the above cases, after a reboot test the working of shared / mount using the command:

# findmnt -o PROPAGATION /

which will produce the following output:

PROPAGATION
shared

Docker compose

The podman-compose package from provides a drop-in replacement for docker compose. Each time a docker compose is used, a warning will remind that this is using podman under the hood. This warning can be squelched permanently by running:

# touch /etc/containers/nodocker

Troubleshooting

"/" is not a shared mount

If you see a warning:

WARN[0000] "/" is not a shared mount, this could cause issues or missing mounts with rootless containers

You might want to fix this temporarily, for currently running system by issuing the command:# mount --make-rshared / Alternately, refer to Shared mount section for permanent solution(s).

Permission problems with rootless podman

You may encounter an error when entering your rootless container:

Error: unable to start container "XYZ": runc: runc create failed: unable to start container process: unable to apply cgroup configuration: rootless needs no limits + no cgrouppath when no permission is granted for cgroups: mkdir /sys/fs/cgroup/XYZ: permission denied: OCI permission denied

This problem may be solved by replacing runc by Crun and recreating your container. Keep in mind that crun replaces runc, which will render containers made with the latter unusable until recreated.

@@ Line 1: / Line 1: @@
+[https://podman.io/ Podman] is a utility provided as part of the libpod library. It can be used to create and maintain containers. Podman (Pod Manager) is a fully featured container engine that is a simple daemonless tool. In Alpine linux, [[Distrobox]] automatically installs and uses Podman.
 == Installation ==
-Podman can be installed via {{Pkg|podman}} package in the community repository.
+Podman can be installed via {{Pkg|podman}} package in the community repository: {{Cmd|# apk add podman}}
-{{Cmd|# apk add podman}}
+== Configuration ==
-=== Running as root ===
+To run podman with full functionality you'll need to enable the [[OpenRC#cgroups|cgroups]] service in v2 or '''unified''' mode, which is the current default. {{Cmd|<nowiki># rc-update add cgroups
+# rc-service cgroups start</nowiki>}}
-To run podman you'll need to enable the <code>cgroups</code> service, consider enabling [[OpenRC#cgroups v2|cgroups v2]].
+The default storage driver setting in {{Path|/etc/containers/storage.conf}} is {{ic|overlay}}. If you're running podman inside a container or using [[Btrfs]] filesystem, change the storage driver to {{ic|vfs}} or {{ic|btrfs}} respectively.
-{{Cmd|# rc-update add cgroups}}
+You might need to restart your machine at this stage for the above changes to work properly.
-{{Cmd|# rc-service cgroups start}}
-You might need to restart your machine for this to work properly.
+=== Running as root ===
-If you are running on top of [[Btrfs]], consider setting storage driver to <code>btrfs</code>:
+No further steps are required to run as root. Run an example container to verify everything works: {{Cmd|# podman run --rm hello-world}}
-{{Cmd|$ cat /etc/containers/storage.conf | grep 'driver ='}}
+=== Running in rootless mode ===
- driver = "btrfs"
+To avoid [[#Permission problems with rootless podman|permission problems]] with rootless podman, consider using [[runc#Crun|Crun]].
-=== Running in rootless mode ===
+To run podman in rootless mode, run the following commands. Replace <USER> with your username in the following commands: {{Cmd|<nowiki># modprobe tun
+# echo tun >>/etc/modules
+# echo <USER>:100000:65536 >/etc/subuid
+# echo <USER>:100000:65536 >/etc/subgid </nowiki>}}
-For rootless support (replace <USER> with your username):
+Run an example container to verify everything works: {{Cmd|$ podman run --rm hello-world}}
-{{Cmd|# modprobe tun
+=== Getting socket ===
-&#35; echo tun >>/etc/modules
-&#35; echo <USER>:100000:65536 >/etc/subuid
-&#35; echo <USER>:100000:65536 >/etc/subgid}}
-Run an example container to verify everything works:
+To use the podman API or use podman remotely, you need podman socket. Socket is not needed, if podman CLI is used locally.
+To get socket, start the podman service: {{Cmd|# rc-service podman start}}
+The default location of the socket is {{Path|/run/podman/podman.sock}}
-{{Cmd|$ podman run --rm hello-world}}
+=== Shared mount ===
-==== Shared mount ====
+Containers on linux might require filesystems to be mounted with different propagation than the kernel default of 'private'.
+{{Cmd|$ findmnt -o PROPAGATION /}} will produce the following output:
+ PROPAGATION
+ private
-Containers on linux might require filesystems to be mounted with different propagation than the kernel default of 'private'. If you see a warning:
+This section explains few ways to mount your root('''/''') as shared for Distrobox to function. This is not needed when running in rootless mode.
-: WARN[0000] "/" is not a shared mount, this could cause issues or missing mounts with rootless containers
+Method1:
+Fill in the file {{path|/etc/local.d/mount-rshared.start}} as follows:{{Cat|/etc/local.d/mount-rshared.start|<nowiki>#!/bin/sh
+mount --make-rshared /</nowiki>}}
-you might want to fix this temporarily, for currently running system:
+Mark it as executable:  {{cmd|# chmod +x /etc/local.d/mount-rshared.start}}
-{{Cmd|doas mount --make-rshared /}}
+Then enable the service to autostart through [[OpenRC]]. {{cmd|<nowiki># rc-update add local default
+# rc-service local start </nowiki>}}
-and try the command that caused the warning again.
+Method2:
+An alternate solution with OpenRC v0.54.2-r1 onwards, edit the file {{path|/etc/fstab}} and add {{ic|shared}} option to the root partition such that:{{Cat|/etc/fstab|...
+/dev/sda2 / ext4 rw,relatime,shared 0 1
+...}}
-Alternatively, you could use following command:
+For both the above cases, after a reboot test the working of shared '''/''' mount using the command: {{Cmd|# findmnt -o PROPAGATION /}} which will produce the following output:
+ PROPAGATION
+ shared
-{{Cmd|doas findmnt -o PROPAGATION /}}
+=== Docker compose ===
-which should print:
+The {{Pkg|podman-compose}} package from provides a drop-in replacement for docker compose.  Each time a docker compose is used, a warning will remind that this is using podman under the hood. This warning can be squelched permanently by running: {{cmd|# touch /etc/containers/nodocker}}
-    PROPAGATION
+== Troubleshooting ==
-    shared
-For a permanent fix (after a [https://github.com/OpenRC/openrc/pull/526 OpenRC PR#526] is released - in newer version than 0.54.2-r1), edit {{path|/etc/fstab}}:
+===  "/" is not a shared mount ===
-   {{cmd|doas $EDITOR /etc/fstab}}
+If you see a warning:
+: WARN[0000] "/" is not a shared mount, this could cause issues or missing mounts with rootless containers
-Add <code>shared</code> option to the root partition:
+You might want to fix this temporarily, for currently running system by issuing the command:{{ic|# mount --make-rshared /}}
+Alternately, refer to [[#Shared mount|Shared mount]] section for permanent solution(s).
-   /dev/sda2 / ext4 rw,relatime,shared 0 1
+=== Permission problems with rootless podman ===
-and after a reboot test it out similarly as above.
+You may encounter an error when entering your rootless container:
-=== Docker compose ===
+<code>Error: unable to start container "XYZ": runc: runc create failed: unable to start container process: unable to apply cgroup configuration: rootless needs no limits + no cgrouppath when no permission is granted for cgroups: mkdir /sys/fs/cgroup/XYZ: permission denied: OCI permission denied</code>
-Podman provides a drop-in replacement for docker compose. The {{Pkg|podman-compose}} package provides this.
+This problem may be solved by replacing [[runc|runc]] by [[runc#Crun|Crun]] and recreating your container. Keep in mind that {{Pkg|crun}} replaces {{Pkg|runc}}, which will render containers made with the latter unusable until recreated.
-Each time that docker compose is used, a warning will remind that this is using podman under the hood. This warning can be squelched permanently by running:
+== See also ==
- touch /etc/containers/nodocker
+* [https://docs.podman.io/en/latest/ Official Podman Documentation]
 [[Category:Virtualization]]