From 4ae8e386ef62a14f6cd38a1a5f77e5474931cf91 Mon Sep 17 00:00:00 2001 From: Paul Holzinger Date: Thu, 11 Sep 2025 18:59:11 +0200 Subject: [PATCH 1/4] Revert "docs: restore podman-systemd.unit.5" This reverts commit cab3c6de6d59fc51aff26591c24ffe2d5ee2a20e. Signed-off-by: Paul Holzinger --- docs/source/markdown/links/podman-systemd.unit.5 | 1 + docs/source/markdown/links/quadlet.5 | 2 +- docs/source/markdown/podman-auto-update.1.md.in | 2 +- docs/source/markdown/podman-generate-systemd.1.md | 2 +- .../{podman-systemd.unit.5.md => podman-quadlet.7.md} | 7 ++++--- docs/source/markdown/podmansh.1.md | 2 +- hack/xref-quadlet-docs | 2 +- 7 files changed, 10 insertions(+), 8 deletions(-) create mode 100644 docs/source/markdown/links/podman-systemd.unit.5 rename docs/source/markdown/{podman-systemd.unit.5.md => podman-quadlet.7.md} (94%) diff --git a/docs/source/markdown/links/podman-systemd.unit.5 b/docs/source/markdown/links/podman-systemd.unit.5 new file mode 100644 index 0000000000..8b26a55dfd --- /dev/null +++ b/docs/source/markdown/links/podman-systemd.unit.5 @@ -0,0 +1 @@ +.so man7/podman-quadlet.7 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/podman-auto-update.1.md.in b/docs/source/markdown/podman-auto-update.1.md.in index ba75679fb4..75b1c27f45 100644 --- a/docs/source/markdown/podman-auto-update.1.md.in +++ b/docs/source/markdown/podman-auto-update.1.md.in @@ -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-generate-systemd.1.md b/docs/source/markdown/podman-generate-systemd.1.md index 6897cb1d03..2d5eb34dad 100644 --- a/docs/source/markdown/podman-generate-systemd.1.md +++ b/docs/source/markdown/podman-generate-systemd.1.md @@ -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-systemd.unit.5.md b/docs/source/markdown/podman-quadlet.7.md similarity index 94% rename from docs/source/markdown/podman-systemd.unit.5.md rename to docs/source/markdown/podman-quadlet.7.md index d2a8f2cd6b..0aa1df5abb 100644 --- a/docs/source/markdown/podman-systemd.unit.5.md +++ b/docs/source/markdown/podman-quadlet.7.md @@ -1,12 +1,12 @@ -% podman-systemd.unit(5) +% podman-quadlet(7) # NAME -podman-systemd.unit - High-level overview of Podman Quadlet integration with systemd +podman\-quadlet - High-level overview of Podman Quadlet integration with systemd # DESCRIPTION -Quadlet is a systemd unit generator that enables declarative container management by defining +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. @@ -99,6 +99,7 @@ has an option with the same name but a different meaning. # 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), 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/xref-quadlet-docs b/hack/xref-quadlet-docs index 56d54a52a9..d20246d0e4 100755 --- a/hack/xref-quadlet-docs +++ b/hack/xref-quadlet-docs @@ -27,7 +27,7 @@ our @Docs = ( "docs/source/markdown/podman-pod.unit.5.md", "docs/source/markdown/podman-volume.unit.5.md", "docs/source/markdown/podman-image.unit.5.md", - "docs/source/markdown/podman-systemd.unit.5.md", + "docs/source/markdown/podman-quadlet.7.md", ); # END user-customizable section From fd60d63bf4e86f4a33743160083f8eb6a8014111 Mon Sep 17 00:00:00 2001 From: Paul Holzinger Date: Thu, 11 Sep 2025 19:00:02 +0200 Subject: [PATCH 2/4] Revert "Deduplicate more options." This reverts commit 6756eb34129381707626ec45761799ac5623dc5c. Signed-off-by: Paul Holzinger --- docs/source/markdown/.gitignore | 2 - docs/source/markdown/options/all-tags.md | 13 -- .../markdown/options/annotation.image.md | 4 +- docs/source/markdown/options/auto-update.md | 11 - docs/source/markdown/options/configmap.md | 18 -- docs/source/markdown/options/disable-dns.md | 12 - docs/source/markdown/options/dns.md | 2 +- docs/source/markdown/options/driver.md | 25 -- docs/source/markdown/options/env.md | 2 +- docs/source/markdown/options/exec.md | 18 -- .../markdown/options/force.kube-down.md | 11 - docs/source/markdown/options/gateway.md | 16 -- docs/source/markdown/options/global-args.md | 15 -- .../source/markdown/options/interface-name.md | 13 -- docs/source/markdown/options/internal.md | 25 -- docs/source/markdown/options/ip-range.md | 17 -- docs/source/markdown/options/ipam-driver.md | 22 -- docs/source/markdown/options/ipv6.md | 11 - docs/source/markdown/options/label.md | 2 +- docs/source/markdown/options/label.network.md | 11 - docs/source/markdown/options/opt.md | 40 ---- docs/source/markdown/options/podman-args.md | 15 -- docs/source/markdown/options/policy.md | 16 -- docs/source/markdown/options/subnet.md | 15 -- docs/source/markdown/options/variant.build.md | 13 -- docs/source/markdown/podman-build.1.md.in | 6 +- .../source/markdown/podman-build.unit.5.md.in | 40 +++- .../markdown/podman-container.unit.5.md.in | 79 +++++-- .../source/markdown/podman-image.unit.5.md.in | 37 ++- ...ube-down.1.md.in => podman-kube-down.1.md} | 4 +- docs/source/markdown/podman-kube-play.1.md.in | 7 +- docs/source/markdown/podman-kube.unit.5.md.in | 40 +++- .../markdown/podman-network-create.1.md | 215 ++++++++++++++++++ .../markdown/podman-network-create.1.md.in | 114 ---------- .../markdown/podman-network.unit.5.md.in | 111 +++++++-- docs/source/markdown/podman-pod.unit.5.md.in | 29 ++- docs/source/markdown/podman-pull.1.md.in | 13 +- .../markdown/podman-volume.unit.5.md.in | 24 +- 38 files changed, 545 insertions(+), 523 deletions(-) delete mode 100644 docs/source/markdown/options/all-tags.md delete mode 100644 docs/source/markdown/options/auto-update.md delete mode 100644 docs/source/markdown/options/configmap.md delete mode 100644 docs/source/markdown/options/disable-dns.md delete mode 100644 docs/source/markdown/options/driver.md delete mode 100644 docs/source/markdown/options/exec.md delete mode 100644 docs/source/markdown/options/force.kube-down.md delete mode 100644 docs/source/markdown/options/gateway.md delete mode 100644 docs/source/markdown/options/global-args.md delete mode 100644 docs/source/markdown/options/interface-name.md delete mode 100644 docs/source/markdown/options/internal.md delete mode 100644 docs/source/markdown/options/ip-range.md delete mode 100644 docs/source/markdown/options/ipam-driver.md delete mode 100644 docs/source/markdown/options/ipv6.md delete mode 100644 docs/source/markdown/options/label.network.md delete mode 100644 docs/source/markdown/options/opt.md delete mode 100644 docs/source/markdown/options/podman-args.md delete mode 100644 docs/source/markdown/options/policy.md delete mode 100644 docs/source/markdown/options/subnet.md delete mode 100644 docs/source/markdown/options/variant.build.md rename docs/source/markdown/{podman-kube-down.1.md.in => podman-kube-down.1.md} (96%) create mode 100644 docs/source/markdown/podman-network-create.1.md delete mode 100644 docs/source/markdown/podman-network-create.1.md.in diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore index a02522d0af..a48ec92172 100644 --- a/docs/source/markdown/.gitignore +++ b/docs/source/markdown/.gitignore @@ -34,7 +34,6 @@ podman-manifest-create.1.md podman-manifest-inspect.1.md podman-manifest-push.1.md podman-mount.1.md -podman-network-create.1.md podman-network-ls.1.md podman-network-reload.1.md podman-pause.1.md @@ -74,7 +73,6 @@ podman-build.unit.5.md podman-container.unit.5.md podman-image.unit.5.md podman-kube.unit.5.md -podman-kube-down.1.md podman-network.unit.5.md podman-pod.unit.5.md podman-volume.unit.5.md diff --git a/docs/source/markdown/options/all-tags.md b/docs/source/markdown/options/all-tags.md deleted file mode 100644 index 6da4e5e5f8..0000000000 --- a/docs/source/markdown/options/all-tags.md +++ /dev/null @@ -1,13 +0,0 @@ -####> This option file is used in: -####> podman podman-image.unit.5.md.in, pull -####> If file is edited, make sure the changes -####> are applicable to all of those. -<< if is_quadlet >> -### `AllTags=true` -<< else >> -#### **--all-tags**, **-a** -<< endif >> - -All tagged images in the repository are pulled. - -*IMPORTANT: When using the all-tags flag, Podman does not iterate over the search registries in the **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)** but always uses docker.io for unqualified image names.* diff --git a/docs/source/markdown/options/annotation.image.md b/docs/source/markdown/options/annotation.image.md index b74abc2ad7..b887ee3242 100644 --- a/docs/source/markdown/options/annotation.image.md +++ b/docs/source/markdown/options/annotation.image.md @@ -1,9 +1,9 @@ ####> This option file is used in: -####> podman build, podman-build.unit.5.md.in, farm build +####> podman build, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. << if is_quadlet >> -### `Annotation=annotation=value [annotation=value ...]` +### `Annotation=annotation=value` << else >> #### **--annotation**=*annotation=value* << endif >> diff --git a/docs/source/markdown/options/auto-update.md b/docs/source/markdown/options/auto-update.md deleted file mode 100644 index 49a0719216..0000000000 --- a/docs/source/markdown/options/auto-update.md +++ /dev/null @@ -1,11 +0,0 @@ -####> This option file is used in: -####> podman podman-container.unit.5.md.in -####> If file is edited, make sure the changes -####> are applicable to all of those. -### `AutoUpdate=registry` - -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. diff --git a/docs/source/markdown/options/configmap.md b/docs/source/markdown/options/configmap.md deleted file mode 100644 index 15ac9a83c1..0000000000 --- a/docs/source/markdown/options/configmap.md +++ /dev/null @@ -1,18 +0,0 @@ -####> This option file is used in: -####> podman kube play, podman-kube.unit.5.md.in -####> If file is edited, make sure the changes -####> are applicable to all of those. -<< if is_quadlet >> -### `ConfigMap=path` -<< else >> -#### **--configmap**=*path* -<< endif >> - -Use Kubernetes configmap YAML at path to provide a source for environment variable values within the containers of the pod. (This option is not available with the remote Podman client) - -<< if is_quadlet >> -The value may contain only one path but it may be absolute or relative to the location of the unit file. -<< else >> -Note: The **--configmap** option can be used multiple times or a comma-separated list of paths can be used to pass multiple Kubernetes configmap YAMLs. -The YAML file may be in a multi-doc YAML format. But, it must contain only configmaps. -<< endif >> diff --git a/docs/source/markdown/options/disable-dns.md b/docs/source/markdown/options/disable-dns.md deleted file mode 100644 index 53db5eddc2..0000000000 --- a/docs/source/markdown/options/disable-dns.md +++ /dev/null @@ -1,12 +0,0 @@ -####> This option file is used in: -####> podman network create, podman-network.unit.5.md.in -####> If file is edited, make sure the changes -####> are applicable to all of those. -<< if is_quadlet >> -### `DisableDNS=true` -<< else >> -#### **--disable-dns** -<< endif >> - -Disables the DNS plugin for this network which if enabled, can perform container to container name -resolution. It is only supported with the `bridge` driver, for other drivers it is always disabled. diff --git a/docs/source/markdown/options/dns.md b/docs/source/markdown/options/dns.md index 050dd95f84..399a715a4a 100644 --- a/docs/source/markdown/options/dns.md +++ b/docs/source/markdown/options/dns.md @@ -1,5 +1,5 @@ ####> This option file is used in: -####> podman build, podman-build.unit.5.md.in, podman-container.unit.5.md.in, create, farm build, network create, podman-network.unit.5.md.in, podman-pod.unit.5.md.in, 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 >> diff --git a/docs/source/markdown/options/driver.md b/docs/source/markdown/options/driver.md deleted file mode 100644 index b4501f8d28..0000000000 --- a/docs/source/markdown/options/driver.md +++ /dev/null @@ -1,25 +0,0 @@ -####> This option file is used in: -####> podman network create, podman-network.unit.5.md.in -####> If file is edited, make sure the changes -####> are applicable to all of those. -<< if is_quadlet >> -### `Driver=driver` -<< else >> -#### **--driver**, **-d**=*driver* -<< endif >> - -Driver to manage the network. Currently `bridge`, `macvlan` and `ipvlan` are supported. Defaults to `bridge`. -As rootless the `macvlan` and `ipvlan` driver have no access to the host network interfaces because rootless networking requires a separate network namespace. - -The netavark backend allows the use of so called *netavark plugins*, see the -[plugin-API.md](https://github.com/containers/netavark/blob/main/plugin-API.md) -documentation in netavark. The binary must be placed in a specified directory -so podman can discover it, this list is set in `netavark_plugin_dirs` in -**[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)** -under the `[network]` section. - -The name of the plugin can then be used as driver to create a network for your plugin. -The list of all supported drivers and plugins can be seen with `podman info --format {{.Plugins.Network}}`. - -Note that the `macvlan` and `ipvlan` drivers do not support port forwarding. Support for port forwarding -with a plugin depends on the implementation of the plugin. diff --git a/docs/source/markdown/options/env.md b/docs/source/markdown/options/env.md index 9cffeff9ec..297ef3ed5a 100644 --- a/docs/source/markdown/options/env.md +++ b/docs/source/markdown/options/env.md @@ -3,7 +3,7 @@ ####> If file is edited, make sure the changes ####> are applicable to all of those. << if is_quadlet >> -### `Environment=env=value [env=value ...]` +### `Environment=env` << else >> #### **--env**, **-e**=*env* << endif >> diff --git a/docs/source/markdown/options/exec.md b/docs/source/markdown/options/exec.md deleted file mode 100644 index af79076e3a..0000000000 --- a/docs/source/markdown/options/exec.md +++ /dev/null @@ -1,18 +0,0 @@ -####> This option file is used in: -####> podman podman-container.unit.5.md.in -####> If file is edited, make sure the changes -####> are applicable to all of those. -### `Exec=command` - -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). diff --git a/docs/source/markdown/options/force.kube-down.md b/docs/source/markdown/options/force.kube-down.md deleted file mode 100644 index ed75202e72..0000000000 --- a/docs/source/markdown/options/force.kube-down.md +++ /dev/null @@ -1,11 +0,0 @@ -####> This option file is used in: -####> podman kube down -####> If file is edited, make sure the changes -####> are applicable to all of those. -<< if is_quadlet >> -### `KubeDownForce=true` -<< else >> -#### **--force** -<< endif >> - -Remove all resources, including volumes, when calling `podman kube down`. diff --git a/docs/source/markdown/options/gateway.md b/docs/source/markdown/options/gateway.md deleted file mode 100644 index 81f2785c7f..0000000000 --- a/docs/source/markdown/options/gateway.md +++ /dev/null @@ -1,16 +0,0 @@ -####> This option file is used in: -####> podman network create, podman-network.unit.5.md.in -####> If file is edited, make sure the changes -####> are applicable to all of those. -<< if is_quadlet >> -### `Gateway=ip` -<< else >> -#### **--gateway**=*ip* -<< endif >> - -Define a gateway for the subnet. To provide a gateway address, a -*subnet* option is required. Can be specified multiple times. - -<< if not is_quadlet >> -The argument order of the **--subnet**, **--gateway** and **--ip-range** options must match. -<< endif >> diff --git a/docs/source/markdown/options/global-args.md b/docs/source/markdown/options/global-args.md deleted file mode 100644 index b63409a44e..0000000000 --- a/docs/source/markdown/options/global-args.md +++ /dev/null @@ -1,15 +0,0 @@ -####> 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. -### `GlobalArgs=` - -This key contains a list of arguments passed directly after the `podman` command in the generated -file. It can be used to access Podman features otherwise unsupported by the generator. Since the -generator is unaware of what unexpected interactions can be caused by these arguments, it is not -recommended to use this option. - -The format of this is a space separated list of arguments, which can optionally be individually -escaped to allow inclusion of whitespace and other control characters. - -This key can be listed multiple times. diff --git a/docs/source/markdown/options/interface-name.md b/docs/source/markdown/options/interface-name.md deleted file mode 100644 index 612395129e..0000000000 --- a/docs/source/markdown/options/interface-name.md +++ /dev/null @@ -1,13 +0,0 @@ -####> This option file is used in: -####> podman network create, podman-network.unit.5.md.in -####> If file is edited, make sure the changes -####> are applicable to all of those. -<< if is_quadlet >> -### `InterfaceName=name` -<< else >> -#### **--interface-name**=*name* -<< endif >> - -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=...`. diff --git a/docs/source/markdown/options/internal.md b/docs/source/markdown/options/internal.md deleted file mode 100644 index f7d32198d9..0000000000 --- a/docs/source/markdown/options/internal.md +++ /dev/null @@ -1,25 +0,0 @@ -####> This option file is used in: -####> podman network create, podman-network.unit.5.md.in -####> If file is edited, make sure the changes -####> are applicable to all of those. -<< if is_quadlet >> -### `Internal=true` -<< else >> -#### **--internal** -<< endif >> - -Restrict external access of this network when using a `bridge` network. Note when using the CNI backend -DNS will be automatically disabled, see **--disable-dns**. - -When using the `macvlan` or `ipvlan` driver with this option no default route will be added to the container. -Because it bypasses the host network stack no additional restrictions can be set by podman and if a -privileged container is run it can set a default route themselves. If this is a concern then the -container connections should be blocked on your actual network gateway. - -Using the `bridge` driver with this option has the following effects: - - Global IP forwarding sysctls will not be changed in the host network namespace. - - IP forwarding is disabled on the bridge interface instead of setting up a firewall. - - No default route will be added to the container. - -In all cases, aardvark-dns will only resolve container names with this option enabled. -Other queries will be answered with `NXDOMAIN`. diff --git a/docs/source/markdown/options/ip-range.md b/docs/source/markdown/options/ip-range.md deleted file mode 100644 index 5c8f245ea3..0000000000 --- a/docs/source/markdown/options/ip-range.md +++ /dev/null @@ -1,17 +0,0 @@ -####> This option file is used in: -####> podman network create, podman-network.unit.5.md.in -####> If file is edited, make sure the changes -####> are applicable to all of those. -<< if is_quadlet >> -### `IPRange=ip` -<< else >> -#### **--ip-range**=*range* -<< endif >> - -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. Can be specified multiple times. - -<< if not is_quadlet >> -The argument order of the **--subnet**, **--gateway** and **--ip-range** options must match. -<< endif >> diff --git a/docs/source/markdown/options/ipam-driver.md b/docs/source/markdown/options/ipam-driver.md deleted file mode 100644 index 325eb96f79..0000000000 --- a/docs/source/markdown/options/ipam-driver.md +++ /dev/null @@ -1,22 +0,0 @@ -####> This option file is used in: -####> podman network create, podman-network.unit.5.md.in -####> If file is edited, make sure the changes -####> are applicable to all of those. -<< if is_quadlet >> -### `IPAMDriver=driver` -<< else >> -#### **--ipam-driver**=*driver* -<< endif >> - -Set the ipam driver (IP Address Management Driver) for the network. When unset podman chooses an -ipam driver automatically based on the network driver. - -Valid values are: - - - `dhcp`: IP addresses are assigned from a dhcp server on the network. When using the netavark backend - the `netavark-dhcp-proxy.socket` must be enabled in order to start the dhcp-proxy when a container is - started, for CNI use the `cni-dhcp.socket` unit instead. - - `host-local`: IP addresses are assigned locally. - - `none`: No ip addresses are assigned to the interfaces. - -View the driver in the **podman network inspect** output under the `ipam_options` field. diff --git a/docs/source/markdown/options/ipv6.md b/docs/source/markdown/options/ipv6.md deleted file mode 100644 index 4f802ccf61..0000000000 --- a/docs/source/markdown/options/ipv6.md +++ /dev/null @@ -1,11 +0,0 @@ -####> This option file is used in: -####> podman network create, podman-network.unit.5.md.in -####> If file is edited, make sure the changes -####> are applicable to all of those. -<< if is_quadlet >> -### `IPv6=true` -<< else >> -#### **--ipv6** -<< endif >> - -Enable IPv6 (Dual Stack) networking. If no subnets are given, it allocates an ipv4 and an ipv6 subnet. diff --git a/docs/source/markdown/options/label.md b/docs/source/markdown/options/label.md index caae2d8716..9f04e81c08 100644 --- a/docs/source/markdown/options/label.md +++ b/docs/source/markdown/options/label.md @@ -3,7 +3,7 @@ ####> If file is edited, make sure the changes ####> are applicable to all of those. << if is_quadlet >> -### `Label=key=value [key=value ...]` +### `Label=key=value` << else >> #### **--label**, **-l**=*key=value* << endif >> diff --git a/docs/source/markdown/options/label.network.md b/docs/source/markdown/options/label.network.md deleted file mode 100644 index bad977fb04..0000000000 --- a/docs/source/markdown/options/label.network.md +++ /dev/null @@ -1,11 +0,0 @@ -####> This option file is used in: -####> podman network create, podman-network.unit.5.md.in -####> If file is edited, make sure the changes -####> are applicable to all of those. -<< if is_quadlet >> -### `Label=key=value [key=value ...]` -<< else >> -#### **--label**=*key=value* -<< endif >> - -Set one or more OCI labels on the network. diff --git a/docs/source/markdown/options/opt.md b/docs/source/markdown/options/opt.md deleted file mode 100644 index 634a7dae43..0000000000 --- a/docs/source/markdown/options/opt.md +++ /dev/null @@ -1,40 +0,0 @@ -####> This option file is used in: -####> podman network create, podman-network.unit.5.md.in -####> If file is edited, make sure the changes -####> are applicable to all of those. -<< if is_quadlet >> -### `Options=option` -<< else >> -#### **--opt**, **-o**=*option* -<< endif >> - -Set driver specific options. - -All drivers accept the `mtu`, `metric`, `no_default_route` and options. - -- `mtu`: Sets the Maximum Transmission Unit (MTU) and takes an integer value. -- `metric` Sets the Route Metric for the default route created in every container joined to this network. Accepts a positive integer value. Can only be used with the Netavark network backend. -- `no_default_route`: If set to 1, Podman will not automatically add a default route to subnets. Routes can still be added -manually by creating a custom route using `--route`. - -Additionally the `bridge` driver supports the following options: - -- `vlan`: This option assign VLAN tag and enables vlan\_filtering. Defaults to none. -- `isolate`: This option isolates networks by blocking traffic between those that have this option enabled. -- `com.docker.network.bridge.name`: This option assigns the given name to the created Linux Bridge -- `com.docker.network.driver.mtu`: Sets the Maximum Transmission Unit (MTU) and takes an integer value. -- `vrf`: This option assigns a VRF to the bridge interface. It accepts the name of the VRF and defaults to none. Can only be used with the Netavark network backend. -- `mode`: This option sets the specified bridge mode on the interface. Defaults to `managed`. Supported values: - - `managed`: Podman creates and deletes the bridge and changes sysctls of it. It adds firewall rules to masquerade outgoing traffic, as well as setup port forwarding for incoming traffic using DNAT. - - `unmanaged`: Podman uses an existing bridge. It must exist by the time you want to start a container which uses the network. There will be no NAT or port forwarding, even if such options were passed while creating the container. - -The `macvlan` and `ipvlan` driver support the following options: - -- `parent`: The host device which is used for the macvlan interface. Defaults to the default route interface. -- `mode`: This option sets the specified ip/macvlan mode on the interface. - - Supported values for `macvlan` are `bridge`, `private`, `vepa`, `passthru`. Defaults to `bridge`. - - Supported values for `ipvlan` are `l2`, `l3`, `l3s`. Defaults to `l2`. - -Additionally the `macvlan` driver supports the `bclim` option: - -- `bclim`: Set the threshold for broadcast queueing. Must be a 32 bit integer. Setting this value to `-1` disables broadcast queueing altogether. diff --git a/docs/source/markdown/options/podman-args.md b/docs/source/markdown/options/podman-args.md deleted file mode 100644 index 7cd28f54a4..0000000000 --- a/docs/source/markdown/options/podman-args.md +++ /dev/null @@ -1,15 +0,0 @@ -####> 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. -### `PodmanArgs=` - -This key contains a list of arguments passed directly to the end of the `podman` command -in the generated file. It can be used to access Podman features otherwise unsupported -by the generator. Since the generator is unaware of what unexpected interactions can be -caused by these arguments, it is not recommended to use this option. - -The format of this is a space separated list of arguments, which can optionally be individually -escaped to allow inclusion of whitespace and other control characters. - -This key can be listed multiple times. diff --git a/docs/source/markdown/options/policy.md b/docs/source/markdown/options/policy.md deleted file mode 100644 index fce4ac6091..0000000000 --- a/docs/source/markdown/options/policy.md +++ /dev/null @@ -1,16 +0,0 @@ -####> This option file is used in: -####> podman podman-image.unit.5.md.in, pull -####> If file is edited, make sure the changes -####> are applicable to all of those. -<< if is_quadlet >> -### `Policy=always` -<< else >> -#### **--policy** -<< endif >> - -Pull image policy. The default is **always**. - -- `always`: Always pull the image and throw an error if the pull fails. -- `missing`: Only pull the image if it could not be found in the local containers storage. Throw an error if no image could be found and the pull fails. -- `never`: Never pull the image; only use the local version. Throw an error if the image is not present locally. -- `newer`: Pull if the image on the registry is newer than the one in the local containers storage. An image is considered to be newer when the digests are different. Comparing the time stamps is prone to errors. Pull errors are suppressed if a local image was found. diff --git a/docs/source/markdown/options/subnet.md b/docs/source/markdown/options/subnet.md deleted file mode 100644 index 9119ae24da..0000000000 --- a/docs/source/markdown/options/subnet.md +++ /dev/null @@ -1,15 +0,0 @@ -####> This option file is used in: -####> podman network create, podman-network.unit.5.md.in -####> If file is edited, make sure the changes -####> are applicable to all of those. -<< if is_quadlet >> -### `Subnet=subnet` -<< else >> -#### **--subnet**=*subnet* -<< endif >> - -The subnet in CIDR notation. Can be specified multiple times to allocate more than one subnet for this network. -<< if not is_quadlet >> -The argument order of the **--subnet**, **--gateway** and **--ip-range** options must match. -<< endif >> -This is useful to set a static ipv4 and ipv6 subnet. diff --git a/docs/source/markdown/options/variant.build.md b/docs/source/markdown/options/variant.build.md deleted file mode 100644 index 1678aa9c28..0000000000 --- a/docs/source/markdown/options/variant.build.md +++ /dev/null @@ -1,13 +0,0 @@ -####> This option file is used in: -####> podman build, podman-build.unit.5.md.in -####> If file is edited, make sure the changes -####> are applicable to all of those. -<< if is_quadlet >> -### `Variant=VARIANT` -<< else >> -#### **--variant**=*VARIANT* -<< endif >> - -Set the architecture variant of the image to be built, and that of the base -image to be pulled, if the build uses one, to the provided value instead of -using the architecture variant of the build host. diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in index 425fac0653..43b544bcf5 100644 --- a/docs/source/markdown/podman-build.1.md.in +++ b/docs/source/markdown/podman-build.1.md.in @@ -481,7 +481,11 @@ Use --stdin to be able to interact from the terminal during the build. @@option uts -@@option variant.build +#### **--variant**=*variant* + +Set the architecture variant of the image to be built, and that of the base +image to be pulled, if the build uses one, to the provided value instead of +using the architecture variant of the build host. @@option volume.image diff --git a/docs/source/markdown/podman-build.unit.5.md.in b/docs/source/markdown/podman-build.unit.5.md.in index 7d29d37e6e..d995494f05 100644 --- a/docs/source/markdown/podman-build.unit.5.md.in +++ b/docs/source/markdown/podman-build.unit.5.md.in @@ -74,7 +74,12 @@ Valid options for `[Build]` section are listed below: | Variant=arm/v7 | --variant=arm/v7 | | Volume=/source:/dest | --volume /source:/dest | -@@option quadlet:annotation.image +### `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 @@ -94,7 +99,17 @@ Valid options for `[Build]` section are listed below: @@option quadlet:force-rm -@@option quadlet:global-args +### `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 @@ -104,7 +119,18 @@ Valid options for `[Build]` section are listed below: @@option quadlet:network.image -@@option quadlet:podman-args +### `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 @@ -114,7 +140,7 @@ Valid options for `[Build]` section are listed below: @@option quadlet:secret.image -### `SetWorkingDirectory=path` +### `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 @@ -139,7 +165,11 @@ also been provided. @@option quadlet:tls-verify -@@option quadlet:variant.build +### `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 diff --git a/docs/source/markdown/podman-container.unit.5.md.in b/docs/source/markdown/podman-container.unit.5.md.in index 19e90afa39..37ca7dd3f8 100644 --- a/docs/source/markdown/podman-container.unit.5.md.in +++ b/docs/source/markdown/podman-container.unit.5.md.in @@ -138,7 +138,14 @@ Description of `[Container]` section are: @@option quadlet:annotation.container -@@option quadlet:auto-update + +### `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 @@ -162,15 +169,38 @@ Description of `[Container]` section are: @@option quadlet:env-host -@@option quadlet:exec +### `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 -@@option quadlet:global-args +### `GlobalArgs=` -### `Group=gid` +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. @@ -210,7 +240,7 @@ which can be modified with `UserNS`, but if that is not specified, this GID is a @@option quadlet:http-proxy -### `Image=name` +### `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 @@ -234,7 +264,7 @@ Special Cases: @@option quadlet:log-opt -### `Mask=/path/1:/path/2` +### `Mask=` Specify the paths to mask separated by a colon. `Mask=/path/1:/path/2`. A masked path cannot be accessed inside the container. @@ -247,12 +277,12 @@ Specify the paths to mask separated by a colon. `Mask=/path/1:/path/2`. A masked @@option quadlet:network-alias -### `NoNewPrivileges=bool` (defaults to `false`) +### `NoNewPrivileges=` (defaults to `false`) If enabled, this disables the container processes from gaining additional privileges via things like setuid and file capabilities. -### `Notify=bool` (defaults to `false`) +### `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 @@ -267,7 +297,7 @@ setting up a container healthcheck, see the `HealthCmd` option for more. @@option quadlet:pids-limit -### `Pod=name` +### `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. @@ -275,7 +305,18 @@ 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. -@@option quadlet:podman-args +### `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 @@ -285,7 +326,7 @@ Quadlet will add all the necessary parameters to link between the container and @@option quadlet:read-only-tmpfs -### `ReloadCmd=/usr/bin/command` +### `ReloadCmd=` Add `ExecReload` line to the `Service` that runs ` podman exec` with this command in this container. @@ -293,7 +334,7 @@ In order to execute the reload run `systemctl reload ` Mutually exclusive with `ReloadSignal` -### `ReloadSignal=signal` +### `ReloadSignal=` Add `ExecReload` line to the `Service` that runs `podman kill` with this signal which sends the signal to the main container process. @@ -309,36 +350,36 @@ Mutually exclusive with `ReloadCmd` @@option quadlet:init -### `SeccompProfile=path` +### `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=bool` +### `SecurityLabelDisable=` Turn off label separation for the container. -### `SecurityLabelFileType=label` +### `SecurityLabelFileType=` Set the label file type for the container files. -### `SecurityLabelLevel=s0:c1,c2` +### `SecurityLabelLevel=` Set the label process level for the container processes. -### `SecurityLabelNested=bool` +### `SecurityLabelNested=` Allow SecurityLabels to function within the container. This allows separation of containers created within the container. -### `SecurityLabelType=type` +### `SecurityLabelType=` Set the label process type for the container processes. @@option quadlet:shm-size -### `StartWithPod=bool` +### `StartWithPod=` Start the container after the associated pod is created. Default to **true**. diff --git a/docs/source/markdown/podman-image.unit.5.md.in b/docs/source/markdown/podman-image.unit.5.md.in index b9e96aeb61..3179bf0730 100644 --- a/docs/source/markdown/podman-image.unit.5.md.in +++ b/docs/source/markdown/podman-image.unit.5.md.in @@ -48,7 +48,11 @@ Valid options for `[Image]` are listed below: | TLSVerify=false | --tls-verify=false | | Variant=arm/v7 | --variant=arm/v7 | -@@option quadlet:all-tags +### `AllTags=` + +All tagged images in the repository are pulled. + +This is equivalent to the Podman `--all-tags` option. @@option quadlet:arch @@ -62,7 +66,17 @@ Valid options for `[Image]` are listed below: @@option quadlet:decryption-key -@@option quadlet:global-args +### `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=` @@ -88,9 +102,24 @@ requires setting @@option quadlet:os.pull -@@option quadlet:podman-args +### `PodmanArgs=` -@@option quadlet:policy +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 diff --git a/docs/source/markdown/podman-kube-down.1.md.in b/docs/source/markdown/podman-kube-down.1.md similarity index 96% rename from docs/source/markdown/podman-kube-down.1.md.in rename to docs/source/markdown/podman-kube-down.1.md index 0d523d5fa8..14411e1a12 100644 --- a/docs/source/markdown/podman-kube-down.1.md.in +++ b/docs/source/markdown/podman-kube-down.1.md @@ -16,7 +16,9 @@ specified as `-`, `podman kube down` reads the YAML from stdin. The input can al ## OPTIONS -@@option force.kube-down +#### **--force** + +Tear down the volumes linked to the PersistentVolumeClaims as part --down ## EXAMPLES diff --git a/docs/source/markdown/podman-kube-play.1.md.in b/docs/source/markdown/podman-kube-play.1.md.in index dd9bd3acf7..0d4cbec4a6 100644 --- a/docs/source/markdown/podman-kube-play.1.md.in +++ b/docs/source/markdown/podman-kube-play.1.md.in @@ -213,7 +213,12 @@ Note: You can also override the default isolation type by setting the BUILDAH_ @@option cert-dir -@@option configmap +#### **--configmap**=*path* + +Use Kubernetes configmap YAML at path to provide a source for environment variable values within the containers of the pod. (This option is not available with the remote Podman client) + +Note: The *--configmap* option can be used multiple times or a comma-separated list of paths can be used to pass multiple Kubernetes configmap YAMLs. +The YAML file may be in a multi-doc YAML format. But, it must container only configmaps #### **--context-dir**=*path* diff --git a/docs/source/markdown/podman-kube.unit.5.md.in b/docs/source/markdown/podman-kube.unit.5.md.in index 424276291b..a1176fc230 100644 --- a/docs/source/markdown/podman-kube.unit.5.md.in +++ b/docs/source/markdown/podman-kube.unit.5.md.in @@ -60,12 +60,17 @@ Indicates whether containers will be auto-updated ([podman-auto-update(1)](podma * `name/(local|registry)`: Tells Podman to perform the `local` or `registry` autoupdate on the specified container name. +### `ConfigMap=` -@@option quadlet: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=how` +### `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) @@ -74,9 +79,19 @@ Control how the main PID of the systemd service should exit. The following value The current default value is `none`. -@@option quadlet:global-args +### `GlobalArgs=` -### `KubeDownForce=true` +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. @@ -85,11 +100,22 @@ Equivalent to the Podman `--force` option. @@option quadlet:network -@@option quadlet:podman-args +### `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=yaml` +### `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. @@ -101,7 +127,7 @@ Quadlet will not set it even if `SetWorkingDirectory` is set @@option quadlet:userns.container -### `Yaml=path` +### `Yaml=` The path, absolute or relative to the location of the unit file, to the Kubernetes YAML file to use. diff --git a/docs/source/markdown/podman-network-create.1.md b/docs/source/markdown/podman-network-create.1.md new file mode 100644 index 0000000000..d96319c678 --- /dev/null +++ b/docs/source/markdown/podman-network-create.1.md @@ -0,0 +1,215 @@ +% podman-network-create 1 + +## NAME +podman\-network-create - Create a Podman network + +## SYNOPSIS +**podman network create** [*options*] [*name*] + +## DESCRIPTION +Create a network configuration for use with Podman. By default, Podman creates a bridge connection. +A *Macvlan* connection can be created with the *-d macvlan* option. A parent device for macvlan or +ipvlan can be designated with the *-o parent=``* or *--network-interface=``* option. + +If no options are provided, Podman assigns a free subnet and name for the network. + +Upon completion of creating the network, Podman displays the name of the newly added network. + +## OPTIONS +#### **--disable-dns** + +Disables the DNS plugin for this network which if enabled, can perform container to container name +resolution. It is only supported with the `bridge` driver, for other drivers it is always disabled. + +#### **--dns**=*ip* + +Set network-scoped DNS resolver/nameserver for containers in this network. If not set, the host servers from `/etc/resolv.conf` is used. It can be overwritten on the container level with the `podman run/create --dns` option. This option can be specified multiple times to set more than one IP. + +#### **--driver**, **-d**=*driver* + +Driver to manage the network. Currently `bridge`, `macvlan` and `ipvlan` are supported. Defaults to `bridge`. +As rootless the `macvlan` and `ipvlan` driver have no access to the host network interfaces because rootless networking requires a separate network namespace. + +The netavark backend allows the use of so called *netavark plugins*, see the +[plugin-API.md](https://github.com/containers/netavark/blob/main/plugin-API.md) +documentation in netavark. The binary must be placed in a specified directory +so podman can discover it, this list is set in `netavark_plugin_dirs` in +**[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)** +under the `[network]` section. + +The name of the plugin can then be used as driver to create a network for your plugin. +The list of all supported drivers and plugins can be seen with `podman info --format {{.Plugins.Network}}`. + +Note that the `macvlan` and `ipvlan` drivers do not support port forwarding. Support for port forwarding +with a plugin depends on the implementation of the plugin. + +#### **--gateway**=*ip* + +Define a gateway for the subnet. To provide a gateway address, a +*subnet* option is required. Can be specified multiple times. +The argument order of the **--subnet**, **--gateway** and **--ip-range** options must match. + +#### **--ignore** + +Ignore the create request if a network with the same name already exists instead of failing. +Note, trying to create a network with an existing name and different parameters does not change the configuration of the existing one. + +#### **--interface-name**=*name* + +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=...`. + +#### **--internal** + +Restrict external access of this network when using a `bridge` network. Note when using the CNI backend +DNS will be automatically disabled, see **--disable-dns**. + +When using the `macvlan` or `ipvlan` driver with this option no default route will be added to the container. +Because it bypasses the host network stack no additional restrictions can be set by podman and if a +privileged container is run it can set a default route themselves. If this is a concern then the +container connections should be blocked on your actual network gateway. + +Using the `bridge` driver with this option has the following effects: + - Global IP forwarding sysctls will not be changed in the host network namespace. + - IP forwarding is disabled on the bridge interface instead of setting up a firewall. + - No default route will be added to the container. + +In all cases, aardvark-dns will only resolve container names with this option enabled. +Other queries will be answered with `NXDOMAIN`. + +#### **--ip-range**=*range* + +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. Can be specified multiple times. +The argument order of the **--subnet**, **--gateway** and **--ip-range** options must match. + +#### **--ipam-driver**=*driver* + +Set the ipam driver (IP Address Management Driver) for the network. When unset podman chooses an +ipam driver automatically based on the network driver. + +Valid values are: + + - `dhcp`: IP addresses are assigned from a dhcp server on the network. When using the netavark backend + the `netavark-dhcp-proxy.socket` must be enabled in order to start the dhcp-proxy when a container is + started, for CNI use the `cni-dhcp.socket` unit instead. + - `host-local`: IP addresses are assigned locally. + - `none`: No ip addresses are assigned to the interfaces. + +View the driver in the **podman network inspect** output under the `ipam_options` field. + +#### **--ipv6** + +Enable IPv6 (Dual Stack) networking. If no subnets are given, it allocates an ipv4 and an ipv6 subnet. + +#### **--label**=*label* + +Set metadata for a network (e.g., --label mykey=value). + +#### **--opt**, **-o**=*option* + +Set driver specific options. + +All drivers accept the `mtu`, `metric`, `no_default_route` and options. + +- `mtu`: Sets the Maximum Transmission Unit (MTU) and takes an integer value. +- `metric` Sets the Route Metric for the default route created in every container joined to this network. Accepts a positive integer value. Can only be used with the Netavark network backend. +- `no_default_route`: If set to 1, Podman will not automatically add a default route to subnets. Routes can still be added +manually by creating a custom route using `--route`. + +Additionally the `bridge` driver supports the following options: + +- `vlan`: This option assign VLAN tag and enables vlan\_filtering. Defaults to none. +- `isolate`: This option isolates networks by blocking traffic between those that have this option enabled. +- `com.docker.network.bridge.name`: This option assigns the given name to the created Linux Bridge +- `com.docker.network.driver.mtu`: Sets the Maximum Transmission Unit (MTU) and takes an integer value. +- `vrf`: This option assigns a VRF to the bridge interface. It accepts the name of the VRF and defaults to none. Can only be used with the Netavark network backend. +- `mode`: This option sets the specified bridge mode on the interface. Defaults to `managed`. Supported values: + - `managed`: Podman creates and deletes the bridge and changes sysctls of it. It adds firewall rules to masquerade outgoing traffic, as well as setup port forwarding for incoming traffic using DNAT. + - `unmanaged`: Podman uses an existing bridge. It must exist by the time you want to start a container which uses the network. There will be no NAT or port forwarding, even if such options were passed while creating the container. + +The `macvlan` and `ipvlan` driver support the following options: + +- `parent`: The host device which is used for the macvlan interface. Defaults to the default route interface. +- `mode`: This option sets the specified ip/macvlan mode on the interface. + - Supported values for `macvlan` are `bridge`, `private`, `vepa`, `passthru`. Defaults to `bridge`. + - Supported values for `ipvlan` are `l2`, `l3`, `l3s`. Defaults to `l2`. + +Additionally the `macvlan` driver supports the `bclim` option: + +- `bclim`: Set the threshold for broadcast queueing. Must be a 32 bit integer. Setting this value to `-1` disables broadcast queueing altogether. + +#### **--route**=*route* + +A static route in the format `,,`. This route will be added to every container in this network. Only available with the netavark backend. It can be specified multiple times if more than one static route is desired. + +#### **--subnet**=*subnet* + +The subnet in CIDR notation. Can be specified multiple times to allocate more than one subnet for this network. +The argument order of the **--subnet**, **--gateway** and **--ip-range** options must match. +This is useful to set a static ipv4 and ipv6 subnet. + +## EXAMPLES + +Create a network with no options. +``` +$ podman network create +podman2 +``` + +Create a network named *newnet* that uses *192.5.0.0/16* for its subnet. +``` +$ podman network create --subnet 192.5.0.0/16 newnet +newnet +``` + +Create an IPv6 network named *newnetv6* with a subnet of *2001:db8::/64*. +``` +$ podman network create --subnet 2001:db8::/64 --ipv6 newnetv6 +newnetv6 +``` + +Create a network named *newnet* that uses *192.168.33.0/24* and defines a gateway as *192.168.33.3*. +``` +$ podman network create --subnet 192.168.33.0/24 --gateway 192.168.33.3 newnet +newnet +``` + +Create a network that uses a *192.168.55.0/24* subnet and has an IP address range of *192.168.55.129 - 192.168.55.254*. +``` +$ podman network create --subnet 192.168.55.0/24 --ip-range 192.168.55.128/25 +podman5 +``` + +Create a network with a static ipv4 and ipv6 subnet and set a gateway. +``` +$ podman network create --subnet 192.168.55.0/24 --gateway 192.168.55.3 --subnet fd52:2a5a:747e:3acd::/64 --gateway fd52:2a5a:747e:3acd::10 +podman4 +``` + +Create a network with a static subnet and a static route. +``` +$ podman network create --subnet 192.168.33.0/24 --route 10.1.0.0/24,192.168.33.10 newnet +``` + +Create a network with a static subnet and a static route without a default +route. +``` +$ podman network create --subnet 192.168.33.0/24 --route 10.1.0.0/24,192.168.33.10 --opt no_default_route=1 newnet +``` + +Create a Macvlan based network using the host interface eth0. Macvlan networks can only be used as root. +``` +$ sudo podman network create -d macvlan -o parent=eth0 --subnet 192.5.0.0/16 newnet +newnet +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-network(1)](podman-network.1.md)**, **[podman-network-inspect(1)](podman-network-inspect.1.md)**, **[podman-network-ls(1)](podman-network-ls.1.md)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)** + +## HISTORY +August 2021, Updated with the new network format by Paul Holzinger + +August 2019, Originally compiled by Brent Baude diff --git a/docs/source/markdown/podman-network-create.1.md.in b/docs/source/markdown/podman-network-create.1.md.in deleted file mode 100644 index 42fa03627b..0000000000 --- a/docs/source/markdown/podman-network-create.1.md.in +++ /dev/null @@ -1,114 +0,0 @@ -% podman-network-create 1 - -## NAME -podman\-network-create - Create a Podman network - -## SYNOPSIS -**podman network create** [*options*] [*name*] - -## DESCRIPTION -Create a network configuration for use with Podman. By default, Podman creates a bridge connection. -A *Macvlan* connection can be created with the *-d macvlan* option. A parent device for macvlan or -ipvlan can be designated with the *-o parent=``* or *--network-interface=``* option. - -If no options are provided, Podman assigns a free subnet and name for the network. - -Upon completion of creating the network, Podman displays the name of the newly added network. - -## OPTIONS - -@@option disable-dns - -@@option dns - -@@option driver - -@@option gateway - -#### **--ignore** - -Ignore the create request if a network with the same name already exists instead of failing. -Note, trying to create a network with an existing name and different parameters does not change the configuration of the existing one. - -@@option interface-name - -@@option internal - -@@option ip-range - -@@option ipam-driver - -@@option ipv6 - -@@option label.network - -@@option opt - -#### **--route**=*route* - -A static route in the format `,,`. This route will be added to every container in this network. Only available with the netavark backend. It can be specified multiple times if more than one static route is desired. - -@@option subnet - -## EXAMPLES - -Create a network with no options. -``` -$ podman network create -podman2 -``` - -Create a network named *newnet* that uses *192.5.0.0/16* for its subnet. -``` -$ podman network create --subnet 192.5.0.0/16 newnet -newnet -``` - -Create an IPv6 network named *newnetv6* with a subnet of *2001:db8::/64*. -``` -$ podman network create --subnet 2001:db8::/64 --ipv6 newnetv6 -newnetv6 -``` - -Create a network named *newnet* that uses *192.168.33.0/24* and defines a gateway as *192.168.33.3*. -``` -$ podman network create --subnet 192.168.33.0/24 --gateway 192.168.33.3 newnet -newnet -``` - -Create a network that uses a *192.168.55.0/24* subnet and has an IP address range of *192.168.55.129 - 192.168.55.254*. -``` -$ podman network create --subnet 192.168.55.0/24 --ip-range 192.168.55.128/25 -podman5 -``` - -Create a network with a static ipv4 and ipv6 subnet and set a gateway. -``` -$ podman network create --subnet 192.168.55.0/24 --gateway 192.168.55.3 --subnet fd52:2a5a:747e:3acd::/64 --gateway fd52:2a5a:747e:3acd::10 -podman4 -``` - -Create a network with a static subnet and a static route. -``` -$ podman network create --subnet 192.168.33.0/24 --route 10.1.0.0/24,192.168.33.10 newnet -``` - -Create a network with a static subnet and a static route without a default -route. -``` -$ podman network create --subnet 192.168.33.0/24 --route 10.1.0.0/24,192.168.33.10 --opt no_default_route=1 newnet -``` - -Create a Macvlan based network using the host interface eth0. Macvlan networks can only be used as root. -``` -$ sudo podman network create -d macvlan -o parent=eth0 --subnet 192.5.0.0/16 newnet -newnet -``` - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-network(1)](podman-network.1.md)**, **[podman-network-inspect(1)](podman-network-inspect.1.md)**, **[podman-network-ls(1)](podman-network-ls.1.md)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)** - -## HISTORY -August 2021, Updated with the new network format by Paul Holzinger - -August 2019, Originally compiled by Brent Baude diff --git a/docs/source/markdown/podman-network.unit.5.md.in b/docs/source/markdown/podman-network.unit.5.md.in index 806f0f2f50..844130c5f7 100644 --- a/docs/source/markdown/podman-network.unit.5.md.in +++ b/docs/source/markdown/podman-network.unit.5.md.in @@ -19,9 +19,7 @@ a network file named `$NAME.network`, the generated Podman network is called `sy 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 by default - -this can be overridden by the `NetworkDeleteOnStop=true` option. - +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. @@ -52,47 +50,124 @@ Valid options for `[Network]` are listed below: | 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 -@@option quadlet:disable-dns +### `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 -@@option quadlet:driver +### `Driver=` (defaults to `bridge`) -@@option quadlet:gateway +Driver to manage the network. Currently `bridge`, `macvlan` and `ipvlan` are supported. -@@option quadlet:global-args +This is equivalent to the Podman `--driver` option -@@option quadlet:interface-name +### `Gateway=` -@@option quadlet:internal +Define a gateway for the subnet. If you want to provide a gateway address, you must also provide a subnet option. -@@option quadlet:ipam-driver +This is equivalent to the Podman `--gateway` option -@@option quadlet:ip-range +This key can be listed multiple times. -@@option quadlet:ipv6 +### `GlobalArgs=` -@@option quadlet:label.network +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. -### `NetworkDeleteOnStop=true` (defaults to `false`) +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=foo` +### `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. -@@option quadlet:opt +### `Options=` -@@option quadlet:podman-args +Set driver specific options. -@@option quadlet:subnet +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 diff --git a/docs/source/markdown/podman-pod.unit.5.md.in b/docs/source/markdown/podman-pod.unit.5.md.in index 5eaf2af3fa..e09087dd38 100644 --- a/docs/source/markdown/podman-pod.unit.5.md.in +++ b/docs/source/markdown/podman-pod.unit.5.md.in @@ -62,7 +62,7 @@ Supported keys in the `[Pod]` section are: @@option quadlet:dns-search.container -### `ExitPolicy=stop` +### `ExitPolicy=` Set the exit policy of the pod when the last container exits. Default for quadlets is **stop**. @@ -70,8 +70,17 @@ To keep the pod active, set `ExitPolicy=continue`. @@option quadlet:gidmap.container -@@option quadlet:global-args +### `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 @@ -85,9 +94,19 @@ To keep the pod active, set `ExitPolicy=continue`. @@option quadlet:network-alias -@@option quadlet:podman-args +### `PodmanArgs=` -### `PodName=name` +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, @@ -98,7 +117,7 @@ So, if PodName is set, it must not conflict with any container. @@option quadlet:publish -### `ServiceName=name` +### `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. diff --git a/docs/source/markdown/podman-pull.1.md.in b/docs/source/markdown/podman-pull.1.md.in index 6c368eede2..71da30f788 100644 --- a/docs/source/markdown/podman-pull.1.md.in +++ b/docs/source/markdown/podman-pull.1.md.in @@ -43,8 +43,11 @@ $ podman pull oci-archive:/tmp/myimage ``` ## OPTIONS +#### **--all-tags**, **-a** -@@option all-tags +All tagged images in the repository are pulled. + +*IMPORTANT: When using the all-tags flag, Podman does not iterate over the search registries in the **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)** but always uses docker.io for unqualified image names.* @@option arch @@ -66,8 +69,14 @@ Print the usage statement. @@option platform -@@option policy +#### **--policy** +Pull image policy. The default is **always**. + +- `always`: Always pull the image and throw an error if the pull fails. +- `missing`: Only pull the image if it could not be found in the local containers storage. Throw an error if no image could be found and the pull fails. +- `never`: Never pull the image; only use the local version. Throw an error if the image is not present locally. +- `newer`: Pull if the image on the registry is newer than the one in the local containers storage. An image is considered to be newer when the digests are different. Comparing the time stamps is prone to errors. Pull errors are suppressed if a local image was found. #### **--quiet**, **-q** diff --git a/docs/source/markdown/podman-volume.unit.5.md.in b/docs/source/markdown/podman-volume.unit.5.md.in index 807a568b38..036a92d26f 100644 --- a/docs/source/markdown/podman-volume.unit.5.md.in +++ b/docs/source/markdown/podman-volume.unit.5.md.in @@ -79,8 +79,17 @@ Specify the volume driver name. When set to `image`, the `Image` key must also b This is equivalent to the Podman `--driver` option. -@@option quadlet:global-args +### `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=` @@ -111,7 +120,18 @@ This key can be listed multiple times. The mount options to use for a filesystem as used by the **mount(8)** command `-o` option. -@@option quadlet:podman-args +### `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=` From bb422c83727757bb7beeb3f10a68a08ffb620311 Mon Sep 17 00:00:00 2001 From: Paul Holzinger Date: Thu, 11 Sep 2025 19:00:17 +0200 Subject: [PATCH 3/4] Revert "Change the syntax to not depend on jinja2." This reverts commit 9de737bf29eba1606c1aff560e2cbba4fa1576e4. Signed-off-by: Paul Holzinger --- docs/source/markdown/.gitignore | 1 + .../markdown/links/podman-systemd.unit.5 | 1 - docs/source/markdown/options/README.md | 8 +- docs/source/markdown/options/add-host.md | 6 +- .../markdown/options/annotation.container.md | 6 +- .../markdown/options/annotation.image.md | 6 +- docs/source/markdown/options/arch.md | 6 +- docs/source/markdown/options/authfile.md | 6 +- docs/source/markdown/options/cap-add.image.md | 6 +- docs/source/markdown/options/cap-add.md | 6 +- docs/source/markdown/options/cap-drop.md | 6 +- docs/source/markdown/options/cert-dir.md | 6 +- docs/source/markdown/options/cgroups.md | 12 +- docs/source/markdown/options/creds.md | 6 +- .../source/markdown/options/decryption-key.md | 6 +- docs/source/markdown/options/device.md | 6 +- .../markdown/options/dns-option.container.md | 10 +- .../markdown/options/dns-option.image.md | 6 +- .../markdown/options/dns-search.container.md | 14 +- .../markdown/options/dns-search.image.md | 6 +- docs/source/markdown/options/dns.md | 8 +- docs/source/markdown/options/entrypoint.md | 8 +- docs/source/markdown/options/env-file.md | 6 +- docs/source/markdown/options/env-host.md | 6 +- docs/source/markdown/options/env.image.md | 12 +- docs/source/markdown/options/env.md | 8 +- docs/source/markdown/options/expose.md | 10 +- docs/source/markdown/options/file.md | 14 +- docs/source/markdown/options/force-rm.md | 8 +- .../markdown/options/gidmap.container.md | 16 +-- docs/source/markdown/options/group-add.md | 6 +- docs/source/markdown/options/health-cmd.md | 6 +- .../markdown/options/health-interval.md | 6 +- .../options/health-log-destination.md | 6 +- .../markdown/options/health-max-log-count.md | 6 +- .../markdown/options/health-max-log-size.md | 6 +- .../markdown/options/health-on-failure.md | 6 +- .../source/markdown/options/health-retries.md | 6 +- .../markdown/options/health-start-period.md | 12 +- .../markdown/options/health-startup-cmd.md | 8 +- .../options/health-startup-interval.md | 6 +- .../options/health-startup-retries.md | 6 +- .../options/health-startup-success.md | 6 +- .../options/health-startup-timeout.md | 6 +- .../source/markdown/options/health-timeout.md | 6 +- .../markdown/options/hostname.container.md | 12 +- docs/source/markdown/options/http-proxy.md | 6 +- docs/source/markdown/options/init.md | 8 +- docs/source/markdown/options/ip.md | 12 +- docs/source/markdown/options/ip6.md | 12 +- docs/source/markdown/options/label.image.md | 6 +- docs/source/markdown/options/label.md | 6 +- docs/source/markdown/options/log-driver.md | 6 +- docs/source/markdown/options/log-opt.md | 12 +- docs/source/markdown/options/memory.md | 10 +- docs/source/markdown/options/module.md | 6 +- docs/source/markdown/options/mount.md | 10 +- .../source/markdown/options/name.container.md | 10 +- docs/source/markdown/options/network-alias.md | 6 +- docs/source/markdown/options/network.image.md | 10 +- docs/source/markdown/options/network.md | 10 +- docs/source/markdown/options/os.pull.md | 6 +- docs/source/markdown/options/pids-limit.md | 6 +- docs/source/markdown/options/publish.md | 6 +- docs/source/markdown/options/pull.image.md | 6 +- docs/source/markdown/options/pull.md | 6 +- .../markdown/options/read-only-tmpfs.md | 16 +-- docs/source/markdown/options/read-only.md | 8 +- docs/source/markdown/options/retry-delay.md | 6 +- docs/source/markdown/options/retry.md | 6 +- docs/source/markdown/options/rootfs.md | 10 +- docs/source/markdown/options/secret.image.md | 6 +- docs/source/markdown/options/secret.md | 6 +- docs/source/markdown/options/shm-size.md | 6 +- docs/source/markdown/options/stop-signal.md | 6 +- docs/source/markdown/options/stop-timeout.md | 10 +- docs/source/markdown/options/subgidname.md | 9 +- docs/source/markdown/options/subuidname.md | 8 +- docs/source/markdown/options/sysctl.md | 7 +- docs/source/markdown/options/tag.md | 8 +- docs/source/markdown/options/target.md | 6 +- docs/source/markdown/options/tls-verify.md | 6 +- docs/source/markdown/options/tmpfs.md | 6 +- docs/source/markdown/options/tz.md | 8 +- .../markdown/options/uidmap.container.md | 32 ++--- docs/source/markdown/options/uidmap.pod.md | 8 +- docs/source/markdown/options/ulimit.md | 6 +- docs/source/markdown/options/user.md | 6 +- .../markdown/options/userns.container.md | 10 +- docs/source/markdown/options/userns.pod.md | 10 +- .../markdown/options/variant.container.md | 6 +- docs/source/markdown/options/volume.image.md | 10 +- docs/source/markdown/options/volume.md | 10 +- docs/source/markdown/options/workdir.md | 8 +- .../source/markdown/podman-build.unit.5.md.in | 21 ++- .../markdown/podman-container.unit.5.md.in | 20 ++- .../source/markdown/podman-image.unit.5.md.in | 40 +++++- docs/source/markdown/podman-kube.unit.5.md.in | 18 ++- .../markdown/podman-network.unit.5.md.in | 17 +++ docs/source/markdown/podman-pod.unit.5.md.in | 22 ++- .../markdown/podman-quadlet-basic-usage.7.md | 2 +- docs/source/markdown/podman-quadlet.7.md | 34 +---- hack/markdown-preprocess | 102 +------------ hack/xref-quadlet-docs | 134 ++++++++---------- rpm/podman.spec | 1 + 105 files changed, 576 insertions(+), 575 deletions(-) delete mode 100644 docs/source/markdown/links/podman-systemd.unit.5 diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore index a48ec92172..3ab040378b 100644 --- a/docs/source/markdown/.gitignore +++ b/docs/source/markdown/.gitignore @@ -76,3 +76,4 @@ 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/podman-systemd.unit.5 b/docs/source/markdown/links/podman-systemd.unit.5 deleted file mode 100644 index 8b26a55dfd..0000000000 --- a/docs/source/markdown/links/podman-systemd.unit.5 +++ /dev/null @@ -1 +0,0 @@ -.so man7/podman-quadlet.7 diff --git a/docs/source/markdown/options/README.md b/docs/source/markdown/options/README.md index f409afc756..cb1844f7f1 100644 --- a/docs/source/markdown/options/README.md +++ b/docs/source/markdown/options/README.md @@ -35,17 +35,17 @@ 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 >> + {% if is_quadlet %} ### `DNS=` - << else >> + {% else %} #### **--dns**=*ipaddr* - << endif >> + {% endif %} ``` It is also possible to use in-line condition: ``` - << '**DNS=.**' if is_quadlet else '**--dns**' >> + {{{ '**DNS=.**' if is_quadlet else '**--dns**' }}} ``` Following variables are available for Jinja2 Templates: diff --git a/docs/source/markdown/options/add-host.md b/docs/source/markdown/options/add-host.md index 3a14116899..478e050418 100644 --- a/docs/source/markdown/options/add-host.md +++ b/docs/source/markdown/options/add-host.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `AddHost=hostname[;hostname[;...]]:ip` -<< else >> +{% else %} #### **--add-host**=*hostname[;hostname[;...]]*:*ip* -<< endif >> +{% 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 c2fc50de11..edff7c3fab 100644 --- a/docs/source/markdown/options/annotation.container.md +++ b/docs/source/markdown/options/annotation.container.md @@ -2,10 +2,10 @@ ####> 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 >> +{% if is_quadlet %} ### `Annotation=key=value` -<< else >> +{% else %} #### **--annotation**=*key=value* -<< endif >> +{% 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 b887ee3242..1417dcc054 100644 --- a/docs/source/markdown/options/annotation.image.md +++ b/docs/source/markdown/options/annotation.image.md @@ -2,11 +2,11 @@ ####> podman build, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. -<< if is_quadlet >> +{% if is_quadlet %} ### `Annotation=annotation=value` -<< else >> +{% else %} #### **--annotation**=*annotation=value* -<< endif >> +{% 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 d25dd0253e..20806f4b17 100644 --- a/docs/source/markdown/options/arch.md +++ b/docs/source/markdown/options/arch.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `Arch=ARCH` -<< else >> +{% else %} #### **--arch**=*ARCH* -<< endif >> +{% 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 101b17fcb1..6999d0c98e 100644 --- a/docs/source/markdown/options/authfile.md +++ b/docs/source/markdown/options/authfile.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `AuthFile=path` -<< else >> +{% else %} #### **--authfile**=*path* -<< endif >> +{% 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 007a95ed14..7696578f12 100644 --- a/docs/source/markdown/options/cap-add.image.md +++ b/docs/source/markdown/options/cap-add.image.md @@ -2,11 +2,11 @@ ####> podman build, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. -<< if is_quadlet >> +{% if is_quadlet %} ### `AddCapability=CAP_xxx` -<< else >> +{% else %} #### **--cap-add**=*CAP\_xxx* -<< endif >> +{% endif %} When executing RUN instructions, run the command specified in the instruction diff --git a/docs/source/markdown/options/cap-add.md b/docs/source/markdown/options/cap-add.md index b91a669297..ada47189f8 100644 --- a/docs/source/markdown/options/cap-add.md +++ b/docs/source/markdown/options/cap-add.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `AddCapability=capability` -<< else >> +{% else %} #### **--cap-add**=*capability* -<< endif >> +{% endif %} Add Linux capabilities. diff --git a/docs/source/markdown/options/cap-drop.md b/docs/source/markdown/options/cap-drop.md index 99ce9aaa36..c9333fae56 100644 --- a/docs/source/markdown/options/cap-drop.md +++ b/docs/source/markdown/options/cap-drop.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `DropCapability=capability` -<< else >> +{% else %} #### **--cap-drop**=*capability* -<< endif >> +{% endif %} Drop these capabilities from the default podman capability set, or `all` to drop all capabilities. diff --git a/docs/source/markdown/options/cert-dir.md b/docs/source/markdown/options/cert-dir.md index befefa7ab3..b32460a8ca 100644 --- a/docs/source/markdown/options/cert-dir.md +++ b/docs/source/markdown/options/cert-dir.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `CertDir=path` -<< else >> +{% else %} #### **--cert-dir**=*path* -<< endif >> +{% 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 bdcbf94e12..7c557fc3be 100644 --- a/docs/source/markdown/options/cgroups.md +++ b/docs/source/markdown/options/cgroups.md @@ -2,23 +2,23 @@ ####> 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 >> +{% if is_quadlet %} ### `CgroupsMode=how` -<< else >> +{% else %} #### **--cgroups**=*how* -<< endif >> +{% endif %} Determines whether the container creates CGroups. -<< if is_quadlet >> +{% 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 >> +{% else %} Default is **enabled**. -<< endif >> +{% 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 740af7d40e..747cb294ed 100644 --- a/docs/source/markdown/options/creds.md +++ b/docs/source/markdown/options/creds.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `Creds=[username[:password]]` -<< else >> +{% else %} #### **--creds**=*[username[:password]]* -<< endif >> +{% 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 589b7ea4b1..2b98acf8d9 100644 --- a/docs/source/markdown/options/decryption-key.md +++ b/docs/source/markdown/options/decryption-key.md @@ -2,10 +2,10 @@ ####> 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 >> +{% if is_quadlet %} ### `DecryptionKey=key[:passphrase]` -<< else >> +{% else %} #### **--decryption-key**=*key[:passphrase]* -<< endif >> +{% 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 3dcad9d976..d13b4b3ca3 100644 --- a/docs/source/markdown/options/device.md +++ b/docs/source/markdown/options/device.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `AddDevice=host-device[:container-device][:permissions]` -<< else >> +{% else %} #### **--device**=*host-device[:container-device][:permissions]* -<< endif >> +{% endif %} Add a host device to the <>. The format of this is `HOST-DEVICE[:CONTAINER-DEVICE][:PERMISSIONS]`, where `HOST-DEVICE` is the path of diff --git a/docs/source/markdown/options/dns-option.container.md b/docs/source/markdown/options/dns-option.container.md index c3847301d5..430959b7f2 100644 --- a/docs/source/markdown/options/dns-option.container.md +++ b/docs/source/markdown/options/dns-option.container.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `DNSOption=option` -<< else >> +{% else %} #### **--dns-option**=*option* -<< endif >> +{% endif %} -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_. +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 ae3b7a6572..80663a3d8e 100644 --- a/docs/source/markdown/options/dns-option.image.md +++ b/docs/source/markdown/options/dns-option.image.md @@ -2,10 +2,10 @@ ####> 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 >> +{% if is_quadlet %} ### `DNSOption=option` -<< else >> +{% else %} #### **--dns-option**=*option* -<< endif >> +{% 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 75c1e9f5f9..6f26aca056 100644 --- a/docs/source/markdown/options/dns-search.container.md +++ b/docs/source/markdown/options/dns-search.container.md @@ -1,13 +1,13 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, podman-pod.unit.5.md.in, 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 >> +{% if is_quadlet %} ### `DNSSearch=domain` -<< else >> +{% else %} #### **--dns-search**=*domain* -<< endif >> +{% endif %} -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. +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 f1ccefe59d..fd7f28bcd1 100644 --- a/docs/source/markdown/options/dns-search.image.md +++ b/docs/source/markdown/options/dns-search.image.md @@ -2,10 +2,10 @@ ####> 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 >> +{% if is_quadlet %} ### `DNSSearch=domain` -<< else >> +{% else %} #### **--dns-search**=*domain* -<< endif >> +{% 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 399a715a4a..01e11011e7 100644 --- a/docs/source/markdown/options/dns.md +++ b/docs/source/markdown/options/dns.md @@ -2,18 +2,18 @@ ####> 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 >> +{% if is_quadlet %} ### `DNS=ipaddr` -<< else >> +{% else %} #### **--dns**=*ipaddr* -<< endif >> +{% 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=.**' if is_quadlet else '**--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 5be09ff10f..e45ab49fc4 100644 --- a/docs/source/markdown/options/entrypoint.md +++ b/docs/source/markdown/options/entrypoint.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `Entrypoint="command"` -<< else >> +{% else %} #### **--entrypoint**=*"command"* | *'["command", "arg1", ...]'* -<< endif >> +{% endif %} Override the default ENTRYPOINT from the image. @@ -16,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=**' if is_quadlet else '**--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 adec9ba9e1..8d0157aa06 100644 --- a/docs/source/markdown/options/env-file.md +++ b/docs/source/markdown/options/env-file.md @@ -2,10 +2,10 @@ ####> 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 >> +{% if is_quadlet %} ### `EnvironmentFile=file` -<< else >> +{% else %} #### **--env-file**=*file* -<< endif >> +{% 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 9b48379130..2e52277f52 100644 --- a/docs/source/markdown/options/env-host.md +++ b/docs/source/markdown/options/env-host.md @@ -2,10 +2,10 @@ ####> 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 >> +{% if is_quadlet %} ### `EnvironmentHost=` -<< else >> +{% else %} #### **--env-host** -<< endif >> +{% 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 73c4467a9d..b4dfad23af 100644 --- a/docs/source/markdown/options/env.image.md +++ b/docs/source/markdown/options/env.image.md @@ -1,17 +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 >> +{% if is_quadlet %} ### `Env=env[=value]` -<< else >> +{% else %} #### **--env**=*env[=value]* -<< endif >> +{% 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 >> +{% if not is_quadlet %} To remove an environment variable from the built image, use the `--unsetenv` option. -<< endif >> +{% endif %} diff --git a/docs/source/markdown/options/env.md b/docs/source/markdown/options/env.md index 297ef3ed5a..74fb020a53 100644 --- a/docs/source/markdown/options/env.md +++ b/docs/source/markdown/options/env.md @@ -1,12 +1,12 @@ ####> This option file is used in: -####> podman podman-build.unit.5.md.in, podman-container.unit.5.md.in, 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 >> +{% if is_quadlet %} ### `Environment=env` -<< else >> +{% else %} #### **--env**, **-e**=*env* -<< endif >> +{% endif %} Set environment variables. diff --git a/docs/source/markdown/options/expose.md b/docs/source/markdown/options/expose.md index f896a8baac..98bae64ad1 100644 --- a/docs/source/markdown/options/expose.md +++ b/docs/source/markdown/options/expose.md @@ -2,15 +2,15 @@ ####> 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 >> +{% if is_quadlet %} ### `ExposeHostPort=port[/protocol]` -<< else >> +{% else %} #### **--expose**=*port[/protocol]* -<< endif >> +{% endif %} -Expose a port or a range of ports (e.g. << '**Expose=3300-3310**' if is_quadlet else '**--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 << '**PublishPort=**' if is_quadlet else '**-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 e02b79b16f..2b589417bc 100644 --- a/docs/source/markdown/options/file.md +++ b/docs/source/markdown/options/file.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `File=Containerfile` -<< else >> +{% else %} #### **--file**, **-f**=*Containerfile* -<< endif >> +{% endif %} Specifies a Containerfile which contains instructions for building the image, @@ -14,18 +14,18 @@ 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 >> +{% 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 >> +{% 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 >> +{% endif %} -Specifying the option << 'File=-' if is_quadlet else '`-f -`' >> causes +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 c1e43c7b0a..04a8707499 100644 --- a/docs/source/markdown/options/force-rm.md +++ b/docs/source/markdown/options/force-rm.md @@ -2,10 +2,10 @@ ####> 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 >> +{% if is_quadlet %} +### `ForceRm=` +{% else %} #### **--force-rm** -<< endif >> +{% 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 ad9297bf09..5b9f94691b 100644 --- a/docs/source/markdown/options/gidmap.container.md +++ b/docs/source/markdown/options/gidmap.container.md @@ -2,18 +2,18 @@ ####> 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 >> +{% if is_quadlet %} ### `GIDMap=[flags]container_uid:from_uid[:amount]` -<< else >> +{% else %} #### **--gidmap**=*[flags]container_uid:from_uid[:amount]* -<< endif >> +{% endif %} -Run 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 +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=**' if is_quadlet else '**--gidmap**' >> option cannot be -called in conjunction with the << '**Pod=**' if is_quadlet else '**--pod**' >> option as +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 a262c1f9f1..8e33c86bda 100644 --- a/docs/source/markdown/options/group-add.md +++ b/docs/source/markdown/options/group-add.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `GroupAdd=group | keep-groups` -<< else >> +{% else %} #### **--group-add**=*group* | *keep-groups* -<< endif >> +{% 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 d97ad6ee07..189274c5f4 100644 --- a/docs/source/markdown/options/health-cmd.md +++ b/docs/source/markdown/options/health-cmd.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `HealthCmd="command"` -<< else >> +{% else %} #### **--health-cmd**=*"command"* | *'["command", "arg1", ...]'* -<< endif >> +{% 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 8e2b04f3f7..71bcce75ff 100644 --- a/docs/source/markdown/options/health-interval.md +++ b/docs/source/markdown/options/health-interval.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `HealthInterval=interval` -<< else >> +{% else %} #### **--health-interval**=*interval* -<< endif >> +{% 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 e1b4e1d591..bda61b3046 100644 --- a/docs/source/markdown/options/health-log-destination.md +++ b/docs/source/markdown/options/health-log-destination.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `HealthLogDestination=directory_path` -<< else >> +{% else %} #### **--health-log-destination**=*directory_path* -<< endif >> +{% 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 d8cd5d1ede..900a4649a4 100644 --- a/docs/source/markdown/options/health-max-log-count.md +++ b/docs/source/markdown/options/health-max-log-count.md @@ -2,10 +2,10 @@ ####> 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 >> +{% if is_quadlet %} ### `HealthMaxLogCount=number` -<< else >> +{% else %} #### **--health-max-log-count**=*number of stored logs* -<< endif >> +{% 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 5403ad5c6c..3ada0d76e9 100644 --- a/docs/source/markdown/options/health-max-log-size.md +++ b/docs/source/markdown/options/health-max-log-size.md @@ -2,10 +2,10 @@ ####> 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 >> +{% if is_quadlet %} ### `HealthMaxLogSize=size` -<< else >> +{% else %} #### **--health-max-log-size**=*size of stored logs* -<< endif >> +{% 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 7936537741..cf82c0668b 100644 --- a/docs/source/markdown/options/health-on-failure.md +++ b/docs/source/markdown/options/health-on-failure.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `HealthOnFailure=action` -<< else >> +{% else %} #### **--health-on-failure**=*action* -<< endif >> +{% 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 1518965760..07e23351f6 100644 --- a/docs/source/markdown/options/health-retries.md +++ b/docs/source/markdown/options/health-retries.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `HealthRetries=retries` -<< else >> +{% else %} #### **--health-retries**=*retries* -<< endif >> +{% 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 a5e587c535..9a6a61492d 100644 --- a/docs/source/markdown/options/health-start-period.md +++ b/docs/source/markdown/options/health-start-period.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `HealthStartPeriod=period` -<< else >> +{% else %} #### **--health-start-period**=*period* -<< endif >> +{% 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**. @@ -14,10 +14,10 @@ The initialization time needed for a container to bootstrap. The value can be ex 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 << '`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`' >> +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`' >>. +{{{ '`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 de81cd6264..20e3debdd8 100644 --- a/docs/source/markdown/options/health-startup-cmd.md +++ b/docs/source/markdown/options/health-startup-cmd.md @@ -2,15 +2,15 @@ ####> 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 >> +{% if is_quadlet %} ### `HealthStartupCmd="command"` -<< else >> +{% else %} #### **--health-startup-cmd**=*"command"* | *'["command", "arg1", ...]'* -<< endif >> +{% 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 -<< '`HealthCmd=`' if is_quadlet else '`--health-cmd`' >> option) is also set. +{{{ '`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 9f0f31cc8f..0149573cbc 100644 --- a/docs/source/markdown/options/health-startup-interval.md +++ b/docs/source/markdown/options/health-startup-interval.md @@ -2,10 +2,10 @@ ####> 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 >> +{% if is_quadlet %} ### `HealthStartupInterval=interval` -<< else >> +{% else %} #### **--health-startup-interval**=*interval* -<< endif >> +{% 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 c35be5c286..30401b87aa 100644 --- a/docs/source/markdown/options/health-startup-retries.md +++ b/docs/source/markdown/options/health-startup-retries.md @@ -2,10 +2,10 @@ ####> 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 >> +{% if is_quadlet %} ### `HealthStartupRetries=retries` -<< else >> +{% else %} #### **--health-startup-retries**=*retries* -<< endif >> +{% 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 54995fa791..9577cf73b6 100644 --- a/docs/source/markdown/options/health-startup-success.md +++ b/docs/source/markdown/options/health-startup-success.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `HealthStartupSuccess=retries` -<< else >> +{% else %} #### **--health-startup-success**=*retries* -<< endif >> +{% 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 9fdf007c83..671ecf5db5 100644 --- a/docs/source/markdown/options/health-startup-timeout.md +++ b/docs/source/markdown/options/health-startup-timeout.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `HealthStartupTimeout=timeout` -<< else >> +{% else %} #### **--health-startup-timeout**=*timeout* -<< endif >> +{% 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 5ceae0fe84..8bbe0c9b48 100644 --- a/docs/source/markdown/options/health-timeout.md +++ b/docs/source/markdown/options/health-timeout.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `HealthTimeout=timeout` -<< else >> +{% else %} #### **--health-timeout**=*timeout* -<< endif >> +{% 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 f986049b16..4c1c108b9b 100644 --- a/docs/source/markdown/options/hostname.container.md +++ b/docs/source/markdown/options/hostname.container.md @@ -1,17 +1,17 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, podman-pod.unit.5.md.in, 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 >> +{% if is_quadlet %} ### `HostName=name` -<< else >> +{% else %} #### **--hostname**, **-h**=*name* -<< endif >> +{% 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=`' if is_quadlet else '`--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 -<< '**AddHost=**' if is_quadlet else '**--add-host**' >> option). +{{{ '**AddHost=**' if is_quadlet else '**--add-host**' }}} option). diff --git a/docs/source/markdown/options/http-proxy.md b/docs/source/markdown/options/http-proxy.md index fec9e520a3..ac15af4382 100644 --- a/docs/source/markdown/options/http-proxy.md +++ b/docs/source/markdown/options/http-proxy.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman build, podman-container.unit.5.md.in, create, farm build, run +####> podman build, create, farm build, run ####> If file is edited, make sure the changes ####> are applicable to all of those. -<< if is_quadlet >> -### `HttpProxy=` -<< else >> #### **--http-proxy** -<< endif>> By default proxy environment variables are passed into the container if set for the Podman process. This can be disabled by setting the value to **false**. diff --git a/docs/source/markdown/options/init.md b/docs/source/markdown/options/init.md index c0ba3fbec6..c8e8dc8da1 100644 --- a/docs/source/markdown/options/init.md +++ b/docs/source/markdown/options/init.md @@ -2,11 +2,11 @@ ####> 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 >> -### `RunInit=` -<< else >> +{% if is_quadlet %} +### `Init=` +{% else %} #### **--init** -<< endif >> +{% 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 efbc5217d8..a5997dd0c3 100644 --- a/docs/source/markdown/options/ip.md +++ b/docs/source/markdown/options/ip.md @@ -2,19 +2,19 @@ ####> 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 >> +{% if is_quadlet %} ### `IP=ipv4` -<< else >> +{% else %} #### **--ip**=*ipv4* -<< endif >> +{% 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**' if is_quadlet else '**--network=network-name**' >> is used at most once - +{{{ '**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_**' >>. +{{{ '**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=**' if is_quadlet else '**--network' >> option with a static IP address +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 04ec81b068..67e6302c4a 100644 --- a/docs/source/markdown/options/ip6.md +++ b/docs/source/markdown/options/ip6.md @@ -2,19 +2,19 @@ ####> 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 >> +{% if is_quadlet %} ### `IP6=ipv6` -<< else >> +{% else %} #### **--ip6**=*ipv6* -<< endif >> +{% 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**' if is_quadlet else '**--network=network-name**' >> is used at most once - +{{{ '**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_**' >>. +{{{ '**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=**' if is_quadlet else '**--network' >> option with a static IPv6 address +{{{ '**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 9a11a4bd0a..fa930c5b79 100644 --- a/docs/source/markdown/options/label.image.md +++ b/docs/source/markdown/options/label.image.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `Label=label` -<< else >> +{% else %} #### **--label**=*label* -<< endif >> +{% 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 9f04e81c08..ff19f3f94c 100644 --- a/docs/source/markdown/options/label.md +++ b/docs/source/markdown/options/label.md @@ -2,10 +2,10 @@ ####> 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 >> +{% if is_quadlet %} ### `Label=key=value` -<< else >> +{% else %} #### **--label**, **-l**=*key=value* -<< endif >> +{% endif %} Add metadata to a <>. diff --git a/docs/source/markdown/options/log-driver.md b/docs/source/markdown/options/log-driver.md index e0b02da357..81b3f73918 100644 --- a/docs/source/markdown/options/log-driver.md +++ b/docs/source/markdown/options/log-driver.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `LogDriver=driver` -<< else >> +{% else %} #### **--log-driver**=*driver* -<< endif >> +{% 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 31ed80f38f..0356425545 100644 --- a/docs/source/markdown/options/log-opt.md +++ b/docs/source/markdown/options/log-opt.md @@ -2,23 +2,23 @@ ####> 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 >> +{% if is_quadlet %} ### `LogOpt=name=value` -<< else >> +{% else %} #### **--log-opt**=*name=value* -<< endif >> +{% 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. << '**LogOpt=path=/var/log/container/mycontainer.json**' if is_quadlet else '**--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. << '**LogOpt=max-size=10mb**' if is_quadlet else '**--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. << '**LogOpt=tag="{{.ImageName}}"**' if is_quadlet else '**--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 a1a2a2b55e..bfe6194340 100644 --- a/docs/source/markdown/options/memory.md +++ b/docs/source/markdown/options/memory.md @@ -2,17 +2,17 @@ ####> 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 >> +{% if is_quadlet %} ### `Memory=number[unit]` -<< else >> +{% else %} #### **--memory**, **-m**=*number[unit]* -<< endif >> +{% 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 << '**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 +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 index 1b09d7470c..c5a4a3c7bb 100644 --- a/docs/source/markdown/options/module.md +++ b/docs/source/markdown/options/module.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `ContainersConfModule=module` -<< else >> +{% else %} #### **--module**=*module* -<< endif >> +{% endif %} Load the specified containers.conf(5) module. diff --git a/docs/source/markdown/options/mount.md b/docs/source/markdown/options/mount.md index b12d970e51..29e394c116 100644 --- a/docs/source/markdown/options/mount.md +++ b/docs/source/markdown/options/mount.md @@ -2,22 +2,22 @@ ####> 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 >> +{% if is_quadlet %} ### `Mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]` -<< else >> +{% else %} #### **--mount**=*type=TYPE,TYPE-SPECIFIC-OPTION[,...]* -<< endif >> +{% endif %} Attach a filesystem mount to the container. -<< if is_quadlet >> +{% 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 >> +{% endif %} Current supported mount TYPEs are **artifact**, **bind**, **devpts**, **glob**, **image**, **ramfs**, **tmpfs** and **volume**. diff --git a/docs/source/markdown/options/name.container.md b/docs/source/markdown/options/name.container.md index 8c40bc7b51..8eec83e353 100644 --- a/docs/source/markdown/options/name.container.md +++ b/docs/source/markdown/options/name.container.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `ContainerName=name` -<< else >> +{% else %} #### **--name**=*name* -<< endif >> +{% endif %} Assign a name to the container. @@ -17,9 +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 << '**ContainerName=**' if is_quadlet else '**--name**' >>, +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 -<< '**AddHost=**' if is_quadlet else '**--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 887dc30d21..29a9d0f83d 100644 --- a/docs/source/markdown/options/network-alias.md +++ b/docs/source/markdown/options/network-alias.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `NetworkAlias=alias` -<< else >> +{% else %} #### **--network-alias**=*alias* -<< endif >> +{% 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 25c2c3cc8a..2aab4b02cd 100644 --- a/docs/source/markdown/options/network.image.md +++ b/docs/source/markdown/options/network.image.md @@ -2,19 +2,19 @@ ####> 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 >> +{% if is_quadlet %} ### `Network=mode` -<< else >> +{% else %} #### **--network**=*mode*, **--net** -<< endif >> +{% endif %} Sets the configuration for network namespaces when handling `RUN` instructions. -<< if is_quadlet >> +{% 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 >> +{% endif %} Valid _mode_ values are: diff --git a/docs/source/markdown/options/network.md b/docs/source/markdown/options/network.md index d2af235c4f..381be6e588 100644 --- a/docs/source/markdown/options/network.md +++ b/docs/source/markdown/options/network.md @@ -2,15 +2,15 @@ ####> 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 >> +{% if is_quadlet %} ### `Network=mode` -<< else >> +{% else %} #### **--network**=*mode*, **--net** -<< endif >> +{% endif %} Set the network mode for the <>. -<< if is_quadlet >> +{% if is_quadlet %} Special cases: * If the `name` of the network ends with `.network`, a Podman network called @@ -21,7 +21,7 @@ created by using a `$name.network` Quadlet file. Note: the corresponding `.netwo * 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 >> +{% endif %} Valid _mode_ values are: diff --git a/docs/source/markdown/options/os.pull.md b/docs/source/markdown/options/os.pull.md index af80fb622d..50866c1017 100644 --- a/docs/source/markdown/options/os.pull.md +++ b/docs/source/markdown/options/os.pull.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `OS=os` -<< else >> +{% else %} #### **--os**=*OS* -<< endif >> +{% 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 ac589d7a28..69dfb7108c 100644 --- a/docs/source/markdown/options/pids-limit.md +++ b/docs/source/markdown/options/pids-limit.md @@ -2,10 +2,10 @@ ####> 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 >> +{% if is_quadlet %} ### `PidsLimit=limit` -<< else >> +{% else %} #### **--pids-limit**=*limit* -<< endif >> +{% 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 9562d52eb4..f644a70500 100644 --- a/docs/source/markdown/options/publish.md +++ b/docs/source/markdown/options/publish.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `PublishPort=[[ip:][hostPort]:]containerPort[/protocol]` -<< else >> +{% else %} #### **--publish**, **-p**=*[[ip:][hostPort]:]containerPort[/protocol]* -<< endif >> +{% 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 074810b08d..f556dd17e8 100644 --- a/docs/source/markdown/options/pull.image.md +++ b/docs/source/markdown/options/pull.image.md @@ -2,11 +2,11 @@ ####> podman build, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. -<< if is_quadlet >> +{% if is_quadlet %} ### `Pull=policy` -<< else >> +{% else %} #### **--pull**=*policy* -<< endif >> +{% 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 95570442fd..63cc6b0ac2 100644 --- a/docs/source/markdown/options/pull.md +++ b/docs/source/markdown/options/pull.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `Pull=policy` -<< else >> +{% else %} #### **--pull**=*policy* -<< endif >> +{% 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 18841c85bd..57e83a3ba7 100644 --- a/docs/source/markdown/options/read-only-tmpfs.md +++ b/docs/source/markdown/options/read-only-tmpfs.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `ReadOnlyTmpfs=` -<< else >> +{% else %} #### **--read-only-tmpfs** -<< endif >> +{% endif %} When running --read-only containers, mount a read-write tmpfs on _/dev_, _/dev/shm_, _/run_, _/tmp_, and _/var/tmp_. The default is **true**. @@ -18,16 +18,16 @@ When running --read-only containers, mount a read-write tmpfs on _/dev_, _/dev/s | false | true | r/w | r/w | -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 +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 << '**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 +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 << '**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. +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 bc84389321..efac96c678 100644 --- a/docs/source/markdown/options/read-only.md +++ b/docs/source/markdown/options/read-only.md @@ -2,14 +2,14 @@ ####> 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 >> +{% if is_quadlet %} ### `ReadOnly=` -<< else >> +{% else %} #### **--read-only** -<< endif >> +{% 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 << '**ReadOnly=**' if is_quadlet else '**--read-only**' >> flag, +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/retry-delay.md b/docs/source/markdown/options/retry-delay.md index 52d8cd4368..a8b7a3b72e 100644 --- a/docs/source/markdown/options/retry-delay.md +++ b/docs/source/markdown/options/retry-delay.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `RetryDelay=duration` -<< else >> +{% else %} #### **--retry-delay**=*duration* -<< endif >> +{% 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 f110eb47fe..c07dd2307f 100644 --- a/docs/source/markdown/options/retry.md +++ b/docs/source/markdown/options/retry.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `Retry=attempts` -<< else >> +{% else %} #### **--retry**=*attempts* -<< endif >> +{% 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 3ee275fe5b..495278344f 100644 --- a/docs/source/markdown/options/rootfs.md +++ b/docs/source/markdown/options/rootfs.md @@ -2,18 +2,18 @@ ####> 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 >> +{% if is_quadlet %} ### `Rootfs=` -<< else >> +{% else %} #### **--rootfs** -<< endif >> +{% endif %} If specified, the first argument refers to an exploded container on the file system. -<< if is_quadlet >> +{% if is_quadlet %} This option conflicts with the `Image` option. -<< endif >> +{% 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 7057c85fed..bc5bf48fdf 100644 --- a/docs/source/markdown/options/secret.image.md +++ b/docs/source/markdown/options/secret.image.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `Secret=id=id[,src=envOrFile][,env=ENV][,type=file | env]` -<< else >> +{% else %} #### **--secret**=**id=id[,src=*envOrFile*][,env=*ENV*][,type=*file* | *env*]** -<< endif >> +{% 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 42f246ddd3..c2d1a9e604 100644 --- a/docs/source/markdown/options/secret.md +++ b/docs/source/markdown/options/secret.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `Secret=secret[,opt=opt ...]` -<< else >> +{% else %} #### **--secret**=*secret[,opt=opt ...]* -<< endif >> +{% 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 822c912a2c..fc9260964c 100644 --- a/docs/source/markdown/options/shm-size.md +++ b/docs/source/markdown/options/shm-size.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `ShmSize=number[unit]` -<< else >> +{% else %} #### **--shm-size**=*number[unit]* -<< endif >> +{% 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 19b525ec4d..cf77adb072 100644 --- a/docs/source/markdown/options/stop-signal.md +++ b/docs/source/markdown/options/stop-signal.md @@ -2,10 +2,10 @@ ####> 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 >> +{% if is_quadlet %} ### `StopSignal=signal` -<< else >> +{% else %} #### **--stop-signal**=*signal* -<< endif >> +{% 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 3027a0a18a..c84651b06e 100644 --- a/docs/source/markdown/options/stop-timeout.md +++ b/docs/source/markdown/options/stop-timeout.md @@ -2,15 +2,15 @@ ####> 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 >> +{% if is_quadlet %} ### `StopTimeout=seconds` -<< else >> +{% else %} #### **--stop-timeout**=*seconds* -<< endif >> +{% endif %} Timeout to stop a container. Default is **10**. Remote connections use local containers.conf for defaults. -<< if is_quadlet >> +{% 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 >> +{% endif %} diff --git a/docs/source/markdown/options/subgidname.md b/docs/source/markdown/options/subgidname.md index 65ee9d00cc..f11c25914b 100644 --- a/docs/source/markdown/options/subgidname.md +++ b/docs/source/markdown/options/subgidname.md @@ -2,12 +2,13 @@ ####> 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 >> +{% if is_quadlet %} ### `SubGIDMap=name` -<< else >> +{% else %} #### **--subgidname**=*name* -<< endif >> +{% 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=**' if is_quadlet else '**--userns**' >> and << '**GIDMap=**' if is_quadlet else '**--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 4f46c9aac1..ebe0f65612 100644 --- a/docs/source/markdown/options/subuidname.md +++ b/docs/source/markdown/options/subuidname.md @@ -2,12 +2,12 @@ ####> 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 >> +{% if is_quadlet %} ### `SubUIDMap=name` -<< else >> +{% else %} #### **--subuidname**=*name* -<< endif >> +{% 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=**' if is_quadlet else '**--userns**' >> and << '**UIDMap=**' if is_quadlet else '**--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 7c987b550c..4e4f884e8f 100644 --- a/docs/source/markdown/options/sysctl.md +++ b/docs/source/markdown/options/sysctl.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `Sysctl=name=value` -<< else >> +{% else %} #### **--sysctl**=*name=value* -<< endif >> +{% endif %} Configure namespaced kernel parameters <>. @@ -22,7 +22,6 @@ For the IPC namespace, the following sysctls are allowed: - kernel.shm_rmid_forced - Sysctls beginning with fs.mqueue.\* - Note: <>, the above sysctls are not allowed. For the network namespace, only sysctls beginning with net.\* are allowed. diff --git a/docs/source/markdown/options/tag.md b/docs/source/markdown/options/tag.md index 6cce46e5ec..a35e6b2fb4 100644 --- a/docs/source/markdown/options/tag.md +++ b/docs/source/markdown/options/tag.md @@ -2,11 +2,11 @@ ####> 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 >> -### `ImageTag=imageName` -<< else >> +{% if is_quadlet %} +### `TaImageTag=imageName` +{% else %} #### **--tag**, **-t**=*imageName* -<< endif >> +{% 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 abb2d10197..83c2a8dacc 100644 --- a/docs/source/markdown/options/target.md +++ b/docs/source/markdown/options/target.md @@ -2,10 +2,10 @@ ####> 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 >> +{% if is_quadlet %} ### `Target=stageName` -<< else >> +{% else %} #### **--target**=*stageName* -<< endif >> +{% 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 f4ba079d75..0cb60d2e5d 100644 --- a/docs/source/markdown/options/tls-verify.md +++ b/docs/source/markdown/options/tls-verify.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `TLSVerify=` -<< else >> +{% else %} #### **--tls-verify** -<< endif >> +{% 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 0426c89c78..4f38eead6c 100644 --- a/docs/source/markdown/options/tmpfs.md +++ b/docs/source/markdown/options/tmpfs.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `Tmpfs=` -<< else >> +{% else %} #### **--tmpfs**=*fs* -<< endif >> +{% endif %} Create a tmpfs mount. diff --git a/docs/source/markdown/options/tz.md b/docs/source/markdown/options/tz.md index fae294362a..61255b88bc 100644 --- a/docs/source/markdown/options/tz.md +++ b/docs/source/markdown/options/tz.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} +### `TimeZone=timezone` +{% else %} #### **--tz**=*timezone* -<< endif >> +{% 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 84816bc8a2..39ed4729b2 100644 --- a/docs/source/markdown/options/uidmap.container.md +++ b/docs/source/markdown/options/uidmap.container.md @@ -2,14 +2,14 @@ ####> 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 >> +{% if is_quadlet %} ### `UIDMap=[flags]container_uid:from_uid[:amount]` -<< else >> +{% else %} #### **--uidmap**=*[flags]container_uid:from_uid[:amount]* -<< endif >> +{% endif %} Run the container in a new user namespace using the supplied UID mapping. This -option conflicts with the << '**UserNS=**' if is_quadlet else '**--userns**' >> and << '**SubUIDMap=**' if is_quadlet else '**--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. @@ -24,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=**' if is_quadlet else '**--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 @@ -48,7 +48,7 @@ happens over two mapping steps: host UID -> intermediate UID -> container UID -The << '**UIDMap=**' if is_quadlet else '**--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. @@ -66,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=**' if is_quadlet else '**--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: @@ -91,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=**' if is_quadlet else '**--uidmap**' >> or << '**GIDMap=**' if is_quadlet else '**--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`, @@ -141,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=**' if is_quadlet else '**--uidmap**' >> or << '**GIDMap=**' if is_quadlet else '**--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 @@ -156,20 +156,20 @@ For instance given the command podman <> --gidmap "0:0:1000" --gidmap "g2000:2000:1" -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**' >>, +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=**' if is_quadlet else '**--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*"**' if is_quadlet else '**--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: @@ -180,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**' if is_quadlet else '**--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, << '**GroupAdd=keep-groups**' if is_quadlet else '**--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. @@ -192,9 +192,9 @@ inside the container. `No subordinate UIDs` Even if a user does not have any subordinate UIDs in _/etc/subuid_, -<< '**UIDMap=**' if is_quadlet else '**--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=**' 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. +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 39cddfabf6..1680927ec6 100644 --- a/docs/source/markdown/options/uidmap.pod.md +++ b/docs/source/markdown/options/uidmap.pod.md @@ -2,13 +2,13 @@ ####> 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 >> +{% if is_quadlet %} ### `UIDMap=container_uid:from_uid:amount` -<< else >> +{% else %} #### **--uidmap**=*container_uid:from_uid:amount* -<< endif >> +{% endif %} Run all containers in the pod in a new user namespace using the supplied mapping. This -option conflicts with the << '**UserNS=.**' if is_quadlet else '**--userns**' >> and << '**SubUIDMap=.**' if is_quadlet else '**--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 b6e2920b39..7b827cdeb0 100644 --- a/docs/source/markdown/options/ulimit.md +++ b/docs/source/markdown/options/ulimit.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `Ulimit=option` -<< else >> +{% else %} #### **--ulimit**=*option* -<< endif >> +{% 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 11130bf908..c3ea5e52b0 100644 --- a/docs/source/markdown/options/user.md +++ b/docs/source/markdown/options/user.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `User=user[:group]` -<< else >> +{% else %} #### **--user**, **-u**=*user[:group]* -<< endif >> +{% 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 6d7fe205e0..0380f7b276 100644 --- a/docs/source/markdown/options/userns.container.md +++ b/docs/source/markdown/options/userns.container.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `UserNS=mode` -<< else >> +{% else %} #### **--userns**=*mode* -<< endif >> +{% endif %} Set the user namespace mode for the container. @@ -18,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=**' if is_quadlet else '**--gidmap**' >>, << '**UIDMap=**' if is_quadlet else '**--uidmap**' >>, << '**SubUIDMap=**' if is_quadlet else '**-**--subuidname****' >> and << '**SubGIDMap=**' if is_quadlet else '**-**--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: @@ -52,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=**' if is_quadlet else '**--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 f5ba4ce5b9..2da8aa430a 100644 --- a/docs/source/markdown/options/userns.pod.md +++ b/docs/source/markdown/options/userns.pod.md @@ -2,15 +2,15 @@ ####> 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 >> +{% if is_quadlet %} ### `UserNS=mode` -<< else >> +{% else %} #### **--userns**=*mode* -<< endif >> +{% 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**' if is_quadlet else '**--userns=Key**' >> mappings: +Rootless user {{{ '**UserNS=Key**' if is_quadlet else '**--userns=Key**' }}} mappings: Key | Host User | Container User ----------|---------------|--------------------- @@ -26,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=' if is_quadlet else '--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 8202a1a436..f49dc9ee53 100644 --- a/docs/source/markdown/options/variant.container.md +++ b/docs/source/markdown/options/variant.container.md @@ -2,10 +2,10 @@ ####> 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 >> +{% if is_quadlet %} ### `Variant=VARIANT` -<< else >> +{% else %} #### **--variant**=*VARIANT* -<< endif >> +{% 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 e339209514..80d5edd928 100644 --- a/docs/source/markdown/options/volume.image.md +++ b/docs/source/markdown/options/volume.image.md @@ -2,20 +2,20 @@ ####> podman build, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. -<< if is_quadlet >> +{% if is_quadlet %} ### `Volume=[HOST-DIR:CONTAINER-DIR[:OPTIONS]]` -<< else >> +{% else %} #### **--volume**, **-v**=*[HOST-DIR:CONTAINER-DIR[:OPTIONS]]* -<< endif >> +{% endif %} Mount a host directory into containers when executing RUN instructions during the build. -<< if is_quadlet >> +{% 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 >> +{% endif %} The `OPTIONS` are a comma-separated list and can be one or more of: diff --git a/docs/source/markdown/options/volume.md b/docs/source/markdown/options/volume.md index 150e484bf7..e6a4441b54 100644 --- a/docs/source/markdown/options/volume.md +++ b/docs/source/markdown/options/volume.md @@ -2,11 +2,11 @@ ####> 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 >> +{% if is_quadlet %} ### `Volume=[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]` -<< else >> +{% else %} #### **--volume**, **-v**=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]* -<< endif >> +{% 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 @@ -17,11 +17,11 @@ 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 >> +{% 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 >> +{% 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.) diff --git a/docs/source/markdown/options/workdir.md b/docs/source/markdown/options/workdir.md index 734edc4a3b..87a8a2d73a 100644 --- a/docs/source/markdown/options/workdir.md +++ b/docs/source/markdown/options/workdir.md @@ -2,14 +2,14 @@ ####> 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 >> +{% if is_quadlet %} ### `WorkingDir=dir` -<< else >> +{% else %} #### **--workdir**, **-w**=*dir* -<< endif >> +{% 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 << '**WokingDir=**' if is_quadlet else '**-w**' >> option. +can override the working directory by using the {{{ '**WokingDir=**' if is_quadlet else '**-w**' }}} option. diff --git a/docs/source/markdown/podman-build.unit.5.md.in b/docs/source/markdown/podman-build.unit.5.md.in index d995494f05..6efac39aa0 100644 --- a/docs/source/markdown/podman-build.unit.5.md.in +++ b/docs/source/markdown/podman-build.unit.5.md.in @@ -42,6 +42,25 @@ The resulting image can be referenced by `.container` or `.volume` units via: 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: @@ -93,7 +112,7 @@ This is equivalent to the `--annotation` option of `podman build`. @@option quadlet:dns-search.image -@@option quadlet:env +@@option quadlet:env.image @@option quadlet:file diff --git a/docs/source/markdown/podman-container.unit.5.md.in b/docs/source/markdown/podman-container.unit.5.md.in index 37ca7dd3f8..4ee555a749 100644 --- a/docs/source/markdown/podman-container.unit.5.md.in +++ b/docs/source/markdown/podman-container.unit.5.md.in @@ -33,6 +33,23 @@ The `.container` file is parsed by the `podman-system-generator` at boot or relo 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: @@ -76,7 +93,6 @@ Valid options for `[Container]` are listed below: | 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 | @@ -238,8 +254,6 @@ which can be modified with `UserNS`, but if that is not specified, this GID is a @@option quadlet:hostname.container -@@option quadlet:http-proxy - ### `Image=` The image to run in the container. diff --git a/docs/source/markdown/podman-image.unit.5.md.in b/docs/source/markdown/podman-image.unit.5.md.in index 3179bf0730..512e9f4702 100644 --- a/docs/source/markdown/podman-image.unit.5.md.in +++ b/docs/source/markdown/podman-image.unit.5.md.in @@ -20,10 +20,27 @@ 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`. +`.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: @@ -129,6 +146,27 @@ This is equivalent to the Podman `--policy` option. @@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: diff --git a/docs/source/markdown/podman-kube.unit.5.md.in b/docs/source/markdown/podman-kube.unit.5.md.in index a1176fc230..075a97cd22 100644 --- a/docs/source/markdown/podman-kube.unit.5.md.in +++ b/docs/source/markdown/podman-kube.unit.5.md.in @@ -27,6 +27,23 @@ The `.kube` file is parsed by the `podman-system-generator` at boot or reload, g 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: @@ -153,5 +170,4 @@ WantedBy=multi-user.target default.target [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-kube-generate(1)](https://docs.podman.io/en/latest/markdown/podman-kube-generate.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 index 844130c5f7..510eec3596 100644 --- a/docs/source/markdown/podman-network.unit.5.md.in +++ b/docs/source/markdown/podman-network.unit.5.md.in @@ -26,6 +26,23 @@ In order to update the network parameters you will first need to manually remove 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: diff --git a/docs/source/markdown/podman-pod.unit.5.md.in b/docs/source/markdown/podman-pod.unit.5.md.in index e09087dd38..efbae70b6a 100644 --- a/docs/source/markdown/podman-pod.unit.5.md.in +++ b/docs/source/markdown/podman-pod.unit.5.md.in @@ -19,6 +19,23 @@ By default, the Podman pod has the same name as the unit, but with a `systemd-` 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: @@ -60,8 +77,6 @@ Supported keys in the `[Pod]` section are: @@option quadlet:dns-option.container -@@option quadlet:dns-search.container - ### `ExitPolicy=` Set the exit policy of the pod when the last container exits. Default for quadlets is **stop**. @@ -82,7 +97,7 @@ escaped to allow inclusion of whitespace and other control characters. This key can be listed multiple times. -@@option quadlet:hostname.container +@option quadlet::hostname.container @@option quadlet:ip @@ -163,3 +178,4 @@ Pod=test.pod [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 index 9097ee628b..b7e597c461 100644 --- a/docs/source/markdown/podman-quadlet-basic-usage.7.md +++ b/docs/source/markdown/podman-quadlet-basic-usage.7.md @@ -146,7 +146,7 @@ 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 +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: diff --git a/docs/source/markdown/podman-quadlet.7.md b/docs/source/markdown/podman-quadlet.7.md index 0aa1df5abb..0d2c786a81 100644 --- a/docs/source/markdown/podman-quadlet.7.md +++ b/docs/source/markdown/podman-quadlet.7.md @@ -49,13 +49,13 @@ Quadlet integrates cleanly with both rootless and rootful Podman environments, d Quadlet supports the following file types: -- **`.container`** — Defines and manages a single container. See [podman-container.unit(5)](podman-container.unit.5.md). -- **`.pod`** — Creates a Podman pod that containers can join. See [podman-pod.unit(5)](podman-pod.unit.5.md). -- **`.volume`** — Ensures a named Podman volume exists. See [podman-volume.unit(5)](podman-volume.unit.5.md). -- **`.network`** — Creates a Podman network for containers and pods. See [podman-network.unit(5)](podman-network.unit.5.md). -- **`.image`** — Pulls and caches a container image. See [podman-image.unit(5)](podman-image.unit.5.md). -- **`.build`** — Builds a container image from a Containerfile. See [podman-build.unit(5)](podman-build.unit.5.md). -- **`.kube`** — Deploys containers from Kubernetes YAML using [podman-kube.unit(5)](podman-kube.unit.5.md). +- **`.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. @@ -77,26 +77,6 @@ Quadlet files should be stored in specific directories depending on rootless or - `/etc/containers/systemd/users/$(UID)` - `/etc/containers/systemd/users/` -## 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. - # SEE ALSO [podman-quadlet(7)](https://docs.podman.io/en/latest/markdown/podman-quadlet.7.html), diff --git a/hack/markdown-preprocess b/hack/markdown-preprocess index a82029f534..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(): """ @@ -23,100 +24,6 @@ class Preprocessor(): self.pod_or_container = '' self.used_by = {} - def render(self, text: str, context: dict) -> str: - """ - Renders the `text` handling the following extra formatting features: - - ``` - << if variable >> - ... - << endif >> - - << if not variable >> - ... - << else >> - ... - << endif >> - - << "foo" if variable else "bar" >> - ``` - - Returns the rendered text. - """ - # Match << ... >> - TOK = re.compile(r"<<(.*?)>>", re.DOTALL) - out = [] - pos = 0 - stack = [] # each frame: {"active": bool, "seen_else": bool} - - def is_active(): - return all(f["active"] for f in stack) - - def get_variable(name: str): - v = context.get(name, None) - if v is None: - raise ValueError(f"undefined variable: {name}") - return v - - def truthy(name: str) -> bool: - name = name.strip() - if name.startswith("not "): - v = get_variable(name[4:].strip()) - return not bool(v) - return bool(get_variable(name)) - - for m in TOK.finditer(text): - # write literal up to token - literal = text[pos:m.start()] - if is_active(): - out.append(literal) - pos = m.end() - - inner = m.group(1).strip() - - # control blocks - if inner.startswith("if ") and len(inner[3:].strip().split(" ")) in [1, 2]: - cond = inner[3:].strip() - stack.append({"active": is_active() and truthy(cond), "seen_else": False}) - continue - if inner == "else": - if not stack: - raise ValueError("`else` without `if`") - frame = stack[-1] - if frame["seen_else"]: - raise ValueError("multiple `else` in the same `if`") - frame["seen_else"] = True - parent_active = all(f["active"] for f in stack[:-1]) - frame["active"] = parent_active and not frame["active"] - continue - if inner == "endif": - if not stack: - raise ValueError("`end` without `if`") - stack.pop() - continue - - # inline "X if cond else Y" --- - if " if " in inner and " else " in inner: - try: - # split by " if " then " else " - then_part, rest = inner.split(" if ", 1) - cond, else_part = rest.split(" else ", 1) - cond = cond.strip() - chosen = then_part if truthy(cond) else else_part - if is_active(): - out.append(chosen.strip().strip("'\"")) - except Exception as e: - raise ValueError(f"Invalid inline if/else syntax: {inner}") from e - continue - - # trailing literal - if is_active(): - out.append(text[pos:]) - - if stack: - raise ValueError("unclosed `if` block(s)") - return "".join(out) - def process(self, infile:str): """ Main calling point: preprocesses one file @@ -198,7 +105,12 @@ 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: - rendered = self.render(fh_included.read(), {"is_quadlet": is_quadlet}) + 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 diff --git a/hack/xref-quadlet-docs b/hack/xref-quadlet-docs index d20246d0e4..022f2c4898 100755 --- a/hack/xref-quadlet-docs +++ b/hack/xref-quadlet-docs @@ -19,16 +19,7 @@ our $VERSION = '0.1'; # BEGIN user-customizable section our $Go = 'pkg/systemd/quadlet/quadlet.go'; -our @Docs = ( - "docs/source/markdown/podman-build.unit.5.md", - "docs/source/markdown/podman-container.unit.5.md", - "docs/source/markdown/podman-kube.unit.5.md", - "docs/source/markdown/podman-network.unit.5.md", - "docs/source/markdown/podman-pod.unit.5.md", - "docs/source/markdown/podman-volume.unit.5.md", - "docs/source/markdown/podman-image.unit.5.md", - "docs/source/markdown/podman-quadlet.7.md", -); +our $Doc = 'docs/source/markdown/podman-systemd.unit.5.md'; # END user-customizable section ############################################################################### @@ -44,7 +35,7 @@ $ME cross-checks quadlet documentation between the Go source[Go] and the man page[MD]. [Go]: $Go - [MD]: @Docs + [MD]: $Doc We check that: @@ -104,7 +95,7 @@ sub main { my $true_keys = read_go($Go); # Read md file, compare against Truth - crossref_docs(\@Docs, $true_keys); + crossref_doc($Doc, $true_keys); exit $errs; } @@ -150,17 +141,19 @@ sub read_go { } ################## -# crossref_docs # Read the markdown pages, cross-check against Truth +# crossref_doc # Read the markdown page, cross-check against Truth ################## -sub crossref_docs { - my $paths_ref = shift; # in: array with paths to .md file +sub crossref_doc { + my $path = shift; # in: path to .md file my $true_keys = shift; # in: AREF, list of keys from .go + open my $fh, '<', $path + or die "$ME: Cannot read $path: $!\n";; + my $unit = ''; my %documented; my @found_in_table; my @described; - my $read_first_table; # Helper function: when done reading description blocks, # make sure that there's one block for each key listed @@ -173,86 +166,85 @@ sub crossref_docs { } }; - # foreach loop - foreach my $path (@$paths_ref) { - open my $fh, '<', $path - or die "$ME: Cannot read $path: $!\n";; + # Main loop: read the docs line by line + while (my $line = <$fh>) { + chomp $line; - my $new_unit = $path; - $crossref_against_table->(); - $unit = $new_unit; + # New section, with its own '| table |' and '### Keyword blocks' + if ($line =~ /^##\s+(\S+)\s+(?:units|section)\s+\[(\S+)\]/) { + my $new_unit = $1; + $new_unit eq $2 + or warn "$ME: $path:$.: inconsistent block names in '$line'\n"; - # Reset, because each section has its own table & blocks - @found_in_table = (); - @described = (); - $read_first_table = 0; + $crossref_against_table->(); + $unit = $new_unit; - # Main loop: read the docs line by line - while (my $line = <$fh>) { - chomp $line; + # Reset, because each section has its own table & blocks + @found_in_table = (); + @described = (); + next; + } - # Table line - if ($read_first_table == 0 && $line =~ s/^\|\s+//) { - next if $line =~ /^\*\*/; # title - next if $line =~ /^-----/; # divider + # Table line + if ($line =~ s/^\|\s+//) { + next if $line =~ /^\*\*/; # title + next if $line =~ /^-----/; # divider - if ($line =~ /^([A-Z][A-Za-z6]+)=/) { - my $key = $1; - - grep { $_ eq $key } @$true_keys - or warn "$ME: $path:$.: unknown key '$key' (not present in $Go)\n"; - - # Sorting check - if (@found_in_table) { - if (lc($key) lt lc($found_in_table[-1])) { - warn "$ME: $path:$.: out-of-order key '$key' in table\n"; - } - } - - push @found_in_table, $key; - $documented{$key}++; - } - else { - warn "$ME: $path:$.: cannot grok table line '$line'\n"; - } - } - - # Description block - elsif ($line =~ /^###\s+`([A-Z][A-Za-z6]+)=.*`/) { + if ($line =~ /^([A-Z][A-Za-z6]+)=/) { my $key = $1; - $read_first_table = 1; + grep { $_ eq $key } @$true_keys + or warn "$ME: $path:$.: unknown key '$key' (not present in $Go)\n"; - # Check for dups and for out-of-order - if (@described) { - if (lc($key) lt lc($described[-1])) { - warn "$ME: $path:$.: out-of-order key '$key'\n"; - } - if (grep { lc($_) eq lc($key) } @described) { - warn "$ME: $path:$.: duplicate key '$key'\n"; + # Sorting check + if (@found_in_table) { + if (lc($key) lt lc($found_in_table[-1])) { + warn "$ME: $path:$.: out-of-order key '$key' in table\n"; } } - grep { $_ eq $key } @found_in_table - or warn "$ME: $path:$.: key '$key' is not listed in table for unit/section '$unit'\n"; - - push @described, $key; + push @found_in_table, $key; $documented{$key}++; } + else { + warn "$ME: $path:$.: cannot grok table line '$line'\n"; + } } - close $fh; + # Description block + elsif ($line =~ /^###\s+`(\S+)=`/) { + my $key = $1; + + # Check for dups and for out-of-order + if (@described) { + if (lc($key) lt lc($described[-1])) { + warn "$ME: $path:$.: out-of-order key '$key'\n"; + } + if (grep { lc($_) eq lc($key) } @described) { + warn "$ME: $path:$.: duplicate key '$key'\n"; + } + } + + grep { $_ eq $key } @found_in_table + or warn "$ME: $path:$.: key '$key' is not listed in table for unit/section '$unit'\n"; + + push @described, $key; + $documented{$key}++; + } } + close $fh; + # Final cross-check between table and description blocks $crossref_against_table->(); # Check that no Go keys are missing + (my $md_basename = $path) =~ s|^.*/||; for my $k (@$true_keys) { $documented{$k} - or warn "$ME: undocumented key: '$k' not found anywhere in @$paths_ref\n"; + or warn "$ME: undocumented key: '$k' not found anywhere in $md_basename\n"; } } 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 From 070d7c3ad392b12cae701cd52ad7434255c15ab7 Mon Sep 17 00:00:00 2001 From: Paul Holzinger Date: Thu, 11 Sep 2025 19:00:19 +0200 Subject: [PATCH 4/4] Revert "Rewrite the Quadlet documentation." This reverts commit c12b1b32bc165766c1aa229ca05432c75cc74c3b. The content contains incorrect information and misses a lot of details from the previous page that must be restored. Signed-off-by: Paul Holzinger --- docs/source/markdown/.gitignore | 8 - docs/source/markdown/links/quadlet.5 | 2 +- docs/source/markdown/options/README.md | 33 - docs/source/markdown/options/add-host.md | 6 +- .../markdown/options/annotation.container.md | 6 +- .../markdown/options/annotation.image.md | 4 - docs/source/markdown/options/arch.md | 7 +- docs/source/markdown/options/authfile.md | 6 +- docs/source/markdown/options/cap-add.image.md | 5 - docs/source/markdown/options/cap-add.md | 6 +- docs/source/markdown/options/cap-drop.md | 10 +- docs/source/markdown/options/cert-dir.md | 6 +- docs/source/markdown/options/cgroups.md | 14 +- docs/source/markdown/options/creds.md | 6 +- .../source/markdown/options/decryption-key.md | 6 +- docs/source/markdown/options/device.md | 14 +- .../markdown/options/dns-option.container.md | 9 +- .../markdown/options/dns-option.image.md | 6 +- .../markdown/options/dns-search.container.md | 11 +- .../markdown/options/dns-search.image.md | 6 +- docs/source/markdown/options/dns.md | 8 +- docs/source/markdown/options/entrypoint.md | 8 +- docs/source/markdown/options/env-file.md | 6 +- docs/source/markdown/options/env-host.md | 6 +- docs/source/markdown/options/env.image.md | 8 +- docs/source/markdown/options/env.md | 6 +- docs/source/markdown/options/expose.md | 10 +- docs/source/markdown/options/file.md | 19 +- docs/source/markdown/options/force-rm.md | 6 +- .../markdown/options/gidmap.container.md | 15 +- docs/source/markdown/options/group-add.md | 6 +- docs/source/markdown/options/health-cmd.md | 6 +- .../markdown/options/health-interval.md | 6 +- .../options/health-log-destination.md | 6 +- .../markdown/options/health-max-log-count.md | 6 +- .../markdown/options/health-max-log-size.md | 6 +- .../markdown/options/health-on-failure.md | 6 +- .../source/markdown/options/health-retries.md | 6 +- .../markdown/options/health-start-period.md | 15 +- .../markdown/options/health-startup-cmd.md | 9 +- .../options/health-startup-interval.md | 6 +- .../options/health-startup-retries.md | 6 +- .../options/health-startup-success.md | 6 +- .../options/health-startup-timeout.md | 6 +- .../source/markdown/options/health-timeout.md | 6 +- .../markdown/options/hostname.container.md | 10 +- docs/source/markdown/options/init.md | 6 +- docs/source/markdown/options/ip.md | 16 +- docs/source/markdown/options/ip6.md | 16 +- docs/source/markdown/options/label.image.md | 6 +- docs/source/markdown/options/label.md | 6 +- docs/source/markdown/options/log-driver.md | 6 +- docs/source/markdown/options/log-opt.md | 12 +- docs/source/markdown/options/memory.md | 10 +- docs/source/markdown/options/module.md | 13 - docs/source/markdown/options/mount.md | 15 +- .../source/markdown/options/name.container.md | 11 +- docs/source/markdown/options/network-alias.md | 6 +- docs/source/markdown/options/network.image.md | 12 +- docs/source/markdown/options/network.md | 19 +- docs/source/markdown/options/os.pull.md | 6 +- docs/source/markdown/options/pids-limit.md | 6 +- docs/source/markdown/options/publish.md | 6 +- docs/source/markdown/options/pull.image.md | 4 - docs/source/markdown/options/pull.md | 6 +- .../markdown/options/read-only-tmpfs.md | 15 +- docs/source/markdown/options/read-only.md | 9 +- docs/source/markdown/options/restart.md | 2 +- docs/source/markdown/options/retry-delay.md | 6 +- docs/source/markdown/options/retry.md | 6 +- docs/source/markdown/options/rootfs.md | 10 +- docs/source/markdown/options/secret.image.md | 6 +- docs/source/markdown/options/secret.md | 6 +- docs/source/markdown/options/shm-size.md | 6 +- docs/source/markdown/options/stop-signal.md | 6 +- docs/source/markdown/options/stop-timeout.md | 10 +- docs/source/markdown/options/subgidname.md | 9 +- docs/source/markdown/options/subuidname.md | 8 +- docs/source/markdown/options/sysctl.md | 6 +- docs/source/markdown/options/tag.md | 6 +- docs/source/markdown/options/target.md | 6 +- docs/source/markdown/options/tls-verify.md | 6 +- docs/source/markdown/options/tmpfs.md | 6 +- docs/source/markdown/options/tz.md | 6 +- .../markdown/options/uidmap.container.md | 32 +- docs/source/markdown/options/uidmap.pod.md | 8 +- docs/source/markdown/options/ulimit.md | 6 +- docs/source/markdown/options/user.md | 6 +- .../markdown/options/userns.container.md | 10 +- docs/source/markdown/options/userns.pod.md | 10 +- .../markdown/options/variant.container.md | 6 +- docs/source/markdown/options/volume.image.md | 10 - docs/source/markdown/options/volume.md | 12 +- docs/source/markdown/options/workdir.md | 8 +- .../markdown/podman-auto-update.1.md.in | 8 +- .../source/markdown/podman-build.unit.5.md.in | 229 -- .../markdown/podman-container.unit.5.md.in | 559 ---- .../markdown/podman-generate-systemd.1.md | 4 +- .../source/markdown/podman-image.unit.5.md.in | 199 -- docs/source/markdown/podman-kube.unit.5.md.in | 173 -- .../markdown/podman-network.unit.5.md.in | 214 -- docs/source/markdown/podman-pod.unit.5.md.in | 181 -- .../markdown/podman-quadlet-basic-usage.7.md | 218 -- docs/source/markdown/podman-quadlet.7.md | 94 - docs/source/markdown/podman-systemd.unit.5.md | 2279 +++++++++++++++++ .../markdown/podman-volume.unit.5.md.in | 177 -- docs/source/markdown/podmansh.1.md | 2 +- hack/markdown-preprocess | 47 +- rpm/podman.spec | 1 - 109 files changed, 2447 insertions(+), 2738 deletions(-) delete mode 100644 docs/source/markdown/options/module.md delete mode 100644 docs/source/markdown/podman-build.unit.5.md.in delete mode 100644 docs/source/markdown/podman-container.unit.5.md.in delete mode 100644 docs/source/markdown/podman-image.unit.5.md.in delete mode 100644 docs/source/markdown/podman-kube.unit.5.md.in delete mode 100644 docs/source/markdown/podman-network.unit.5.md.in delete mode 100644 docs/source/markdown/podman-pod.unit.5.md.in delete mode 100644 docs/source/markdown/podman-quadlet-basic-usage.7.md delete mode 100644 docs/source/markdown/podman-quadlet.7.md create mode 100644 docs/source/markdown/podman-systemd.unit.5.md delete mode 100644 docs/source/markdown/podman-volume.unit.5.md.in diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore index 3ab040378b..3dd3b2e7d4 100644 --- a/docs/source/markdown/.gitignore +++ b/docs/source/markdown/.gitignore @@ -69,11 +69,3 @@ 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 8b26a55dfd..1241a235f5 100644 --- a/docs/source/markdown/links/quadlet.5 +++ b/docs/source/markdown/links/quadlet.5 @@ -1 +1 @@ -.so man7/podman-quadlet.7 +.so man5/podman-systemd.unit.5 diff --git a/docs/source/markdown/options/README.md b/docs/source/markdown/options/README.md index cb1844f7f1..bc3f5bfccb 100644 --- a/docs/source/markdown/options/README.md +++ b/docs/source/markdown/options/README.md @@ -17,8 +17,6 @@ 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 @@ -27,37 +25,6 @@ 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 478e050418..316d635d5c 100644 --- a/docs/source/markdown/options/add-host.md +++ b/docs/source/markdown/options/add-host.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman build, podman-container.unit.5.md.in, create, farm build, pod create, podman-pod.unit.5.md.in, run +####> podman build, create, farm build, pod create, 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 edff7c3fab..aadaef264f 100644 --- a/docs/source/markdown/options/annotation.container.md +++ b/docs/source/markdown/options/annotation.container.md @@ -1,11 +1,7 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, kube play, run +####> podman 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 1417dcc054..13964ec23d 100644 --- a/docs/source/markdown/options/annotation.image.md +++ b/docs/source/markdown/options/annotation.image.md @@ -2,11 +2,7 @@ ####> 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 20806f4b17..33cee10299 100644 --- a/docs/source/markdown/options/arch.md +++ b/docs/source/markdown/options/arch.md @@ -1,12 +1,7 @@ ####> This option file is used in: -####> podman podman-build.unit.5.md.in, create, podman-image.unit.5.md.in, pull, run +####> podman create, 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 6999d0c98e..e6724b4b8a 100644 --- a/docs/source/markdown/options/authfile.md +++ b/docs/source/markdown/options/authfile.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> 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 +####> 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 ####> 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 7696578f12..1874f558b8 100644 --- a/docs/source/markdown/options/cap-add.image.md +++ b/docs/source/markdown/options/cap-add.image.md @@ -2,12 +2,7 @@ ####> 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 ada47189f8..67fc2e4d36 100644 --- a/docs/source/markdown/options/cap-add.md +++ b/docs/source/markdown/options/cap-add.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run +####> podman 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 c9333fae56..1baacc96d6 100644 --- a/docs/source/markdown/options/cap-drop.md +++ b/docs/source/markdown/options/cap-drop.md @@ -1,13 +1,7 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run +####> podman 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 these capabilities from the default podman capability set, or `all` to drop all capabilities. - -This is a space separated list of capabilities. +Drop Linux capabilities. diff --git a/docs/source/markdown/options/cert-dir.md b/docs/source/markdown/options/cert-dir.md index b32460a8ca..c2bd97dfcc 100644 --- a/docs/source/markdown/options/cert-dir.md +++ b/docs/source/markdown/options/cert-dir.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> 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 +####> podman artifact pull, artifact push, build, container runlabel, create, farm build, image sign, 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 7c557fc3be..a5e16e5783 100644 --- a/docs/source/markdown/options/cgroups.md +++ b/docs/source/markdown/options/cgroups.md @@ -1,24 +1,12 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run +####> podman 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 747cb294ed..138dd68d57 100644 --- a/docs/source/markdown/options/creds.md +++ b/docs/source/markdown/options/creds.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> 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 +####> podman artifact pull, artifact push, build, container runlabel, create, farm build, 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 2b98acf8d9..ee7ed881bc 100644 --- a/docs/source/markdown/options/decryption-key.md +++ b/docs/source/markdown/options/decryption-key.md @@ -1,11 +1,7 @@ ####> This option file is used in: -####> podman artifact pull, build, create, farm build, podman-image.unit.5.md.in, pull, run +####> podman artifact pull, build, create, farm build, 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 d13b4b3ca3..8875645b93 100644 --- a/docs/source/markdown/options/device.md +++ b/docs/source/markdown/options/device.md @@ -1,18 +1,12 @@ ####> This option file is used in: -####> podman build, podman-container.unit.5.md.in, create, farm build, pod clone, pod create, run +####> podman build, 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 <>. 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). +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). 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 430959b7f2..f1b57de1a1 100644 --- a/docs/source/markdown/options/dns-option.container.md +++ b/docs/source/markdown/options/dns-option.container.md @@ -1,12 +1,7 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, podman-pod.unit.5.md.in, run +####> podman create, 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 {{{ '**DNSOption=**' if is_quadlet else '**--dns-option**' }}} -with {{{ '**Network=**' if is_quadlet else '**--network**' }}} that is set to **none** or **container:**_id_. +Set custom DNS options. Invalid if using **--dns-option** with **--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 80663a3d8e..345efd47c4 100644 --- a/docs/source/markdown/options/dns-option.image.md +++ b/docs/source/markdown/options/dns-option.image.md @@ -1,11 +1,7 @@ ####> This option file is used in: -####> podman build, podman-build.unit.5.md.in, farm build +####> podman build, 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 6f26aca056..589e3fa6d6 100644 --- a/docs/source/markdown/options/dns-search.container.md +++ b/docs/source/markdown/options/dns-search.container.md @@ -1,13 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run +####> podman 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 {{{ '**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. +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. diff --git a/docs/source/markdown/options/dns-search.image.md b/docs/source/markdown/options/dns-search.image.md index fd7f28bcd1..5e75afde53 100644 --- a/docs/source/markdown/options/dns-search.image.md +++ b/docs/source/markdown/options/dns-search.image.md @@ -1,11 +1,7 @@ ####> This option file is used in: -####> podman build, podman-build.unit.5.md.in, farm build +####> podman build, 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 01e11011e7..a02a18e6e5 100644 --- a/docs/source/markdown/options/dns.md +++ b/docs/source/markdown/options/dns.md @@ -1,19 +1,15 @@ ####> This option file is used in: -####> 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 +####> podman build, create, farm build, 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=.**' if is_quadlet else '**--dns**' }}} flag is necessary for every run. +is the case the **--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 e45ab49fc4..78fb05a818 100644 --- a/docs/source/markdown/options/entrypoint.md +++ b/docs/source/markdown/options/entrypoint.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run +####> podman 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. @@ -16,7 +12,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=**' if is_quadlet else '**--entrypoint=.**' }}}option allows a new +something else inside the container, the **--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 8d0157aa06..428cb78582 100644 --- a/docs/source/markdown/options/env-file.md +++ b/docs/source/markdown/options/env-file.md @@ -1,11 +1,7 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, exec, run +####> podman 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 2e52277f52..53b121cbc2 100644 --- a/docs/source/markdown/options/env-host.md +++ b/docs/source/markdown/options/env-host.md @@ -1,11 +1,7 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run +####> podman 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 b4dfad23af..d214291d53 100644 --- a/docs/source/markdown/options/env.image.md +++ b/docs/source/markdown/options/env.image.md @@ -1,17 +1,11 @@ ####> This option file is used in: -####> podman build, podman-build.unit.5.md.in, farm build +####> podman build, 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 74fb020a53..19bfc42ae4 100644 --- a/docs/source/markdown/options/env.md +++ b/docs/source/markdown/options/env.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, exec, run +####> podman 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 98bae64ad1..745e25226c 100644 --- a/docs/source/markdown/options/expose.md +++ b/docs/source/markdown/options/expose.md @@ -1,16 +1,12 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run +####> podman 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**' if is_quadlet else '**--expose=3300-3310**' }}}). +Expose a port or a range of ports (e.g. **--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 {{{ '**PublishPort=**' if is_quadlet else '**-p/--publish**' }}} option instead. +into the container use the **-p/--publish** option instead. diff --git a/docs/source/markdown/options/file.md b/docs/source/markdown/options/file.md index 2b589417bc..60c3aea5ad 100644 --- a/docs/source/markdown/options/file.md +++ b/docs/source/markdown/options/file.md @@ -1,31 +1,16 @@ ####> This option file is used in: -####> podman build, podman-build.unit.5.md.in, farm build +####> podman build, 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 {{{ 'File=-' if is_quadlet else '`-f -`' }}} causes -the Containerfile contents to be read from stdin. +Specifying the option `-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 04a8707499..5af1f5a8af 100644 --- a/docs/source/markdown/options/force-rm.md +++ b/docs/source/markdown/options/force-rm.md @@ -1,11 +1,7 @@ ####> This option file is used in: -####> podman build, podman-build.unit.5.md.in, farm build +####> podman build, 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 5b9f94691b..0f4cfa86b0 100644 --- a/docs/source/markdown/options/gidmap.container.md +++ b/docs/source/markdown/options/gidmap.container.md @@ -1,19 +1,12 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, podman-pod.unit.5.md.in, run +####> podman create, 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 %} -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 +Run the container in a new user namespace using the supplied GID mapping. This +option conflicts with the **--userns** and **--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=**' 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. +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. diff --git a/docs/source/markdown/options/group-add.md b/docs/source/markdown/options/group-add.md index 8e33c86bda..dadb8b4f1c 100644 --- a/docs/source/markdown/options/group-add.md +++ b/docs/source/markdown/options/group-add.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman build, podman-build.unit.5.md.in, podman-container.unit.5.md.in, create, farm build, run +####> podman build, 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 189274c5f4..cc1587796d 100644 --- a/docs/source/markdown/options/health-cmd.md +++ b/docs/source/markdown/options/health-cmd.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run, update +####> podman 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 71bcce75ff..2657187e59 100644 --- a/docs/source/markdown/options/health-interval.md +++ b/docs/source/markdown/options/health-interval.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run, update +####> podman 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 bda61b3046..91e91e269c 100644 --- a/docs/source/markdown/options/health-log-destination.md +++ b/docs/source/markdown/options/health-log-destination.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run, update +####> podman 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 900a4649a4..137d470830 100644 --- a/docs/source/markdown/options/health-max-log-count.md +++ b/docs/source/markdown/options/health-max-log-count.md @@ -1,11 +1,7 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run, update +####> podman 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 3ada0d76e9..1c3169c7f4 100644 --- a/docs/source/markdown/options/health-max-log-size.md +++ b/docs/source/markdown/options/health-max-log-size.md @@ -1,11 +1,7 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run, update +####> podman 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 cf82c0668b..6c539e7332 100644 --- a/docs/source/markdown/options/health-on-failure.md +++ b/docs/source/markdown/options/health-on-failure.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run, update +####> podman 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 07e23351f6..4060fb30ed 100644 --- a/docs/source/markdown/options/health-retries.md +++ b/docs/source/markdown/options/health-retries.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run, update +####> podman 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 9a6a61492d..302af88072 100644 --- a/docs/source/markdown/options/health-start-period.md +++ b/docs/source/markdown/options/health-start-period.md @@ -1,23 +1,16 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run, update +####> podman 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 {{{ '`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`' }}}. +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`. 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 20e3debdd8..67b2db32ad 100644 --- a/docs/source/markdown/options/health-startup-cmd.md +++ b/docs/source/markdown/options/health-startup-cmd.md @@ -1,16 +1,11 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run, update +####> podman 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 -{{{ '`HealthCmd=`' if is_quadlet else '`--health-cmd`' }}} option) is also set. +used when a regular healthcheck (from the container's image or the **--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 0149573cbc..052d703a78 100644 --- a/docs/source/markdown/options/health-startup-interval.md +++ b/docs/source/markdown/options/health-startup-interval.md @@ -1,11 +1,7 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run, update +####> podman 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 30401b87aa..2a0f9fdf90 100644 --- a/docs/source/markdown/options/health-startup-retries.md +++ b/docs/source/markdown/options/health-startup-retries.md @@ -1,11 +1,7 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run, update +####> podman 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 9577cf73b6..e1f911b215 100644 --- a/docs/source/markdown/options/health-startup-success.md +++ b/docs/source/markdown/options/health-startup-success.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run, update +####> podman 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 671ecf5db5..deffa14025 100644 --- a/docs/source/markdown/options/health-startup-timeout.md +++ b/docs/source/markdown/options/health-startup-timeout.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run, update +####> podman 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 8bbe0c9b48..458442508b 100644 --- a/docs/source/markdown/options/health-timeout.md +++ b/docs/source/markdown/options/health-timeout.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run, update +####> podman 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 4c1c108b9b..ab7e76c9ed 100644 --- a/docs/source/markdown/options/hostname.container.md +++ b/docs/source/markdown/options/hostname.container.md @@ -1,17 +1,13 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run +####> podman 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=`' if is_quadlet else '`--pod`' }}} is given and the pod shares the same UTS namespace +(default). If `--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 -{{{ '**AddHost=**' if is_quadlet else '**--add-host**' }}} option). +**--add-host** option). diff --git a/docs/source/markdown/options/init.md b/docs/source/markdown/options/init.md index c8e8dc8da1..5a9fb2f29e 100644 --- a/docs/source/markdown/options/init.md +++ b/docs/source/markdown/options/init.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run +####> podman 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 a5997dd0c3..d3c865a88d 100644 --- a/docs/source/markdown/options/ip.md +++ b/docs/source/markdown/options/ip.md @@ -1,20 +1,12 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, pod create, podman-pod.unit.5.md.in, run +####> podman create, pod create, 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**' 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_**' }}}. +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_**. 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=**' if is_quadlet else '**--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** 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 67e6302c4a..a2dd619f72 100644 --- a/docs/source/markdown/options/ip6.md +++ b/docs/source/markdown/options/ip6.md @@ -1,20 +1,12 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, pod create, podman-pod.unit.5.md.in, run +####> podman create, pod create, 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**' 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_**' }}}. +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_**. The address must be within the network's IPv6 address pool. -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. +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. diff --git a/docs/source/markdown/options/label.image.md b/docs/source/markdown/options/label.image.md index fa930c5b79..d119c43625 100644 --- a/docs/source/markdown/options/label.image.md +++ b/docs/source/markdown/options/label.image.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman build, podman-build.unit.5.md.in, farm build +####> podman build, 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 ff19f3f94c..af88b3f95f 100644 --- a/docs/source/markdown/options/label.md +++ b/docs/source/markdown/options/label.md @@ -1,11 +1,7 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, pod clone, pod create, podman-pod.unit.5.md.in, run +####> podman create, pod clone, pod create, 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 81b3f73918..d99f229c5e 100644 --- a/docs/source/markdown/options/log-driver.md +++ b/docs/source/markdown/options/log-driver.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, podman-kube.unit.5.md.in, run +####> podman create, 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 0356425545..9cb1402ae3 100644 --- a/docs/source/markdown/options/log-opt.md +++ b/docs/source/markdown/options/log-opt.md @@ -1,24 +1,20 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, kube play, run +####> podman 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. {{{ '**LogOpt=path=/var/log/container/mycontainer.json**' if is_quadlet else '**--log-opt path=/var/log/container/mycontainer.json**' }}}); + (e.g. **--log-opt path=/var/log/container/mycontainer.json**); **max-size**: specify a max size of the log file - (e.g. {{{ '**LogOpt=max-size=10mb**' if is_quadlet else '**--log-opt max-size=10mb**' }}}); + (e.g. **--log-opt max-size=10mb**); **tag**: specify a custom log tag for the container - (e.g. {{{ '**LogOpt=tag="{{.ImageName}}"**' if is_quadlet else '**--log-opt tag="{{.ImageName}}"**' }}}. + (e.g. **--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 bfe6194340..dd53d8d8e6 100644 --- a/docs/source/markdown/options/memory.md +++ b/docs/source/markdown/options/memory.md @@ -1,18 +1,14 @@ ####> This option file is used in: -####> podman build, container clone, podman-container.unit.5.md.in, create, farm build, pod clone, pod create, run, update +####> podman build, container clone, 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 {{{ '**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 +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 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 deleted file mode 100644 index c5a4a3c7bb..0000000000 --- a/docs/source/markdown/options/module.md +++ /dev/null @@ -1,13 +0,0 @@ -####> 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 29e394c116..bf03d05099 100644 --- a/docs/source/markdown/options/mount.md +++ b/docs/source/markdown/options/mount.md @@ -1,24 +1,11 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run +####> podman 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 8eec83e353..b7b454bc0b 100644 --- a/docs/source/markdown/options/name.container.md +++ b/docs/source/markdown/options/name.container.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run +####> podman 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. @@ -17,9 +13,8 @@ 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 {{{ '**ContainerName=**' if is_quadlet else '**--name**' }}}, -Podman generates a random string name. The name can +container using **--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 -{{{ '**AddHost=**' if is_quadlet else '**--add-host**' }}} option). +**--add-host** option). diff --git a/docs/source/markdown/options/network-alias.md b/docs/source/markdown/options/network-alias.md index 29a9d0f83d..3c0ed9c9db 100644 --- a/docs/source/markdown/options/network-alias.md +++ b/docs/source/markdown/options/network-alias.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, pod create, podman-pod.unit.5.md.in, run +####> podman create, pod create, 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 2aab4b02cd..f03a38d9ca 100644 --- a/docs/source/markdown/options/network.image.md +++ b/docs/source/markdown/options/network.image.md @@ -1,21 +1,11 @@ ####> This option file is used in: -####> podman build, podman-build.unit.5.md.in, farm build +####> podman build, 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 381be6e588..eb0d304f4a 100644 --- a/docs/source/markdown/options/network.md +++ b/docs/source/markdown/options/network.md @@ -1,28 +1,11 @@ ####> This option file is used in: -####> 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 +####> podman create, kube play, pod create, 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 50866c1017..aeb0bdbe5d 100644 --- a/docs/source/markdown/options/os.pull.md +++ b/docs/source/markdown/options/os.pull.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman create, podman-image.unit.5.md.in, pull, run +####> podman create, 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 69dfb7108c..d59f6c82b0 100644 --- a/docs/source/markdown/options/pids-limit.md +++ b/docs/source/markdown/options/pids-limit.md @@ -1,11 +1,7 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run, update +####> podman 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 f644a70500..05ec22f197 100644 --- a/docs/source/markdown/options/publish.md +++ b/docs/source/markdown/options/publish.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, podman-kube.unit.5.md.in, pod create, podman-pod.unit.5.md.in, run +####> podman create, pod create, 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 f556dd17e8..112e612210 100644 --- a/docs/source/markdown/options/pull.image.md +++ b/docs/source/markdown/options/pull.image.md @@ -2,11 +2,7 @@ ####> 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 63cc6b0ac2..e8c2090aba 100644 --- a/docs/source/markdown/options/pull.md +++ b/docs/source/markdown/options/pull.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-build.unit.5.md.in, podman-container.unit.5.md.in, create, run +####> podman 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 57e83a3ba7..246dff0d87 100644 --- a/docs/source/markdown/options/read-only-tmpfs.md +++ b/docs/source/markdown/options/read-only-tmpfs.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run +####> podman 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**. @@ -17,17 +13,14 @@ 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 {{{ '**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 +When **--read-only=true** and **--read-only-tmpfs=true** additional tmpfs are mounted on the /tmp, /run, and /var/tmp directories. -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 +When **--read-only=true** and **--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 {{{ '**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. +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. diff --git a/docs/source/markdown/options/read-only.md b/docs/source/markdown/options/read-only.md index efac96c678..3c16f65a39 100644 --- a/docs/source/markdown/options/read-only.md +++ b/docs/source/markdown/options/read-only.md @@ -1,15 +1,10 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run +####> podman 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 {{{ '**ReadOnly=**' if is_quadlet else '**--read-only**' }}} flag, -the containers root filesystem are mounted read-only prohibiting any writes. +to write files anywhere. By specifying the **--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 94237b83cc..74e4e7814f 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-quadlet**(7) and **systemd.service**(5). +See **podman-systemd.unit**(5) and **systemd.service**(5). diff --git a/docs/source/markdown/options/retry-delay.md b/docs/source/markdown/options/retry-delay.md index a8b7a3b72e..14c652ffb1 100644 --- a/docs/source/markdown/options/retry-delay.md +++ b/docs/source/markdown/options/retry-delay.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> 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 +####> podman artifact pull, artifact push, build, create, farm build, 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 c07dd2307f..08c8c263e3 100644 --- a/docs/source/markdown/options/retry.md +++ b/docs/source/markdown/options/retry.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> 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 +####> podman artifact pull, artifact push, build, create, farm build, 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 495278344f..a30e878ff7 100644 --- a/docs/source/markdown/options/rootfs.md +++ b/docs/source/markdown/options/rootfs.md @@ -1,19 +1,11 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run +####> podman 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 bc5bf48fdf..46f8ff0f97 100644 --- a/docs/source/markdown/options/secret.image.md +++ b/docs/source/markdown/options/secret.image.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman build, podman-build.unit.5.md.in, farm build +####> podman build, 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 c2d1a9e604..7b8f6e0397 100644 --- a/docs/source/markdown/options/secret.md +++ b/docs/source/markdown/options/secret.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run +####> podman 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 fc9260964c..0f51a3f193 100644 --- a/docs/source/markdown/options/shm-size.md +++ b/docs/source/markdown/options/shm-size.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman build, podman-container.unit.5.md.in, create, farm build, pod clone, pod create, podman-pod.unit.5.md.in, run +####> podman build, 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 %} -### `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 cf77adb072..efbca84cf7 100644 --- a/docs/source/markdown/options/stop-signal.md +++ b/docs/source/markdown/options/stop-signal.md @@ -1,11 +1,7 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run +####> podman 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 c84651b06e..a61bad440d 100644 --- a/docs/source/markdown/options/stop-timeout.md +++ b/docs/source/markdown/options/stop-timeout.md @@ -1,16 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run +####> podman 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 f11c25914b..d31cb7ea79 100644 --- a/docs/source/markdown/options/subgidname.md +++ b/docs/source/markdown/options/subgidname.md @@ -1,14 +1,9 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, pod clone, pod create, podman-pod.unit.5.md.in, run +####> podman create, pod clone, pod create, 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=**' if is_quadlet else '**--userns**' }}} and {{{ '**GIDMap=**' if is_quadlet else '**--gidmap**' }}}. - +This flag conflicts with **--userns** and **--gidmap**. diff --git a/docs/source/markdown/options/subuidname.md b/docs/source/markdown/options/subuidname.md index ebe0f65612..ac3e1f372a 100644 --- a/docs/source/markdown/options/subuidname.md +++ b/docs/source/markdown/options/subuidname.md @@ -1,13 +1,9 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, pod clone, pod create, podman-pod.unit.5.md.in, run +####> podman create, pod clone, pod create, 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=**' if is_quadlet else '**--userns**' }}} and {{{ '**UIDMap=**' if is_quadlet else '**--uidmap**' }}}. +This flag conflicts with **--userns** and **--uidmap**. diff --git a/docs/source/markdown/options/sysctl.md b/docs/source/markdown/options/sysctl.md index 4e4f884e8f..1027d5640f 100644 --- a/docs/source/markdown/options/sysctl.md +++ b/docs/source/markdown/options/sysctl.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, pod clone, pod create, run +####> podman 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 a35e6b2fb4..63a24e59a5 100644 --- a/docs/source/markdown/options/tag.md +++ b/docs/source/markdown/options/tag.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman build, podman-build.unit.5.md.in, farm build +####> podman build, 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 83c2a8dacc..5c5646a915 100644 --- a/docs/source/markdown/options/target.md +++ b/docs/source/markdown/options/target.md @@ -1,11 +1,7 @@ ####> This option file is used in: -####> podman build, podman-build.unit.5.md.in, farm build +####> podman build, 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 0cb60d2e5d..3c15a77a84 100644 --- a/docs/source/markdown/options/tls-verify.md +++ b/docs/source/markdown/options/tls-verify.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> 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 +####> 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 ####> 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 4f38eead6c..11c62756ae 100644 --- a/docs/source/markdown/options/tmpfs.md +++ b/docs/source/markdown/options/tmpfs.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run +####> podman 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 61255b88bc..bfe18f0e6a 100644 --- a/docs/source/markdown/options/tz.md +++ b/docs/source/markdown/options/tz.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run +####> podman 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 39ed4729b2..24a3a6615c 100644 --- a/docs/source/markdown/options/uidmap.container.md +++ b/docs/source/markdown/options/uidmap.container.md @@ -1,15 +1,11 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run +####> podman 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=**' if is_quadlet else '**--userns**' }}} and {{{ '**SubUIDMap=**' if is_quadlet else '**--subuidname**' }}} options. This +option conflicts with the **--userns** and **--subuidname** options. This option provides a way to map host UIDs to container UIDs. It can be passed several times to map different ranges. @@ -24,7 +20,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=**' if is_quadlet else '**--uidmap**' }}} +When **podman <>** is called by a privileged user, the option **--uidmap** works as a direct mapping between host UIDs and container UIDs. host UID -> container UID @@ -48,7 +44,7 @@ happens over two mapping steps: host UID -> intermediate UID -> container UID -The {{{ '**UIDMap=**' if is_quadlet else '**--uidmap**' }}} option only influences the second mapping step. +The **--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. @@ -66,7 +62,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=**' if is_quadlet else '**--uidmap**' }}}. +The second mapping step is configured with **--uidmap**. If for example _amount_ is **5** the second mapping step looks like: @@ -91,7 +87,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=**' if is_quadlet else '**--uidmap**' }}} or {{{ '**GIDMap=**' if is_quadlet else '**--gidmap**' }}} +As a rootless user, the given host ID in **--uidmap** or **--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`, @@ -141,7 +137,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=**' if is_quadlet else '**--uidmap**' }}} or {{{ '**GIDMap=**' if is_quadlet else '**--gidmap**' }}} is given, +For convenience, if only one of **--uidmap** or **--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 @@ -156,20 +152,20 @@ For instance given the command podman <> --gidmap "0:0:1000" --gidmap "g2000:2000:1" -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**' }}}, +Since no **--uidmap** is given, the **--gidmap** is copied to **--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=**' if is_quadlet else '**--uidmap**' }}}. +not copied to **--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*"**' if is_quadlet else '**--gidmap "+g*container_gid*:@*host_gid*"**' }}} +This can be done with **--gidmap "+g*container_gid*:@*host_gid*"** Where: @@ -180,9 +176,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**' if is_quadlet else '**--gidmap=+g100000:@2000**' }}}. +the user can map the group into the container with: **--gidmap=+g100000:@2000**. -If this mapping is combined with the option, {{{ '**GroupAdd=keep-groups**' if is_quadlet else '**--group-add=keep-groups**' }}}, the +If this mapping is combined with the option, **--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. @@ -192,9 +188,9 @@ inside the container. `No subordinate UIDs` Even if a user does not have any subordinate UIDs in _/etc/subuid_, -{{{ '**UIDMap=**' if is_quadlet else '**--uidmap**' }}} can be used to map the normal UID of the user to a +**--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=**' 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. +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. diff --git a/docs/source/markdown/options/uidmap.pod.md b/docs/source/markdown/options/uidmap.pod.md index 1680927ec6..04f7c229c7 100644 --- a/docs/source/markdown/options/uidmap.pod.md +++ b/docs/source/markdown/options/uidmap.pod.md @@ -1,14 +1,10 @@ ####> This option file is used in: -####> podman pod clone, pod create, podman-pod.unit.5.md.in +####> podman pod clone, pod create ####> 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=.**' if is_quadlet else '**--userns**' }}} and {{{ '**SubUIDMap=.**' if is_quadlet else '**--subuidname**' }}} options. This +option conflicts with the **--userns** and **--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 7b827cdeb0..a387b2f02a 100644 --- a/docs/source/markdown/options/ulimit.md +++ b/docs/source/markdown/options/ulimit.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, run +####> podman 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 c3ea5e52b0..2307fcc9b6 100644 --- a/docs/source/markdown/options/user.md +++ b/docs/source/markdown/options/user.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, exec, run +####> podman 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 0380f7b276..b128546f1c 100644 --- a/docs/source/markdown/options/userns.container.md +++ b/docs/source/markdown/options/userns.container.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, kube play, podman-kube.unit.5.md.in, run +####> podman create, kube play, 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. @@ -18,7 +14,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=**' if is_quadlet else '**--gidmap**' }}}, {{{ '**UIDMap=**' if is_quadlet else '**--uidmap**' }}}, {{{ '**SubUIDMap=**' if is_quadlet else '**-**--subuidname****' }}} and {{{ '**SubGIDMap=**' if is_quadlet else '**-**--subgidname****' }}}. +This option is incompatible with **--gidmap**, **--uidmap**, **--subuidname** and **--subgidname**. Rootless user --userns=Key mappings: @@ -52,7 +48,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=**' if is_quadlet else '**--uidmap**' }}}. +For details see **--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 2da8aa430a..82040b709c 100644 --- a/docs/source/markdown/options/userns.pod.md +++ b/docs/source/markdown/options/userns.pod.md @@ -1,16 +1,12 @@ ####> This option file is used in: -####> podman pod clone, pod create, podman-pod.unit.5.md.in +####> podman pod clone, pod create ####> 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**' if is_quadlet else '**--userns=Key**' }}} mappings: +Rootless user --userns=Key mappings: Key | Host User | Container User ----------|---------------|--------------------- @@ -26,7 +22,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=' if is_quadlet else '--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=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 f49dc9ee53..522e74bf1a 100644 --- a/docs/source/markdown/options/variant.container.md +++ b/docs/source/markdown/options/variant.container.md @@ -1,11 +1,7 @@ ####> This option file is used in: -####> podman create, podman-image.unit.5.md.in, pull, run +####> podman create, 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 80d5edd928..f77a99c4b8 100644 --- a/docs/source/markdown/options/volume.image.md +++ b/docs/source/markdown/options/volume.image.md @@ -2,21 +2,11 @@ ####> 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 e6a4441b54..1f58237b13 100644 --- a/docs/source/markdown/options/volume.md +++ b/docs/source/markdown/options/volume.md @@ -1,12 +1,8 @@ ####> This option file is used in: -####> 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 +####> podman create, pod clone, pod create, 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 @@ -17,12 +13,6 @@ 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 87a8a2d73a..70a63eba74 100644 --- a/docs/source/markdown/options/workdir.md +++ b/docs/source/markdown/options/workdir.md @@ -1,15 +1,11 @@ ####> This option file is used in: -####> podman podman-container.unit.5.md.in, create, exec, run +####> podman 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 {{{ '**WokingDir=**' if is_quadlet else '**-w**' }}} option. +can override the working directory by using the **-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 75b1c27f45..1963867362 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-quadlet(7)` on how to run Podman under systemd. +Please refer to `podman-systemd.unit(5)` 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-quadlet(7)` 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-systemd.unit(5)` 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-quadlet(7)` 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-systemd.unit(5)` 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-quadlet(7)](podman-quadlet.7.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-systemd.unit(5)](podman-systemd.unit.5.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 deleted file mode 100644 index 6efac39aa0..0000000000 --- a/docs/source/markdown/podman-build.unit.5.md.in +++ /dev/null @@ -1,229 +0,0 @@ -% 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 deleted file mode 100644 index 4ee555a749..0000000000 --- a/docs/source/markdown/podman-container.unit.5.md.in +++ /dev/null @@ -1,559 +0,0 @@ -% 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 2d5eb34dad..cd6c637bd7 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-quadlet.7.md) +Note: **podman generate systemd** is deprecated. We recommend using [Quadlet](podman-systemd.unit.5.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-quadlet(7)](podman-quadlet.7.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-systemd.unit(5)](podman-systemd.unit.5.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 deleted file mode 100644 index 512e9f4702..0000000000 --- a/docs/source/markdown/podman-image.unit.5.md.in +++ /dev/null @@ -1,199 +0,0 @@ -% 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 deleted file mode 100644 index 075a97cd22..0000000000 --- a/docs/source/markdown/podman-kube.unit.5.md.in +++ /dev/null @@ -1,173 +0,0 @@ -% 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 deleted file mode 100644 index 510eec3596..0000000000 --- a/docs/source/markdown/podman-network.unit.5.md.in +++ /dev/null @@ -1,214 +0,0 @@ -% 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 deleted file mode 100644 index efbae70b6a..0000000000 --- a/docs/source/markdown/podman-pod.unit.5.md.in +++ /dev/null @@ -1,181 +0,0 @@ -% 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 deleted file mode 100644 index b7e597c461..0000000000 --- a/docs/source/markdown/podman-quadlet-basic-usage.7.md +++ /dev/null @@ -1,218 +0,0 @@ -% 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 deleted file mode 100644 index 0d2c786a81..0000000000 --- a/docs/source/markdown/podman-quadlet.7.md +++ /dev/null @@ -1,94 +0,0 @@ -% 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 new file mode 100644 index 0000000000..480f08eb22 --- /dev/null +++ b/docs/source/markdown/podman-systemd.unit.5.md @@ -0,0 +1,2279 @@ +% 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 deleted file mode 100644 index 036a92d26f..0000000000 --- a/docs/source/markdown/podman-volume.unit.5.md.in +++ /dev/null @@ -1,177 +0,0 @@ -% 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 1c5f32a553..a4ca55548c 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-quadlet(7)](podman-quadlet.7.md)** +**[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)** ## HISTORY May 2023, Originally compiled by Dan Walsh diff --git a/hack/markdown-preprocess b/hack/markdown-preprocess index 8c37a08ee6..11fa1ea9e1 100755 --- a/hack/markdown-preprocess +++ b/hack/markdown-preprocess @@ -11,7 +11,6 @@ import glob import os import re import sys -from jinja2 import Template class Preprocessor(): """ @@ -41,24 +40,18 @@ 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: - 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 + # '@@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) os.chmod(outfile_tmp, 0o444) os.rename(outfile_tmp, outfile) @@ -94,7 +87,7 @@ class Preprocessor(): else: os.unlink(tmpfile) - def insert_file(self, fh_out, path: str, is_quadlet=False): + def insert_file(self, fh_out, path: str): """ Reads one option file, writes it out to the given output filehandle """ @@ -105,20 +98,13 @@ 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: - 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(): + for opt_line in fh_included: 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 + '\n') + fh_out.write(opt_line) fh_out.write("\n[//]: # (END included file " + path + ")\n") def podman_subcommand(self, full=None) -> str: @@ -131,9 +117,6 @@ 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 ba615648b6..1064c20f2f 100644 --- a/rpm/podman.spec +++ b/rpm/podman.spec @@ -99,7 +99,6 @@ 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