% podman-image.unit 5 # 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 the `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: | **[Image] options** | **podman image pull equivalent** | |----------------------------------------|--------------------------------------------------| | 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 | [//]: # (BEGIN included file options/all-tags.md) ### `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 the **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)** but always uses docker.io for unqualified image names.* [//]: # (END included file options/all-tags.md) [//]: # (BEGIN included file options/arch.md) ### `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. [//]: # (END included file options/arch.md) [//]: # (BEGIN included file options/authfile.md) ### `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](podman-login.1.md)**. 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_**. [//]: # (END included file options/authfile.md) [//]: # (BEGIN included file options/cert-dir.md) ### `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)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) [//]: # (END included file options/cert-dir.md) [//]: # (BEGIN included file options/module.md) ### `ContainersConfModule=module` Load the specified containers.conf(5) module. This option can be listed multiple times. [//]: # (END included file options/module.md) [//]: # (BEGIN included file options/creds.md) ### `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. [//]: # (END included file options/creds.md) [//]: # (BEGIN included file options/decryption-key.md) ### `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. [//]: # (END included file options/decryption-key.md) [//]: # (BEGIN included file options/global-args.md) ### `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. [//]: # (END included file options/global-args.md) ### `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` requires setting - `Image=docker-archive:/tmp/archive-file.tar` - `ImageTag=quay.io/podman/stable:latest` [//]: # (BEGIN included file options/os.pull.md) ### `OS=os` Override the OS, defaults to the host, of the image to be pulled. For example, `windows`. Unless overridden, subsequent lookups of the same image in the local storage matches this OS, regardless of the host. [//]: # (END included file options/os.pull.md) [//]: # (BEGIN included file options/podman-args.md) ### `PodmanArgs=` This key contains a list of arguments passed directly to the end of 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. [//]: # (END included file options/podman-args.md) [//]: # (BEGIN included file options/policy.md) ### `Policy=always` Pull image policy. The default is **always**. - `always`: Always pull the image and throw an error if the pull fails. - `missing`: Only pull the image if it could not 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 is not present locally. - `newer`: Pull if the image on the registry is newer than the one in the local containers storage. An image is considered to be newer when the digests are different. Comparing the time stamps is prone to errors. Pull errors are suppressed if a local image was found. [//]: # (END included file options/policy.md) [//]: # (BEGIN included file options/retry.md) ### `Retry=attempts` Number of times to retry pulling or pushing images between the registry and local storage in case of failure. Default is **3**. [//]: # (END included file options/retry.md) [//]: # (BEGIN included file options/retry-delay.md) ### `RetryDelay=duration` Duration of delay between retry attempts when pulling or pushing images between the registry and local storage in case of failure. The default is to start at two seconds and then exponentially back off. The delay is used when this value is set, and no exponential back off occurs. [//]: # (END included file options/retry-delay.md) [//]: # (BEGIN included file options/tls-verify.md) ### `TLSVerify=` Require HTTPS and verify certificates when contacting registries (default: **true**). If explicitly set to **true**, TLS verification is used. If set to **false**, TLS verification is not used. If not specified, TLS verification is used unless the target registry is listed as an insecure registry in **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)** [//]: # (END included file options/tls-verify.md) [//]: # (BEGIN included file options/variant.container.md) ### `Variant=VARIANT` Use _VARIANT_ instead of the default architecture variant of the container image. Some images can use multiple variants of the arm architectures, such as arm/v5 and arm/v7. [//]: # (END included file options/variant.container.md) # 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-image-pull.1.md), [podman-systemd.unit(5)](podman-systemd.unit.5.md), [systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)