4 Configuring Storage for Podman

The following information describes how to add and configure storage for Podman and related utilities.

By default, images are stored in the /var/lib/containers directory when Podman is run by the root user. For standard users, images are typically stored in $HOME/.local/share/containers/storage/. These locations conform to Open Container Initiative (OCI) 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 locations can be set up as mount points to take advantage of some forms of network storage or of dedicated local file systems, depending on requirements.

Caution:

When containers are run by users without root permissions, Podman lacks 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 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 storage configuration is handled by editing the file at /etc/containers/storage.conf.

You can override the system-wide storage configuration by creating a separate $HOME/.config/containers/storage.conf configuration file for any user.

The following is an example of a typical storage configuration file:

cat ~/.config/containers/storage.conf

[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 might help you better understand the information in this 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 usually 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 is unshared 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.