diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore index 3ab040378b..a48ec92172 100644 --- a/docs/source/markdown/.gitignore +++ b/docs/source/markdown/.gitignore @@ -76,4 +76,3 @@ 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 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/options/README.md b/docs/source/markdown/options/README.md index cb1844f7f1..f409afc756 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 478e050418..3a14116899 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 edff7c3fab..c2fc50de11 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 1417dcc054..b887ee3242 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 20806f4b17..d25dd0253e 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 6999d0c98e..101b17fcb1 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 7696578f12..007a95ed14 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 ada47189f8..b91a669297 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 c9333fae56..99ce9aaa36 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 b32460a8ca..befefa7ab3 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 7c557fc3be..bdcbf94e12 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 747cb294ed..740af7d40e 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 2b98acf8d9..589b7ea4b1 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 d13b4b3ca3..3dcad9d976 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 430959b7f2..c3847301d5 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 80663a3d8e..ae3b7a6572 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 6f26aca056..75c1e9f5f9 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, run +####> podman podman-container.unit.5.md.in, create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. -{% if is_quadlet %} +<< 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 fd7f28bcd1..f1ccefe59d 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 01e11011e7..399a715a4a 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 e45ab49fc4..5be09ff10f 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 8d0157aa06..adec9ba9e1 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 2e52277f52..9b48379130 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 b4dfad23af..73c4467a9d 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, 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 %} +<< 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 74fb020a53..297ef3ed5a 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-container.unit.5.md.in, create, exec, run +####> podman podman-build.unit.5.md.in, 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 98bae64ad1..f896a8baac 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 2b589417bc..e02b79b16f 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 04a8707499..c1e43c7b0a 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 5b9f94691b..ad9297bf09 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 >> -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=**' 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 8e33c86bda..a262c1f9f1 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 189274c5f4..d97ad6ee07 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 71bcce75ff..8e2b04f3f7 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 bda61b3046..e1b4e1d591 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 900a4649a4..d8cd5d1ede 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 3ada0d76e9..5403ad5c6c 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 cf82c0668b..7936537741 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 07e23351f6..1518965760 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 9a6a61492d..a5e587c535 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 20e3debdd8..de81cd6264 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 0149573cbc..9f0f31cc8f 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 30401b87aa..c35be5c286 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 9577cf73b6..54995fa791 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 671ecf5db5..9fdf007c83 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 8bbe0c9b48..5ceae0fe84 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 4c1c108b9b..f986049b16 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, run +####> podman podman-container.unit.5.md.in, create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. -{% if is_quadlet %} +<< 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 ac15af4382..fec9e520a3 100644 --- a/docs/source/markdown/options/http-proxy.md +++ b/docs/source/markdown/options/http-proxy.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman build, create, farm build, run +####> podman build, 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 >> +### `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 c8e8dc8da1..c0ba3fbec6 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 %} -### `Init=` -{% else %} +<< if is_quadlet >> +### `RunInit=` +<< 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 a5997dd0c3..efbc5217d8 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 67e6302c4a..04ec81b068 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 fa930c5b79..9a11a4bd0a 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 ff19f3f94c..9f04e81c08 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 81b3f73918..e0b02da357 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 0356425545..31ed80f38f 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 bfe6194340..a1a2a2b55e 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 c5a4a3c7bb..1b09d7470c 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 29e394c116..b12d970e51 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 8eec83e353..8c40bc7b51 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 29a9d0f83d..887dc30d21 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 2aab4b02cd..25c2c3cc8a 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 381be6e588..d2af235c4f 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 50866c1017..af80fb622d 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 69dfb7108c..ac589d7a28 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 f644a70500..9562d52eb4 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 f556dd17e8..074810b08d 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 63cc6b0ac2..95570442fd 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 57e83a3ba7..18841c85bd 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 efac96c678..bc84389321 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 a8b7a3b72e..52d8cd4368 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 c07dd2307f..f110eb47fe 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 495278344f..3ee275fe5b 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 bc5bf48fdf..7057c85fed 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 c2d1a9e604..42f246ddd3 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 fc9260964c..822c912a2c 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 cf77adb072..19b525ec4d 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 c84651b06e..3027a0a18a 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 f11c25914b..65ee9d00cc 100644 --- a/docs/source/markdown/options/subgidname.md +++ b/docs/source/markdown/options/subgidname.md @@ -2,13 +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 >> ### `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 ebe0f65612..4f46c9aac1 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 4e4f884e8f..7c987b550c 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,6 +22,7 @@ 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 a35e6b2fb4..6cce46e5ec 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 %} -### `TaImageTag=imageName` -{% else %} +<< if is_quadlet >> +### `ImageTag=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 83c2a8dacc..abb2d10197 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 0cb60d2e5d..f4ba079d75 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 4f38eead6c..0426c89c78 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 61255b88bc..fae294362a 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 39ed4729b2..84816bc8a2 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 1680927ec6..39cddfabf6 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 7b827cdeb0..b6e2920b39 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 c3ea5e52b0..11130bf908 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 0380f7b276..6d7fe205e0 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 2da8aa430a..f5ba4ce5b9 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 f49dc9ee53..8202a1a436 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 80d5edd928..e339209514 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 e6a4441b54..150e484bf7 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 87a8a2d73a..734edc4a3b 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 6efac39aa0..d995494f05 100644 --- a/docs/source/markdown/podman-build.unit.5.md.in +++ b/docs/source/markdown/podman-build.unit.5.md.in @@ -42,25 +42,6 @@ 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: @@ -112,7 +93,7 @@ This is equivalent to the `--annotation` option of `podman build`. @@option quadlet:dns-search.image -@@option quadlet:env.image +@@option quadlet:env @@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 4ee555a749..37ca7dd3f8 100644 --- a/docs/source/markdown/podman-container.unit.5.md.in +++ b/docs/source/markdown/podman-container.unit.5.md.in @@ -33,23 +33,6 @@ 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: @@ -93,6 +76,7 @@ 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 | @@ -254,6 +238,8 @@ 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 512e9f4702..3179bf0730 100644 --- a/docs/source/markdown/podman-image.unit.5.md.in +++ b/docs/source/markdown/podman-image.unit.5.md.in @@ -20,27 +20,10 @@ 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: @@ -146,27 +129,6 @@ 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 075a97cd22..a1176fc230 100644 --- a/docs/source/markdown/podman-kube.unit.5.md.in +++ b/docs/source/markdown/podman-kube.unit.5.md.in @@ -27,23 +27,6 @@ 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: @@ -170,4 +153,5 @@ 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 510eec3596..844130c5f7 100644 --- a/docs/source/markdown/podman-network.unit.5.md.in +++ b/docs/source/markdown/podman-network.unit.5.md.in @@ -26,23 +26,6 @@ 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 efbae70b6a..e09087dd38 100644 --- a/docs/source/markdown/podman-pod.unit.5.md.in +++ b/docs/source/markdown/podman-pod.unit.5.md.in @@ -19,23 +19,6 @@ 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: @@ -77,6 +60,8 @@ 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**. @@ -97,7 +82,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 @@ -178,4 +163,3 @@ 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 b7e597c461..9097ee628b 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 0d2c786a81..0aa1df5abb 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)**. -- **`.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)**. +- **`.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). Each file is mapped to a corresponding `.service` unit with a predictable naming pattern, typically appending `-.service` to the unit base name. @@ -77,6 +77,26 @@ 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 8c37a08ee6..a82029f534 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(): """ @@ -24,6 +23,100 @@ 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 @@ -105,12 +198,7 @@ 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') - ) + rendered = self.render(fh_included.read(), {"is_quadlet": is_quadlet}) for opt_line in rendered.splitlines(): if opt_line.startswith('####>'): continue diff --git a/hack/xref-quadlet-docs b/hack/xref-quadlet-docs index 022f2c4898..d20246d0e4 100755 --- a/hack/xref-quadlet-docs +++ b/hack/xref-quadlet-docs @@ -19,7 +19,16 @@ our $VERSION = '0.1'; # BEGIN user-customizable section our $Go = 'pkg/systemd/quadlet/quadlet.go'; -our $Doc = 'docs/source/markdown/podman-systemd.unit.5.md'; +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", +); # END user-customizable section ############################################################################### @@ -35,7 +44,7 @@ $ME cross-checks quadlet documentation between the Go source[Go] and the man page[MD]. [Go]: $Go - [MD]: $Doc + [MD]: @Docs We check that: @@ -95,7 +104,7 @@ sub main { my $true_keys = read_go($Go); # Read md file, compare against Truth - crossref_doc($Doc, $true_keys); + crossref_docs(\@Docs, $true_keys); exit $errs; } @@ -141,19 +150,17 @@ sub read_go { } ################## -# crossref_doc # Read the markdown page, cross-check against Truth +# crossref_docs # Read the markdown pages, cross-check against Truth ################## -sub crossref_doc { - my $path = shift; # in: path to .md file +sub crossref_docs { + my $paths_ref = shift; # in: array with paths 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 @@ -166,85 +173,86 @@ sub crossref_doc { } }; - # Main loop: read the docs line by line - while (my $line = <$fh>) { - chomp $line; + # foreach loop + foreach my $path (@$paths_ref) { + open my $fh, '<', $path + or die "$ME: Cannot read $path: $!\n";; - # 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"; + my $new_unit = $path; + $crossref_against_table->(); + $unit = $new_unit; - $crossref_against_table->(); + # Reset, because each section has its own table & blocks + @found_in_table = (); + @described = (); + $read_first_table = 0; - $unit = $new_unit; - # Reset, because each section has its own table & blocks - @found_in_table = (); - @described = (); - next; - } + # Main loop: read the docs line by line + while (my $line = <$fh>) { + chomp $line; - # Table line - if ($line =~ s/^\|\s+//) { - next if $line =~ /^\*\*/; # title - next if $line =~ /^-----/; # divider + # Table line + if ($read_first_table == 0 && $line =~ s/^\|\s+//) { + next if $line =~ /^\*\*/; # title + next if $line =~ /^-----/; # divider - if ($line =~ /^([A-Z][A-Za-z6]+)=/) { + 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]+)=.*`/) { my $key = $1; - grep { $_ eq $key } @$true_keys - or warn "$ME: $path:$.: unknown key '$key' (not present in $Go)\n"; + $read_first_table = 1; - # 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"; + # 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"; } } - push @found_in_table, $key; + 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}++; } - else { - warn "$ME: $path:$.: cannot grok table line '$line'\n"; - } } - # 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; } - 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 $md_basename\n"; + or warn "$ME: undocumented key: '$k' not found anywhere in @$paths_ref\n"; } } 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