diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore index 3dd3b2e7d4..a02522d0af 100644 --- a/docs/source/markdown/.gitignore +++ b/docs/source/markdown/.gitignore @@ -34,6 +34,7 @@ podman-manifest-create.1.md podman-manifest-inspect.1.md podman-manifest-push.1.md podman-mount.1.md +podman-network-create.1.md podman-network-ls.1.md podman-network-reload.1.md podman-pause.1.md @@ -69,3 +70,11 @@ podman-unpause.1.md podman-update.1.md podman-volume-ls.1.md podman-wait.1.md +podman-build.unit.5.md +podman-container.unit.5.md +podman-image.unit.5.md +podman-kube.unit.5.md +podman-kube-down.1.md +podman-network.unit.5.md +podman-pod.unit.5.md +podman-volume.unit.5.md diff --git a/docs/source/markdown/options/README.md b/docs/source/markdown/options/README.md index bc3f5bfccb..1ca8400298 100644 --- a/docs/source/markdown/options/README.md +++ b/docs/source/markdown/options/README.md @@ -17,6 +17,8 @@ mechanism: ``` @@option foo ! includes options/foo.md +@@option quadlet:foo ! includes options/foo.md with `is_quadlet=True` + ! See "Jinja2 Templating" below. ``` The tool that does this is `hack/markdown-preprocess`. It is a python @@ -25,6 +27,41 @@ file, this script creates a `.md` file that can then be read by `go-md2man`, `sphinx`, anything that groks markdown. This runs as part of `make docs`. +Conditionals +============ + +Some options are used as both Podman command line options and Quadlet +options. To reduce the duplication, the very limited conditionals are +supported in the Markdown files. + +The basic condition: + +``` +<< if variable >> +... +<< endif >> +``` + +It is possible to use the `not` keyword and `else` keyword: + +``` +<< if not variable >> +... +<< else >> +... +<< endif >> +``` + +It is also possible to do inline conditions like this: + +``` +<< "foo" if variable else "bar" >> +``` + +The following variables are available for Jinja2 Templates: + +- `is_quadlet`: True if file is imported using `@@option quadlet:foo`. + Special Substitutions ===================== diff --git a/docs/source/markdown/options/add-host.md b/docs/source/markdown/options/add-host.md index 316d635d5c..3a14116899 100644 --- a/docs/source/markdown/options/add-host.md +++ b/docs/source/markdown/options/add-host.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman build, create, farm build, pod create, run +####> podman build, podman-container.unit.5.md.in, create, farm build, pod create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `AddHost=hostname[;hostname[;...]]:ip` +<< else >> #### **--add-host**=*hostname[;hostname[;...]]*:*ip* +<< endif >> Add a custom host-to-IP mapping to the <>'s `/etc/hosts` file. diff --git a/docs/source/markdown/options/all-tags.md b/docs/source/markdown/options/all-tags.md new file mode 100644 index 0000000000..6da4e5e5f8 --- /dev/null +++ b/docs/source/markdown/options/all-tags.md @@ -0,0 +1,13 @@ +####> This option file is used in: +####> podman podman-image.unit.5.md.in, pull +####> If file is edited, make sure the changes +####> are applicable to all of those. +<< if is_quadlet >> +### `AllTags=true` +<< else >> +#### **--all-tags**, **-a** +<< endif >> + +All tagged images in the repository are pulled. + +*IMPORTANT: When using the all-tags flag, Podman does not iterate over the search registries in the **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)** but always uses docker.io for unqualified image names.* diff --git a/docs/source/markdown/options/annotation.container.md b/docs/source/markdown/options/annotation.container.md index aadaef264f..c2fc50de11 100644 --- a/docs/source/markdown/options/annotation.container.md +++ b/docs/source/markdown/options/annotation.container.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman create, kube play, run +####> podman podman-container.unit.5.md.in, create, kube play, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Annotation=key=value` +<< else >> #### **--annotation**=*key=value* +<< endif >> Add an annotation to the container<<| or pod>>. This option can be set multiple times. diff --git a/docs/source/markdown/options/annotation.image.md b/docs/source/markdown/options/annotation.image.md index 13964ec23d..b74abc2ad7 100644 --- a/docs/source/markdown/options/annotation.image.md +++ b/docs/source/markdown/options/annotation.image.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman build, farm build +####> podman build, podman-build.unit.5.md.in, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Annotation=annotation=value [annotation=value ...]` +<< else >> #### **--annotation**=*annotation=value* +<< endif >> Add an image *annotation* (e.g. annotation=*value*) to the image metadata. Can be used multiple times. diff --git a/docs/source/markdown/options/arch.md b/docs/source/markdown/options/arch.md index 33cee10299..d25dd0253e 100644 --- a/docs/source/markdown/options/arch.md +++ b/docs/source/markdown/options/arch.md @@ -1,7 +1,12 @@ ####> This option file is used in: -####> podman create, pull, run +####> podman podman-build.unit.5.md.in, create, podman-image.unit.5.md.in, pull, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Arch=ARCH` +<< else >> #### **--arch**=*ARCH* +<< endif >> + Override the architecture, defaults to hosts, of the image to be pulled. For example, `arm`. Unless overridden, subsequent lookups of the same image in the local storage matches this architecture, regardless of the host. diff --git a/docs/source/markdown/options/authfile.md b/docs/source/markdown/options/authfile.md index e6724b4b8a..101b17fcb1 100644 --- a/docs/source/markdown/options/authfile.md +++ b/docs/source/markdown/options/authfile.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman artifact pull, artifact push, auto update, build, container runlabel, create, farm build, image sign, kube play, login, logout, manifest add, manifest inspect, manifest push, pull, push, run, search +####> podman artifact pull, artifact push, auto update, build, podman-build.unit.5.md.in, container runlabel, create, farm build, image sign, podman-image.unit.5.md.in, kube play, login, logout, manifest add, manifest inspect, manifest push, pull, push, run, search ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `AuthFile=path` +<< else >> #### **--authfile**=*path* +<< endif >> Path of the authentication file. Default is `${XDG_RUNTIME_DIR}/containers/auth.json` on Linux, and `$HOME/.config/containers/auth.json` on Windows/macOS. The file is created by **[podman login](podman-login.1.md)**. If the authorization state is not found there, `$HOME/.docker/config.json` is checked, which is set using **docker login**. diff --git a/docs/source/markdown/options/auto-update.md b/docs/source/markdown/options/auto-update.md new file mode 100644 index 0000000000..49a0719216 --- /dev/null +++ b/docs/source/markdown/options/auto-update.md @@ -0,0 +1,11 @@ +####> This option file is used in: +####> podman podman-container.unit.5.md.in +####> If file is edited, make sure the changes +####> are applicable to all of those. +### `AutoUpdate=registry` + +Indicates whether the container will be auto-updated ([podman-auto-update(1)](podman-auto-update.1.md)). The following values are supported: + +* `registry`: Requires a fully-qualified image reference (e.g., quay.io/podman/stable:latest) to be used to create the container. This enforcement is necessary to know which image to actually check and pull. If an image ID was used, Podman does not know which image to check/pull anymore. + +* `local`: Tells Podman to compare the image a container is using to the image with its raw name in local storage. If an image is updated locally, Podman simply restarts the systemd unit executing the container. diff --git a/docs/source/markdown/options/cap-add.image.md b/docs/source/markdown/options/cap-add.image.md index 1874f558b8..007a95ed14 100644 --- a/docs/source/markdown/options/cap-add.image.md +++ b/docs/source/markdown/options/cap-add.image.md @@ -2,7 +2,12 @@ ####> podman build, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `AddCapability=CAP_xxx` +<< else >> #### **--cap-add**=*CAP\_xxx* +<< endif >> + When executing RUN instructions, run the command specified in the instruction with the specified capability added to its capability set. diff --git a/docs/source/markdown/options/cap-add.md b/docs/source/markdown/options/cap-add.md index 67fc2e4d36..b91a669297 100644 --- a/docs/source/markdown/options/cap-add.md +++ b/docs/source/markdown/options/cap-add.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `AddCapability=capability` +<< else >> #### **--cap-add**=*capability* +<< endif >> Add Linux capabilities. diff --git a/docs/source/markdown/options/cap-drop.md b/docs/source/markdown/options/cap-drop.md index 1baacc96d6..99ce9aaa36 100644 --- a/docs/source/markdown/options/cap-drop.md +++ b/docs/source/markdown/options/cap-drop.md @@ -1,7 +1,13 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `DropCapability=capability` +<< else >> #### **--cap-drop**=*capability* +<< endif >> -Drop Linux capabilities. +Drop these capabilities from the default podman capability set, or `all` to drop all capabilities. + +This is a space separated list of capabilities. diff --git a/docs/source/markdown/options/cert-dir.md b/docs/source/markdown/options/cert-dir.md index c2bd97dfcc..befefa7ab3 100644 --- a/docs/source/markdown/options/cert-dir.md +++ b/docs/source/markdown/options/cert-dir.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman artifact pull, artifact push, build, container runlabel, create, farm build, image sign, kube play, login, manifest add, manifest push, pull, push, run, search +####> podman artifact pull, artifact push, build, container runlabel, create, farm build, image sign, podman-image.unit.5.md.in, kube play, login, manifest add, manifest push, pull, push, run, search ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `CertDir=path` +<< else >> #### **--cert-dir**=*path* +<< endif >> Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. (Default: /etc/containers/certs.d) For details, see **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**. diff --git a/docs/source/markdown/options/cgroups.md b/docs/source/markdown/options/cgroups.md index a5e16e5783..bdcbf94e12 100644 --- a/docs/source/markdown/options/cgroups.md +++ b/docs/source/markdown/options/cgroups.md @@ -1,12 +1,24 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `CgroupsMode=how` +<< else >> #### **--cgroups**=*how* +<< endif >> Determines whether the container creates CGroups. +<< if is_quadlet >> +By default, the cgroups mode of the container created by Quadlet is `split`, +which differs from the default (`enabled`) used by the Podman CLI. + +If the container joins a pod (i.e. `Pod=` is specified), you may want to change this to +`no-conmon` or `enabled` so that pod level cgroup resource limits can take effect. +<< else >> Default is **enabled**. +<< endif >> The **enabled** option creates a new cgroup under the cgroup-parent. The **disabled** option forces the container to not create CGroups, and thus conflicts with CGroup options (**--cgroupns** and **--cgroup-parent**). diff --git a/docs/source/markdown/options/configmap.md b/docs/source/markdown/options/configmap.md new file mode 100644 index 0000000000..15ac9a83c1 --- /dev/null +++ b/docs/source/markdown/options/configmap.md @@ -0,0 +1,18 @@ +####> This option file is used in: +####> podman kube play, podman-kube.unit.5.md.in +####> If file is edited, make sure the changes +####> are applicable to all of those. +<< if is_quadlet >> +### `ConfigMap=path` +<< else >> +#### **--configmap**=*path* +<< endif >> + +Use Kubernetes configmap YAML at path to provide a source for environment variable values within the containers of the pod. (This option is not available with the remote Podman client) + +<< if is_quadlet >> +The value may contain only one path but it may be absolute or relative to the location of the unit file. +<< else >> +Note: The **--configmap** option can be used multiple times or a comma-separated list of paths can be used to pass multiple Kubernetes configmap YAMLs. +The YAML file may be in a multi-doc YAML format. But, it must contain only configmaps. +<< endif >> diff --git a/docs/source/markdown/options/creds.md b/docs/source/markdown/options/creds.md index 138dd68d57..740af7d40e 100644 --- a/docs/source/markdown/options/creds.md +++ b/docs/source/markdown/options/creds.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman artifact pull, artifact push, build, container runlabel, create, farm build, kube play, manifest add, manifest push, pull, push, run, search +####> podman artifact pull, artifact push, build, container runlabel, create, farm build, podman-image.unit.5.md.in, kube play, manifest add, manifest push, pull, push, run, search ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Creds=[username[:password]]` +<< else >> #### **--creds**=*[username[:password]]* +<< endif >> The [username[:password]] to use to authenticate with the registry, if required. If one or both values are not supplied, a command line prompt appears and the diff --git a/docs/source/markdown/options/decryption-key.md b/docs/source/markdown/options/decryption-key.md index ee7ed881bc..589b7ea4b1 100644 --- a/docs/source/markdown/options/decryption-key.md +++ b/docs/source/markdown/options/decryption-key.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman artifact pull, build, create, farm build, pull, run +####> podman artifact pull, build, create, farm build, podman-image.unit.5.md.in, pull, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `DecryptionKey=key[:passphrase]` +<< else >> #### **--decryption-key**=*key[:passphrase]* +<< endif >> The [key[:passphrase]] to be used for decryption of images. Key can point to keys and/or certificates. Decryption is tried with all keys. If the key is protected by a passphrase, it is required to be passed in the argument and omitted otherwise. diff --git a/docs/source/markdown/options/device.md b/docs/source/markdown/options/device.md index 8875645b93..3dcad9d976 100644 --- a/docs/source/markdown/options/device.md +++ b/docs/source/markdown/options/device.md @@ -1,12 +1,18 @@ ####> This option file is used in: -####> podman build, create, farm build, pod clone, pod create, run +####> podman build, podman-container.unit.5.md.in, create, farm build, pod clone, pod create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `AddDevice=host-device[:container-device][:permissions]` +<< else >> #### **--device**=*host-device[:container-device][:permissions]* +<< endif >> -Add a host device to the <>. Optional *permissions* parameter -can be used to specify device permissions by combining -**r** for read, **w** for write, and **m** for **mknod**(2). +Add a host device to the <>. The format of this is +`HOST-DEVICE[:CONTAINER-DEVICE][:PERMISSIONS]`, where `HOST-DEVICE` is the path of +the device node on the host, `CONTAINER-DEVICE` is the path of the device node in +the container, and `PERMISSIONS` is a list of permissions combining 'r' for read, +'w' for write, and 'm' for mknod(2). Example: **--device=/dev/sdc:/dev/xvdc:rwm**. diff --git a/docs/source/markdown/options/disable-dns.md b/docs/source/markdown/options/disable-dns.md new file mode 100644 index 0000000000..53db5eddc2 --- /dev/null +++ b/docs/source/markdown/options/disable-dns.md @@ -0,0 +1,12 @@ +####> This option file is used in: +####> podman network create, podman-network.unit.5.md.in +####> If file is edited, make sure the changes +####> are applicable to all of those. +<< if is_quadlet >> +### `DisableDNS=true` +<< else >> +#### **--disable-dns** +<< endif >> + +Disables the DNS plugin for this network which if enabled, can perform container to container name +resolution. It is only supported with the `bridge` driver, for other drivers it is always disabled. diff --git a/docs/source/markdown/options/dns-option.container.md b/docs/source/markdown/options/dns-option.container.md index f1b57de1a1..c3847301d5 100644 --- a/docs/source/markdown/options/dns-option.container.md +++ b/docs/source/markdown/options/dns-option.container.md @@ -1,7 +1,12 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `DNSOption=option` +<< else >> #### **--dns-option**=*option* +<< endif >> -Set custom DNS options. Invalid if using **--dns-option** with **--network** that is set to **none** or **container:**_id_. +Set custom DNS options. Invalid if using << '**DNSOption=**' if is_quadlet else '**--dns-option**' >> +with << '**Network=**' if is_quadlet else '**--network**' >> that is set to **none** or **container:**_id_. diff --git a/docs/source/markdown/options/dns-option.image.md b/docs/source/markdown/options/dns-option.image.md index 345efd47c4..ae3b7a6572 100644 --- a/docs/source/markdown/options/dns-option.image.md +++ b/docs/source/markdown/options/dns-option.image.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman build, farm build +####> podman build, podman-build.unit.5.md.in, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `DNSOption=option` +<< else >> #### **--dns-option**=*option* +<< endif >> Set custom DNS options to be used during the build. diff --git a/docs/source/markdown/options/dns-search.container.md b/docs/source/markdown/options/dns-search.container.md index 589e3fa6d6..75c1e9f5f9 100644 --- a/docs/source/markdown/options/dns-search.container.md +++ b/docs/source/markdown/options/dns-search.container.md @@ -1,8 +1,13 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `DNSSearch=domain` +<< else >> #### **--dns-search**=*domain* +<< endif >> -Set custom DNS search domains. Invalid if using **--dns-search** with **--network** that is set to **none** or **container:**_id_. -Use **--dns-search=.** to remove the search domain. +Set custom DNS search domains. Invalid if using << '**DNSSearch=**' if is_quadlet else '**--dns-search**' >> +with with << '**Network=**' if is_quadlet else '**--network**' >> that is set to **none** or **container:**_id_. +Use << '**DNSSearch=.**' if is_quadlet else '**--dns-search=.**' >> to remove the search domain. diff --git a/docs/source/markdown/options/dns-search.image.md b/docs/source/markdown/options/dns-search.image.md index 5e75afde53..f1ccefe59d 100644 --- a/docs/source/markdown/options/dns-search.image.md +++ b/docs/source/markdown/options/dns-search.image.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman build, farm build +####> podman build, podman-build.unit.5.md.in, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `DNSSearch=domain` +<< else >> #### **--dns-search**=*domain* +<< endif >> Set custom DNS search domains to be used during the build. diff --git a/docs/source/markdown/options/dns.md b/docs/source/markdown/options/dns.md index a02a18e6e5..050dd95f84 100644 --- a/docs/source/markdown/options/dns.md +++ b/docs/source/markdown/options/dns.md @@ -1,15 +1,19 @@ ####> This option file is used in: -####> podman build, create, farm build, run +####> podman build, podman-build.unit.5.md.in, podman-container.unit.5.md.in, create, farm build, network create, podman-network.unit.5.md.in, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `DNS=ipaddr` +<< else >> #### **--dns**=*ipaddr* +<< endif >> Set custom DNS servers. This option can be used to override the DNS configuration passed to the container. Typically this is necessary when the host DNS configuration is invalid for the container (e.g., **127.0.0.1**). When this -is the case the **--dns** flag is necessary for every run. +is the case the << '**DNS=.**' if is_quadlet else '**--dns**' >> flag is necessary for every run. The special value **none** can be specified to disable creation of _/etc/resolv.conf_ in the container by Podman. The _/etc/resolv.conf_ file in the image is then used without changes. diff --git a/docs/source/markdown/options/driver.md b/docs/source/markdown/options/driver.md new file mode 100644 index 0000000000..b4501f8d28 --- /dev/null +++ b/docs/source/markdown/options/driver.md @@ -0,0 +1,25 @@ +####> This option file is used in: +####> podman network create, podman-network.unit.5.md.in +####> If file is edited, make sure the changes +####> are applicable to all of those. +<< if is_quadlet >> +### `Driver=driver` +<< else >> +#### **--driver**, **-d**=*driver* +<< endif >> + +Driver to manage the network. Currently `bridge`, `macvlan` and `ipvlan` are supported. Defaults to `bridge`. +As rootless the `macvlan` and `ipvlan` driver have no access to the host network interfaces because rootless networking requires a separate network namespace. + +The netavark backend allows the use of so called *netavark plugins*, see the +[plugin-API.md](https://github.com/containers/netavark/blob/main/plugin-API.md) +documentation in netavark. The binary must be placed in a specified directory +so podman can discover it, this list is set in `netavark_plugin_dirs` in +**[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)** +under the `[network]` section. + +The name of the plugin can then be used as driver to create a network for your plugin. +The list of all supported drivers and plugins can be seen with `podman info --format {{.Plugins.Network}}`. + +Note that the `macvlan` and `ipvlan` drivers do not support port forwarding. Support for port forwarding +with a plugin depends on the implementation of the plugin. diff --git a/docs/source/markdown/options/entrypoint.md b/docs/source/markdown/options/entrypoint.md index 78fb05a818..5be09ff10f 100644 --- a/docs/source/markdown/options/entrypoint.md +++ b/docs/source/markdown/options/entrypoint.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Entrypoint="command"` +<< else >> #### **--entrypoint**=*"command"* | *'["command", "arg1", ...]'* +<< endif >> Override the default ENTRYPOINT from the image. @@ -12,7 +16,7 @@ because it specifies what executable to run when the container starts, but it is default nature or behavior. When the ENTRYPOINT is set, the container runs as if it were that binary, complete with default options. More options can be passed in via the COMMAND. But, if a user wants to run -something else inside the container, the **--entrypoint** option allows a new +something else inside the container, the << '**Entrypoint=**' if is_quadlet else '**--entrypoint=.**' >>option allows a new ENTRYPOINT to be specified. Specify multi option commands in the form of a JSON string. diff --git a/docs/source/markdown/options/env-file.md b/docs/source/markdown/options/env-file.md index 428cb78582..adec9ba9e1 100644 --- a/docs/source/markdown/options/env-file.md +++ b/docs/source/markdown/options/env-file.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman create, exec, run +####> podman podman-container.unit.5.md.in, create, exec, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `EnvironmentFile=file` +<< else >> #### **--env-file**=*file* +<< endif >> Read in a line-delimited file of environment variables. diff --git a/docs/source/markdown/options/env-host.md b/docs/source/markdown/options/env-host.md index 53b121cbc2..9b48379130 100644 --- a/docs/source/markdown/options/env-host.md +++ b/docs/source/markdown/options/env-host.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `EnvironmentHost=` +<< else >> #### **--env-host** +<< endif >> Use host environment inside of the container. See **Environment** note below for precedence. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) diff --git a/docs/source/markdown/options/env.image.md b/docs/source/markdown/options/env.image.md index d214291d53..73c4467a9d 100644 --- a/docs/source/markdown/options/env.image.md +++ b/docs/source/markdown/options/env.image.md @@ -2,10 +2,16 @@ ####> podman build, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Env=env[=value]` +<< else >> #### **--env**=*env[=value]* +<< endif >> Add a value (e.g. env=*value*) to the built image. Can be used multiple times. If neither `=` nor a *value* are specified, but *env* is set in the current environment, the value from the current environment is added to the image. +<< if not is_quadlet >> To remove an environment variable from the built image, use the `--unsetenv` option. +<< endif >> diff --git a/docs/source/markdown/options/env.md b/docs/source/markdown/options/env.md index 19bfc42ae4..9cffeff9ec 100644 --- a/docs/source/markdown/options/env.md +++ b/docs/source/markdown/options/env.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, exec, run +####> podman podman-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 >> +### `Environment=env=value [env=value ...]` +<< else >> #### **--env**, **-e**=*env* +<< endif >> Set environment variables. diff --git a/docs/source/markdown/options/exec.md b/docs/source/markdown/options/exec.md new file mode 100644 index 0000000000..af79076e3a --- /dev/null +++ b/docs/source/markdown/options/exec.md @@ -0,0 +1,18 @@ +####> This option file is used in: +####> podman podman-container.unit.5.md.in +####> If file is edited, make sure the changes +####> are applicable to all of those. +### `Exec=command` + +Additional arguments for the container; this has exactly the same effect as passing +more arguments after a `podman run ` invocation. + +The format is the same as for [systemd command lines](https://www.freedesktop.org/software/systemd/man/systemd.service.html#Command%20lines), +However, unlike the usage scenario for similarly-named systemd `ExecStart=` verb +which operates on the ambient root filesystem, it is very common for container +images to have their own `ENTRYPOINT` or `CMD` metadata which this interacts with. + +The default expectation for many images is that the image will include an `ENTRYPOINT` +with a default binary, and this field will add arguments to that entrypoint. + +Another way to describe this is that it works the same way as the [args field in a Kubernetes pod](https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell). diff --git a/docs/source/markdown/options/expose.md b/docs/source/markdown/options/expose.md index 745e25226c..f896a8baac 100644 --- a/docs/source/markdown/options/expose.md +++ b/docs/source/markdown/options/expose.md @@ -1,12 +1,16 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `ExposeHostPort=port[/protocol]` +<< else >> #### **--expose**=*port[/protocol]* +<< endif >> -Expose a port or a range of ports (e.g. **--expose=3300-3310**). +Expose a port or a range of ports (e.g. << '**Expose=3300-3310**' if is_quadlet else '**--expose=3300-3310**' >>). The protocol can be `tcp`, `udp` or `sctp` and if not given `tcp` is assumed. This option matches the EXPOSE instruction for image builds and has no effect on the actual networking rules unless **-P/--publish-all** is used to forward to all exposed ports from random host ports. To forward specific ports from the host -into the container use the **-p/--publish** option instead. +into the container use the << '**PublishPort=**' if is_quadlet else '**-p/--publish**' >> option instead. diff --git a/docs/source/markdown/options/file.md b/docs/source/markdown/options/file.md index 60c3aea5ad..b6bb8e4dc1 100644 --- a/docs/source/markdown/options/file.md +++ b/docs/source/markdown/options/file.md @@ -1,16 +1,31 @@ ####> This option file is used in: -####> podman build, farm build +####> podman build, podman-build.unit.5.md.in, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `File=Containerfile` +<< else >> #### **--file**, **-f**=*Containerfile* +<< endif >> + Specifies a Containerfile which contains instructions for building the image, either a local file or an **http** or **https** URL. If more than one Containerfile is specified, *FROM* instructions are only be accepted from the last specified file. +<< if is_quadlet >> +Note that for a given relative path to a Containerfile, or when using a `http(s)://` URL, also set +`SetWorkingDirectory=` in order for `podman build` to find a valid context directory for the +resources specified in the Containerfile. + +Note that setting a `File=` field is mandatory for a `.build` file, unless `SetWorkingDirectory` (or +a `WorkingDirectory` in the `Service` group) has also been set. +<< else >> If a build context is not specified, and at least one Containerfile is a local file, the directory in which it resides is used as the build context. +<< endif >> -Specifying the option `-f -` causes the Containerfile contents to be read from stdin. +Specifying the option << 'File=-' if is_quadlet else '`-f -`' >> causes +the Containerfile contents to be read from stdin. diff --git a/docs/source/markdown/options/force-rm.md b/docs/source/markdown/options/force-rm.md index 5af1f5a8af..c1e43c7b0a 100644 --- a/docs/source/markdown/options/force-rm.md +++ b/docs/source/markdown/options/force-rm.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman build, farm build +####> podman build, podman-build.unit.5.md.in, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `ForceRM=` +<< else >> #### **--force-rm** +<< endif >> Always remove intermediate containers after a build, even if the build fails (default true). diff --git a/docs/source/markdown/options/force.kube-down.md b/docs/source/markdown/options/force.kube-down.md new file mode 100644 index 0000000000..ed75202e72 --- /dev/null +++ b/docs/source/markdown/options/force.kube-down.md @@ -0,0 +1,11 @@ +####> This option file is used in: +####> podman kube down +####> If file is edited, make sure the changes +####> are applicable to all of those. +<< if is_quadlet >> +### `KubeDownForce=true` +<< else >> +#### **--force** +<< endif >> + +Remove all resources, including volumes, when calling `podman kube down`. diff --git a/docs/source/markdown/options/gateway.md b/docs/source/markdown/options/gateway.md new file mode 100644 index 0000000000..81f2785c7f --- /dev/null +++ b/docs/source/markdown/options/gateway.md @@ -0,0 +1,16 @@ +####> This option file is used in: +####> podman network create, podman-network.unit.5.md.in +####> If file is edited, make sure the changes +####> are applicable to all of those. +<< if is_quadlet >> +### `Gateway=ip` +<< else >> +#### **--gateway**=*ip* +<< endif >> + +Define a gateway for the subnet. To provide a gateway address, a +*subnet* option is required. Can be specified multiple times. + +<< if not is_quadlet >> +The argument order of the **--subnet**, **--gateway** and **--ip-range** options must match. +<< endif >> diff --git a/docs/source/markdown/options/gidmap.container.md b/docs/source/markdown/options/gidmap.container.md index 0f4cfa86b0..ad9297bf09 100644 --- a/docs/source/markdown/options/gidmap.container.md +++ b/docs/source/markdown/options/gidmap.container.md @@ -1,12 +1,19 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `GIDMap=[flags]container_uid:from_uid[:amount]` +<< else >> #### **--gidmap**=*[flags]container_uid:from_uid[:amount]* +<< endif >> Run the container in a new user namespace using the supplied GID mapping. This -option conflicts with the **--userns** and **--subgidname** options. This +option conflicts with the << '**UserNS=**' if is_quadlet else '**--userns**' >> and +<< '**SubGIDMap=**' if is_quadlet else '**--subgidname**' >> options. This option provides a way to map host GIDs to container GIDs in the same way as __--uidmap__ maps host UIDs to container UIDs. For details see __--uidmap__. -Note: the **--gidmap** option cannot be called in conjunction with the **--pod** option as a gidmap cannot be set on the container level when in a pod. +Note: the << '**GIDMap=**' if is_quadlet else '**--gidmap**' >> option cannot be +called in conjunction with the << '**Pod=**' if is_quadlet else '**--pod**' >> option as +a gidmap cannot be set on the container level when in a pod. diff --git a/docs/source/markdown/options/global-args.md b/docs/source/markdown/options/global-args.md new file mode 100644 index 0000000000..b63409a44e --- /dev/null +++ b/docs/source/markdown/options/global-args.md @@ -0,0 +1,15 @@ +####> This option file is used in: +####> podman podman-build.unit.5.md.in, podman-container.unit.5.md.in, podman-image.unit.5.md.in, podman-kube.unit.5.md.in, podman-network.unit.5.md.in, podman-pod.unit.5.md.in, podman-volume.unit.5.md.in +####> If file is edited, make sure the changes +####> are applicable to all of those. +### `GlobalArgs=` + +This key contains a list of arguments passed directly after the `podman` command in the generated +file. It can be used to access Podman features otherwise unsupported by the generator. Since the +generator is unaware of what unexpected interactions can be caused by these arguments, it is not +recommended to use this option. + +The format of this is a space separated list of arguments, which can optionally be individually +escaped to allow inclusion of whitespace and other control characters. + +This key can be listed multiple times. diff --git a/docs/source/markdown/options/group-add.md b/docs/source/markdown/options/group-add.md index dadb8b4f1c..a262c1f9f1 100644 --- a/docs/source/markdown/options/group-add.md +++ b/docs/source/markdown/options/group-add.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman build, create, farm build, run +####> podman build, podman-build.unit.5.md.in, podman-container.unit.5.md.in, create, farm build, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `GroupAdd=group | keep-groups` +<< else >> #### **--group-add**=*group* | *keep-groups* +<< endif >> Assign additional groups to the primary user running within the container process. diff --git a/docs/source/markdown/options/health-cmd.md b/docs/source/markdown/options/health-cmd.md index cc1587796d..d97ad6ee07 100644 --- a/docs/source/markdown/options/health-cmd.md +++ b/docs/source/markdown/options/health-cmd.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `HealthCmd="command"` +<< else >> #### **--health-cmd**=*"command"* | *'["command", "arg1", ...]'* +<< endif >> Set or alter a healthcheck command for a container. The command is a command to be executed inside the container that determines the container health. The command is required for other healthcheck options diff --git a/docs/source/markdown/options/health-interval.md b/docs/source/markdown/options/health-interval.md index 2657187e59..8e2b04f3f7 100644 --- a/docs/source/markdown/options/health-interval.md +++ b/docs/source/markdown/options/health-interval.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `HealthInterval=interval` +<< else >> #### **--health-interval**=*interval* +<< endif >> Set an interval for the healthchecks. An _interval_ of **disable** results in no automatic timer setup. The default is **30s**. diff --git a/docs/source/markdown/options/health-log-destination.md b/docs/source/markdown/options/health-log-destination.md index 91e91e269c..e1b4e1d591 100644 --- a/docs/source/markdown/options/health-log-destination.md +++ b/docs/source/markdown/options/health-log-destination.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `HealthLogDestination=directory_path` +<< else >> #### **--health-log-destination**=*directory_path* +<< endif >> Set the destination of the HealthCheck log. Directory path, local or events_logger (local use container state file) (Default: local) diff --git a/docs/source/markdown/options/health-max-log-count.md b/docs/source/markdown/options/health-max-log-count.md index 137d470830..d8cd5d1ede 100644 --- a/docs/source/markdown/options/health-max-log-count.md +++ b/docs/source/markdown/options/health-max-log-count.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `HealthMaxLogCount=number` +<< else >> #### **--health-max-log-count**=*number of stored logs* +<< endif >> Set maximum number of attempts in the HealthCheck log file. ('0' value means an infinite number of attempts in the log file) (Default: 5 attempts) diff --git a/docs/source/markdown/options/health-max-log-size.md b/docs/source/markdown/options/health-max-log-size.md index 1c3169c7f4..5403ad5c6c 100644 --- a/docs/source/markdown/options/health-max-log-size.md +++ b/docs/source/markdown/options/health-max-log-size.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `HealthMaxLogSize=size` +<< else >> #### **--health-max-log-size**=*size of stored logs* +<< endif >> Set maximum length in characters of stored HealthCheck log. ("0" value means an infinite log length) (Default: 500 characters) diff --git a/docs/source/markdown/options/health-on-failure.md b/docs/source/markdown/options/health-on-failure.md index 6c539e7332..7936537741 100644 --- a/docs/source/markdown/options/health-on-failure.md +++ b/docs/source/markdown/options/health-on-failure.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `HealthOnFailure=action` +<< else >> #### **--health-on-failure**=*action* +<< endif >> Action to take once the container transitions to an unhealthy state. The default is **none**. diff --git a/docs/source/markdown/options/health-retries.md b/docs/source/markdown/options/health-retries.md index 4060fb30ed..1518965760 100644 --- a/docs/source/markdown/options/health-retries.md +++ b/docs/source/markdown/options/health-retries.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `HealthRetries=retries` +<< else >> #### **--health-retries**=*retries* +<< endif >> The number of retries allowed before a healthcheck is considered to be unhealthy. The default value is **3**. diff --git a/docs/source/markdown/options/health-start-period.md b/docs/source/markdown/options/health-start-period.md index 302af88072..a5e587c535 100644 --- a/docs/source/markdown/options/health-start-period.md +++ b/docs/source/markdown/options/health-start-period.md @@ -1,16 +1,23 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `HealthStartPeriod=period` +<< else >> #### **--health-start-period**=*period* +<< endif >> The initialization time needed for a container to bootstrap. The value can be expressed in time format like **2m3s**. The default value is **0s**. Note: The health check command is executed as soon as a container is started, if the health check is successful the container's health state will be updated to `healthy`. However, if the health check fails, the health state will -stay as `starting` until either the health check is successful or until the `--health-start-period` time is over. If the -health check command fails after the `--health-start-period` time is over, the health state will be updated to `unhealthy`. -The health check command is executed periodically based on the value of `--health-interval`. +stay as `starting` until either the health check is successful or until +the << '`HealthStartPeriod=`' if is_quadlet else '`--health-start-period`' >> time is over. If the +health check command fails after the << '`HealthStartPeriod=`' if is_quadlet else '`--health-start-period`' >> +time is over, the health state will be updated to `unhealthy`. +The health check command is executed periodically based on the value of +<< '`HealthInternal=`' if is_quadlet else '`--health-interval`' >>. Note: This parameter will overwrite related healthcheck configuration from the image. diff --git a/docs/source/markdown/options/health-startup-cmd.md b/docs/source/markdown/options/health-startup-cmd.md index 67b2db32ad..de81cd6264 100644 --- a/docs/source/markdown/options/health-startup-cmd.md +++ b/docs/source/markdown/options/health-startup-cmd.md @@ -1,11 +1,16 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `HealthStartupCmd="command"` +<< else >> #### **--health-startup-cmd**=*"command"* | *'["command", "arg1", ...]'* +<< endif >> Set a startup healthcheck command for a container. This command is executed inside the container and is used to gate the regular healthcheck. When the startup command succeeds, the regular healthcheck begins and the startup healthcheck ceases. Optionally, if the command fails for a set number of attempts, the container is restarted. A startup healthcheck can be used to ensure that containers with an extended startup period are not marked as unhealthy until they are fully started. Startup healthchecks can only be -used when a regular healthcheck (from the container's image or the **--health-cmd** option) is also set. +used when a regular healthcheck (from the container's image or the +<< '`HealthCmd=`' if is_quadlet else '`--health-cmd`' >> option) is also set. diff --git a/docs/source/markdown/options/health-startup-interval.md b/docs/source/markdown/options/health-startup-interval.md index 052d703a78..9f0f31cc8f 100644 --- a/docs/source/markdown/options/health-startup-interval.md +++ b/docs/source/markdown/options/health-startup-interval.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `HealthStartupInterval=interval` +<< else >> #### **--health-startup-interval**=*interval* +<< endif >> Set an interval for the startup healthcheck. An _interval_ of **disable** results in no automatic timer setup. The default is **30s**. diff --git a/docs/source/markdown/options/health-startup-retries.md b/docs/source/markdown/options/health-startup-retries.md index 2a0f9fdf90..c35be5c286 100644 --- a/docs/source/markdown/options/health-startup-retries.md +++ b/docs/source/markdown/options/health-startup-retries.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `HealthStartupRetries=retries` +<< else >> #### **--health-startup-retries**=*retries* +<< endif >> The number of attempts allowed before the startup healthcheck restarts the container. If set to **0**, the container is never restarted. The default is **0**. diff --git a/docs/source/markdown/options/health-startup-success.md b/docs/source/markdown/options/health-startup-success.md index e1f911b215..54995fa791 100644 --- a/docs/source/markdown/options/health-startup-success.md +++ b/docs/source/markdown/options/health-startup-success.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `HealthStartupSuccess=retries` +<< else >> #### **--health-startup-success**=*retries* +<< endif >> The number of successful runs required before the startup healthcheck succeeds and the regular healthcheck begins. A value of **0** means that any success begins the regular healthcheck. The default is **0**. diff --git a/docs/source/markdown/options/health-startup-timeout.md b/docs/source/markdown/options/health-startup-timeout.md index deffa14025..9fdf007c83 100644 --- a/docs/source/markdown/options/health-startup-timeout.md +++ b/docs/source/markdown/options/health-startup-timeout.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `HealthStartupTimeout=timeout` +<< else >> #### **--health-startup-timeout**=*timeout* +<< endif >> The maximum time a startup healthcheck command has to complete before it is marked as failed. The value can be expressed in a time format like **2m3s**. The default value is **30s**. diff --git a/docs/source/markdown/options/health-timeout.md b/docs/source/markdown/options/health-timeout.md index 458442508b..5ceae0fe84 100644 --- a/docs/source/markdown/options/health-timeout.md +++ b/docs/source/markdown/options/health-timeout.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `HealthTimeout=timeout` +<< else >> #### **--health-timeout**=*timeout* +<< endif >> The maximum time allowed to complete the healthcheck before an interval is considered failed. Like start-period, the value can be expressed in a time format such as **1m22s**. The default value is **30s**. diff --git a/docs/source/markdown/options/hostname.container.md b/docs/source/markdown/options/hostname.container.md index ab7e76c9ed..f986049b16 100644 --- a/docs/source/markdown/options/hostname.container.md +++ b/docs/source/markdown/options/hostname.container.md @@ -1,13 +1,17 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `HostName=name` +<< else >> #### **--hostname**, **-h**=*name* +<< endif >> Set the container's hostname inside the container. This option can only be used with a private UTS namespace `--uts=private` -(default). If `--pod` is given and the pod shares the same UTS namespace +(default). If << '`Pod=`' if is_quadlet else '`--pod`' >> is given and the pod shares the same UTS namespace (default), the pod's hostname is used. The given hostname is also added to the `/etc/hosts` file using the container's primary IP address (also see the -**--add-host** option). +<< '**AddHost=**' if is_quadlet else '**--add-host**' >> option). diff --git a/docs/source/markdown/options/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 5a9fb2f29e..c0ba3fbec6 100644 --- a/docs/source/markdown/options/init.md +++ b/docs/source/markdown/options/init.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `RunInit=` +<< else >> #### **--init** +<< endif >> Run an init inside the container that forwards signals and reaps processes. The container-init binary is mounted at `/run/podman-init`. diff --git a/docs/source/markdown/options/interface-name.md b/docs/source/markdown/options/interface-name.md new file mode 100644 index 0000000000..612395129e --- /dev/null +++ b/docs/source/markdown/options/interface-name.md @@ -0,0 +1,13 @@ +####> This option file is used in: +####> podman network create, podman-network.unit.5.md.in +####> If file is edited, make sure the changes +####> are applicable to all of those. +<< if is_quadlet >> +### `InterfaceName=name` +<< else >> +#### **--interface-name**=*name* +<< endif >> + +This option maps the *network_interface* option in the network config, see **podman network inspect**. +Depending on the driver, this can have different effects; for `bridge`, it uses the bridge interface name. +For `macvlan` and `ipvlan`, it is the parent device on the host. It is the same as `--opt parent=...`. diff --git a/docs/source/markdown/options/internal.md b/docs/source/markdown/options/internal.md new file mode 100644 index 0000000000..41578b4c15 --- /dev/null +++ b/docs/source/markdown/options/internal.md @@ -0,0 +1,25 @@ +####> This option file is used in: +####> podman network create, podman-network.unit.5.md.in +####> If file is edited, make sure the changes +####> are applicable to all of those. +<< if is_quadlet >> +### `Internal=true` +<< else >> +#### **--internal** +<< endif >> + +Restrict external access of this network when using a `bridge` network. Note when using the CNI backend +DNS will be automatically disabled, see **--disable-dns**. + +When using the `macvlan` or `ipvlan` driver with this option no default route will be added to the container. +Because it bypasses the host network stack no additional restrictions can be set by podman and if a +privileged container is run it can set a default route themselves. If this is a concern then the +container connections should be blocked on the actual network gateway. + +Using the `bridge` driver with this option has the following effects: + - Global IP forwarding sysctls will not be changed in the host network namespace. + - IP forwarding is disabled on the bridge interface instead of setting up a firewall. + - No default route will be added to the container. + +In all cases, aardvark-dns will only resolve container names with this option enabled. +Other queries will be answered with `NXDOMAIN`. diff --git a/docs/source/markdown/options/ip-range.md b/docs/source/markdown/options/ip-range.md new file mode 100644 index 0000000000..5c8f245ea3 --- /dev/null +++ b/docs/source/markdown/options/ip-range.md @@ -0,0 +1,17 @@ +####> This option file is used in: +####> podman network create, podman-network.unit.5.md.in +####> If file is edited, make sure the changes +####> are applicable to all of those. +<< if is_quadlet >> +### `IPRange=ip` +<< else >> +#### **--ip-range**=*range* +<< endif >> + +Allocate container IP from a range. The range must be a either a complete subnet in CIDR notation or be in +the `-` syntax which allows for a more flexible range compared to the CIDR subnet. +The *ip-range* option must be used with a *subnet* option. Can be specified multiple times. + +<< if not is_quadlet >> +The argument order of the **--subnet**, **--gateway** and **--ip-range** options must match. +<< endif >> diff --git a/docs/source/markdown/options/ip.md b/docs/source/markdown/options/ip.md index d3c865a88d..efbc5217d8 100644 --- a/docs/source/markdown/options/ip.md +++ b/docs/source/markdown/options/ip.md @@ -1,12 +1,20 @@ ####> This option file is used in: -####> podman create, pod create, run +####> podman podman-container.unit.5.md.in, create, pod create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `IP=ipv4` +<< else >> #### **--ip**=*ipv4* +<< endif >> Specify a static IPv4 address for the <>, for example **10.88.64.128**. -This option can only be used if the <> is joined to only a single network - i.e., **--network=network-name** is used at most once - -and if the <> is not joining another container's network namespace via **--network=container:_id_**. +This option can only be used if the <> is joined to only a single network - i.e., +<< '**Network=network-name**' if is_quadlet else '**--network=network-name**' >> is used at most once - +and if the <> is not joining another container's network namespace via +<< '**Network=container:_id_**' if is_quadlet else '**--network=container:_id_**' >>. The address must be within the network's IP address pool (default **10.88.0.0/16**). -To specify multiple static IP addresses per <>, set multiple networks using the **--network** option with a static IP address specified for each using the `ip` mode for that option. +To specify multiple static IP addresses per <>, set multiple networks using +the << '**Network=**' if is_quadlet else '**--network' >> option with a static IP address +specified for each using the `ip` mode for that option. diff --git a/docs/source/markdown/options/ip6.md b/docs/source/markdown/options/ip6.md index a2dd619f72..04ec81b068 100644 --- a/docs/source/markdown/options/ip6.md +++ b/docs/source/markdown/options/ip6.md @@ -1,12 +1,20 @@ ####> This option file is used in: -####> podman create, pod create, run +####> podman podman-container.unit.5.md.in, create, pod create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `IP6=ipv6` +<< else >> #### **--ip6**=*ipv6* +<< endif >> Specify a static IPv6 address for the <>, for example **fd46:db93:aa76:ac37::10**. -This option can only be used if the <> is joined to only a single network - i.e., **--network=network-name** is used at most once - -and if the <> is not joining another container's network namespace via **--network=container:_id_**. +This option can only be used if the <> is joined to only a single network - i.e., +<< '**Network=network-name**' if is_quadlet else '**--network=network-name**' >> is used at most once - +and if the <> is not joining another container's network namespace via +<< '**Network=container:_id_**' if is_quadlet else '**--network=container:_id_**' >>. The address must be within the network's IPv6 address pool. -To specify multiple static IPv6 addresses per <>, set multiple networks using the **--network** option with a static IPv6 address specified for each using the `ip6` mode for that option. +To specify multiple static IPv6 addresses per <>, set multiple networks using the +<< '**Network=**' if is_quadlet else '**--network' >> option with a static IPv6 address +specified for each using the `ip6` mode for that option. diff --git a/docs/source/markdown/options/ipam-driver.md b/docs/source/markdown/options/ipam-driver.md new file mode 100644 index 0000000000..325eb96f79 --- /dev/null +++ b/docs/source/markdown/options/ipam-driver.md @@ -0,0 +1,22 @@ +####> This option file is used in: +####> podman network create, podman-network.unit.5.md.in +####> If file is edited, make sure the changes +####> are applicable to all of those. +<< if is_quadlet >> +### `IPAMDriver=driver` +<< else >> +#### **--ipam-driver**=*driver* +<< endif >> + +Set the ipam driver (IP Address Management Driver) for the network. When unset podman chooses an +ipam driver automatically based on the network driver. + +Valid values are: + + - `dhcp`: IP addresses are assigned from a dhcp server on the network. When using the netavark backend + the `netavark-dhcp-proxy.socket` must be enabled in order to start the dhcp-proxy when a container is + started, for CNI use the `cni-dhcp.socket` unit instead. + - `host-local`: IP addresses are assigned locally. + - `none`: No ip addresses are assigned to the interfaces. + +View the driver in the **podman network inspect** output under the `ipam_options` field. diff --git a/docs/source/markdown/options/ipv6.md b/docs/source/markdown/options/ipv6.md new file mode 100644 index 0000000000..4f802ccf61 --- /dev/null +++ b/docs/source/markdown/options/ipv6.md @@ -0,0 +1,11 @@ +####> This option file is used in: +####> podman network create, podman-network.unit.5.md.in +####> If file is edited, make sure the changes +####> are applicable to all of those. +<< if is_quadlet >> +### `IPv6=true` +<< else >> +#### **--ipv6** +<< endif >> + +Enable IPv6 (Dual Stack) networking. If no subnets are given, it allocates an ipv4 and an ipv6 subnet. diff --git a/docs/source/markdown/options/label.image.md b/docs/source/markdown/options/label.image.md index d119c43625..9a11a4bd0a 100644 --- a/docs/source/markdown/options/label.image.md +++ b/docs/source/markdown/options/label.image.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman build, farm build +####> podman build, podman-build.unit.5.md.in, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Label=label` +<< else >> #### **--label**=*label* +<< endif >> Add an image *label* (e.g. label=*value*) to the image metadata. Can be used multiple times. diff --git a/docs/source/markdown/options/label.md b/docs/source/markdown/options/label.md index af88b3f95f..caae2d8716 100644 --- a/docs/source/markdown/options/label.md +++ b/docs/source/markdown/options/label.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman create, pod clone, pod create, run +####> podman podman-container.unit.5.md.in, create, pod clone, pod create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Label=key=value [key=value ...]` +<< else >> #### **--label**, **-l**=*key=value* +<< endif >> Add metadata to a <>. diff --git a/docs/source/markdown/options/label.network.md b/docs/source/markdown/options/label.network.md new file mode 100644 index 0000000000..bad977fb04 --- /dev/null +++ b/docs/source/markdown/options/label.network.md @@ -0,0 +1,11 @@ +####> This option file is used in: +####> podman network create, podman-network.unit.5.md.in +####> If file is edited, make sure the changes +####> are applicable to all of those. +<< if is_quadlet >> +### `Label=key=value [key=value ...]` +<< else >> +#### **--label**=*key=value* +<< endif >> + +Set one or more OCI labels on the network. diff --git a/docs/source/markdown/options/log-driver.md b/docs/source/markdown/options/log-driver.md index d99f229c5e..e0b02da357 100644 --- a/docs/source/markdown/options/log-driver.md +++ b/docs/source/markdown/options/log-driver.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, podman-kube.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `LogDriver=driver` +<< else >> #### **--log-driver**=*driver* +<< endif >> Logging driver for the container. Currently available options are **k8s-file**, **journald**, **none**, **passthrough** and **passthrough-tty**, with **json-file** aliased to **k8s-file** for scripting compatibility. (Default **journald**). diff --git a/docs/source/markdown/options/log-opt.md b/docs/source/markdown/options/log-opt.md index 9cb1402ae3..31ed80f38f 100644 --- a/docs/source/markdown/options/log-opt.md +++ b/docs/source/markdown/options/log-opt.md @@ -1,20 +1,24 @@ ####> This option file is used in: -####> podman create, kube play, run +####> podman podman-container.unit.5.md.in, create, kube play, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `LogOpt=name=value` +<< else >> #### **--log-opt**=*name=value* +<< endif >> Logging driver specific options. Set custom logging configuration. The following *name*s are supported: **path**: specify a path to the log file - (e.g. **--log-opt path=/var/log/container/mycontainer.json**); + (e.g. << '**LogOpt=path=/var/log/container/mycontainer.json**' if is_quadlet else '**--log-opt path=/var/log/container/mycontainer.json**' >>); **max-size**: specify a max size of the log file - (e.g. **--log-opt max-size=10mb**); + (e.g. << '**LogOpt=max-size=10mb**' if is_quadlet else '**--log-opt max-size=10mb**' >>); **tag**: specify a custom log tag for the container - (e.g. **--log-opt tag="{{.ImageName}}"**. + (e.g. << '**LogOpt=tag="{{.ImageName}}"**' if is_quadlet else '**--log-opt tag="{{.ImageName}}"**' >>. It supports the same keys as **podman inspect --format**. This option is currently supported only by the **journald** log driver. diff --git a/docs/source/markdown/options/memory.md b/docs/source/markdown/options/memory.md index dd53d8d8e6..a1a2a2b55e 100644 --- a/docs/source/markdown/options/memory.md +++ b/docs/source/markdown/options/memory.md @@ -1,14 +1,18 @@ ####> This option file is used in: -####> podman build, container clone, create, farm build, pod clone, pod create, run, update +####> podman build, container clone, podman-container.unit.5.md.in, create, farm build, pod clone, pod create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Memory=number[unit]` +<< else >> #### **--memory**, **-m**=*number[unit]* +<< endif >> Memory limit. A _unit_ can be **b** (bytes), **k** (kibibytes), **m** (mebibytes), or **g** (gibibytes). Allows the memory available to a container to be constrained. If the host -supports swap memory, then the **-m** memory setting can be larger than physical -RAM. If a limit of 0 is specified (not using **-m**), the container's memory is +supports swap memory, then the << '**Memory=**' if is_quadlet else '**--m**' >> memory setting can be larger than physical +RAM. If a limit of 0 is specified (not using << '**Memory=**' if is_quadlet else '**--m**' >>), the container's memory is not limited. The actual limit may be rounded up to a multiple of the operating system's page size (the value is very large, that's millions of trillions). diff --git a/docs/source/markdown/options/module.md b/docs/source/markdown/options/module.md new file mode 100644 index 0000000000..1b09d7470c --- /dev/null +++ b/docs/source/markdown/options/module.md @@ -0,0 +1,13 @@ +####> This option file is used in: +####> podman podman-build.unit.5.md.in, podman-container.unit.5.md.in, podman-image.unit.5.md.in, podman-kube.unit.5.md.in, podman-network.unit.5.md.in, podman-pod.unit.5.md.in, podman-volume.unit.5.md.in +####> If file is edited, make sure the changes +####> are applicable to all of those. +<< if is_quadlet >> +### `ContainersConfModule=module` +<< else >> +#### **--module**=*module* +<< endif >> + +Load the specified containers.conf(5) module. + +This option can be listed multiple times. diff --git a/docs/source/markdown/options/mount.md b/docs/source/markdown/options/mount.md index bf03d05099..b12d970e51 100644 --- a/docs/source/markdown/options/mount.md +++ b/docs/source/markdown/options/mount.md @@ -1,11 +1,24 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]` +<< else >> #### **--mount**=*type=TYPE,TYPE-SPECIFIC-OPTION[,...]* +<< endif >> Attach a filesystem mount to the container. +<< if is_quadlet >> +Special cases: + +* For `type=volume`, if `source` ends with `.volume`, the Podman named volume generated by the corresponding `.volume` file is used. +* For `type=image`, if `source` ends with `.image`, the image generated by the corresponding `.image` file is used. + +In both cases, the generated systemd service will contain a dependency on the service generated for the corresponding unit. Note: the corresponding `.volume` or `.image` file must exist. +<< endif >> + Current supported mount TYPEs are **artifact**, **bind**, **devpts**, **glob**, **image**, **ramfs**, **tmpfs** and **volume**. Options common to all mount types: diff --git a/docs/source/markdown/options/name.container.md b/docs/source/markdown/options/name.container.md index b7b454bc0b..8c40bc7b51 100644 --- a/docs/source/markdown/options/name.container.md +++ b/docs/source/markdown/options/name.container.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `ContainerName=name` +<< else >> #### **--name**=*name* +<< endif >> Assign a name to the container. @@ -13,8 +17,9 @@ The operator can identify a container in three ways: - Name (“jonah”). Podman generates a UUID for each container, and if no name is assigned to the -container using **--name**, Podman generates a random string name. The name can +container using << '**ContainerName=**' if is_quadlet else '**--name**' >>, +Podman generates a random string name. The name can be useful as a more human-friendly way to identify containers. This works for both background and foreground containers. The container's name is also added to the `/etc/hosts` file using the container's primary IP address (also see the -**--add-host** option). +<< '**AddHost=**' if is_quadlet else '**--add-host**' >> option). diff --git a/docs/source/markdown/options/network-alias.md b/docs/source/markdown/options/network-alias.md index 3c0ed9c9db..887dc30d21 100644 --- a/docs/source/markdown/options/network-alias.md +++ b/docs/source/markdown/options/network-alias.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, pod create, run +####> podman podman-container.unit.5.md.in, create, pod create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `NetworkAlias=alias` +<< else >> #### **--network-alias**=*alias* +<< endif >> Add a network-scoped alias for the <>, setting the alias for all networks that the container joins. To set a name only for a specific network, use the alias option as described under the **--network** option. diff --git a/docs/source/markdown/options/network.image.md b/docs/source/markdown/options/network.image.md index f03a38d9ca..25c2c3cc8a 100644 --- a/docs/source/markdown/options/network.image.md +++ b/docs/source/markdown/options/network.image.md @@ -1,11 +1,21 @@ ####> This option file is used in: -####> podman build, farm build +####> podman build, podman-build.unit.5.md.in, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Network=mode` +<< else >> #### **--network**=*mode*, **--net** +<< endif >> Sets the configuration for network namespaces when handling `RUN` instructions. +<< if is_quadlet >> +Special case: + +* If the `name` of the network ends with `.network`, Quadlet will look for the corresponding `.network` Quadlet unit. If found, Quadlet will use the name of the Network set in the Unit, otherwise, `systemd-$name` is used. The generated systemd service contains a dependency on the service unit generated for that `.network` unit, or on `$name-network.service` if the `.network` unit is not found. Note: the corresponding `.network` file must exist. +<< endif >> + Valid _mode_ values are: - **none**: no networking. diff --git a/docs/source/markdown/options/network.md b/docs/source/markdown/options/network.md index eb0d304f4a..d2af235c4f 100644 --- a/docs/source/markdown/options/network.md +++ b/docs/source/markdown/options/network.md @@ -1,11 +1,28 @@ ####> This option file is used in: -####> podman create, kube play, pod create, run +####> podman podman-container.unit.5.md.in, create, kube play, podman-kube.unit.5.md.in, pod create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Network=mode` +<< else >> #### **--network**=*mode*, **--net** +<< endif >> Set the network mode for the <>. +<< if is_quadlet >> +Special cases: + +* If the `name` of the network ends with `.network`, a Podman network called +`systemd-$name` is used, and the generated systemd service contains +a dependency on the `$name-network.service`. Such a network can be automatically +created by using a `$name.network` Quadlet file. Note: the corresponding `.network` file must exist. + +* If the `name` ends with `.container`, +the container will reuse the network stack of another container created by `$name.container`. +The generated systemd service contains a dependency on `$name.service`. Note: the corresponding `.container` file must exist. +<< endif >> + Valid _mode_ values are: - **bridge[:OPTIONS,...]**: Create a network stack on the default bridge. This is the default for rootful containers. It is possible to specify these additional options: diff --git a/docs/source/markdown/options/opt.md b/docs/source/markdown/options/opt.md new file mode 100644 index 0000000000..634a7dae43 --- /dev/null +++ b/docs/source/markdown/options/opt.md @@ -0,0 +1,40 @@ +####> This option file is used in: +####> podman network create, podman-network.unit.5.md.in +####> If file is edited, make sure the changes +####> are applicable to all of those. +<< if is_quadlet >> +### `Options=option` +<< else >> +#### **--opt**, **-o**=*option* +<< endif >> + +Set driver specific options. + +All drivers accept the `mtu`, `metric`, `no_default_route` and options. + +- `mtu`: Sets the Maximum Transmission Unit (MTU) and takes an integer value. +- `metric` Sets the Route Metric for the default route created in every container joined to this network. Accepts a positive integer value. Can only be used with the Netavark network backend. +- `no_default_route`: If set to 1, Podman will not automatically add a default route to subnets. Routes can still be added +manually by creating a custom route using `--route`. + +Additionally the `bridge` driver supports the following options: + +- `vlan`: This option assign VLAN tag and enables vlan\_filtering. Defaults to none. +- `isolate`: This option isolates networks by blocking traffic between those that have this option enabled. +- `com.docker.network.bridge.name`: This option assigns the given name to the created Linux Bridge +- `com.docker.network.driver.mtu`: Sets the Maximum Transmission Unit (MTU) and takes an integer value. +- `vrf`: This option assigns a VRF to the bridge interface. It accepts the name of the VRF and defaults to none. Can only be used with the Netavark network backend. +- `mode`: This option sets the specified bridge mode on the interface. Defaults to `managed`. Supported values: + - `managed`: Podman creates and deletes the bridge and changes sysctls of it. It adds firewall rules to masquerade outgoing traffic, as well as setup port forwarding for incoming traffic using DNAT. + - `unmanaged`: Podman uses an existing bridge. It must exist by the time you want to start a container which uses the network. There will be no NAT or port forwarding, even if such options were passed while creating the container. + +The `macvlan` and `ipvlan` driver support the following options: + +- `parent`: The host device which is used for the macvlan interface. Defaults to the default route interface. +- `mode`: This option sets the specified ip/macvlan mode on the interface. + - Supported values for `macvlan` are `bridge`, `private`, `vepa`, `passthru`. Defaults to `bridge`. + - Supported values for `ipvlan` are `l2`, `l3`, `l3s`. Defaults to `l2`. + +Additionally the `macvlan` driver supports the `bclim` option: + +- `bclim`: Set the threshold for broadcast queueing. Must be a 32 bit integer. Setting this value to `-1` disables broadcast queueing altogether. diff --git a/docs/source/markdown/options/os.pull.md b/docs/source/markdown/options/os.pull.md index aeb0bdbe5d..af80fb622d 100644 --- a/docs/source/markdown/options/os.pull.md +++ b/docs/source/markdown/options/os.pull.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, pull, run +####> podman create, podman-image.unit.5.md.in, pull, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `OS=os` +<< else >> #### **--os**=*OS* +<< endif >> Override the OS, defaults to hosts, of the image to be pulled. For example, `windows`. Unless overridden, subsequent lookups of the same image in the local storage matches this OS, regardless of the host. diff --git a/docs/source/markdown/options/pids-limit.md b/docs/source/markdown/options/pids-limit.md index d59f6c82b0..ac589d7a28 100644 --- a/docs/source/markdown/options/pids-limit.md +++ b/docs/source/markdown/options/pids-limit.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman create, run, update +####> podman podman-container.unit.5.md.in, create, run, update ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `PidsLimit=limit` +<< else >> #### **--pids-limit**=*limit* +<< endif >> Tune the container's pids limit. Set to **-1** to have unlimited pids for the container. The default is **2048** on systems that support "pids" cgroup controller. diff --git a/docs/source/markdown/options/podman-args.md b/docs/source/markdown/options/podman-args.md new file mode 100644 index 0000000000..7cd28f54a4 --- /dev/null +++ b/docs/source/markdown/options/podman-args.md @@ -0,0 +1,15 @@ +####> This option file is used in: +####> podman podman-build.unit.5.md.in, podman-container.unit.5.md.in, podman-image.unit.5.md.in, podman-kube.unit.5.md.in, podman-network.unit.5.md.in, podman-pod.unit.5.md.in, podman-volume.unit.5.md.in +####> If file is edited, make sure the changes +####> are applicable to all of those. +### `PodmanArgs=` + +This key contains a list of arguments passed directly to the end of the `podman` command +in the generated file. It can be used to access Podman features otherwise unsupported +by the generator. Since the generator is unaware of what unexpected interactions can be +caused by these arguments, it is not recommended to use this option. + +The format of this is a space separated list of arguments, which can optionally be individually +escaped to allow inclusion of whitespace and other control characters. + +This key can be listed multiple times. diff --git a/docs/source/markdown/options/policy.md b/docs/source/markdown/options/policy.md new file mode 100644 index 0000000000..fce4ac6091 --- /dev/null +++ b/docs/source/markdown/options/policy.md @@ -0,0 +1,16 @@ +####> This option file is used in: +####> podman podman-image.unit.5.md.in, pull +####> If file is edited, make sure the changes +####> are applicable to all of those. +<< if is_quadlet >> +### `Policy=always` +<< else >> +#### **--policy** +<< endif >> + +Pull image policy. The default is **always**. + +- `always`: Always pull the image and throw an error if the pull fails. +- `missing`: Only pull the image if it could not be found in the local containers storage. Throw an error if no image could be found and the pull fails. +- `never`: Never pull the image; only use the local version. Throw an error if the image is not present locally. +- `newer`: Pull if the image on the registry is newer than the one in the local containers storage. An image is considered to be newer when the digests are different. Comparing the time stamps is prone to errors. Pull errors are suppressed if a local image was found. diff --git a/docs/source/markdown/options/publish.md b/docs/source/markdown/options/publish.md index 05ec22f197..9562d52eb4 100644 --- a/docs/source/markdown/options/publish.md +++ b/docs/source/markdown/options/publish.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, pod create, run +####> podman podman-container.unit.5.md.in, create, podman-kube.unit.5.md.in, pod create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `PublishPort=[[ip:][hostPort]:]containerPort[/protocol]` +<< else >> #### **--publish**, **-p**=*[[ip:][hostPort]:]containerPort[/protocol]* +<< endif >> Publish a container's port, or range of ports,<<| within this pod>> to the host. diff --git a/docs/source/markdown/options/pull.image.md b/docs/source/markdown/options/pull.image.md index 112e612210..074810b08d 100644 --- a/docs/source/markdown/options/pull.image.md +++ b/docs/source/markdown/options/pull.image.md @@ -2,7 +2,11 @@ ####> podman build, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Pull=policy` +<< else >> #### **--pull**=*policy* +<< endif >> Pull image policy. The default is **missing**. diff --git a/docs/source/markdown/options/pull.md b/docs/source/markdown/options/pull.md index e8c2090aba..95570442fd 100644 --- a/docs/source/markdown/options/pull.md +++ b/docs/source/markdown/options/pull.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-build.unit.5.md.in, podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Pull=policy` +<< else >> #### **--pull**=*policy* +<< endif >> Pull image policy. The default is **missing**. diff --git a/docs/source/markdown/options/read-only-tmpfs.md b/docs/source/markdown/options/read-only-tmpfs.md index 246dff0d87..18841c85bd 100644 --- a/docs/source/markdown/options/read-only-tmpfs.md +++ b/docs/source/markdown/options/read-only-tmpfs.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `ReadOnlyTmpfs=` +<< else >> #### **--read-only-tmpfs** +<< endif >> When running --read-only containers, mount a read-write tmpfs on _/dev_, _/dev/shm_, _/run_, _/tmp_, and _/var/tmp_. The default is **true**. @@ -13,14 +17,17 @@ When running --read-only containers, mount a read-write tmpfs on _/dev_, _/dev/s | false | false | r/w | r/w | | false | true | r/w | r/w | -When **--read-only=true** and **--read-only-tmpfs=true** additional tmpfs are mounted on + +When << '**ReadOnly=true**' if is_quadlet else '**--read-only==true**' >> and +<< '**ReadOnlyTmpfs=true**' if is_quadlet else '**--read-only-tmpfs==true**' >> additional tmpfs are mounted on the /tmp, /run, and /var/tmp directories. -When **--read-only=true** and **--read-only-tmpfs=false** /dev and /dev/shm are marked +When << '**ReadOnly=true**' if is_quadlet else '**--read-only==true**' >> and +<< '**ReadOnlyTmpfs=false**' if is_quadlet else '**--read-only-tmpfs==false**' >> /dev and /dev/shm are marked Read/Only and no tmpfs are mounted on /tmp, /run and /var/tmp. The directories are exposed from the underlying image, meaning they are read-only by default. This makes the container totally read-only. No writable directories exist within the container. In this mode writable directories need to be added via external volumes or mounts. -By default, when **--read-only=false**, the /dev and /dev/shm are read/write, and the /tmp, /run, and /var/tmp are read/write directories from the container image. +By default, when << '**ReadOnly=false**' if is_quadlet else '**--read-only==false**' >> , the /dev and /dev/shm are read/write, and the /tmp, /run, and /var/tmp are read/write directories from the container image. diff --git a/docs/source/markdown/options/read-only.md b/docs/source/markdown/options/read-only.md index 3c16f65a39..bc84389321 100644 --- a/docs/source/markdown/options/read-only.md +++ b/docs/source/markdown/options/read-only.md @@ -1,10 +1,15 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `ReadOnly=` +<< else >> #### **--read-only** +<< endif >> Mount the container's root filesystem as read-only. By default, container root filesystems are writable, allowing processes -to write files anywhere. By specifying the **--read-only** flag, the containers root filesystem are mounted read-only prohibiting any writes. +to write files anywhere. By specifying the << '**ReadOnly=**' if is_quadlet else '**--read-only**' >> flag, +the containers root filesystem are mounted read-only prohibiting any writes. diff --git a/docs/source/markdown/options/restart.md b/docs/source/markdown/options/restart.md index 74e4e7814f..8bc85cd77a 100644 --- a/docs/source/markdown/options/restart.md +++ b/docs/source/markdown/options/restart.md @@ -19,4 +19,4 @@ Podman provides a systemd unit file, podman-restart.service, which restarts cont When running containers in systemd services, use the restart functionality provided by systemd. In other words, do not use this option in a container unit, instead set the `Restart=` systemd directive in the `[Service]` section. -See **podman-systemd.unit**(5) and **systemd.service**(5). +See **podman-systemd**(5) and **systemd.service**(5). diff --git a/docs/source/markdown/options/retry-delay.md b/docs/source/markdown/options/retry-delay.md index 14c652ffb1..52d8cd4368 100644 --- a/docs/source/markdown/options/retry-delay.md +++ b/docs/source/markdown/options/retry-delay.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman artifact pull, artifact push, build, create, farm build, pull, push, run +####> podman artifact pull, artifact push, build, podman-build.unit.5.md.in, podman-container.unit.5.md.in, create, farm build, podman-image.unit.5.md.in, pull, push, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `RetryDelay=duration` +<< else >> #### **--retry-delay**=*duration* +<< endif >> Duration of delay between retry attempts when pulling or pushing images between the registry and local storage in case of failure. The default is to start at two seconds and then exponentially back off. The delay is used when this value is set, and no exponential back off occurs. diff --git a/docs/source/markdown/options/retry.md b/docs/source/markdown/options/retry.md index 08c8c263e3..f110eb47fe 100644 --- a/docs/source/markdown/options/retry.md +++ b/docs/source/markdown/options/retry.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman artifact pull, artifact push, build, create, farm build, pull, push, run +####> podman artifact pull, artifact push, build, podman-build.unit.5.md.in, podman-container.unit.5.md.in, create, farm build, podman-image.unit.5.md.in, pull, push, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Retry=attempts` +<< else >> #### **--retry**=*attempts* +<< endif >> Number of times to retry pulling or pushing images between the registry and local storage in case of failure. Default is **3**. diff --git a/docs/source/markdown/options/rootfs.md b/docs/source/markdown/options/rootfs.md index a30e878ff7..3ee275fe5b 100644 --- a/docs/source/markdown/options/rootfs.md +++ b/docs/source/markdown/options/rootfs.md @@ -1,11 +1,19 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Rootfs=` +<< else >> #### **--rootfs** +<< endif >> If specified, the first argument refers to an exploded container on the file system. +<< if is_quadlet >> +This option conflicts with the `Image` option. + +<< endif >> This is useful to run a container without requiring any image management, the rootfs of the container is assumed to be managed externally. diff --git a/docs/source/markdown/options/secret.image.md b/docs/source/markdown/options/secret.image.md index 46f8ff0f97..7057c85fed 100644 --- a/docs/source/markdown/options/secret.image.md +++ b/docs/source/markdown/options/secret.image.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman build, farm build +####> podman build, podman-build.unit.5.md.in, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Secret=id=id[,src=envOrFile][,env=ENV][,type=file | env]` +<< else >> #### **--secret**=**id=id[,src=*envOrFile*][,env=*ENV*][,type=*file* | *env*]** +<< endif >> Pass secret information to be used in the Containerfile for building images in a safe way that will not end up stored in the final image, or be seen in other stages. diff --git a/docs/source/markdown/options/secret.md b/docs/source/markdown/options/secret.md index 7b8f6e0397..42f246ddd3 100644 --- a/docs/source/markdown/options/secret.md +++ b/docs/source/markdown/options/secret.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Secret=secret[,opt=opt ...]` +<< else >> #### **--secret**=*secret[,opt=opt ...]* +<< endif >> Give the container access to a secret. Can be specified multiple times. diff --git a/docs/source/markdown/options/shm-size.md b/docs/source/markdown/options/shm-size.md index 0f51a3f193..822c912a2c 100644 --- a/docs/source/markdown/options/shm-size.md +++ b/docs/source/markdown/options/shm-size.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman build, create, farm build, pod clone, pod create, run +####> podman build, podman-container.unit.5.md.in, create, farm build, pod clone, pod create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `ShmSize=number[unit]` +<< else >> #### **--shm-size**=*number[unit]* +<< endif >> Size of _/dev/shm_. A _unit_ can be **b** (bytes), **k** (kibibytes), **m** (mebibytes), or **g** (gibibytes). If the unit is omitted, the system uses bytes. If the size is omitted, the default is **64m**. diff --git a/docs/source/markdown/options/stop-signal.md b/docs/source/markdown/options/stop-signal.md index efbca84cf7..19b525ec4d 100644 --- a/docs/source/markdown/options/stop-signal.md +++ b/docs/source/markdown/options/stop-signal.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `StopSignal=signal` +<< else >> #### **--stop-signal**=*signal* +<< endif >> Signal to stop a container. Default is **SIGTERM**. diff --git a/docs/source/markdown/options/stop-timeout.md b/docs/source/markdown/options/stop-timeout.md index a61bad440d..777b2d57a4 100644 --- a/docs/source/markdown/options/stop-timeout.md +++ b/docs/source/markdown/options/stop-timeout.md @@ -1,8 +1,16 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `StopTimeout=seconds` +<< else >> #### **--stop-timeout**=*seconds* +<< endif >> Timeout to stop a container. Default is **10**. Remote connections use local containers.conf for defaults. + +<< if is_quadlet >> +Note, this value should be lower than the actual systemd unit timeout to make sure the `podman rm` command is not killed by systemd. +<< endif >> diff --git a/docs/source/markdown/options/subgidname.md b/docs/source/markdown/options/subgidname.md index d31cb7ea79..65ee9d00cc 100644 --- a/docs/source/markdown/options/subgidname.md +++ b/docs/source/markdown/options/subgidname.md @@ -1,9 +1,13 @@ ####> This option file is used in: -####> podman create, pod clone, pod create, run +####> podman podman-container.unit.5.md.in, create, pod clone, pod create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `SubGIDMap=name` +<< else >> #### **--subgidname**=*name* +<< endif >> Run the container in a new user namespace using the map with _name_ in the _/etc/subgid_ file. If running rootless, the user needs to have the right to use the mapping. See **subgid**(5). -This flag conflicts with **--userns** and **--gidmap**. +This flag conflicts with << '**UserNS=**' if is_quadlet else '**--userns**' >> and << '**GIDMap=**' if is_quadlet else '**--gidmap**' >>. diff --git a/docs/source/markdown/options/subnet.md b/docs/source/markdown/options/subnet.md new file mode 100644 index 0000000000..9119ae24da --- /dev/null +++ b/docs/source/markdown/options/subnet.md @@ -0,0 +1,15 @@ +####> This option file is used in: +####> podman network create, podman-network.unit.5.md.in +####> If file is edited, make sure the changes +####> are applicable to all of those. +<< if is_quadlet >> +### `Subnet=subnet` +<< else >> +#### **--subnet**=*subnet* +<< endif >> + +The subnet in CIDR notation. Can be specified multiple times to allocate more than one subnet for this network. +<< if not is_quadlet >> +The argument order of the **--subnet**, **--gateway** and **--ip-range** options must match. +<< endif >> +This is useful to set a static ipv4 and ipv6 subnet. diff --git a/docs/source/markdown/options/subuidname.md b/docs/source/markdown/options/subuidname.md index ac3e1f372a..4f46c9aac1 100644 --- a/docs/source/markdown/options/subuidname.md +++ b/docs/source/markdown/options/subuidname.md @@ -1,9 +1,13 @@ ####> This option file is used in: -####> podman create, pod clone, pod create, run +####> podman podman-container.unit.5.md.in, create, pod clone, pod create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `SubUIDMap=name` +<< else >> #### **--subuidname**=*name* +<< endif >> Run the container in a new user namespace using the map with _name_ in the _/etc/subuid_ file. If running rootless, the user needs to have the right to use the mapping. See **subuid**(5). -This flag conflicts with **--userns** and **--uidmap**. +This flag conflicts with << '**UserNS=**' if is_quadlet else '**--userns**' >> and << '**UIDMap=**' if is_quadlet else '**--uidmap**' >>. diff --git a/docs/source/markdown/options/sysctl.md b/docs/source/markdown/options/sysctl.md index 1027d5640f..fa5862a7d4 100644 --- a/docs/source/markdown/options/sysctl.md +++ b/docs/source/markdown/options/sysctl.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, pod clone, pod create, run +####> podman podman-container.unit.5.md.in, create, pod clone, pod create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Sysctl=name=value` +<< else >> #### **--sysctl**=*name=value* +<< endif >> Configure namespaced kernel parameters <>. diff --git a/docs/source/markdown/options/tag.md b/docs/source/markdown/options/tag.md index 63a24e59a5..6cce46e5ec 100644 --- a/docs/source/markdown/options/tag.md +++ b/docs/source/markdown/options/tag.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman build, farm build +####> podman build, podman-build.unit.5.md.in, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `ImageTag=imageName` +<< else >> #### **--tag**, **-t**=*imageName* +<< endif >> Specifies the name which is assigned to the resulting image if the build process completes successfully. If _imageName_ does not include a registry name, the registry name *localhost* is prepended to the image name. diff --git a/docs/source/markdown/options/target.md b/docs/source/markdown/options/target.md index 5c5646a915..abb2d10197 100644 --- a/docs/source/markdown/options/target.md +++ b/docs/source/markdown/options/target.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman build, farm build +####> podman build, podman-build.unit.5.md.in, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Target=stageName` +<< else >> #### **--target**=*stageName* +<< endif >> Set the target build stage to build. When building a Containerfile with multiple build stages, --target can be used to specify an intermediate build stage by name as the final stage for the resulting image. Commands after the target stage is skipped. diff --git a/docs/source/markdown/options/tls-verify.md b/docs/source/markdown/options/tls-verify.md index 3c15a77a84..f4ba079d75 100644 --- a/docs/source/markdown/options/tls-verify.md +++ b/docs/source/markdown/options/tls-verify.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman artifact pull, artifact push, auto update, build, container runlabel, create, farm build, kube play, login, machine init, manifest add, manifest create, manifest inspect, manifest push, pull, push, run, search +####> podman artifact pull, artifact push, auto update, build, podman-build.unit.5.md.in, container runlabel, create, farm build, podman-image.unit.5.md.in, kube play, login, machine init, manifest add, manifest create, manifest inspect, manifest push, pull, push, run, search ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `TLSVerify=` +<< else >> #### **--tls-verify** +<< endif >> Require HTTPS and verify certificates when contacting registries (default: **true**). If explicitly set to **true**, TLS verification is used. diff --git a/docs/source/markdown/options/tmpfs.md b/docs/source/markdown/options/tmpfs.md index 11c62756ae..0426c89c78 100644 --- a/docs/source/markdown/options/tmpfs.md +++ b/docs/source/markdown/options/tmpfs.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Tmpfs=` +<< else >> #### **--tmpfs**=*fs* +<< endif >> Create a tmpfs mount. diff --git a/docs/source/markdown/options/tz.md b/docs/source/markdown/options/tz.md index bfe18f0e6a..fae294362a 100644 --- a/docs/source/markdown/options/tz.md +++ b/docs/source/markdown/options/tz.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Timezone=timezone` +<< else >> #### **--tz**=*timezone* +<< endif >> Set timezone in container. This flag takes area-based timezones, GMT time, as well as `local`, which sets the timezone in the container to match the host machine. See `/usr/share/zoneinfo/` for valid timezones. Remote connections use local containers.conf for defaults diff --git a/docs/source/markdown/options/uidmap.container.md b/docs/source/markdown/options/uidmap.container.md index 24a3a6615c..84816bc8a2 100644 --- a/docs/source/markdown/options/uidmap.container.md +++ b/docs/source/markdown/options/uidmap.container.md @@ -1,11 +1,15 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `UIDMap=[flags]container_uid:from_uid[:amount]` +<< else >> #### **--uidmap**=*[flags]container_uid:from_uid[:amount]* +<< endif >> Run the container in a new user namespace using the supplied UID mapping. This -option conflicts with the **--userns** and **--subuidname** options. This +option conflicts with the << '**UserNS=**' if is_quadlet else '**--userns**' >> and << '**SubUIDMap=**' if is_quadlet else '**--subuidname**' >> options. This option provides a way to map host UIDs to container UIDs. It can be passed several times to map different ranges. @@ -20,7 +24,7 @@ The *from_uid* value is based upon the user running the command, either rootful `Rootful mappings` -When **podman <>** is called by a privileged user, the option **--uidmap** +When **podman <>** is called by a privileged user, the option << '**UIDMap=**' if is_quadlet else '**--uidmap**' >> works as a direct mapping between host UIDs and container UIDs. host UID -> container UID @@ -44,7 +48,7 @@ happens over two mapping steps: host UID -> intermediate UID -> container UID -The **--uidmap** option only influences the second mapping step. +The << '**UIDMap=**' if is_quadlet else '**--uidmap**' >> option only influences the second mapping step. The first mapping step is derived by Podman from the contents of the file _/etc/subuid_ and the UID of the user calling Podman. @@ -62,7 +66,7 @@ First mapping step: To be able to use intermediate UIDs greater than zero, the user needs to have subordinate UIDs configured in _/etc/subuid_. See **subuid**(5). -The second mapping step is configured with **--uidmap**. +The second mapping step is configured with << '**UIDMap=**' if is_quadlet else '**--uidmap**' >>. If for example _amount_ is **5** the second mapping step looks like: @@ -87,7 +91,7 @@ Every additional range is added sequentially afterward: `Referencing a host ID from the parent namespace` -As a rootless user, the given host ID in **--uidmap** or **--gidmap** +As a rootless user, the given host ID in << '**UIDMap=**' if is_quadlet else '**--uidmap**' >> or << '**GIDMap=**' if is_quadlet else '**--gidmap**' >> is mapped from the *intermediate namespace* generated by Podman. Sometimes it is desirable to refer directly at the *host namespace*. It is possible to manually do so, by running `podman unshare cat /proc/self/gid_map`, @@ -137,7 +141,7 @@ the rest of subordinate ids to be mapped by Podman at will. Usually, subordinated user and group ids are assigned simultaneously, and for any user the subordinated user ids match the subordinated group ids. -For convenience, if only one of **--uidmap** or **--gidmap** is given, +For convenience, if only one of << '**UIDMap=**' if is_quadlet else '**--uidmap**' >> or << '**GIDMap=**' if is_quadlet else '**--gidmap**' >> is given, podman assumes the mapping refers to both UIDs and GIDs and applies the given mapping to both. If only one value of the two needs to be changed, the mappings should include the `u` or the `g` flags to specify that @@ -152,20 +156,20 @@ For instance given the command podman <> --gidmap "0:0:1000" --gidmap "g2000:2000:1" -Since no **--uidmap** is given, the **--gidmap** is copied to **--uidmap**, +Since no << '**UIDMap=**' if is_quadlet else '**--uidmap**' >> is given, the << '**GIDMap=**' if is_quadlet else '**--gidmap**' >> is copied to << '**UIDMap=**' if is_quadlet else '**--uidmap**' >>, giving a command equivalent to podman <> --gidmap "0:0:1000" --gidmap "2000:2000:1" --uidmap "0:0:1000" The `--gidmap "g2000:2000:1"` used the `g` flag and therefore it was -not copied to **--uidmap**. +not copied to << '**UIDMap=**' if is_quadlet else '**--uidmap**' >>. `Rootless mapping of additional host GIDs` A rootless user may desire to map a specific host group that has already been subordinated within _/etc/subgid_ without specifying the rest of the mapping. -This can be done with **--gidmap "+g*container_gid*:@*host_gid*"** +This can be done with << '**GIDMap="+g*container_gid*:@*host_gid*"**' if is_quadlet else '**--gidmap "+g*container_gid*:@*host_gid*"**' >> Where: @@ -176,9 +180,9 @@ Where: For instance, if a user belongs to the group `2000` and that group is subordinated to that user (with `usermod --add-subgids 2000-2000 $USER`), -the user can map the group into the container with: **--gidmap=+g100000:@2000**. +the user can map the group into the container with: << '**GIDMap=+g100000:@2000**' if is_quadlet else '**--gidmap=+g100000:@2000**' >>. -If this mapping is combined with the option, **--group-add=keep-groups**, the +If this mapping is combined with the option, << '**GroupAdd=keep-groups**' if is_quadlet else '**--group-add=keep-groups**' >>, the process in the container will belong to group `100000`, and files belonging to group `2000` in the host will appear as being owned by group `100000` inside the container. @@ -188,9 +192,9 @@ inside the container. `No subordinate UIDs` Even if a user does not have any subordinate UIDs in _/etc/subuid_, -**--uidmap** can be used to map the normal UID of the user to a +<< '**UIDMap=**' if is_quadlet else '**--uidmap**' >> can be used to map the normal UID of the user to a container UID by running `podman <> --uidmap $container_uid:0:1 --user $container_uid ...`. `Pods` -The **--uidmap** option cannot be called in conjunction with the **--pod** option as a uidmap cannot be set on the container level when in a pod. +The << '**UIDMap=**' if is_quadlet else '**--uidmap**' >> option cannot be called in conjunction with the << '**Pod=**' if is_quadlet else '**--pod**' >> option as a uidmap cannot be set on the container level when in a pod. diff --git a/docs/source/markdown/options/uidmap.pod.md b/docs/source/markdown/options/uidmap.pod.md index 04f7c229c7..39cddfabf6 100644 --- a/docs/source/markdown/options/uidmap.pod.md +++ b/docs/source/markdown/options/uidmap.pod.md @@ -1,10 +1,14 @@ ####> This option file is used in: -####> podman pod clone, pod create +####> podman pod clone, pod create, podman-pod.unit.5.md.in ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `UIDMap=container_uid:from_uid:amount` +<< else >> #### **--uidmap**=*container_uid:from_uid:amount* +<< endif >> Run all containers in the pod in a new user namespace using the supplied mapping. This -option conflicts with the **--userns** and **--subuidname** options. This +option conflicts with the << '**UserNS=.**' if is_quadlet else '**--userns**' >> and << '**SubUIDMap=.**' if is_quadlet else '**--subuidname**' >> options. This option provides a way to map host UIDs to container UIDs. It can be passed several times to map different ranges. diff --git a/docs/source/markdown/options/ulimit.md b/docs/source/markdown/options/ulimit.md index a387b2f02a..b6e2920b39 100644 --- a/docs/source/markdown/options/ulimit.md +++ b/docs/source/markdown/options/ulimit.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, run +####> podman podman-container.unit.5.md.in, create, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Ulimit=option` +<< else >> #### **--ulimit**=*option* +<< endif >> Ulimit options. Sets the ulimits values inside of the container. diff --git a/docs/source/markdown/options/user.md b/docs/source/markdown/options/user.md index 2307fcc9b6..11130bf908 100644 --- a/docs/source/markdown/options/user.md +++ b/docs/source/markdown/options/user.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, exec, run +####> podman podman-container.unit.5.md.in, create, exec, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `User=user[:group]` +<< else >> #### **--user**, **-u**=*user[:group]* +<< endif >> Sets the username or UID used and, optionally, the groupname or GID for the specified command. Both *user* and *group* may be symbolic or numeric. diff --git a/docs/source/markdown/options/userns.container.md b/docs/source/markdown/options/userns.container.md index b128546f1c..6d7fe205e0 100644 --- a/docs/source/markdown/options/userns.container.md +++ b/docs/source/markdown/options/userns.container.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, kube play, run +####> podman podman-container.unit.5.md.in, create, kube play, podman-kube.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `UserNS=mode` +<< else >> #### **--userns**=*mode* +<< endif >> Set the user namespace mode for the container. @@ -14,7 +18,7 @@ If `--userns` is not set, the default value is determined as follows. `--userns=""` (i.e., an empty string) is an alias for `--userns=host`. -This option is incompatible with **--gidmap**, **--uidmap**, **--subuidname** and **--subgidname**. +This option is incompatible with << '**GIDMap=**' if is_quadlet else '**--gidmap**' >>, << '**UIDMap=**' if is_quadlet else '**--uidmap**' >>, << '**SubUIDMap=**' if is_quadlet else '**-**--subuidname****' >> and << '**SubGIDMap=**' if is_quadlet else '**-**--subgidname****' >>. Rootless user --userns=Key mappings: @@ -48,7 +52,7 @@ Using `--userns=auto` when starting new containers does not work as long as any The host UID and GID in *gidmapping* and *uidmapping* can optionally be prefixed with the `@` symbol. In this case, podman will look up the intermediate ID corresponding to host ID and it will map the found intermediate ID to the container id. -For details see **--uidmap**. +For details see << '**UIDMap=**' if is_quadlet else '**--uidmap**' >>. **container:**_id_: join the user namespace of the specified container. diff --git a/docs/source/markdown/options/userns.pod.md b/docs/source/markdown/options/userns.pod.md index 82040b709c..f5ba4ce5b9 100644 --- a/docs/source/markdown/options/userns.pod.md +++ b/docs/source/markdown/options/userns.pod.md @@ -1,12 +1,16 @@ ####> This option file is used in: -####> podman pod clone, pod create +####> podman pod clone, pod create, podman-pod.unit.5.md.in ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `UserNS=mode` +<< else >> #### **--userns**=*mode* +<< endif >> Set the user namespace mode for all the containers in a pod. It defaults to the `PODMAN_USERNS` environment variable. An empty value ("") means user namespaces are disabled. -Rootless user --userns=Key mappings: +Rootless user << '**UserNS=Key**' if is_quadlet else '**--userns=Key**' >> mappings: Key | Host User | Container User ----------|---------------|--------------------- @@ -22,7 +26,7 @@ Valid _mode_ values are: - *gidmapping=*_CONTAINER\_GID:HOST\_GID:SIZE_ to force a GID mapping to be present in the user namespace. - - *size=*_SIZE_: to specify an explicit size for the automatic user namespace. e.g. `--userns=auto:size=8192`. If `size` is not specified, `auto` estimates the size for the user namespace. + - *size=*_SIZE_: to specify an explicit size for the automatic user namespace. e.g. `<< 'UserNS=' if is_quadlet else '--userns=' >>auto:size=8192`. If `size` is not specified, `auto` estimates the size for the user namespace. - *uidmapping=*_CONTAINER\_UID:HOST\_UID:SIZE_ to force a UID mapping to be present in the user namespace. diff --git a/docs/source/markdown/options/variant.build.md b/docs/source/markdown/options/variant.build.md new file mode 100644 index 0000000000..1678aa9c28 --- /dev/null +++ b/docs/source/markdown/options/variant.build.md @@ -0,0 +1,13 @@ +####> This option file is used in: +####> podman build, podman-build.unit.5.md.in +####> If file is edited, make sure the changes +####> are applicable to all of those. +<< if is_quadlet >> +### `Variant=VARIANT` +<< else >> +#### **--variant**=*VARIANT* +<< endif >> + +Set the architecture variant of the image to be built, and that of the base +image to be pulled, if the build uses one, to the provided value instead of +using the architecture variant of the build host. diff --git a/docs/source/markdown/options/variant.container.md b/docs/source/markdown/options/variant.container.md index 522e74bf1a..8202a1a436 100644 --- a/docs/source/markdown/options/variant.container.md +++ b/docs/source/markdown/options/variant.container.md @@ -1,7 +1,11 @@ ####> This option file is used in: -####> podman create, pull, run +####> podman create, podman-image.unit.5.md.in, pull, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Variant=VARIANT` +<< else >> #### **--variant**=*VARIANT* +<< endif >> Use _VARIANT_ instead of the default architecture variant of the container image. Some images can use multiple variants of the arm architectures, such as arm/v5 and arm/v7. diff --git a/docs/source/markdown/options/volume.image.md b/docs/source/markdown/options/volume.image.md index f77a99c4b8..e339209514 100644 --- a/docs/source/markdown/options/volume.image.md +++ b/docs/source/markdown/options/volume.image.md @@ -2,11 +2,21 @@ ####> podman build, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Volume=[HOST-DIR:CONTAINER-DIR[:OPTIONS]]` +<< else >> #### **--volume**, **-v**=*[HOST-DIR:CONTAINER-DIR[:OPTIONS]]* +<< endif >> Mount a host directory into containers when executing RUN instructions during the build. +<< if is_quadlet >> +Special case: + +* If `SOURCE-VOLUME` ends with `.volume`, Quadlet will look for the corresponding `.volume` Quadlet unit. If found, Quadlet will use the name of the Volume set in the Unit, otherwise, `systemd-$name` is used. The generated systemd service contains a dependency on the service unit generated for that `.volume` unit, or on `$name-volume.service` if the `.volume` unit is not found. Note: the corresponding `.volume` file must exist. +<< endif >> + The `OPTIONS` are a comma-separated list and can be one or more of: * [rw|ro] diff --git a/docs/source/markdown/options/volume.md b/docs/source/markdown/options/volume.md index 1f58237b13..150e484bf7 100644 --- a/docs/source/markdown/options/volume.md +++ b/docs/source/markdown/options/volume.md @@ -1,8 +1,12 @@ ####> This option file is used in: -####> podman create, pod clone, pod create, run +####> podman podman-build.unit.5.md.in, podman-container.unit.5.md.in, create, pod clone, pod create, podman-pod.unit.5.md.in, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `Volume=[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]` +<< else >> #### **--volume**, **-v**=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]* +<< endif >> Create a bind mount. If `-v /HOST-DIR:/CONTAINER-DIR` is specified, Podman bind mounts `/HOST-DIR` from the host into `/CONTAINER-DIR` in the Podman @@ -13,6 +17,12 @@ as an anonymously named volume with a randomly generated name, and is removed when the <> is removed via the `--rm` flag or the `podman rm --volumes` command. +<< if is_quadlet >> +Special case: + +* If `SOURCE-VOLUME` ends with `.volume`, a Podman named volume called `systemd-$name` is used as the source, and the generated systemd service contains a dependency on the `$name-volume.service`. Note that the corresponding `.volume` file must exist. +<< endif >> + (Note when using the remote client, including Mac and Windows (excluding WSL2) machines, the volumes are mounted from the remote server, not necessarily the client machine.) The _OPTIONS_ is a comma-separated list and can be one or more of: diff --git a/docs/source/markdown/options/workdir.md b/docs/source/markdown/options/workdir.md index 70a63eba74..734edc4a3b 100644 --- a/docs/source/markdown/options/workdir.md +++ b/docs/source/markdown/options/workdir.md @@ -1,11 +1,15 @@ ####> This option file is used in: -####> podman create, exec, run +####> podman podman-container.unit.5.md.in, create, exec, run ####> If file is edited, make sure the changes ####> are applicable to all of those. +<< if is_quadlet >> +### `WorkingDir=dir` +<< else >> #### **--workdir**, **-w**=*dir* +<< endif >> Working directory inside the container. The default working directory for running binaries within a container is the root directory (**/**). The image developer can set a different default with the WORKDIR instruction. The operator -can override the working directory by using the **-w** option. +can override the working directory by using the << '**WokingDir=**' if is_quadlet else '**-w**' >> option. diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in index 43b544bcf5..425fac0653 100644 --- a/docs/source/markdown/podman-build.1.md.in +++ b/docs/source/markdown/podman-build.1.md.in @@ -481,11 +481,7 @@ Use --stdin to be able to interact from the terminal during the build. @@option uts -#### **--variant**=*variant* - -Set the architecture variant of the image to be built, and that of the base -image to be pulled, if the build uses one, to the provided value instead of -using the architecture variant of the build host. +@@option variant.build @@option volume.image diff --git a/docs/source/markdown/podman-build.unit.5.md.in b/docs/source/markdown/podman-build.unit.5.md.in new file mode 100644 index 0000000000..6571e12529 --- /dev/null +++ b/docs/source/markdown/podman-build.unit.5.md.in @@ -0,0 +1,175 @@ +% podman-build.unit(5) + +# NAME + +podman\-build.unit - systemd unit files for building container images using Podman Quadlet + +# SYNOPSIS + +*name*.build + +# DESCRIPTION + +Build files are named with a `.build` extension and contain a section `[Build]` describing the image +build command. The generated service is a one-time command that ensures that the image is built on +the host from a supplied Containerfile and context directory. Subsequent (re-)starts of the +generated built service will usually finish quickly, as image layer caching will skip unchanged +build steps. + +A minimal `.build` unit needs at least the `ImageTag=` key, and either of `File=` or +`SetWorkingDirectory=` keys. + +Using build units allows containers and volumes to depend on images being built locally. This can be +interesting for creating container images not available on container registries, or for local +testing and development. + +# USAGE SUMMARY + +The `.build` file is parsed by the `podman-system-generator` at boot or reload, generating a systemd +`.service` that runs `podman build`. That service can be managed like any other unit: + +```bash +systemctl --user start myimage-build.service +``` + +The resulting image can be referenced by `.container` or `.volume` units via: + +```ini +Image=myimage.build +``` + +# OPTIONS + +Valid options for `[Build]` section are listed below: + +| **[Build] options** | **podman build equivalent** | +|-------------------------------------|---------------------------------------------| +| Annotation=annotation=value | --annotation=annotation=value | +| Arch=aarch64 | --arch=aarch64 | +| AuthFile=/etc/registry/auth\.json | --authfile=/etc/registry/auth\.json | +| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | +| DNS=192.168.55.1 | --dns=192.168.55.1 | +| DNSOption=ndots:1 | --dns-option=ndots:1 | +| DNSSearch=example.com | --dns-search example.com | +| Environment=foo=bar | --env foo=bar | +| File=/path/to/Containerfile | --file=/path/to/Containerfile | +| ForceRM=false | --force-rm=false | +| GlobalArgs=--log-level=debug | --log-level=debug | +| GroupAdd=keep-groups | --group-add=keep-groups | +| ImageTag=localhost/imagename | --tag=localhost/imagename | +| Label=label | --label=label | +| Network=host | --network=host | +| PodmanArgs=--pull never | --pull never | +| Pull=never | --pull never | +| Retry=5 | --retry=5 | +| RetryDelay=10s | --retry-delay=10s | +| Secret=secret | --secret=id=mysecret,src=path | +| SetWorkingDirectory=unit | Set `WorkingDirectory` of systemd unit file | +| Target=my-app | --target=my-app | +| TLSVerify=false | --tls-verify=false | +| Variant=arm/v7 | --variant=arm/v7 | +| Volume=/source:/dest | --volume /source:/dest | + +@@option quadlet:annotation.image + +@@option quadlet:arch + +@@option quadlet:authfile + +@@option quadlet:module + +@@option quadlet:dns + +@@option quadlet:dns-option.image + +@@option quadlet:dns-search.image + +@@option quadlet:env + +@@option quadlet:file + +@@option quadlet:force-rm + +@@option quadlet:global-args + +@@option quadlet:group-add + +@@option quadlet:tag + +@@option quadlet:label.image + +@@option quadlet:network.image + +@@option quadlet:podman-args + +@@option quadlet:pull + +@@option quadlet:retry + +@@option quadlet:retry-delay + +@@option quadlet:secret.image + +### `SetWorkingDirectory=path` + +Provide context (a working directory) to `podman build`. Supported values are a path, a URL, or the +special keys `file` or `unit` to set the context directory to the parent directory of the file from +the `File=` key or to that of the Quadlet `.build` unit file, respectively. This allows Quadlet to +resolve relative paths. + +When using one of the special keys (`file` or `unit`), the `WorkingDirectory` field of the `Service` +group of the Systemd service unit will also be set to accordingly. Alternatively, users can +explicitly set the `WorkingDirectory` field of the `Service` group in the `.build` file. Please note +that if the `WorkingDirectory` field of the `Service` group is set by the user, Quadlet will not +overwrite it even if `SetWorkingDirectory` is set to `file` or `unit`. + +By providing a URL to `SetWorkingDirectory=` you can instruct `podman build` to clone a Git +repository or download an archive file extracted to a temporary location by `podman build` as build +context. Note that in this case, the `WorkingDirectory` of the Systemd service unit is left +untouched by Quadlet. + +Note that providing context directory is mandatory for a `.build` file, unless a `File=` key has +also been provided. + +@@option quadlet:target + +@@option quadlet:tls-verify + +@@option quadlet:variant.build + +@@option quadlet:volume + + +# EXAMPLES + +### Simple build + +```ini +[Build] +ImageTag=localhost/myapp +File=Containerfile +SetWorkingDirectory=unit +``` + +### From Git repository + +```ini +[Build] +ImageTag=localhost/mygitimage +File=Containerfile +SetWorkingDirectory=https://github.com/example/repo.git +``` + +### Build with secret + +```ini +[Build] +ImageTag=localhost/secureimage +Secret=mysecret +``` + +# SEE ALSO + +[podman-build(1)](podman-build.1.md), +podman-systemd.unit(5)](podman-systemd.unit.5.md), +[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html) diff --git a/docs/source/markdown/podman-container.unit.5.md.in b/docs/source/markdown/podman-container.unit.5.md.in new file mode 100644 index 0000000000..6ddb7b66f6 --- /dev/null +++ b/docs/source/markdown/podman-container.unit.5.md.in @@ -0,0 +1,501 @@ +% podman-container.unit(5) + +# NAME + +podman\-container.unit - systemd unit files for managing containers using Podman Quadlet + +# SYNOPSIS + +*name*.container + +# DESCRIPTION + +Container units are named with a `.container` extension and contain a `[Container]` section describing +the container that is run as a service. The resulting service file contains a line like +`ExecStart=podman run ... image-name`, and most of the keys in this section control the command-line +options passed to Podman. However, some options also affect the details of how systemd is set up to run and +interact with the container. + +By default, the Podman container has the same name as the unit, but with a `systemd-` prefix, i.e. +a `$name.container` file creates a `$name.service` unit and a `systemd-$name` Podman container. The +`ContainerName` option allows for overriding this default name with a user-provided one. + +There is only one required key, `Image`, which defines the container image the service runs. + +# USAGE SUMMARY + +The `.container` file is parsed by the `podman-system-generator` at boot or reload, generating a systemd +`.service` that runs `podman run`. That service can be managed like any other unit: + +```bash +systemctl --user start myimage-container.service +``` + +# OPTIONS + +Valid options for `[Container]` are listed below: + +| **[Container] options** | **podman run equivalent** | +|--------------------------------------|------------------------------------------------------| +| AddCapability=CAP | --cap-add CAP | +| AddDevice=/dev/foo | --device /dev/foo | +| AddHost=example\.com:192.168.10.11 | --add-host example.com:192.168.10.11 | +| Annotation="XYZ" | --annotation "XYZ" | +| AutoUpdate=registry | --label "io.containers.autoupdate=registry" | +| CgroupsMode=no-conmon | --cgroups=no-conmon | +| ContainerName=name | --name name | +| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | +| DNS=192.168.55.1 | --dns=192.168.55.1 | +| DNSOption=ndots:1 | --dns-option=ndots:1 | +| DNSSearch=example.com | --dns-search example.com | +| DropCapability=CAP | --cap-drop=CAP | +| Entrypoint=/foo.sh | --entrypoint=/foo.sh | +| Environment=foo=bar | --env foo=bar | +| EnvironmentFile=/tmp/env | --env-file /tmp/env | +| EnvironmentHost=true | --env-host | +| Exec=/usr/bin/command | Command after image specification - /usr/bin/command | +| ExposeHostPort=50-59 | --expose 50-59 | +| GIDMap=0:10000:10 | --gidmap=0:10000:10 | +| GlobalArgs=--log-level=debug | --log-level=debug | +| Group=1234 | --user UID:1234 | +| GroupAdd=keep-groups | --group-add=keep-groups | +| HealthCmd=/usr/bin/command | --health-cmd=/usr/bin/command | +| HealthInterval=2m | --health-interval=2m | +| HealthLogDestination=/foo/log | --health-log-destination=/foo/log | +| HealthMaxLogCount=5 | --health-max-log-count=5 | +| HealthMaxLogSize=500 | --health-max-log-size=500 | +| HealthOnFailure=kill | --health-on-failure=kill | +| HealthRetries=5 | --health-retries=5 | +| HealthStartPeriod=1m | --health-start-period=period=1m | +| HealthStartupCmd=command | --health-startup-cmd=command | +| HealthStartupInterval=1m | --health-startup-interval=1m | +| HealthStartupRetries=8 | --health-startup-retries=8 | +| HealthStartupSuccess=2 | --health-startup-success=2 | +| HealthStartupTimeout=1m33s | --health-startup-timeout=1m33s | +| HealthTimeout=20s | --health-timeout=20s | +| HostName=example.com | --hostname example.com | +| HttpProxy=true | --http-proxy=true | +| Image=ubi8 | Image specification - ubi8 | +| IP=192.5.0.1 | --ip 192.5.0.1 | +| IP6=2001:db8::1 | --ip6 2001:db8::1 | +| Label="XYZ" | --label "XYZ" | +| LogDriver=journald | --log-driver journald | +| LogOpt=path=/var/log/mykube\.json | --log-opt path=/var/log/mykube\.json | +| Mask=/proc/sys/foo\:/proc/sys/bar | --security-opt mask=/proc/sys/foo:/proc/sys/bar | +| Memory=20g | --memory 20g | +| Mount=type=... | --mount type=... | +| Network=host | --network host | +| NetworkAlias=name | --network-alias name | +| NoNewPrivileges=true | --security-opt no-new-privileges | +| Notify=true | --sdnotify container | +| PidsLimit=10000 | --pids-limit 10000 | +| Pod=pod-name | --pod=pod-name | +| PodmanArgs=--publish 8080:80 | --publish 8080:80 | +| PublishPort=8080:80 | --publish 8080:80 | +| Pull=never | --pull never | +| ReadOnly=true | --read-only | +| ReadOnlyTmpfs=true | --read-only-tmpfs | +| ReloadCmd=/usr/bin/command | Add ExecReload and run exec with the value | +| ReloadSignal=SIGHUP | Add ExecReload and run kill with the signal | +| Retry=5 | --retry=5 | +| RetryDelay=5s | --retry-delay=5s | +| Rootfs=/var/lib/rootfs | --rootfs /var/lib/rootfs | +| RunInit=true | --init | +| SeccompProfile=/tmp/s.json | --security-opt seccomp=/tmp/s.json | +| Secret=secret | --secret=secret[,opt=opt ...] | +| SecurityLabelDisable=true | --security-opt label=disable | +| SecurityLabelFileType=usr_t | --security-opt label=filetype:usr_t | +| SecurityLabelLevel=s0:c1,c2 | --security-opt label=level:s0:c1,c2 | +| SecurityLabelNested=true | --security-opt label=nested | +| SecurityLabelType=spc_t | --security-opt label=type:spc_t | +| ShmSize=100m | --shm-size=100m | +| StartWithPod=true | If Pod= is defined, container is started by pod | +| StopSignal=SIGINT | --stop-signal=SIGINT | +| StopTimeout=20 | --stop-timeout=20 | +| SubGIDMap=gtest | --subgidname=gtest | +| SubUIDMap=utest | --subuidname=utest | +| Sysctl=name=value | --sysctl=name=value | +| Timezone=local | --tz local | +| Tmpfs=/work | --tmpfs /work | +| UIDMap=0:10000:10 | --uidmap=0:10000:10 | +| Ulimit=nofile=1000:10000 | --ulimit nofile=1000:10000 | +| Unmask=ALL | --security-opt unmask=ALL | +| User=bin | --user bin | +| UserNS=keep-id:uid=200,gid=210 | --userns keep-id:uid=200,gid=210 | +| Volume=/source:/dest | --volume /source:/dest | +| WorkingDir=$HOME | --workdir $HOME | + +Description of `[Container]` section are: + + +@@option quadlet:cap-add + +@@option quadlet:device + +@@option quadlet:add-host + +@@option quadlet:annotation.container + +@@option quadlet:auto-update + +@@option quadlet:cgroups + +@@option quadlet:name.container + +@@option quadlet:module + +@@option quadlet:dns + +@@option quadlet:dns-option.container + +@@option quadlet:dns-search.container + +@@option quadlet:cap-drop + +@@option quadlet:entrypoint + +@@option quadlet:env + +@@option quadlet:env-file + +@@option quadlet:env-host + +@@option quadlet:exec + +@@option quadlet:expose + +@@option quadlet:gidmap.container + +@@option quadlet:global-args + +### `Group=gid` + +The (numeric) GID to run as inside the container. This does not need to match the GID on the host, +which can be modified with `UserNS`, but if that is not specified, this GID is also used on the host. + + +@@option quadlet:group-add + +@@option quadlet:health-cmd + +@@option quadlet:health-interval + +@@option quadlet:health-log-destination + +@@option quadlet:health-max-log-count + +@@option quadlet:health-max-log-size + +@@option quadlet:health-on-failure + +@@option quadlet:health-retries + +@@option quadlet:health-start-period + +@@option quadlet:health-startup-cmd + +@@option quadlet:health-startup-interval + +@@option quadlet:health-startup-retries + +@@option quadlet:health-startup-success + +@@option quadlet:health-startup-timeout + +@@option quadlet:health-timeout + +@@option quadlet:hostname.container + +@@option quadlet:http-proxy + +### `Image=name` + +The image to run in the container. +It is recommended to use a fully qualified image name rather than a short name, both for +performance and robustness reasons. + +The format of the name is the same as when passed to `podman pull`. So, it supports using +`:tag` or digests to guarantee the specific image version. + +Special Cases: + +* If the `name` of the image ends with `.image`, Quadlet will use the image pulled by the corresponding `.image` file, and the generated systemd service contains a dependency on the `$name-image.service` (or the service name set in the .image file). Note that the corresponding `.image` file must exist. +* If the `name` of the image ends with `.build`, Quadlet will use the image built by the corresponding `.build` file, and the generated systemd service contains a dependency on the `$name-build.service`. Note: the corresponding `.build` file must exist. + +@@option quadlet:ip + +@@option quadlet:ip6 + +@@option quadlet:label + +@@option quadlet:log-driver + +@@option quadlet:log-opt + +### `Mask=/path/1:/path/2` + +Specify the paths to mask separated by a colon. `Mask=/path/1:/path/2`. A masked path cannot be accessed inside the container. + + +@@option quadlet:memory + +@@option quadlet:mount + +@@option quadlet:network + +@@option quadlet:network-alias + +### `NoNewPrivileges=bool` (defaults to `false`) + +If enabled, this disables the container processes from gaining additional privileges via things like +setuid and file capabilities. + +### `Notify=bool` (defaults to `false`) + +By default, Podman is run in such a way that the systemd startup notify command is handled by +the container runtime. In other words, the service is deemed started when the container runtime +starts the child in the container. However, if the container application supports +[sd_notify](https://www.freedesktop.org/software/systemd/man/sd_notify.html), then setting +`Notify` to true passes the notification details to the container allowing it to notify +of startup on its own. + +In addition, setting `Notify` to `healthy` will postpone startup notifications until such time as +the container is marked healthy, as determined by Podman healthchecks. Note that this requires +setting up a container healthcheck, see the `HealthCmd` option for more. + +@@option quadlet:pids-limit + +### `Pod=name` + +Specify a Quadlet `.pod` unit to link the container to. +The value must take the form of `.pod` and the `.pod` unit must exist. + +Quadlet will add all the necessary parameters to link between the container and the pod and between their corresponding services. + + +@@option quadlet:podman-args + +@@option quadlet:publish + +@@option quadlet:pull + +@@option quadlet:read-only + +@@option quadlet:read-only-tmpfs + +### `ReloadCmd=/usr/bin/command` + +Add `ExecReload` line to the `Service` that runs ` podman exec` with this command in this container. + +In order to execute the reload run `systemctl reload ` + +Mutually exclusive with `ReloadSignal` + +### `ReloadSignal=signal` + +Add `ExecReload` line to the `Service` that runs `podman kill` with this signal which sends the signal to the main container process. + +In order to execute the reload run `systemctl reload ` + +Mutually exclusive with `ReloadCmd` + +@@option quadlet:retry + +@@option quadlet:retry-delay + +@@option quadlet:rootfs + +@@option quadlet:init + +### `SeccompProfile=path` + +Set the seccomp profile to use in the container. If unset, the default podman profile is used. +Set to either the pathname of a JSON file, or `unconfined` to disable the seccomp filters. + +@@option quadlet:secret + +### `SecurityLabelDisable=bool` + +Turn off label separation for the container. + +### `SecurityLabelFileType=label` + +Set the label file type for the container files. + +### `SecurityLabelLevel=s0:c1,c2` + +Set the label process level for the container processes. + +### `SecurityLabelNested=bool` + +Allow SecurityLabels to function within the container. This allows separation of containers created within the container. + +### `SecurityLabelType=type` + +Set the label process type for the container processes. + +@@option quadlet:shm-size + +### `StartWithPod=bool` + +Start the container after the associated pod is created. Default to **true**. + +If `true`, container will be started/stopped/restarted alongside the pod. + +If `false`, the container will not be started when the pod starts. The container will be stopped with the pod. Restarting the pod will also restart the container as long as the container was also running before. + +Note, the container can still be started manually or through a target by configuring the `[Install]` section. The pod will be started as needed in any case. + +@@option quadlet:stop-signal + +@@option quadlet:stop-timeout + +@@option quadlet:subgidname + +@@option quadlet:subuidname + +@@option quadlet:sysctl + +@@option quadlet:tz + +@@option quadlet:tmpfs + +@@option quadlet:uidmap.container + +@@option quadlet:ulimit + +### `Unmask=` + +Specify the paths to unmask separated by a colon. unmask=ALL or /path/1:/path/2, or shell expanded paths (/proc/*): + +If set to `ALL`, Podman will unmask all the paths that are masked or made read-only by default. + +The default masked paths are /proc/acpi, /proc/kcore, /proc/keys, /proc/latency_stats, /proc/sched_debug, /proc/scsi, /proc/timer_list, /proc/timer_stats, /sys/firmware, and /sys/fs/selinux. + +The default paths that are read-only are /proc/asound, /proc/bus, /proc/fs, /proc/irq, /proc/sys, /proc/sysrq-trigger, /sys/fs/cgroup. + +@@option quadlet:user + +@@option quadlet:userns.container + +@@option quadlet:volume + +@@option quadlet:workdir + + +# SERVICE TYPE + +By default, the generator sets `Type=notify` for `.container` units. + +This can be overridden by explicitly setting `Type=` in the `[Service]` section. + +For one-shot containers (e.g., init tasks), use: + +``` +[Service] +Type=oneshot +RemainAfterExit=yes +``` + +Refer to `systemd.service(5)` for full details on service types and related behaviors. + +# INSTALL SECTION + +To ensure a container starts on boot, include an `[Install]` section: + +``` +[Install] +WantedBy=multi-user.target +``` + +Only `Alias=`, `WantedBy=`, `RequiredBy=`, and `UpheldBy=` keys are supported. + +# TIMEOUTS + +Container startup may exceed systemd’s default 90s timeout (e.g., when pulling images). Use: + +``` +[Service] +TimeoutStartSec=900 +``` + +Note: `TimeoutStartSec` is ignored for `Type=oneshot`. + +# NETWORK DEPENDENCIES + +Quadlet adds: + +- `After=network-online.target` (for root units) +- `After=podman-user-wait-network-online.service` (for user units) + +To disable this, add: + +``` +[Quadlet] +DefaultDependencies=false +``` + +# RESOURCE NAMING + +By default, the container is named `systemd-`. Use `ContainerName=` to override. + +Avoid using systemd specifiers like `%N` in resource names—they break inter-resource linking. + +# TEMPLATE UNITS + +Quadlet supports templated container units, e.g., `foo@.container` creates `foo@.service`. + +You can instantiate with: + +```bash +systemctl start foo@bar.service +``` + +You may also symlink instances: + +```bash +ln -s foo@.container foo@bar.container +``` + +Use drop-ins for instance-specific customization: + +``` +foo@bar.container.d/10-override.conf +``` + +# DROP-IN FILES + +Quadlet supports drop-in configuration in `.container.d/` directories. + +For example, a drop-in: + +``` +test.container.d/10-extra.conf +``` + +can override or extend the main unit file. + +Drop-ins follow the same override and merging behavior as systemd units. + +# EXAMPLE + +Minimal container unit: + +``` +[Unit] +Description=A minimal container + +[Container] +Image=quay.io/centos/centos:latest +Exec=sleep 60 + +[Install] +WantedBy=multi-user.target +``` + +# SEE ALSO + +[podman-run(1)](podman-run.1.md), +[podman-systemd.unit(5)](podman-systemd.unit.5.md), +[systemd.service(5)](https://www.freedesktop.org/software/systemd/man/systemd.service.html), +[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html) diff --git a/docs/source/markdown/podman-image.unit.5.md.in b/docs/source/markdown/podman-image.unit.5.md.in new file mode 100644 index 0000000000..294343238e --- /dev/null +++ b/docs/source/markdown/podman-image.unit.5.md.in @@ -0,0 +1,132 @@ +% podman-image.unit(5) + +# NAME + +podman\-image.unit - systemd unit files for managing container image pulls using Podman Quadlet + +# SYNOPSIS + +*name*.image + +# DESCRIPTION + +Image files are named with a `.image` extension and contain a section `[Image]` describing the +container image pull command. The generated service is a one-time command that ensures that the image +exists on the host, pulling it if needed. + +Using image units allows containers and volumes to depend on images being automatically pulled. This is +particularly interesting when using special options to control image pulls. + +# USAGE SUMMARY + +The `.image` file is parsed by the `podman-system-generator` at boot or reload, generating a systemd +`.service` that runs `podman image pull`. + +The reference to the `.image` file can be used in the `.container` file's `Image=` option. + +# OPTIONS + +Valid options for `[Image]` are listed below: + +| **[Image] options** | **podman image pull equivalent** | +|----------------------------------------|--------------------------------------------------| +| AllTags=true | --all-tags | +| Arch=aarch64 | --arch=aarch64 | +| AuthFile=/etc/registry/auth\.json | --authfile=/etc/registry/auth\.json | +| CertDir=/etc/registry/certs | --cert-dir=/etc/registry/certs | +| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | +| Creds=myname\:mypassword | --creds=myname\:mypassword | +| DecryptionKey=/etc/registry\.key | --decryption-key=/etc/registry\.key | +| GlobalArgs=--log-level=debug | --log-level=debug | +| Image=quay\.io/centos/centos:latest | podman image pull quay.io/centos/centos\:latest | +| ImageTag=quay\.io/centos/centos:latest | Use this name when resolving `.image` references | +| OS=windows | --os=windows | +| PodmanArgs=--os=linux | --os=linux | +| Policy=always | --policy=always | +| Retry=5 | --retry=5 | +| RetryDelay=10s | --retry-delay=10s | +| TLSVerify=false | --tls-verify=false | +| Variant=arm/v7 | --variant=arm/v7 | + +@@option quadlet:all-tags + +@@option quadlet:arch + +@@option quadlet:authfile + +@@option quadlet:cert-dir + +@@option quadlet:module + +@@option quadlet:creds + +@@option quadlet:decryption-key + +@@option quadlet:global-args + +### `Image=` + +The image to pull. +It is recommended to use a fully qualified image name rather than a short name, both for +performance and robustness reasons. + +The format of the name is the same as when passed to `podman pull`. So, it supports using +`:tag` or digests to guarantee the specific image version. + +### `ImageTag=` + +Actual FQIN of the referenced `Image`. +Only meaningful when source is a file or directory archive. + +For example, an image saved into a `docker-archive` with the following Podman command: + +`podman image save --format docker-archive --output /tmp/archive-file.tar quay.io/podman/stable:latest` + +requires setting +- `Image=docker-archive:/tmp/archive-file.tar` +- `ImageTag=quay.io/podman/stable:latest` + +@@option quadlet:os.pull + +@@option quadlet:podman-args + +@@option quadlet:policy + +@@option quadlet:retry + +@@option quadlet:retry-delay + +@@option quadlet:tls-verify + +@@option quadlet:variant.container + +# EXAMPLES + +Basic image pull: + +``` +[Image] +Image=quay.io/centos/centos:latest +``` + +Pull from docker archive: + +``` +[Image] +Image=docker-archive:/tmp/centos.tar +ImageTag=quay.io/centos/centos:latest +``` + +Pull with credentials: + +``` +[Image] +Image=quay.io/private/image:latest +Creds=myuser:mypassword +``` + +# SEE ALSO + +[podman-image-pull(1)](podman-image-pull.1.md), +[podman-systemd.unit(5)](podman-systemd.unit.5.md), +[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html) diff --git a/docs/source/markdown/podman-kube-down.1.md b/docs/source/markdown/podman-kube-down.1.md.in similarity index 96% rename from docs/source/markdown/podman-kube-down.1.md rename to docs/source/markdown/podman-kube-down.1.md.in index 14411e1a12..0d523d5fa8 100644 --- a/docs/source/markdown/podman-kube-down.1.md +++ b/docs/source/markdown/podman-kube-down.1.md.in @@ -16,9 +16,7 @@ specified as `-`, `podman kube down` reads the YAML from stdin. The input can al ## OPTIONS -#### **--force** - -Tear down the volumes linked to the PersistentVolumeClaims as part --down +@@option force.kube-down ## EXAMPLES diff --git a/docs/source/markdown/podman-kube-play.1.md.in b/docs/source/markdown/podman-kube-play.1.md.in index 0d4cbec4a6..dd9bd3acf7 100644 --- a/docs/source/markdown/podman-kube-play.1.md.in +++ b/docs/source/markdown/podman-kube-play.1.md.in @@ -213,12 +213,7 @@ Note: You can also override the default isolation type by setting the BUILDAH_ @@option cert-dir -#### **--configmap**=*path* - -Use Kubernetes configmap YAML at path to provide a source for environment variable values within the containers of the pod. (This option is not available with the remote Podman client) - -Note: The *--configmap* option can be used multiple times or a comma-separated list of paths can be used to pass multiple Kubernetes configmap YAMLs. -The YAML file may be in a multi-doc YAML format. But, it must container only configmaps +@@option configmap #### **--context-dir**=*path* diff --git a/docs/source/markdown/podman-kube.unit.5.md.in b/docs/source/markdown/podman-kube.unit.5.md.in new file mode 100644 index 0000000000..d67cefdce3 --- /dev/null +++ b/docs/source/markdown/podman-kube.unit.5.md.in @@ -0,0 +1,131 @@ +% podman-kube.unit(5) + +# NAME + +podman\-kube.unit - systemd unit files for managing Podman Kubernetes YAML deployments using Quadlet + +# SYNOPSIS + +*name*.kube + +# DESCRIPTION + +Kube units are named with a `.kube` extension and contain a `[Kube]` section describing +how `podman kube play` runs as a service. The resulting service file contains a line like +`ExecStart=podman kube play … file.yml`, and most of the keys in this section control the command-line +options passed to Podman. However, some options also affect the details of how systemd is set up to run and +interact with the container. + +There is only one required key, `Yaml`, which defines the path to the Kubernetes YAML file. + +# USAGE SUMMARY + +The `.kube` file is parsed by the `podman-system-generator` at boot or reload, generating a systemd +`.service` that runs `podman kube play`. That service can be managed like any other unit: + +```bash +systemctl --user start name.service +``` + +# OPTIONS + +Valid options for `[Kube]` are listed below: + +| **[Kube] options** | **podman kube play equivalent** | +| ------------------------------------| -----------------------------------------------------------------| +| AutoUpdate=registry | --annotation "io.containers.autoupdate=registry" | +| ConfigMap=/tmp/config.map | --config-map /tmp/config.map | +| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | +| ExitCodePropagation=how | How to propagate container error status | +| GlobalArgs=--log-level=debug | --log-level=debug | +| KubeDownForce=true | --force (for `podman kube down`) | +| LogDriver=journald | --log-driver journald | +| Network=host | --network host | +| PodmanArgs=\-\-annotation=key=value | --annotation=key=value | +| PublishPort=8080:80 | --publish 8080:80 | +| SetWorkingDirectory=yaml | Set `WorkingDirectory` of unit file to location of the YAML file | +| UserNS=keep-id:uid=200,gid=210 | --userns keep-id:uid=200,gid=210 | +| Yaml=/tmp/kube.yaml | podman kube play /tmp/kube.yaml | + +Supported keys in the `[Kube]` section are: + + +### `AutoUpdate=` + +Indicates whether containers will be auto-updated ([podman-auto-update(1)](podman-auto-update.1.md)). AutoUpdate can be specified multiple times. The following values are supported: + +* `registry`: Requires a fully-qualified image reference (e.g., quay.io/podman/stable:latest) to be used to create the container. This enforcement is necessary to know which images to actually check and pull. If an image ID was used, Podman does not know which image to check/pull anymore. + +* `local`: Tells Podman to compare the image a container is using to the image with its raw name in local storage. If an image is updated locally, Podman simply restarts the systemd unit executing the Kubernetes Quadlet. + +* `name/(local|registry)`: Tells Podman to perform the `local` or `registry` autoupdate on the specified container name. + + +@@option quadlet:configmap + +@@option quadlet:module + +### `ExitCodePropagation=how` + +Control how the main PID of the systemd service should exit. The following values are supported: +- `all`: exit non-zero if all containers have failed (i.e., exited non-zero) +- `any`: exit non-zero if any container has failed +- `none`: exit zero and ignore failed containers + +The current default value is `none`. + +@@option quadlet:global-args + +### `KubeDownForce=true` + +Remove all resources, including volumes, when calling `podman kube down`. +Equivalent to the Podman `--force` option. + +@@option quadlet:log-driver + +@@option quadlet:network + +@@option quadlet:podman-args + +@@option quadlet:publish + +### `SetWorkingDirectory=yaml` + +Set the `WorkingDirectory` field of the `Service` group of the Systemd service unit file. +Used to allow `podman kube play` to correctly resolve relative paths. +Supported values are `yaml` and `unit` to set the working directory to that of the YAML or Quadlet Unit file respectively. + +Alternatively, users can explicitly set the `WorkingDirectory` field of the `Service` group in the `.kube` file. +Please note that if the `WorkingDirectory` field of the `Service` group is set, +Quadlet will not set it even if `SetWorkingDirectory` is set + +@@option quadlet:userns.container + +### `Yaml=path` + +The path, absolute or relative to the location of the unit file, to the Kubernetes YAML file to use. + + +# EXAMPLES + +Deploy from local YAML: + +``` +[Unit] +Description=A kubernetes yaml based service +Before=local-fs.target + +[Kube] +Yaml=/opt/k8s/deployment.yml + +[Install] +# Start by default on boot +WantedBy=multi-user.target default.target +``` + +# SEE ALSO + +[podman-kube-generate(1)](podman-kube-generate.1.md), +[podman-kube-play(1)](podman-kube-play.1.md), +[podman-systemd.unit(5)](podman-systemd.unit.5.md), +[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html) diff --git a/docs/source/markdown/podman-network-create.1.md b/docs/source/markdown/podman-network-create.1.md deleted file mode 100644 index d96319c678..0000000000 --- a/docs/source/markdown/podman-network-create.1.md +++ /dev/null @@ -1,215 +0,0 @@ -% podman-network-create 1 - -## NAME -podman\-network-create - Create a Podman network - -## SYNOPSIS -**podman network create** [*options*] [*name*] - -## DESCRIPTION -Create a network configuration for use with Podman. By default, Podman creates a bridge connection. -A *Macvlan* connection can be created with the *-d macvlan* option. A parent device for macvlan or -ipvlan can be designated with the *-o parent=``* or *--network-interface=``* option. - -If no options are provided, Podman assigns a free subnet and name for the network. - -Upon completion of creating the network, Podman displays the name of the newly added network. - -## OPTIONS -#### **--disable-dns** - -Disables the DNS plugin for this network which if enabled, can perform container to container name -resolution. It is only supported with the `bridge` driver, for other drivers it is always disabled. - -#### **--dns**=*ip* - -Set network-scoped DNS resolver/nameserver for containers in this network. If not set, the host servers from `/etc/resolv.conf` is used. It can be overwritten on the container level with the `podman run/create --dns` option. This option can be specified multiple times to set more than one IP. - -#### **--driver**, **-d**=*driver* - -Driver to manage the network. Currently `bridge`, `macvlan` and `ipvlan` are supported. Defaults to `bridge`. -As rootless the `macvlan` and `ipvlan` driver have no access to the host network interfaces because rootless networking requires a separate network namespace. - -The netavark backend allows the use of so called *netavark plugins*, see the -[plugin-API.md](https://github.com/containers/netavark/blob/main/plugin-API.md) -documentation in netavark. The binary must be placed in a specified directory -so podman can discover it, this list is set in `netavark_plugin_dirs` in -**[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)** -under the `[network]` section. - -The name of the plugin can then be used as driver to create a network for your plugin. -The list of all supported drivers and plugins can be seen with `podman info --format {{.Plugins.Network}}`. - -Note that the `macvlan` and `ipvlan` drivers do not support port forwarding. Support for port forwarding -with a plugin depends on the implementation of the plugin. - -#### **--gateway**=*ip* - -Define a gateway for the subnet. To provide a gateway address, a -*subnet* option is required. Can be specified multiple times. -The argument order of the **--subnet**, **--gateway** and **--ip-range** options must match. - -#### **--ignore** - -Ignore the create request if a network with the same name already exists instead of failing. -Note, trying to create a network with an existing name and different parameters does not change the configuration of the existing one. - -#### **--interface-name**=*name* - -This option maps the *network_interface* option in the network config, see **podman network inspect**. -Depending on the driver, this can have different effects; for `bridge`, it uses the bridge interface name. -For `macvlan` and `ipvlan`, it is the parent device on the host. It is the same as `--opt parent=...`. - -#### **--internal** - -Restrict external access of this network when using a `bridge` network. Note when using the CNI backend -DNS will be automatically disabled, see **--disable-dns**. - -When using the `macvlan` or `ipvlan` driver with this option no default route will be added to the container. -Because it bypasses the host network stack no additional restrictions can be set by podman and if a -privileged container is run it can set a default route themselves. If this is a concern then the -container connections should be blocked on your actual network gateway. - -Using the `bridge` driver with this option has the following effects: - - Global IP forwarding sysctls will not be changed in the host network namespace. - - IP forwarding is disabled on the bridge interface instead of setting up a firewall. - - No default route will be added to the container. - -In all cases, aardvark-dns will only resolve container names with this option enabled. -Other queries will be answered with `NXDOMAIN`. - -#### **--ip-range**=*range* - -Allocate container IP from a range. The range must be a either a complete subnet in CIDR notation or be in -the `-` syntax which allows for a more flexible range compared to the CIDR subnet. -The *ip-range* option must be used with a *subnet* option. Can be specified multiple times. -The argument order of the **--subnet**, **--gateway** and **--ip-range** options must match. - -#### **--ipam-driver**=*driver* - -Set the ipam driver (IP Address Management Driver) for the network. When unset podman chooses an -ipam driver automatically based on the network driver. - -Valid values are: - - - `dhcp`: IP addresses are assigned from a dhcp server on the network. When using the netavark backend - the `netavark-dhcp-proxy.socket` must be enabled in order to start the dhcp-proxy when a container is - started, for CNI use the `cni-dhcp.socket` unit instead. - - `host-local`: IP addresses are assigned locally. - - `none`: No ip addresses are assigned to the interfaces. - -View the driver in the **podman network inspect** output under the `ipam_options` field. - -#### **--ipv6** - -Enable IPv6 (Dual Stack) networking. If no subnets are given, it allocates an ipv4 and an ipv6 subnet. - -#### **--label**=*label* - -Set metadata for a network (e.g., --label mykey=value). - -#### **--opt**, **-o**=*option* - -Set driver specific options. - -All drivers accept the `mtu`, `metric`, `no_default_route` and options. - -- `mtu`: Sets the Maximum Transmission Unit (MTU) and takes an integer value. -- `metric` Sets the Route Metric for the default route created in every container joined to this network. Accepts a positive integer value. Can only be used with the Netavark network backend. -- `no_default_route`: If set to 1, Podman will not automatically add a default route to subnets. Routes can still be added -manually by creating a custom route using `--route`. - -Additionally the `bridge` driver supports the following options: - -- `vlan`: This option assign VLAN tag and enables vlan\_filtering. Defaults to none. -- `isolate`: This option isolates networks by blocking traffic between those that have this option enabled. -- `com.docker.network.bridge.name`: This option assigns the given name to the created Linux Bridge -- `com.docker.network.driver.mtu`: Sets the Maximum Transmission Unit (MTU) and takes an integer value. -- `vrf`: This option assigns a VRF to the bridge interface. It accepts the name of the VRF and defaults to none. Can only be used with the Netavark network backend. -- `mode`: This option sets the specified bridge mode on the interface. Defaults to `managed`. Supported values: - - `managed`: Podman creates and deletes the bridge and changes sysctls of it. It adds firewall rules to masquerade outgoing traffic, as well as setup port forwarding for incoming traffic using DNAT. - - `unmanaged`: Podman uses an existing bridge. It must exist by the time you want to start a container which uses the network. There will be no NAT or port forwarding, even if such options were passed while creating the container. - -The `macvlan` and `ipvlan` driver support the following options: - -- `parent`: The host device which is used for the macvlan interface. Defaults to the default route interface. -- `mode`: This option sets the specified ip/macvlan mode on the interface. - - Supported values for `macvlan` are `bridge`, `private`, `vepa`, `passthru`. Defaults to `bridge`. - - Supported values for `ipvlan` are `l2`, `l3`, `l3s`. Defaults to `l2`. - -Additionally the `macvlan` driver supports the `bclim` option: - -- `bclim`: Set the threshold for broadcast queueing. Must be a 32 bit integer. Setting this value to `-1` disables broadcast queueing altogether. - -#### **--route**=*route* - -A static route in the format `,,`. This route will be added to every container in this network. Only available with the netavark backend. It can be specified multiple times if more than one static route is desired. - -#### **--subnet**=*subnet* - -The subnet in CIDR notation. Can be specified multiple times to allocate more than one subnet for this network. -The argument order of the **--subnet**, **--gateway** and **--ip-range** options must match. -This is useful to set a static ipv4 and ipv6 subnet. - -## EXAMPLES - -Create a network with no options. -``` -$ podman network create -podman2 -``` - -Create a network named *newnet* that uses *192.5.0.0/16* for its subnet. -``` -$ podman network create --subnet 192.5.0.0/16 newnet -newnet -``` - -Create an IPv6 network named *newnetv6* with a subnet of *2001:db8::/64*. -``` -$ podman network create --subnet 2001:db8::/64 --ipv6 newnetv6 -newnetv6 -``` - -Create a network named *newnet* that uses *192.168.33.0/24* and defines a gateway as *192.168.33.3*. -``` -$ podman network create --subnet 192.168.33.0/24 --gateway 192.168.33.3 newnet -newnet -``` - -Create a network that uses a *192.168.55.0/24* subnet and has an IP address range of *192.168.55.129 - 192.168.55.254*. -``` -$ podman network create --subnet 192.168.55.0/24 --ip-range 192.168.55.128/25 -podman5 -``` - -Create a network with a static ipv4 and ipv6 subnet and set a gateway. -``` -$ podman network create --subnet 192.168.55.0/24 --gateway 192.168.55.3 --subnet fd52:2a5a:747e:3acd::/64 --gateway fd52:2a5a:747e:3acd::10 -podman4 -``` - -Create a network with a static subnet and a static route. -``` -$ podman network create --subnet 192.168.33.0/24 --route 10.1.0.0/24,192.168.33.10 newnet -``` - -Create a network with a static subnet and a static route without a default -route. -``` -$ podman network create --subnet 192.168.33.0/24 --route 10.1.0.0/24,192.168.33.10 --opt no_default_route=1 newnet -``` - -Create a Macvlan based network using the host interface eth0. Macvlan networks can only be used as root. -``` -$ sudo podman network create -d macvlan -o parent=eth0 --subnet 192.5.0.0/16 newnet -newnet -``` - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-network(1)](podman-network.1.md)**, **[podman-network-inspect(1)](podman-network-inspect.1.md)**, **[podman-network-ls(1)](podman-network-ls.1.md)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)** - -## HISTORY -August 2021, Updated with the new network format by Paul Holzinger - -August 2019, Originally compiled by Brent Baude diff --git a/docs/source/markdown/podman-network-create.1.md.in b/docs/source/markdown/podman-network-create.1.md.in new file mode 100644 index 0000000000..42fa03627b --- /dev/null +++ b/docs/source/markdown/podman-network-create.1.md.in @@ -0,0 +1,114 @@ +% podman-network-create 1 + +## NAME +podman\-network-create - Create a Podman network + +## SYNOPSIS +**podman network create** [*options*] [*name*] + +## DESCRIPTION +Create a network configuration for use with Podman. By default, Podman creates a bridge connection. +A *Macvlan* connection can be created with the *-d macvlan* option. A parent device for macvlan or +ipvlan can be designated with the *-o parent=``* or *--network-interface=``* option. + +If no options are provided, Podman assigns a free subnet and name for the network. + +Upon completion of creating the network, Podman displays the name of the newly added network. + +## OPTIONS + +@@option disable-dns + +@@option dns + +@@option driver + +@@option gateway + +#### **--ignore** + +Ignore the create request if a network with the same name already exists instead of failing. +Note, trying to create a network with an existing name and different parameters does not change the configuration of the existing one. + +@@option interface-name + +@@option internal + +@@option ip-range + +@@option ipam-driver + +@@option ipv6 + +@@option label.network + +@@option opt + +#### **--route**=*route* + +A static route in the format `,,`. This route will be added to every container in this network. Only available with the netavark backend. It can be specified multiple times if more than one static route is desired. + +@@option subnet + +## EXAMPLES + +Create a network with no options. +``` +$ podman network create +podman2 +``` + +Create a network named *newnet* that uses *192.5.0.0/16* for its subnet. +``` +$ podman network create --subnet 192.5.0.0/16 newnet +newnet +``` + +Create an IPv6 network named *newnetv6* with a subnet of *2001:db8::/64*. +``` +$ podman network create --subnet 2001:db8::/64 --ipv6 newnetv6 +newnetv6 +``` + +Create a network named *newnet* that uses *192.168.33.0/24* and defines a gateway as *192.168.33.3*. +``` +$ podman network create --subnet 192.168.33.0/24 --gateway 192.168.33.3 newnet +newnet +``` + +Create a network that uses a *192.168.55.0/24* subnet and has an IP address range of *192.168.55.129 - 192.168.55.254*. +``` +$ podman network create --subnet 192.168.55.0/24 --ip-range 192.168.55.128/25 +podman5 +``` + +Create a network with a static ipv4 and ipv6 subnet and set a gateway. +``` +$ podman network create --subnet 192.168.55.0/24 --gateway 192.168.55.3 --subnet fd52:2a5a:747e:3acd::/64 --gateway fd52:2a5a:747e:3acd::10 +podman4 +``` + +Create a network with a static subnet and a static route. +``` +$ podman network create --subnet 192.168.33.0/24 --route 10.1.0.0/24,192.168.33.10 newnet +``` + +Create a network with a static subnet and a static route without a default +route. +``` +$ podman network create --subnet 192.168.33.0/24 --route 10.1.0.0/24,192.168.33.10 --opt no_default_route=1 newnet +``` + +Create a Macvlan based network using the host interface eth0. Macvlan networks can only be used as root. +``` +$ sudo podman network create -d macvlan -o parent=eth0 --subnet 192.5.0.0/16 newnet +newnet +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-network(1)](podman-network.1.md)**, **[podman-network-inspect(1)](podman-network-inspect.1.md)**, **[podman-network-ls(1)](podman-network-ls.1.md)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)** + +## HISTORY +August 2021, Updated with the new network format by Paul Holzinger + +August 2019, Originally compiled by Brent Baude diff --git a/docs/source/markdown/podman-network.unit.5.md.in b/docs/source/markdown/podman-network.unit.5.md.in new file mode 100644 index 0000000000..8ac5cdd70a --- /dev/null +++ b/docs/source/markdown/podman-network.unit.5.md.in @@ -0,0 +1,127 @@ +% podman-network.unit(5) + +# NAME + +podman\-network.unit - systemd unit files for managing Podman networks using Quadlet + +# SYNOPSIS + +*name*.network + +# DESCRIPTION + +Network files are named with a `.network` extension and contain a section `[Network]` describing the +named Podman network. The generated service is a one-time command that ensures that the network +exists on the host, creating it if needed. + +By default, the Podman network has the same name as the unit, but with a `systemd-` prefix, i.e. for +a network file named `$NAME.network`, the generated Podman network is called `systemd-$NAME`, and +the generated service file is `$NAME-network.service`. The `NetworkName` option allows for +overriding this default name with a user-provided one. + +Please note that stopping the corresponding service will not remove the podman network by default - +this can be overridden by the `NetworkDeleteOnStop=true` option. + +In addition, updating an existing network is not supported. +In order to update the network parameters you will first need to manually remove the podman network and then restart the service. + +Using network units allows containers to depend on networks being automatically pre-created. This is +particularly interesting when using special options to control network creation, as Podman otherwise creates networks with the default options. + +# USAGE SUMMARY + +The `.network` file is parsed by the `podman-system-generator` at boot or reload, generating a systemd +`.service` that runs `podman network create`. + +# OPTIONS + +Valid options for `[Network]` are listed below: + +| **[Network] options** | **podman network create equivalent** | +|-------------------------------------|-----------------------------------------------------------------| +| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | +| DisableDNS=true | --disable-dns | +| DNS=192.168.55.1 | --dns=192.168.55.1 | +| Driver=bridge | --driver bridge | +| Gateway=192.168.55.3 | --gateway 192.168.55.3 | +| GlobalArgs=--log-level=debug | --log-level=debug | +| InterfaceName=enp1 | --interface-name enp1 | +| Internal=true | --internal | +| IPAMDriver=dhcp | --ipam-driver dhcp | +| IPRange=192.168.55.128/25 | --ip-range 192.168.55.128/25 | +| IPv6=true | --ipv6 | +| Label="XYZ" | --label "XYZ" | +| NetworkDeleteOnStop=true | Add ExecStopPost to delete the network when the unit is stopped | +| NetworkName=foo | podman network create foo | +| Options=isolate=true | --opt isolate=true | +| PodmanArgs=--dns=192.168.55.1 | --dns=192.168.55.1 | +| Subnet=192.5.0.0/16 | --subnet 192.5.0.0/16 | + + +@@option quadlet:module + +@@option quadlet:disable-dns + +@@option quadlet:dns + +@@option quadlet:driver + +@@option quadlet:gateway + +@@option quadlet:global-args + +@@option quadlet:interface-name + +@@option quadlet:internal + +@@option quadlet:ipam-driver + +@@option quadlet:ip-range + +@@option quadlet:ipv6 + +@@option quadlet:label.network + +### `NetworkDeleteOnStop=true` (defaults to `false`) + +When set to `true` the network is deleted when the service is stopped + +### `NetworkName=foo` + +The (optional) name of the Podman network. +If this is not specified, the default value is the same name as the unit, but with a `systemd-` prefix, +i.e. a `$name.network` file creates a `systemd-$name` Podman network to avoid +conflicts with user-managed network. + +@@option quadlet:opt + +@@option quadlet:podman-args + +@@option quadlet:subnet + +# EXAMPLES + +Basic bridge network: + +``` +[Network] +NetworkName=private0 +Subnet=10.10.0.0/16 +Gateway=10.10.0.1 +``` + +Enable IPv6 with IPAM driver: + +``` +[Network] +NetworkName=v6net +Subnet=fd00:dead:beef::/64 +IPv6=true +IPAMDriver=host-local +``` + +# SEE ALSO + +[podman-network-create(1)](podman-network-create.1.md), +[podman-systemd.unit(5)](podman-systemd.unit.5.md), +[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html) diff --git a/docs/source/markdown/podman-pod.unit.5.md.in b/docs/source/markdown/podman-pod.unit.5.md.in new file mode 100644 index 0000000000..7af989015b --- /dev/null +++ b/docs/source/markdown/podman-pod.unit.5.md.in @@ -0,0 +1,146 @@ +% podman-pod.unit(5) + +# NAME + +podman\-pod.unit - systemd unit files for managing Podman pods using Quadlet + +# SYNOPSIS + +*name*.pod + +# DESCRIPTION + +Pod units are named with a `.pod` extension and contain a `[Pod]` section describing +the pod that is created and run as a service. The resulting service file contains a line like +`ExecStartPre=podman pod create …`, and most of the keys in this section control the command-line +options passed to Podman. + +By default, the Podman pod has the same name as the unit, but with a `systemd-` prefix, i.e. +a `$name.pod` file creates a `$name-pod.service` unit and a `systemd-$name` Podman pod. The +`PodName` option allows for overriding this default name with a user-provided one. + +# OPTIONS + +Valid options for `[Pod]` are listed below: + +| **[Pod] options** | **podman pod create equivalent** | +|-------------------------------------|----------------------------------------| +| AddHost=example\.com:192.168.10.11 | --add-host example.com:192.168.10.11 | +| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | +| DNS=192.168.55.1 | --dns=192.168.55.1 | +| DNSOption=ndots:1 | --dns-option=ndots:1 | +| DNSSearch=example.com | --dns-search example.com | +| ExitPolicy=stop | --exit-policy stop | +| GIDMap=0:10000:10 | --gidmap=0:10000:10 | +| GlobalArgs=--log-level=debug | --log-level=debug | +| HostName=name | --hostname=name | +| IP=192.5.0.1 | --ip 192.5.0.1 | +| IP6=2001:db8::1 | --ip6 2001:db8::1 | +| Label="XYZ" | --label "XYZ" | +| Network=host | --network host | +| NetworkAlias=name | --network-alias name | +| PodmanArgs=\-\-cpus=2 | --cpus=2 | +| PodName=name | --name=name | +| PublishPort=8080:80 | --publish 8080:80 | +| ServiceName=name | Name the systemd unit `name.service` | +| ShmSize=100m | --shm-size=100m | +| SubGIDMap=gtest | --subgidname=gtest | +| SubUIDMap=utest | --subuidname=utest | +| UIDMap=0:10000:10 | --uidmap=0:10000:10 | +| UserNS=keep-id:uid=200,gid=210 | --userns keep-id:uid=200,gid=210 | +| Volume=/source:/dest | --volume /source:/dest | + +Supported keys in the `[Pod]` section are: + +@@option quadlet:add-host + +@@option quadlet:module + +@@option quadlet:dns + +@@option quadlet:dns-option.container + +@@option quadlet:dns-search.container + +### `ExitPolicy=stop` + +Set the exit policy of the pod when the last container exits. Default for quadlets is **stop**. + +To keep the pod active, set `ExitPolicy=continue`. + +@@option quadlet:gidmap.container + +@@option quadlet:global-args + + +@@option quadlet:hostname.container + +@@option quadlet:ip + +@@option quadlet:ip6 + +@@option quadlet:label + +@@option quadlet:network + +@@option quadlet:network-alias + +@@option quadlet:podman-args + +### `PodName=name` + +The (optional) name of the Podman pod. +If this is not specified, the default value is the same name as the unit, but with a `systemd-` prefix, +i.e. a `$name.pod` file creates a `systemd-$name` Podman pod to avoid conflicts with user-managed pods. + +Please note that pods and containers cannot have the same name. +So, if PodName is set, it must not conflict with any container. + +@@option quadlet:publish + +### `ServiceName=name` + +By default, Quadlet will name the systemd service unit by appending `-pod` to the name of the Quadlet. +Setting this key overrides this behavior by instructing Quadlet to use the provided name. + +Note, the name should not include the `.service` file extension + +@@option quadlet:shm-size + +@@option quadlet:subgidname + +@@option quadlet:subuidname + +@@option quadlet:uidmap.pod + +@@option quadlet:userns.pod + +@@option quadlet:volume + + +# EXAMPLES + +Example for Container in a Pod: + +test.pod: + +``` +[Pod] +PodName=test +centos.container +``` + +centos.container: + +``` +[Container] +Image=quay.io/centos/centos:latest +Exec=sh -c "sleep inf" +Pod=test.pod +``` + +# SEE ALSO + +[podman-kube-play(1)](https://docs.podman.io/en/latest/markdown/podman-kube-play.1.html), +[podman-systemd.unit(5)](podman-systemd.unit.5.md), +[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html) diff --git a/docs/source/markdown/podman-pull.1.md.in b/docs/source/markdown/podman-pull.1.md.in index 71da30f788..6c368eede2 100644 --- a/docs/source/markdown/podman-pull.1.md.in +++ b/docs/source/markdown/podman-pull.1.md.in @@ -43,11 +43,8 @@ $ podman pull oci-archive:/tmp/myimage ``` ## OPTIONS -#### **--all-tags**, **-a** -All tagged images in the repository are pulled. - -*IMPORTANT: When using the all-tags flag, Podman does not iterate over the search registries in the **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)** but always uses docker.io for unqualified image names.* +@@option all-tags @@option arch @@ -69,14 +66,8 @@ Print the usage statement. @@option platform -#### **--policy** - -Pull image policy. The default is **always**. +@@option policy -- `always`: Always pull the image and throw an error if the pull fails. -- `missing`: Only pull the image if it could not be found in the local containers storage. Throw an error if no image could be found and the pull fails. -- `never`: Never pull the image; only use the local version. Throw an error if the image is not present locally. -- `newer`: Pull if the image on the registry is newer than the one in the local containers storage. An image is considered to be newer when the digests are different. Comparing the time stamps is prone to errors. Pull errors are suppressed if a local image was found. #### **--quiet**, **-q** diff --git a/docs/source/markdown/podman-quadlet-basic-usage.7.md b/docs/source/markdown/podman-quadlet-basic-usage.7.md new file mode 100644 index 0000000000..1b17543d88 --- /dev/null +++ b/docs/source/markdown/podman-quadlet-basic-usage.7.md @@ -0,0 +1,218 @@ +% podman-quadlet-basic-usage(7) + +# NAME + +podman\-quadlet\-basic\-usage - Basic usage examples and step-by-step guide for Podman Quadlet + +# DESCRIPTION + +This guide introduces common usage patterns for Podman Quadlet. It provides step-by-step examples for defining +containers, exposing ports, creating volumes, and establishing dependencies using declarative `.container`, `.volume`, +and related unit files. + +Quadlet simplifies container lifecycle management by translating these files into systemd services, making them +manageable with `systemctl`. + +# EXAMPLE 1: RUNNING A SIMPLE CONTAINER + +## Step 1: Create `hello.container` + +```ini +[Unit] +Description=Hello Alpine Container + +[Container] +Image=alpine +Exec=echo Hello from Quadlet! + +[Install] +WantedBy=multi-user.target +``` + +## Step 2: Place the file + +For rootless use: +```bash +mkdir -p ~/.config/containers/systemd +cp hello.container ~/.config/containers/systemd/ +``` + +For rootful use: +```bash +sudo cp hello.container ~/etc/containers/systemd/ +``` + +## Step 3: Reload and enable the service + +For rootless use: +```bash +systemctl --user daemon-reload +systemctl --user start hello.service +``` + +For rootful use: +```bash +sudo systemctl daemon-reload +sudo systemctl enable --now hello.service +``` + +## Expected Output: + +For rootles, check logs using: +```bash +journalctl --user -u hello.service +``` + +For rootful: +```bash +journalctl -u hello.service +``` + +You should see: `Hello from Quadlet!` + +That means the container started, executed the echo statement and exited. + +# EXAMPLE 2: CREATING A NAMED VOLUME + +## Step 1: Create `mydata.volume` + +```ini +[Volume] +VolumeName=mydata +Label=purpose=demo +``` + +## Step 2: Place and reload + +For rootless use: +```bash +mkdir -p ~/.config/containers/systemd +cp mydata.volume ~/.config/containers/systemd/ +systemctl --user daemon-reload +``` + +For rootful use: +```bash +sudo cp mydata.volume /etc/containers/systemd/ +sudo systemctl daemon-reload +``` + +## Step 3: Create the volume + +For rootless use: +```bash +systemctl --user start mydata-volume.service +``` + +For rootful use: +```bash +systemctl start mydata-volume.service +``` + +# EXAMPLE 3: CONTAINER USING A VOLUME + +## Create `with-volume.container` + +```ini +[Unit] +Description=Container with Mounted Volume + +[Container] +Image=alpine +Exec=sh -c "ls /data && echo Hello > /data/hello.txt" +Volume=mydata.volume:/data + +[Install] +WantedBy=default.target +``` + +This container shows all the files on volume and creates the `hello.txt`. + +## Start the container and check the status + +For rootless use: +```bash +cp with-volume.container ~/.config/containers/systemd/ +systemctl --user daemon-reload +systemctl --user start with-volume.service +systemctl --user status with-volume.service +``` + +For rootful use: +```bash +sudo cp with-volume.container /etc/containers/systemd/ +sudo systemctl daemon-reload +sudo systemctl start with-volume.service +sudo systemctl status with-volume.service +``` + +When started for the first time, the `hello.txt` will not appear in the +`systemctl status` output, because it has not been created yet. But when +started for the second time, the output will be: + +``` +hello.txt +``` + +This means the volume is used and is persistent. + +# EXAMPLE 4: EXPOSE CONTAINER PORT TO HOST + +## Create `webserver.container` + +```ini +[Unit] +Description=Nginx Webserver + +[Container] +Image=nginx:alpine +PublishPort=8080:80 + +[Install] +WantedBy=default.target +``` + +## Start the web server + +For rootless use: +```bash +cp webserver.container ~/.config/containers/systemd/ +systemctl --user daemon-reload +systemctl --user start webserver.service +``` + +For rootful use: +```bash +sudo cp webserver.container ~/.config/containers/systemd/ +sudo systemctl daemon-reload +sudo systemctl start webserver.service +``` + +Visit `http://localhost:8080` in your browser. + +# TIPS + +To start a container on system boot, use: + +``` +[Install] +WantedBy=multi-user.target default.target +``` + +If the `foo.service` file is not generated, it usually means there is a syntax +error in your quadlet file. To find the details, use: + +```bash +systemd-analyze --user --generators=true verify foo.service +``` + +# SEE ALSO + +[podman-systemd.unit(5)](podman-systemd.unit.5.md), +[podman-container.unit(5)](podman-container.unit.5.md), +[podman-volume.unit(5)](podman-volume.unit.5.md), +[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html) + +# AUTHORS + +Podman Team diff --git a/docs/source/markdown/podman-systemd.unit.5.md b/docs/source/markdown/podman-systemd.unit.5.md index 480f08eb22..7ee5baa315 100644 --- a/docs/source/markdown/podman-systemd.unit.5.md +++ b/docs/source/markdown/podman-systemd.unit.5.md @@ -8,6 +8,14 @@ podman\-systemd.unit - systemd units using Podman Quadlet *name*.container, *name*.volume, *name*.network, *name*.kube *name*.image, *name*.build *name*.pod +- **`.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). + ### Podman rootful unit search path Quadlet files for the root user can be placed in the following directories ordered in precedence. Meaning duplicate named quadlets found under /run take precedence over ones in /etc, as well as those in /usr: @@ -283,1997 +291,199 @@ Quadlet units allow setting the names of the created resources Note that using systemd specifiers that reference the generated service unit (e.g. `$N`) breaks Quadlet's ability to link between resources as they are translated differently in each service -## Container units [Container] - -Container units are named with a `.container` extension and contain a `[Container]` section describing -the container that is run as a service. The resulting service file contains a line like -`ExecStart=podman run … image-name`, and most of the keys in this section control the command-line -options passed to Podman. However, some options also affect the details of how systemd is set up to run and -interact with the container. - -By default, the Podman container has the same name as the unit, but with a `systemd-` prefix, i.e. -a `$name.container` file creates a `$name.service` unit and a `systemd-$name` Podman container. The -`ContainerName` option allows for overriding this default name with a user-provided one. - -There is only one required key, `Image`, which defines the container image the service runs. - -Valid options for `[Container]` are listed below: - -| **[Container] options** | **podman run equivalent** | -|--------------------------------------|------------------------------------------------------| -| AddCapability=CAP | --cap-add CAP | -| AddDevice=/dev/foo | --device /dev/foo | -| AddHost=example\.com:192.168.10.11 | --add-host example.com:192.168.10.11 | -| Annotation="XYZ" | --annotation "XYZ" | -| AutoUpdate=registry | --label "io.containers.autoupdate=registry" | -| CgroupsMode=no-conmon | --cgroups=no-conmon | -| ContainerName=name | --name name | -| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | -| DNS=192.168.55.1 | --dns=192.168.55.1 | -| DNSOption=ndots:1 | --dns-option=ndots:1 | -| DNSSearch=example.com | --dns-search example.com | -| DropCapability=CAP | --cap-drop=CAP | -| Entrypoint=/foo.sh | --entrypoint=/foo.sh | -| Environment=foo=bar | --env foo=bar | -| EnvironmentFile=/tmp/env | --env-file /tmp/env | -| EnvironmentHost=true | --env-host | -| Exec=/usr/bin/command | Command after image specification - /usr/bin/command | -| ExposeHostPort=50-59 | --expose 50-59 | -| GIDMap=0:10000:10 | --gidmap=0:10000:10 | -| GlobalArgs=--log-level=debug | --log-level=debug | -| Group=1234 | --user UID:1234 | -| GroupAdd=keep-groups | --group-add=keep-groups | -| HealthCmd=/usr/bin/command | --health-cmd=/usr/bin/command | -| HealthInterval=2m | --health-interval=2m | -| HealthLogDestination=/foo/log | --health-log-destination=/foo/log | -| HealthMaxLogCount=5 | --health-max-log-count=5 | -| HealthMaxLogSize=500 | --health-max-log-size=500 | -| HealthOnFailure=kill | --health-on-failure=kill | -| HealthRetries=5 | --health-retries=5 | -| HealthStartPeriod=1m | --health-start-period=period=1m | -| HealthStartupCmd=command | --health-startup-cmd=command | -| HealthStartupInterval=1m | --health-startup-interval=1m | -| HealthStartupRetries=8 | --health-startup-retries=8 | -| HealthStartupSuccess=2 | --health-startup-success=2 | -| HealthStartupTimeout=1m33s | --health-startup-timeout=1m33s | -| HealthTimeout=20s | --health-timeout=20s | -| HostName=example.com | --hostname example.com | -| HttpProxy=true | --http-proxy=true | -| Image=ubi8 | Image specification - ubi8 | -| IP=192.5.0.1 | --ip 192.5.0.1 | -| IP6=2001:db8::1 | --ip6 2001:db8::1 | -| Label="XYZ" | --label "XYZ" | -| LogDriver=journald | --log-driver journald | -| LogOpt=path=/var/log/mykube\.json | --log-opt path=/var/log/mykube\.json | -| Mask=/proc/sys/foo\:/proc/sys/bar | --security-opt mask=/proc/sys/foo:/proc/sys/bar | -| Memory=20g | --memory 20g | -| Mount=type=... | --mount type=... | -| Network=host | --network host | -| NetworkAlias=name | --network-alias name | -| NoNewPrivileges=true | --security-opt no-new-privileges | -| Notify=true | --sdnotify container | -| PidsLimit=10000 | --pids-limit 10000 | -| Pod=pod-name | --pod=pod-name | -| PodmanArgs=--publish 8080:80 | --publish 8080:80 | -| PublishPort=8080:80 | --publish 8080:80 | -| Pull=never | --pull never | -| ReadOnly=true | --read-only | -| ReadOnlyTmpfs=true | --read-only-tmpfs | -| ReloadCmd=/usr/bin/command | Add ExecReload and run exec with the value | -| ReloadSignal=SIGHUP | Add ExecReload and run kill with the signal | -| Retry=5 | --retry=5 | -| RetryDelay=5s | --retry-delay=5s | -| Rootfs=/var/lib/rootfs | --rootfs /var/lib/rootfs | -| RunInit=true | --init | -| SeccompProfile=/tmp/s.json | --security-opt seccomp=/tmp/s.json | -| Secret=secret | --secret=secret[,opt=opt ...] | -| SecurityLabelDisable=true | --security-opt label=disable | -| SecurityLabelFileType=usr_t | --security-opt label=filetype:usr_t | -| SecurityLabelLevel=s0:c1,c2 | --security-opt label=level:s0:c1,c2 | -| SecurityLabelNested=true | --security-opt label=nested | -| SecurityLabelType=spc_t | --security-opt label=type:spc_t | -| ShmSize=100m | --shm-size=100m | -| StartWithPod=true | If Pod= is defined, container is started by pod | -| StopSignal=SIGINT | --stop-signal=SIGINT | -| StopTimeout=20 | --stop-timeout=20 | -| SubGIDMap=gtest | --subgidname=gtest | -| SubUIDMap=utest | --subuidname=utest | -| Sysctl=name=value | --sysctl=name=value | -| Timezone=local | --tz local | -| Tmpfs=/work | --tmpfs /work | -| UIDMap=0:10000:10 | --uidmap=0:10000:10 | -| Ulimit=nofile=1000:10000 | --ulimit nofile=1000:10000 | -| Unmask=ALL | --security-opt unmask=ALL | -| User=bin | --user bin | -| UserNS=keep-id:uid=200,gid=210 | --userns keep-id:uid=200,gid=210 | -| Volume=/source:/dest | --volume /source:/dest | -| WorkingDir=$HOME | --workdir $HOME | - -Description of `[Container]` section are: - -### `AddCapability=` - -Add these capabilities, in addition to the default Podman capability set, to the container. - -This is a space separated list of capabilities. This key can be listed multiple times. - -For example: -``` -AddCapability=CAP_DAC_OVERRIDE CAP_IPC_OWNER -``` - -### `AddDevice=` - -Adds a device node from the host into the container. The format of this is -`HOST-DEVICE[:CONTAINER-DEVICE][:PERMISSIONS]`, where `HOST-DEVICE` is the path of -the device node on the host, `CONTAINER-DEVICE` is the path of the device node in -the container, and `PERMISSIONS` is a list of permissions combining 'r' for read, -'w' for write, and 'm' for mknod(2). The `-` prefix tells Quadlet to add the device -only if it exists on the host. - -This key can be listed multiple times. - -### `AddHost=` - -Add host-to-IP mapping to /etc/hosts. -The format is `hostname:ip`. - -Equivalent to the Podman `--add-host` option. -This key can be listed multiple times. - -### `Annotation=` - -Set one or more OCI annotations on the container. The format is a list of `key=value` items, -similar to `Environment`. - -This key can be listed multiple times. - -### `AutoUpdate=` - -Indicates whether the container will be auto-updated ([podman-auto-update(1)](podman-auto-update.1.md)). The following values are supported: - -* `registry`: Requires a fully-qualified image reference (e.g., quay.io/podman/stable:latest) to be used to create the container. This enforcement is necessary to know which image to actually check and pull. If an image ID was used, Podman does not know which image to check/pull anymore. - -* `local`: Tells Podman to compare the image a container is using to the image with its raw name in local storage. If an image is updated locally, Podman simply restarts the systemd unit executing the container. - -### `CgroupsMode=` +## Quadlet section [Quadlet] +Some quadlet specific configuration is shared between different unit types. Those settings +can be configured in the `[Quadlet]` section. -The cgroups mode of the Podman container. Equivalent to the Podman `--cgroups` option. +Valid options for `[Quadlet]` are listed below: -By default, the cgroups mode of the container created by Quadlet is `split`, -which differs from the default (`enabled`) used by the Podman CLI. +| **[Quadlet] options** | **Description** | +|----------------------------|---------------------------------------------------| +| DefaultDependencies=false | Disable implicit network dependencies to the unit | -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. +### `DefaultDependencies=` -### `ContainerName=` +Add Quadlet's default network dependencies to the unit (default is `true`). -The (optional) name of the Podman container. If this is not specified, the default value -of `systemd-%N` is used, which is the same as the service name but with a `systemd-` -prefix to avoid conflicts with user-managed containers. +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. -### `ContainersConfModule=` +Note, this option is set in the `[Quadlet]` section. The _systemd_ `[Unit]` section +has an option with the same name but a different meaning. -Load the specified containers.conf(5) module. Equivalent to the Podman `--module` option. +## EXAMPLES -This key can be listed multiple times. +Example `test.container`: -### `DNS=` +``` +[Unit] +Description=A minimal container -Set network-scoped DNS resolver/nameserver for containers in this network. +[Container] +# Use the centos image +Image=quay.io/centos/centos:latest -This key can be listed multiple times. +# Use volume and network defined below +Volume=test.volume:/data +Network=test.network -### `DNSOption=` +# In the container we just run sleep +Exec=sleep 60 -Set custom DNS options. +[Service] +# Restart service when sleep finishes +Restart=always +# Extend Timeout to allow time to pull the image +TimeoutStartSec=900 +# ExecStartPre flag and other systemd commands can go here, see systemd.unit(5) man page. +ExecStartPre=/usr/share/mincontainer/setup.sh -This key can be listed multiple times. +[Install] +# Start by default on boot +WantedBy=multi-user.target default.target +``` -### `DNSSearch=` +Example `test.kube`: +``` +[Unit] +Description=A kubernetes yaml based service +Before=local-fs.target -Set custom DNS search domains. Use **DNSSearch=.** to remove the search domain. +[Kube] +Yaml=/opt/k8s/deployment.yml -This key can be listed multiple times. +[Install] +# Start by default on boot +WantedBy=multi-user.target default.target +``` -### `DropCapability=` +Example for locally built image to be used in a container: -Drop these capabilities from the default podman capability set, or `all` to drop all capabilities. +`test.build` +``` +[Build] +# Tag the image to be built +ImageTag=localhost/imagename -This is a space separated list of capabilities. This key can be listed multiple times. +# Set the working directory to the path of the unit file, +# expecting to find a Containerfile/Dockerfile +# + other files needed to build the image +SetWorkingDirectory=unit +``` -For example: +`test.container` ``` -DropCapability=CAP_DAC_OVERRIDE CAP_IPC_OWNER +[Container] +Image=test.build ``` -### `Entrypoint=` - -Override the default ENTRYPOINT from the image. -Equivalent to the Podman `--entrypoint` option. -Specify multi option commands in the form of a JSON string. - -### `Environment=` - -Set an environment variable in the container. This uses the same format as -[services in systemd](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Environment=) -and can be listed multiple times. - -### `EnvironmentFile=` - -Use a line-delimited file to set environment variables in the container. -The path may be absolute or relative to the location of the unit file. -This key may be used multiple times, and the order persists when passed to `podman run`. - -### `EnvironmentHost=` - -Use the host environment inside of the container. - -### `Exec=` - -Additional arguments for the container; this has exactly the same effect as passing -more arguments after a `podman run ` invocation. - -The format is the same as for [systemd command lines](https://www.freedesktop.org/software/systemd/man/systemd.service.html#Command%20lines), -However, unlike the usage scenario for similarly-named systemd `ExecStart=` verb -which operates on the ambient root filesystem, it is very common for container -images to have their own `ENTRYPOINT` or `CMD` metadata which this interacts with. - -The default expectation for many images is that the image will include an `ENTRYPOINT` -with a default binary, and this field will add arguments to that entrypoint. - -Another way to describe this is that it works the same way as the [args field in a Kubernetes pod](https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell). - -### `ExposeHostPort=` - -Exposes a port, or a range of ports (e.g. `50-59`), from the host to the container. Equivalent -to the Podman `--expose` option. - -This key can be listed multiple times. - -### `GIDMap=` - -Run the container in a new user namespace using the supplied GID mapping. -Equivalent to the Podman `--gidmap` option. - -This key can be listed multiple times. - -### `GlobalArgs=` - -This key contains a list of arguments passed directly between `podman` and `run` -in the generated file. It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware -of what unexpected interactions can be caused by these arguments, it is not recommended to use -this option. - -The format of this is a space separated list of arguments, which can optionally be individually -escaped to allow inclusion of whitespace and other control characters. - -This key can be listed multiple times. - -### `Group=` - -The (numeric) GID to run as inside the container. This does not need to match the GID on the host, -which can be modified with `UserNS`, but if that is not specified, this GID is also used on the host. - -Note: when both `User=` and `Group=` are specified, they are combined into a single `--user USER:GROUP` -argument passed to Podman. Using `Group=` without `User=` will result in an error. - -### `GroupAdd=` - -Assign additional groups to the primary user running within the container process. Also supports the `keep-groups` special flag. -Equivalent to the Podman `--group-add` option. - -### `HealthCmd=` - -Set or alter a healthcheck command for a container. A value of none disables existing healthchecks. -Equivalent to the Podman `--health-cmd` option. - -### `HealthInterval=` - -Set an interval for the healthchecks. An interval of disable results in no automatic timer setup. -Equivalent to the Podman `--health-interval` option. - -### `HealthLogDestination=` - -Set the destination of the HealthCheck log. Directory path, local or events_logger (local use container state file) -(Default: local) -Equivalent to the Podman `--health-log-destination` option. - -* `local`: (default) HealthCheck logs are stored in overlay containers. (For example: `$runroot/healthcheck.log`) -* `directory`: creates a log file named `-healthcheck.log` with HealthCheck logs in the specified directory. -* `events_logger`: The log will be written with logging mechanism set by events_logger. It also saves the log to a default directory, for performance on a system with a large number of logs. - -### `HealthMaxLogCount=` - -Set maximum number of attempts in the HealthCheck log file. ('0' value means an infinite number of attempts in the log file) -(Default: 5 attempts) -Equivalent to the Podman `--Health-max-log-count` option. - -### `HealthMaxLogSize=` - -Set maximum length in characters of stored HealthCheck log. ("0" value means an infinite log length) -(Default: 500 characters) -Equivalent to the Podman `--Health-max-log-size` option. - -### `HealthOnFailure=` - -Action to take once the container transitions to an unhealthy state. -The "kill" action in combination integrates best with systemd. Once -the container turns unhealthy, it gets killed, and systemd restarts the -service. -Equivalent to the Podman `--health-on-failure` option. - -### `HealthRetries=` - -The number of retries allowed before a healthcheck is considered to be unhealthy. -Equivalent to the Podman `--health-retries` option. - -### `HealthStartPeriod=` - -The initialization time needed for a container to bootstrap. -Equivalent to the Podman `--health-start-period` option. - -### `HealthStartupCmd=` - -Set a startup healthcheck command for a container. -Equivalent to the Podman `--health-startup-cmd` option. - -### `HealthStartupInterval=` - -Set an interval for the startup healthcheck. An interval of disable results in no automatic timer setup. -Equivalent to the Podman `--health-startup-interval` option. - -### `HealthStartupRetries=` - -The number of attempts allowed before the startup healthcheck restarts the container. -Equivalent to the Podman `--health-startup-retries` option. - -### `HealthStartupSuccess=` - -The number of successful runs required before the startup healthcheck succeeds and the regular healthcheck begins. -Equivalent to the Podman `--health-startup-success` option. - -### `HealthStartupTimeout=` - -The maximum time a startup healthcheck command has to complete before it is marked as failed. -Equivalent to the Podman `--health-startup-timeout` option. - -### `HealthTimeout=` - -The maximum time allowed to complete the healthcheck before an interval is considered failed. -Equivalent to the Podman `--health-timeout` option. - -### `HostName=` - -Sets the host name that is available inside the container. -Equivalent to the Podman `--hostname` option. - -### `HttpProxy=` - -Controls whether proxy environment variables (http_proxy, https_proxy, ftp_proxy, no_proxy) are passed from the Podman process into the container during image pulls and builds. - -Set to `true` to enable proxy inheritance (default Podman behavior) or `false` to disable it. -This option is particularly useful on systems that require proxy configuration for internet access but don't want proxy settings passed to the container runtime. - -Equivalent to the Podman `--http-proxy` option. - -### `Image=` - -The image to run in the container. -It is recommended to use a fully qualified image name rather than a short name, both for -performance and robustness reasons. - -The format of the name is the same as when passed to `podman pull`. So, it supports using -`:tag` or digests to guarantee the specific image version. - -Special Cases: - -* If the `name` of the image ends with `.image`, Quadlet will use the image pulled by the corresponding `.image` file, and the generated systemd service contains a dependency on the `$name-image.service` (or the service name set in the .image file). Note that the corresponding `.image` file must exist. -* If the `name` of the image ends with `.build`, Quadlet will use the image built by the corresponding `.build` file, and the generated systemd service contains a dependency on the `$name-build.service`. Note: the corresponding `.build` file must exist. - -### `IP=` - -Specify a static IPv4 address for the container, for example **10.88.64.128**. -Equivalent to the Podman `--ip` option. - -### `IP6=` - -Specify a static IPv6 address for the container, for example **fd46:db93:aa76:ac37::10**. -Equivalent to the Podman `--ip6` option. - -### `Label=` - -Set one or more OCI labels on the container. The format is a list of `key=value` items, -similar to `Environment`. - -This key can be listed multiple times. - -### `LogDriver=` - -Set the log-driver used by Podman when running the container. -Equivalent to the Podman `--log-driver` option. - -### `LogOpt=` - -Set the log-opt (logging options) used by Podman when running the container. -Equivalent to the Podman `--log-opt` option. -This key can be listed multiple times. - -### `Mask=` - -Specify the paths to mask separated by a colon. `Mask=/path/1:/path/2`. A masked path cannot be accessed inside the container. - -### `Memory=` - -Specify the amount of memory for the container. - -### `Mount=` - -Attach a filesystem mount to the container. -This is equivalent to the Podman `--mount` option, and -generally has the form `type=TYPE,TYPE-SPECIFIC-OPTION[,...]`. - -Special cases: - -* For `type=volume`, if `source` ends with `.volume`, the Podman named volume generated by the corresponding `.volume` file is used. -* For `type=image`, if `source` ends with `.image`, the image generated by the corresponding `.image` file is used. - -In both cases, the generated systemd service will contain a dependency on the service generated for the corresponding unit. Note: the corresponding `.volume` or `.image` file must exist. - -This key can be listed multiple times. - -### `Network=` - -Specify a custom network for the container. This has the same format as the `--network` option -to `podman run`. For example, use `host` to use the host network in the container, or `none` to -not set up networking in the container. - -Special cases: - -* If the `name` of the network ends with `.network`, a Podman network called -`systemd-$name` is used, and the generated systemd service contains -a dependency on the `$name-network.service`. Such a network can be automatically -created by using a `$name.network` Quadlet file. Note: the corresponding `.network` file must exist. - -* If the `name` ends with `.container`, -the container will reuse the network stack of another container created by `$name.container`. -The generated systemd service contains a dependency on `$name.service`. Note: the corresponding `.container` file must exist. - -This key can be listed multiple times. - -### `NetworkAlias=` - -Add a network-scoped alias for the container. This has the same format as the `--network-alias` -option to `podman run`. Aliases can be used to group containers together in DNS resolution: for -example, setting `NetworkAlias=web` on multiple containers will make a DNS query for `web` resolve -to all the containers with that alias. - -This key can be listed multiple times. - -### `NoNewPrivileges=` (defaults to `false`) - -If enabled, this disables the container processes from gaining additional privileges via things like -setuid and file capabilities. - -### `Notify=` (defaults to `false`) - -By default, Podman is run in such a way that the systemd startup notify command is handled by -the container runtime. In other words, the service is deemed started when the container runtime -starts the child in the container. However, if the container application supports -[sd_notify](https://www.freedesktop.org/software/systemd/man/sd_notify.html), then setting -`Notify` to true passes the notification details to the container allowing it to notify -of startup on its own. - -In addition, setting `Notify` to `healthy` will postpone startup notifications until such time as -the container is marked healthy, as determined by Podman healthchecks. Note that this requires -setting up a container healthcheck, see the `HealthCmd` option for more. - -### `PidsLimit=` - -Tune the container's pids limit. -This is equivalent to the Podman `--pids-limit` option. +Example `test.volume`: -### `Pod=` +``` +[Volume] +User=root +Group=root +Label=org.test.Key=value +``` -Specify a Quadlet `.pod` unit to link the container to. -The value must take the form of `.pod` and the `.pod` unit must exist. +Example `test.network`: +``` +[Network] +Subnet=172.16.0.0/24 +Gateway=172.16.0.1 +IPRange=172.16.0.0/28 +Label=org.test.Key=value +``` -Quadlet will add all the necessary parameters to link between the container and the pod and between their corresponding services. +Example for Container in a Pod: +`test.pod` +``` +[Pod] +PodName=test +``` -### `PodmanArgs=` +`centos.container` +``` +[Container] +Image=quay.io/centos/centos:latest +Exec=sh -c "sleep inf" +Pod=test.pod +``` -This key contains a list of arguments passed directly to the end of the `podman run` command -in the generated file (right before the image name in the command line). It can be used to -access Podman features otherwise unsupported by the generator. Since the generator is unaware -of what unexpected interactions can be caused by these arguments, it is not recommended to use -this option. +Example for a Pod with a oneshot Startup Task: -The format of this is a space separated list of arguments, which can optionally be individually -escaped to allow inclusion of whitespace and other control characters. +`test.pod` +``` +[Pod] +PodName=test +ExitPolicy=continue +``` -This key can be listed multiple times. +`startup-task.container` +``` +[Service] +Type=oneshot +RemainAfterExit=yes -### `PublishPort=` +[Container] +Pod=test.pod +Image=quay.io/centos/centos:latest +Exec=sh -c "echo 'setup starting'; sleep 2; echo 'setup complete'" +``` -Exposes a port, or a range of ports (e.g. `50-59`), from the container to the host. Equivalent -to the Podman `--publish` option. The format is similar to the Podman options, which is of -the form `ip:hostPort:containerPort`, `ip::containerPort`, `hostPort:containerPort` or -`containerPort`, where the number of host and container ports must be the same (in the case -of a range). +`app.container` +``` +[Unit] +Requires=startup-task.container +After=startup-task.container -If the IP is set to 0.0.0.0 or not set at all, the port is bound on all IPv4 addresses on -the host; use [::] for IPv6. +[Container] +Pod=test.pod +Image=quay.io/centos/centos:latest +Exec=sh -c "echo 'app running.'; sleep 30" +``` -Note that not listing a host port means that Podman automatically selects one, and it -may be different for each invocation of service. This makes that a less useful option. The -allocated port can be found with the `podman port` command. +Example `s3fs.volume`: -This key can be listed multiple times. +For further details, please see the [s3fs-fuse](https://github.com/s3fs-fuse/s3fs-fuse) project. +Remember to read the [FAQ](https://github.com/s3fs-fuse/s3fs-fuse/wiki/FAQ) -### `Pull=` +> NOTE: Enabling the cache massively speeds up access and write times on static files/objects. -Set the image pull policy. -This is equivalent to the Podman `--pull` option +> However, `use_cache` is [UNBOUNDED](https://github.com/s3fs-fuse/s3fs-fuse/wiki/FAQ#q-how-does-the-local-file-cache-work)! -### `ReadOnly=` (defaults to `false`) +> Be careful, it will fill up with any files accessed on the s3 bucket through the file system. -If enabled, makes the image read-only. +Please remember to set `S3_BUCKET`, `PATH`, `AWS_REGION`. `CACHE_DIRECTORY` should be set up by [systemd](https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#RuntimeDirectory=) -### `ReadOnlyTmpfs=` (defaults to `true`) +``` +[Service] +CacheDirectory=s3fs +ExecStartPre=/usr/local/bin/aws s3api put-object --bucket ${S3_BUCKET} --key ${PATH}/ -If ReadOnly is set to `true`, mount a read-write tmpfs on /dev, /dev/shm, /run, /tmp, and /var/tmp. +[Volume] +Device=${S3_BUCKET}:/${PATH} +Type=fuse.s3fs +VolumeName=s3fs-volume +Options=iam_role,endpoint=${AWS_REGION},use_xattr,listobjectsv2,del_cache,use_cache=${CACHE_DIRECTORY} +# `iam_role` assumes inside EC2, if not, Use `profile=` instead +``` -### `ReloadCmd=` - -Add `ExecReload` line to the `Service` that runs ` podman exec` with this command in this container. - -In order to execute the reload run `systemctl reload ` - -Mutually exclusive with `ReloadSignal` - -### `ReloadSignal=` - -Add `ExecReload` line to the `Service` that runs `podman kill` with this signal which sends the signal to the main container process. - -In order to execute the reload run `systemctl reload ` - -Mutually exclusive with `ReloadCmd` - -### `Retry=` - -Number of times to retry the image pull when a HTTP error occurs. Equivalent to the Podman `--retry` option. - -### `RetryDelay=` - -Delay between retries. Equivalent to the Podman `--retry-delay` option. - -### `Rootfs=` - -The rootfs to use for the container. Rootfs points to a directory on the system that contains the content to be run within the container. This option conflicts with the `Image` option. - -The format of the rootfs is the same as when passed to `podman run --rootfs`, so it supports overlay mounts as well. - -Note: On SELinux systems, the rootfs needs the correct label, which is by default unconfined_u:object_r:container_file_t:s0. - -### `RunInit=` (defaults to `false`) - -If enabled, the container has a minimal init process inside the -container that forwards signals and reaps processes. - -### `SeccompProfile=` - -Set the seccomp profile to use in the container. If unset, the default podman profile is used. -Set to either the pathname of a JSON file, or `unconfined` to disable the seccomp filters. - -### `Secret=` - -Use a Podman secret in the container either as a file or an environment variable. -This is equivalent to the Podman `--secret` option and generally has the form `secret[,opt=opt ...]` - -### `SecurityLabelDisable=` - -Turn off label separation for the container. - -### `SecurityLabelFileType=` - -Set the label file type for the container files. - -### `SecurityLabelLevel=` - -Set the label process level for the container processes. - -### `SecurityLabelNested=` - -Allow SecurityLabels to function within the container. This allows separation of containers created within the container. - -### `SecurityLabelType=` - -Set the label process type for the container processes. - -### `ShmSize=` - -Size of /dev/shm. - -This is equivalent to the Podman `--shm-size` option and generally has the form `number[unit]` - -### `StartWithPod=` - -Start the container after the associated pod is created. Default to **true**. - -If `true`, container will be started/stopped/restarted alongside the pod. - -If `false`, the container will not be started when the pod starts. The container will be stopped with the pod. Restarting the pod will also restart the container as long as the container was also running before. - -Note, the container can still be started manually or through a target by configuring the `[Install]` section. The pod will be started as needed in any case. - -### `StopSignal=` - -Signal to stop a container. Default is **SIGTERM**. - -This is equivalent to the Podman `--stop-signal` option - -### `StopTimeout=` - -Seconds to wait before forcibly stopping the container. - -Note, this value should be lower than the actual systemd unit timeout to make sure the podman rm command is not killed by systemd. - -This is equivalent to the Podman `--stop-timeout` option - -### `SubGIDMap=` - -Run the container in a new user namespace using the map with name in the /etc/subgid file. -Equivalent to the Podman `--subgidname` option. - -### `SubUIDMap=` - -Run the container in a new user namespace using the map with name in the /etc/subuid file. -Equivalent to the Podman `--subuidname` option. - -### `Sysctl=` - -Configures namespaced kernel parameters for the container. The format is `Sysctl=name=value`. - -This is a space separated list of kernel parameters. This key can be listed multiple times. - -For example: -``` -Sysctl=net.ipv6.conf.all.disable_ipv6=1 net.ipv6.conf.all.use_tempaddr=1 -``` - -### `Timezone=` (if unset uses system-configured default) - -The timezone to run the container in. - -### `Tmpfs=` - -Mount a tmpfs in the container. This is equivalent to the Podman `--tmpfs` option, and -generally has the form `CONTAINER-DIR[:OPTIONS]`. - -This key can be listed multiple times. - -### `UIDMap=` - -Run the container in a new user namespace using the supplied UID mapping. -Equivalent to the Podman `--uidmap` option. - -This key can be listed multiple times. - -### `Ulimit=` - -Ulimit options. Sets the ulimits values inside of the container. - -This key can be listed multiple times. - -### `Unmask=` - -Specify the paths to unmask separated by a colon. unmask=ALL or /path/1:/path/2, or shell expanded paths (/proc/*): - -If set to `ALL`, Podman will unmask all the paths that are masked or made read-only by default. - -The default masked paths are /proc/acpi, /proc/kcore, /proc/keys, /proc/latency_stats, /proc/sched_debug, /proc/scsi, /proc/timer_list, /proc/timer_stats, /sys/firmware, and /sys/fs/selinux. - -The default paths that are read-only are /proc/asound, /proc/bus, /proc/fs, /proc/irq, /proc/sys, /proc/sysrq-trigger, /sys/fs/cgroup. - -### `User=` - -The (numeric) UID to run as inside the container. This does not need to match the UID on the host, -which can be modified with `UserNS`, but if that is not specified, this UID is also used on the host. - -Note: when both `User=` and `Group=` are specified, they are combined into a single `--user USER:GROUP` -argument passed to Podman. - -### `UserNS=` - -Set the user namespace mode for the container. This is equivalent to the Podman `--userns` option and -generally has the form `MODE[:OPTIONS,...]`. - -### `Volume=` - -Mount a volume in the container. This is equivalent to the Podman `--volume` option, and -generally has the form `[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]`. - -If `SOURCE-VOLUME` starts with `.`, Quadlet resolves the path relative to the location of the unit file. - -Special case: - -* If `SOURCE-VOLUME` ends with `.volume`, a Podman named volume called `systemd-$name` is used as the source, and the generated systemd service contains a dependency on the `$name-volume.service`. Note that the corresponding `.volume` file must exist. - -This key can be listed multiple times. - -### `WorkingDir=` - -Working directory inside the container. - -The default working directory for running binaries within a container is the root directory (/). The image developer can set a different default with the WORKDIR instruction. This option overrides the working directory by using the -w option. - -## Pod units [Pod] - -Pod units are named with a `.pod` extension and contain a `[Pod]` section describing -the pod that is created and run as a service. The resulting service file contains a line like -`ExecStartPre=podman pod create …`, and most of the keys in this section control the command-line -options passed to Podman. - -By default, the Podman pod has the same name as the unit, but with a `systemd-` prefix, i.e. -a `$name.pod` file creates a `$name-pod.service` unit and a `systemd-$name` Podman pod. The -`PodName` option allows for overriding this default name with a user-provided one. - -Valid options for `[Pod]` are listed below: - -| **[Pod] options** | **podman pod create equivalent** | -|-------------------------------------|----------------------------------------| -| AddHost=example\.com:192.168.10.11 | --add-host example.com:192.168.10.11 | -| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | -| DNS=192.168.55.1 | --dns=192.168.55.1 | -| DNSOption=ndots:1 | --dns-option=ndots:1 | -| DNSSearch=example.com | --dns-search example.com | -| ExitPolicy=stop | --exit-policy stop | -| GIDMap=0:10000:10 | --gidmap=0:10000:10 | -| GlobalArgs=--log-level=debug | --log-level=debug | -| HostName=name | --hostname=name | -| IP=192.5.0.1 | --ip 192.5.0.1 | -| IP6=2001:db8::1 | --ip6 2001:db8::1 | -| Label="XYZ" | --label "XYZ" | -| Network=host | --network host | -| NetworkAlias=name | --network-alias name | -| PodmanArgs=\-\-cpus=2 | --cpus=2 | -| PodName=name | --name=name | -| PublishPort=8080:80 | --publish 8080:80 | -| ServiceName=name | Name the systemd unit `name.service` | -| ShmSize=100m | --shm-size=100m | -| SubGIDMap=gtest | --subgidname=gtest | -| SubUIDMap=utest | --subuidname=utest | -| UIDMap=0:10000:10 | --uidmap=0:10000:10 | -| UserNS=keep-id:uid=200,gid=210 | --userns keep-id:uid=200,gid=210 | -| Volume=/source:/dest | --volume /source:/dest | - -Supported keys in the `[Pod]` section are: - -### `AddHost=` - -Add host-to-IP mapping to /etc/hosts. -The format is `hostname:ip`. - -Equivalent to the Podman `--add-host` option. -This key can be listed multiple times. - -### `ContainersConfModule=` - -Load the specified containers.conf(5) module. Equivalent to the Podman `--module` option. - -This key can be listed multiple times. - -### `DNS=` - -Set network-scoped DNS resolver/nameserver for containers in this pod. - -This key can be listed multiple times. - -### `DNSOption=` - -Set custom DNS options. - -This key can be listed multiple times. - -### `DNSSearch=` - -Set custom DNS search domains. Use **DNSSearch=.** to remove the search domain. - -This key can be listed multiple times. - -### `ExitPolicy=` - -Set the exit policy of the pod when the last container exits. Default for quadlets is **stop**. - -To keep the pod active, set `ExitPolicy=continue`. - -### `GIDMap=` - -Create the pod in a new user namespace using the supplied GID mapping. -Equivalent to the Podman `--gidmap` option. - -This key can be listed multiple times. - -### `GlobalArgs=` - -This key contains a list of arguments passed directly between `podman` and `pod` -in the generated file. It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware -of what unexpected interactions can be caused by these arguments, it is not recommended to use -this option. - -The format of this is a space separated list of arguments, which can optionally be individually -escaped to allow inclusion of whitespace and other control characters. - -This key can be listed multiple times. - -### `HostName=` - -Set the pod’s hostname inside all containers. - -The given hostname is also added to the /etc/hosts file using the container’s primary IP address (also see the `--add-host` option). - -Equivalent to the Podman `--hostname` option. -This key can be listed multiple times. - -### `IP=` - -Specify a static IPv4 address for the pod, for example **10.88.64.128**. -Equivalent to the Podman `--ip` option. - -### `IP6=` - -Specify a static IPv6 address for the pod, for example **fd46:db93:aa76:ac37::10**. -Equivalent to the Podman `--ip6` option. - -### `Label=` - -Set one or more OCI labels on the pod. The format is a list of -`key=value` items, similar to `Environment`. - -This key can be listed multiple times. - -### `Network=` - -Specify a custom network for the pod. -This has the same format as the `--network` option to `podman pod create`. -For example, use `host` to use the host network in the pod, or `none` to not set up networking in the pod. - -Special case: - -* If the `name` of the network ends with `.network`, Quadlet will look for the corresponding `.network` Quadlet unit. If found, Quadlet will use the name of the Network set in the Unit, otherwise, `systemd-$name` is used. - -The generated systemd service contains a dependency on the service unit generated for that `.network` unit. Note: the corresponding `.network` file must exist. - -This key can be listed multiple times. - -### `NetworkAlias=` - -Add a network-scoped alias for the pod. This has the same format as the `--network-alias` option to -`podman pod create`. Aliases can be used to group containers together in DNS resolution: for -example, setting `NetworkAlias=web` on multiple containers will make a DNS query for `web` resolve -to all the containers with that alias. - -This key can be listed multiple times. - -### `PodmanArgs=` - -This key contains a list of arguments passed directly to the end of the `podman pod create` command -in the generated file. It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware -of what unexpected interactions can be caused by these arguments, is not recommended to use -this option. - -The format of this is a space separated list of arguments, which can optionally be individually -escaped to allow inclusion of whitespace and other control characters. - -This key can be listed multiple times. - -### `PodName=` - -The (optional) name of the Podman pod. -If this is not specified, the default value is the same name as the unit, but with a `systemd-` prefix, -i.e. a `$name.pod` file creates a `systemd-$name` Podman pod to avoid conflicts with user-managed pods. - -Please note that pods and containers cannot have the same name. -So, if PodName is set, it must not conflict with any container. - -### `PublishPort=` - -Exposes a port, or a range of ports (e.g. `50-59`), from the pod to the host. Equivalent -to the Podman `--publish` option. The format is similar to the Podman options, which is of -the form `ip:hostPort:containerPort`, `ip::containerPort`, `hostPort:containerPort` or -`containerPort`, where the number of host and container ports must be the same (in the case -of a range). - -If the IP is set to 0.0.0.0 or not set at all, the port is bound on all IPv4 addresses on -the host; use [::] for IPv6. - -Note that not listing a host port means that Podman automatically selects one, and it -may be different for each invocation of service. This makes that a less useful option. The -allocated port can be found with the `podman port` command. - -When using `host` networking via `Network=host`, the `PublishPort=` option cannot be used. - -This key can be listed multiple times. - - -### `ServiceName=` - -By default, Quadlet will name the systemd service unit by appending `-pod` to the name of the Quadlet. -Setting this key overrides this behavior by instructing Quadlet to use the provided name. - -Note, the name should not include the `.service` file extension - -### `ShmSize=` - -Size of /dev/shm. - -This is equivalent to the Podman `--shm-size` option and generally has the form `number[unit]` - -### `SubGIDMap=` - -Create the pod in a new user namespace using the map with name in the /etc/subgid file. -Equivalent to the Podman `--subgidname` option. - -### `SubUIDMap=` - -Create the pod in a new user namespace using the map with name in the /etc/subuid file. -Equivalent to the Podman `--subuidname` option. - -### `UIDMap=` - -Create the pod in a new user namespace using the supplied UID mapping. -Equivalent to the Podman `--uidmap` option. - -This key can be listed multiple times. - -### `UserNS=` - -Set the user namespace mode for the pod. This is equivalent to the Podman `--userns` option and -generally has the form `MODE[:OPTIONS,...]`. - -### `Volume=` - -Mount a volume in the pod. This is equivalent to the Podman `--volume` option, and -generally has the form `[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]`. - -If `SOURCE-VOLUME` starts with `.`, Quadlet resolves the path relative to the location of the unit file. - -Special case: - -* If `SOURCE-VOLUME` ends with `.volume`, Quadlet will look for the corresponding `.volume` Quadlet unit. If found, Quadlet will use the name of the Volume set in the Unit, otherwise, `systemd-$name` is used. Note: the corresponding `.volume` file must exist. - -The generated systemd service contains a dependency on the service unit generated for that `.volume` unit, -or on `$name-volume.service` if the `.volume` unit is not found. - -This key can be listed multiple times. - -## Kube units [Kube] - -Kube units are named with a `.kube` extension and contain a `[Kube]` section describing -how `podman kube play` runs as a service. The resulting service file contains a line like -`ExecStart=podman kube play … file.yml`, and most of the keys in this section control the command-line -options passed to Podman. However, some options also affect the details of how systemd is set up to run and -interact with the container. - -There is only one required key, `Yaml`, which defines the path to the Kubernetes YAML file. - -Valid options for `[Kube]` are listed below: - -| **[Kube] options** | **podman kube play equivalent** | -| ------------------------------------| -----------------------------------------------------------------| -| AutoUpdate=registry | --annotation "io.containers.autoupdate=registry" | -| ConfigMap=/tmp/config.map | --config-map /tmp/config.map | -| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | -| ExitCodePropagation=how | How to propagate container error status | -| GlobalArgs=--log-level=debug | --log-level=debug | -| KubeDownForce=true | --force (for `podman kube down`) | -| LogDriver=journald | --log-driver journald | -| Network=host | --network host | -| PodmanArgs=\-\-annotation=key=value | --annotation=key=value | -| PublishPort=8080:80 | --publish 8080:80 | -| SetWorkingDirectory=yaml | Set `WorkingDirectory` of unit file to location of the YAML file | -| UserNS=keep-id:uid=200,gid=210 | --userns keep-id:uid=200,gid=210 | -| Yaml=/tmp/kube.yaml | podman kube play /tmp/kube.yaml | - -Supported keys in the `[Kube]` section are: - -### `AutoUpdate=` - -Indicates whether containers will be auto-updated ([podman-auto-update(1)](podman-auto-update.1.md)). AutoUpdate can be specified multiple times. The following values are supported: - -* `registry`: Requires a fully-qualified image reference (e.g., quay.io/podman/stable:latest) to be used to create the container. This enforcement is necessary to know which images to actually check and pull. If an image ID was used, Podman does not know which image to check/pull anymore. - -* `local`: Tells Podman to compare the image a container is using to the image with its raw name in local storage. If an image is updated locally, Podman simply restarts the systemd unit executing the Kubernetes Quadlet. - -* `name/(local|registry)`: Tells Podman to perform the `local` or `registry` autoupdate on the specified container name. - -### `ConfigMap=` - -Pass the Kubernetes ConfigMap YAML path to `podman kube play` via the `--configmap` argument. -Unlike the `configmap` argument, the value may contain only one path but -it may be absolute or relative to the location of the unit file. - -This key may be used multiple times - -### `ContainersConfModule=` - -Load the specified containers.conf(5) module. Equivalent to the Podman `--module` option. - -This key can be listed multiple times. - -### `ExitCodePropagation=` - -Control how the main PID of the systemd service should exit. The following values are supported: -- `all`: exit non-zero if all containers have failed (i.e., exited non-zero) -- `any`: exit non-zero if any container has failed -- `none`: exit zero and ignore failed containers - -The current default value is `none`. - -### `GlobalArgs=` - -This key contains a list of arguments passed directly between `podman` and `kube` -in the generated file. It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware -of what unexpected interactions can be caused by these arguments, it is not recommended to use -this option. - -The format of this is a space separated list of arguments, which can optionally be individually -escaped to allow inclusion of whitespace and other control characters. - -This key can be listed multiple times. - -### `KubeDownForce=` - -Remove all resources, including volumes, when calling `podman kube down`. -Equivalent to the Podman `--force` option. - -### `LogDriver=` - -Set the log-driver Podman uses when running the container. -Equivalent to the Podman `--log-driver` option. - -### `Network=` - -Specify a custom network for the container. This has the same format as the `--network` option -to `podman kube play`. For example, use `host` to use the host network in the container, or `none` to -not set up networking in the container. - -Special case: - -* If the `name` of the network ends with `.network`, a Podman network called `systemd-$name` is used, and the generated systemd service contains a dependency on the `$name-network.service`. Such a network can be automatically created by using a `$name.network` Quadlet file. Note: the corresponding `.network` file must exist. - -This key can be listed multiple times. - -### `PodmanArgs=` - -This key contains a list of arguments passed directly to the end of the `podman kube play` command -in the generated file (right before the path to the yaml file in the command line). It can be used to -access Podman features otherwise unsupported by the generator. Since the generator is unaware -of what unexpected interactions can be caused by these arguments, is not recommended to use -this option. - -The format of this is a space separated list of arguments, which can optionally be individually -escaped to allow inclusion of whitespace and other control characters. - -This key can be listed multiple times. - -### `PublishPort=` - -Exposes a port, or a range of ports (e.g. `50-59`), from the container to the host. Equivalent -to the `podman kube play`'s `--publish` option. The format is similar to the Podman options, which is of -the form `ip:hostPort:containerPort`, `ip::containerPort`, `hostPort:containerPort` or -`containerPort`, where the number of host and container ports must be the same (in the case -of a range). - -If the IP is set to 0.0.0.0 or not set at all, the port is bound on all IPv4 addresses on -the host; use [::] for IPv6. - -The list of published ports specified in the unit file is merged with the list of ports specified -in the Kubernetes YAML file. If the same container port and protocol is specified in both, the -entry from the unit file takes precedence - -This key can be listed multiple times. - -### `SetWorkingDirectory=` - -Set the `WorkingDirectory` field of the `Service` group of the Systemd service unit file. -Used to allow `podman kube play` to correctly resolve relative paths. -Supported values are `yaml` and `unit` to set the working directory to that of the YAML or Quadlet Unit file respectively. - -Alternatively, users can explicitly set the `WorkingDirectory` field of the `Service` group in the `.kube` file. -Please note that if the `WorkingDirectory` field of the `Service` group is set, -Quadlet will not set it even if `SetWorkingDirectory` is set - -### `UserNS=` - -Set the user namespace mode for the container. This is equivalent to the Podman `--userns` option and -generally has the form `MODE[:OPTIONS,...]`. - -### `Yaml=` - -The path, absolute or relative to the location of the unit file, to the Kubernetes YAML file to use. - -## Network units [Network] - -Network files are named with a `.network` extension and contain a section `[Network]` describing the -named Podman network. The generated service is a one-time command that ensures that the network -exists on the host, creating it if needed. - -By default, the Podman network has the same name as the unit, but with a `systemd-` prefix, i.e. for -a network file named `$NAME.network`, the generated Podman network is called `systemd-$NAME`, and -the generated service file is `$NAME-network.service`. The `NetworkName` option allows for -overriding this default name with a user-provided one. - -Please note that stopping the corresponding service will not remove the podman network. -In addition, updating an existing network is not supported. -In order to update the network parameters you will first need to manually remove the podman network and then restart the service. - -Using network units allows containers to depend on networks being automatically pre-created. This is -particularly interesting when using special options to control network creation, as Podman otherwise creates networks with the default options. - -Valid options for `[Network]` are listed below: - -| **[Network] options** | **podman network create equivalent** | -|-------------------------------------|-----------------------------------------------------------------| -| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | -| DisableDNS=true | --disable-dns | -| DNS=192.168.55.1 | --dns=192.168.55.1 | -| Driver=bridge | --driver bridge | -| Gateway=192.168.55.3 | --gateway 192.168.55.3 | -| GlobalArgs=--log-level=debug | --log-level=debug | -| InterfaceName=enp1 | --interface-name enp1 | -| Internal=true | --internal | -| IPAMDriver=dhcp | --ipam-driver dhcp | -| IPRange=192.168.55.128/25 | --ip-range 192.168.55.128/25 | -| IPv6=true | --ipv6 | -| Label="XYZ" | --label "XYZ" | -| NetworkDeleteOnStop=true | Add ExecStopPost to delete the network when the unit is stopped | -| NetworkName=foo | podman network create foo | -| Options=isolate=true | --opt isolate=true | -| PodmanArgs=--dns=192.168.55.1 | --dns=192.168.55.1 | -| Subnet=192.5.0.0/16 | --subnet 192.5.0.0/16 | - -Supported keys in `[Network]` section are: - -### `ContainersConfModule=` - -Load the specified containers.conf(5) module. Equivalent to the Podman `--module` option. - -This key can be listed multiple times. - -### `DisableDNS=` (defaults to `false`) - -If enabled, disables the DNS plugin for this network. - -This is equivalent to the Podman `--disable-dns` option - -### `DNS=` - -Set network-scoped DNS resolver/nameserver for containers in this network. - -This key can be listed multiple times. - -### `Driver=` (defaults to `bridge`) - -Driver to manage the network. Currently `bridge`, `macvlan` and `ipvlan` are supported. - -This is equivalent to the Podman `--driver` option - -### `Gateway=` - -Define a gateway for the subnet. If you want to provide a gateway address, you must also provide a subnet option. - -This is equivalent to the Podman `--gateway` option - -This key can be listed multiple times. - -### `GlobalArgs=` - -This key contains a list of arguments passed directly between `podman` and `network` -in the generated file. It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware -of what unexpected interactions can be caused by these arguments, it is not recommended to use -this option. - -The format of this is a space separated list of arguments, which can optionally be individually -escaped to allow inclusion of whitespace and other control characters. - -This key can be listed multiple times. - -### `InterfaceName=` - -This option maps the *network_interface* option in the network config, see **podman network inspect**. -Depending on the driver, this can have different effects; for `bridge`, it uses the bridge interface name. -For `macvlan` and `ipvlan`, it is the parent device on the host. It is the same as `--opt parent=...`. - -This is equivalent to the Podman `--interface-name` option. - -### `Internal=` (defaults to `false`) - -Restrict external access of this network. - -This is equivalent to the Podman `--internal` option - -### `IPAMDriver=` - -Set the ipam driver (IP Address Management Driver) for the network. Currently `host-local`, `dhcp` and `none` are supported. - -This is equivalent to the Podman `--ipam-driver` option - -### `IPRange=` - -Allocate container IP from a range. The range must be a either a complete subnet in CIDR notation or be -in the `-` syntax which allows for a more flexible range compared to the CIDR subnet. -The ip-range option must be used with a subnet option. - -This is equivalent to the Podman `--ip-range` option - -This key can be listed multiple times. - -### `IPv6=` - -Enable IPv6 (Dual Stack) networking. - -This is equivalent to the Podman `--ipv6` option - -### `Label=` - -Set one or more OCI labels on the network. The format is a list of -`key=value` items, similar to `Environment`. - -This key can be listed multiple times. - -### `NetworkDeleteOnStop=` (defaults to `false`) - -When set to `true` the network is deleted when the service is stopped - -### `NetworkName=` - -The (optional) name of the Podman network. -If this is not specified, the default value is the same name as the unit, but with a `systemd-` prefix, -i.e. a `$name.network` file creates a `systemd-$name` Podman network to avoid -conflicts with user-managed network. - -### `Options=` - -Set driver specific options. - -This is equivalent to the Podman `--opt` option - -### `PodmanArgs=` - -This key contains a list of arguments passed directly to the end of the `podman network create` command -in the generated file (right before the name of the network in the command line). It can be used to -access Podman features otherwise unsupported by the generator. Since the generator is unaware -of what unexpected interactions can be caused by these arguments, is not recommended to use -this option. - -The format of this is a space separated list of arguments, which can optionally be individually -escaped to allow inclusion of whitespace and other control characters. - -This key can be listed multiple times. - -### `Subnet=` - -The subnet in CIDR notation. - -This is equivalent to the Podman `--subnet` option - -This key can be listed multiple times. - -## Volume units [Volume] - -Volume files are named with a `.volume` extension and contain a section `[Volume]` describing the -named Podman volume. The generated service is a one-time command that ensures that the volume -exists on the host, creating it if needed. - -By default, the Podman volume has the same name as the unit, but with a `systemd-` prefix, i.e. for -a volume file named `$NAME.volume`, the generated Podman volume is called `systemd-$NAME`, and the -generated service file is `$NAME-volume.service`. The `VolumeName` option allows for overriding this -default name with a user-provided one. - -Using volume units allows containers to depend on volumes being automatically pre-created. This is -particularly interesting when using special options to control volume creation, -as Podman otherwise creates volumes with the default options. - -Valid options for `[Volume]` are listed below: - -| **[Volume] options** | **podman volume create equivalent** | -|-------------------------------------|-------------------------------------------| -| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | -| Copy=true | --opt copy | -| Device=tmpfs | --opt device=tmpfs | -| Driver=image | --driver=image | -| GlobalArgs=--log-level=debug | --log-level=debug | -| Group=192 | --opt group=192 | -| Image=quay.io/centos/centos\:latest | --opt image=quay.io/centos/centos\:latest | -| Label="foo=bar" | --label "foo=bar" | -| Options=XYZ | --opt "o=XYZ" | -| PodmanArgs=--driver=image | --driver=image | -| Type=type | Filesystem type of Device | -| User=123 | --opt uid=123 | -| VolumeName=foo | podman volume create foo | - -Supported keys in `[Volume]` section are: - -### `ContainersConfModule=` - -Load the specified containers.conf(5) module. Equivalent to the Podman `--module` option. - -This key can be listed multiple times. - -### `Copy=` (default to `true`) - -If enabled, the content of the image located at the mountpoint of the volume is copied into the -volume on the first run. - -### `Device=` - -The path of a device which is mounted for the volume. - -### `Driver=` - -Specify the volume driver name. When set to `image`, the `Image` key must also be set. - -This is equivalent to the Podman `--driver` option. - -### `GlobalArgs=` - -This key contains a list of arguments passed directly between `podman` and `volume` -in the generated file. It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware -of what unexpected interactions can be caused by these arguments, it is not recommended to use -this option. - -The format of this is a space separated list of arguments, which can optionally be individually -escaped to allow inclusion of whitespace and other control characters. - -This key can be listed multiple times. - -### `Group=` - -The host (numeric) GID, or group name to use as the group for the volume - -### `Image=` - -Specifies the image the volume is based on when `Driver` is set to the `image`. -It is recommended to use a fully qualified image name rather than a short name, both for -performance and robustness reasons. - -The format of the name is the same as when passed to `podman pull`. So, it supports using -`:tag` or digests to guarantee the specific image version. - -Special case: - -* If the `name` of the image ends with `.image`, Quadlet will use the image -pulled by the corresponding `.image` file, and the generated systemd service contains a dependency on the `$name-image.service` (or the service name set in the .image file). Note: the corresponding `.image` file must exist. - -### `Label=` - -Set one or more OCI labels on the volume. The format is a list of -`key=value` items, similar to `Environment`. - -This key can be listed multiple times. - -### `Options=` - -The mount options to use for a filesystem as used by the **mount(8)** command `-o` option. - -### `PodmanArgs=` - -This key contains a list of arguments passed directly to the end of the `podman volume create` command -in the generated file (right before the name of the volume in the command line). It can be used to -access Podman features otherwise unsupported by the generator. Since the generator is unaware -of what unexpected interactions can be caused by these arguments, is not recommended to use -this option. - -The format of this is a space separated list of arguments, which can optionally be individually -escaped to allow inclusion of whitespace and other control characters. - -This key can be listed multiple times. - -### `Type=` - -The filesystem type of `Device` as used by the **mount(8)** commands `-t` option. - -### `User=` - -The host (numeric) UID, or user name to use as the owner for the volume - -### `VolumeName=` - -The (optional) name of the Podman volume. -If this is not specified, the default value is the same name as the unit, but with a `systemd-` prefix, -i.e. a `$name.volume` file creates a `systemd-$name` Podman volume to avoid -conflicts with user-managed volumes. - -## Build units [Build] - -Build files are named with a `.build` extension and contain a section `[Build]` describing the image -build command. The generated service is a one-time command that ensures that the image is built on -the host from a supplied Containerfile and context directory. Subsequent (re-)starts of the -generated built service will usually finish quickly, as image layer caching will skip unchanged -build steps. - -A minimal `.build` unit needs at least the `ImageTag=` key, and either of `File=` or -`SetWorkingDirectory=` keys. - -Using build units allows containers and volumes to depend on images being built locally. This can be -interesting for creating container images not available on container registries, or for local -testing and development. - -Valid options for `[Build]` are listed below: - -| **[Build] options** | **podman build equivalent** | -|-------------------------------------|---------------------------------------------| -| Annotation=annotation=value | --annotation=annotation=value | -| Arch=aarch64 | --arch=aarch64 | -| AuthFile=/etc/registry/auth\.json | --authfile=/etc/registry/auth\.json | -| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | -| DNS=192.168.55.1 | --dns=192.168.55.1 | -| DNSOption=ndots:1 | --dns-option=ndots:1 | -| DNSSearch=example.com | --dns-search example.com | -| Environment=foo=bar | --env foo=bar | -| File=/path/to/Containerfile | --file=/path/to/Containerfile | -| ForceRM=false | --force-rm=false | -| GlobalArgs=--log-level=debug | --log-level=debug | -| GroupAdd=keep-groups | --group-add=keep-groups | -| ImageTag=localhost/imagename | --tag=localhost/imagename | -| Label=label | --label=label | -| Network=host | --network=host | -| PodmanArgs=--pull never | --pull never | -| Pull=never | --pull never | -| Retry=5 | --retry=5 | -| RetryDelay=10s | --retry-delay=10s | -| Secret=secret | --secret=id=mysecret,src=path | -| SetWorkingDirectory=unit | Set `WorkingDirectory` of systemd unit file | -| Target=my-app | --target=my-app | -| TLSVerify=false | --tls-verify=false | -| Variant=arm/v7 | --variant=arm/v7 | -| Volume=/source:/dest | --volume /source:/dest | - -### `Annotation=` - -Add an image *annotation* (e.g. annotation=*value*) to the image metadata. Can be used multiple -times. - -This is equivalent to the `--annotation` option of `podman build`. - -### `Arch=` - -Override the architecture, defaults to hosts', of the image to be built. - -This is equivalent to the `--arch` option of `podman build`. - -### `AuthFile=` - -Path of the authentication file. - -This is equivalent to the `--authfile` option of `podman build`. - -### `ContainersConfModule=` - -Load the specified containers.conf(5) module. Equivalent to the Podman `--module` option. - -This key can be listed multiple times. - -### `DNS=` - -Set network-scoped DNS resolver/nameserver for the build container. - -This key can be listed multiple times. - -This is equivalent to the `--dns` option of `podman build`. - -### `DNSOption=` - -Set custom DNS options. - -This key can be listed multiple times. - -This is equivalent to the `--dns-option` option of `podman build`. - -### `DNSSearch=` - -Set custom DNS search domains. Use **DNSSearch=.** to remove the search domain. - -This key can be listed multiple times. - -This is equivalent to the `--dns-search` option of `podman build`. - -### `Environment=` - -Add a value (e.g. env=*value*) to the built image. This uses the same format as [services in -systemd](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Environment=) and can be -listed multiple times. - -### `File=` - -Specifies a Containerfile which contains instructions for building the image. A URL starting with -`http(s)://` allows you to specify a remote Containerfile to be downloaded. Note that for a given -relative path to a Containerfile, or when using a `http(s)://` URL, you also must set -`SetWorkingDirectory=` in order for `podman build` to find a valid context directory for the -resources specified in the Containerfile. - -Note that setting a `File=` field is mandatory for a `.build` file, unless `SetWorkingDirectory` (or -a `WorkingDirectory` in the `Service` group) has also been set. - -This is equivalent to the `--file` option of `podman build`. - -### `ForceRM=` - -Always remove intermediate containers after a build, even if the build fails (default true). - -This is equivalent to the `--force-rm` option of `podman build`. - -### `GlobalArgs=` - -This key contains a list of arguments passed directly between `podman` and `build` in the generated -file. It can be used to access Podman features otherwise unsupported by the generator. Since the -generator is unaware of what unexpected interactions can be caused by these arguments, it is not -recommended to use this option. - -The format of this is a space separated list of arguments, which can optionally be individually -escaped to allow inclusion of whitespace and other control characters. - -This key can be listed multiple times. - -### `GroupAdd=` - -Assign additional groups to the primary user running within the container process. Also supports the -`keep-groups` special flag. - -This is equivalent to the `--group-add` option of `podman build`. - -### `ImageTag=` - -Specifies the name which is assigned to the resulting image if the build process completes -successfully. - -This is equivalent to the `--tag` option of `podman build`. - -This key can be listed multiple times. The first instance will be used as the name of the created artifact when the `.build` file is referenced by another Quadlet unit. - -### `Label=` - -Add an image *label* (e.g. label=*value*) to the image metadata. Can be used multiple times. - -This is equivalent to the `--label` option of `podman build`. - -### `Network=` - -Sets the configuration for network namespaces when handling RUN instructions. This has the same -format as the `--network` option to `podman build`. For example, use `host` to use the host network, -or `none` to not set up networking. - -Special case: - -* If the `name` of the network ends with `.network`, Quadlet will look for the corresponding `.network` Quadlet unit. If found, Quadlet will use the name of the Network set in the Unit, otherwise, `systemd-$name` is used. The generated systemd service contains a dependency on the service unit generated for that `.network` unit, or on `$name-network.service` if the `.network` unit is not found. Note: the corresponding `.network` file must exist. - -This key can be listed multiple times. - -### `PodmanArgs=` - -This key contains a list of arguments passed directly to the end of the `podman build` command -in the generated file (right before the image name in the command line). It can be used to -access Podman features otherwise unsupported by the generator. Since the generator is unaware -of what unexpected interactions can be caused by these arguments, it is not recommended to use -this option. - -The format of this is a space separated list of arguments, which can optionally be individually -escaped to allow inclusion of whitespace and other control characters. - -This key can be listed multiple times. - -### `Pull=` - -Set the image pull policy. - -This is equivalent to the `--pull` option of `podman build`. - -### `Retry=` - -Number of times to retry the image pull when a HTTP error occurs. Equivalent to the Podman `--retry` option. - -### `RetryDelay=` - -Delay between retries. Equivalent to the Podman `--retry-delay` option. - -### `Secret=` - -Pass secret information used in Containerfile build stages in a safe way. - -This is equivalent to the `--secret` option of `podman build` and generally has the form -`secret[,opt=opt ...]`. - -### `SetWorkingDirectory=` - -Provide context (a working directory) to `podman build`. Supported values are a path, a URL, or the -special keys `file` or `unit` to set the context directory to the parent directory of the file from -the `File=` key or to that of the Quadlet `.build` unit file, respectively. This allows Quadlet to -resolve relative paths. - -When using one of the special keys (`file` or `unit`), the `WorkingDirectory` field of the `Service` -group of the Systemd service unit will also be set to accordingly. Alternatively, users can -explicitly set the `WorkingDirectory` field of the `Service` group in the `.build` file. Please note -that if the `WorkingDirectory` field of the `Service` group is set by the user, Quadlet will not -overwrite it even if `SetWorkingDirectory` is set to `file` or `unit`. - -By providing a URL to `SetWorkingDirectory=` you can instruct `podman build` to clone a Git -repository or download an archive file extracted to a temporary location by `podman build` as build -context. Note that in this case, the `WorkingDirectory` of the Systemd service unit is left -untouched by Quadlet. - -Note that providing context directory is mandatory for a `.build` file, unless a `File=` key has -also been provided. - -### `Target=` - -Set the target build stage to build. Commands in the Containerfile after the target stage are -skipped. - -This is equivalent to the `--target` option of `podman build`. - -### `TLSVerify=` - -Require HTTPS and verification of certificates when contacting registries. - -This is equivalent to the `--tls-verify` option of `podman build`. - -### `Variant=` - -Override the default architecture variant of the container image to be built. - -This is equivalent to the `--variant` option of `podman build`. - -### `Volume=` - -Mount a volume to containers when executing RUN instructions during the build. This is equivalent to -the `--volume` option of `podman build`, and generally has the form -`[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]`. - -If `SOURCE-VOLUME` starts with `.`, Quadlet resolves the path relative to the location of the unit file. - -Special case: - -* If `SOURCE-VOLUME` ends with `.volume`, Quadlet will look for the corresponding `.volume` Quadlet unit. If found, Quadlet will use the name of the Volume set in the Unit, otherwise, `systemd-$name` is used. The generated systemd service contains a dependency on the service unit generated for that `.volume` unit, or on `$name-volume.service` if the `.volume` unit is not found. Note: the corresponding `.volume` file must exist. - -This key can be listed multiple times. - -## Image units [Image] - -Image files are named with a `.image` extension and contain a section `[Image]` describing the -container image pull command. The generated service is a one-time command that ensures that the image -exists on the host, pulling it if needed. - -Using image units allows containers and volumes to depend on images being automatically pulled. This is -particularly interesting when using special options to control image pulls. - -Valid options for `[Image]` are listed below: - -| **[Image] options** | **podman image pull equivalent** | -|----------------------------------------|--------------------------------------------------| -| AllTags=true | --all-tags | -| Arch=aarch64 | --arch=aarch64 | -| AuthFile=/etc/registry/auth\.json | --authfile=/etc/registry/auth\.json | -| CertDir=/etc/registry/certs | --cert-dir=/etc/registry/certs | -| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | -| Creds=myname\:mypassword | --creds=myname\:mypassword | -| DecryptionKey=/etc/registry\.key | --decryption-key=/etc/registry\.key | -| GlobalArgs=--log-level=debug | --log-level=debug | -| Image=quay\.io/centos/centos:latest | podman image pull quay.io/centos/centos\:latest | -| ImageTag=quay\.io/centos/centos:latest | Use this name when resolving `.image` references | -| OS=windows | --os=windows | -| PodmanArgs=--os=linux | --os=linux | -| Policy=always | --policy=always | -| Retry=5 | --retry=5 | -| RetryDelay=10s | --retry-delay=10s | -| TLSVerify=false | --tls-verify=false | -| Variant=arm/v7 | --variant=arm/v7 | - -### `AllTags=` - -All tagged images in the repository are pulled. - -This is equivalent to the Podman `--all-tags` option. - -### `Arch=` - -Override the architecture, defaults to hosts, of the image to be pulled. - -This is equivalent to the Podman `--arch` option. - -### `AuthFile=` - -Path of the authentication file. - -This is equivalent to the Podman `--authfile` option. - -### `CertDir=` - -Use certificates at path (*.crt, *.cert, *.key) to connect to the registry. - -This is equivalent to the Podman `--cert-dir` option. - -### `ContainersConfModule=` - -Load the specified containers.conf(5) module. Equivalent to the Podman `--module` option. - -This key can be listed multiple times. - -### `Creds=` - -The `[username[:password]]` to use to authenticate with the registry, if required. - -This is equivalent to the Podman `--creds` option. - -### `DecryptionKey=` - -The `[key[:passphrase]]` to be used for decryption of images. - -This is equivalent to the Podman `--decryption-key` option. - -### `GlobalArgs=` - -This key contains a list of arguments passed directly between `podman` and `image` -in the generated file. It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware -of what unexpected interactions can be caused by these arguments, it is not recommended to use -this option. - -The format of this is a space separated list of arguments, which can optionally be individually -escaped to allow inclusion of whitespace and other control characters. - -This key can be listed multiple times. - -### `Image=` - -The image to pull. -It is recommended to use a fully qualified image name rather than a short name, both for -performance and robustness reasons. - -The format of the name is the same as when passed to `podman pull`. So, it supports using -`:tag` or digests to guarantee the specific image version. - -### `ImageTag=` - -Actual FQIN of the referenced `Image`. -Only meaningful when source is a file or directory archive. - -For example, an image saved into a `docker-archive` with the following Podman command: - -`podman image save --format docker-archive --output /tmp/archive-file.tar quay.io/podman/stable:latest` - -requires setting -- `Image=docker-archive:/tmp/archive-file.tar` -- `ImageTag=quay.io/podman/stable:latest` - -### `OS=` - -Override the OS, defaults to hosts, of the image to be pulled. - -This is equivalent to the Podman `--os` option. - -### `PodmanArgs=` - -This key contains a list of arguments passed directly to the end of the `podman image pull` command -in the generated file (right before the image name in the command line). It can be used to -access Podman features otherwise unsupported by the generator. Since the generator is unaware -of what unexpected interactions can be caused by these arguments, it is not recommended to use -this option. - -The format of this is a space separated list of arguments, which can optionally be individually -escaped to allow inclusion of whitespace and other control characters. - -This key can be listed multiple times. - -### `Policy=` - -The pull policy to use when pulling the image. - -This is equivalent to the Podman `--policy` option. - -### `Retry=` - -Number of times to retry the image pull when a HTTP error occurs. Equivalent to the Podman `--retry` option. - -### `RetryDelay=` - -Delay between retries. Equivalent to the Podman `--retry-delay` option. - -### `TLSVerify=` - -Require HTTPS and verification of certificates when contacting registries. - -This is equivalent to the Podman `--tls-verify` option. - -### `Variant=` - -Override the default architecture variant of the container image. - -This is equivalent to the Podman `--variant` option. - -## Quadlet section [Quadlet] -Some quadlet specific configuration is shared between different unit types. Those settings -can be configured in the `[Quadlet]` section. - -Valid options for `[Quadlet]` are listed below: - -| **[Quadlet] options** | **Description** | -|----------------------------|---------------------------------------------------| -| DefaultDependencies=false | Disable implicit network dependencies to the unit | - -### `DefaultDependencies=` - -Add Quadlet's default network dependencies to the unit (default is `true`). - -When set to false, Quadlet will **not** add a dependency (After=, Wants=) to -`network-online.target`/`podman-user-wait-network-online.service` to the generated unit. - -Note, this option is set in the `[Quadlet]` section. The _systemd_ `[Unit]` section -has an option with the same name but a different meaning. - -## EXAMPLES - -Example `test.container`: - -``` -[Unit] -Description=A minimal container - -[Container] -# Use the centos image -Image=quay.io/centos/centos:latest - -# Use volume and network defined below -Volume=test.volume:/data -Network=test.network - -# In the container we just run sleep -Exec=sleep 60 - -[Service] -# Restart service when sleep finishes -Restart=always -# Extend Timeout to allow time to pull the image -TimeoutStartSec=900 -# ExecStartPre flag and other systemd commands can go here, see systemd.unit(5) man page. -ExecStartPre=/usr/share/mincontainer/setup.sh - -[Install] -# Start by default on boot -WantedBy=multi-user.target default.target -``` - -Example `test.kube`: -``` -[Unit] -Description=A kubernetes yaml based service -Before=local-fs.target - -[Kube] -Yaml=/opt/k8s/deployment.yml - -[Install] -# Start by default on boot -WantedBy=multi-user.target default.target -``` - -Example for locally built image to be used in a container: - -`test.build` -``` -[Build] -# Tag the image to be built -ImageTag=localhost/imagename - -# Set the working directory to the path of the unit file, -# expecting to find a Containerfile/Dockerfile -# + other files needed to build the image -SetWorkingDirectory=unit -``` - -`test.container` -``` -[Container] -Image=test.build -``` - -Example `test.volume`: - -``` -[Volume] -User=root -Group=root -Label=org.test.Key=value -``` - -Example `test.network`: -``` -[Network] -Subnet=172.16.0.0/24 -Gateway=172.16.0.1 -IPRange=172.16.0.0/28 -Label=org.test.Key=value -``` - -Example for Container in a Pod: - -`test.pod` -``` -[Pod] -PodName=test -``` - -`centos.container` -``` -[Container] -Image=quay.io/centos/centos:latest -Exec=sh -c "sleep inf" -Pod=test.pod -``` - -Example for a Pod with a oneshot Startup Task: - -`test.pod` -``` -[Pod] -PodName=test -ExitPolicy=continue -``` - -`startup-task.container` -``` -[Service] -Type=oneshot -RemainAfterExit=yes - -[Container] -Pod=test.pod -Image=quay.io/centos/centos:latest -Exec=sh -c "echo 'setup starting'; sleep 2; echo 'setup complete'" -``` - -`app.container` -``` -[Unit] -Requires=startup-task.container -After=startup-task.container - -[Container] -Pod=test.pod -Image=quay.io/centos/centos:latest -Exec=sh -c "echo 'app running.'; sleep 30" -``` - -Example `s3fs.volume`: - -For further details, please see the [s3fs-fuse](https://github.com/s3fs-fuse/s3fs-fuse) project. -Remember to read the [FAQ](https://github.com/s3fs-fuse/s3fs-fuse/wiki/FAQ) - -> NOTE: Enabling the cache massively speeds up access and write times on static files/objects. - -> However, `use_cache` is [UNBOUNDED](https://github.com/s3fs-fuse/s3fs-fuse/wiki/FAQ#q-how-does-the-local-file-cache-work)! - -> Be careful, it will fill up with any files accessed on the s3 bucket through the file system. - -Please remember to set `S3_BUCKET`, `PATH`, `AWS_REGION`. `CACHE_DIRECTORY` should be set up by [systemd](https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#RuntimeDirectory=) - -``` -[Service] -CacheDirectory=s3fs -ExecStartPre=/usr/local/bin/aws s3api put-object --bucket ${S3_BUCKET} --key ${PATH}/ - -[Volume] -Device=${S3_BUCKET}:/${PATH} -Type=fuse.s3fs -VolumeName=s3fs-volume -Options=iam_role,endpoint=${AWS_REGION},use_xattr,listobjectsv2,del_cache,use_cache=${CACHE_DIRECTORY} -# `iam_role` assumes inside EC2, if not, Use `profile=` instead -``` +For more examples, please see the [podman-quadlet-basic-usage.7](podman-quadlet-basic-usage.7.md). ## SEE ALSO -**[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)**, -**[systemd.service(5)](https://www.freedesktop.org/software/systemd/man/systemd.service.html)**, -**[systemd-analyze(1)](https://www.freedesktop.org/software/systemd/man/latest/systemd-analyze.html)**, -**[podman-run(1)](podman-run.1.md)**, -**[podman-network-create(1)](podman-network-create.1.md)**, -**[podman-auto-update(1)](podman-auto-update.1.md)** +-**[podman-auto-update(1)](podman-auto-update.1.md)** +-**[podman-build.unit(5)](podman-build.unit.5.md),** +-**[podman-container.unit(5)](podman-container.unit.5.md),** +-**[podman-image.unit(5)](podman-image.unit.5.md),** +-**[podman-kube.unit(5)](podman-kube.unit.5.md),** +-**[podman-network-create(1)](podman-network-create.1.md)**, +-**[podman-network.unit(5)](podman-network.unit.5.md),** +-**[podman-pod.unit(5)](podman-pod.unit.5.md),** +-**[podman-quadlet-basic-usage.7](podman-quadlet-basic-usage.7.md),** +-**[podman-run(1)](podman-run.1.md)**, +-**[podman-volume.unit(5)](podman-volume.unit.5.md),** +-**[systemd-analyze(1)](https://www.freedesktop.org/software/systemd/man/latest/systemd-analyze.html)**, +-**[systemd.service(5)](https://www.freedesktop.org/software/systemd/man/systemd.service.html)**, +-**[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)** diff --git a/docs/source/markdown/podman-volume.unit.5.md.in b/docs/source/markdown/podman-volume.unit.5.md.in new file mode 100644 index 0000000000..4bfeabe82a --- /dev/null +++ b/docs/source/markdown/podman-volume.unit.5.md.in @@ -0,0 +1,145 @@ +% podman-volume.unit(5) + +# NAME + +podman\-volume.unit - systemd unit files for managing container volumes using Podman Quadlet + +# SYNOPSIS + +*name*.container + +# DESCRIPTION + +Volume files are named with a `.volume` extension and contain a section `[Volume]` describing the +named Podman volume. The generated service is a one-time command that ensures that the volume +exists on the host, creating it if needed. + +By default, the Podman volume has the same name as the unit, but with a `systemd-` prefix, i.e. for +a volume file named `$NAME.volume`, the generated Podman volume is called `systemd-$NAME`, and the +generated service file is `$NAME-volume.service`. The `VolumeName` option allows for overriding this +default name with a user-provided one. + +Using volume units allows containers to depend on volumes being automatically pre-created. This is +particularly interesting when using special options to control volume creation, +as Podman otherwise creates volumes with the default options. + +# USAGE SUMMARY + +The `.container` file is parsed by the `podman-system-generator` at boot or reload, generating a systemd +`.service` that runs `podman volume create`. + +# OPTIONS + +Valid options for `[Volume]` are listed below: + +| **[Volume] options** | **podman volume create equivalent** | +|-------------------------------------|-------------------------------------------| +| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf | +| Copy=true | --opt copy | +| Device=tmpfs | --opt device=tmpfs | +| Driver=image | --driver=image | +| GlobalArgs=--log-level=debug | --log-level=debug | +| Group=192 | --opt group=192 | +| Image=quay.io/centos/centos\:latest | --opt image=quay.io/centos/centos\:latest | +| Label="foo=bar" | --label "foo=bar" | +| Options=XYZ | --opt "o=XYZ" | +| PodmanArgs=--driver=image | --driver=image | +| Type=type | Filesystem type of Device | +| User=123 | --opt uid=123 | +| VolumeName=foo | podman volume create foo | + +Supported keys in `[Volume]` section are: + +@@option quadlet:module + +### `Copy=` (default to `true`) + +If enabled, the content of the image located at the mountpoint of the volume is copied into the +volume on the first run. + +### `Device=` + +The path of a device which is mounted for the volume. + +### `Driver=` + +Specify the volume driver name. When set to `image`, the `Image` key must also be set. + +This is equivalent to the Podman `--driver` option. + +@@option quadlet:global-args + + +### `Group=` + +The host (numeric) GID, or group name to use as the group for the volume + +### `Image=` + +Specifies the image the volume is based on when `Driver` is set to the `image`. +It is recommended to use a fully qualified image name rather than a short name, both for +performance and robustness reasons. + +The format of the name is the same as when passed to `podman pull`. So, it supports using +`:tag` or digests to guarantee the specific image version. + +Special case: + +* If the `name` of the image ends with `.image`, Quadlet will use the image +pulled by the corresponding `.image` file, and the generated systemd service contains a dependency on the `$name-image.service` (or the service name set in the .image file). Note: the corresponding `.image` file must exist. + +### `Label=` + +Set one or more OCI labels on the volume. The format is a list of +`key=value` items, similar to `Environment`. + +This key can be listed multiple times. + +### `Options=` + +The mount options to use for a filesystem as used by the **mount(8)** command `-o` option. + +@@option quadlet:podman-args + +### `Type=` + +The filesystem type of `Device` as used by the **mount(8)** commands `-t` option. + +### `User=` + +The host (numeric) UID, or user name to use as the owner for the volume + +### `VolumeName=` + +The (optional) name of the Podman volume. +If this is not specified, the default value is the same name as the unit, but with a `systemd-` prefix, +i.e. a `$name.volume` file creates a `systemd-$name` Podman volume to avoid +conflicts with user-managed volumes. + +# EXAMPLE + +Minimal volume unit: + +``` +[Volume] +VolumeName=mydata +Label=app=data +User=1000 +Group=1000 +``` + +Volume unit backed by an image: + +``` +[Volume] +VolumeName=html +Driver=image +Image=quay.io/centos/centos:latest +Copy=true +``` + +# SEE ALSO + +[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html), +[podman-systemd.unit(5)](podman-systemd.unit.5.md), +[podman-volume-create(1)](podman-volume-create.1.md) diff --git a/hack/markdown-preprocess b/hack/markdown-preprocess index 11fa1ea9e1..a82029f534 100755 --- a/hack/markdown-preprocess +++ b/hack/markdown-preprocess @@ -23,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 @@ -40,18 +134,24 @@ class Preprocessor(): with open(infile, 'r', encoding='utf-8') as fh_in, open(outfile_tmp, 'w', encoding='utf-8', newline='\n') as fh_out: for line in fh_in: - # '@@option foo' -> include file options/foo.md - if line.startswith('@@option '): - _, optionname = line.strip().split(" ") - optionfile = os.path.join("options", optionname + '.md') - self.track_optionfile(optionfile) - self.insert_file(fh_out, optionfile) - # '@@include relative-path/must-exist.md' - elif line.startswith('@@include '): - _, path = line.strip().split(" ") - self.insert_file(fh_out, path) - else: - fh_out.write(line) + try: + # '@@option foo' -> include file options/foo.md + if line.startswith('@@option '): + _, optionname = line.strip().split(" ") + is_quadlet = optionname.startswith("quadlet:") + if is_quadlet: + optionname = optionname[len("quadlet:"):] + optionfile = os.path.join("options", optionname + '.md') + self.track_optionfile(optionfile) + self.insert_file(fh_out, optionfile, is_quadlet) + # '@@include relative-path/must-exist.md' + elif line.startswith('@@include '): + _, path = line.strip().split(" ") + self.insert_file(fh_out, path) + else: + fh_out.write(line) + except Exception as ex: + raise Exception(f"Error while processing {infile} line '{line[:-1]}'") from ex os.chmod(outfile_tmp, 0o444) os.rename(outfile_tmp, outfile) @@ -87,7 +187,7 @@ class Preprocessor(): else: os.unlink(tmpfile) - def insert_file(self, fh_out, path: str): + def insert_file(self, fh_out, path: str, is_quadlet=False): """ Reads one option file, writes it out to the given output filehandle """ @@ -98,13 +198,15 @@ class Preprocessor(): # comment in its output. fh_out.write("\n[//]: # (BEGIN included file " + path + ")\n") with open(path, 'r', encoding='utf-8') as fh_included: - for opt_line in fh_included: + rendered = self.render(fh_included.read(), {"is_quadlet": is_quadlet}) + for opt_line in rendered.splitlines(): if opt_line.startswith('####>'): continue + opt_line = self.replace_type(opt_line) opt_line = opt_line.replace('<>', self.podman_subcommand()) opt_line = opt_line.replace('<>', self.podman_subcommand('full')) - fh_out.write(opt_line) + fh_out.write(opt_line + '\n') fh_out.write("\n[//]: # (END included file " + path + ")\n") def podman_subcommand(self, full=None) -> str: @@ -117,6 +219,9 @@ class Preprocessor(): if not full: if subcommand.startswith("podman-pod-"): subcommand = subcommand[len("podman-pod-"):] + # For quadlet man-pages, the subcommand is simply the full manpage name. + if subcommand.endswith(".unit.5.md.in"): + return subcommand if subcommand.startswith("podman-"): subcommand = subcommand[len("podman-"):] if subcommand.endswith(".1.md.in"): diff --git a/hack/xref-quadlet-docs b/hack/xref-quadlet-docs index 022f2c4898..7878a47ead 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-systemd.unit.5.md", + "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", +); # 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]+)=/) { - my $key = $1; + 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"; + 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"; + # 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"; + push @found_in_table, $key; + $documented{$key}++; + } + else { + warn "$ME: $path:$.: cannot grok table line '$line'\n"; + } } - } - # Description block - elsif ($line =~ /^###\s+`(\S+)=`/) { - my $key = $1; + # Description block + elsif ($line =~ /^###\s+`([A-Z][A-Za-z6]+)=.*`/) { + 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"; + $read_first_table = 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"; + 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}++; + 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"; } }