Podman: Difference between revisions

Revision as of 10:02, 2 June 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.

Installation

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

# apk add podman

Configuration

To run podman you'll need to enable the cgroups service.

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

In the past cgroups v2 needs to be enabled in OpenRC. Currently this is the default setting in cgroups v2.

If you are running on top of Btrfs, consider setting storage driver to btrfs:

$ cat /etc/containers/storage.conf

driver = "btrfs"

If you're running podman inside a container, change the storage driver to vfs

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 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

Troubleshooting

Shared mount

Containers on linux might require filesystems to be mounted with different propagation than the kernel default of 'private'. 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:

# mount --make-rshared /

Try the command that caused the warning again.

Alternatively, you could use following command:

# findmnt -o PROPAGATION /

which should print:

   PROPAGATION
   shared

For a permanent fix (after a OpenRC PR#526 is released - in newer version than 0.54.2-r1), edit /etc/fstab:

# $EDITOR /etc/fstab

Add shared option to the root partition:

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

and after a reboot test it out similarly as above.

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

@@ 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.
 == 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 you'll need to enable the <code>cgroups</code> service. {{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]].
+In the past cgroups v2 needs to be enabled in OpenRC. Currently this is the default setting in [[OpenRC#cgroups v2|cgroups v2]].
-{{Cmd|# rc-update add cgroups}}
+If you are running on top of [[Btrfs]], consider setting storage driver to <code>btrfs</code>: {{Cmd|$ cat /etc/containers/storage.conf | grep 'driver ='}}
-{{Cmd|# rc-service cgroups start}}
+ driver = "btrfs"
+If you're running podman inside a container, change the storage driver to <code>vfs</code>
-You might need to restart your machine for this to work properly.
+You might need to restart your machine at this stage for the above changes to work properly.
-If you are running on top of [[Btrfs]], consider setting storage driver to <code>btrfs</code>:
+=== Running as root ===
-{{Cmd|$ cat /etc/containers/storage.conf | grep 'driver ='}}
+No further steps are required to run as root. Run an example container to verify everything works: {{Cmd|# podman run --rm hello-world}}
- driver = "btrfs"
-If you're running inside a container, change the storage driver to <code>vfs</code>
 === Running in rootless mode ===
-For rootless support (replace <USER> with your username):
+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
-{{Cmd|# modprobe tun
+# echo <USER>:100000:65536 >/etc/subuid
-&#35; echo tun >>/etc/modules
+# echo <USER>:100000:65536 >/etc/subgid </nowiki>}}
-&#35; echo <USER>:100000:65536 >/etc/subuid
-&#35; echo <USER>:100000:65536 >/etc/subgid}}
-Run an example container to verify everything works:
+Run an example container to verify everything works: {{Cmd|$ podman run --rm hello-world}}
-{{Cmd|$ podman run --rm hello-world}}
+== Troubleshooting ==
-==== Shared mount ====
+=== Shared mount ===
 Containers on linux might require filesystems to be mounted with different propagation than the kernel default of 'private'. If you see a warning:
@@ Line 41: / Line 39: @@
 : 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:
+you might want to fix this temporarily, for currently running system: {{Cmd|# mount --make-rshared /}}
-{{Cmd|# mount --make-rshared /}}
-and try the command that caused the warning again.
-Alternatively, you could use following command:
+Try the command that caused the warning again.
-{{Cmd|# findmnt -o PROPAGATION /}}
+Alternatively, you could use following command: {{Cmd|# findmnt -o PROPAGATION /}}
 which should print:
      PROPAGATION
      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}}:
+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}}:{{cmd|# $EDITOR /etc/fstab}}
-   {{cmd|# $EDITOR /etc/fstab}}
 Add <code>shared</code> option to the root partition:
     /dev/sda2 / ext4 rw,relatime,shared 0 1
 and after a reboot test it out similarly as above.
 === Docker compose ===
-Podman provides a drop-in replacement for docker compose. The {{Pkg|podman-compose}} package provides this.
+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}}
-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:
-{{cmd|# touch /etc/containers/nodocker}}
 [[Category:Virtualization]]