podman-image.unit(5)

🦋 podman-image.unit(5) 🦋

okay bestie, this is the File Formats Manual page for podman-image.unit — aka the Podman Quadlet image-unit situation. It's giving "systemd unit files for managing container image pulls using Podman Quadlet," and we're gonna get you comfy with it. 💅

---

✨ NAME ✨

podman-image.unit — systemd unit files for managing container image pulls using Podman Quadlet.

🫶 SYNOPSIS 🫶

name.image

🌸 DESCRIPTION 🌸

Image files are named with a .image extension and contain a section [Image] describing the container image pull command. The generated service is a one-time command that ensures that the image exists on the host, pulling it if needed.

Using image units allows containers and volumes to depend on images being automatically pulled. This is particularly interesting when using special options to control image pulls. 👑

🎀 USAGE SUMMARY 🎀

The .image file is parsed by podman-system-generator at boot or reload, generating a systemd .service that runs podman image pull.

A .image file can be referenced in a .container file's Image= option.

👑 OPTIONS 👑

Valid options for [Image] are listed below. Here's the cheat sheet mapping each [Image] option to its podman image pull equivalent, bestie:

• AllTags=true → --all-tags
• Arch=aarch64 → --arch=aarch64
• AuthFile=/etc/registry/auth.json → --authfile=/etc/registry/auth.json
• CertDir=/etc/registry/certs → --cert-dir=/etc/registry/certs
• ContainersConfModule=/etc/nvd.conf → --module=/etc/nvd.conf
• Creds=myname:mypassword → --creds=myname:mypassword
• DecryptionKey=/etc/registry.key → --decryption-key=/etc/registry.key
• GlobalArgs=--log-level=debug → --log-level=debug
• Image=quay.io/centos/centos:latest → podman image pull quay.io/centos/centos:latest
• ImageTag=quay.io/centos/centos:latest → Use this name when resolving .image references
• OS=windows → --os=windows
• PodmanArgs=--os=linux → --os=linux
• Policy=always → --policy=always
• Retry=5 → --retry=5
• RetryDelay=10s → --retry-delay=10s
• TLSVerify=false → --tls-verify=false
• Variant=arm/v7 → --variant=arm/v7

AllTags=true

All tagged images in the repository are pulled.

IMPORTANT: When using the all-tags flag, Podman does not iterate over the search registries in containers-registries.conf(5) but always uses docker.io for unqualified image names. 🫶

Arch=ARCH

Override the architecture, defaults to the host, of the image to be pulled. For example, arm. Unless overridden, subsequent lookups of the same image in the local storage matches this architecture, regardless of the host.

AuthFile=path

Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/containers/auth.json on Linux, and $HOME/.config/containers/auth.json on Windows/macOS. The file is created by podman login. If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using docker login.

Note: There is also the option to override the default path of the authentication file by setting the REGISTRY_AUTH_FILE environment variable. This can be done with export REGISTRY_AUTH_FILE=path.

CertDir=path

Use certificates at path (*.crt, *.cert, *.key) to connect to the registry. (Default: /etc/containers/certs.d) For details, see containers-certs.d(5). (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines)

ContainersConfModule=module

Load the specified containers.conf(5) module.

This option can be listed multiple times.

Creds=[username[:password]]

The [username[:password]] to use to authenticate with the registry, if required. If one or both values are not supplied, a command line prompt appears and the value can be entered. The password is entered without echo.

Note that the specified credentials are only used to authenticate against target registries. They are not used for mirrors or when the registry gets rewritten (see containers-registries.conf(5)); to authenticate against those consider using a containers-auth.json(5) file.

DecryptionKey=key[:passphrase]

The [key[:passphrase]] to be used for decryption of images. Key can point to keys and/or certificates. Decryption is tried with all keys. If the key is protected by a passphrase, it is required to be passed in the argument and omitted otherwise.

GlobalArgs=

This key contains a list of arguments passed directly after the podman command in the generated file. It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, it is not recommended to use this option.

The format of this is a space separated list of arguments, which can optionally be individually escaped to allow inclusion of whitespace and other control characters.

This key can be listed multiple times.

Image=

The image to pull. It is recommended to use a fully qualified image name rather than a short name, both for performance and robustness reasons.

The format of the name is the same as when passed to podman pull. It supports using :tag or digests to guarantee the specific image version.

ImageTag=

The actual Fully Qualified Image Name (FQIN) of the referenced Image. Only meaningful when the source is a file or directory archive.

For example, an image saved into a docker-archive with the following Podman command:

podman image save --format docker-archive --output /tmp/archive-file.tar quay.io/podman/stable:latest

...and heads up, this one's got a whole little checklist attached — it requires you to set both of these together:

• Image=docker-archive:/tmp/archive-file.tar
• ImageTag=quay.io/podman/stable:latest

---

• OS=os — overrides the OS of the image you're pulling, and it defaults to whatever the host's OS is. Think windows as your example, bestie. And unless you override it, every later lookup of that same image in local storage matches this OS — regardless of what the host happens to be. Sneaky but fair 💅
• PodmanArgs= — this key holds a list of arguments that get passed straight to the end of the podman command in the generated file. It's basically the secret back door for reaching Podman features the generator doesn't support on its own. But here's the tea: the generator has no clue what unexpected chaos these arguments might cause, so using this option is not recommended, fr fr 🙈

The format is a space separated list of arguments, and each one can optionally be individually escaped so you can sneak whitespace and other control characters in there.

This key can be listed multiple times.

• Policy=always — the pull image policy, and the default is always. The four moods are:
  • always: always pull the image and throw an error if the pull fails.
  • missing: only pull the image if it couldn't be found in the local containers storage. Throw an error if no image could be found and the pull fails.
  • never: never pull the image; only use the local version. Throw an error if the image isn't present locally.
  • newer: pull if the image on the registry is newer than the one in the local containers storage. An image counts as newer when the digests are different — comparing the time stamps is prone to errors, so don't 👀. Pull errors are suppressed if a local image was found.
• Retry=attempts — how many times to retry pulling or pushing images between the registry and local storage when something fails. Default is 3. Persistence slay ✨
• RetryDelay=duration — how long to wait between those retry attempts when pulling or pushing images between the registry and local storage fails. The default is to start at two seconds and then exponentially back off. But listen: the delay is used when this value is set, and no exponential back off occurs once you set it. You're taking the wheel 🎀
• TLSVerify= — require HTTPS and verify certificates when contacting registries (default: true). If you explicitly set it to true, TLS verification is used. If you set it to false, TLS verification is not used. And if you don't specify it at all, TLS verification is used — unless the target registry is listed as an insecure registry in containers-registries.conf(5). Details matter, iykyk 💖
• Variant=VARIANT — use VARIANT instead of the default architecture variant of the container image. Some images can use multiple variants of the arm architectures, like arm/v5 and arm/v7. Pick your fighter 💅

---

✨ EXAMPLES ✨

Basic image pull:

[Image]
Image=quay.io/centos/centos:latest

Pull from docker archive:

[Image]
Image=docker-archive:/tmp/centos.tar
ImageTag=quay.io/centos/centos:latest

Pull with credentials:

[Image]
Image=quay.io/private/image:latest
Creds=myuser:mypassword

---

💜 SEE ALSO 💜

podman-image-pull(1), podman-systemd.unit(5), systemd.unit(5)

---

And that's the whole page, bestie — you ate that 🫶 This is podman-image.unit(5), straight from the source with its version and date stamped in the corner, no cap. Go forth and pull some images 👑🌸