diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore index 3dd3b2e7d4..3ab040378b 100644 --- a/docs/source/markdown/.gitignore +++ b/docs/source/markdown/.gitignore @@ -69,3 +69,11 @@ podman-unpause.1.md podman-update.1.md podman-volume-ls.1.md podman-wait.1.md +podman-build.unit.5.md +podman-container.unit.5.md +podman-image.unit.5.md +podman-kube.unit.5.md +podman-network.unit.5.md +podman-pod.unit.5.md +podman-volume.unit.5.md + diff --git a/docs/source/markdown/links/quadlet.5 b/docs/source/markdown/links/quadlet.5 index 1241a235f5..8b26a55dfd 100644 --- a/docs/source/markdown/links/quadlet.5 +++ b/docs/source/markdown/links/quadlet.5 @@ -1 +1 @@ -.so man5/podman-systemd.unit.5 +.so man7/podman-quadlet.7 diff --git a/docs/source/markdown/options/README.md b/docs/source/markdown/options/README.md index bc3f5bfccb..cb1844f7f1 100644 --- a/docs/source/markdown/options/README.md +++ b/docs/source/markdown/options/README.md @@ -17,6 +17,8 @@ mechanism: ``` @@option foo ! includes options/foo.md +@@option quadlet:foo ! includes options/foo.md with `is_quadlet=True` + ! See "Jinja2 Templating" below. ``` The tool that does this is `hack/markdown-preprocess`. It is a python @@ -25,6 +27,37 @@ file, this script creates a `.md` file that can then be read by `go-md2man`, `sphinx`, anything that groks markdown. This runs as part of `make docs`. +Jinja2 Templating +================= + +Some options are used as both Podman command line option and Quadlet +option. To reduce the duplication, the Jinja2 templating system can be +used to define parts which should be rendered only in Quadlet man-pages: + +``` + {% if is_quadlet %} + ### `DNS=` + {% else %} + #### **--dns**=*ipaddr* + {% endif %} +``` + +It is also possible to use in-line condition: + +``` + {{{ '**DNS=.**' if is_quadlet else '**--dns**' }}} +``` + +Following variables are available for Jinja2 Templates: + +- `is_quadlet`: True if file is imported using `@@option quadlet:foo`. +- `subcommand`: Same as `<>`, see below. +This allows the shared use of examples in the option file: +- `fullcommand`: Same as `<>`, see below. + +For more information about Jinja2, check +https://jinja.palletsprojects.com/en/stable/. + Special Substitutions ===================== diff --git a/docs/source/markdown/options/add-host.md b/docs/source/markdown/options/add-host.md index 316d635d5c..478e050418 100644 --- a/docs/source/markdown/options/add-host.md +++ b/docs/source/markdown/options/add-host.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman build, create, farm build, pod create, run +####> podman build, podman-container.unit.5.md.in, create, farm build, pod create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `AddHost=hostname[;hostname[;...]]:ip` +{% else %} #### **--add-host**=*hostname[;hostname[;...]]*:*ip* +{% endif %} Add a custom host-to-IP mapping to the <>'s `/etc/hosts` file. diff --git a/docs/source/markdown/options/annotation.container.md b/docs/source/markdown/options/annotation.container.md index aadaef264f..edff7c3fab 100644 --- a/docs/source/markdown/options/annotation.container.md +++ b/docs/source/markdown/options/annotation.container.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman create, kube play, run +####> podman podman-container.unit.5.md.in, create, kube play, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Annotation=key=value` +{% else %} #### **--annotation**=*key=value* +{% endif %} Add an annotation to the container<<| or pod>>. This option can be set multiple times. diff --git a/docs/source/markdown/options/annotation.image.md b/docs/source/markdown/options/annotation.image.md index 13964ec23d..1417dcc054 100644 --- a/docs/source/markdown/options/annotation.image.md +++ b/docs/source/markdown/options/annotation.image.md @@ -2,7 +2,11 @@ ####> podman build, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Annotation=annotation=value` +{% else %} #### **--annotation**=*annotation=value* +{% endif %} Add an image *annotation* (e.g. annotation=*value*) to the image metadata. Can be used multiple times. diff --git a/docs/source/markdown/options/arch.md b/docs/source/markdown/options/arch.md index 33cee10299..20806f4b17 100644 --- a/docs/source/markdown/options/arch.md +++ b/docs/source/markdown/options/arch.md @@ -1,7 +1,12 @@ ####> This option file is used in: -####> podman create, pull, run +####> podman podman-build.unit.5.md.in, create, podman-image.unit.5.md.in, pull, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Arch=ARCH` +{% else %} #### **--arch**=*ARCH* +{% endif %} + Override the architecture, defaults to hosts, 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. diff --git a/docs/source/markdown/options/authfile.md b/docs/source/markdown/options/authfile.md index e6724b4b8a..6999d0c98e 100644 --- a/docs/source/markdown/options/authfile.md +++ b/docs/source/markdown/options/authfile.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman artifact pull, artifact push, auto update, build, container runlabel, create, farm build, image sign, kube play, login, logout, manifest add, manifest inspect, manifest push, pull, push, run, search +####> podman artifact pull, artifact push, auto update, build, podman-build.unit.5.md.in, container runlabel, create, farm build, image sign, podman-image.unit.5.md.in, kube play, login, logout, manifest add, manifest inspect, manifest push, pull, push, run, search ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `AuthFile=path` +{% else %} #### **--authfile**=*path* +{% endif %} 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**. diff --git a/docs/source/markdown/options/cap-add.image.md b/docs/source/markdown/options/cap-add.image.md index 1874f558b8..7696578f12 100644 --- a/docs/source/markdown/options/cap-add.image.md +++ b/docs/source/markdown/options/cap-add.image.md @@ -2,7 +2,12 @@ ####> podman build, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `AddCapability=CAP_xxx` +{% else %} #### **--cap-add**=*CAP\_xxx* +{% endif %} + When executing RUN instructions, run the command specified in the instruction with the specified capability added to its capability set. diff --git a/docs/source/markdown/options/cap-add.md b/docs/source/markdown/options/cap-add.md index 67fc2e4d36..ada47189f8 100644 --- a/docs/source/markdown/options/cap-add.md +++ b/docs/source/markdown/options/cap-add.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `AddCapability=capability` +{% else %} #### **--cap-add**=*capability* +{% endif %} Add Linux capabilities. diff --git a/docs/source/markdown/options/cap-drop.md b/docs/source/markdown/options/cap-drop.md index 1baacc96d6..c9333fae56 100644 --- a/docs/source/markdown/options/cap-drop.md +++ b/docs/source/markdown/options/cap-drop.md @@ -1,7 +1,13 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `DropCapability=capability` +{% else %} #### **--cap-drop**=*capability* +{% endif %} -Drop Linux capabilities. +Drop these capabilities from the default podman capability set, or `all` to drop all capabilities. + +This is a space separated list of capabilities. diff --git a/docs/source/markdown/options/cert-dir.md b/docs/source/markdown/options/cert-dir.md index c2bd97dfcc..b32460a8ca 100644 --- a/docs/source/markdown/options/cert-dir.md +++ b/docs/source/markdown/options/cert-dir.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman artifact pull, artifact push, build, container runlabel, create, farm build, image sign, kube play, login, manifest add, manifest push, pull, push, run, search +####> podman artifact pull, artifact push, build, container runlabel, create, farm build, image sign, podman-image.unit.5.md.in, kube play, login, manifest add, manifest push, pull, push, run, search ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `CertDir=path` +{% else %} #### **--cert-dir**=*path* +{% endif %} 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)**. diff --git a/docs/source/markdown/options/cgroups.md b/docs/source/markdown/options/cgroups.md index a5e16e5783..7c557fc3be 100644 --- a/docs/source/markdown/options/cgroups.md +++ b/docs/source/markdown/options/cgroups.md @@ -1,12 +1,24 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `CgroupsMode=how` +{% else %} #### **--cgroups**=*how* +{% endif %} Determines whether the container creates CGroups. +{% if is_quadlet %} +By default, the cgroups mode of the container created by Quadlet is `split`, +which differs from the default (`enabled`) used by the Podman CLI. + +If the container joins a pod (i.e. `Pod=` is specified), you may want to change this to +`no-conmon` or `enabled` so that pod level cgroup resource limits can take effect. +{% else %} Default is **enabled**. +{% endif %} The **enabled** option creates a new cgroup under the cgroup-parent. The **disabled** option forces the container to not create CGroups, and thus conflicts with CGroup options (**--cgroupns** and **--cgroup-parent**). diff --git a/docs/source/markdown/options/creds.md b/docs/source/markdown/options/creds.md index 138dd68d57..747cb294ed 100644 --- a/docs/source/markdown/options/creds.md +++ b/docs/source/markdown/options/creds.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman artifact pull, artifact push, build, container runlabel, create, farm build, kube play, manifest add, manifest push, pull, push, run, search +####> podman artifact pull, artifact push, build, container runlabel, create, farm build, podman-image.unit.5.md.in, kube play, manifest add, manifest push, pull, push, run, search ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Creds=[username[:password]]` +{% else %} #### **--creds**=*[username[:password]]* +{% endif %} 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 diff --git a/docs/source/markdown/options/decryption-key.md b/docs/source/markdown/options/decryption-key.md index ee7ed881bc..2b98acf8d9 100644 --- a/docs/source/markdown/options/decryption-key.md +++ b/docs/source/markdown/options/decryption-key.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman artifact pull, build, create, farm build, pull, run +####> podman artifact pull, build, create, farm build, podman-image.unit.5.md.in, pull, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `DecryptionKey=key[:passphrase]` +{% else %} #### **--decryption-key**=*key[:passphrase]* +{% endif %} 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. diff --git a/docs/source/markdown/options/device.md b/docs/source/markdown/options/device.md index 8875645b93..d13b4b3ca3 100644 --- a/docs/source/markdown/options/device.md +++ b/docs/source/markdown/options/device.md @@ -1,12 +1,18 @@ ####> This option file is used in: -####> podman build, create, farm build, pod clone, pod create, run +####> podman build, podman-container.unit.5.md.in, create, farm build, pod clone, pod create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `AddDevice=host-device[:container-device][:permissions]` +{% else %} #### **--device**=*host-device[:container-device][:permissions]* +{% endif %} -Add a host device to the <>. Optional *permissions* parameter -can be used to specify device permissions by combining -**r** for read, **w** for write, and **m** for **mknod**(2). +Add a host device to the <>. The format of this is +`HOST-DEVICE[:CONTAINER-DEVICE][:PERMISSIONS]`, where `HOST-DEVICE` is the path of +the device node on the host, `CONTAINER-DEVICE` is the path of the device node in +the container, and `PERMISSIONS` is a list of permissions combining 'r' for read, +'w' for write, and 'm' for mknod(2). Example: **--device=/dev/sdc:/dev/xvdc:rwm**. diff --git a/docs/source/markdown/options/dns-option.container.md b/docs/source/markdown/options/dns-option.container.md index f1b57de1a1..430959b7f2 100644 --- a/docs/source/markdown/options/dns-option.container.md +++ b/docs/source/markdown/options/dns-option.container.md @@ -1,7 +1,12 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `DNSOption=option` +{% else %} #### **--dns-option**=*option* +{% endif %} -Set custom DNS options. Invalid if using **--dns-option** with **--network** that is set to **none** or **container:**_id_. +Set custom DNS options. Invalid if using {{{ '**DNSOption=**' if is_quadlet else '**--dns-option**' }}} +with {{{ '**Network=**' if is_quadlet else '**--network**' }}} that is set to **none** or **container:**_id_. diff --git a/docs/source/markdown/options/dns-option.image.md b/docs/source/markdown/options/dns-option.image.md index 345efd47c4..80663a3d8e 100644 --- a/docs/source/markdown/options/dns-option.image.md +++ b/docs/source/markdown/options/dns-option.image.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman build, farm build +####> podman build, podman-build.unit.5.md.in, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `DNSOption=option` +{% else %} #### **--dns-option**=*option* +{% endif %} Set custom DNS options to be used during the build. diff --git a/docs/source/markdown/options/dns-search.container.md b/docs/source/markdown/options/dns-search.container.md index 589e3fa6d6..6f26aca056 100644 --- a/docs/source/markdown/options/dns-search.container.md +++ b/docs/source/markdown/options/dns-search.container.md @@ -1,8 +1,13 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `DNSSearch=domain` +{% else %} #### **--dns-search**=*domain* +{% endif %} -Set custom DNS search domains. Invalid if using **--dns-search** with **--network** that is set to **none** or **container:**_id_. -Use **--dns-search=.** to remove the search domain. +Set custom DNS search domains. Invalid if using {{{ '**DNSSearch=**' if is_quadlet else '**--dns-search**' }}} +with with {{{ '**Network=**' if is_quadlet else '**--network**' }}} that is set to **none** or **container:**_id_. +Use {{{ '**DNSSearch=.**' if is_quadlet else '**--dns-search=.**' }}} to remove the search domain. diff --git a/docs/source/markdown/options/dns-search.image.md b/docs/source/markdown/options/dns-search.image.md index 5e75afde53..fd7f28bcd1 100644 --- a/docs/source/markdown/options/dns-search.image.md +++ b/docs/source/markdown/options/dns-search.image.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman build, farm build +####> podman build, podman-build.unit.5.md.in, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `DNSSearch=domain` +{% else %} #### **--dns-search**=*domain* +{% endif %} Set custom DNS search domains to be used during the build. diff --git a/docs/source/markdown/options/dns.md b/docs/source/markdown/options/dns.md index a02a18e6e5..01e11011e7 100644 --- a/docs/source/markdown/options/dns.md +++ b/docs/source/markdown/options/dns.md @@ -1,15 +1,19 @@ ####> This option file is used in: -####> podman build, create, farm build, run +####> podman build, podman-build.unit.5.md.in, podman-container.unit.5.md.in, create, farm build, podman-network.unit.5.md.in, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `DNS=ipaddr` +{% else %} #### **--dns**=*ipaddr* +{% endif %} Set custom DNS servers. This option can be used to override the DNS configuration passed to the container. Typically this is necessary when the host DNS configuration is invalid for the container (e.g., **127.0.0.1**). When this -is the case the **--dns** flag is necessary for every run. +is the case the {{{ '**DNS=.**' if is_quadlet else '**--dns**' }}} flag is necessary for every run. The special value **none** can be specified to disable creation of _/etc/resolv.conf_ in the container by Podman. The _/etc/resolv.conf_ file in the image is then used without changes. diff --git a/docs/source/markdown/options/entrypoint.md b/docs/source/markdown/options/entrypoint.md index 78fb05a818..e45ab49fc4 100644 --- a/docs/source/markdown/options/entrypoint.md +++ b/docs/source/markdown/options/entrypoint.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Entrypoint="command"` +{% else %} #### **--entrypoint**=*"command"* | *'["command", "arg1", ...]'* +{% endif %} Override the default ENTRYPOINT from the image. @@ -12,7 +16,7 @@ because it specifies what executable to run when the container starts, but it is default nature or behavior. When the ENTRYPOINT is set, the container runs as if it were that binary, complete with default options. More options can be passed in via the COMMAND. But, if a user wants to run -something else inside the container, the **--entrypoint** option allows a new +something else inside the container, the {{{ '**Entrypoint=**' if is_quadlet else '**--entrypoint=.**' }}}option allows a new ENTRYPOINT to be specified. Specify multi option commands in the form of a JSON string. diff --git a/docs/source/markdown/options/env-file.md b/docs/source/markdown/options/env-file.md index 428cb78582..8d0157aa06 100644 --- a/docs/source/markdown/options/env-file.md +++ b/docs/source/markdown/options/env-file.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman create, exec, run +####> podman podman-container.unit.5.md.in, create, exec, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `EnvironmentFile=file` +{% else %} #### **--env-file**=*file* +{% endif %} Read in a line-delimited file of environment variables. diff --git a/docs/source/markdown/options/env-host.md b/docs/source/markdown/options/env-host.md index 53b121cbc2..2e52277f52 100644 --- a/docs/source/markdown/options/env-host.md +++ b/docs/source/markdown/options/env-host.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `EnvironmentHost=` +{% else %} #### **--env-host** +{% endif %} Use host environment inside of the container. See **Environment** note below for precedence. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) diff --git a/docs/source/markdown/options/env.image.md b/docs/source/markdown/options/env.image.md index d214291d53..b4dfad23af 100644 --- a/docs/source/markdown/options/env.image.md +++ b/docs/source/markdown/options/env.image.md @@ -1,11 +1,17 @@ ####> This option file is used in: -####> podman build, farm build +####> podman build, podman-build.unit.5.md.in, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Env=env[=value]` +{% else %} #### **--env**=*env[=value]* +{% endif %} Add a value (e.g. env=*value*) to the built image. Can be used multiple times. If neither `=` nor a *value* are specified, but *env* is set in the current environment, the value from the current environment is added to the image. +{% if not is_quadlet %} To remove an environment variable from the built image, use the `--unsetenv` option. +{% endif %} diff --git a/docs/source/markdown/options/env.md b/docs/source/markdown/options/env.md index 19bfc42ae4..74fb020a53 100644 --- a/docs/source/markdown/options/env.md +++ b/docs/source/markdown/options/env.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, exec, run +####> podman podman-container.unit.5.md.in, create, exec, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Environment=env` +{% else %} #### **--env**, **-e**=*env* +{% endif %} Set environment variables. diff --git a/docs/source/markdown/options/expose.md b/docs/source/markdown/options/expose.md index 745e25226c..98bae64ad1 100644 --- a/docs/source/markdown/options/expose.md +++ b/docs/source/markdown/options/expose.md @@ -1,12 +1,16 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `ExposeHostPort=port[/protocol]` +{% else %} #### **--expose**=*port[/protocol]* +{% endif %} -Expose a port or a range of ports (e.g. **--expose=3300-3310**). +Expose a port or a range of ports (e.g. {{{ '**Expose=3300-3310**' if is_quadlet else '**--expose=3300-3310**' }}}). The protocol can be `tcp`, `udp` or `sctp` and if not given `tcp` is assumed. This option matches the EXPOSE instruction for image builds and has no effect on the actual networking rules unless **-P/--publish-all** is used to forward to all exposed ports from random host ports. To forward specific ports from the host -into the container use the **-p/--publish** option instead. +into the container use the {{{ '**PublishPort=**' if is_quadlet else '**-p/--publish**' }}} option instead. diff --git a/docs/source/markdown/options/file.md b/docs/source/markdown/options/file.md index 60c3aea5ad..2b589417bc 100644 --- a/docs/source/markdown/options/file.md +++ b/docs/source/markdown/options/file.md @@ -1,16 +1,31 @@ ####> This option file is used in: -####> podman build, farm build +####> podman build, podman-build.unit.5.md.in, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `File=Containerfile` +{% else %} #### **--file**, **-f**=*Containerfile* +{% endif %} + Specifies a Containerfile which contains instructions for building the image, either a local file or an **http** or **https** URL. If more than one Containerfile is specified, *FROM* instructions are only be accepted from the last specified file. +{% if is_quadlet %} +Note that for a given relative path to a Containerfile, or when using a `http(s)://` URL, you also must set +`SetWorkingDirectory=` in order for `podman build` to find a valid context directory for the +resources specified in the Containerfile. + +Note that setting a `File=` field is mandatory for a `.build` file, unless `SetWorkingDirectory` (or +a `WorkingDirectory` in the `Service` group) has also been set. +{% else %} If a build context is not specified, and at least one Containerfile is a local file, the directory in which it resides is used as the build context. +{% endif %} -Specifying the option `-f -` causes the Containerfile contents to be read from stdin. +Specifying the option {{{ 'File=-' if is_quadlet else '`-f -`' }}} causes +the Containerfile contents to be read from stdin. diff --git a/docs/source/markdown/options/force-rm.md b/docs/source/markdown/options/force-rm.md index 5af1f5a8af..04a8707499 100644 --- a/docs/source/markdown/options/force-rm.md +++ b/docs/source/markdown/options/force-rm.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman build, farm build +####> podman build, podman-build.unit.5.md.in, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `ForceRm=` +{% else %} #### **--force-rm** +{% endif %} Always remove intermediate containers after a build, even if the build fails (default true). diff --git a/docs/source/markdown/options/gidmap.container.md b/docs/source/markdown/options/gidmap.container.md index 0f4cfa86b0..5b9f94691b 100644 --- a/docs/source/markdown/options/gidmap.container.md +++ b/docs/source/markdown/options/gidmap.container.md @@ -1,12 +1,19 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `GIDMap=[flags]container_uid:from_uid[:amount]` +{% else %} #### **--gidmap**=*[flags]container_uid:from_uid[:amount]* +{% endif %} -Run the container in a new user namespace using the supplied GID mapping. This -option conflicts with the **--userns** and **--subgidname** options. This +un the container in a new user namespace using the supplied GID mapping. This +option conflicts with the {{{ '**UserNS=**' if is_quadlet else '**--userns**' }}} and +{{{ '**SubGIDMap=**' if is_quadlet else '**--subgidname**' }}} options. This option provides a way to map host GIDs to container GIDs in the same way as __--uidmap__ maps host UIDs to container UIDs. For details see __--uidmap__. -Note: the **--gidmap** option cannot be called in conjunction with the **--pod** option as a gidmap cannot be set on the container level when in a pod. +Note: the {{{ '**GIDMap=**' if is_quadlet else '**--gidmap**' }}} option cannot be +called in conjunction with the {{{ '**Pod=**' if is_quadlet else '**--pod**' }}} option as +a gidmap cannot be set on the container level when in a pod. diff --git a/docs/source/markdown/options/group-add.md b/docs/source/markdown/options/group-add.md index dadb8b4f1c..8e33c86bda 100644 --- a/docs/source/markdown/options/group-add.md +++ b/docs/source/markdown/options/group-add.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman build, create, farm build, run +####> podman build, podman-build.unit.5.md.in, podman-container.unit.5.md.in, create, farm build, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `GroupAdd=group | keep-groups` +{% else %} #### **--group-add**=*group* | *keep-groups* +{% endif %} Assign additional groups to the primary user running within the container process. diff --git a/docs/source/markdown/options/health-cmd.md b/docs/source/markdown/options/health-cmd.md index cc1587796d..189274c5f4 100644 --- a/docs/source/markdown/options/health-cmd.md +++ b/docs/source/markdown/options/health-cmd.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `HealthCmd="command"` +{% else %} #### **--health-cmd**=*"command"* | *'["command", "arg1", ...]'* +{% endif %} Set or alter a healthcheck command for a container. The command is a command to be executed inside the container that determines the container health. The command is required for other healthcheck options diff --git a/docs/source/markdown/options/health-interval.md b/docs/source/markdown/options/health-interval.md index 2657187e59..71bcce75ff 100644 --- a/docs/source/markdown/options/health-interval.md +++ b/docs/source/markdown/options/health-interval.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `HealthInterval=interval` +{% else %} #### **--health-interval**=*interval* +{% endif %} Set an interval for the healthchecks. An _interval_ of **disable** results in no automatic timer setup. The default is **30s**. diff --git a/docs/source/markdown/options/health-log-destination.md b/docs/source/markdown/options/health-log-destination.md index 91e91e269c..bda61b3046 100644 --- a/docs/source/markdown/options/health-log-destination.md +++ b/docs/source/markdown/options/health-log-destination.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `HealthLogDestination=directory_path` +{% else %} #### **--health-log-destination**=*directory_path* +{% endif %} Set the destination of the HealthCheck log. Directory path, local or events_logger (local use container state file) (Default: local) diff --git a/docs/source/markdown/options/health-max-log-count.md b/docs/source/markdown/options/health-max-log-count.md index 137d470830..900a4649a4 100644 --- a/docs/source/markdown/options/health-max-log-count.md +++ b/docs/source/markdown/options/health-max-log-count.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `HealthMaxLogCount=number` +{% else %} #### **--health-max-log-count**=*number of stored logs* +{% endif %} Set maximum number of attempts in the HealthCheck log file. ('0' value means an infinite number of attempts in the log file) (Default: 5 attempts) diff --git a/docs/source/markdown/options/health-max-log-size.md b/docs/source/markdown/options/health-max-log-size.md index 1c3169c7f4..3ada0d76e9 100644 --- a/docs/source/markdown/options/health-max-log-size.md +++ b/docs/source/markdown/options/health-max-log-size.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `HealthMaxLogSize=size` +{% else %} #### **--health-max-log-size**=*size of stored logs* +{% endif %} Set maximum length in characters of stored HealthCheck log. ("0" value means an infinite log length) (Default: 500 characters) diff --git a/docs/source/markdown/options/health-on-failure.md b/docs/source/markdown/options/health-on-failure.md index 6c539e7332..cf82c0668b 100644 --- a/docs/source/markdown/options/health-on-failure.md +++ b/docs/source/markdown/options/health-on-failure.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `HealthOnFailure=action` +{% else %} #### **--health-on-failure**=*action* +{% endif %} Action to take once the container transitions to an unhealthy state. The default is **none**. diff --git a/docs/source/markdown/options/health-retries.md b/docs/source/markdown/options/health-retries.md index 4060fb30ed..07e23351f6 100644 --- a/docs/source/markdown/options/health-retries.md +++ b/docs/source/markdown/options/health-retries.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `HealthRetries=retries` +{% else %} #### **--health-retries**=*retries* +{% endif %} The number of retries allowed before a healthcheck is considered to be unhealthy. The default value is **3**. diff --git a/docs/source/markdown/options/health-start-period.md b/docs/source/markdown/options/health-start-period.md index 302af88072..9a6a61492d 100644 --- a/docs/source/markdown/options/health-start-period.md +++ b/docs/source/markdown/options/health-start-period.md @@ -1,16 +1,23 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `HealthStartPeriod=period` +{% else %} #### **--health-start-period**=*period* +{% endif %} The initialization time needed for a container to bootstrap. The value can be expressed in time format like **2m3s**. The default value is **0s**. Note: The health check command is executed as soon as a container is started, if the health check is successful the container's health state will be updated to `healthy`. However, if the health check fails, the health state will -stay as `starting` until either the health check is successful or until the `--health-start-period` time is over. If the -health check command fails after the `--health-start-period` time is over, the health state will be updated to `unhealthy`. -The health check command is executed periodically based on the value of `--health-interval`. +stay as `starting` until either the health check is successful or until +the {{{ '`HealthStartPeriod=`' if is_quadlet else '`--health-start-period`' }}} time is over. If the +health check command fails after the {{{ '`HealthStartPeriod=`' if is_quadlet else '`--health-start-period`' }}} +time is over, the health state will be updated to `unhealthy`. +The health check command is executed periodically based on the value of +{{{ '`HealthInternal=`' if is_quadlet else '`--health-interval`' }}}. Note: This parameter will overwrite related healthcheck configuration from the image. diff --git a/docs/source/markdown/options/health-startup-cmd.md b/docs/source/markdown/options/health-startup-cmd.md index 67b2db32ad..20e3debdd8 100644 --- a/docs/source/markdown/options/health-startup-cmd.md +++ b/docs/source/markdown/options/health-startup-cmd.md @@ -1,11 +1,16 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `HealthStartupCmd="command"` +{% else %} #### **--health-startup-cmd**=*"command"* | *'["command", "arg1", ...]'* +{% endif %} Set a startup healthcheck command for a container. This command is executed inside the container and is used to gate the regular healthcheck. When the startup command succeeds, the regular healthcheck begins and the startup healthcheck ceases. Optionally, if the command fails for a set number of attempts, the container is restarted. A startup healthcheck can be used to ensure that containers with an extended startup period are not marked as unhealthy until they are fully started. Startup healthchecks can only be -used when a regular healthcheck (from the container's image or the **--health-cmd** option) is also set. +used when a regular healthcheck (from the container's image or the +{{{ '`HealthCmd=`' if is_quadlet else '`--health-cmd`' }}} option) is also set. diff --git a/docs/source/markdown/options/health-startup-interval.md b/docs/source/markdown/options/health-startup-interval.md index 052d703a78..0149573cbc 100644 --- a/docs/source/markdown/options/health-startup-interval.md +++ b/docs/source/markdown/options/health-startup-interval.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `HealthStartupInterval=interval` +{% else %} #### **--health-startup-interval**=*interval* +{% endif %} Set an interval for the startup healthcheck. An _interval_ of **disable** results in no automatic timer setup. The default is **30s**. diff --git a/docs/source/markdown/options/health-startup-retries.md b/docs/source/markdown/options/health-startup-retries.md index 2a0f9fdf90..30401b87aa 100644 --- a/docs/source/markdown/options/health-startup-retries.md +++ b/docs/source/markdown/options/health-startup-retries.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `HealthStartupRetries=retries` +{% else %} #### **--health-startup-retries**=*retries* +{% endif %} The number of attempts allowed before the startup healthcheck restarts the container. If set to **0**, the container is never restarted. The default is **0**. diff --git a/docs/source/markdown/options/health-startup-success.md b/docs/source/markdown/options/health-startup-success.md index e1f911b215..9577cf73b6 100644 --- a/docs/source/markdown/options/health-startup-success.md +++ b/docs/source/markdown/options/health-startup-success.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `HealthStartupSuccess=retries` +{% else %} #### **--health-startup-success**=*retries* +{% endif %} The number of successful runs required before the startup healthcheck succeeds and the regular healthcheck begins. A value of **0** means that any success begins the regular healthcheck. The default is **0**. diff --git a/docs/source/markdown/options/health-startup-timeout.md b/docs/source/markdown/options/health-startup-timeout.md index deffa14025..671ecf5db5 100644 --- a/docs/source/markdown/options/health-startup-timeout.md +++ b/docs/source/markdown/options/health-startup-timeout.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `HealthStartupTimeout=timeout` +{% else %} #### **--health-startup-timeout**=*timeout* +{% endif %} The maximum time a startup healthcheck command has to complete before it is marked as failed. The value can be expressed in a time format like **2m3s**. The default value is **30s**. diff --git a/docs/source/markdown/options/health-timeout.md b/docs/source/markdown/options/health-timeout.md index 458442508b..8bbe0c9b48 100644 --- a/docs/source/markdown/options/health-timeout.md +++ b/docs/source/markdown/options/health-timeout.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `HealthTimeout=timeout` +{% else %} #### **--health-timeout**=*timeout* +{% endif %} The maximum time allowed to complete the healthcheck before an interval is considered failed. Like start-period, the value can be expressed in a time format such as **1m22s**. The default value is **30s**. diff --git a/docs/source/markdown/options/hostname.container.md b/docs/source/markdown/options/hostname.container.md index ab7e76c9ed..4c1c108b9b 100644 --- a/docs/source/markdown/options/hostname.container.md +++ b/docs/source/markdown/options/hostname.container.md @@ -1,13 +1,17 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `HostName=name` +{% else %} #### **--hostname**, **-h**=*name* +{% endif %} Set the container's hostname inside the container. This option can only be used with a private UTS namespace `--uts=private` -(default). If `--pod` is given and the pod shares the same UTS namespace +(default). If {{{ '`Pod=`' if is_quadlet else '`--pod`' }}} is given and the pod shares the same UTS namespace (default), the pod's hostname is used. The given hostname is also added to the `/etc/hosts` file using the container's primary IP address (also see the -**--add-host** option). +{{{ '**AddHost=**' if is_quadlet else '**--add-host**' }}} option). diff --git a/docs/source/markdown/options/init.md b/docs/source/markdown/options/init.md index 5a9fb2f29e..c8e8dc8da1 100644 --- a/docs/source/markdown/options/init.md +++ b/docs/source/markdown/options/init.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Init=` +{% else %} #### **--init** +{% endif %} Run an init inside the container that forwards signals and reaps processes. The container-init binary is mounted at `/run/podman-init`. diff --git a/docs/source/markdown/options/ip.md b/docs/source/markdown/options/ip.md index d3c865a88d..a5997dd0c3 100644 --- a/docs/source/markdown/options/ip.md +++ b/docs/source/markdown/options/ip.md @@ -1,12 +1,20 @@ ####> This option file is used in: -####> podman create, pod create, run +####> podman podman-container.unit.5.md.in, create, pod create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `IP=ipv4` +{% else %} #### **--ip**=*ipv4* +{% endif %} Specify a static IPv4 address for the <>, for example **10.88.64.128**. -This option can only be used if the <> is joined to only a single network - i.e., **--network=network-name** is used at most once - -and if the <> is not joining another container's network namespace via **--network=container:_id_**. +This option can only be used if the <> is joined to only a single network - i.e., +{{{ '**Network=network-name**' if is_quadlet else '**--network=network-name**' }}} is used at most once - +and if the <> is not joining another container's network namespace via +{{{ '**Network=container:_id_**' if is_quadlet else '**--network=container:_id_**' }}}. The address must be within the network's IP address pool (default **10.88.0.0/16**). -To specify multiple static IP addresses per <>, set multiple networks using the **--network** option with a static IP address specified for each using the `ip` mode for that option. +To specify multiple static IP addresses per <>, set multiple networks using +the {{{ '**Network=**' if is_quadlet else '**--network' }}} option with a static IP address +specified for each using the `ip` mode for that option. diff --git a/docs/source/markdown/options/ip6.md b/docs/source/markdown/options/ip6.md index a2dd619f72..67e6302c4a 100644 --- a/docs/source/markdown/options/ip6.md +++ b/docs/source/markdown/options/ip6.md @@ -1,12 +1,20 @@ ####> This option file is used in: -####> podman create, pod create, run +####> podman podman-container.unit.5.md.in, create, pod create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `IP6=ipv6` +{% else %} #### **--ip6**=*ipv6* +{% endif %} Specify a static IPv6 address for the <>, for example **fd46:db93:aa76:ac37::10**. -This option can only be used if the <> is joined to only a single network - i.e., **--network=network-name** is used at most once - -and if the <> is not joining another container's network namespace via **--network=container:_id_**. +This option can only be used if the <> is joined to only a single network - i.e., +{{{ '**Network=network-name**' if is_quadlet else '**--network=network-name**' }}} is used at most once - +and if the <> is not joining another container's network namespace via +{{{ '**Network=container:_id_**' if is_quadlet else '**--network=container:_id_**' }}}. The address must be within the network's IPv6 address pool. -To specify multiple static IPv6 addresses per <>, set multiple networks using the **--network** option with a static IPv6 address specified for each using the `ip6` mode for that option. +To specify multiple static IPv6 addresses per <>, set multiple networks using the +{{{ '**Network=**' if is_quadlet else '**--network' }}} option with a static IPv6 address +specified for each using the `ip6` mode for that option. diff --git a/docs/source/markdown/options/label.image.md b/docs/source/markdown/options/label.image.md index d119c43625..fa930c5b79 100644 --- a/docs/source/markdown/options/label.image.md +++ b/docs/source/markdown/options/label.image.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman build, farm build +####> podman build, podman-build.unit.5.md.in, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Label=label` +{% else %} #### **--label**=*label* +{% endif %} Add an image *label* (e.g. label=*value*) to the image metadata. Can be used multiple times. diff --git a/docs/source/markdown/options/label.md b/docs/source/markdown/options/label.md index af88b3f95f..ff19f3f94c 100644 --- a/docs/source/markdown/options/label.md +++ b/docs/source/markdown/options/label.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman create, pod clone, pod create, run +####> podman podman-container.unit.5.md.in, create, pod clone, pod create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Label=key=value` +{% else %} #### **--label**, **-l**=*key=value* +{% endif %} Add metadata to a <>. diff --git a/docs/source/markdown/options/log-driver.md b/docs/source/markdown/options/log-driver.md index d99f229c5e..81b3f73918 100644 --- a/docs/source/markdown/options/log-driver.md +++ b/docs/source/markdown/options/log-driver.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, podman-kube.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `LogDriver=driver` +{% else %} #### **--log-driver**=*driver* +{% endif %} Logging driver for the container. Currently available options are **k8s-file**, **journald**, **none**, **passthrough** and **passthrough-tty**, with **json-file** aliased to **k8s-file** for scripting compatibility. (Default **journald**). diff --git a/docs/source/markdown/options/log-opt.md b/docs/source/markdown/options/log-opt.md index 9cb1402ae3..0356425545 100644 --- a/docs/source/markdown/options/log-opt.md +++ b/docs/source/markdown/options/log-opt.md @@ -1,20 +1,24 @@ ####> This option file is used in: -####> podman create, kube play, run +####> podman podman-container.unit.5.md.in, create, kube play, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `LogOpt=name=value` +{% else %} #### **--log-opt**=*name=value* +{% endif %} Logging driver specific options. Set custom logging configuration. The following *name*s are supported: **path**: specify a path to the log file - (e.g. **--log-opt path=/var/log/container/mycontainer.json**); + (e.g. {{{ '**LogOpt=path=/var/log/container/mycontainer.json**' if is_quadlet else '**--log-opt path=/var/log/container/mycontainer.json**' }}}); **max-size**: specify a max size of the log file - (e.g. **--log-opt max-size=10mb**); + (e.g. {{{ '**LogOpt=max-size=10mb**' if is_quadlet else '**--log-opt max-size=10mb**' }}}); **tag**: specify a custom log tag for the container - (e.g. **--log-opt tag="{{.ImageName}}"**. + (e.g. {{{ '**LogOpt=tag="{{.ImageName}}"**' if is_quadlet else '**--log-opt tag="{{.ImageName}}"**' }}}. It supports the same keys as **podman inspect --format**. This option is currently supported only by the **journald** log driver. diff --git a/docs/source/markdown/options/memory.md b/docs/source/markdown/options/memory.md index dd53d8d8e6..bfe6194340 100644 --- a/docs/source/markdown/options/memory.md +++ b/docs/source/markdown/options/memory.md @@ -1,14 +1,18 @@ ####> This option file is used in: -####> podman build, container clone, create, farm build, pod clone, pod create, run, update +####> podman build, container clone, podman-container.unit.5.md.in, create, farm build, pod clone, pod create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Memory=number[unit]` +{% else %} #### **--memory**, **-m**=*number[unit]* +{% endif %} Memory limit. A _unit_ can be **b** (bytes), **k** (kibibytes), **m** (mebibytes), or **g** (gibibytes). Allows the memory available to a container to be constrained. If the host -supports swap memory, then the **-m** memory setting can be larger than physical -RAM. If a limit of 0 is specified (not using **-m**), the container's memory is +supports swap memory, then the {{{ '**Memory=**' if is_quadlet else '**--m**' }}} memory setting can be larger than physical +RAM. If a limit of 0 is specified (not using {{{ '**Memory=**' if is_quadlet else '**--m**' }}}), the container's memory is not limited. The actual limit may be rounded up to a multiple of the operating system's page size (the value is very large, that's millions of trillions). diff --git a/docs/source/markdown/options/module.md b/docs/source/markdown/options/module.md new file mode 100644 index 0000000000..c5a4a3c7bb --- /dev/null +++ b/docs/source/markdown/options/module.md @@ -0,0 +1,13 @@ +####> This option file is used in: +####> podman podman-build.unit.5.md.in, podman-container.unit.5.md.in, podman-image.unit.5.md.in, podman-kube.unit.5.md.in, podman-network.unit.5.md.in, podman-pod.unit.5.md.in, podman-volume.unit.5.md.in +####> If file is edited, make sure the changes +####> are applicable to all of those. +{% if is_quadlet %} +### `ContainersConfModule=module` +{% else %} +#### **--module**=*module* +{% endif %} + +Load the specified containers.conf(5) module. + +This option can be listed multiple times. diff --git a/docs/source/markdown/options/mount.md b/docs/source/markdown/options/mount.md index bf03d05099..29e394c116 100644 --- a/docs/source/markdown/options/mount.md +++ b/docs/source/markdown/options/mount.md @@ -1,11 +1,24 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]` +{% else %} #### **--mount**=*type=TYPE,TYPE-SPECIFIC-OPTION[,...]* +{% endif %} Attach a filesystem mount to the container. +{% if is_quadlet %} +Special cases: + +* For `type=volume`, if `source` ends with `.volume`, the Podman named volume generated by the corresponding `.volume` file is used. +* For `type=image`, if `source` ends with `.image`, the image generated by the corresponding `.image` file is used. + +In both cases, the generated systemd service will contain a dependency on the service generated for the corresponding unit. Note: the corresponding `.volume` or `.image` file must exist. +{% endif %} + Current supported mount TYPEs are **artifact**, **bind**, **devpts**, **glob**, **image**, **ramfs**, **tmpfs** and **volume**. Options common to all mount types: diff --git a/docs/source/markdown/options/name.container.md b/docs/source/markdown/options/name.container.md index b7b454bc0b..8eec83e353 100644 --- a/docs/source/markdown/options/name.container.md +++ b/docs/source/markdown/options/name.container.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `ContainerName=name` +{% else %} #### **--name**=*name* +{% endif %} Assign a name to the container. @@ -13,8 +17,9 @@ The operator can identify a container in three ways: - Name (“jonah”). Podman generates a UUID for each container, and if no name is assigned to the -container using **--name**, Podman generates a random string name. The name can +container using {{{ '**ContainerName=**' if is_quadlet else '**--name**' }}}, +Podman generates a random string name. The name can be useful as a more human-friendly way to identify containers. This works for both background and foreground containers. The container's name is also added to the `/etc/hosts` file using the container's primary IP address (also see the -**--add-host** option). +{{{ '**AddHost=**' if is_quadlet else '**--add-host**' }}} option). diff --git a/docs/source/markdown/options/network-alias.md b/docs/source/markdown/options/network-alias.md index 3c0ed9c9db..29a9d0f83d 100644 --- a/docs/source/markdown/options/network-alias.md +++ b/docs/source/markdown/options/network-alias.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, pod create, run +####> podman podman-container.unit.5.md.in, create, pod create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `NetworkAlias=alias` +{% else %} #### **--network-alias**=*alias* +{% endif %} Add a network-scoped alias for the <>, setting the alias for all networks that the container joins. To set a name only for a specific network, use the alias option as described under the **--network** option. diff --git a/docs/source/markdown/options/network.image.md b/docs/source/markdown/options/network.image.md index f03a38d9ca..2aab4b02cd 100644 --- a/docs/source/markdown/options/network.image.md +++ b/docs/source/markdown/options/network.image.md @@ -1,11 +1,21 @@ ####> This option file is used in: -####> podman build, farm build +####> podman build, podman-build.unit.5.md.in, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Network=mode` +{% else %} #### **--network**=*mode*, **--net** +{% endif %} Sets the configuration for network namespaces when handling `RUN` instructions. +{% if is_quadlet %} +Special case: + +* If the `name` of the network ends with `.network`, Quadlet will look for the corresponding `.network` Quadlet unit. If found, Quadlet will use the name of the Network set in the Unit, otherwise, `systemd-$name` is used. The generated systemd service contains a dependency on the service unit generated for that `.network` unit, or on `$name-network.service` if the `.network` unit is not found. Note: the corresponding `.network` file must exist. +{% endif %} + Valid _mode_ values are: - **none**: no networking. diff --git a/docs/source/markdown/options/network.md b/docs/source/markdown/options/network.md index eb0d304f4a..381be6e588 100644 --- a/docs/source/markdown/options/network.md +++ b/docs/source/markdown/options/network.md @@ -1,11 +1,28 @@ ####> This option file is used in: -####> podman create, kube play, pod create, run +####> podman podman-container.unit.5.md.in, create, kube play, podman-kube.unit.5.md.in, pod create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Network=mode` +{% else %} #### **--network**=*mode*, **--net** +{% endif %} Set the network mode for the <>. +{% if is_quadlet %} +Special cases: + +* If the `name` of the network ends with `.network`, a Podman network called +`systemd-$name` is used, and the generated systemd service contains +a dependency on the `$name-network.service`. Such a network can be automatically +created by using a `$name.network` Quadlet file. Note: the corresponding `.network` file must exist. + +* If the `name` ends with `.container`, +the container will reuse the network stack of another container created by `$name.container`. +The generated systemd service contains a dependency on `$name.service`. Note: the corresponding `.container` file must exist. +{% endif %} + Valid _mode_ values are: - **bridge[:OPTIONS,...]**: Create a network stack on the default bridge. This is the default for rootful containers. It is possible to specify these additional options: diff --git a/docs/source/markdown/options/os.pull.md b/docs/source/markdown/options/os.pull.md index aeb0bdbe5d..50866c1017 100644 --- a/docs/source/markdown/options/os.pull.md +++ b/docs/source/markdown/options/os.pull.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, pull, run +####> podman create, podman-image.unit.5.md.in, pull, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `OS=os` +{% else %} #### **--os**=*OS* +{% endif %} Override the OS, defaults to hosts, 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. diff --git a/docs/source/markdown/options/pids-limit.md b/docs/source/markdown/options/pids-limit.md index d59f6c82b0..69dfb7108c 100644 --- a/docs/source/markdown/options/pids-limit.md +++ b/docs/source/markdown/options/pids-limit.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `PidsLimit=limit` +{% else %} #### **--pids-limit**=*limit* +{% endif %} Tune the container's pids limit. Set to **-1** to have unlimited pids for the container. The default is **2048** on systems that support "pids" cgroup controller. diff --git a/docs/source/markdown/options/publish.md b/docs/source/markdown/options/publish.md index 05ec22f197..f644a70500 100644 --- a/docs/source/markdown/options/publish.md +++ b/docs/source/markdown/options/publish.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, pod create, run +####> podman podman-container.unit.5.md.in, create, podman-kube.unit.5.md.in, pod create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `PublishPort=[[ip:][hostPort]:]containerPort[/protocol]` +{% else %} #### **--publish**, **-p**=*[[ip:][hostPort]:]containerPort[/protocol]* +{% endif %} Publish a container's port, or range of ports,<<| within this pod>> to the host. diff --git a/docs/source/markdown/options/pull.image.md b/docs/source/markdown/options/pull.image.md index 112e612210..f556dd17e8 100644 --- a/docs/source/markdown/options/pull.image.md +++ b/docs/source/markdown/options/pull.image.md @@ -2,7 +2,11 @@ ####> podman build, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Pull=policy` +{% else %} #### **--pull**=*policy* +{% endif %} Pull image policy. The default is **missing**. diff --git a/docs/source/markdown/options/pull.md b/docs/source/markdown/options/pull.md index e8c2090aba..63cc6b0ac2 100644 --- a/docs/source/markdown/options/pull.md +++ b/docs/source/markdown/options/pull.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-build.unit.5.md.in, podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Pull=policy` +{% else %} #### **--pull**=*policy* +{% endif %} Pull image policy. The default is **missing**. diff --git a/docs/source/markdown/options/read-only-tmpfs.md b/docs/source/markdown/options/read-only-tmpfs.md index 246dff0d87..57e83a3ba7 100644 --- a/docs/source/markdown/options/read-only-tmpfs.md +++ b/docs/source/markdown/options/read-only-tmpfs.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `ReadOnlyTmpfs=` +{% else %} #### **--read-only-tmpfs** +{% endif %} When running --read-only containers, mount a read-write tmpfs on _/dev_, _/dev/shm_, _/run_, _/tmp_, and _/var/tmp_. The default is **true**. @@ -13,14 +17,17 @@ When running --read-only containers, mount a read-write tmpfs on _/dev_, _/dev/s | false | false | r/w | r/w | | false | true | r/w | r/w | -When **--read-only=true** and **--read-only-tmpfs=true** additional tmpfs are mounted on + +When {{{ '**ReadOnly=true**' if is_quadlet else '**--read-only==true**' }}} and +{{{ '**ReadOnlyTmpfs=true**' if is_quadlet else '**--read-only-tmpfs==true**' }}} additional tmpfs are mounted on the /tmp, /run, and /var/tmp directories. -When **--read-only=true** and **--read-only-tmpfs=false** /dev and /dev/shm are marked +When {{{ '**ReadOnly=true**' if is_quadlet else '**--read-only==true**' }}} and +{{{ '**ReadOnlyTmpfs=false**' if is_quadlet else '**--read-only-tmpfs==false**' }}} /dev and /dev/shm are marked Read/Only and no tmpfs are mounted on /tmp, /run and /var/tmp. The directories are exposed from the underlying image, meaning they are read-only by default. This makes the container totally read-only. No writable directories exist within the container. In this mode writable directories need to be added via external volumes or mounts. -By default, when **--read-only=false**, the /dev and /dev/shm are read/write, and the /tmp, /run, and /var/tmp are read/write directories from the container image. +By default, when {{{ '**ReadOnly=false**' if is_quadlet else '**--read-only==false**' }}} , the /dev and /dev/shm are read/write, and the /tmp, /run, and /var/tmp are read/write directories from the container image. diff --git a/docs/source/markdown/options/read-only.md b/docs/source/markdown/options/read-only.md index 3c16f65a39..efac96c678 100644 --- a/docs/source/markdown/options/read-only.md +++ b/docs/source/markdown/options/read-only.md @@ -1,10 +1,15 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `ReadOnly=` +{% else %} #### **--read-only** +{% endif %} Mount the container's root filesystem as read-only. By default, container root filesystems are writable, allowing processes -to write files anywhere. By specifying the **--read-only** flag, the containers root filesystem are mounted read-only prohibiting any writes. +to write files anywhere. By specifying the {{{ '**ReadOnly=**' if is_quadlet else '**--read-only**' }}} flag, +the containers root filesystem are mounted read-only prohibiting any writes. diff --git a/docs/source/markdown/options/restart.md b/docs/source/markdown/options/restart.md index 74e4e7814f..94237b83cc 100644 --- a/docs/source/markdown/options/restart.md +++ b/docs/source/markdown/options/restart.md @@ -19,4 +19,4 @@ Podman provides a systemd unit file, podman-restart.service, which restarts cont When running containers in systemd services, use the restart functionality provided by systemd. In other words, do not use this option in a container unit, instead set the `Restart=` systemd directive in the `[Service]` section. -See **podman-systemd.unit**(5) and **systemd.service**(5). +See **podman-quadlet**(7) and **systemd.service**(5). diff --git a/docs/source/markdown/options/retry-delay.md b/docs/source/markdown/options/retry-delay.md index 14c652ffb1..a8b7a3b72e 100644 --- a/docs/source/markdown/options/retry-delay.md +++ b/docs/source/markdown/options/retry-delay.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman artifact pull, artifact push, build, create, farm build, pull, push, run +####> podman artifact pull, artifact push, build, podman-build.unit.5.md.in, podman-container.unit.5.md.in, create, farm build, podman-image.unit.5.md.in, pull, push, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `RetryDelay=duration` +{% else %} #### **--retry-delay**=*duration* +{% endif %} 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. diff --git a/docs/source/markdown/options/retry.md b/docs/source/markdown/options/retry.md index 08c8c263e3..c07dd2307f 100644 --- a/docs/source/markdown/options/retry.md +++ b/docs/source/markdown/options/retry.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman artifact pull, artifact push, build, create, farm build, pull, push, run +####> podman artifact pull, artifact push, build, podman-build.unit.5.md.in, podman-container.unit.5.md.in, create, farm build, podman-image.unit.5.md.in, pull, push, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Retry=attempts` +{% else %} #### **--retry**=*attempts* +{% endif %} Number of times to retry pulling or pushing images between the registry and local storage in case of failure. Default is **3**. diff --git a/docs/source/markdown/options/rootfs.md b/docs/source/markdown/options/rootfs.md index a30e878ff7..495278344f 100644 --- a/docs/source/markdown/options/rootfs.md +++ b/docs/source/markdown/options/rootfs.md @@ -1,11 +1,19 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Rootfs=` +{% else %} #### **--rootfs** +{% endif %} If specified, the first argument refers to an exploded container on the file system. +{% if is_quadlet %} +This option conflicts with the `Image` option. + +{% endif %} This is useful to run a container without requiring any image management, the rootfs of the container is assumed to be managed externally. diff --git a/docs/source/markdown/options/secret.image.md b/docs/source/markdown/options/secret.image.md index 46f8ff0f97..bc5bf48fdf 100644 --- a/docs/source/markdown/options/secret.image.md +++ b/docs/source/markdown/options/secret.image.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman build, farm build +####> podman build, podman-build.unit.5.md.in, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Secret=id=id[,src=envOrFile][,env=ENV][,type=file | env]` +{% else %} #### **--secret**=**id=id[,src=*envOrFile*][,env=*ENV*][,type=*file* | *env*]** +{% endif %} Pass secret information to be used in the Containerfile for building images in a safe way that will not end up stored in the final image, or be seen in other stages. diff --git a/docs/source/markdown/options/secret.md b/docs/source/markdown/options/secret.md index 7b8f6e0397..c2d1a9e604 100644 --- a/docs/source/markdown/options/secret.md +++ b/docs/source/markdown/options/secret.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Secret=secret[,opt=opt ...]` +{% else %} #### **--secret**=*secret[,opt=opt ...]* +{% endif %} Give the container access to a secret. Can be specified multiple times. diff --git a/docs/source/markdown/options/shm-size.md b/docs/source/markdown/options/shm-size.md index 0f51a3f193..fc9260964c 100644 --- a/docs/source/markdown/options/shm-size.md +++ b/docs/source/markdown/options/shm-size.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman build, create, farm build, pod clone, pod create, run +####> podman build, podman-container.unit.5.md.in, create, farm build, pod clone, pod create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `ShmSize=number[unit]` +{% else %} #### **--shm-size**=*number[unit]* +{% endif %} Size of _/dev/shm_. A _unit_ can be **b** (bytes), **k** (kibibytes), **m** (mebibytes), or **g** (gibibytes). If the unit is omitted, the system uses bytes. If the size is omitted, the default is **64m**. diff --git a/docs/source/markdown/options/stop-signal.md b/docs/source/markdown/options/stop-signal.md index efbca84cf7..cf77adb072 100644 --- a/docs/source/markdown/options/stop-signal.md +++ b/docs/source/markdown/options/stop-signal.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `StopSignal=signal` +{% else %} #### **--stop-signal**=*signal* +{% endif %} Signal to stop a container. Default is **SIGTERM**. diff --git a/docs/source/markdown/options/stop-timeout.md b/docs/source/markdown/options/stop-timeout.md index a61bad440d..c84651b06e 100644 --- a/docs/source/markdown/options/stop-timeout.md +++ b/docs/source/markdown/options/stop-timeout.md @@ -1,8 +1,16 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `StopTimeout=seconds` +{% else %} #### **--stop-timeout**=*seconds* +{% endif %} Timeout to stop a container. Default is **10**. Remote connections use local containers.conf for defaults. + +{% if is_quadlet %} +Note, this value should be lower than the actual systemd unit timeout to make sure the podman rm command is not killed by systemd. +{% endif %} diff --git a/docs/source/markdown/options/subgidname.md b/docs/source/markdown/options/subgidname.md index d31cb7ea79..f11c25914b 100644 --- a/docs/source/markdown/options/subgidname.md +++ b/docs/source/markdown/options/subgidname.md @@ -1,9 +1,14 @@ ####> This option file is used in: -####> podman create, pod clone, pod create, run +####> podman podman-container.unit.5.md.in, create, pod clone, pod create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `SubGIDMap=name` +{% else %} #### **--subgidname**=*name* +{% endif %} Run the container in a new user namespace using the map with _name_ in the _/etc/subgid_ file. If running rootless, the user needs to have the right to use the mapping. See **subgid**(5). -This flag conflicts with **--userns** and **--gidmap**. +This flag conflicts with {{{ '**UserNS=**' if is_quadlet else '**--userns**' }}} and {{{ '**GIDMap=**' if is_quadlet else '**--gidmap**' }}}. + diff --git a/docs/source/markdown/options/subuidname.md b/docs/source/markdown/options/subuidname.md index ac3e1f372a..ebe0f65612 100644 --- a/docs/source/markdown/options/subuidname.md +++ b/docs/source/markdown/options/subuidname.md @@ -1,9 +1,13 @@ ####> This option file is used in: -####> podman create, pod clone, pod create, run +####> podman podman-container.unit.5.md.in, create, pod clone, pod create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `SubUIDMap=name` +{% else %} #### **--subuidname**=*name* +{% endif %} Run the container in a new user namespace using the map with _name_ in the _/etc/subuid_ file. If running rootless, the user needs to have the right to use the mapping. See **subuid**(5). -This flag conflicts with **--userns** and **--uidmap**. +This flag conflicts with {{{ '**UserNS=**' if is_quadlet else '**--userns**' }}} and {{{ '**UIDMap=**' if is_quadlet else '**--uidmap**' }}}. diff --git a/docs/source/markdown/options/sysctl.md b/docs/source/markdown/options/sysctl.md index 1027d5640f..4e4f884e8f 100644 --- a/docs/source/markdown/options/sysctl.md +++ b/docs/source/markdown/options/sysctl.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, pod clone, pod create, run +####> podman podman-container.unit.5.md.in, create, pod clone, pod create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Sysctl=name=value` +{% else %} #### **--sysctl**=*name=value* +{% endif %} Configure namespaced kernel parameters <>. diff --git a/docs/source/markdown/options/tag.md b/docs/source/markdown/options/tag.md index 63a24e59a5..a35e6b2fb4 100644 --- a/docs/source/markdown/options/tag.md +++ b/docs/source/markdown/options/tag.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman build, farm build +####> podman build, podman-build.unit.5.md.in, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `TaImageTag=imageName` +{% else %} #### **--tag**, **-t**=*imageName* +{% endif %} Specifies the name which is assigned to the resulting image if the build process completes successfully. If _imageName_ does not include a registry name, the registry name *localhost* is prepended to the image name. diff --git a/docs/source/markdown/options/target.md b/docs/source/markdown/options/target.md index 5c5646a915..83c2a8dacc 100644 --- a/docs/source/markdown/options/target.md +++ b/docs/source/markdown/options/target.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman build, farm build +####> podman build, podman-build.unit.5.md.in, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Target=stageName` +{% else %} #### **--target**=*stageName* +{% endif %} Set the target build stage to build. When building a Containerfile with multiple build stages, --target can be used to specify an intermediate build stage by name as the final stage for the resulting image. Commands after the target stage is skipped. diff --git a/docs/source/markdown/options/tls-verify.md b/docs/source/markdown/options/tls-verify.md index 3c15a77a84..0cb60d2e5d 100644 --- a/docs/source/markdown/options/tls-verify.md +++ b/docs/source/markdown/options/tls-verify.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman artifact pull, artifact push, auto update, build, container runlabel, create, farm build, kube play, login, machine init, manifest add, manifest create, manifest inspect, manifest push, pull, push, run, search +####> podman artifact pull, artifact push, auto update, build, podman-build.unit.5.md.in, container runlabel, create, farm build, podman-image.unit.5.md.in, kube play, login, machine init, manifest add, manifest create, manifest inspect, manifest push, pull, push, run, search ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `TLSVerify=` +{% else %} #### **--tls-verify** +{% endif %} Require HTTPS and verify certificates when contacting registries (default: **true**). If explicitly set to **true**, TLS verification is used. diff --git a/docs/source/markdown/options/tmpfs.md b/docs/source/markdown/options/tmpfs.md index 11c62756ae..4f38eead6c 100644 --- a/docs/source/markdown/options/tmpfs.md +++ b/docs/source/markdown/options/tmpfs.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Tmpfs=` +{% else %} #### **--tmpfs**=*fs* +{% endif %} Create a tmpfs mount. diff --git a/docs/source/markdown/options/tz.md b/docs/source/markdown/options/tz.md index bfe18f0e6a..61255b88bc 100644 --- a/docs/source/markdown/options/tz.md +++ b/docs/source/markdown/options/tz.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `TimeZone=timezone` +{% else %} #### **--tz**=*timezone* +{% endif %} Set timezone in container. This flag takes area-based timezones, GMT time, as well as `local`, which sets the timezone in the container to match the host machine. See `/usr/share/zoneinfo/` for valid timezones. Remote connections use local containers.conf for defaults diff --git a/docs/source/markdown/options/uidmap.container.md b/docs/source/markdown/options/uidmap.container.md index 24a3a6615c..39ed4729b2 100644 --- a/docs/source/markdown/options/uidmap.container.md +++ b/docs/source/markdown/options/uidmap.container.md @@ -1,11 +1,15 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `UIDMap=[flags]container_uid:from_uid[:amount]` +{% else %} #### **--uidmap**=*[flags]container_uid:from_uid[:amount]* +{% endif %} Run the container in a new user namespace using the supplied UID mapping. This -option conflicts with the **--userns** and **--subuidname** options. This +option conflicts with the {{{ '**UserNS=**' if is_quadlet else '**--userns**' }}} and {{{ '**SubUIDMap=**' if is_quadlet else '**--subuidname**' }}} options. This option provides a way to map host UIDs to container UIDs. It can be passed several times to map different ranges. @@ -20,7 +24,7 @@ The *from_uid* value is based upon the user running the command, either rootful `Rootful mappings` -When **podman <>** is called by a privileged user, the option **--uidmap** +When **podman <>** is called by a privileged user, the option {{{ '**UIDMap=**' if is_quadlet else '**--uidmap**' }}} works as a direct mapping between host UIDs and container UIDs. host UID -> container UID @@ -44,7 +48,7 @@ happens over two mapping steps: host UID -> intermediate UID -> container UID -The **--uidmap** option only influences the second mapping step. +The {{{ '**UIDMap=**' if is_quadlet else '**--uidmap**' }}} option only influences the second mapping step. The first mapping step is derived by Podman from the contents of the file _/etc/subuid_ and the UID of the user calling Podman. @@ -62,7 +66,7 @@ First mapping step: To be able to use intermediate UIDs greater than zero, the user needs to have subordinate UIDs configured in _/etc/subuid_. See **subuid**(5). -The second mapping step is configured with **--uidmap**. +The second mapping step is configured with {{{ '**UIDMap=**' if is_quadlet else '**--uidmap**' }}}. If for example _amount_ is **5** the second mapping step looks like: @@ -87,7 +91,7 @@ Every additional range is added sequentially afterward: `Referencing a host ID from the parent namespace` -As a rootless user, the given host ID in **--uidmap** or **--gidmap** +As a rootless user, the given host ID in {{{ '**UIDMap=**' if is_quadlet else '**--uidmap**' }}} or {{{ '**GIDMap=**' if is_quadlet else '**--gidmap**' }}} is mapped from the *intermediate namespace* generated by Podman. Sometimes it is desirable to refer directly at the *host namespace*. It is possible to manually do so, by running `podman unshare cat /proc/self/gid_map`, @@ -137,7 +141,7 @@ the rest of subordinate ids to be mapped by Podman at will. Usually, subordinated user and group ids are assigned simultaneously, and for any user the subordinated user ids match the subordinated group ids. -For convenience, if only one of **--uidmap** or **--gidmap** is given, +For convenience, if only one of {{{ '**UIDMap=**' if is_quadlet else '**--uidmap**' }}} or {{{ '**GIDMap=**' if is_quadlet else '**--gidmap**' }}} is given, podman assumes the mapping refers to both UIDs and GIDs and applies the given mapping to both. If only one value of the two needs to be changed, the mappings should include the `u` or the `g` flags to specify that @@ -152,20 +156,20 @@ For instance given the command podman <> --gidmap "0:0:1000" --gidmap "g2000:2000:1" -Since no **--uidmap** is given, the **--gidmap** is copied to **--uidmap**, +Since no {{{ '**UIDMap=**' if is_quadlet else '**--uidmap**' }}} is given, the {{{ '**GIDMap=**' if is_quadlet else '**--gidmap**' }}} is copied to {{{ '**UIDMap=**' if is_quadlet else '**--uidmap**' }}}, giving a command equivalent to podman <> --gidmap "0:0:1000" --gidmap "2000:2000:1" --uidmap "0:0:1000" The `--gidmap "g2000:2000:1"` used the `g` flag and therefore it was -not copied to **--uidmap**. +not copied to {{{ '**UIDMap=**' if is_quadlet else '**--uidmap**' }}}. `Rootless mapping of additional host GIDs` A rootless user may desire to map a specific host group that has already been subordinated within _/etc/subgid_ without specifying the rest of the mapping. -This can be done with **--gidmap "+g*container_gid*:@*host_gid*"** +This can be done with {{{ '**GIDMap="+g*container_gid*:@*host_gid*"**' if is_quadlet else '**--gidmap "+g*container_gid*:@*host_gid*"**' }}} Where: @@ -176,9 +180,9 @@ Where: For instance, if a user belongs to the group `2000` and that group is subordinated to that user (with `usermod --add-subgids 2000-2000 $USER`), -the user can map the group into the container with: **--gidmap=+g100000:@2000**. +the user can map the group into the container with: {{{ '**GIDMap=+g100000:@2000**' if is_quadlet else '**--gidmap=+g100000:@2000**' }}}. -If this mapping is combined with the option, **--group-add=keep-groups**, the +If this mapping is combined with the option, {{{ '**GroupAdd=keep-groups**' if is_quadlet else '**--group-add=keep-groups**' }}}, the process in the container will belong to group `100000`, and files belonging to group `2000` in the host will appear as being owned by group `100000` inside the container. @@ -188,9 +192,9 @@ inside the container. `No subordinate UIDs` Even if a user does not have any subordinate UIDs in _/etc/subuid_, -**--uidmap** can be used to map the normal UID of the user to a +{{{ '**UIDMap=**' if is_quadlet else '**--uidmap**' }}} can be used to map the normal UID of the user to a container UID by running `podman <> --uidmap $container_uid:0:1 --user $container_uid ...`. `Pods` -The **--uidmap** option cannot be called in conjunction with the **--pod** option as a uidmap cannot be set on the container level when in a pod. +The {{{ '**UIDMap=**' if is_quadlet else '**--uidmap**' }}} option cannot be called in conjunction with the {{{ '**Pod=**' if is_quadlet else '**--pod**' }}} option as a uidmap cannot be set on the container level when in a pod. diff --git a/docs/source/markdown/options/uidmap.pod.md b/docs/source/markdown/options/uidmap.pod.md index 04f7c229c7..1680927ec6 100644 --- a/docs/source/markdown/options/uidmap.pod.md +++ b/docs/source/markdown/options/uidmap.pod.md @@ -1,10 +1,14 @@ ####> This option file is used in: -####> podman pod clone, pod create +####> podman pod clone, pod create, podman-pod.unit.5.md.in ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `UIDMap=container_uid:from_uid:amount` +{% else %} #### **--uidmap**=*container_uid:from_uid:amount* +{% endif %} Run all containers in the pod in a new user namespace using the supplied mapping. This -option conflicts with the **--userns** and **--subuidname** options. This +option conflicts with the {{{ '**UserNS=.**' if is_quadlet else '**--userns**' }}} and {{{ '**SubUIDMap=.**' if is_quadlet else '**--subuidname**' }}} options. This option provides a way to map host UIDs to container UIDs. It can be passed several times to map different ranges. diff --git a/docs/source/markdown/options/ulimit.md b/docs/source/markdown/options/ulimit.md index a387b2f02a..7b827cdeb0 100644 --- a/docs/source/markdown/options/ulimit.md +++ b/docs/source/markdown/options/ulimit.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Ulimit=option` +{% else %} #### **--ulimit**=*option* +{% endif %} Ulimit options. Sets the ulimits values inside of the container. diff --git a/docs/source/markdown/options/user.md b/docs/source/markdown/options/user.md index 2307fcc9b6..c3ea5e52b0 100644 --- a/docs/source/markdown/options/user.md +++ b/docs/source/markdown/options/user.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, exec, run +####> podman podman-container.unit.5.md.in, create, exec, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `User=user[:group]` +{% else %} #### **--user**, **-u**=*user[:group]* +{% endif %} Sets the username or UID used and, optionally, the groupname or GID for the specified command. Both *user* and *group* may be symbolic or numeric. diff --git a/docs/source/markdown/options/userns.container.md b/docs/source/markdown/options/userns.container.md index b128546f1c..0380f7b276 100644 --- a/docs/source/markdown/options/userns.container.md +++ b/docs/source/markdown/options/userns.container.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, kube play, run +####> podman podman-container.unit.5.md.in, create, kube play, podman-kube.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `UserNS=mode` +{% else %} #### **--userns**=*mode* +{% endif %} Set the user namespace mode for the container. @@ -14,7 +18,7 @@ If `--userns` is not set, the default value is determined as follows. `--userns=""` (i.e., an empty string) is an alias for `--userns=host`. -This option is incompatible with **--gidmap**, **--uidmap**, **--subuidname** and **--subgidname**. +This option is incompatible with {{{ '**GIDMap=**' if is_quadlet else '**--gidmap**' }}}, {{{ '**UIDMap=**' if is_quadlet else '**--uidmap**' }}}, {{{ '**SubUIDMap=**' if is_quadlet else '**-**--subuidname****' }}} and {{{ '**SubGIDMap=**' if is_quadlet else '**-**--subgidname****' }}}. Rootless user --userns=Key mappings: @@ -48,7 +52,7 @@ Using `--userns=auto` when starting new containers does not work as long as any The host UID and GID in *gidmapping* and *uidmapping* can optionally be prefixed with the `@` symbol. In this case, podman will look up the intermediate ID corresponding to host ID and it will map the found intermediate ID to the container id. -For details see **--uidmap**. +For details see {{{ '**UIDMap=**' if is_quadlet else '**--uidmap**' }}}. **container:**_id_: join the user namespace of the specified container. diff --git a/docs/source/markdown/options/userns.pod.md b/docs/source/markdown/options/userns.pod.md index 82040b709c..2da8aa430a 100644 --- a/docs/source/markdown/options/userns.pod.md +++ b/docs/source/markdown/options/userns.pod.md @@ -1,12 +1,16 @@ ####> This option file is used in: -####> podman pod clone, pod create +####> podman pod clone, pod create, podman-pod.unit.5.md.in ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `UserNS=mode` +{% else %} #### **--userns**=*mode* +{% endif %} Set the user namespace mode for all the containers in a pod. It defaults to the `PODMAN_USERNS` environment variable. An empty value ("") means user namespaces are disabled. -Rootless user --userns=Key mappings: +Rootless user {{{ '**UserNS=Key**' if is_quadlet else '**--userns=Key**' }}} mappings: Key | Host User | Container User ----------|---------------|--------------------- @@ -22,7 +26,7 @@ Valid _mode_ values are: - *gidmapping=*_CONTAINER\_GID:HOST\_GID:SIZE_ to force a GID mapping to be present in the user namespace. - - *size=*_SIZE_: to specify an explicit size for the automatic user namespace. e.g. `--userns=auto:size=8192`. If `size` is not specified, `auto` estimates the size for the user namespace. + - *size=*_SIZE_: to specify an explicit size for the automatic user namespace. e.g. `{{{ 'UserNS=' if is_quadlet else '--userns=' }}}auto:size=8192`. If `size` is not specified, `auto` estimates the size for the user namespace. - *uidmapping=*_CONTAINER\_UID:HOST\_UID:SIZE_ to force a UID mapping to be present in the user namespace. diff --git a/docs/source/markdown/options/variant.container.md b/docs/source/markdown/options/variant.container.md index 522e74bf1a..f49dc9ee53 100644 --- a/docs/source/markdown/options/variant.container.md +++ b/docs/source/markdown/options/variant.container.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman create, pull, run +####> podman create, podman-image.unit.5.md.in, pull, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Variant=VARIANT` +{% else %} #### **--variant**=*VARIANT* +{% endif %} 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. diff --git a/docs/source/markdown/options/volume.image.md b/docs/source/markdown/options/volume.image.md index f77a99c4b8..80d5edd928 100644 --- a/docs/source/markdown/options/volume.image.md +++ b/docs/source/markdown/options/volume.image.md @@ -2,11 +2,21 @@ ####> podman build, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Volume=[HOST-DIR:CONTAINER-DIR[:OPTIONS]]` +{% else %} #### **--volume**, **-v**=*[HOST-DIR:CONTAINER-DIR[:OPTIONS]]* +{% endif %} Mount a host directory into containers when executing RUN instructions during the build. +{% if is_quadlet %} +Special case: + +* If `SOURCE-VOLUME` ends with `.volume`, Quadlet will look for the corresponding `.volume` Quadlet unit. If found, Quadlet will use the name of the Volume set in the Unit, otherwise, `systemd-$name` is used. The generated systemd service contains a dependency on the service unit generated for that `.volume` unit, or on `$name-volume.service` if the `.volume` unit is not found. Note: the corresponding `.volume` file must exist. +{% endif %} + The `OPTIONS` are a comma-separated list and can be one or more of: * [rw|ro] diff --git a/docs/source/markdown/options/volume.md b/docs/source/markdown/options/volume.md index 1f58237b13..e6a4441b54 100644 --- a/docs/source/markdown/options/volume.md +++ b/docs/source/markdown/options/volume.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, pod clone, pod create, run +####> podman podman-build.unit.5.md.in, podman-container.unit.5.md.in, create, pod clone, pod create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `Volume=[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]` +{% else %} #### **--volume**, **-v**=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]* +{% endif %} Create a bind mount. If `-v /HOST-DIR:/CONTAINER-DIR` is specified, Podman bind mounts `/HOST-DIR` from the host into `/CONTAINER-DIR` in the Podman @@ -13,6 +17,12 @@ as an anonymously named volume with a randomly generated name, and is removed when the <> is removed via the `--rm` flag or the `podman rm --volumes` command. +{% if is_quadlet %} +Special case: + +* If `SOURCE-VOLUME` ends with `.volume`, a Podman named volume called `systemd-$name` is used as the source, and the generated systemd service contains a dependency on the `$name-volume.service`. Note that the corresponding `.volume` file must exist. +{% endif %} + (Note when using the remote client, including Mac and Windows (excluding WSL2) machines, the volumes are mounted from the remote server, not necessarily the client machine.) The _OPTIONS_ is a comma-separated list and can be one or more of: diff --git a/docs/source/markdown/options/workdir.md b/docs/source/markdown/options/workdir.md index 70a63eba74..87a8a2d73a 100644 --- a/docs/source/markdown/options/workdir.md +++ b/docs/source/markdown/options/workdir.md @@ -1,11 +1,15 @@ ####> This option file is used in: -####> podman create, exec, run +####> podman podman-container.unit.5.md.in, create, exec, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +{% if is_quadlet %} +### `WorkingDir=dir` +{% else %} #### **--workdir**, **-w**=*dir* +{% endif %} Working directory inside the container. The default working directory for running binaries within a container is the root directory (**/**). The image developer can set a different default with the WORKDIR instruction. The operator -can override the working directory by using the **-w** option. +can override the working directory by using the {{{ '**WokingDir=**' if is_quadlet else '**-w**' }}} option. diff --git a/docs/source/markdown/podman-auto-update.1.md.in b/docs/source/markdown/podman-auto-update.1.md.in index 1963867362..75b1c27f45 100644 --- a/docs/source/markdown/podman-auto-update.1.md.in +++ b/docs/source/markdown/podman-auto-update.1.md.in @@ -10,9 +10,9 @@ podman\-auto-update - Auto update containers according to their auto-update poli **podman auto-update** pulls down new container images and restarts containers configured for auto updates. To make use of auto updates, the container or Kubernetes workloads must run inside a systemd unit. After a successful update of an image, the containers using the image get updated by restarting the systemd units they run in. -Please refer to `podman-systemd.unit(5)` on how to run Podman under systemd. +Please refer to `podman-quadlet(7)` on how to run Podman under systemd. -To configure a container for auto updates, it must be created with the `io.containers.autoupdate` label or the `AutoUpdate` field in `podman-systemd.unit(5)` with one of the following two values: +To configure a container for auto updates, it must be created with the `io.containers.autoupdate` label or the `AutoUpdate` field in `podman-quadlet(7)` with one of the following two values: * `registry`: If the label is present and set to `registry`, Podman reaches out to the corresponding registry to check if the image has been updated. The label `image` is an alternative to `registry` maintained for backwards compatibility. @@ -27,7 +27,7 @@ If they differ, the local image is considered to be newer and the systemd unit g ### Auto Updates and Kubernetes YAML -Podman supports auto updates for Kubernetes workloads. The auto-update policy can be configured directly via `podman-systemd.unit(5)` or inside the Kubernetes YAML with the Podman-specific annotations mentioned below: +Podman supports auto updates for Kubernetes workloads. The auto-update policy can be configured directly via `podman-quadlet(7)` or inside the Kubernetes YAML with the Podman-specific annotations mentioned below: * `io.containers.autoupdate`: "registry|local" to apply the auto-update policy to all containers * `io.containers.autoupdate/$container`: "registry|local" to apply the auto-update policy to `$container` only @@ -119,4 +119,4 @@ sleep.service f8e4759798d4 (systemd-sleep) registry.fedoraproject.org/fedora:l ``` ## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-generate-systemd(1)](podman-generate-systemd.1.md)**, **[podman-run(1)](podman-run.1.md)**, **[podman-systemd.unit(5)](podman-systemd.unit.5.md)**, **sd_notify(3)**, **[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)** +**[podman(1)](podman.1.md)**, **[podman-generate-systemd(1)](podman-generate-systemd.1.md)**, **[podman-run(1)](podman-run.1.md)**, **[podman-quadlet(7)](podman-quadlet.7.md)**, **sd_notify(3)**, **[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)** diff --git a/docs/source/markdown/podman-build.unit.5.md.in b/docs/source/markdown/podman-build.unit.5.md.in new file mode 100644 index 0000000000..6efac39aa0 --- /dev/null +++ b/docs/source/markdown/podman-build.unit.5.md.in @@ -0,0 +1,229 @@ +% podman-build.unit(5) + +# NAME + +podman\-build.unit - systemd unit files for building container images using Podman Quadlet + +# SYNOPSIS + +*name*.build + +# DESCRIPTION + +Build units (`.build` files) are used by **Podman Quadlet** to declaratively define systemd services that +build container images from a `Containerfile` or `Dockerfile`. + +These units ensure that the image is built on the host before being used by containers or volumes. If the +image already exists and the context hasn’t changed, subsequent executions will complete quickly thanks to +Podman’s build cache. + +They are especially useful for: +- Creating images not available in registries +- Automating image builds during boot +- Local testing and development pipelines + +A minimal `.build` file must specify: +- `ImageTag=` — to name the built image +- Either `File=` or `SetWorkingDirectory=` + + +# USAGE SUMMARY + +The `.build` file is parsed by the `podman-system-generator` at boot or reload, generating a systemd +`.service` that runs `podman build`. That service can be managed like any other unit: + +```bash +systemctl --user start myimage-build.service +``` + +The resulting image can be referenced by `.container` or `.volume` units via: + +```ini +Image=myimage.build +``` + + +# FILE LOCATIONS + +Place `.build` files in one of the following: + +### Rootless + +- `$XDG_RUNTIME_DIR/containers/systemd/` +- `$XDG_CONFIG_HOME/containers/systemd/` or `~/.config/containers/systemd/` +- `/etc/containers/systemd/users/$(UID)` +- `/etc/containers/systemd/users/` + +### Rootful + +- `/run/containers/systemd/` +- `/etc/containers/systemd/` +- `/usr/share/containers/systemd/` + + +# OPTIONS + +Valid options for `[Build]` section are listed below: + +| **[Build] options** | **podman build equivalent** | +|-------------------------------------|---------------------------------------------| +| Annotation=annotation=value | --annotation=annotation=value | +| Arch=aarch64 | --arch=aarch64 | +| AuthFile=/etc/registry/auth\.json | --authfile=/etc/registry/auth\.json | +| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | +| DNS=192.168.55.1 | --dns=192.168.55.1 | +| DNSOption=ndots:1 | --dns-option=ndots:1 | +| DNSSearch=example.com | --dns-search example.com | +| Environment=foo=bar | --env foo=bar | +| File=/path/to/Containerfile | --file=/path/to/Containerfile | +| ForceRM=false | --force-rm=false | +| GlobalArgs=--log-level=debug | --log-level=debug | +| GroupAdd=keep-groups | --group-add=keep-groups | +| ImageTag=localhost/imagename | --tag=localhost/imagename | +| Label=label | --label=label | +| Network=host | --network=host | +| PodmanArgs=--pull never | --pull never | +| Pull=never | --pull never | +| Retry=5 | --retry=5 | +| RetryDelay=10s | --retry-delay=10s | +| Secret=secret | --secret=id=mysecret,src=path | +| SetWorkingDirectory=unit | Set `WorkingDirectory` of systemd unit file | +| Target=my-app | --target=my-app | +| TLSVerify=false | --tls-verify=false | +| Variant=arm/v7 | --variant=arm/v7 | +| Volume=/source:/dest | --volume /source:/dest | + +### `Annotation=` + +Add an image *annotation* (e.g. annotation=*value*) to the image metadata. Can be used multiple +times. + +This is equivalent to the `--annotation` option of `podman build`. + +@@option quadlet:arch + +@@option quadlet:authfile + +@@option quadlet:module + +@@option quadlet:dns + +@@option quadlet:dns-option.image + +@@option quadlet:dns-search.image + +@@option quadlet:env.image + +@@option quadlet:file + +@@option quadlet:force-rm + +### `GlobalArgs=` + +This key contains a list of arguments passed directly between `podman` and `build` 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. + +@@option quadlet:group-add + +@@option quadlet:tag + +@@option quadlet:label.image + +@@option quadlet:network.image + +### `PodmanArgs=` + +This key contains a list of arguments passed directly to the end of the `podman build` command +in the generated file (right before the image name in the command line). 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. + +@@option quadlet:pull + +@@option quadlet:retry + +@@option quadlet:retry-delay + +@@option quadlet:secret.image + +### `SetWorkingDirectory=` + +Provide context (a working directory) to `podman build`. Supported values are a path, a URL, or the +special keys `file` or `unit` to set the context directory to the parent directory of the file from +the `File=` key or to that of the Quadlet `.build` unit file, respectively. This allows Quadlet to +resolve relative paths. + +When using one of the special keys (`file` or `unit`), the `WorkingDirectory` field of the `Service` +group of the Systemd service unit will also be set to accordingly. Alternatively, users can +explicitly set the `WorkingDirectory` field of the `Service` group in the `.build` file. Please note +that if the `WorkingDirectory` field of the `Service` group is set by the user, Quadlet will not +overwrite it even if `SetWorkingDirectory` is set to `file` or `unit`. + +By providing a URL to `SetWorkingDirectory=` you can instruct `podman build` to clone a Git +repository or download an archive file extracted to a temporary location by `podman build` as build +context. Note that in this case, the `WorkingDirectory` of the Systemd service unit is left +untouched by Quadlet. + +Note that providing context directory is mandatory for a `.build` file, unless a `File=` key has +also been provided. + +@@option quadlet:target + +@@option quadlet:tls-verify + +### `Variant=` + +Override the default architecture variant of the container image to be built. + +This is equivalent to the `--variant` option of `podman build`. + +@@option quadlet:volume + + +# EXAMPLES + +### Simple build + +```ini +[Build] +ImageTag=localhost/myapp +File=Containerfile +SetWorkingDirectory=unit +``` + +### From Git repository + +```ini +[Build] +ImageTag=localhost/mygitimage +File=Containerfile +SetWorkingDirectory=https://github.com/example/repo.git +``` + +### Build with secret + +```ini +[Build] +ImageTag=localhost/secureimage +Secret=mysecret +``` + +# SEE ALSO + +- [podman-quadlet(7)](podman-quadlet.7.md) +- [systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html) +- [podman-build(1)](https://docs.podman.io/en/latest/markdown/podman-build.1.html) +- [podman-quadlet(7)] diff --git a/docs/source/markdown/podman-container.unit.5.md.in b/docs/source/markdown/podman-container.unit.5.md.in new file mode 100644 index 0000000000..4ee555a749 --- /dev/null +++ b/docs/source/markdown/podman-container.unit.5.md.in @@ -0,0 +1,559 @@ +% podman-container.unit(5) + +# NAME + +podman\-container.unit - systemd unit files for managing containers using Podman Quadlet + +# SYNOPSIS + +*name*.container + +# DESCRIPTION + +Container units are `.container` files interpreted by Podman Quadlet to generate systemd `.service` units that manage containers as systemd services. + +The `.container` file format extends regular systemd unit files with a `[Container]` section, allowing detailed configuration of the container to be run. + +The resulting service file contains a line like `ExecStart=podman run … image-name`, and most of the keys in this section control the command-line +options passed to Podman. However, some options also affect the details of how systemd is set up to run and +interact with the container. + +By default, the Podman container has the same name as the unit, but with a `systemd-` prefix, i.e. +a `$name.container` file creates a `$name.service` unit and a `systemd-$name` Podman container. The +`ContainerName` option allows for overriding this default name with a user-provided one. + +There is only one required key, `Image`, which defines the container image the service runs. + +# USAGE SUMMARY + +The `.container` file is parsed by the `podman-system-generator` at boot or reload, generating a systemd +`.service` that runs `podman run`. That service can be managed like any other unit: + +```bash +systemctl --user start myimage-container.service +``` + +# FILE LOCATIONS + +Place `.container` files in one of the following: + +### Rootless + +- `$XDG_RUNTIME_DIR/containers/systemd/` +- `$XDG_CONFIG_HOME/containers/systemd/` or `~/.config/containers/systemd/` +- `/etc/containers/systemd/users/$(UID)` +- `/etc/containers/systemd/users/` + +### Rootful + +- `/run/containers/systemd/` +- `/etc/containers/systemd/` +- `/usr/share/containers/systemd/` + +# OPTIONS + +Valid options for `[Container]` are listed below: + +| **[Container] options** | **podman run equivalent** | +|--------------------------------------|------------------------------------------------------| +| AddCapability=CAP | --cap-add CAP | +| AddDevice=/dev/foo | --device /dev/foo | +| AddHost=example\.com:192.168.10.11 | --add-host example.com:192.168.10.11 | +| Annotation="XYZ" | --annotation "XYZ" | +| AutoUpdate=registry | --label "io.containers.autoupdate=registry" | +| CgroupsMode=no-conmon | --cgroups=no-conmon | +| ContainerName=name | --name name | +| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | +| DNS=192.168.55.1 | --dns=192.168.55.1 | +| DNSOption=ndots:1 | --dns-option=ndots:1 | +| DNSSearch=example.com | --dns-search example.com | +| DropCapability=CAP | --cap-drop=CAP | +| Entrypoint=/foo.sh | --entrypoint=/foo.sh | +| Environment=foo=bar | --env foo=bar | +| EnvironmentFile=/tmp/env | --env-file /tmp/env | +| EnvironmentHost=true | --env-host | +| Exec=/usr/bin/command | Command after image specification - /usr/bin/command | +| ExposeHostPort=50-59 | --expose 50-59 | +| GIDMap=0:10000:10 | --gidmap=0:10000:10 | +| GlobalArgs=--log-level=debug | --log-level=debug | +| Group=1234 | --user UID:1234 | +| GroupAdd=keep-groups | --group-add=keep-groups | +| HealthCmd=/usr/bin/command | --health-cmd=/usr/bin/command | +| HealthInterval=2m | --health-interval=2m | +| HealthLogDestination=/foo/log | --health-log-destination=/foo/log | +| HealthMaxLogCount=5 | --health-max-log-count=5 | +| HealthMaxLogSize=500 | --health-max-log-size=500 | +| HealthOnFailure=kill | --health-on-failure=kill | +| HealthRetries=5 | --health-retries=5 | +| HealthStartPeriod=1m | --health-start-period=period=1m | +| HealthStartupCmd=command | --health-startup-cmd=command | +| HealthStartupInterval=1m | --health-startup-interval=1m | +| HealthStartupRetries=8 | --health-startup-retries=8 | +| HealthStartupSuccess=2 | --health-startup-success=2 | +| HealthStartupTimeout=1m33s | --health-startup-timeout=1m33s | +| HealthTimeout=20s | --health-timeout=20s | +| HostName=example.com | --hostname example.com | +| Image=ubi8 | Image specification - ubi8 | +| IP=192.5.0.1 | --ip 192.5.0.1 | +| IP6=2001:db8::1 | --ip6 2001:db8::1 | +| Label="XYZ" | --label "XYZ" | +| LogDriver=journald | --log-driver journald | +| LogOpt=path=/var/log/mykube\.json | --log-opt path=/var/log/mykube\.json | +| Mask=/proc/sys/foo\:/proc/sys/bar | --security-opt mask=/proc/sys/foo:/proc/sys/bar | +| Memory=20g | --memory 20g | +| Mount=type=... | --mount type=... | +| Network=host | --network host | +| NetworkAlias=name | --network-alias name | +| NoNewPrivileges=true | --security-opt no-new-privileges | +| Notify=true | --sdnotify container | +| PidsLimit=10000 | --pids-limit 10000 | +| Pod=pod-name | --pod=pod-name | +| PodmanArgs=--publish 8080:80 | --publish 8080:80 | +| PublishPort=8080:80 | --publish 8080:80 | +| Pull=never | --pull never | +| ReadOnly=true | --read-only | +| ReadOnlyTmpfs=true | --read-only-tmpfs | +| ReloadCmd=/usr/bin/command | Add ExecReload and run exec with the value | +| ReloadSignal=SIGHUP | Add ExecReload and run kill with the signal | +| Retry=5 | --retry=5 | +| RetryDelay=5s | --retry-delay=5s | +| Rootfs=/var/lib/rootfs | --rootfs /var/lib/rootfs | +| RunInit=true | --init | +| SeccompProfile=/tmp/s.json | --security-opt seccomp=/tmp/s.json | +| Secret=secret | --secret=secret[,opt=opt ...] | +| SecurityLabelDisable=true | --security-opt label=disable | +| SecurityLabelFileType=usr_t | --security-opt label=filetype:usr_t | +| SecurityLabelLevel=s0:c1,c2 | --security-opt label=level:s0:c1,c2 | +| SecurityLabelNested=true | --security-opt label=nested | +| SecurityLabelType=spc_t | --security-opt label=type:spc_t | +| ShmSize=100m | --shm-size=100m | +| StartWithPod=true | If Pod= is defined, container is started by pod | +| StopSignal=SIGINT | --stop-signal=SIGINT | +| StopTimeout=20 | --stop-timeout=20 | +| SubGIDMap=gtest | --subgidname=gtest | +| SubUIDMap=utest | --subuidname=utest | +| Sysctl=name=value | --sysctl=name=value | +| Timezone=local | --tz local | +| Tmpfs=/work | --tmpfs /work | +| UIDMap=0:10000:10 | --uidmap=0:10000:10 | +| Ulimit=nofile=1000:10000 | --ulimit nofile=1000:10000 | +| Unmask=ALL | --security-opt unmask=ALL | +| User=bin | --user bin | +| UserNS=keep-id:uid=200,gid=210 | --userns keep-id:uid=200,gid=210 | +| Volume=/source:/dest | --volume /source:/dest | +| WorkingDir=$HOME | --workdir $HOME | + +Description of `[Container]` section are: + + +@@option quadlet:cap-add + +@@option quadlet:device + +@@option quadlet:add-host + +@@option quadlet:annotation.container + + +### `AutoUpdate=` + +Indicates whether the container will be auto-updated ([podman-auto-update(1)](podman-auto-update.1.md)). The following values are supported: + +* `registry`: Requires a fully-qualified image reference (e.g., quay.io/podman/stable:latest) to be used to create the container. This enforcement is necessary to know which image to actually check and pull. If an image ID was used, Podman does not know which image to check/pull anymore. + +* `local`: Tells Podman to compare the image a container is using to the image with its raw name in local storage. If an image is updated locally, Podman simply restarts the systemd unit executing the container. + +@@option quadlet:cgroups + +@@option quadlet:name.container + +@@option quadlet:module + +@@option quadlet:dns + +@@option quadlet:dns-option.container + +@@option quadlet:dns-search.container + +@@option quadlet:cap-drop + +@@option quadlet:entrypoint + +@@option quadlet:env + +@@option quadlet:env-file + +@@option quadlet:env-host + +### `Exec=` + +Additional arguments for the container; this has exactly the same effect as passing +more arguments after a `podman run ` invocation. + +The format is the same as for [systemd command lines](https://www.freedesktop.org/software/systemd/man/systemd.service.html#Command%20lines), +However, unlike the usage scenario for similarly-named systemd `ExecStart=` verb +which operates on the ambient root filesystem, it is very common for container +images to have their own `ENTRYPOINT` or `CMD` metadata which this interacts with. + +The default expectation for many images is that the image will include an `ENTRYPOINT` +with a default binary, and this field will add arguments to that entrypoint. + +Another way to describe this is that it works the same way as the [args field in a Kubernetes pod](https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell). + +@@option quadlet:expose + +@@option quadlet:gidmap.container + +### `GlobalArgs=` + +This key contains a list of arguments passed directly between `podman` and `run` +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. + +### `Group=` + +The (numeric) GID to run as inside the container. This does not need to match the GID on the host, +which can be modified with `UserNS`, but if that is not specified, this GID is also used on the host. + + +@@option quadlet:group-add + +@@option quadlet:health-cmd + +@@option quadlet:health-interval + +@@option quadlet:health-log-destination + +@@option quadlet:health-max-log-count + +@@option quadlet:health-max-log-size + +@@option quadlet:health-on-failure + +@@option quadlet:health-retries + +@@option quadlet:health-start-period + +@@option quadlet:health-startup-cmd + +@@option quadlet:health-startup-interval + +@@option quadlet:health-startup-retries + +@@option quadlet:health-startup-success + +@@option quadlet:health-startup-timeout + +@@option quadlet:health-timeout + +@@option quadlet:hostname.container + +### `Image=` + +The image to run in the container. +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`. So, it supports using +`:tag` or digests to guarantee the specific image version. + +Special Cases: + +* If the `name` of the image ends with `.image`, Quadlet will use the image pulled by the corresponding `.image` file, and the generated systemd service contains a dependency on the `$name-image.service` (or the service name set in the .image file). Note that the corresponding `.image` file must exist. +* If the `name` of the image ends with `.build`, Quadlet will use the image built by the corresponding `.build` file, and the generated systemd service contains a dependency on the `$name-build.service`. Note: the corresponding `.build` file must exist. + +@@option quadlet:ip + +@@option quadlet:ip6 + +@@option quadlet:label + +@@option quadlet:log-driver + +@@option quadlet:log-opt + +### `Mask=` + +Specify the paths to mask separated by a colon. `Mask=/path/1:/path/2`. A masked path cannot be accessed inside the container. + + +@@option quadlet:memory + +@@option quadlet:mount + +@@option quadlet:network + +@@option quadlet:network-alias + +### `NoNewPrivileges=` (defaults to `false`) + +If enabled, this disables the container processes from gaining additional privileges via things like +setuid and file capabilities. + +### `Notify=` (defaults to `false`) + +By default, Podman is run in such a way that the systemd startup notify command is handled by +the container runtime. In other words, the service is deemed started when the container runtime +starts the child in the container. However, if the container application supports +[sd_notify](https://www.freedesktop.org/software/systemd/man/sd_notify.html), then setting +`Notify` to true passes the notification details to the container allowing it to notify +of startup on its own. + +In addition, setting `Notify` to `healthy` will postpone startup notifications until such time as +the container is marked healthy, as determined by Podman healthchecks. Note that this requires +setting up a container healthcheck, see the `HealthCmd` option for more. + +@@option quadlet:pids-limit + +### `Pod=` + +Specify a Quadlet `.pod` unit to link the container to. +The value must take the form of `.pod` and the `.pod` unit must exist. + +Quadlet will add all the necessary parameters to link between the container and the pod and between their corresponding services. + + +### `PodmanArgs=` + +This key contains a list of arguments passed directly to the end of the `podman run` command +in the generated file (right before the image name in the command line). 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. + +@@option quadlet:publish + +@@option quadlet:pull + +@@option quadlet:read-only + +@@option quadlet:read-only-tmpfs + +### `ReloadCmd=` + +Add `ExecReload` line to the `Service` that runs ` podman exec` with this command in this container. + +In order to execute the reload run `systemctl reload ` + +Mutually exclusive with `ReloadSignal` + +### `ReloadSignal=` + +Add `ExecReload` line to the `Service` that runs `podman kill` with this signal which sends the signal to the main container process. + +In order to execute the reload run `systemctl reload ` + +Mutually exclusive with `ReloadCmd` + +@@option quadlet:retry + +@@option quadlet:retry-delay + +@@option quadlet:rootfs + +@@option quadlet:init + +### `SeccompProfile=` + +Set the seccomp profile to use in the container. If unset, the default podman profile is used. +Set to either the pathname of a JSON file, or `unconfined` to disable the seccomp filters. + +@@option quadlet:secret + +### `SecurityLabelDisable=` + +Turn off label separation for the container. + +### `SecurityLabelFileType=` + +Set the label file type for the container files. + +### `SecurityLabelLevel=` + +Set the label process level for the container processes. + +### `SecurityLabelNested=` + +Allow SecurityLabels to function within the container. This allows separation of containers created within the container. + +### `SecurityLabelType=` + +Set the label process type for the container processes. + +@@option quadlet:shm-size + +### `StartWithPod=` + +Start the container after the associated pod is created. Default to **true**. + +If `true`, container will be started/stopped/restarted alongside the pod. + +If `false`, the container will not be started when the pod starts. The container will be stopped with the pod. Restarting the pod will also restart the container as long as the container was also running before. + +Note, the container can still be started manually or through a target by configuring the `[Install]` section. The pod will be started as needed in any case. + +@@option quadlet:stop-signal + +@@option quadlet:stop-timeout + +@@option quadlet:subgidname + +@@option quadlet:subuidname + +@@option quadlet:sysctl + +@@option quadlet:tz + +@@option quadlet:tmpfs + +@@option quadlet:uidmap.container + +@@option quadlet:ulimit + +### `Unmask=` + +Specify the paths to unmask separated by a colon. unmask=ALL or /path/1:/path/2, or shell expanded paths (/proc/*): + +If set to `ALL`, Podman will unmask all the paths that are masked or made read-only by default. + +The default masked paths are /proc/acpi, /proc/kcore, /proc/keys, /proc/latency_stats, /proc/sched_debug, /proc/scsi, /proc/timer_list, /proc/timer_stats, /sys/firmware, and /sys/fs/selinux. + +The default paths that are read-only are /proc/asound, /proc/bus, /proc/fs, /proc/irq, /proc/sys, /proc/sysrq-trigger, /sys/fs/cgroup. + +@@option quadlet:user + +@@option quadlet:userns.container + +@@option quadlet:volume + +@@option quadlet:workdir + + +# SERVICE TYPE + +By default, the generator sets `Type=notify` for `.container` units. + +This can be overridden by explicitly setting `Type=` in the `[Service]` section. + +For one-shot containers (e.g., init tasks), use: + +``` +[Service] +Type=oneshot +RemainAfterExit=yes +``` + +Refer to `systemd.service(5)` for full details on service types and related behaviors. + +# INSTALL SECTION + +To ensure a container starts on boot, include an `[Install]` section: + +``` +[Install] +WantedBy=multi-user.target +``` + +Only `Alias=`, `WantedBy=`, `RequiredBy=`, and `UpheldBy=` keys are supported. + +# TIMEOUTS + +Container startup may exceed systemd’s default 90s timeout (e.g., when pulling images). Use: + +``` +[Service] +TimeoutStartSec=900 +``` + +Note: `TimeoutStartSec` is ignored for `Type=oneshot`. + +# NETWORK DEPENDENCIES + +Quadlet adds: + +- `After=network-online.target` (for root units) +- `After=podman-user-wait-network-online.service` (for user units) + +To disable this, add: + +``` +[Quadlet] +DefaultDependencies=false +``` + +# RESOURCE NAMING + +By default, the container is named `systemd-`. Use `ContainerName=` to override. + +Avoid using systemd specifiers like `%N` in resource names—they break inter-resource linking. + +# TEMPLATE UNITS + +Quadlet supports templated container units, e.g., `foo@.container` creates `foo@.service`. + +You can instantiate with: + +```bash +systemctl start foo@bar.service +``` + +You may also symlink instances: + +```bash +ln -s foo@.container foo@bar.container +``` + +Use drop-ins for instance-specific customization: + +``` +foo@bar.container.d/10-override.conf +``` + +# DROP-IN FILES + +Quadlet supports drop-in configuration in `.container.d/` directories. + +For example, a drop-in: + +``` +test.container.d/10-extra.conf +``` + +can override or extend the main unit file. + +Drop-ins follow the same override and merging behavior as systemd units. + +# EXAMPLE + +Minimal container unit: + +``` +[Unit] +Description=A minimal container + +[Container] +Image=quay.io/centos/centos:latest +Exec=sleep 60 + +[Install] +WantedBy=multi-user.target +``` + +# SEE ALSO + +[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html), +[systemd.service(5)](https://www.freedesktop.org/software/systemd/man/systemd.service.html), +[systemd-analyze(1)](https://www.freedesktop.org/software/systemd/man/latest/systemd-analyze.html), +[podman-run(1)](https://docs.podman.io/en/latest/markdown/podman-run.1.html), +[podman-quadlet(7)] diff --git a/docs/source/markdown/podman-generate-systemd.1.md b/docs/source/markdown/podman-generate-systemd.1.md index cd6c637bd7..2d5eb34dad 100644 --- a/docs/source/markdown/podman-generate-systemd.1.md +++ b/docs/source/markdown/podman-generate-systemd.1.md @@ -8,7 +8,7 @@ podman\-generate\-systemd - [DEPRECATED] Generate systemd unit file(s) for a con ## DESCRIPTION DEPRECATED: -Note: **podman generate systemd** is deprecated. We recommend using [Quadlet](podman-systemd.unit.5.md) +Note: **podman generate systemd** is deprecated. We recommend using [Quadlet](podman-quadlet.7.md) files when running Podman containers or pods under systemd. There are no plans to remove the command. It will receive urgent bug fixes but no new features. @@ -311,7 +311,7 @@ CONTAINER ID IMAGE COMMAND CREATED STATUS bb310a0780ae docker.io/library/alpine:latest /bin/sh 3 minutes ago Created busy_moser ``` ## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-container(1)](podman-container.1.md)**, **systemctl(1)**, **systemd.unit(5)**, **systemd.service(5)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**, **[podman-systemd.unit(5)](podman-systemd.unit.5.md)** +**[podman(1)](podman.1.md)**, **[podman-container(1)](podman-container.1.md)**, **systemctl(1)**, **systemd.unit(5)**, **systemd.service(5)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**, **[podman-quadlet(7)](podman-quadlet.7.md)** ## HISTORY April 2020, Updated details and added use case to use generated .service files as root and non-root, by Sujil Shah (sushah at redhat dot com) diff --git a/docs/source/markdown/podman-image.unit.5.md.in b/docs/source/markdown/podman-image.unit.5.md.in new file mode 100644 index 0000000000..512e9f4702 --- /dev/null +++ b/docs/source/markdown/podman-image.unit.5.md.in @@ -0,0 +1,199 @@ +% 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`. + +The reference to the `.image` file can be used in the `.container` file's `Image=` option. + +# FILE LOCATIONS + +Place `.image` files in one of the following: + +### Rootless + +- `$XDG_RUNTIME_DIR/containers/systemd/` +- `$XDG_CONFIG_HOME/containers/systemd/` or `~/.config/containers/systemd/` +- `/etc/containers/systemd/users/$(UID)` +- `/etc/containers/systemd/users/` + +### Rootful + +- `/run/containers/systemd/` +- `/etc/containers/systemd/` +- `/usr/share/containers/systemd/` + +# 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 | + +### `AllTags=` + +All tagged images in the repository are pulled. + +This is equivalent to the Podman `--all-tags` option. + +@@option quadlet:arch + +@@option quadlet:authfile + +@@option quadlet:cert-dir + +@@option quadlet:module + +@@option quadlet:creds + +@@option quadlet:decryption-key + +### `GlobalArgs=` + +This key contains a list of arguments passed directly between `podman` and `image` +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`. So, it supports using +`:tag` or digests to guarantee the specific image version. + +### `ImageTag=` + +Actual FQIN of the referenced `Image`. +Only meaningful when 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` + +@@option quadlet:os.pull + +### `PodmanArgs=` + +This key contains a list of arguments passed directly to the end of the `podman image pull` command +in the generated file (right before the image name in the command line). 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. + +### `Policy=` + +The pull policy to use when pulling the image. + +This is equivalent to the Podman `--policy` option. + +@@option quadlet:retry + +@@option quadlet:retry-delay + +@@option quadlet:tls-verify + +@@option quadlet:variant.container + + +## Quadlet section [Quadlet] +Some quadlet specific configuration is shared between different unit types. Those settings +can be configured in the `[Quadlet]` section. + +Valid options for `[Quadlet]` are listed below: + +| **[Quadlet] options** | **Description** | +|----------------------------|---------------------------------------------------| +| DefaultDependencies=false | Disable implicit network dependencies to the unit | + +### `DefaultDependencies=` + +Add Quadlet's default network dependencies to the unit (default is `true`). + +When set to false, Quadlet will **not** add a dependency (After=, Wants=) to +`network-online.target`/`podman-user-wait-network-online.service` to the generated unit. + +Note, this option is set in the `[Quadlet]` section. The _systemd_ `[Unit]` section +has an option with the same name but a different meaning. + +# 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 + +[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html), +[podman-image-pull(1)](https://docs.podman.io/en/latest/markdown/podman-image-pull.1.html), +[podman-quadlet(7)] diff --git a/docs/source/markdown/podman-kube.unit.5.md.in b/docs/source/markdown/podman-kube.unit.5.md.in new file mode 100644 index 0000000000..075a97cd22 --- /dev/null +++ b/docs/source/markdown/podman-kube.unit.5.md.in @@ -0,0 +1,173 @@ +% podman-kube.unit(5) + +# NAME + +podman\-kube.unit - systemd unit files for managing Podman Kubernetes YAML deployments using Quadlet + +# SYNOPSIS + +*name*.kube + +# DESCRIPTION + +Kube units are named with a `.kube` extension and contain a `[Kube]` section describing +how `podman kube play` runs as a service. The resulting service file contains a line like +`ExecStart=podman kube play … file.yml`, and most of the keys in this section control the command-line +options passed to Podman. However, some options also affect the details of how systemd is set up to run and +interact with the container. + +There is only one required key, `Yaml`, which defines the path to the Kubernetes YAML file. + +# USAGE SUMMARY + +The `.kube` file is parsed by the `podman-system-generator` at boot or reload, generating a systemd +`.service` that runs `podman kube play`. That service can be managed like any other unit: + +```bash +systemctl --user start name.service +``` + +# FILE LOCATIONS + +Place `.kube` files in one of the following: + +### Rootless + +- `$XDG_RUNTIME_DIR/containers/systemd/` +- `$XDG_CONFIG_HOME/containers/systemd/` or `~/.config/containers/systemd/` +- `/etc/containers/systemd/users/$(UID)` +- `/etc/containers/systemd/users/` + +### Rootful + +- `/run/containers/systemd/` +- `/etc/containers/systemd/` +- `/usr/share/containers/systemd/` + +# OPTIONS + +Valid options for `[Kube]` are listed below: + +| **[Kube] options** | **podman kube play equivalent** | +| ------------------------------------| -----------------------------------------------------------------| +| AutoUpdate=registry | --annotation "io.containers.autoupdate=registry" | +| ConfigMap=/tmp/config.map | --config-map /tmp/config.map | +| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | +| ExitCodePropagation=how | How to propagate container error status | +| GlobalArgs=--log-level=debug | --log-level=debug | +| KubeDownForce=true | --force (for `podman kube down`) | +| LogDriver=journald | --log-driver journald | +| Network=host | --network host | +| PodmanArgs=\-\-annotation=key=value | --annotation=key=value | +| PublishPort=8080:80 | --publish 8080:80 | +| SetWorkingDirectory=yaml | Set `WorkingDirectory` of unit file to location of the YAML file | +| UserNS=keep-id:uid=200,gid=210 | --userns keep-id:uid=200,gid=210 | +| Yaml=/tmp/kube.yaml | podman kube play /tmp/kube.yaml | + +Supported keys in the `[Kube]` section are: + + +### `AutoUpdate=` + +Indicates whether containers will be auto-updated ([podman-auto-update(1)](podman-auto-update.1.md)). AutoUpdate can be specified multiple times. The following values are supported: + +* `registry`: Requires a fully-qualified image reference (e.g., quay.io/podman/stable:latest) to be used to create the container. This enforcement is necessary to know which images to actually check and pull. If an image ID was used, Podman does not know which image to check/pull anymore. + +* `local`: Tells Podman to compare the image a container is using to the image with its raw name in local storage. If an image is updated locally, Podman simply restarts the systemd unit executing the Kubernetes Quadlet. + +* `name/(local|registry)`: Tells Podman to perform the `local` or `registry` autoupdate on the specified container name. + +### `ConfigMap=` + +Pass the Kubernetes ConfigMap YAML path to `podman kube play` via the `--configmap` argument. +Unlike the `configmap` argument, the value may contain only one path but +it may be absolute or relative to the location of the unit file. + +This key may be used multiple times + +@@option quadlet:module + +### `ExitCodePropagation=` + +Control how the main PID of the systemd service should exit. The following values are supported: +- `all`: exit non-zero if all containers have failed (i.e., exited non-zero) +- `any`: exit non-zero if any container has failed +- `none`: exit zero and ignore failed containers + +The current default value is `none`. + +### `GlobalArgs=` + +This key contains a list of arguments passed directly between `podman` and `kube` +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. + +### `KubeDownForce=` + +Remove all resources, including volumes, when calling `podman kube down`. +Equivalent to the Podman `--force` option. + +@@option quadlet:log-driver + +@@option quadlet:network + +### `PodmanArgs=` + +This key contains a list of arguments passed directly to the end of the `podman kube play` command +in the generated file (right before the path to the yaml file in the command line). 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, 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. + +@@option quadlet:publish + +### `SetWorkingDirectory=` + +Set the `WorkingDirectory` field of the `Service` group of the Systemd service unit file. +Used to allow `podman kube play` to correctly resolve relative paths. +Supported values are `yaml` and `unit` to set the working directory to that of the YAML or Quadlet Unit file respectively. + +Alternatively, users can explicitly set the `WorkingDirectory` field of the `Service` group in the `.kube` file. +Please note that if the `WorkingDirectory` field of the `Service` group is set, +Quadlet will not set it even if `SetWorkingDirectory` is set + +@@option quadlet:userns.container + +### `Yaml=` + +The path, absolute or relative to the location of the unit file, to the Kubernetes YAML file to use. + + +# EXAMPLES + +Deploy from local YAML: + +``` +[Unit] +Description=A kubernetes yaml based service +Before=local-fs.target + +[Kube] +Yaml=/opt/k8s/deployment.yml + +[Install] +# Start by default on boot +WantedBy=multi-user.target default.target +``` + +# SEE ALSO + +[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html), +[podman-kube-play(1)](https://docs.podman.io/en/latest/markdown/podman-kube-play.1.html), +[podman-quadlet(7)] diff --git a/docs/source/markdown/podman-network.unit.5.md.in b/docs/source/markdown/podman-network.unit.5.md.in new file mode 100644 index 0000000000..510eec3596 --- /dev/null +++ b/docs/source/markdown/podman-network.unit.5.md.in @@ -0,0 +1,214 @@ +% podman-network.unit(5) + +# NAME + +podman\-network.unit - systemd unit files for managing Podman networks using Quadlet + +# SYNOPSIS + +*name*.network + +# DESCRIPTION + +Network files are named with a `.network` extension and contain a section `[Network]` describing the +named Podman network. The generated service is a one-time command that ensures that the network +exists on the host, creating it if needed. + +By default, the Podman network has the same name as the unit, but with a `systemd-` prefix, i.e. for +a network file named `$NAME.network`, the generated Podman network is called `systemd-$NAME`, and +the generated service file is `$NAME-network.service`. The `NetworkName` option allows for +overriding this default name with a user-provided one. + +Please note that stopping the corresponding service will not remove the podman network. +In addition, updating an existing network is not supported. +In order to update the network parameters you will first need to manually remove the podman network and then restart the service. + +Using network units allows containers to depend on networks being automatically pre-created. This is +particularly interesting when using special options to control network creation, as Podman otherwise creates networks with the default options. + +# FILE LOCATIONS + +Place `.image` files in one of the following: + +### Rootless + +- `$XDG_RUNTIME_DIR/containers/systemd/` +- `$XDG_CONFIG_HOME/containers/systemd/` or `~/.config/containers/systemd/` +- `/etc/containers/systemd/users/$(UID)` +- `/etc/containers/systemd/users/` + +### Rootful + +- `/run/containers/systemd/` +- `/etc/containers/systemd/` +- `/usr/share/containers/systemd/` + +# OPTIONS + +Valid options for `[Network]` are listed below: + +| **[Network] options** | **podman network create equivalent** | +|-------------------------------------|-----------------------------------------------------------------| +| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | +| DisableDNS=true | --disable-dns | +| DNS=192.168.55.1 | --dns=192.168.55.1 | +| Driver=bridge | --driver bridge | +| Gateway=192.168.55.3 | --gateway 192.168.55.3 | +| GlobalArgs=--log-level=debug | --log-level=debug | +| InterfaceName=enp1 | --interface-name enp1 | +| Internal=true | --internal | +| IPAMDriver=dhcp | --ipam-driver dhcp | +| IPRange=192.168.55.128/25 | --ip-range 192.168.55.128/25 | +| IPv6=true | --ipv6 | +| Label="XYZ" | --label "XYZ" | +| NetworkDeleteOnStop=true | Add ExecStopPost to delete the network when the unit is stopped | +| NetworkName=foo | podman network create foo | +| Options=isolate=true | --opt isolate=true | +| PodmanArgs=--dns=192.168.55.1 | --dns=192.168.55.1 | +| Subnet=192.5.0.0/16 | --subnet 192.5.0.0/16 | + +Supported keys in `[Network]` section are: + +@@option quadlet:module + +### `DisableDNS=` (defaults to `false`) + +If enabled, disables the DNS plugin for this network. + +This is equivalent to the Podman `--disable-dns` option + +@@option quadlet:dns + +### `Driver=` (defaults to `bridge`) + +Driver to manage the network. Currently `bridge`, `macvlan` and `ipvlan` are supported. + +This is equivalent to the Podman `--driver` option + +### `Gateway=` + +Define a gateway for the subnet. If you want to provide a gateway address, you must also provide a subnet option. + +This is equivalent to the Podman `--gateway` option + +This key can be listed multiple times. + +### `GlobalArgs=` + +This key contains a list of arguments passed directly between `podman` and `network` +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. + +### `InterfaceName=` + +This option maps the *network_interface* option in the network config, see **podman network inspect**. +Depending on the driver, this can have different effects; for `bridge`, it uses the bridge interface name. +For `macvlan` and `ipvlan`, it is the parent device on the host. It is the same as `--opt parent=...`. + +This is equivalent to the Podman `--interface-name` option. + +### `Internal=` (defaults to `false`) + +Restrict external access of this network. + +This is equivalent to the Podman `--internal` option + +### `IPAMDriver=` + +Set the ipam driver (IP Address Management Driver) for the network. Currently `host-local`, `dhcp` and `none` are supported. + +This is equivalent to the Podman `--ipam-driver` option + +### `IPRange=` + +Allocate container IP from a range. The range must be a either a complete subnet in CIDR notation or be +in the `-` syntax which allows for a more flexible range compared to the CIDR subnet. +The ip-range option must be used with a subnet option. + +This is equivalent to the Podman `--ip-range` option + +This key can be listed multiple times. + +### `IPv6=` + +Enable IPv6 (Dual Stack) networking. + +This is equivalent to the Podman `--ipv6` option + +### `Label=` + +Set one or more OCI labels on the network. The format is a list of +`key=value` items, similar to `Environment`. + +This key can be listed multiple times. + +### `NetworkDeleteOnStop=` (defaults to `false`) + +When set to `true` the network is deleted when the service is stopped + +### `NetworkName=` + +The (optional) name of the Podman network. +If this is not specified, the default value is the same name as the unit, but with a `systemd-` prefix, +i.e. a `$name.network` file creates a `systemd-$name` Podman network to avoid +conflicts with user-managed network. + +### `Options=` + +Set driver specific options. + +This is equivalent to the Podman `--opt` option + +### `PodmanArgs=` + +This key contains a list of arguments passed directly to the end of the `podman network create` command +in the generated file (right before the name of the network in the command line). 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, 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. + +### `Subnet=` + +The subnet in CIDR notation. + +This is equivalent to the Podman `--subnet` option + +This key can be listed multiple times. + +# EXAMPLES + +Basic bridge network: + +``` +[Network] +NetworkName=private0 +Subnet=10.10.0.0/16 +Gateway=10.10.0.1 +``` + +Enable IPv6 with IPAM driver: + +``` +[Network] +NetworkName=v6net +Subnet=fd00:dead:beef::/64 +IPv6=true +IPAMDriver=host-local +``` + +# SEE ALSO + +[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html), +[podman-network-create(1)](https://docs.podman.io/en/latest/markdown/podman-network-create.1.html), +[podman-quadlet(7)] diff --git a/docs/source/markdown/podman-pod.unit.5.md.in b/docs/source/markdown/podman-pod.unit.5.md.in new file mode 100644 index 0000000000..efbae70b6a --- /dev/null +++ b/docs/source/markdown/podman-pod.unit.5.md.in @@ -0,0 +1,181 @@ +% podman-pod.unit(5) + +# NAME + +podman\-pod.unit - systemd unit files for managing Podman pods using Quadlet + +# SYNOPSIS + +*name*.pod + +# DESCRIPTION + +Pod units are named with a `.pod` extension and contain a `[Pod]` section describing +the pod that is created and run as a service. The resulting service file contains a line like +`ExecStartPre=podman pod create …`, and most of the keys in this section control the command-line +options passed to Podman. + +By default, the Podman pod has the same name as the unit, but with a `systemd-` prefix, i.e. +a `$name.pod` file creates a `$name-pod.service` unit and a `systemd-$name` Podman pod. The +`PodName` option allows for overriding this default name with a user-provided one. + +# FILE LOCATIONS + +Place `.pod` files in one of the following: + +### Rootless + +- `$XDG_RUNTIME_DIR/containers/systemd/` +- `$XDG_CONFIG_HOME/containers/systemd/` or `~/.config/containers/systemd/` +- `/etc/containers/systemd/users/$(UID)` +- `/etc/containers/systemd/users/` + +### Rootful + +- `/run/containers/systemd/` +- `/etc/containers/systemd/` +- `/usr/share/containers/systemd/` + +# OPTIONS + +Valid options for `[Pod]` are listed below: + +| **[Pod] options** | **podman pod create equivalent** | +|-------------------------------------|----------------------------------------| +| AddHost=example\.com:192.168.10.11 | --add-host example.com:192.168.10.11 | +| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | +| DNS=192.168.55.1 | --dns=192.168.55.1 | +| DNSOption=ndots:1 | --dns-option=ndots:1 | +| DNSSearch=example.com | --dns-search example.com | +| ExitPolicy=stop | --exit-policy stop | +| GIDMap=0:10000:10 | --gidmap=0:10000:10 | +| GlobalArgs=--log-level=debug | --log-level=debug | +| HostName=name | --hostname=name | +| IP=192.5.0.1 | --ip 192.5.0.1 | +| IP6=2001:db8::1 | --ip6 2001:db8::1 | +| Label="XYZ" | --label "XYZ" | +| Network=host | --network host | +| NetworkAlias=name | --network-alias name | +| PodmanArgs=\-\-cpus=2 | --cpus=2 | +| PodName=name | --name=name | +| PublishPort=8080:80 | --publish 8080:80 | +| ServiceName=name | Name the systemd unit `name.service` | +| ShmSize=100m | --shm-size=100m | +| SubGIDMap=gtest | --subgidname=gtest | +| SubUIDMap=utest | --subuidname=utest | +| UIDMap=0:10000:10 | --uidmap=0:10000:10 | +| UserNS=keep-id:uid=200,gid=210 | --userns keep-id:uid=200,gid=210 | +| Volume=/source:/dest | --volume /source:/dest | + +Supported keys in the `[Pod]` section are: + +@@option quadlet:add-host + +@@option quadlet:module + +@@option quadlet:dns + +@@option quadlet:dns-option.container + +### `ExitPolicy=` + +Set the exit policy of the pod when the last container exits. Default for quadlets is **stop**. + +To keep the pod active, set `ExitPolicy=continue`. + +@@option quadlet:gidmap.container + +### `GlobalArgs=` + +This key contains a list of arguments passed directly between `podman` and `pod` +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. + +@option quadlet::hostname.container + +@@option quadlet:ip + +@@option quadlet:ip6 + +@@option quadlet:label + +@@option quadlet:network + +@@option quadlet:network-alias + +### `PodmanArgs=` + +This key contains a list of arguments passed directly to the end of the `podman pod create` 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, 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. + +### `PodName=` + +The (optional) name of the Podman pod. +If this is not specified, the default value is the same name as the unit, but with a `systemd-` prefix, +i.e. a `$name.pod` file creates a `systemd-$name` Podman pod to avoid conflicts with user-managed pods. + +Please note that pods and containers cannot have the same name. +So, if PodName is set, it must not conflict with any container. + +@@option quadlet:publish + +### `ServiceName=` + +By default, Quadlet will name the systemd service unit by appending `-pod` to the name of the Quadlet. +Setting this key overrides this behavior by instructing Quadlet to use the provided name. + +Note, the name should not include the `.service` file extension + +@@option quadlet:shm-size + +@@option quadlet:subgidname + +@@option quadlet:subuidname + +@@option quadlet:uidmap.pod + +@@option quadlet:userns.pod + +@@option quadlet:volume + + +# EXAMPLES + +Example for Container in a Pod: + +test.pod: + +``` +[Pod] +PodName=test +centos.container +``` + +centos.container: + +``` +[Container] +Image=quay.io/centos/centos:latest +Exec=sh -c "sleep inf" +Pod=test.pod +``` + +# SEE ALSO + +[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html), +[podman-kube-play(1)](https://docs.podman.io/en/latest/markdown/podman-kube-play.1.html), +[podman-quadlet(7)] + diff --git a/docs/source/markdown/podman-quadlet-basic-usage.7.md b/docs/source/markdown/podman-quadlet-basic-usage.7.md new file mode 100644 index 0000000000..b7e597c461 --- /dev/null +++ b/docs/source/markdown/podman-quadlet-basic-usage.7.md @@ -0,0 +1,218 @@ +% podman-quadlet-basic-usage(7) + +# NAME + +podman\-quadlet\-basic\-usage - Basic usage examples and step-by-step guide for Podman Quadlet + +# DESCRIPTION + +This guide introduces common usage patterns for Podman Quadlet. It provides step-by-step examples for defining +containers, exposing ports, creating volumes, and establishing dependencies using declarative `.container`, `.volume`, +and related unit files. + +Quadlet simplifies container lifecycle management by translating these files into systemd services, making them +manageable with `systemctl`. + +# EXAMPLE 1: RUNNING A SIMPLE CONTAINER + +## Step 1: Create `hello.container` + +```ini +[Unit] +Description=Hello Alpine Container + +[Container] +Image=alpine +Exec=echo Hello from Quadlet! + +[Install] +WantedBy=multi-user.target +``` + +## Step 2: Place the file + +For rootless use: +```bash +mkdir -p ~/.config/containers/systemd +cp hello.container ~/.config/containers/systemd/ +``` + +For rootful use: +```bash +sudo cp hello.container ~/etc/containers/systemd/ +``` + +## Step 3: Reload and enable the service + +For rootless use: +```bash +systemctl --user daemon-reload +systemctl --user start hello.service +``` + +For rootful use: +```bash +sudo systemctl daemon-reload +sudo systemctl enable --now hello.service +``` + +## Expected Output: + +For rootles, check logs using: +```bash +journalctl --user -u hello.service +``` + +For rootful: +```bash +journalctl -u hello.service +``` + +You should see: `Hello from Quadlet!` + +That means the container started, executed the echo statement and exited. + +# EXAMPLE 2: CREATING A NAMED VOLUME + +## Step 1: Create `mydata.volume` + +```ini +[Volume] +VolumeName=mydata +Label=purpose=demo +``` + +## Step 2: Place and reload + +For rootless use: +```bash +mkdir -p ~/.config/containers/systemd +cp mydata.volume ~/.config/containers/systemd/ +systemctl --user daemon-reload +``` + +For rootful use: +```bash +sudo cp mydata.volume /etc/containers/systemd/ +sudo systemctl daemon-reload +``` + +## Step 3: Create the volume + +For rootless use: +```bash +systemctl --user start mydata-volume.service +``` + +For rootful use: +```bash +systemctl start mydata-volume.service +``` + +# EXAMPLE 3: CONTAINER USING A VOLUME + +## Create `with-volume.container` + +```ini +[Unit] +Description=Container with Mounted Volume + +[Container] +Image=alpine +Exec=sh -c "ls /data && echo Hello > /data/hello.txt" +Volume=mydata.volume:/data + +[Install] +WantedBy=default.target +``` + +This container shows all the files on volume and creates the `hello.txt`. + +## Start the container and check the status + +For rootless use: +```bash +cp with-volume.container ~/.config/containers/systemd/ +systemctl --user daemon-reload +systemctl --user start with-volume.service +systemctl --user status with-volume.service +``` + +For rootful use: +```bash +sudo cp with-volume.container /etc/containers/systemd/ +sudo systemctl daemon-reload +sudo systemctl start with-volume.service +sudo systemctl status with-volume.service +``` + +When started for the first time, the `hello.txt` will not appear in the +`systemctl status` output, because it has not been created yet. But when +started for the second time, the output will be: + +``` +hello.txt +``` + +This means the volume is used and is persistent. + +# EXAMPLE 4: EXPOSE CONTAINER PORT TO HOST + +## Create `webserver.container` + +```ini +[Unit] +Description=Nginx Webserver + +[Container] +Image=nginx:alpine +PublishPort=8080:80 + +[Install] +WantedBy=default.target +``` + +## Start the web server + +For rootless use: +```bash +cp webserver.container ~/.config/containers/systemd/ +systemctl --user daemon-reload +systemctl --user start webserver.service +``` + +For rootful use: +```bash +sudo cp webserver.container ~/.config/containers/systemd/ +sudo systemctl daemon-reload +sudo systemctl start webserver.service +``` + +Visit `http://localhost:8080` in your browser. + +# TIPS + +To start a container on system boot, use: + +``` +[Install] +WantedBy=multi-user.target default.target +``` + +If the `foo.service` file is not generated, it usually means there is a syntax +error in your quadlet file. To find the details, use: + +```bash +systemd-analyze --user --generators=true verify foo.service +``` + +# SEE ALSO + +[podman-quadlet(7)](podman-quadlet.7.md), +[podman-container.unit(5)](podman-container.unit.5.md), +[podman-volume.unit(5)](podman-volume.unit.5.md), +[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html) + +# AUTHORS + +Podman Team diff --git a/docs/source/markdown/podman-quadlet.7.md b/docs/source/markdown/podman-quadlet.7.md new file mode 100644 index 0000000000..0d2c786a81 --- /dev/null +++ b/docs/source/markdown/podman-quadlet.7.md @@ -0,0 +1,94 @@ +% podman-quadlet(7) + +# NAME + +podman\-quadlet - High-level overview of Podman Quadlet integration with systemd + +# DESCRIPTION + +Podman Quadlet is a systemd unit generator that enables declarative container management by defining +Podman resources using specialized systemd unit files. It provides an interface between Podman and systemd, +allowing users to manage containers, pods, volumes, images, and more through native systemd service units. + +Quadlet parses `.container`, `.pod`, `.volume`, `.network`, `.image`, `.build`, and `.kube` files located in +well-known directories and converts them into corresponding `.service` units for systemd. These units are then +used to create and manage container resources on boot or via explicit `systemctl` commands. + +# PURPOSE + +Quadlet's goal is to bridge the gap between container lifecycle management and system initialization. It lets +you define container infrastructure declaratively, leveraging systemd's features such as dependency ordering, +restart policies, boot-time activation, logging, and drop-in configuration. + +It eliminates the need to write complex `ExecStart=` lines or manage custom systemd services manually. + +# BENEFITS + +- Declarative and human-readable unit definitions +- Seamless integration with native systemd features +- Consistent naming and dependency management +- Support for advanced Podman features (pods, kube, image builds) +- Rootless and rootful compatibility +- Drop-in override support for all unit types + +# INTEGRATION WITH SYSTEMD + +At boot time, the `podman-system-generator` reads Quadlet unit files from predefined directories and translates +them into `.service` files under `/run/systemd/generator/`. These generated services are treated like native +systemd units and can be enabled, started, and inspected using standard tools such as: + +```bash +systemctl enable my-container.service +systemctl start my-container.service +journalctl -u my-container.service +``` + +Quadlet integrates cleanly with both rootless and rootful Podman environments, depending on the search paths used. + +# FILE TYPES + +Quadlet supports the following file types: + +- **`.container`** — Defines and manages a single container. See **podman-container.unit(5)**. +- **`.pod`** — Creates a Podman pod that containers can join. See **podman-pod.unit(5)**. +- **`.volume`** — Ensures a named Podman volume exists. See **podman-volume.unit(5)**. +- **`.network`** — Creates a Podman network for containers and pods. See **podman-network.unit(5)**. +- **`.image`** — Pulls and caches a container image. See **podman-image.unit(5)**. +- **`.build`** — Builds a container image from a Containerfile. See **podman-build.unit(5)**. +- **`.kube`** — Deploys containers from Kubernetes YAML using `podman kube play`. See **podman-kube.unit(5)**. + +Each file is mapped to a corresponding `.service` unit with a predictable naming pattern, typically appending +`-.service` to the unit base name. + +# FILE PATHS + +Quadlet files should be stored in specific directories depending on rootless or rootful execution. + +## Rootful + +- `/run/containers/systemd/` +- `/etc/containers/systemd/` +- `/usr/share/containers/systemd/` + +## Rootless + +- `$XDG_RUNTIME_DIR/containers/systemd/` +- `$XDG_CONFIG_HOME/containers/systemd/` or `~/.config/containers/systemd/` +- `/etc/containers/systemd/users/$(UID)` +- `/etc/containers/systemd/users/` + +# SEE ALSO + +[podman-quadlet(7)](https://docs.podman.io/en/latest/markdown/podman-quadlet.7.html), +[podman-container.unit(5)](podman-container.unit.5.md), +[podman-pod.unit(5)](podman-pod.unit.5.md), +[podman-volume.unit(5)](podman-volume.unit.5.md), +[podman-network.unit(5)](podman-network.unit.5.md), +[podman-image.unit(5)](podman-image.unit.5.md), +[podman-build.unit(5)](podman-build.unit.5.md), +[podman-kube.unit(5)](podman-kube.unit.5.md), +[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html) + +# AUTHORS + +Podman Team diff --git a/docs/source/markdown/podman-systemd.unit.5.md b/docs/source/markdown/podman-systemd.unit.5.md deleted file mode 100644 index 480f08eb22..0000000000 --- a/docs/source/markdown/podman-systemd.unit.5.md +++ /dev/null @@ -1,2279 +0,0 @@ -% podman-systemd.unit 5 - -## NAME - -podman\-systemd.unit - systemd units using Podman Quadlet - -## SYNOPSIS - -*name*.container, *name*.volume, *name*.network, *name*.kube *name*.image, *name*.build *name*.pod - -### Podman rootful unit search path - -Quadlet files for the root user can be placed in the following directories ordered in precedence. Meaning duplicate named quadlets found under /run take precedence over ones in /etc, as well as those in /usr: - -Temporary quadlets, usually used for testing: - -* /run/containers/systemd/ - -System administrator's defined quadlets: - -* /etc/containers/systemd/ - -Distribution defined quadlets: - -* /usr/share/containers/systemd/ - -### Podman rootless unit search path - -Quadlet files for non-root users can be placed in the following directories: - - * $XDG_RUNTIME_DIR/containers/systemd/ - * $XDG_CONFIG_HOME/containers/systemd/ or ~/.config/containers/systemd/ - * /etc/containers/systemd/users/$(UID) - * /etc/containers/systemd/users/ - -### Using symbolic links - -Quadlet supports using symbolic links for the base of the search paths and inside them. - -## DESCRIPTION - -Podman supports building and starting containers (and creating volumes) via systemd by using a -[systemd generator](https://www.freedesktop.org/software/systemd/man/systemd.generator.html). -These files are read during boot (and when `systemctl daemon-reload` is run) and generate -corresponding regular systemd service unit files. Both system and user systemd units are supported. -All options and tables available in standard systemd unit files are supported. For example, options defined in -the [Service] table and [Install] tables pass directly to systemd and are handled by it. -See systemd.unit(5) man page for more information. - -The Podman generator reads the search paths above and reads files with the extensions `.container` -`.volume`, `.network`, `.build`, `.pod` and `.kube`, and for each file generates a similarly named `.service` file. Be aware that -existing vendor services (i.e., in `/usr/`) are replaced if they have the same name. The generated unit files can -be started and managed with `systemctl` like any other systemd service. `systemctl {--user} list-unit-files` -lists existing unit files on the system. - -The Podman files use the same format as [regular systemd unit files](https://www.freedesktop.org/software/systemd/man/systemd.syntax.html). -Each file type has a custom section (for example, `[Container]`) that is handled by Podman, and all -other sections are passed on untouched, allowing the use of any normal systemd configuration options -like dependencies or cgroup limits. - -The source files also support drop-ins in the same [way systemd does](https://www.freedesktop.org/software/systemd/man/latest/systemd.unit.html). -For a given source file (`foo.container`), the corresponding `.d` directory (`foo.container.d`) will -be scanned for files with a `.conf` extension, which are then merged into the base file in alphabetical -order. Top-level type drop-ins (`container.d`) will also be included. If the unit contains dashes ("-") -in the name (`foo-bar-baz.container`), then the drop-in directories generated by truncating the name after -the dash are searched as well (`foo-.container.d` and `foo-bar-.container.d`). Drop-in files with the same name -further down the hierarchy override those further up (`foo-bar-baz.container.d/10-override.conf` overrides -`foo-bar-.container.d/10-override.conf`, which overrides `foo-.service.d/10-override.conf`, which overrides -`container.d/10-override.conf`). The format of these drop-in files is the same as the base file. This is useful -to alter or add configuration settings for a unit, without having to modify unit files. - -For rootless containers, when administrators place Quadlet files in the -/etc/containers/systemd/users directory, all users' sessions execute the -Quadlet when the login session begins. If the administrator places a Quadlet -file in the /etc/containers/systemd/users/${UID}/ directory, then only the -user with the matching UID executes the Quadlet when the login -session gets started. For unit files placed in subdirectories within -/etc/containers/systemd/user/${UID}/ and the other user unit search paths, -Quadlet will recursively search and run the unit files present in these subdirectories. - -Note that Quadlet units do not support running as a non-root user by defining the -[User, Group](https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#User=), -or [DynamicUser](https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#DynamicUser=) -systemd options. If you want to run a rootless Quadlet, you will need to create the user -and add the unit file to one of the above rootless unit search paths. - -Note: When a Quadlet is starting, Podman often pulls or builds one more container images which may take a considerable amount of time. -Systemd defaults service start time to 90 seconds, or fails the service. Pre-pulling the image or extending -the systemd timeout time for the service using the *TimeoutStartSec* Service option can fix the problem. -A word of caution: *TimeoutStartSec* is not available for `Type=oneshot` units. Refer to `systemd.service(5)` -for more information on how to handle long startup times for units which do not need to stay active -once their main process has finished. - -Adding the following snippet to a Quadlet file extends the systemd timeout to 15 minutes. - -``` -[Service] -TimeoutStartSec=900 -``` - -Quadlet requires the use of cgroup v2, use `podman info --format {{.Host.CgroupsVersion}}` to check on the system. - -### Service Type - -By default, the `Type` field of the `Service` section of the Quadlet file does not need to be set. -Quadlet will set it to `notify` for `.container` and `.kube` files, -`forking` for `.pod` files, and `oneshot` for `.volume`, `.network`, `.build`, and `.image` files. - -However, `Type` may be explicitly set to `oneshot` for `.container` and `.kube` files when no containers are expected -to run once `podman` exits. - -When setting `Type=oneshot`, it is recommended to also set `RemainAfterExit=yes` to prevent the service state -from becoming `inactive (dead)`. However, when activating a service via a timer unit, having `RemainAfterExit=yes` -leaves the job in a "started" state which prevents subsequent activations by the timer. For more information, see the -`systemd.service(5)` man page. - -Examples for such cases: -- `.container` file with an image that exits after their entrypoint has finished - -- `.kube` file pointing to a Kubernetes Yaml file that does not define any containers. E.g. PVCs only - -### Enabling unit files - -The services created by Podman are considered transient by systemd, which means they don't have the same -persistence rules as regular units. In particular, it is not possible to `systemctl enable` them -in order for them to become automatically enabled on the next boot. - -To compensate for this, the generator manually applies the `[Install]` section of the container definition -unit files during generation, in the same way `systemctl enable` does when run later. - -For example, to start a container on boot, add something like this to the file: - -``` -[Install] -WantedBy=default.target -``` - -Currently, only the `Alias`, `WantedBy`, `RequiredBy`, and `UpheldBy` keys are supported. - -The Install section can be part of the main file, or it can be in a -separate drop-in file as described above. The latter allows you to -install an non-enabled unit and then later enabling it by installing -the drop-in. - -### Template files - -Systemd supports a concept of [template files](https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html#Service%20Templates). -They are units with names of the form "basename@instancename.service" -when they are running, but that can be instantiated multiple times -from a single "basename@.service" file. The individual instances can -also be different by using drop-in files with the full instance name. - -Quadlets support these in two ways. First of all, a quadlet unit with -a template form will generate a systemd service with a template form, -and the template systemd service can be used as a regular template. -For example, "foo@.container" will generate "foo@.service" and you can -then "systemctl start foo@bar.service". - -Secondly, if you make a symlink like "foo@instance.container", that -will generate an instantiated template file. When generating this file -quadlet will read drop-in files both from the instanced directory -(foo@instance.container.d) and the template directory -(foo@.container.d). This allows customization of individual instances. - -Instanced template files (like `foo@bar.container`) can be enabled -just like non-templated ones. However, templated ones -(`foo@.container`) are different, because they need to be -instantiated. If the `[Install]` section contains a `DefaultInstance=` -key, then that instance will be enabled, but if not, nothing will -happen and the options will only be used as the default for units -that are instantiated using symlinks. - -An example template file `sleep@.container` might look like this: - -``` -[Unit] -Description=A templated sleepy container - -[Container] -Image=quay.io/fedora/fedora -Exec=sleep %i - -[Service] -# Restart service when sleep finishes -Restart=always - -[Install] -WantedBy=multi-user.target -DefaultInstance=100 -``` - -If this is installed, then on boot there will be a `sleep@100.service` -running that sleeps for 100 seconds. You can then do something like -`systemctl start sleep@50.service` to start another instance that -sleeps 50 seconds, or alternatively another service can start it via a -dependency like `Wants=sleep@50.service`. - -In addition, if you do `ln -s sleep@.container sleep@10.container` you -will also have a 10 second sleep running at boot. And, if you want -that particular instance to be running with another image, you can -create a drop-in file like `sleep@10.container.d/10-image.conf`: -``` -[Container] -Image=quay.io/centos/centos -``` - -### Relative paths - -In order to support Systemd specifiers, Quadlet does not resolve relative paths that start with `%`. -To resolve such a path, prepend it with `./`. - -For example, instead of `EnvironmentFile=%n/env` use `EnvironmentFile=./%n/env` - -### Debugging unit files - -After placing the unit file in one of the unit search paths (mentioned -above), you can start it with `systemctl start {--user}`. If it fails -with "Failed to start example.service: Unit example.service not -found.", then it is possible that you used incorrect syntax or you -used an option from a newer version of Podman Quadlet and the -generator failed to create a service file. - -View the generated files and/or error messages with: -``` -/usr/lib/systemd/system-generators/podman-system-generator {--user} --dryrun -``` - -Alternatively, show only the errors with: -``` -systemd-analyze {--user} --generators=true verify example.service -``` - -That command also performs additional checks on the generated service unit. -For details, see systemd-analyze(1) man page. - -#### Debugging a limited set of unit files - -If you would like to debug a limited set of unit files, you can copy them to a separate directory and set the -`QUADLET_UNIT_DIRS` environment variable to this directory when running the command below: - -``` -QUADLET_UNIT_DIRS= /usr/lib/systemd/system-generators/podman-system-generator {--user} --dryrun -``` - -This will instruct Quadlet to look for units in this directory instead of the common ones and by -that limit the output to only the units you are debugging. - -### Implicit network dependencies - -Quadlet will add dependencies on `network-online.target` (as root) or `podman-user-wait-network-online.service` -(as user) by adding `After=` and `Wants=` properties to the unit. This is to ensure that the network is reachable -if an image needs to be pulled and by the time the container is started. - -The special case `podman-user-wait-network-online.service` unit is needed as user because user units are unable to wait -for system (root) units so `network-online.target` doesn't do anything there and is instead ignored. As this caused -a significant amount of issues we decided to work around this with our own special purpose unit that simply checks if -the `network-online.target` unit is active with `systemctl is-active network-online.target`. - -This behavior can be disabled by adding `DefaultDependencies=false` in the `Quadlet` section. -Note, the _systemd_ `[Unit]` section has an option with the same name but a different meaning. - -### Dependency between Quadlet units - -Quadlet will automatically translate dependencies, specified in the keys -`Wants`, `Requires`, `Requisite`, `BindsTo`, `PartOf`, `Upholds`, `Conflicts`, `Before` and `After` -of the `[Unit]` section, between different Quadlet units. - -For example the `fedora.container` unit below specifies a dependency on the `basic.container` unit. -``` -[Unit] -After=basic.container -Requires=basic.container - -[Container] -Image=registry.fedoraproject.org/fedora:41 -``` - -### Setting resource names - -Quadlet units allow setting the names of the created resources -(e.g. `VolumeName` for `.volume` units or `PodName` for `.pod` units). - -Note that using systemd specifiers that reference the generated service unit (e.g. `$N`) -breaks Quadlet's ability to link between resources as they are translated differently in each service - -## Container units [Container] - -Container units are named with a `.container` extension and contain a `[Container]` section describing -the container that is run as a service. The resulting service file contains a line like -`ExecStart=podman run … image-name`, and most of the keys in this section control the command-line -options passed to Podman. However, some options also affect the details of how systemd is set up to run and -interact with the container. - -By default, the Podman container has the same name as the unit, but with a `systemd-` prefix, i.e. -a `$name.container` file creates a `$name.service` unit and a `systemd-$name` Podman container. The -`ContainerName` option allows for overriding this default name with a user-provided one. - -There is only one required key, `Image`, which defines the container image the service runs. - -Valid options for `[Container]` are listed below: - -| **[Container] options** | **podman run equivalent** | -|--------------------------------------|------------------------------------------------------| -| AddCapability=CAP | --cap-add CAP | -| AddDevice=/dev/foo | --device /dev/foo | -| AddHost=example\.com:192.168.10.11 | --add-host example.com:192.168.10.11 | -| Annotation="XYZ" | --annotation "XYZ" | -| AutoUpdate=registry | --label "io.containers.autoupdate=registry" | -| CgroupsMode=no-conmon | --cgroups=no-conmon | -| ContainerName=name | --name name | -| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | -| DNS=192.168.55.1 | --dns=192.168.55.1 | -| DNSOption=ndots:1 | --dns-option=ndots:1 | -| DNSSearch=example.com | --dns-search example.com | -| DropCapability=CAP | --cap-drop=CAP | -| Entrypoint=/foo.sh | --entrypoint=/foo.sh | -| Environment=foo=bar | --env foo=bar | -| EnvironmentFile=/tmp/env | --env-file /tmp/env | -| EnvironmentHost=true | --env-host | -| Exec=/usr/bin/command | Command after image specification - /usr/bin/command | -| ExposeHostPort=50-59 | --expose 50-59 | -| GIDMap=0:10000:10 | --gidmap=0:10000:10 | -| GlobalArgs=--log-level=debug | --log-level=debug | -| Group=1234 | --user UID:1234 | -| GroupAdd=keep-groups | --group-add=keep-groups | -| HealthCmd=/usr/bin/command | --health-cmd=/usr/bin/command | -| HealthInterval=2m | --health-interval=2m | -| HealthLogDestination=/foo/log | --health-log-destination=/foo/log | -| HealthMaxLogCount=5 | --health-max-log-count=5 | -| HealthMaxLogSize=500 | --health-max-log-size=500 | -| HealthOnFailure=kill | --health-on-failure=kill | -| HealthRetries=5 | --health-retries=5 | -| HealthStartPeriod=1m | --health-start-period=period=1m | -| HealthStartupCmd=command | --health-startup-cmd=command | -| HealthStartupInterval=1m | --health-startup-interval=1m | -| HealthStartupRetries=8 | --health-startup-retries=8 | -| HealthStartupSuccess=2 | --health-startup-success=2 | -| HealthStartupTimeout=1m33s | --health-startup-timeout=1m33s | -| HealthTimeout=20s | --health-timeout=20s | -| HostName=example.com | --hostname example.com | -| HttpProxy=true | --http-proxy=true | -| Image=ubi8 | Image specification - ubi8 | -| IP=192.5.0.1 | --ip 192.5.0.1 | -| IP6=2001:db8::1 | --ip6 2001:db8::1 | -| Label="XYZ" | --label "XYZ" | -| LogDriver=journald | --log-driver journald | -| LogOpt=path=/var/log/mykube\.json | --log-opt path=/var/log/mykube\.json | -| Mask=/proc/sys/foo\:/proc/sys/bar | --security-opt mask=/proc/sys/foo:/proc/sys/bar | -| Memory=20g | --memory 20g | -| Mount=type=... | --mount type=... | -| Network=host | --network host | -| NetworkAlias=name | --network-alias name | -| NoNewPrivileges=true | --security-opt no-new-privileges | -| Notify=true | --sdnotify container | -| PidsLimit=10000 | --pids-limit 10000 | -| Pod=pod-name | --pod=pod-name | -| PodmanArgs=--publish 8080:80 | --publish 8080:80 | -| PublishPort=8080:80 | --publish 8080:80 | -| Pull=never | --pull never | -| ReadOnly=true | --read-only | -| ReadOnlyTmpfs=true | --read-only-tmpfs | -| ReloadCmd=/usr/bin/command | Add ExecReload and run exec with the value | -| ReloadSignal=SIGHUP | Add ExecReload and run kill with the signal | -| Retry=5 | --retry=5 | -| RetryDelay=5s | --retry-delay=5s | -| Rootfs=/var/lib/rootfs | --rootfs /var/lib/rootfs | -| RunInit=true | --init | -| SeccompProfile=/tmp/s.json | --security-opt seccomp=/tmp/s.json | -| Secret=secret | --secret=secret[,opt=opt ...] | -| SecurityLabelDisable=true | --security-opt label=disable | -| SecurityLabelFileType=usr_t | --security-opt label=filetype:usr_t | -| SecurityLabelLevel=s0:c1,c2 | --security-opt label=level:s0:c1,c2 | -| SecurityLabelNested=true | --security-opt label=nested | -| SecurityLabelType=spc_t | --security-opt label=type:spc_t | -| ShmSize=100m | --shm-size=100m | -| StartWithPod=true | If Pod= is defined, container is started by pod | -| StopSignal=SIGINT | --stop-signal=SIGINT | -| StopTimeout=20 | --stop-timeout=20 | -| SubGIDMap=gtest | --subgidname=gtest | -| SubUIDMap=utest | --subuidname=utest | -| Sysctl=name=value | --sysctl=name=value | -| Timezone=local | --tz local | -| Tmpfs=/work | --tmpfs /work | -| UIDMap=0:10000:10 | --uidmap=0:10000:10 | -| Ulimit=nofile=1000:10000 | --ulimit nofile=1000:10000 | -| Unmask=ALL | --security-opt unmask=ALL | -| User=bin | --user bin | -| UserNS=keep-id:uid=200,gid=210 | --userns keep-id:uid=200,gid=210 | -| Volume=/source:/dest | --volume /source:/dest | -| WorkingDir=$HOME | --workdir $HOME | - -Description of `[Container]` section are: - -### `AddCapability=` - -Add these capabilities, in addition to the default Podman capability set, to the container. - -This is a space separated list of capabilities. This key can be listed multiple times. - -For example: -``` -AddCapability=CAP_DAC_OVERRIDE CAP_IPC_OWNER -``` - -### `AddDevice=` - -Adds a device node from the host into the container. The format of this is -`HOST-DEVICE[:CONTAINER-DEVICE][:PERMISSIONS]`, where `HOST-DEVICE` is the path of -the device node on the host, `CONTAINER-DEVICE` is the path of the device node in -the container, and `PERMISSIONS` is a list of permissions combining 'r' for read, -'w' for write, and 'm' for mknod(2). The `-` prefix tells Quadlet to add the device -only if it exists on the host. - -This key can be listed multiple times. - -### `AddHost=` - -Add host-to-IP mapping to /etc/hosts. -The format is `hostname:ip`. - -Equivalent to the Podman `--add-host` option. -This key can be listed multiple times. - -### `Annotation=` - -Set one or more OCI annotations on the container. The format is a list of `key=value` items, -similar to `Environment`. - -This key can be listed multiple times. - -### `AutoUpdate=` - -Indicates whether the container will be auto-updated ([podman-auto-update(1)](podman-auto-update.1.md)). The following values are supported: - -* `registry`: Requires a fully-qualified image reference (e.g., quay.io/podman/stable:latest) to be used to create the container. This enforcement is necessary to know which image to actually check and pull. If an image ID was used, Podman does not know which image to check/pull anymore. - -* `local`: Tells Podman to compare the image a container is using to the image with its raw name in local storage. If an image is updated locally, Podman simply restarts the systemd unit executing the container. - -### `CgroupsMode=` - -The cgroups mode of the Podman container. Equivalent to the Podman `--cgroups` option. - -By default, the cgroups mode of the container created by Quadlet is `split`, -which differs from the default (`enabled`) used by the Podman CLI. - -If the container joins a pod (i.e. `Pod=` is specified), you may want to change this to -`no-conmon` or `enabled` so that pod level cgroup resource limits can take effect. - -### `ContainerName=` - -The (optional) name of the Podman container. If this is not specified, the default value -of `systemd-%N` is used, which is the same as the service name but with a `systemd-` -prefix to avoid conflicts with user-managed containers. - -### `ContainersConfModule=` - -Load the specified containers.conf(5) module. Equivalent to the Podman `--module` option. - -This key can be listed multiple times. - -### `DNS=` - -Set network-scoped DNS resolver/nameserver for containers in this network. - -This key can be listed multiple times. - -### `DNSOption=` - -Set custom DNS options. - -This key can be listed multiple times. - -### `DNSSearch=` - -Set custom DNS search domains. Use **DNSSearch=.** to remove the search domain. - -This key can be listed multiple times. - -### `DropCapability=` - -Drop these capabilities from the default podman capability set, or `all` to drop all capabilities. - -This is a space separated list of capabilities. This key can be listed multiple times. - -For example: -``` -DropCapability=CAP_DAC_OVERRIDE CAP_IPC_OWNER -``` - -### `Entrypoint=` - -Override the default ENTRYPOINT from the image. -Equivalent to the Podman `--entrypoint` option. -Specify multi option commands in the form of a JSON string. - -### `Environment=` - -Set an environment variable in the container. This uses the same format as -[services in systemd](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Environment=) -and can be listed multiple times. - -### `EnvironmentFile=` - -Use a line-delimited file to set environment variables in the container. -The path may be absolute or relative to the location of the unit file. -This key may be used multiple times, and the order persists when passed to `podman run`. - -### `EnvironmentHost=` - -Use the host environment inside of the container. - -### `Exec=` - -Additional arguments for the container; this has exactly the same effect as passing -more arguments after a `podman run ` invocation. - -The format is the same as for [systemd command lines](https://www.freedesktop.org/software/systemd/man/systemd.service.html#Command%20lines), -However, unlike the usage scenario for similarly-named systemd `ExecStart=` verb -which operates on the ambient root filesystem, it is very common for container -images to have their own `ENTRYPOINT` or `CMD` metadata which this interacts with. - -The default expectation for many images is that the image will include an `ENTRYPOINT` -with a default binary, and this field will add arguments to that entrypoint. - -Another way to describe this is that it works the same way as the [args field in a Kubernetes pod](https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell). - -### `ExposeHostPort=` - -Exposes a port, or a range of ports (e.g. `50-59`), from the host to the container. Equivalent -to the Podman `--expose` option. - -This key can be listed multiple times. - -### `GIDMap=` - -Run the container in a new user namespace using the supplied GID mapping. -Equivalent to the Podman `--gidmap` option. - -This key can be listed multiple times. - -### `GlobalArgs=` - -This key contains a list of arguments passed directly between `podman` and `run` -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. - -### `Group=` - -The (numeric) GID to run as inside the container. This does not need to match the GID on the host, -which can be modified with `UserNS`, but if that is not specified, this GID is also used on the host. - -Note: when both `User=` and `Group=` are specified, they are combined into a single `--user USER:GROUP` -argument passed to Podman. Using `Group=` without `User=` will result in an error. - -### `GroupAdd=` - -Assign additional groups to the primary user running within the container process. Also supports the `keep-groups` special flag. -Equivalent to the Podman `--group-add` option. - -### `HealthCmd=` - -Set or alter a healthcheck command for a container. A value of none disables existing healthchecks. -Equivalent to the Podman `--health-cmd` option. - -### `HealthInterval=` - -Set an interval for the healthchecks. An interval of disable results in no automatic timer setup. -Equivalent to the Podman `--health-interval` option. - -### `HealthLogDestination=` - -Set the destination of the HealthCheck log. Directory path, local or events_logger (local use container state file) -(Default: local) -Equivalent to the Podman `--health-log-destination` option. - -* `local`: (default) HealthCheck logs are stored in overlay containers. (For example: `$runroot/healthcheck.log`) -* `directory`: creates a log file named `-healthcheck.log` with HealthCheck logs in the specified directory. -* `events_logger`: The log will be written with logging mechanism set by events_logger. It also saves the log to a default directory, for performance on a system with a large number of logs. - -### `HealthMaxLogCount=` - -Set maximum number of attempts in the HealthCheck log file. ('0' value means an infinite number of attempts in the log file) -(Default: 5 attempts) -Equivalent to the Podman `--Health-max-log-count` option. - -### `HealthMaxLogSize=` - -Set maximum length in characters of stored HealthCheck log. ("0" value means an infinite log length) -(Default: 500 characters) -Equivalent to the Podman `--Health-max-log-size` option. - -### `HealthOnFailure=` - -Action to take once the container transitions to an unhealthy state. -The "kill" action in combination integrates best with systemd. Once -the container turns unhealthy, it gets killed, and systemd restarts the -service. -Equivalent to the Podman `--health-on-failure` option. - -### `HealthRetries=` - -The number of retries allowed before a healthcheck is considered to be unhealthy. -Equivalent to the Podman `--health-retries` option. - -### `HealthStartPeriod=` - -The initialization time needed for a container to bootstrap. -Equivalent to the Podman `--health-start-period` option. - -### `HealthStartupCmd=` - -Set a startup healthcheck command for a container. -Equivalent to the Podman `--health-startup-cmd` option. - -### `HealthStartupInterval=` - -Set an interval for the startup healthcheck. An interval of disable results in no automatic timer setup. -Equivalent to the Podman `--health-startup-interval` option. - -### `HealthStartupRetries=` - -The number of attempts allowed before the startup healthcheck restarts the container. -Equivalent to the Podman `--health-startup-retries` option. - -### `HealthStartupSuccess=` - -The number of successful runs required before the startup healthcheck succeeds and the regular healthcheck begins. -Equivalent to the Podman `--health-startup-success` option. - -### `HealthStartupTimeout=` - -The maximum time a startup healthcheck command has to complete before it is marked as failed. -Equivalent to the Podman `--health-startup-timeout` option. - -### `HealthTimeout=` - -The maximum time allowed to complete the healthcheck before an interval is considered failed. -Equivalent to the Podman `--health-timeout` option. - -### `HostName=` - -Sets the host name that is available inside the container. -Equivalent to the Podman `--hostname` option. - -### `HttpProxy=` - -Controls whether proxy environment variables (http_proxy, https_proxy, ftp_proxy, no_proxy) are passed from the Podman process into the container during image pulls and builds. - -Set to `true` to enable proxy inheritance (default Podman behavior) or `false` to disable it. -This option is particularly useful on systems that require proxy configuration for internet access but don't want proxy settings passed to the container runtime. - -Equivalent to the Podman `--http-proxy` option. - -### `Image=` - -The image to run in the container. -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`. So, it supports using -`:tag` or digests to guarantee the specific image version. - -Special Cases: - -* If the `name` of the image ends with `.image`, Quadlet will use the image pulled by the corresponding `.image` file, and the generated systemd service contains a dependency on the `$name-image.service` (or the service name set in the .image file). Note that the corresponding `.image` file must exist. -* If the `name` of the image ends with `.build`, Quadlet will use the image built by the corresponding `.build` file, and the generated systemd service contains a dependency on the `$name-build.service`. Note: the corresponding `.build` file must exist. - -### `IP=` - -Specify a static IPv4 address for the container, for example **10.88.64.128**. -Equivalent to the Podman `--ip` option. - -### `IP6=` - -Specify a static IPv6 address for the container, for example **fd46:db93:aa76:ac37::10**. -Equivalent to the Podman `--ip6` option. - -### `Label=` - -Set one or more OCI labels on the container. The format is a list of `key=value` items, -similar to `Environment`. - -This key can be listed multiple times. - -### `LogDriver=` - -Set the log-driver used by Podman when running the container. -Equivalent to the Podman `--log-driver` option. - -### `LogOpt=` - -Set the log-opt (logging options) used by Podman when running the container. -Equivalent to the Podman `--log-opt` option. -This key can be listed multiple times. - -### `Mask=` - -Specify the paths to mask separated by a colon. `Mask=/path/1:/path/2`. A masked path cannot be accessed inside the container. - -### `Memory=` - -Specify the amount of memory for the container. - -### `Mount=` - -Attach a filesystem mount to the container. -This is equivalent to the Podman `--mount` option, and -generally has the form `type=TYPE,TYPE-SPECIFIC-OPTION[,...]`. - -Special cases: - -* For `type=volume`, if `source` ends with `.volume`, the Podman named volume generated by the corresponding `.volume` file is used. -* For `type=image`, if `source` ends with `.image`, the image generated by the corresponding `.image` file is used. - -In both cases, the generated systemd service will contain a dependency on the service generated for the corresponding unit. Note: the corresponding `.volume` or `.image` file must exist. - -This key can be listed multiple times. - -### `Network=` - -Specify a custom network for the container. This has the same format as the `--network` option -to `podman run`. For example, use `host` to use the host network in the container, or `none` to -not set up networking in the container. - -Special cases: - -* If the `name` of the network ends with `.network`, a Podman network called -`systemd-$name` is used, and the generated systemd service contains -a dependency on the `$name-network.service`. Such a network can be automatically -created by using a `$name.network` Quadlet file. Note: the corresponding `.network` file must exist. - -* If the `name` ends with `.container`, -the container will reuse the network stack of another container created by `$name.container`. -The generated systemd service contains a dependency on `$name.service`. Note: the corresponding `.container` file must exist. - -This key can be listed multiple times. - -### `NetworkAlias=` - -Add a network-scoped alias for the container. This has the same format as the `--network-alias` -option to `podman run`. Aliases can be used to group containers together in DNS resolution: for -example, setting `NetworkAlias=web` on multiple containers will make a DNS query for `web` resolve -to all the containers with that alias. - -This key can be listed multiple times. - -### `NoNewPrivileges=` (defaults to `false`) - -If enabled, this disables the container processes from gaining additional privileges via things like -setuid and file capabilities. - -### `Notify=` (defaults to `false`) - -By default, Podman is run in such a way that the systemd startup notify command is handled by -the container runtime. In other words, the service is deemed started when the container runtime -starts the child in the container. However, if the container application supports -[sd_notify](https://www.freedesktop.org/software/systemd/man/sd_notify.html), then setting -`Notify` to true passes the notification details to the container allowing it to notify -of startup on its own. - -In addition, setting `Notify` to `healthy` will postpone startup notifications until such time as -the container is marked healthy, as determined by Podman healthchecks. Note that this requires -setting up a container healthcheck, see the `HealthCmd` option for more. - -### `PidsLimit=` - -Tune the container's pids limit. -This is equivalent to the Podman `--pids-limit` option. - -### `Pod=` - -Specify a Quadlet `.pod` unit to link the container to. -The value must take the form of `.pod` and the `.pod` unit must exist. - -Quadlet will add all the necessary parameters to link between the container and the pod and between their corresponding services. - - -### `PodmanArgs=` - -This key contains a list of arguments passed directly to the end of the `podman run` command -in the generated file (right before the image name in the command line). 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. - -### `PublishPort=` - -Exposes a port, or a range of ports (e.g. `50-59`), from the container to the host. Equivalent -to the Podman `--publish` option. The format is similar to the Podman options, which is of -the form `ip:hostPort:containerPort`, `ip::containerPort`, `hostPort:containerPort` or -`containerPort`, where the number of host and container ports must be the same (in the case -of a range). - -If the IP is set to 0.0.0.0 or not set at all, the port is bound on all IPv4 addresses on -the host; use [::] for IPv6. - -Note that not listing a host port means that Podman automatically selects one, and it -may be different for each invocation of service. This makes that a less useful option. The -allocated port can be found with the `podman port` command. - -This key can be listed multiple times. - -### `Pull=` - -Set the image pull policy. -This is equivalent to the Podman `--pull` option - -### `ReadOnly=` (defaults to `false`) - -If enabled, makes the image read-only. - -### `ReadOnlyTmpfs=` (defaults to `true`) - -If ReadOnly is set to `true`, mount a read-write tmpfs on /dev, /dev/shm, /run, /tmp, and /var/tmp. - -### `ReloadCmd=` - -Add `ExecReload` line to the `Service` that runs ` podman exec` with this command in this container. - -In order to execute the reload run `systemctl reload ` - -Mutually exclusive with `ReloadSignal` - -### `ReloadSignal=` - -Add `ExecReload` line to the `Service` that runs `podman kill` with this signal which sends the signal to the main container process. - -In order to execute the reload run `systemctl reload ` - -Mutually exclusive with `ReloadCmd` - -### `Retry=` - -Number of times to retry the image pull when a HTTP error occurs. Equivalent to the Podman `--retry` option. - -### `RetryDelay=` - -Delay between retries. Equivalent to the Podman `--retry-delay` option. - -### `Rootfs=` - -The rootfs to use for the container. Rootfs points to a directory on the system that contains the content to be run within the container. This option conflicts with the `Image` option. - -The format of the rootfs is the same as when passed to `podman run --rootfs`, so it supports overlay mounts as well. - -Note: On SELinux systems, the rootfs needs the correct label, which is by default unconfined_u:object_r:container_file_t:s0. - -### `RunInit=` (defaults to `false`) - -If enabled, the container has a minimal init process inside the -container that forwards signals and reaps processes. - -### `SeccompProfile=` - -Set the seccomp profile to use in the container. If unset, the default podman profile is used. -Set to either the pathname of a JSON file, or `unconfined` to disable the seccomp filters. - -### `Secret=` - -Use a Podman secret in the container either as a file or an environment variable. -This is equivalent to the Podman `--secret` option and generally has the form `secret[,opt=opt ...]` - -### `SecurityLabelDisable=` - -Turn off label separation for the container. - -### `SecurityLabelFileType=` - -Set the label file type for the container files. - -### `SecurityLabelLevel=` - -Set the label process level for the container processes. - -### `SecurityLabelNested=` - -Allow SecurityLabels to function within the container. This allows separation of containers created within the container. - -### `SecurityLabelType=` - -Set the label process type for the container processes. - -### `ShmSize=` - -Size of /dev/shm. - -This is equivalent to the Podman `--shm-size` option and generally has the form `number[unit]` - -### `StartWithPod=` - -Start the container after the associated pod is created. Default to **true**. - -If `true`, container will be started/stopped/restarted alongside the pod. - -If `false`, the container will not be started when the pod starts. The container will be stopped with the pod. Restarting the pod will also restart the container as long as the container was also running before. - -Note, the container can still be started manually or through a target by configuring the `[Install]` section. The pod will be started as needed in any case. - -### `StopSignal=` - -Signal to stop a container. Default is **SIGTERM**. - -This is equivalent to the Podman `--stop-signal` option - -### `StopTimeout=` - -Seconds to wait before forcibly stopping the container. - -Note, this value should be lower than the actual systemd unit timeout to make sure the podman rm command is not killed by systemd. - -This is equivalent to the Podman `--stop-timeout` option - -### `SubGIDMap=` - -Run the container in a new user namespace using the map with name in the /etc/subgid file. -Equivalent to the Podman `--subgidname` option. - -### `SubUIDMap=` - -Run the container in a new user namespace using the map with name in the /etc/subuid file. -Equivalent to the Podman `--subuidname` option. - -### `Sysctl=` - -Configures namespaced kernel parameters for the container. The format is `Sysctl=name=value`. - -This is a space separated list of kernel parameters. This key can be listed multiple times. - -For example: -``` -Sysctl=net.ipv6.conf.all.disable_ipv6=1 net.ipv6.conf.all.use_tempaddr=1 -``` - -### `Timezone=` (if unset uses system-configured default) - -The timezone to run the container in. - -### `Tmpfs=` - -Mount a tmpfs in the container. This is equivalent to the Podman `--tmpfs` option, and -generally has the form `CONTAINER-DIR[:OPTIONS]`. - -This key can be listed multiple times. - -### `UIDMap=` - -Run the container in a new user namespace using the supplied UID mapping. -Equivalent to the Podman `--uidmap` option. - -This key can be listed multiple times. - -### `Ulimit=` - -Ulimit options. Sets the ulimits values inside of the container. - -This key can be listed multiple times. - -### `Unmask=` - -Specify the paths to unmask separated by a colon. unmask=ALL or /path/1:/path/2, or shell expanded paths (/proc/*): - -If set to `ALL`, Podman will unmask all the paths that are masked or made read-only by default. - -The default masked paths are /proc/acpi, /proc/kcore, /proc/keys, /proc/latency_stats, /proc/sched_debug, /proc/scsi, /proc/timer_list, /proc/timer_stats, /sys/firmware, and /sys/fs/selinux. - -The default paths that are read-only are /proc/asound, /proc/bus, /proc/fs, /proc/irq, /proc/sys, /proc/sysrq-trigger, /sys/fs/cgroup. - -### `User=` - -The (numeric) UID to run as inside the container. This does not need to match the UID on the host, -which can be modified with `UserNS`, but if that is not specified, this UID is also used on the host. - -Note: when both `User=` and `Group=` are specified, they are combined into a single `--user USER:GROUP` -argument passed to Podman. - -### `UserNS=` - -Set the user namespace mode for the container. This is equivalent to the Podman `--userns` option and -generally has the form `MODE[:OPTIONS,...]`. - -### `Volume=` - -Mount a volume in the container. This is equivalent to the Podman `--volume` option, and -generally has the form `[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]`. - -If `SOURCE-VOLUME` starts with `.`, Quadlet resolves the path relative to the location of the unit file. - -Special case: - -* If `SOURCE-VOLUME` ends with `.volume`, a Podman named volume called `systemd-$name` is used as the source, and the generated systemd service contains a dependency on the `$name-volume.service`. Note that the corresponding `.volume` file must exist. - -This key can be listed multiple times. - -### `WorkingDir=` - -Working directory inside the container. - -The default working directory for running binaries within a container is the root directory (/). The image developer can set a different default with the WORKDIR instruction. This option overrides the working directory by using the -w option. - -## Pod units [Pod] - -Pod units are named with a `.pod` extension and contain a `[Pod]` section describing -the pod that is created and run as a service. The resulting service file contains a line like -`ExecStartPre=podman pod create …`, and most of the keys in this section control the command-line -options passed to Podman. - -By default, the Podman pod has the same name as the unit, but with a `systemd-` prefix, i.e. -a `$name.pod` file creates a `$name-pod.service` unit and a `systemd-$name` Podman pod. The -`PodName` option allows for overriding this default name with a user-provided one. - -Valid options for `[Pod]` are listed below: - -| **[Pod] options** | **podman pod create equivalent** | -|-------------------------------------|----------------------------------------| -| AddHost=example\.com:192.168.10.11 | --add-host example.com:192.168.10.11 | -| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | -| DNS=192.168.55.1 | --dns=192.168.55.1 | -| DNSOption=ndots:1 | --dns-option=ndots:1 | -| DNSSearch=example.com | --dns-search example.com | -| ExitPolicy=stop | --exit-policy stop | -| GIDMap=0:10000:10 | --gidmap=0:10000:10 | -| GlobalArgs=--log-level=debug | --log-level=debug | -| HostName=name | --hostname=name | -| IP=192.5.0.1 | --ip 192.5.0.1 | -| IP6=2001:db8::1 | --ip6 2001:db8::1 | -| Label="XYZ" | --label "XYZ" | -| Network=host | --network host | -| NetworkAlias=name | --network-alias name | -| PodmanArgs=\-\-cpus=2 | --cpus=2 | -| PodName=name | --name=name | -| PublishPort=8080:80 | --publish 8080:80 | -| ServiceName=name | Name the systemd unit `name.service` | -| ShmSize=100m | --shm-size=100m | -| SubGIDMap=gtest | --subgidname=gtest | -| SubUIDMap=utest | --subuidname=utest | -| UIDMap=0:10000:10 | --uidmap=0:10000:10 | -| UserNS=keep-id:uid=200,gid=210 | --userns keep-id:uid=200,gid=210 | -| Volume=/source:/dest | --volume /source:/dest | - -Supported keys in the `[Pod]` section are: - -### `AddHost=` - -Add host-to-IP mapping to /etc/hosts. -The format is `hostname:ip`. - -Equivalent to the Podman `--add-host` option. -This key can be listed multiple times. - -### `ContainersConfModule=` - -Load the specified containers.conf(5) module. Equivalent to the Podman `--module` option. - -This key can be listed multiple times. - -### `DNS=` - -Set network-scoped DNS resolver/nameserver for containers in this pod. - -This key can be listed multiple times. - -### `DNSOption=` - -Set custom DNS options. - -This key can be listed multiple times. - -### `DNSSearch=` - -Set custom DNS search domains. Use **DNSSearch=.** to remove the search domain. - -This key can be listed multiple times. - -### `ExitPolicy=` - -Set the exit policy of the pod when the last container exits. Default for quadlets is **stop**. - -To keep the pod active, set `ExitPolicy=continue`. - -### `GIDMap=` - -Create the pod in a new user namespace using the supplied GID mapping. -Equivalent to the Podman `--gidmap` option. - -This key can be listed multiple times. - -### `GlobalArgs=` - -This key contains a list of arguments passed directly between `podman` and `pod` -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. - -### `HostName=` - -Set the pod’s hostname inside all containers. - -The given hostname is also added to the /etc/hosts file using the container’s primary IP address (also see the `--add-host` option). - -Equivalent to the Podman `--hostname` option. -This key can be listed multiple times. - -### `IP=` - -Specify a static IPv4 address for the pod, for example **10.88.64.128**. -Equivalent to the Podman `--ip` option. - -### `IP6=` - -Specify a static IPv6 address for the pod, for example **fd46:db93:aa76:ac37::10**. -Equivalent to the Podman `--ip6` option. - -### `Label=` - -Set one or more OCI labels on the pod. The format is a list of -`key=value` items, similar to `Environment`. - -This key can be listed multiple times. - -### `Network=` - -Specify a custom network for the pod. -This has the same format as the `--network` option to `podman pod create`. -For example, use `host` to use the host network in the pod, or `none` to not set up networking in the pod. - -Special case: - -* If the `name` of the network ends with `.network`, Quadlet will look for the corresponding `.network` Quadlet unit. If found, Quadlet will use the name of the Network set in the Unit, otherwise, `systemd-$name` is used. - -The generated systemd service contains a dependency on the service unit generated for that `.network` unit. Note: the corresponding `.network` file must exist. - -This key can be listed multiple times. - -### `NetworkAlias=` - -Add a network-scoped alias for the pod. This has the same format as the `--network-alias` option to -`podman pod create`. Aliases can be used to group containers together in DNS resolution: for -example, setting `NetworkAlias=web` on multiple containers will make a DNS query for `web` resolve -to all the containers with that alias. - -This key can be listed multiple times. - -### `PodmanArgs=` - -This key contains a list of arguments passed directly to the end of the `podman pod create` 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, 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. - -### `PodName=` - -The (optional) name of the Podman pod. -If this is not specified, the default value is the same name as the unit, but with a `systemd-` prefix, -i.e. a `$name.pod` file creates a `systemd-$name` Podman pod to avoid conflicts with user-managed pods. - -Please note that pods and containers cannot have the same name. -So, if PodName is set, it must not conflict with any container. - -### `PublishPort=` - -Exposes a port, or a range of ports (e.g. `50-59`), from the pod to the host. Equivalent -to the Podman `--publish` option. The format is similar to the Podman options, which is of -the form `ip:hostPort:containerPort`, `ip::containerPort`, `hostPort:containerPort` or -`containerPort`, where the number of host and container ports must be the same (in the case -of a range). - -If the IP is set to 0.0.0.0 or not set at all, the port is bound on all IPv4 addresses on -the host; use [::] for IPv6. - -Note that not listing a host port means that Podman automatically selects one, and it -may be different for each invocation of service. This makes that a less useful option. The -allocated port can be found with the `podman port` command. - -When using `host` networking via `Network=host`, the `PublishPort=` option cannot be used. - -This key can be listed multiple times. - - -### `ServiceName=` - -By default, Quadlet will name the systemd service unit by appending `-pod` to the name of the Quadlet. -Setting this key overrides this behavior by instructing Quadlet to use the provided name. - -Note, the name should not include the `.service` file extension - -### `ShmSize=` - -Size of /dev/shm. - -This is equivalent to the Podman `--shm-size` option and generally has the form `number[unit]` - -### `SubGIDMap=` - -Create the pod in a new user namespace using the map with name in the /etc/subgid file. -Equivalent to the Podman `--subgidname` option. - -### `SubUIDMap=` - -Create the pod in a new user namespace using the map with name in the /etc/subuid file. -Equivalent to the Podman `--subuidname` option. - -### `UIDMap=` - -Create the pod in a new user namespace using the supplied UID mapping. -Equivalent to the Podman `--uidmap` option. - -This key can be listed multiple times. - -### `UserNS=` - -Set the user namespace mode for the pod. This is equivalent to the Podman `--userns` option and -generally has the form `MODE[:OPTIONS,...]`. - -### `Volume=` - -Mount a volume in the pod. This is equivalent to the Podman `--volume` option, and -generally has the form `[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]`. - -If `SOURCE-VOLUME` starts with `.`, Quadlet resolves the path relative to the location of the unit file. - -Special case: - -* If `SOURCE-VOLUME` ends with `.volume`, Quadlet will look for the corresponding `.volume` Quadlet unit. If found, Quadlet will use the name of the Volume set in the Unit, otherwise, `systemd-$name` is used. Note: the corresponding `.volume` file must exist. - -The generated systemd service contains a dependency on the service unit generated for that `.volume` unit, -or on `$name-volume.service` if the `.volume` unit is not found. - -This key can be listed multiple times. - -## Kube units [Kube] - -Kube units are named with a `.kube` extension and contain a `[Kube]` section describing -how `podman kube play` runs as a service. The resulting service file contains a line like -`ExecStart=podman kube play … file.yml`, and most of the keys in this section control the command-line -options passed to Podman. However, some options also affect the details of how systemd is set up to run and -interact with the container. - -There is only one required key, `Yaml`, which defines the path to the Kubernetes YAML file. - -Valid options for `[Kube]` are listed below: - -| **[Kube] options** | **podman kube play equivalent** | -| ------------------------------------| -----------------------------------------------------------------| -| AutoUpdate=registry | --annotation "io.containers.autoupdate=registry" | -| ConfigMap=/tmp/config.map | --config-map /tmp/config.map | -| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | -| ExitCodePropagation=how | How to propagate container error status | -| GlobalArgs=--log-level=debug | --log-level=debug | -| KubeDownForce=true | --force (for `podman kube down`) | -| LogDriver=journald | --log-driver journald | -| Network=host | --network host | -| PodmanArgs=\-\-annotation=key=value | --annotation=key=value | -| PublishPort=8080:80 | --publish 8080:80 | -| SetWorkingDirectory=yaml | Set `WorkingDirectory` of unit file to location of the YAML file | -| UserNS=keep-id:uid=200,gid=210 | --userns keep-id:uid=200,gid=210 | -| Yaml=/tmp/kube.yaml | podman kube play /tmp/kube.yaml | - -Supported keys in the `[Kube]` section are: - -### `AutoUpdate=` - -Indicates whether containers will be auto-updated ([podman-auto-update(1)](podman-auto-update.1.md)). AutoUpdate can be specified multiple times. The following values are supported: - -* `registry`: Requires a fully-qualified image reference (e.g., quay.io/podman/stable:latest) to be used to create the container. This enforcement is necessary to know which images to actually check and pull. If an image ID was used, Podman does not know which image to check/pull anymore. - -* `local`: Tells Podman to compare the image a container is using to the image with its raw name in local storage. If an image is updated locally, Podman simply restarts the systemd unit executing the Kubernetes Quadlet. - -* `name/(local|registry)`: Tells Podman to perform the `local` or `registry` autoupdate on the specified container name. - -### `ConfigMap=` - -Pass the Kubernetes ConfigMap YAML path to `podman kube play` via the `--configmap` argument. -Unlike the `configmap` argument, the value may contain only one path but -it may be absolute or relative to the location of the unit file. - -This key may be used multiple times - -### `ContainersConfModule=` - -Load the specified containers.conf(5) module. Equivalent to the Podman `--module` option. - -This key can be listed multiple times. - -### `ExitCodePropagation=` - -Control how the main PID of the systemd service should exit. The following values are supported: -- `all`: exit non-zero if all containers have failed (i.e., exited non-zero) -- `any`: exit non-zero if any container has failed -- `none`: exit zero and ignore failed containers - -The current default value is `none`. - -### `GlobalArgs=` - -This key contains a list of arguments passed directly between `podman` and `kube` -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. - -### `KubeDownForce=` - -Remove all resources, including volumes, when calling `podman kube down`. -Equivalent to the Podman `--force` option. - -### `LogDriver=` - -Set the log-driver Podman uses when running the container. -Equivalent to the Podman `--log-driver` option. - -### `Network=` - -Specify a custom network for the container. This has the same format as the `--network` option -to `podman kube play`. For example, use `host` to use the host network in the container, or `none` to -not set up networking in the container. - -Special case: - -* If the `name` of the network ends with `.network`, a Podman network called `systemd-$name` is used, and the generated systemd service contains a dependency on the `$name-network.service`. Such a network can be automatically created by using a `$name.network` Quadlet file. Note: the corresponding `.network` file must exist. - -This key can be listed multiple times. - -### `PodmanArgs=` - -This key contains a list of arguments passed directly to the end of the `podman kube play` command -in the generated file (right before the path to the yaml file in the command line). 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, 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. - -### `PublishPort=` - -Exposes a port, or a range of ports (e.g. `50-59`), from the container to the host. Equivalent -to the `podman kube play`'s `--publish` option. The format is similar to the Podman options, which is of -the form `ip:hostPort:containerPort`, `ip::containerPort`, `hostPort:containerPort` or -`containerPort`, where the number of host and container ports must be the same (in the case -of a range). - -If the IP is set to 0.0.0.0 or not set at all, the port is bound on all IPv4 addresses on -the host; use [::] for IPv6. - -The list of published ports specified in the unit file is merged with the list of ports specified -in the Kubernetes YAML file. If the same container port and protocol is specified in both, the -entry from the unit file takes precedence - -This key can be listed multiple times. - -### `SetWorkingDirectory=` - -Set the `WorkingDirectory` field of the `Service` group of the Systemd service unit file. -Used to allow `podman kube play` to correctly resolve relative paths. -Supported values are `yaml` and `unit` to set the working directory to that of the YAML or Quadlet Unit file respectively. - -Alternatively, users can explicitly set the `WorkingDirectory` field of the `Service` group in the `.kube` file. -Please note that if the `WorkingDirectory` field of the `Service` group is set, -Quadlet will not set it even if `SetWorkingDirectory` is set - -### `UserNS=` - -Set the user namespace mode for the container. This is equivalent to the Podman `--userns` option and -generally has the form `MODE[:OPTIONS,...]`. - -### `Yaml=` - -The path, absolute or relative to the location of the unit file, to the Kubernetes YAML file to use. - -## Network units [Network] - -Network files are named with a `.network` extension and contain a section `[Network]` describing the -named Podman network. The generated service is a one-time command that ensures that the network -exists on the host, creating it if needed. - -By default, the Podman network has the same name as the unit, but with a `systemd-` prefix, i.e. for -a network file named `$NAME.network`, the generated Podman network is called `systemd-$NAME`, and -the generated service file is `$NAME-network.service`. The `NetworkName` option allows for -overriding this default name with a user-provided one. - -Please note that stopping the corresponding service will not remove the podman network. -In addition, updating an existing network is not supported. -In order to update the network parameters you will first need to manually remove the podman network and then restart the service. - -Using network units allows containers to depend on networks being automatically pre-created. This is -particularly interesting when using special options to control network creation, as Podman otherwise creates networks with the default options. - -Valid options for `[Network]` are listed below: - -| **[Network] options** | **podman network create equivalent** | -|-------------------------------------|-----------------------------------------------------------------| -| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | -| DisableDNS=true | --disable-dns | -| DNS=192.168.55.1 | --dns=192.168.55.1 | -| Driver=bridge | --driver bridge | -| Gateway=192.168.55.3 | --gateway 192.168.55.3 | -| GlobalArgs=--log-level=debug | --log-level=debug | -| InterfaceName=enp1 | --interface-name enp1 | -| Internal=true | --internal | -| IPAMDriver=dhcp | --ipam-driver dhcp | -| IPRange=192.168.55.128/25 | --ip-range 192.168.55.128/25 | -| IPv6=true | --ipv6 | -| Label="XYZ" | --label "XYZ" | -| NetworkDeleteOnStop=true | Add ExecStopPost to delete the network when the unit is stopped | -| NetworkName=foo | podman network create foo | -| Options=isolate=true | --opt isolate=true | -| PodmanArgs=--dns=192.168.55.1 | --dns=192.168.55.1 | -| Subnet=192.5.0.0/16 | --subnet 192.5.0.0/16 | - -Supported keys in `[Network]` section are: - -### `ContainersConfModule=` - -Load the specified containers.conf(5) module. Equivalent to the Podman `--module` option. - -This key can be listed multiple times. - -### `DisableDNS=` (defaults to `false`) - -If enabled, disables the DNS plugin for this network. - -This is equivalent to the Podman `--disable-dns` option - -### `DNS=` - -Set network-scoped DNS resolver/nameserver for containers in this network. - -This key can be listed multiple times. - -### `Driver=` (defaults to `bridge`) - -Driver to manage the network. Currently `bridge`, `macvlan` and `ipvlan` are supported. - -This is equivalent to the Podman `--driver` option - -### `Gateway=` - -Define a gateway for the subnet. If you want to provide a gateway address, you must also provide a subnet option. - -This is equivalent to the Podman `--gateway` option - -This key can be listed multiple times. - -### `GlobalArgs=` - -This key contains a list of arguments passed directly between `podman` and `network` -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. - -### `InterfaceName=` - -This option maps the *network_interface* option in the network config, see **podman network inspect**. -Depending on the driver, this can have different effects; for `bridge`, it uses the bridge interface name. -For `macvlan` and `ipvlan`, it is the parent device on the host. It is the same as `--opt parent=...`. - -This is equivalent to the Podman `--interface-name` option. - -### `Internal=` (defaults to `false`) - -Restrict external access of this network. - -This is equivalent to the Podman `--internal` option - -### `IPAMDriver=` - -Set the ipam driver (IP Address Management Driver) for the network. Currently `host-local`, `dhcp` and `none` are supported. - -This is equivalent to the Podman `--ipam-driver` option - -### `IPRange=` - -Allocate container IP from a range. The range must be a either a complete subnet in CIDR notation or be -in the `-` syntax which allows for a more flexible range compared to the CIDR subnet. -The ip-range option must be used with a subnet option. - -This is equivalent to the Podman `--ip-range` option - -This key can be listed multiple times. - -### `IPv6=` - -Enable IPv6 (Dual Stack) networking. - -This is equivalent to the Podman `--ipv6` option - -### `Label=` - -Set one or more OCI labels on the network. The format is a list of -`key=value` items, similar to `Environment`. - -This key can be listed multiple times. - -### `NetworkDeleteOnStop=` (defaults to `false`) - -When set to `true` the network is deleted when the service is stopped - -### `NetworkName=` - -The (optional) name of the Podman network. -If this is not specified, the default value is the same name as the unit, but with a `systemd-` prefix, -i.e. a `$name.network` file creates a `systemd-$name` Podman network to avoid -conflicts with user-managed network. - -### `Options=` - -Set driver specific options. - -This is equivalent to the Podman `--opt` option - -### `PodmanArgs=` - -This key contains a list of arguments passed directly to the end of the `podman network create` command -in the generated file (right before the name of the network in the command line). 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, 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. - -### `Subnet=` - -The subnet in CIDR notation. - -This is equivalent to the Podman `--subnet` option - -This key can be listed multiple times. - -## Volume units [Volume] - -Volume files are named with a `.volume` extension and contain a section `[Volume]` describing the -named Podman volume. The generated service is a one-time command that ensures that the volume -exists on the host, creating it if needed. - -By default, the Podman volume has the same name as the unit, but with a `systemd-` prefix, i.e. for -a volume file named `$NAME.volume`, the generated Podman volume is called `systemd-$NAME`, and the -generated service file is `$NAME-volume.service`. The `VolumeName` option allows for overriding this -default name with a user-provided one. - -Using volume units allows containers to depend on volumes being automatically pre-created. This is -particularly interesting when using special options to control volume creation, -as Podman otherwise creates volumes with the default options. - -Valid options for `[Volume]` are listed below: - -| **[Volume] options** | **podman volume create equivalent** | -|-------------------------------------|-------------------------------------------| -| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | -| Copy=true | --opt copy | -| Device=tmpfs | --opt device=tmpfs | -| Driver=image | --driver=image | -| GlobalArgs=--log-level=debug | --log-level=debug | -| Group=192 | --opt group=192 | -| Image=quay.io/centos/centos\:latest | --opt image=quay.io/centos/centos\:latest | -| Label="foo=bar" | --label "foo=bar" | -| Options=XYZ | --opt "o=XYZ" | -| PodmanArgs=--driver=image | --driver=image | -| Type=type | Filesystem type of Device | -| User=123 | --opt uid=123 | -| VolumeName=foo | podman volume create foo | - -Supported keys in `[Volume]` section are: - -### `ContainersConfModule=` - -Load the specified containers.conf(5) module. Equivalent to the Podman `--module` option. - -This key can be listed multiple times. - -### `Copy=` (default to `true`) - -If enabled, the content of the image located at the mountpoint of the volume is copied into the -volume on the first run. - -### `Device=` - -The path of a device which is mounted for the volume. - -### `Driver=` - -Specify the volume driver name. When set to `image`, the `Image` key must also be set. - -This is equivalent to the Podman `--driver` option. - -### `GlobalArgs=` - -This key contains a list of arguments passed directly between `podman` and `volume` -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. - -### `Group=` - -The host (numeric) GID, or group name to use as the group for the volume - -### `Image=` - -Specifies the image the volume is based on when `Driver` is set to the `image`. -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`. So, it supports using -`:tag` or digests to guarantee the specific image version. - -Special case: - -* If the `name` of the image ends with `.image`, Quadlet will use the image -pulled by the corresponding `.image` file, and the generated systemd service contains a dependency on the `$name-image.service` (or the service name set in the .image file). Note: the corresponding `.image` file must exist. - -### `Label=` - -Set one or more OCI labels on the volume. The format is a list of -`key=value` items, similar to `Environment`. - -This key can be listed multiple times. - -### `Options=` - -The mount options to use for a filesystem as used by the **mount(8)** command `-o` option. - -### `PodmanArgs=` - -This key contains a list of arguments passed directly to the end of the `podman volume create` command -in the generated file (right before the name of the volume in the command line). 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, 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. - -### `Type=` - -The filesystem type of `Device` as used by the **mount(8)** commands `-t` option. - -### `User=` - -The host (numeric) UID, or user name to use as the owner for the volume - -### `VolumeName=` - -The (optional) name of the Podman volume. -If this is not specified, the default value is the same name as the unit, but with a `systemd-` prefix, -i.e. a `$name.volume` file creates a `systemd-$name` Podman volume to avoid -conflicts with user-managed volumes. - -## Build units [Build] - -Build files are named with a `.build` extension and contain a section `[Build]` describing the image -build command. The generated service is a one-time command that ensures that the image is built on -the host from a supplied Containerfile and context directory. Subsequent (re-)starts of the -generated built service will usually finish quickly, as image layer caching will skip unchanged -build steps. - -A minimal `.build` unit needs at least the `ImageTag=` key, and either of `File=` or -`SetWorkingDirectory=` keys. - -Using build units allows containers and volumes to depend on images being built locally. This can be -interesting for creating container images not available on container registries, or for local -testing and development. - -Valid options for `[Build]` are listed below: - -| **[Build] options** | **podman build equivalent** | -|-------------------------------------|---------------------------------------------| -| Annotation=annotation=value | --annotation=annotation=value | -| Arch=aarch64 | --arch=aarch64 | -| AuthFile=/etc/registry/auth\.json | --authfile=/etc/registry/auth\.json | -| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | -| DNS=192.168.55.1 | --dns=192.168.55.1 | -| DNSOption=ndots:1 | --dns-option=ndots:1 | -| DNSSearch=example.com | --dns-search example.com | -| Environment=foo=bar | --env foo=bar | -| File=/path/to/Containerfile | --file=/path/to/Containerfile | -| ForceRM=false | --force-rm=false | -| GlobalArgs=--log-level=debug | --log-level=debug | -| GroupAdd=keep-groups | --group-add=keep-groups | -| ImageTag=localhost/imagename | --tag=localhost/imagename | -| Label=label | --label=label | -| Network=host | --network=host | -| PodmanArgs=--pull never | --pull never | -| Pull=never | --pull never | -| Retry=5 | --retry=5 | -| RetryDelay=10s | --retry-delay=10s | -| Secret=secret | --secret=id=mysecret,src=path | -| SetWorkingDirectory=unit | Set `WorkingDirectory` of systemd unit file | -| Target=my-app | --target=my-app | -| TLSVerify=false | --tls-verify=false | -| Variant=arm/v7 | --variant=arm/v7 | -| Volume=/source:/dest | --volume /source:/dest | - -### `Annotation=` - -Add an image *annotation* (e.g. annotation=*value*) to the image metadata. Can be used multiple -times. - -This is equivalent to the `--annotation` option of `podman build`. - -### `Arch=` - -Override the architecture, defaults to hosts', of the image to be built. - -This is equivalent to the `--arch` option of `podman build`. - -### `AuthFile=` - -Path of the authentication file. - -This is equivalent to the `--authfile` option of `podman build`. - -### `ContainersConfModule=` - -Load the specified containers.conf(5) module. Equivalent to the Podman `--module` option. - -This key can be listed multiple times. - -### `DNS=` - -Set network-scoped DNS resolver/nameserver for the build container. - -This key can be listed multiple times. - -This is equivalent to the `--dns` option of `podman build`. - -### `DNSOption=` - -Set custom DNS options. - -This key can be listed multiple times. - -This is equivalent to the `--dns-option` option of `podman build`. - -### `DNSSearch=` - -Set custom DNS search domains. Use **DNSSearch=.** to remove the search domain. - -This key can be listed multiple times. - -This is equivalent to the `--dns-search` option of `podman build`. - -### `Environment=` - -Add a value (e.g. env=*value*) to the built image. This uses the same format as [services in -systemd](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Environment=) and can be -listed multiple times. - -### `File=` - -Specifies a Containerfile which contains instructions for building the image. A URL starting with -`http(s)://` allows you to specify a remote Containerfile to be downloaded. Note that for a given -relative path to a Containerfile, or when using a `http(s)://` URL, you also must set -`SetWorkingDirectory=` in order for `podman build` to find a valid context directory for the -resources specified in the Containerfile. - -Note that setting a `File=` field is mandatory for a `.build` file, unless `SetWorkingDirectory` (or -a `WorkingDirectory` in the `Service` group) has also been set. - -This is equivalent to the `--file` option of `podman build`. - -### `ForceRM=` - -Always remove intermediate containers after a build, even if the build fails (default true). - -This is equivalent to the `--force-rm` option of `podman build`. - -### `GlobalArgs=` - -This key contains a list of arguments passed directly between `podman` and `build` 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. - -### `GroupAdd=` - -Assign additional groups to the primary user running within the container process. Also supports the -`keep-groups` special flag. - -This is equivalent to the `--group-add` option of `podman build`. - -### `ImageTag=` - -Specifies the name which is assigned to the resulting image if the build process completes -successfully. - -This is equivalent to the `--tag` option of `podman build`. - -This key can be listed multiple times. The first instance will be used as the name of the created artifact when the `.build` file is referenced by another Quadlet unit. - -### `Label=` - -Add an image *label* (e.g. label=*value*) to the image metadata. Can be used multiple times. - -This is equivalent to the `--label` option of `podman build`. - -### `Network=` - -Sets the configuration for network namespaces when handling RUN instructions. This has the same -format as the `--network` option to `podman build`. For example, use `host` to use the host network, -or `none` to not set up networking. - -Special case: - -* If the `name` of the network ends with `.network`, Quadlet will look for the corresponding `.network` Quadlet unit. If found, Quadlet will use the name of the Network set in the Unit, otherwise, `systemd-$name` is used. The generated systemd service contains a dependency on the service unit generated for that `.network` unit, or on `$name-network.service` if the `.network` unit is not found. Note: the corresponding `.network` file must exist. - -This key can be listed multiple times. - -### `PodmanArgs=` - -This key contains a list of arguments passed directly to the end of the `podman build` command -in the generated file (right before the image name in the command line). 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. - -### `Pull=` - -Set the image pull policy. - -This is equivalent to the `--pull` option of `podman build`. - -### `Retry=` - -Number of times to retry the image pull when a HTTP error occurs. Equivalent to the Podman `--retry` option. - -### `RetryDelay=` - -Delay between retries. Equivalent to the Podman `--retry-delay` option. - -### `Secret=` - -Pass secret information used in Containerfile build stages in a safe way. - -This is equivalent to the `--secret` option of `podman build` and generally has the form -`secret[,opt=opt ...]`. - -### `SetWorkingDirectory=` - -Provide context (a working directory) to `podman build`. Supported values are a path, a URL, or the -special keys `file` or `unit` to set the context directory to the parent directory of the file from -the `File=` key or to that of the Quadlet `.build` unit file, respectively. This allows Quadlet to -resolve relative paths. - -When using one of the special keys (`file` or `unit`), the `WorkingDirectory` field of the `Service` -group of the Systemd service unit will also be set to accordingly. Alternatively, users can -explicitly set the `WorkingDirectory` field of the `Service` group in the `.build` file. Please note -that if the `WorkingDirectory` field of the `Service` group is set by the user, Quadlet will not -overwrite it even if `SetWorkingDirectory` is set to `file` or `unit`. - -By providing a URL to `SetWorkingDirectory=` you can instruct `podman build` to clone a Git -repository or download an archive file extracted to a temporary location by `podman build` as build -context. Note that in this case, the `WorkingDirectory` of the Systemd service unit is left -untouched by Quadlet. - -Note that providing context directory is mandatory for a `.build` file, unless a `File=` key has -also been provided. - -### `Target=` - -Set the target build stage to build. Commands in the Containerfile after the target stage are -skipped. - -This is equivalent to the `--target` option of `podman build`. - -### `TLSVerify=` - -Require HTTPS and verification of certificates when contacting registries. - -This is equivalent to the `--tls-verify` option of `podman build`. - -### `Variant=` - -Override the default architecture variant of the container image to be built. - -This is equivalent to the `--variant` option of `podman build`. - -### `Volume=` - -Mount a volume to containers when executing RUN instructions during the build. This is equivalent to -the `--volume` option of `podman build`, and generally has the form -`[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]`. - -If `SOURCE-VOLUME` starts with `.`, Quadlet resolves the path relative to the location of the unit file. - -Special case: - -* If `SOURCE-VOLUME` ends with `.volume`, Quadlet will look for the corresponding `.volume` Quadlet unit. If found, Quadlet will use the name of the Volume set in the Unit, otherwise, `systemd-$name` is used. The generated systemd service contains a dependency on the service unit generated for that `.volume` unit, or on `$name-volume.service` if the `.volume` unit is not found. Note: the corresponding `.volume` file must exist. - -This key can be listed multiple times. - -## Image units [Image] - -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. - -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 | - -### `AllTags=` - -All tagged images in the repository are pulled. - -This is equivalent to the Podman `--all-tags` option. - -### `Arch=` - -Override the architecture, defaults to hosts, of the image to be pulled. - -This is equivalent to the Podman `--arch` option. - -### `AuthFile=` - -Path of the authentication file. - -This is equivalent to the Podman `--authfile` option. - -### `CertDir=` - -Use certificates at path (*.crt, *.cert, *.key) to connect to the registry. - -This is equivalent to the Podman `--cert-dir` option. - -### `ContainersConfModule=` - -Load the specified containers.conf(5) module. Equivalent to the Podman `--module` option. - -This key can be listed multiple times. - -### `Creds=` - -The `[username[:password]]` to use to authenticate with the registry, if required. - -This is equivalent to the Podman `--creds` option. - -### `DecryptionKey=` - -The `[key[:passphrase]]` to be used for decryption of images. - -This is equivalent to the Podman `--decryption-key` option. - -### `GlobalArgs=` - -This key contains a list of arguments passed directly between `podman` and `image` -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`. So, it supports using -`:tag` or digests to guarantee the specific image version. - -### `ImageTag=` - -Actual FQIN of the referenced `Image`. -Only meaningful when 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` - -### `OS=` - -Override the OS, defaults to hosts, of the image to be pulled. - -This is equivalent to the Podman `--os` option. - -### `PodmanArgs=` - -This key contains a list of arguments passed directly to the end of the `podman image pull` command -in the generated file (right before the image name in the command line). 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. - -### `Policy=` - -The pull policy to use when pulling the image. - -This is equivalent to the Podman `--policy` option. - -### `Retry=` - -Number of times to retry the image pull when a HTTP error occurs. Equivalent to the Podman `--retry` option. - -### `RetryDelay=` - -Delay between retries. Equivalent to the Podman `--retry-delay` option. - -### `TLSVerify=` - -Require HTTPS and verification of certificates when contacting registries. - -This is equivalent to the Podman `--tls-verify` option. - -### `Variant=` - -Override the default architecture variant of the container image. - -This is equivalent to the Podman `--variant` option. - -## Quadlet section [Quadlet] -Some quadlet specific configuration is shared between different unit types. Those settings -can be configured in the `[Quadlet]` section. - -Valid options for `[Quadlet]` are listed below: - -| **[Quadlet] options** | **Description** | -|----------------------------|---------------------------------------------------| -| DefaultDependencies=false | Disable implicit network dependencies to the unit | - -### `DefaultDependencies=` - -Add Quadlet's default network dependencies to the unit (default is `true`). - -When set to false, Quadlet will **not** add a dependency (After=, Wants=) to -`network-online.target`/`podman-user-wait-network-online.service` to the generated unit. - -Note, this option is set in the `[Quadlet]` section. The _systemd_ `[Unit]` section -has an option with the same name but a different meaning. - -## EXAMPLES - -Example `test.container`: - -``` -[Unit] -Description=A minimal container - -[Container] -# Use the centos image -Image=quay.io/centos/centos:latest - -# Use volume and network defined below -Volume=test.volume:/data -Network=test.network - -# In the container we just run sleep -Exec=sleep 60 - -[Service] -# Restart service when sleep finishes -Restart=always -# Extend Timeout to allow time to pull the image -TimeoutStartSec=900 -# ExecStartPre flag and other systemd commands can go here, see systemd.unit(5) man page. -ExecStartPre=/usr/share/mincontainer/setup.sh - -[Install] -# Start by default on boot -WantedBy=multi-user.target default.target -``` - -Example `test.kube`: -``` -[Unit] -Description=A kubernetes yaml based service -Before=local-fs.target - -[Kube] -Yaml=/opt/k8s/deployment.yml - -[Install] -# Start by default on boot -WantedBy=multi-user.target default.target -``` - -Example for locally built image to be used in a container: - -`test.build` -``` -[Build] -# Tag the image to be built -ImageTag=localhost/imagename - -# Set the working directory to the path of the unit file, -# expecting to find a Containerfile/Dockerfile -# + other files needed to build the image -SetWorkingDirectory=unit -``` - -`test.container` -``` -[Container] -Image=test.build -``` - -Example `test.volume`: - -``` -[Volume] -User=root -Group=root -Label=org.test.Key=value -``` - -Example `test.network`: -``` -[Network] -Subnet=172.16.0.0/24 -Gateway=172.16.0.1 -IPRange=172.16.0.0/28 -Label=org.test.Key=value -``` - -Example for Container in a Pod: - -`test.pod` -``` -[Pod] -PodName=test -``` - -`centos.container` -``` -[Container] -Image=quay.io/centos/centos:latest -Exec=sh -c "sleep inf" -Pod=test.pod -``` - -Example for a Pod with a oneshot Startup Task: - -`test.pod` -``` -[Pod] -PodName=test -ExitPolicy=continue -``` - -`startup-task.container` -``` -[Service] -Type=oneshot -RemainAfterExit=yes - -[Container] -Pod=test.pod -Image=quay.io/centos/centos:latest -Exec=sh -c "echo 'setup starting'; sleep 2; echo 'setup complete'" -``` - -`app.container` -``` -[Unit] -Requires=startup-task.container -After=startup-task.container - -[Container] -Pod=test.pod -Image=quay.io/centos/centos:latest -Exec=sh -c "echo 'app running.'; sleep 30" -``` - -Example `s3fs.volume`: - -For further details, please see the [s3fs-fuse](https://github.com/s3fs-fuse/s3fs-fuse) project. -Remember to read the [FAQ](https://github.com/s3fs-fuse/s3fs-fuse/wiki/FAQ) - -> NOTE: Enabling the cache massively speeds up access and write times on static files/objects. - -> However, `use_cache` is [UNBOUNDED](https://github.com/s3fs-fuse/s3fs-fuse/wiki/FAQ#q-how-does-the-local-file-cache-work)! - -> Be careful, it will fill up with any files accessed on the s3 bucket through the file system. - -Please remember to set `S3_BUCKET`, `PATH`, `AWS_REGION`. `CACHE_DIRECTORY` should be set up by [systemd](https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#RuntimeDirectory=) - -``` -[Service] -CacheDirectory=s3fs -ExecStartPre=/usr/local/bin/aws s3api put-object --bucket ${S3_BUCKET} --key ${PATH}/ - -[Volume] -Device=${S3_BUCKET}:/${PATH} -Type=fuse.s3fs -VolumeName=s3fs-volume -Options=iam_role,endpoint=${AWS_REGION},use_xattr,listobjectsv2,del_cache,use_cache=${CACHE_DIRECTORY} -# `iam_role` assumes inside EC2, if not, Use `profile=` instead -``` - -## SEE ALSO -**[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)**, -**[systemd.service(5)](https://www.freedesktop.org/software/systemd/man/systemd.service.html)**, -**[systemd-analyze(1)](https://www.freedesktop.org/software/systemd/man/latest/systemd-analyze.html)**, -**[podman-run(1)](podman-run.1.md)**, -**[podman-network-create(1)](podman-network-create.1.md)**, -**[podman-auto-update(1)](podman-auto-update.1.md)** diff --git a/docs/source/markdown/podman-volume.unit.5.md.in b/docs/source/markdown/podman-volume.unit.5.md.in new file mode 100644 index 0000000000..036a92d26f --- /dev/null +++ b/docs/source/markdown/podman-volume.unit.5.md.in @@ -0,0 +1,177 @@ +% podman-volume.unit(5) + +# NAME + +podman\-volume.unit - systemd unit files for managing container volumes using Podman Quadlet + +# SYNOPSIS + +*name*.container + +# DESCRIPTION + +Volume files are named with a `.volume` extension and contain a section `[Volume]` describing the +named Podman volume. The generated service is a one-time command that ensures that the volume +exists on the host, creating it if needed. + +By default, the Podman volume has the same name as the unit, but with a `systemd-` prefix, i.e. for +a volume file named `$NAME.volume`, the generated Podman volume is called `systemd-$NAME`, and the +generated service file is `$NAME-volume.service`. The `VolumeName` option allows for overriding this +default name with a user-provided one. + +Using volume units allows containers to depend on volumes being automatically pre-created. This is +particularly interesting when using special options to control volume creation, +as Podman otherwise creates volumes with the default options. + +# FILE LOCATIONS + +Place `.pod` files in one of the following: + +### Rootless + +- `$XDG_RUNTIME_DIR/containers/systemd/` +- `$XDG_CONFIG_HOME/containers/systemd/` or `~/.config/containers/systemd/` +- `/etc/containers/systemd/users/$(UID)` +- `/etc/containers/systemd/users/` + +### Rootful + +- `/run/containers/systemd/` +- `/etc/containers/systemd/` +- `/usr/share/containers/systemd/` + +# OPTIONS + +Valid options for `[Volume]` are listed below: + +| **[Volume] options** | **podman volume create equivalent** | +|-------------------------------------|-------------------------------------------| +| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | +| Copy=true | --opt copy | +| Device=tmpfs | --opt device=tmpfs | +| Driver=image | --driver=image | +| GlobalArgs=--log-level=debug | --log-level=debug | +| Group=192 | --opt group=192 | +| Image=quay.io/centos/centos\:latest | --opt image=quay.io/centos/centos\:latest | +| Label="foo=bar" | --label "foo=bar" | +| Options=XYZ | --opt "o=XYZ" | +| PodmanArgs=--driver=image | --driver=image | +| Type=type | Filesystem type of Device | +| User=123 | --opt uid=123 | +| VolumeName=foo | podman volume create foo | + +Supported keys in `[Volume]` section are: + +@@option quadlet:module + +### `Copy=` (default to `true`) + +If enabled, the content of the image located at the mountpoint of the volume is copied into the +volume on the first run. + +### `Device=` + +The path of a device which is mounted for the volume. + +### `Driver=` + +Specify the volume driver name. When set to `image`, the `Image` key must also be set. + +This is equivalent to the Podman `--driver` option. + +### `GlobalArgs=` + +This key contains a list of arguments passed directly between `podman` and `volume` +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. + +### `Group=` + +The host (numeric) GID, or group name to use as the group for the volume + +### `Image=` + +Specifies the image the volume is based on when `Driver` is set to the `image`. +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`. So, it supports using +`:tag` or digests to guarantee the specific image version. + +Special case: + +* If the `name` of the image ends with `.image`, Quadlet will use the image +pulled by the corresponding `.image` file, and the generated systemd service contains a dependency on the `$name-image.service` (or the service name set in the .image file). Note: the corresponding `.image` file must exist. + +### `Label=` + +Set one or more OCI labels on the volume. The format is a list of +`key=value` items, similar to `Environment`. + +This key can be listed multiple times. + +### `Options=` + +The mount options to use for a filesystem as used by the **mount(8)** command `-o` option. + +### `PodmanArgs=` + +This key contains a list of arguments passed directly to the end of the `podman volume create` command +in the generated file (right before the name of the volume in the command line). 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, 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. + +### `Type=` + +The filesystem type of `Device` as used by the **mount(8)** commands `-t` option. + +### `User=` + +The host (numeric) UID, or user name to use as the owner for the volume + +### `VolumeName=` + +The (optional) name of the Podman volume. +If this is not specified, the default value is the same name as the unit, but with a `systemd-` prefix, +i.e. a `$name.volume` file creates a `systemd-$name` Podman volume to avoid +conflicts with user-managed volumes. + +# EXAMPLE + +Minimal volume unit: + +``` +[Volume] +VolumeName=mydata +Label=app=data +User=1000 +Group=1000 +``` + +Volume unit backed by an image: + +``` +[Volume] +VolumeName=html +Driver=image +Image=quay.io/centos/centos:latest +Copy=true +``` + +# SEE ALSO + +[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html), +[podman-volume-create(1)](https://docs.podman.io/en/latest/markdown/podman-volume-create.1.html), +[podman-quadlet(7)] diff --git a/docs/source/markdown/podmansh.1.md b/docs/source/markdown/podmansh.1.md index a4ca55548c..1c5f32a553 100644 --- a/docs/source/markdown/podmansh.1.md +++ b/docs/source/markdown/podmansh.1.md @@ -127,7 +127,7 @@ _EOF ``` ## SEE ALSO -**[containers.conf(5)](containers.conf.5.md)**, **[podman(1)](podman.1.md)**, **[podman-exec(1)](podman-exec.1.md)**, **[podman-systemd.unit(5)](podman-systemd.unit.5.md)** +**[containers.conf(5)](containers.conf.5.md)**, **[podman(1)](podman.1.md)**, **[podman-exec(1)](podman-exec.1.md)**, **[podman-quadlet(7)](podman-quadlet.7.md)** ## HISTORY May 2023, Originally compiled by Dan Walsh diff --git a/hack/markdown-preprocess b/hack/markdown-preprocess index 11fa1ea9e1..8c37a08ee6 100755 --- a/hack/markdown-preprocess +++ b/hack/markdown-preprocess @@ -11,6 +11,7 @@ import glob import os import re import sys +from jinja2 import Template class Preprocessor(): """ @@ -40,18 +41,24 @@ class Preprocessor(): with open(infile, 'r', encoding='utf-8') as fh_in, open(outfile_tmp, 'w', encoding='utf-8', newline='\n') as fh_out: for line in fh_in: - # '@@option foo' -> include file options/foo.md - if line.startswith('@@option '): - _, optionname = line.strip().split(" ") - optionfile = os.path.join("options", optionname + '.md') - self.track_optionfile(optionfile) - self.insert_file(fh_out, optionfile) - # '@@include relative-path/must-exist.md' - elif line.startswith('@@include '): - _, path = line.strip().split(" ") - self.insert_file(fh_out, path) - else: - fh_out.write(line) + try: + # '@@option foo' -> include file options/foo.md + if line.startswith('@@option '): + _, optionname = line.strip().split(" ") + is_quadlet = optionname.startswith("quadlet:") + if is_quadlet: + optionname = optionname[len("quadlet:"):] + optionfile = os.path.join("options", optionname + '.md') + self.track_optionfile(optionfile) + self.insert_file(fh_out, optionfile, is_quadlet) + # '@@include relative-path/must-exist.md' + elif line.startswith('@@include '): + _, path = line.strip().split(" ") + self.insert_file(fh_out, path) + else: + fh_out.write(line) + except Exception as ex: + raise Exception(f"Error while processing {infile} line '{line[:-1]}'") from ex os.chmod(outfile_tmp, 0o444) os.rename(outfile_tmp, outfile) @@ -87,7 +94,7 @@ class Preprocessor(): else: os.unlink(tmpfile) - def insert_file(self, fh_out, path: str): + def insert_file(self, fh_out, path: str, is_quadlet=False): """ Reads one option file, writes it out to the given output filehandle """ @@ -98,13 +105,20 @@ class Preprocessor(): # comment in its output. fh_out.write("\n[//]: # (BEGIN included file " + path + ")\n") with open(path, 'r', encoding='utf-8') as fh_included: - for opt_line in fh_included: + template = Template(fh_included.read(), variable_start_string='{{{', variable_end_string='}}}') + rendered = template.render( + is_quadlet=is_quadlet, + subcommand=self.podman_subcommand, + fullsubcommand=self.podman_subcommand('full') + ) + for opt_line in rendered.splitlines(): if opt_line.startswith('####>'): continue + opt_line = self.replace_type(opt_line) opt_line = opt_line.replace('<>', self.podman_subcommand()) opt_line = opt_line.replace('<>', self.podman_subcommand('full')) - fh_out.write(opt_line) + fh_out.write(opt_line + '\n') fh_out.write("\n[//]: # (END included file " + path + ")\n") def podman_subcommand(self, full=None) -> str: @@ -117,6 +131,9 @@ class Preprocessor(): if not full: if subcommand.startswith("podman-pod-"): subcommand = subcommand[len("podman-pod-"):] + # For quadlet man-pages, the subcommand is simply the full manpage name. + if subcommand.endswith(".unit.5.md.in"): + return subcommand if subcommand.startswith("podman-"): subcommand = subcommand[len("podman-"):] if subcommand.endswith(".1.md.in"): diff --git a/rpm/podman.spec b/rpm/podman.spec index 1064c20f2f..ba615648b6 100644 --- a/rpm/podman.spec +++ b/rpm/podman.spec @@ -99,6 +99,7 @@ BuildRequires: man-db BuildRequires: sqlite-devel BuildRequires: systemd BuildRequires: systemd-devel +BuildRequires: python3-jinja2 Requires: catatonit Requires: conmon >= 2:2.1.7-2 %if %{defined fedora} && 0%{?fedora} >= 40