7 Podman Storage

Set up and configure storage for Podman pods and containers, and for Buildah and Skopeo.

By default, container images are stored in $HOME/.local/share/containers/storage/. If you start a container using root privileges (using the sudo command), the images are stored in the /var/lib/containers directory. These locations conform to Open Container Initiative specifications. The separation of the local image repository for standard users ensures that containers and images maintain the correct permissions and that containers can run concurrently without affecting other users on the system.

All Podman related utilities take advantage of the same storage configuration. This means that Podman, Buildah, and Skopeo are all aware of the same storage locations for images available on the system.

These storage locations can be set up as mount points to take advantage of network storage, or dedicated local file systems, depending on requirements.

Caution:

When containers are run by a standard user (without the sudo command), Podman doesn't have the necessary permissions to access network shares and mounted volumes. If you intend to run containers as a standard user, only configure directory locations on the local file systems.

You can alter the configuration for Podman storage to address other requirements for a particular use case.

Setting Storage Configuration Options

System-wide Podman storage is configured in the /etc/containers/storage.conf file on Oracle Linux 8 and Oracle Linux 9 systems, and the /usr/share/containers/storage.conf file on Oracle Linux 10 systems.

You can override the system-wide storage configuration by creating a separate $HOME/.config/containers/storage.conf configuration file for any user. This file must be created as needed. For example, the following is an example of a storage configuration file for a user in the $HOME/.config/containers/storage.conf file: 

[storage]
  driver = "overlay"
  runroot = "/run/user/1000"
  graphroot = "/home/oracle/.local/share/containers/storage"
  [storage.options]
    size = ""
    remap-uids = ""
    remap-gids = ""
    ignore_chown_errors = ""
    remap-user = ""
    remap-group = ""
    mount_program = "/usr/bin/fuse-overlayfs"
    mountopt = ""
    [storage.options.thinpool]
      autoextend_percent = ""
      autoextend_threshold = ""
      basesize = ""
      blocksize = ""
      directlvm_device = ""
      directlvm_device_force = ""
      fs = ""
      log_level = ""
      min_free_space = ""
      mkfsarg = ""
      mountopt = ""
      use_deferred_deletion = ""
      use_deferred_removal = ""
      xfs_nospace_max_retries = ""

Configuration options are described in detail in the containers-storage.conf(5) manual page. The following descriptions describe the information in this example configuration file:

  • driver: The storage driver is used to define how images and containers are stored. In Docker, there were options to use overlay or overlay2 drivers, but Podman treats these as interchangeable to mean overlay2. Oracle has tested the overlay2 driver with XFS, Ext4, and Btrfs where kernel support is available. Although you can change the storage driver to use another file system that's capable of layering, Oracle only supports the overlay2 driver with the tested file systems.

  • graphroot: The storage location where images are stored. As already mentioned, for standard users images are typically in $HOME/.local/share/containers/storage/. A legitimate use case to change this location, is where home directories might be NFS mounted.

    Important:

    If you change the graphroot location, you must ensure that SELinux labeling is correct for the new location.

    You can provide more storage locations for other image repositories by defining the paths to this in the additionalimagestores parameter within the [storage.options] section of the configuration file. Use this option to provide read-only access to shared images across networked storage.

  • runroot: The default storage directory for all writable content for a container. The data within this directory is temporary and exists for the lifetime of the container. For a root user, the runroot location is often set to /var/run/containers/storage.

Depending on the storage driver that you use, different storage options might be available to use in the [storage.options] section of the configuration file. Some generic options that control user and group remapping are available to all drivers, and in all cases you can set a size parameter to apply quotas to container images.

Setting Up Container Mounts

Podman caters to automatically mounting particular directories on the host system into each container. This feature can be useful for sharing host secrets and authentication information with each container without storing the information within the images themselves. A common use case is that where system-wide private keys, certificates, or authentication credentials might be needed during a build process to provide access to external resources that a user might not have at their privilege level.

You can define other default mounts in /usr/share/containers/mounts.conf or in /etc/containers/mounts.conf. These entries are formatted as a colon-separated mapping between the source and destination directories, for example: 

/src/dir/on/host:/run/target/on/container

See the containers-mounts.conf(5) manual page for more information.

You can also use the --volume or -v option when building an image or running a container from an image to mount a local directory into a container directory where required. For example: 

sudo buildah bud -v /path/on/host:/path/on/container:rw -t newimage:1.0 .
sudo podman run --name mycontainer -d -v /path/on/host:/path/on/container:z newimage:1.0

Other options are available for a volume mount. Notably the -z option helps where you might need to share an SELinux security context between several containers or between the container and the host system. Sharing an SELinux security context is useful when running a container as a non root user. This option is based on the SELinux multi level security (MLS) feature.

To restrict the volume to only the running container such that the volume's SELinux context isn't with other containers, use the -Z option. This option is based on the SELinux multi category security (MCS) feature.

See the podman-run(1) manual page for more information on --volume options. See the Oracle Linux: Administering SELinux for more information about SELinux contexts.