opensource/podman
1
0
Fork 0
mirror of https://github.com/containers/podman.git synced 2025-10-16 10:43:52 +08:00
Code Issues Packages Projects Releases Wiki Activity

Rewrite the Quadlet documentation.

Browse Source 
This commit does the following:

- Splits the podman-systemd.unit.5.md into multiple files - one for each
  quadlet file type, podman-quadlet.7.md for general quadlet information
  and podman-quadlet-basic-usage.7.md for quadlet examples.
- Removes the original podman-systemd.unit.5.md file.
- Adds support for jinja2 templating language in the markdown_preprocess.
- Uses jinja2 in options/*.md to use the single .md file for both podman
  subcommands man-pages and quadlet man-pages. This deduplicates
  the Quadlet man-pages a lot.
- Adds new `@@option quadlet:source.md` preprocess command to import
  such .md files from options directory.

Signed-off-by: Jan Kaluza <jkaluza@redhat.com>
This commit is contained in:
Jan Kaluza
2025-08-19 12:52:17 +02:00
parent fcdb6b59d9
commit c12b1b32bc
109 changed files with 2738 additions and 2447 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/source/markdown/.gitignore vendored
View File

@ -69,3 +69,11 @@ podman-unpause.1.md
podman-update.1.md
podman-volume-ls.1.md
podman-wait.1.md
podman-build.unit.5.md
podman-container.unit.5.md
podman-image.unit.5.md
podman-kube.unit.5.md
podman-network.unit.5.md
podman-pod.unit.5.md
podman-volume.unit.5.md

2
docs/source/markdown/links/quadlet.5
View File

@ -1 +1 @@
.so man5/podman-systemd.unit.5
.so man7/podman-quadlet.7

33
docs/source/markdown/options/README.md
View File

@ -17,6 +17,8 @@ mechanism:
```
@@option foo ! includes options/foo.md
@@option quadlet:foo ! includes options/foo.md with `is_quadlet=True`
! See "Jinja2 Templating" below.
```
The tool that does this is `hack/markdown-preprocess`. It is a python
@ -25,6 +27,37 @@ file, this script creates a `.md` file that can then be read by
`go-md2man`, `sphinx`, anything that groks markdown. This runs as
part of `make docs`.
Jinja2 Templating
=================
Some options are used as both Podman command line option and Quadlet
option. To reduce the duplication, the Jinja2 templating system can be
used to define parts which should be rendered only in Quadlet man-pages:
```
{% if is_quadlet %}
### `DNS=`
{% else %}
#### **--dns**=*ipaddr*
{% endif %}
```
It is also possible to use in-line condition:
```
{{{ '**DNS=.**' if is_quadlet else '**--dns**' }}}
```
Following variables are available for Jinja2 Templates:
- `is_quadlet`: True if file is imported using `@@option quadlet:foo`.
- `subcommand`: Same as `<<subcommand>>`, see below.
This allows the shared use of examples in the option file:
- `fullcommand`: Same as `<<fullsubcommand>>`, see below.
For more information about Jinja2, check
https://jinja.palletsprojects.com/en/stable/.
Special Substitutions
=====================

6
docs/source/markdown/options/add-host.md
View File

@ -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 <<container|pod>>'s `/etc/hosts` file.

6
docs/source/markdown/options/annotation.container.md
View File

@ -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.

4
docs/source/markdown/options/annotation.image.md
View File

@ -2,7 +2,11 @@
####> podman build, farm build
####> If file is edited, make sure the changes
####> are applicable to all of those.
{% if is_quadlet %}
### `Annotation=annotation=value`
{% else %}
#### **--annotation**=*annotation=value*
{% endif %}
Add an image *annotation* (e.g. annotation=*value*) to the image metadata. Can
be used multiple times.

7
docs/source/markdown/options/arch.md
View File

@ -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.

6
docs/source/markdown/options/authfile.md
View File

@ -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**.

5
docs/source/markdown/options/cap-add.image.md
View File

@ -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.

6
docs/source/markdown/options/cap-add.md
View File

@ -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.

10
docs/source/markdown/options/cap-drop.md
View File

@ -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.

6
docs/source/markdown/options/cert-dir.md
View File

@ -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)**.

14
docs/source/markdown/options/cgroups.md
View File

@ -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**).

6
docs/source/markdown/options/creds.md
View File

@ -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

6
docs/source/markdown/options/decryption-key.md
View File

@ -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.

14
docs/source/markdown/options/device.md
View File

@ -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 <<container|pod>>. 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 <<container|pod>>. 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**.

9
docs/source/markdown/options/dns-option.container.md
View File

@ -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_.

6
docs/source/markdown/options/dns-option.image.md
View File

@ -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.

11
docs/source/markdown/options/dns-search.container.md
View File

@ -1,8 +1,13 @@
####> This option file is used in:
####> podman create, run
####> podman podman-container.unit.5.md.in, create, run
####> If file is edited, make sure the changes
####> are applicable to all of those.
{% if is_quadlet %}
### `DNSSearch=domain`
{% else %}
#### **--dns-search**=*domain*
{% endif %}
Set custom DNS search domains. Invalid if using **--dns-search** with **--network** that is set to **none** or **container:**_id_.
Use **--dns-search=.** to remove the search domain.
Set custom DNS search domains. Invalid if using {{{ '**DNSSearch=**' if is_quadlet else '**--dns-search**' }}}
with with {{{ '**Network=**' if is_quadlet else '**--network**' }}} that is set to **none** or **container:**_id_.
Use {{{ '**DNSSearch=.**' if is_quadlet else '**--dns-search=.**' }}} to remove the search domain.

6
docs/source/markdown/options/dns-search.image.md
View File

@ -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.

8
docs/source/markdown/options/dns.md
View File

@ -1,15 +1,19 @@
####> This option file is used in:
####> podman build, create, farm build, run
####> podman build, podman-build.unit.5.md.in, podman-container.unit.5.md.in, create, farm build, podman-network.unit.5.md.in, podman-pod.unit.5.md.in, run
####> If file is edited, make sure the changes
####> are applicable to all of those.
{% if is_quadlet %}
### `DNS=ipaddr`
{% else %}
#### **--dns**=*ipaddr*
{% endif %}
Set custom DNS servers.
This option can be used to override the DNS
configuration passed to the container. Typically this is necessary when the
host DNS configuration is invalid for the container (e.g., **127.0.0.1**). When this
is the case the **--dns** flag is necessary for every run.
is the case the {{{ '**DNS=.**' if is_quadlet else '**--dns**' }}} flag is necessary for every run.
The special value **none** can be specified to disable creation of _/etc/resolv.conf_ in the container by Podman.
The _/etc/resolv.conf_ file in the image is then used without changes.

8
docs/source/markdown/options/entrypoint.md
View File

@ -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.

6
docs/source/markdown/options/env-file.md
View File

@ -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.

6
docs/source/markdown/options/env-host.md
View File

@ -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)

8
docs/source/markdown/options/env.image.md
View File

@ -1,11 +1,17 @@
####> This option file is used in:
####> podman build, farm build
####> podman build, podman-build.unit.5.md.in, farm build
####> If file is edited, make sure the changes
####> are applicable to all of those.
{% if is_quadlet %}
### `Env=env[=value]`
{% else %}
#### **--env**=*env[=value]*
{% endif %}
Add a value (e.g. env=*value*) to the built image. Can be used multiple times.
If neither `=` nor a *value* are specified, but *env* is set in the current
environment, the value from the current environment is added to the image.
{% if not is_quadlet %}
To remove an environment variable from the built image, use the `--unsetenv`
option.
{% endif %}

6
docs/source/markdown/options/env.md
View File

@ -1,8 +1,12 @@
####> This option file is used in:
####> podman create, exec, run
####> podman podman-container.unit.5.md.in, create, exec, run
####> If file is edited, make sure the changes
####> are applicable to all of those.
{% if is_quadlet %}
### `Environment=env`
{% else %}
#### **--env**, **-e**=*env*
{% endif %}
Set environment variables.

10
docs/source/markdown/options/expose.md
View File

@ -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.

19
docs/source/markdown/options/file.md
View File

@ -1,16 +1,31 @@
####> This option file is used in:
####> podman build, farm build
####> podman build, podman-build.unit.5.md.in, farm build
####> If file is edited, make sure the changes
####> are applicable to all of those.
{% if is_quadlet %}
### `File=Containerfile`
{% else %}
#### **--file**, **-f**=*Containerfile*
{% endif %}
Specifies a Containerfile which contains instructions for building the image,
either a local file or an **http** or **https** URL. If more than one
Containerfile is specified, *FROM* instructions are only be accepted from the
last specified file.
{% if is_quadlet %}
Note that for a given relative path to a Containerfile, or when using a `http(s)://` URL, you also must set
`SetWorkingDirectory=` in order for `podman build` to find a valid context directory for the
resources specified in the Containerfile.
Note that setting a `File=` field is mandatory for a `.build` file, unless `SetWorkingDirectory` (or
a `WorkingDirectory` in the `Service` group) has also been set.
{% else %}
If a build context is not specified, and at least one Containerfile is a
local file, the directory in which it resides is used as the build
context.
{% endif %}
Specifying the option `-f -` causes the Containerfile contents to be read from stdin.
Specifying the option {{{ 'File=-' if is_quadlet else '`-f -`' }}} causes
the Containerfile contents to be read from stdin.

6
docs/source/markdown/options/force-rm.md
View File

@ -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).

15
docs/source/markdown/options/gidmap.container.md
View File

@ -1,12 +1,19 @@
####> This option file is used in:
####> podman create, run
####> podman podman-container.unit.5.md.in, create, podman-pod.unit.5.md.in, run
####> If file is edited, make sure the changes
####> are applicable to all of those.
{% if is_quadlet %}
### `GIDMap=[flags]container_uid:from_uid[:amount]`
{% else %}
#### **--gidmap**=*[flags]container_uid:from_uid[:amount]*
{% endif %}
Run the container in a new user namespace using the supplied GID mapping. This
option conflicts with the **--userns** and **--subgidname** options. This
un the container in a new user namespace using the supplied GID mapping. This
option conflicts with the {{{ '**UserNS=**' if is_quadlet else '**--userns**' }}} and
{{{ '**SubGIDMap=**' if is_quadlet else '**--subgidname**' }}} options. This
option provides a way to map host GIDs to container GIDs in the same way as
__--uidmap__ maps host UIDs to container UIDs. For details see __--uidmap__.
Note: the **--gidmap** option cannot be called in conjunction with the **--pod** option as a gidmap cannot be set on the container level when in a pod.
Note: the {{{ '**GIDMap=**' if is_quadlet else '**--gidmap**' }}} option cannot be
called in conjunction with the {{{ '**Pod=**' if is_quadlet else '**--pod**' }}} option as
a gidmap cannot be set on the container level when in a pod.

6
docs/source/markdown/options/group-add.md
View File

@ -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.

6
docs/source/markdown/options/health-cmd.md
View File

@ -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

6
docs/source/markdown/options/health-interval.md
View File

@ -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**.

6
docs/source/markdown/options/health-log-destination.md
View File

@ -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)

6
docs/source/markdown/options/health-max-log-count.md
View File

@ -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)

6
docs/source/markdown/options/health-max-log-size.md
View File

@ -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)

6
docs/source/markdown/options/health-on-failure.md
View File

@ -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**.

6
docs/source/markdown/options/health-retries.md
View File

@ -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**.

15
docs/source/markdown/options/health-start-period.md
View File

@ -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.

9
docs/source/markdown/options/health-startup-cmd.md
View File

@ -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.

6
docs/source/markdown/options/health-startup-interval.md
View File

@ -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**.

6
docs/source/markdown/options/health-startup-retries.md
View File

@ -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**.

6
docs/source/markdown/options/health-startup-success.md
View File

@ -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**.

6
docs/source/markdown/options/health-startup-timeout.md
View File

@ -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**.

6
docs/source/markdown/options/health-timeout.md
View File

@ -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**.

10
docs/source/markdown/options/hostname.container.md
View File

@ -1,13 +1,17 @@
####> This option file is used in:
####> podman create, run
####> podman podman-container.unit.5.md.in, create, run
####> If file is edited, make sure the changes
####> are applicable to all of those.
{% if is_quadlet %}
### `HostName=name`
{% else %}
#### **--hostname**, **-h**=*name*
{% endif %}
Set the container's hostname inside the container.
This option can only be used with a private UTS namespace `--uts=private`
(default). If `--pod` is given and the pod shares the same UTS namespace
(default). If {{{ '`Pod=`' if is_quadlet else '`--pod`' }}} is given and the pod shares the same UTS namespace
(default), the pod's hostname is used. The given hostname is also added to the
`/etc/hosts` file using the container's primary IP address (also see the
**--add-host** option).
{{{ '**AddHost=**' if is_quadlet else '**--add-host**' }}} option).

6
docs/source/markdown/options/init.md
View File

@ -1,8 +1,12 @@
####> This option file is used in:
####> podman create, run
####> podman podman-container.unit.5.md.in, create, run
####> If file is edited, make sure the changes
####> are applicable to all of those.
{% if is_quadlet %}
### `Init=`
{% else %}
#### **--init**
{% endif %}
Run an init inside the container that forwards signals and reaps processes.
The container-init binary is mounted at `/run/podman-init`.

16
docs/source/markdown/options/ip.md
View File

@ -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 <<container|pod>>, for example **10.88.64.128**.
This option can only be used if the <<container|pod>> is joined to only a single network - i.e., **--network=network-name** is used at most once -
and if the <<container|pod>> is not joining another container's network namespace via **--network=container:_id_**.
This option can only be used if the <<container|pod>> 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 <<container|pod>> 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 <<container|pod>>, 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 <<container|pod>>, 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.

16
docs/source/markdown/options/ip6.md
View File

@ -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 <<container|pod>>, for example **fd46:db93:aa76:ac37::10**.
This option can only be used if the <<container|pod>> is joined to only a single network - i.e., **--network=network-name** is used at most once -
and if the <<container|pod>> is not joining another container's network namespace via **--network=container:_id_**.
This option can only be used if the <<container|pod>> 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 <<container|pod>> 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 <<container|pod>>, 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 <<container|pod>>, 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.

6
docs/source/markdown/options/label.image.md
View File

@ -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.

6
docs/source/markdown/options/label.md
View File

@ -1,7 +1,11 @@
####> This option file is used in:
####> podman create, pod clone, pod create, run
####> podman podman-container.unit.5.md.in, create, pod clone, pod create, podman-pod.unit.5.md.in, run
####> If file is edited, make sure the changes
####> are applicable to all of those.
{% if is_quadlet %}
### `Label=key=value`
{% else %}
#### **--label**, **-l**=*key=value*
{% endif %}
Add metadata to a <<container|pod>>.

6
docs/source/markdown/options/log-driver.md
View File

@ -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**).

12
docs/source/markdown/options/log-opt.md
View File

@ -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.

10
docs/source/markdown/options/memory.md
View File

@ -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).

13
docs/source/markdown/options/module.md Normal file
View File

@ -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.

15
docs/source/markdown/options/mount.md
View File

@ -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:

11
docs/source/markdown/options/name.container.md
View File

@ -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).

6
docs/source/markdown/options/network-alias.md
View File

@ -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 <<container|pod>>, 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.

12
docs/source/markdown/options/network.image.md
View File

@ -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.

19
docs/source/markdown/options/network.md
View File

@ -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 <<container|pod>>.
{% 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:

6
docs/source/markdown/options/os.pull.md
View File

@ -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.

6
docs/source/markdown/options/pids-limit.md
View File

@ -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.

6
docs/source/markdown/options/publish.md
View File

@ -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.

4
docs/source/markdown/options/pull.image.md
View File

@ -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**.

6
docs/source/markdown/options/pull.md
View File

@ -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**.

15
docs/source/markdown/options/read-only-tmpfs.md
View File

@ -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.

9
docs/source/markdown/options/read-only.md
View File

@ -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.

2
docs/source/markdown/options/restart.md
View File

@ -19,4 +19,4 @@ Podman provides a systemd unit file, podman-restart.service, which restarts cont
When running containers in systemd services, use the restart functionality provided by systemd.
In other words, do not use this option in a container unit, instead set the `Restart=` systemd directive in the `[Service]` section.
See **podman-systemd.unit**(5) and **systemd.service**(5).
See **podman-quadlet**(7) and **systemd.service**(5).

6
docs/source/markdown/options/retry-delay.md
View File

@ -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.

6
docs/source/markdown/options/retry.md
View File

@ -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**.

10
docs/source/markdown/options/rootfs.md
View File

@ -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.

6
docs/source/markdown/options/secret.image.md
View File

@ -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.

6
docs/source/markdown/options/secret.md
View File

@ -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.

6
docs/source/markdown/options/shm-size.md
View File

@ -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**.

6
docs/source/markdown/options/stop-signal.md
View File

@ -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**.

10
docs/source/markdown/options/stop-timeout.md
View File

@ -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 %}

9
docs/source/markdown/options/subgidname.md
View File

@ -1,9 +1,14 @@
####> This option file is used in:
####> podman create, pod clone, pod create, run
####> podman podman-container.unit.5.md.in, create, pod clone, pod create, podman-pod.unit.5.md.in, run
####> If file is edited, make sure the changes
####> are applicable to all of those.
{% if is_quadlet %}
### `SubGIDMap=name`
{% else %}
#### **--subgidname**=*name*
{% endif %}
Run the container in a new user namespace using the map with _name_ in the _/etc/subgid_ file.
If running rootless, the user needs to have the right to use the mapping. See **subgid**(5).
This flag conflicts with **--userns** and **--gidmap**.
This flag conflicts with {{{ '**UserNS=**' if is_quadlet else '**--userns**' }}} and {{{ '**GIDMap=**' if is_quadlet else '**--gidmap**' }}}.

8
docs/source/markdown/options/subuidname.md
View File

@ -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**' }}}.

6
docs/source/markdown/options/sysctl.md
View File

@ -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 <<at runtime|for all containers in the pod>>.

6
docs/source/markdown/options/tag.md
View File

@ -1,8 +1,12 @@
####> This option file is used in:
####> podman build, farm build
####> podman build, podman-build.unit.5.md.in, farm build
####> If file is edited, make sure the changes
####> are applicable to all of those.
{% if is_quadlet %}
### `TaImageTag=imageName`
{% else %}
#### **--tag**, **-t**=*imageName*
{% endif %}
Specifies the name which is assigned to the resulting image if the build process completes successfully.
If _imageName_ does not include a registry name, the registry name *localhost* is prepended to the image name.

6
docs/source/markdown/options/target.md
View File

@ -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.

6
docs/source/markdown/options/tls-verify.md
View File

@ -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.

6
docs/source/markdown/options/tmpfs.md
View File

@ -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.

6
docs/source/markdown/options/tz.md
View File

@ -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

32
docs/source/markdown/options/uidmap.container.md
View File

@ -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 <<subcommand>>** is called by a privileged user, the option **--uidmap**
When **podman <<subcommand>>** 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 <<subcommand>> --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 <<subcommand>> --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 <<subcommand>> --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.

8
docs/source/markdown/options/uidmap.pod.md
View File

@ -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.

6
docs/source/markdown/options/ulimit.md
View File

@ -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.

6
docs/source/markdown/options/user.md
View File

@ -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.

10
docs/source/markdown/options/userns.container.md
View File

@ -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.

10
docs/source/markdown/options/userns.pod.md
View File

@ -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.

6
docs/source/markdown/options/variant.container.md
View File

@ -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.

10
docs/source/markdown/options/volume.image.md
View File

@ -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]

12
docs/source/markdown/options/volume.md
View File

@ -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 <<container|pod>> 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:

8
docs/source/markdown/options/workdir.md
View File

@ -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.

8
docs/source/markdown/podman-auto-update.1.md.in
View File

@ -10,9 +10,9 @@ podman\-auto-update - Auto update containers according to their auto-update poli
**podman auto-update** pulls down new container images and restarts containers configured for auto updates.
To make use of auto updates, the container or Kubernetes workloads must run inside a systemd unit.
After a successful update of an image, the containers using the image get updated by restarting the systemd units they run in.
Please refer to `podman-systemd.unit(5)` on how to run Podman under systemd.
Please refer to `podman-quadlet(7)` on how to run Podman under systemd.
To configure a container for auto updates, it must be created with the `io.containers.autoupdate` label or the `AutoUpdate` field in `podman-systemd.unit(5)` with one of the following two values:
To configure a container for auto updates, it must be created with the `io.containers.autoupdate` label or the `AutoUpdate` field in `podman-quadlet(7)` with one of the following two values:
* `registry`: If the label is present and set to `registry`, Podman reaches out to the corresponding registry to check if the image has been updated.
The label `image` is an alternative to `registry` maintained for backwards compatibility.
@ -27,7 +27,7 @@ If they differ, the local image is considered to be newer and the systemd unit g
### Auto Updates and Kubernetes YAML
Podman supports auto updates for Kubernetes workloads. The auto-update policy can be configured directly via `podman-systemd.unit(5)` or inside the Kubernetes YAML with the Podman-specific annotations mentioned below:
Podman supports auto updates for Kubernetes workloads. The auto-update policy can be configured directly via `podman-quadlet(7)` or inside the Kubernetes YAML with the Podman-specific annotations mentioned below:
* `io.containers.autoupdate`: "registry|local" to apply the auto-update policy to all containers
* `io.containers.autoupdate/$container`: "registry|local" to apply the auto-update policy to `$container` only
@ -119,4 +119,4 @@ sleep.service f8e4759798d4 (systemd-sleep) registry.fedoraproject.org/fedora:l
```
## SEE ALSO
**[podman(1)](podman.1.md)**, **[podman-generate-systemd(1)](podman-generate-systemd.1.md)**, **[podman-run(1)](podman-run.1.md)**, **[podman-systemd.unit(5)](podman-systemd.unit.5.md)**, **sd_notify(3)**, **[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)**
**[podman(1)](podman.1.md)**, **[podman-generate-systemd(1)](podman-generate-systemd.1.md)**, **[podman-run(1)](podman-run.1.md)**, **[podman-quadlet(7)](podman-quadlet.7.md)**, **sd_notify(3)**, **[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)**

229
docs/source/markdown/podman-build.unit.5.md.in Normal file
View File

@ -0,0 +1,229 @@
% podman-build.unit(5)
# NAME
podman\-build.unit - systemd unit files for building container images using Podman Quadlet
# SYNOPSIS
*name*.build
# DESCRIPTION
Build units (`.build` files) are used by **Podman Quadlet** to declaratively define systemd services that
build container images from a `Containerfile` or `Dockerfile`.
These units ensure that the image is built on the host before being used by containers or volumes. If the
image already exists and the context hasn’t changed, subsequent executions will complete quickly thanks to
Podman’s build cache.
They are especially useful for:
- Creating images not available in registries
- Automating image builds during boot
- Local testing and development pipelines
A minimal `.build` file must specify:
- `ImageTag=` — to name the built image
- Either `File=` or `SetWorkingDirectory=`
# USAGE SUMMARY
The `.build` file is parsed by the `podman-system-generator` at boot or reload, generating a systemd
`.service` that runs `podman build`. That service can be managed like any other unit:
```bash
systemctl --user start myimage-build.service
```
The resulting image can be referenced by `.container` or `.volume` units via:
```ini
Image=myimage.build
```
# FILE LOCATIONS
Place `.build` files in one of the following:
### Rootless
- `$XDG_RUNTIME_DIR/containers/systemd/`
- `$XDG_CONFIG_HOME/containers/systemd/` or `~/.config/containers/systemd/`
- `/etc/containers/systemd/users/$(UID)`
- `/etc/containers/systemd/users/`
### Rootful
- `/run/containers/systemd/`
- `/etc/containers/systemd/`
- `/usr/share/containers/systemd/`
# OPTIONS
Valid options for `[Build]` section are listed below:
| **[Build] options** | **podman build equivalent** |
|-------------------------------------|---------------------------------------------|
| Annotation=annotation=value | --annotation=annotation=value |
| Arch=aarch64 | --arch=aarch64 |
| AuthFile=/etc/registry/auth\.json | --authfile=/etc/registry/auth\.json |
| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf |
| DNS=192.168.55.1 | --dns=192.168.55.1 |
| DNSOption=ndots:1 | --dns-option=ndots:1 |
| DNSSearch=example.com | --dns-search example.com |
| Environment=foo=bar | --env foo=bar |
| File=/path/to/Containerfile | --file=/path/to/Containerfile |
| ForceRM=false | --force-rm=false |
| GlobalArgs=--log-level=debug | --log-level=debug |
| GroupAdd=keep-groups | --group-add=keep-groups |
| ImageTag=localhost/imagename | --tag=localhost/imagename |
| Label=label | --label=label |
| Network=host | --network=host |
| PodmanArgs=--pull never | --pull never |
| Pull=never | --pull never |
| Retry=5 | --retry=5 |
| RetryDelay=10s | --retry-delay=10s |
| Secret=secret | --secret=id=mysecret,src=path |
| SetWorkingDirectory=unit | Set `WorkingDirectory` of systemd unit file |
| Target=my-app | --target=my-app |
| TLSVerify=false | --tls-verify=false |
| Variant=arm/v7 | --variant=arm/v7 |
| Volume=/source:/dest | --volume /source:/dest |
### `Annotation=`
Add an image *annotation* (e.g. annotation=*value*) to the image metadata. Can be used multiple
times.
This is equivalent to the `--annotation` option of `podman build`.
@@option quadlet:arch
@@option quadlet:authfile
@@option quadlet:module
@@option quadlet:dns
@@option quadlet:dns-option.image
@@option quadlet:dns-search.image
@@option quadlet:env.image
@@option quadlet:file
@@option quadlet:force-rm
### `GlobalArgs=`
This key contains a list of arguments passed directly between `podman` and `build` in the generated
file. It can be used to access Podman features otherwise unsupported by the generator. Since the
generator is unaware of what unexpected interactions can be caused by these arguments, it is not
recommended to use this option.
The format of this is a space separated list of arguments, which can optionally be individually
escaped to allow inclusion of whitespace and other control characters.
This key can be listed multiple times.
@@option quadlet:group-add
@@option quadlet:tag
@@option quadlet:label.image
@@option quadlet:network.image
### `PodmanArgs=`
This key contains a list of arguments passed directly to the end of the `podman build` command
in the generated file (right before the image name in the command line). It can be used to
access Podman features otherwise unsupported by the generator. Since the generator is unaware
of what unexpected interactions can be caused by these arguments, it is not recommended to use
this option.
The format of this is a space separated list of arguments, which can optionally be individually
escaped to allow inclusion of whitespace and other control characters.
This key can be listed multiple times.
@@option quadlet:pull
@@option quadlet:retry
@@option quadlet:retry-delay
@@option quadlet:secret.image
### `SetWorkingDirectory=`
Provide context (a working directory) to `podman build`. Supported values are a path, a URL, or the
special keys `file` or `unit` to set the context directory to the parent directory of the file from
the `File=` key or to that of the Quadlet `.build` unit file, respectively. This allows Quadlet to
resolve relative paths.
When using one of the special keys (`file` or `unit`), the `WorkingDirectory` field of the `Service`
group of the Systemd service unit will also be set to accordingly. Alternatively, users can
explicitly set the `WorkingDirectory` field of the `Service` group in the `.build` file. Please note
that if the `WorkingDirectory` field of the `Service` group is set by the user, Quadlet will not
overwrite it even if `SetWorkingDirectory` is set to `file` or `unit`.
By providing a URL to `SetWorkingDirectory=` you can instruct `podman build` to clone a Git
repository or download an archive file extracted to a temporary location by `podman build` as build
context. Note that in this case, the `WorkingDirectory` of the Systemd service unit is left
untouched by Quadlet.
Note that providing context directory is mandatory for a `.build` file, unless a `File=` key has
also been provided.
@@option quadlet:target
@@option quadlet:tls-verify
### `Variant=`
Override the default architecture variant of the container image to be built.
This is equivalent to the `--variant` option of `podman build`.
@@option quadlet:volume
# EXAMPLES
### Simple build
```ini
[Build]
ImageTag=localhost/myapp
File=Containerfile
SetWorkingDirectory=unit
```
### From Git repository
```ini
[Build]
ImageTag=localhost/mygitimage
File=Containerfile
SetWorkingDirectory=https://github.com/example/repo.git
```
### Build with secret
```ini
[Build]
ImageTag=localhost/secureimage
Secret=mysecret
```
# SEE ALSO
- [podman-quadlet(7)](podman-quadlet.7.md)
- [systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)
- [podman-build(1)](https://docs.podman.io/en/latest/markdown/podman-build.1.html)
- [podman-quadlet(7)]

559
docs/source/markdown/podman-container.unit.5.md.in Normal file
View File

@ -0,0 +1,559 @@
% podman-container.unit(5)
# NAME
podman\-container.unit - systemd unit files for managing containers using Podman Quadlet
# SYNOPSIS
*name*.container
# DESCRIPTION
Container units are `.container` files interpreted by Podman Quadlet to generate systemd `.service` units that manage containers as systemd services.
The `.container` file format extends regular systemd unit files with a `[Container]` section, allowing detailed configuration of the container to be run.
The resulting service file contains a line like `ExecStart=podman run … image-name`, and most of the keys in this section control the command-line
options passed to Podman. However, some options also affect the details of how systemd is set up to run and
interact with the container.
By default, the Podman container has the same name as the unit, but with a `systemd-` prefix, i.e.
a `$name.container` file creates a `$name.service` unit and a `systemd-$name` Podman container. The
`ContainerName` option allows for overriding this default name with a user-provided one.
There is only one required key, `Image`, which defines the container image the service runs.
# USAGE SUMMARY
The `.container` file is parsed by the `podman-system-generator` at boot or reload, generating a systemd
`.service` that runs `podman run`. That service can be managed like any other unit:
```bash
systemctl --user start myimage-container.service
```
# FILE LOCATIONS
Place `.container` files in one of the following:
### Rootless
- `$XDG_RUNTIME_DIR/containers/systemd/`
- `$XDG_CONFIG_HOME/containers/systemd/` or `~/.config/containers/systemd/`
- `/etc/containers/systemd/users/$(UID)`
- `/etc/containers/systemd/users/`
### Rootful
- `/run/containers/systemd/`
- `/etc/containers/systemd/`
- `/usr/share/containers/systemd/`
# OPTIONS
Valid options for `[Container]` are listed below:
| **[Container] options** | **podman run equivalent** |
|--------------------------------------|------------------------------------------------------|
| AddCapability=CAP | --cap-add CAP |
| AddDevice=/dev/foo | --device /dev/foo |
| AddHost=example\.com:192.168.10.11 | --add-host example.com:192.168.10.11 |
| Annotation="XYZ" | --annotation "XYZ" |
| AutoUpdate=registry | --label "io.containers.autoupdate=registry" |
| CgroupsMode=no-conmon | --cgroups=no-conmon |
| ContainerName=name | --name name |
| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf |
| DNS=192.168.55.1 | --dns=192.168.55.1 |
| DNSOption=ndots:1 | --dns-option=ndots:1 |
| DNSSearch=example.com | --dns-search example.com |
| DropCapability=CAP | --cap-drop=CAP |
| Entrypoint=/foo.sh | --entrypoint=/foo.sh |
| Environment=foo=bar | --env foo=bar |
| EnvironmentFile=/tmp/env | --env-file /tmp/env |
| EnvironmentHost=true | --env-host |
| Exec=/usr/bin/command | Command after image specification - /usr/bin/command |
| ExposeHostPort=50-59 | --expose 50-59 |
| GIDMap=0:10000:10 | --gidmap=0:10000:10 |
| GlobalArgs=--log-level=debug | --log-level=debug |
| Group=1234 | --user UID:1234 |
| GroupAdd=keep-groups | --group-add=keep-groups |
| HealthCmd=/usr/bin/command | --health-cmd=/usr/bin/command |
| HealthInterval=2m | --health-interval=2m |
| HealthLogDestination=/foo/log | --health-log-destination=/foo/log |
| HealthMaxLogCount=5 | --health-max-log-count=5 |
| HealthMaxLogSize=500 | --health-max-log-size=500 |
| HealthOnFailure=kill | --health-on-failure=kill |
| HealthRetries=5 | --health-retries=5 |
| HealthStartPeriod=1m | --health-start-period=period=1m |
| HealthStartupCmd=command | --health-startup-cmd=command |
| HealthStartupInterval=1m | --health-startup-interval=1m |
| HealthStartupRetries=8 | --health-startup-retries=8 |
| HealthStartupSuccess=2 | --health-startup-success=2 |
| HealthStartupTimeout=1m33s | --health-startup-timeout=1m33s |
| HealthTimeout=20s | --health-timeout=20s |
| HostName=example.com | --hostname example.com |
| Image=ubi8 | Image specification - ubi8 |
| IP=192.5.0.1 | --ip 192.5.0.1 |
| IP6=2001:db8::1 | --ip6 2001:db8::1 |
| Label="XYZ" | --label "XYZ" |
| LogDriver=journald | --log-driver journald |
| LogOpt=path=/var/log/mykube\.json | --log-opt path=/var/log/mykube\.json |
| Mask=/proc/sys/foo\:/proc/sys/bar | --security-opt mask=/proc/sys/foo:/proc/sys/bar |
| Memory=20g | --memory 20g |
| Mount=type=... | --mount type=... |
| Network=host | --network host |
| NetworkAlias=name | --network-alias name |
| NoNewPrivileges=true | --security-opt no-new-privileges |
| Notify=true | --sdnotify container |
| PidsLimit=10000 | --pids-limit 10000 |
| Pod=pod-name | --pod=pod-name |
| PodmanArgs=--publish 8080:80 | --publish 8080:80 |
| PublishPort=8080:80 | --publish 8080:80 |
| Pull=never | --pull never |
| ReadOnly=true | --read-only |
| ReadOnlyTmpfs=true | --read-only-tmpfs |
| ReloadCmd=/usr/bin/command | Add ExecReload and run exec with the value |
| ReloadSignal=SIGHUP | Add ExecReload and run kill with the signal |
| Retry=5 | --retry=5 |
| RetryDelay=5s | --retry-delay=5s |
| Rootfs=/var/lib/rootfs | --rootfs /var/lib/rootfs |
| RunInit=true | --init |
| SeccompProfile=/tmp/s.json | --security-opt seccomp=/tmp/s.json |
| Secret=secret | --secret=secret[,opt=opt ...] |
| SecurityLabelDisable=true | --security-opt label=disable |
| SecurityLabelFileType=usr_t | --security-opt label=filetype:usr_t |
| SecurityLabelLevel=s0:c1,c2 | --security-opt label=level:s0:c1,c2 |
| SecurityLabelNested=true | --security-opt label=nested |
| SecurityLabelType=spc_t | --security-opt label=type:spc_t |
| ShmSize=100m | --shm-size=100m |
| StartWithPod=true | If Pod= is defined, container is started by pod |
| StopSignal=SIGINT | --stop-signal=SIGINT |
| StopTimeout=20 | --stop-timeout=20 |
| SubGIDMap=gtest | --subgidname=gtest |
| SubUIDMap=utest | --subuidname=utest |
| Sysctl=name=value | --sysctl=name=value |
| Timezone=local | --tz local |
| Tmpfs=/work | --tmpfs /work |
| UIDMap=0:10000:10 | --uidmap=0:10000:10 |
| Ulimit=nofile=1000:10000 | --ulimit nofile=1000:10000 |
| Unmask=ALL | --security-opt unmask=ALL |
| User=bin | --user bin |
| UserNS=keep-id:uid=200,gid=210 | --userns keep-id:uid=200,gid=210 |
| Volume=/source:/dest | --volume /source:/dest |
| WorkingDir=$HOME | --workdir $HOME |
Description of `[Container]` section are:
@@option quadlet:cap-add
@@option quadlet:device
@@option quadlet:add-host
@@option quadlet:annotation.container
### `AutoUpdate=`
Indicates whether the container will be auto-updated ([podman-auto-update(1)](podman-auto-update.1.md)). The following values are supported:
* `registry`: Requires a fully-qualified image reference (e.g., quay.io/podman/stable:latest) to be used to create the container. This enforcement is necessary to know which image to actually check and pull. If an image ID was used, Podman does not know which image to check/pull anymore.
* `local`: Tells Podman to compare the image a container is using to the image with its raw name in local storage. If an image is updated locally, Podman simply restarts the systemd unit executing the container.
@@option quadlet:cgroups
@@option quadlet:name.container
@@option quadlet:module
@@option quadlet:dns
@@option quadlet:dns-option.container
@@option quadlet:dns-search.container
@@option quadlet:cap-drop
@@option quadlet:entrypoint
@@option quadlet:env
@@option quadlet:env-file
@@option quadlet:env-host
### `Exec=`
Additional arguments for the container; this has exactly the same effect as passing
more arguments after a `podman run <image> <arguments>` invocation.
The format is the same as for [systemd command lines](https://www.freedesktop.org/software/systemd/man/systemd.service.html#Command%20lines),
However, unlike the usage scenario for similarly-named systemd `ExecStart=` verb
which operates on the ambient root filesystem, it is very common for container
images to have their own `ENTRYPOINT` or `CMD` metadata which this interacts with.
The default expectation for many images is that the image will include an `ENTRYPOINT`
with a default binary, and this field will add arguments to that entrypoint.
Another way to describe this is that it works the same way as the [args field in a Kubernetes pod](https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell).
@@option quadlet:expose
@@option quadlet:gidmap.container
### `GlobalArgs=`
This key contains a list of arguments passed directly between `podman` and `run`
in the generated file. It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware
of what unexpected interactions can be caused by these arguments, it is not recommended to use
this option.
The format of this is a space separated list of arguments, which can optionally be individually
escaped to allow inclusion of whitespace and other control characters.
This key can be listed multiple times.
### `Group=`
The (numeric) GID to run as inside the container. This does not need to match the GID on the host,
which can be modified with `UserNS`, but if that is not specified, this GID is also used on the host.
@@option quadlet:group-add
@@option quadlet:health-cmd
@@option quadlet:health-interval
@@option quadlet:health-log-destination
@@option quadlet:health-max-log-count
@@option quadlet:health-max-log-size
@@option quadlet:health-on-failure
@@option quadlet:health-retries
@@option quadlet:health-start-period
@@option quadlet:health-startup-cmd
@@option quadlet:health-startup-interval
@@option quadlet:health-startup-retries
@@option quadlet:health-startup-success
@@option quadlet:health-startup-timeout
@@option quadlet:health-timeout
@@option quadlet:hostname.container
### `Image=`
The image to run in the container.
It is recommended to use a fully qualified image name rather than a short name, both for
performance and robustness reasons.
The format of the name is the same as when passed to `podman pull`. So, it supports using
`:tag` or digests to guarantee the specific image version.
Special Cases:
* If the `name` of the image ends with `.image`, Quadlet will use the image pulled by the corresponding `.image` file, and the generated systemd service contains a dependency on the `$name-image.service` (or the service name set in the .image file). Note that the corresponding `.image` file must exist.
* If the `name` of the image ends with `.build`, Quadlet will use the image built by the corresponding `.build` file, and the generated systemd service contains a dependency on the `$name-build.service`. Note: the corresponding `.build` file must exist.
@@option quadlet:ip
@@option quadlet:ip6
@@option quadlet:label
@@option quadlet:log-driver
@@option quadlet:log-opt
### `Mask=`
Specify the paths to mask separated by a colon. `Mask=/path/1:/path/2`. A masked path cannot be accessed inside the container.
@@option quadlet:memory
@@option quadlet:mount
@@option quadlet:network
@@option quadlet:network-alias
### `NoNewPrivileges=` (defaults to `false`)
If enabled, this disables the container processes from gaining additional privileges via things like
setuid and file capabilities.
### `Notify=` (defaults to `false`)
By default, Podman is run in such a way that the systemd startup notify command is handled by
the container runtime. In other words, the service is deemed started when the container runtime
starts the child in the container. However, if the container application supports
[sd_notify](https://www.freedesktop.org/software/systemd/man/sd_notify.html), then setting
`Notify` to true passes the notification details to the container allowing it to notify
of startup on its own.
In addition, setting `Notify` to `healthy` will postpone startup notifications until such time as
the container is marked healthy, as determined by Podman healthchecks. Note that this requires
setting up a container healthcheck, see the `HealthCmd` option for more.
@@option quadlet:pids-limit
### `Pod=`
Specify a Quadlet `.pod` unit to link the container to.
The value must take the form of `<name>.pod` and the `.pod` unit must exist.
Quadlet will add all the necessary parameters to link between the container and the pod and between their corresponding services.
### `PodmanArgs=`
This key contains a list of arguments passed directly to the end of the `podman run` command
in the generated file (right before the image name in the command line). It can be used to
access Podman features otherwise unsupported by the generator. Since the generator is unaware
of what unexpected interactions can be caused by these arguments, it is not recommended to use
this option.
The format of this is a space separated list of arguments, which can optionally be individually
escaped to allow inclusion of whitespace and other control characters.
This key can be listed multiple times.
@@option quadlet:publish
@@option quadlet:pull
@@option quadlet:read-only
@@option quadlet:read-only-tmpfs
### `ReloadCmd=`
Add `ExecReload` line to the `Service` that runs ` podman exec` with this command in this container.
In order to execute the reload run `systemctl reload <Service>`
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 <Service>`
Mutually exclusive with `ReloadCmd`
@@option quadlet:retry
@@option quadlet:retry-delay
@@option quadlet:rootfs
@@option quadlet:init
### `SeccompProfile=`
Set the seccomp profile to use in the container. If unset, the default podman profile is used.
Set to either the pathname of a JSON file, or `unconfined` to disable the seccomp filters.
@@option quadlet:secret
### `SecurityLabelDisable=`
Turn off label separation for the container.
### `SecurityLabelFileType=`
Set the label file type for the container files.
### `SecurityLabelLevel=`
Set the label process level for the container processes.
### `SecurityLabelNested=`
Allow SecurityLabels to function within the container. This allows separation of containers created within the container.
### `SecurityLabelType=`
Set the label process type for the container processes.
@@option quadlet:shm-size
### `StartWithPod=`
Start the container after the associated pod is created. Default to **true**.
If `true`, container will be started/stopped/restarted alongside the pod.
If `false`, the container will not be started when the pod starts. The container will be stopped with the pod. Restarting the pod will also restart the container as long as the container was also running before.
Note, the container can still be started manually or through a target by configuring the `[Install]` section. The pod will be started as needed in any case.
@@option quadlet:stop-signal
@@option quadlet:stop-timeout
@@option quadlet:subgidname
@@option quadlet:subuidname
@@option quadlet:sysctl
@@option quadlet:tz
@@option quadlet:tmpfs
@@option quadlet:uidmap.container
@@option quadlet:ulimit
### `Unmask=`
Specify the paths to unmask separated by a colon. unmask=ALL or /path/1:/path/2, or shell expanded paths (/proc/*):
If set to `ALL`, Podman will unmask all the paths that are masked or made read-only by default.
The default masked paths are /proc/acpi, /proc/kcore, /proc/keys, /proc/latency_stats, /proc/sched_debug, /proc/scsi, /proc/timer_list, /proc/timer_stats, /sys/firmware, and /sys/fs/selinux.
The default paths that are read-only are /proc/asound, /proc/bus, /proc/fs, /proc/irq, /proc/sys, /proc/sysrq-trigger, /sys/fs/cgroup.
@@option quadlet:user
@@option quadlet:userns.container
@@option quadlet:volume
@@option quadlet:workdir
# SERVICE TYPE
By default, the generator sets `Type=notify` for `.container` units.
This can be overridden by explicitly setting `Type=` in the `[Service]` section.
For one-shot containers (e.g., init tasks), use:
```
[Service]
Type=oneshot
RemainAfterExit=yes
```
Refer to `systemd.service(5)` for full details on service types and related behaviors.
# INSTALL SECTION
To ensure a container starts on boot, include an `[Install]` section:
```
[Install]
WantedBy=multi-user.target
```
Only `Alias=`, `WantedBy=`, `RequiredBy=`, and `UpheldBy=` keys are supported.
# TIMEOUTS
Container startup may exceed systemd’s default 90s timeout (e.g., when pulling images). Use:
```
[Service]
TimeoutStartSec=900
```
Note: `TimeoutStartSec` is ignored for `Type=oneshot`.
# NETWORK DEPENDENCIES
Quadlet adds:
- `After=network-online.target` (for root units)
- `After=podman-user-wait-network-online.service` (for user units)
To disable this, add:
```
[Quadlet]
DefaultDependencies=false
```
# RESOURCE NAMING
By default, the container is named `systemd-<unitname>`. Use `ContainerName=` to override.
Avoid using systemd specifiers like `%N` in resource names—they break inter-resource linking.
# TEMPLATE UNITS
Quadlet supports templated container units, e.g., `foo@.container` creates `foo@.service`.
You can instantiate with:
```bash
systemctl start foo@bar.service
```
You may also symlink instances:
```bash
ln -s foo@.container foo@bar.container
```
Use drop-ins for instance-specific customization:
```
foo@bar.container.d/10-override.conf
```
# DROP-IN FILES
Quadlet supports drop-in configuration in `.container.d/` directories.
For example, a drop-in:
```
test.container.d/10-extra.conf
```
can override or extend the main unit file.
Drop-ins follow the same override and merging behavior as systemd units.
# EXAMPLE
Minimal container unit:
```
[Unit]
Description=A minimal container
[Container]
Image=quay.io/centos/centos:latest
Exec=sleep 60
[Install]
WantedBy=multi-user.target
```
# SEE ALSO
[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html),
[systemd.service(5)](https://www.freedesktop.org/software/systemd/man/systemd.service.html),
[systemd-analyze(1)](https://www.freedesktop.org/software/systemd/man/latest/systemd-analyze.html),
[podman-run(1)](https://docs.podman.io/en/latest/markdown/podman-run.1.html),
[podman-quadlet(7)]

4
docs/source/markdown/podman-generate-systemd.1.md
View File

@ -8,7 +8,7 @@ podman\-generate\-systemd - [DEPRECATED] Generate systemd unit file(s) for a con
## DESCRIPTION
DEPRECATED:
Note: **podman generate systemd** is deprecated. We recommend using [Quadlet](podman-systemd.unit.5.md)
Note: **podman generate systemd** is deprecated. We recommend using [Quadlet](podman-quadlet.7.md)
files when running Podman containers or pods under systemd. There are no plans to remove the command.
It will receive urgent bug fixes but no new features.
@ -311,7 +311,7 @@ CONTAINER ID IMAGE COMMAND CREATED STATUS
bb310a0780ae docker.io/library/alpine:latest /bin/sh 3 minutes ago Created busy_moser
```
## SEE ALSO
**[podman(1)](podman.1.md)**, **[podman-container(1)](podman-container.1.md)**, **systemctl(1)**, **systemd.unit(5)**, **systemd.service(5)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**, **[podman-systemd.unit(5)](podman-systemd.unit.5.md)**
**[podman(1)](podman.1.md)**, **[podman-container(1)](podman-container.1.md)**, **systemctl(1)**, **systemd.unit(5)**, **systemd.service(5)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**, **[podman-quadlet(7)](podman-quadlet.7.md)**
## HISTORY
April 2020, Updated details and added use case to use generated .service files as root and non-root, by Sujil Shah (sushah at redhat dot com)

199
docs/source/markdown/podman-image.unit.5.md.in Normal file
View File

@ -0,0 +1,199 @@
% podman-image.unit(5)
# NAME
podman\-image.unit - systemd unit files for managing container image pulls using Podman Quadlet
# SYNOPSIS
*name*.image
# DESCRIPTION
Image files are named with a `.image` extension and contain a section `[Image]` describing the
container image pull command. The generated service is a one-time command that ensures that the image
exists on the host, pulling it if needed.
Using image units allows containers and volumes to depend on images being automatically pulled. This is
particularly interesting when using special options to control image pulls.
# USAGE SUMMARY
The `.image` file is parsed by the `podman-system-generator` at boot or reload, generating a systemd
`.service` that runs `podman image pull`.
The reference to the `.image` file can be used in the `.container` file's `Image=` option.
# FILE LOCATIONS
Place `.image` files in one of the following:
### Rootless
- `$XDG_RUNTIME_DIR/containers/systemd/`
- `$XDG_CONFIG_HOME/containers/systemd/` or `~/.config/containers/systemd/`
- `/etc/containers/systemd/users/$(UID)`
- `/etc/containers/systemd/users/`
### Rootful
- `/run/containers/systemd/`
- `/etc/containers/systemd/`
- `/usr/share/containers/systemd/`
# OPTIONS
Valid options for `[Image]` are listed below:
| **[Image] options** | **podman image pull equivalent** |
|----------------------------------------|--------------------------------------------------|
| AllTags=true | --all-tags |
| Arch=aarch64 | --arch=aarch64 |
| AuthFile=/etc/registry/auth\.json | --authfile=/etc/registry/auth\.json |
| CertDir=/etc/registry/certs | --cert-dir=/etc/registry/certs |
| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf |
| Creds=myname\:mypassword | --creds=myname\:mypassword |
| DecryptionKey=/etc/registry\.key | --decryption-key=/etc/registry\.key |
| GlobalArgs=--log-level=debug | --log-level=debug |
| Image=quay\.io/centos/centos:latest | podman image pull quay.io/centos/centos\:latest |
| ImageTag=quay\.io/centos/centos:latest | Use this name when resolving `.image` references |
| OS=windows | --os=windows |
| PodmanArgs=--os=linux | --os=linux |
| Policy=always | --policy=always |
| Retry=5 | --retry=5 |
| RetryDelay=10s | --retry-delay=10s |
| TLSVerify=false | --tls-verify=false |
| Variant=arm/v7 | --variant=arm/v7 |
### `AllTags=`
All tagged images in the repository are pulled.
This is equivalent to the Podman `--all-tags` option.
@@option quadlet:arch
@@option quadlet:authfile
@@option quadlet:cert-dir
@@option quadlet:module
@@option quadlet:creds
@@option quadlet:decryption-key
### `GlobalArgs=`
This key contains a list of arguments passed directly between `podman` and `image`
in the generated file. It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware
of what unexpected interactions can be caused by these arguments, it is not recommended to use
this option.
The format of this is a space separated list of arguments, which can optionally be individually
escaped to allow inclusion of whitespace and other control characters.
This key can be listed multiple times.
### `Image=`
The image to pull.
It is recommended to use a fully qualified image name rather than a short name, both for
performance and robustness reasons.
The format of the name is the same as when passed to `podman pull`. So, it supports using
`:tag` or digests to guarantee the specific image version.
### `ImageTag=`
Actual FQIN of the referenced `Image`.
Only meaningful when source is a file or directory archive.
For example, an image saved into a `docker-archive` with the following Podman command:
`podman image save --format docker-archive --output /tmp/archive-file.tar quay.io/podman/stable:latest`
requires setting
- `Image=docker-archive:/tmp/archive-file.tar`
- `ImageTag=quay.io/podman/stable:latest`
@@option quadlet:os.pull
### `PodmanArgs=`
This key contains a list of arguments passed directly to the end of the `podman image pull` command
in the generated file (right before the image name in the command line). It can be used to
access Podman features otherwise unsupported by the generator. Since the generator is unaware
of what unexpected interactions can be caused by these arguments, it is not recommended to use
this option.
The format of this is a space separated list of arguments, which can optionally be individually
escaped to allow inclusion of whitespace and other control characters.
This key can be listed multiple times.
### `Policy=`
The pull policy to use when pulling the image.
This is equivalent to the Podman `--policy` option.
@@option quadlet:retry
@@option quadlet:retry-delay
@@option quadlet:tls-verify
@@option quadlet:variant.container
## Quadlet section [Quadlet]
Some quadlet specific configuration is shared between different unit types. Those settings
can be configured in the `[Quadlet]` section.
Valid options for `[Quadlet]` are listed below:
| **[Quadlet] options** | **Description** |
|----------------------------|---------------------------------------------------|
| DefaultDependencies=false | Disable implicit network dependencies to the unit |
### `DefaultDependencies=`
Add Quadlet's default network dependencies to the unit (default is `true`).
When set to false, Quadlet will **not** add a dependency (After=, Wants=) to
`network-online.target`/`podman-user-wait-network-online.service` to the generated unit.
Note, this option is set in the `[Quadlet]` section. The _systemd_ `[Unit]` section
has an option with the same name but a different meaning.
# EXAMPLES
Basic image pull:
```
[Image]
Image=quay.io/centos/centos:latest
```
Pull from docker archive:
```
[Image]
Image=docker-archive:/tmp/centos.tar
ImageTag=quay.io/centos/centos:latest
```
Pull with credentials:
```
[Image]
Image=quay.io/private/image:latest
Creds=myuser:mypassword
```
# SEE ALSO
[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html),
[podman-image-pull(1)](https://docs.podman.io/en/latest/markdown/podman-image-pull.1.html),
[podman-quadlet(7)]

173
docs/source/markdown/podman-kube.unit.5.md.in Normal file
View File

@ -0,0 +1,173 @@
% podman-kube.unit(5)
# NAME
podman\-kube.unit - systemd unit files for managing Podman Kubernetes YAML deployments using Quadlet
# SYNOPSIS
*name*.kube
# DESCRIPTION
Kube units are named with a `.kube` extension and contain a `[Kube]` section describing
how `podman kube play` runs as a service. The resulting service file contains a line like
`ExecStart=podman kube play … file.yml`, and most of the keys in this section control the command-line
options passed to Podman. However, some options also affect the details of how systemd is set up to run and
interact with the container.
There is only one required key, `Yaml`, which defines the path to the Kubernetes YAML file.
# USAGE SUMMARY
The `.kube` file is parsed by the `podman-system-generator` at boot or reload, generating a systemd
`.service` that runs `podman kube play`. That service can be managed like any other unit:
```bash
systemctl --user start name.service
```
# FILE LOCATIONS
Place `.kube` files in one of the following:
### Rootless
- `$XDG_RUNTIME_DIR/containers/systemd/`
- `$XDG_CONFIG_HOME/containers/systemd/` or `~/.config/containers/systemd/`
- `/etc/containers/systemd/users/$(UID)`
- `/etc/containers/systemd/users/`
### Rootful
- `/run/containers/systemd/`
- `/etc/containers/systemd/`
- `/usr/share/containers/systemd/`
# OPTIONS
Valid options for `[Kube]` are listed below:
| **[Kube] options** | **podman kube play equivalent** |
| ------------------------------------| -----------------------------------------------------------------|
| AutoUpdate=registry | --annotation "io.containers.autoupdate=registry" |
| ConfigMap=/tmp/config.map | --config-map /tmp/config.map |
| ContainersConfModule=/etc/nvd\.conf | --module=/etc/nvd\.conf |
| ExitCodePropagation=how | How to propagate container error status |
| GlobalArgs=--log-level=debug | --log-level=debug |
| KubeDownForce=true | --force (for `podman kube down`) |
| LogDriver=journald | --log-driver journald |
| Network=host | --network host |
| PodmanArgs=\-\-annotation=key=value | --annotation=key=value |
| PublishPort=8080:80 | --publish 8080:80 |
| SetWorkingDirectory=yaml | Set `WorkingDirectory` of unit file to location of the YAML file |
| UserNS=keep-id:uid=200,gid=210 | --userns keep-id:uid=200,gid=210 |
| Yaml=/tmp/kube.yaml | podman kube play /tmp/kube.yaml |
Supported keys in the `[Kube]` section are:
### `AutoUpdate=`
Indicates whether containers will be auto-updated ([podman-auto-update(1)](podman-auto-update.1.md)). AutoUpdate can be specified multiple times. The following values are supported:
* `registry`: Requires a fully-qualified image reference (e.g., quay.io/podman/stable:latest) to be used to create the container. This enforcement is necessary to know which images to actually check and pull. If an image ID was used, Podman does not know which image to check/pull anymore.
* `local`: Tells Podman to compare the image a container is using to the image with its raw name in local storage. If an image is updated locally, Podman simply restarts the systemd unit executing the Kubernetes Quadlet.
* `name/(local|registry)`: Tells Podman to perform the `local` or `registry` autoupdate on the specified container name.
### `ConfigMap=`
Pass the Kubernetes ConfigMap YAML path to `podman kube play` via the `--configmap` argument.
Unlike the `configmap` argument, the value may contain only one path but
it may be absolute or relative to the location of the unit file.
This key may be used multiple times
@@option quadlet:module
### `ExitCodePropagation=`
Control how the main PID of the systemd service should exit. The following values are supported:
- `all`: exit non-zero if all containers have failed (i.e., exited non-zero)
- `any`: exit non-zero if any container has failed
- `none`: exit zero and ignore failed containers
The current default value is `none`.
### `GlobalArgs=`
This key contains a list of arguments passed directly between `podman` and `kube`
in the generated file. It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware
of what unexpected interactions can be caused by these arguments, it is not recommended to use
this option.
The format of this is a space separated list of arguments, which can optionally be individually
escaped to allow inclusion of whitespace and other control characters.
This key can be listed multiple times.
### `KubeDownForce=`
Remove all resources, including volumes, when calling `podman kube down`.
Equivalent to the Podman `--force` option.
@@option quadlet:log-driver
@@option quadlet:network
### `PodmanArgs=`
This key contains a list of arguments passed directly to the end of the `podman kube play` command
in the generated file (right before the path to the yaml file in the command line). It can be used to
access Podman features otherwise unsupported by the generator. Since the generator is unaware
of what unexpected interactions can be caused by these arguments, is not recommended to use
this option.
The format of this is a space separated list of arguments, which can optionally be individually
escaped to allow inclusion of whitespace and other control characters.
This key can be listed multiple times.
@@option quadlet:publish
### `SetWorkingDirectory=`
Set the `WorkingDirectory` field of the `Service` group of the Systemd service unit file.
Used to allow `podman kube play` to correctly resolve relative paths.
Supported values are `yaml` and `unit` to set the working directory to that of the YAML or Quadlet Unit file respectively.
Alternatively, users can explicitly set the `WorkingDirectory` field of the `Service` group in the `.kube` file.
Please note that if the `WorkingDirectory` field of the `Service` group is set,
Quadlet will not set it even if `SetWorkingDirectory` is set
@@option quadlet:userns.container
### `Yaml=`
The path, absolute or relative to the location of the unit file, to the Kubernetes YAML file to use.
# EXAMPLES
Deploy from local YAML:
```
[Unit]
Description=A kubernetes yaml based service
Before=local-fs.target
[Kube]
Yaml=/opt/k8s/deployment.yml
[Install]
# Start by default on boot
WantedBy=multi-user.target default.target
```
# SEE ALSO
[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html),
[podman-kube-play(1)](https://docs.podman.io/en/latest/markdown/podman-kube-play.1.html),
[podman-quadlet(7)]

Some files were not shown because too many files have changed in this diff Show More