Podman: Difference between revisions

Latest revision as of 03:33, 20 July 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

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

@@ 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 `podman` package in the community repository.
+Podman can be installed via {{Pkg|podman}} package in the community repository: {{Cmd|# apk add podman}}
+== Configuration ==
+To run podman you'll need to enable the <code>cgroups</code> service. {{Cmd|<nowiki># rc-update add cgroups
+# rc-service cgroups start</nowiki>}}
+In the past cgroups v2 needs to be enabled in OpenRC. Currently this is the default setting in [[OpenRC#cgroups v2|cgroups v2]].
+If you are running on top of [[Btrfs]], consider setting storage driver to <code>btrfs</code>: {{Cmd|$ cat /etc/containers/storage.conf | grep 'driver ='}}
+ 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 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: {{Cmd|# 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: {{Cmd|<nowiki># modprobe tun
+# echo tun >>/etc/modules
+# echo <USER>:100000:65536 >/etc/subuid
+# echo <USER>:100000:65536 >/etc/subgid </nowiki>}}
+Run an example container to verify everything works: {{Cmd|$ 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: {{Cmd|# rc-service podman start}}
+The default location of the socket is {{Path|/run/podman/podman.sock}}
+=== 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
+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 {{path|/etc/local.d/mount-rshared.start}} as follows:{{Cat|/etc/local.d/mount-rshared.start|<nowiki>#!/bin/sh
+mount --make-rshared /</nowiki>}}
+Mark it as executable:  {{cmd|# chmod +x /etc/local.d/mount-rshared.start}}
-  # apk add podman
+Then enable the service to autostart through [[OpenRC]]. {{cmd|<nowiki># rc-update add local default
+# rc-service local start </nowiki>}}
-To run podman you'll need to enable the cgroups service, consider enabling [[OpenRC#cgroups v2|cgroups v2]].
+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
+...}}
-  # rc-update add cgroups
+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:
-  # rc-service cgroups start
+ PROPAGATION
+ shared
-You might need to restart your machine for this to work properly.
+=== Docker compose ===
-If you are running on top of btrfs, consider setting driver to btrfs:
+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}}
-  +   $ cat /etc/containers/storage.conf | grep 'driver ='
+== Troubleshooting ==
-  driver = "btrfs"
-For rootless support (replace <USER> with your username):
+===  "/" is not a shared mount ===
-  # modprobe tun
+If you see a warning:
-  # echo tun >>/etc/modules
+: WARN[0000] "/" is not a shared mount, this could cause issues or missing mounts with rootless containers
-  # echo <USER>:100000:65536 >/etc/subuid
-  # echo <USER>:100000:65536 >/etc/subgid
-Run an example container to verify everything works:
+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).
-  $ podman run --rm hello-world
+[[Category:Virtualization]]