Podman: Difference between revisions

Latest revision as of 14:32, 5 May 2026

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.

Error: netavark: iptables: No such file or directory (os error 2)

Podman depends on iptables package:

# apk add iptables

@@ 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}}
+=== Running in rootless mode ===
-{{Cmd|$ cat /etc/containers/storage.conf | grep 'driver ='}}
+To avoid [[#Permission problems with rootless podman|permission problems]] with rootless podman, consider using [[runc#Crun|Crun]].
- driver = "btrfs"
+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>}}
-If you're running inside a container, change the storage driver to <code>vfs</code>
+Run an example container to verify everything works: {{Cmd|$ podman run --rm hello-world}}
-=== Running in rootless mode ===
+=== Getting socket ===
-For rootless support (replace <USER> with your username):
+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|# modprobe tun
+=== Shared mount ===
-&#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:
+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
-{{Cmd|$ podman run --rm hello-world}}
+This section explains few ways to mount your root('''/''') as shared for Distrobox to function. This is not needed when running in rootless mode.
-==== Shared mount ====
+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>}}
-Containers on linux might require filesystems to be mounted with different propagation than the kernel default of 'private'. If you see a warning:
+Mark it as executable:  {{cmd|# chmod +x /etc/local.d/mount-rshared.start}}
-: WARN[0000] "/" is not a shared mount, this could cause issues or missing mounts with rootless containers
+Then enable the service to autostart through [[OpenRC]]. {{cmd|<nowiki># rc-update add local default
+# rc-service local start </nowiki>}}
-you might want to fix this temporarily, for currently running system:
+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
+...}}
-{{Cmd|# mount --make-rshared /}}
+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
-and try the command that caused the warning again.
+=== Docker compose ===
-Alternatively, you could use following command:
+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}}
-{{Cmd|# findmnt -o PROPAGATION /}}
+== Troubleshooting ==
-which should print:
+===  "/" is not a shared mount ===
-    PROPAGATION
+If you see a warning:
-    shared
+: WARN[0000] "/" is not a shared mount, this could cause issues or missing mounts with rootless containers
-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}}:
+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).
-   {{cmd|# $EDITOR /etc/fstab}}
+=== Permission problems with rootless podman ===
-Add <code>shared</code> option to the root partition:
+You may encounter an error when entering your rootless container:
-   /dev/sda2 / ext4 rw,relatime,shared 0 1
+<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>
-and after a reboot test it out similarly as above.
+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.
-=== Docker compose ===
+=== Error: netavark: iptables: No such file or directory (os error 2) ===
-Podman provides a drop-in replacement for docker compose. The {{Pkg|podman-compose}} package provides this.
+Podman depends on {{Pkg|iptables}} package:
+{{cmd|# apk add iptables}}
-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 ==
-{{cmd|# touch /etc/containers/nodocker}}
+* [https://docs.podman.io/en/latest/ Official Podman Documentation]
 [[Category:Virtualization]]