diff options
Diffstat (limited to 'docs')
31 files changed, 312 insertions, 368 deletions
diff --git a/docs/Makefile b/docs/Makefile index fb67e266c..c9192f5e6 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -13,7 +13,8 @@ help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) clean: - rm -fr build/ + $(RM) -fr build + cd source/markdown && $(RM) -f $$(<.gitignore) .PHONY: help Makefile diff --git a/docs/source/conf.py b/docs/source/conf.py index 505bcbec7..b58bb3f46 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -15,6 +15,19 @@ # sys.path.insert(0, os.path.abspath('.')) import re +import os +import subprocess + +# We have to run the preprocessor to create the actual markdown files from .in files. +# Do it here so the it can work on readthedocs as well. +path = os.path.join(os.path.abspath(os.path.dirname( + __file__)), "../../hack/markdown-preprocess") +p = subprocess.Popen(path, + stdout=subprocess.PIPE, stderr=subprocess.PIPE) +out, err = p.communicate() +if p.returncode != 0: + raise Exception("failed to run markdown-preprocess", out, err) + # -- Project information ----------------------------------------------------- diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore new file mode 100644 index 000000000..c441d74c5 --- /dev/null +++ b/docs/source/markdown/.gitignore @@ -0,0 +1,2 @@ +podman-create.1.md +podman-run.1.md diff --git a/docs/source/markdown/options/cgroup-conf.md b/docs/source/markdown/options/cgroup-conf.md new file mode 100644 index 000000000..91d724ab6 --- /dev/null +++ b/docs/source/markdown/options/cgroup-conf.md @@ -0,0 +1,3 @@ +#### **--cgroup-conf**=*KEY=VALUE* + +When running on cgroup v2, specify the cgroup file to write to and its value. For example **--cgroup-conf=memory.high=1073741824** sets the memory.high limit to 1GB. diff --git a/docs/source/markdown/options/chrootdirs.md b/docs/source/markdown/options/chrootdirs.md new file mode 100644 index 000000000..624a10624 --- /dev/null +++ b/docs/source/markdown/options/chrootdirs.md @@ -0,0 +1,5 @@ +#### **--chrootdirs**=*path* + +Path to a directory inside the container that should be treated as a `chroot` directory. +Any Podman managed file (e.g., /etc/resolv.conf, /etc/hosts, etc/hostname) that is mounted into the root directory will be mounted into that location as well. +Multiple directories should be separated with a comma. diff --git a/docs/source/markdown/options/env-host.md b/docs/source/markdown/options/env-host.md new file mode 100644 index 000000000..665fca016 --- /dev/null +++ b/docs/source/markdown/options/env-host.md @@ -0,0 +1,3 @@ +#### **--env-host** + +Use host environment inside of the container. See **Environment** note below for precedence. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) diff --git a/docs/source/markdown/options/group-add.md b/docs/source/markdown/options/group-add.md new file mode 100644 index 000000000..ac9ade3a7 --- /dev/null +++ b/docs/source/markdown/options/group-add.md @@ -0,0 +1,11 @@ +#### **--group-add**=*group* | *keep-groups* + +Assign additional groups to the primary user running within the container process. + +- `keep-groups` is a special flag that tells Podman to keep the supplementary group access. + +Allows container to use the user's supplementary group access. If file systems or +devices are only accessible by the rootless user's group, this flag tells the OCI +runtime to pass the group access into the container. Currently only available +with the `crun` OCI runtime. Note: `keep-groups` is exclusive, you cannot add any other groups +with this flag. (Not available for remote commands, including Mac and Windows (excluding WSL2) machines) diff --git a/docs/source/markdown/options/hostuser.md b/docs/source/markdown/options/hostuser.md new file mode 100644 index 000000000..d1d12c88f --- /dev/null +++ b/docs/source/markdown/options/hostuser.md @@ -0,0 +1,4 @@ +#### **--hostuser**=*name* + +Add a user account to /etc/passwd from the host to the container. The Username +or UID must exist on the host system. diff --git a/docs/source/markdown/options/image-volume.md b/docs/source/markdown/options/image-volume.md new file mode 100644 index 000000000..2a549ef3c --- /dev/null +++ b/docs/source/markdown/options/image-volume.md @@ -0,0 +1,8 @@ +#### **--image-volume**=**bind** | *tmpfs* | *ignore* + +Tells Podman how to handle the builtin image volumes. Default is **bind**. + +- **bind**: An anonymous named volume will be created and mounted into the container. +- **tmpfs**: The volume is mounted onto the container as a tmpfs, which allows the users to create +content that disappears when the container is stopped. +- **ignore**: All volumes are just ignored and no action is taken. diff --git a/docs/source/markdown/options/init-path.md b/docs/source/markdown/options/init-path.md new file mode 100644 index 000000000..c2be27874 --- /dev/null +++ b/docs/source/markdown/options/init-path.md @@ -0,0 +1,3 @@ +#### **--init-path**=*path* + +Path to the container-init binary. diff --git a/docs/source/markdown/options/init.md b/docs/source/markdown/options/init.md new file mode 100644 index 000000000..caf300efe --- /dev/null +++ b/docs/source/markdown/options/init.md @@ -0,0 +1,5 @@ +#### **--init** + +Run an init inside the container that forwards signals and reaps processes. +The container-init binary is mounted at `/run/podman-init`. +Mounting over `/run` will hence break container execution. diff --git a/docs/source/markdown/options/mount.md b/docs/source/markdown/options/mount.md new file mode 100644 index 000000000..e81af539d --- /dev/null +++ b/docs/source/markdown/options/mount.md @@ -0,0 +1,77 @@ +#### **--mount**=*type=TYPE,TYPE-SPECIFIC-OPTION[,...]* + +Attach a filesystem mount to the container + +Current supported mount TYPEs are **bind**, **volume**, **image**, **tmpfs** and **devpts**. <sup>[[1]](#Footnote1)</sup> + + e.g. + + type=bind,source=/path/on/host,destination=/path/in/container + + type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared + + type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared,U=true + + type=volume,source=vol1,destination=/path/in/container,ro=true + + type=tmpfs,tmpfs-size=512M,destination=/path/in/container + + type=image,source=fedora,destination=/fedora-image,rw=true + + type=devpts,destination=/dev/pts + + Common Options: + + · src, source: mount source spec for bind and volume. Mandatory for bind. + + · dst, destination, target: mount destination spec. + + Options specific to volume: + + · ro, readonly: true or false (default). + + . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container. + + · idmap: true or false (default). If specified, create an idmapped mount to the target user namespace in the container. + + Options specific to image: + + · rw, readwrite: true or false (default). + + Options specific to bind: + + · ro, readonly: true or false (default). + + · bind-propagation: shared, slave, private, unbindable, rshared, rslave, runbindable, or rprivate(default). See also mount(2). + + . bind-nonrecursive: do not set up a recursive bind mount. By default it is recursive. + + . relabel: shared, private. + + · idmap: true or false (default). If specified, create an idmapped mount to the target user namespace in the container. + + . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container. + + Options specific to tmpfs: + + · ro, readonly: true or false (default). + + · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux. + + · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux. + + · tmpcopyup: Enable copyup from the image directory at the same location to the tmpfs. Used by default. + + · notmpcopyup: Disable copying files from the image to the tmpfs. + + . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container. + + Options specific to devpts: + + · uid: UID of the file owner (default 0). + + · gid: GID of the file owner (default 0). + + · mode: permission mask for the file (default 600). + + · max: maximum number of PTYs (default 1048576). diff --git a/docs/source/markdown/options/no-healthcheck.md b/docs/source/markdown/options/no-healthcheck.md new file mode 100644 index 000000000..a722ac5b5 --- /dev/null +++ b/docs/source/markdown/options/no-healthcheck.md @@ -0,0 +1,3 @@ +#### **--no-healthcheck** + +Disable any defined healthchecks for container. diff --git a/docs/source/markdown/options/oom-kill-disable.md b/docs/source/markdown/options/oom-kill-disable.md new file mode 100644 index 000000000..24ed9a889 --- /dev/null +++ b/docs/source/markdown/options/oom-kill-disable.md @@ -0,0 +1,5 @@ +#### **--oom-kill-disable** + +Whether to disable OOM Killer for the container or not. + +This flag is not supported on cgroups V2 systems. diff --git a/docs/source/markdown/options/passwd-entry.md b/docs/source/markdown/options/passwd-entry.md new file mode 100644 index 000000000..33c179d12 --- /dev/null +++ b/docs/source/markdown/options/passwd-entry.md @@ -0,0 +1,5 @@ +#### **--passwd-entry**=*ENTRY* + +Customize the entry that is written to the `/etc/passwd` file within the container when `--passwd` is used. + +The variables $USERNAME, $UID, $GID, $NAME, $HOME are automatically replaced with their value at runtime. diff --git a/docs/source/markdown/options/personality.md b/docs/source/markdown/options/personality.md new file mode 100644 index 000000000..663f14782 --- /dev/null +++ b/docs/source/markdown/options/personality.md @@ -0,0 +1,3 @@ +#### **--personality**=*persona* + +Personality sets the execution domain via Linux personality(2). diff --git a/docs/source/markdown/options/pidfile.md b/docs/source/markdown/options/pidfile.md new file mode 100644 index 000000000..a494b522e --- /dev/null +++ b/docs/source/markdown/options/pidfile.md @@ -0,0 +1,9 @@ +#### **--pidfile**=*path* + +When the pidfile location is specified, the container process' PID will be written to the pidfile. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) +If the pidfile option is not specified, the container process' PID will be written to /run/containers/storage/${storage-driver}-containers/$CID/userdata/pidfile. + +After the container is started, the location for the pidfile can be discovered with the following `podman inspect` command: + + $ podman inspect --format '{{ .PidFile }}' $CID + /run/containers/storage/${storage-driver}-containers/$CID/userdata/pidfile diff --git a/docs/source/markdown/options/sdnotify.md b/docs/source/markdown/options/sdnotify.md new file mode 100644 index 000000000..d090cbf7c --- /dev/null +++ b/docs/source/markdown/options/sdnotify.md @@ -0,0 +1,10 @@ +#### **--sdnotify**=**container** | *conmon* | *ignore* + +Determines how to use the NOTIFY_SOCKET, as passed with systemd and Type=notify. + +Default is **container**, which means allow the OCI runtime to proxy the socket into the +container to receive ready notification. Podman will set the MAINPID to conmon's pid. +The **conmon** option sets MAINPID to conmon's pid, and sends READY when the container +has started. The socket is never passed to the runtime or the container. +The **ignore** option removes NOTIFY_SOCKET from the environment for itself and child processes, +for the case where some other process above Podman uses NOTIFY_SOCKET and Podman should not use it. diff --git a/docs/source/markdown/options/seccomp-policy.md b/docs/source/markdown/options/seccomp-policy.md new file mode 100644 index 000000000..3b2eb7553 --- /dev/null +++ b/docs/source/markdown/options/seccomp-policy.md @@ -0,0 +1,5 @@ +#### **--seccomp-policy**=*policy* + +Specify the policy to select the seccomp profile. If set to *image*, Podman will look for a "io.containers.seccomp.profile" label in the container-image config and use its value as a seccomp profile. Otherwise, Podman will follow the *default* policy by applying the default profile unless specified otherwise via *--security-opt seccomp* as described below. + +Note that this feature is experimental and may change in the future. diff --git a/docs/source/markdown/options/timeout.md b/docs/source/markdown/options/timeout.md new file mode 100644 index 000000000..731feb973 --- /dev/null +++ b/docs/source/markdown/options/timeout.md @@ -0,0 +1,5 @@ +#### **--timeout**=*seconds* + +Maximum time a container is allowed to run before conmon sends it the kill +signal. By default containers will run until they exit or are stopped by +`podman stop`. diff --git a/docs/source/markdown/options/tz.md b/docs/source/markdown/options/tz.md new file mode 100644 index 000000000..0442e8a76 --- /dev/null +++ b/docs/source/markdown/options/tz.md @@ -0,0 +1,4 @@ +#### **--tz**=*timezone* + +Set timezone in container. This flag takes area-based timezones, GMT time, as well as `local`, which sets the timezone in the container to match the host machine. See `/usr/share/zoneinfo/` for valid timezones. +Remote connections use local containers.conf for defaults diff --git a/docs/source/markdown/options/umask.md b/docs/source/markdown/options/umask.md new file mode 100644 index 000000000..55668b6da --- /dev/null +++ b/docs/source/markdown/options/umask.md @@ -0,0 +1,4 @@ +#### **--umask**=*umask* + +Set the umask inside the container. Defaults to `0022`. +Remote connections use local containers.conf for defaults diff --git a/docs/source/markdown/options/unsetenv-all.md b/docs/source/markdown/options/unsetenv-all.md new file mode 100644 index 000000000..3aad2e805 --- /dev/null +++ b/docs/source/markdown/options/unsetenv-all.md @@ -0,0 +1,5 @@ +#### **--unsetenv-all** + +Unset all default environment variables for the container. Default environment +variables include variables provided natively by Podman, environment variables +configured by the image, and environment variables from containers.conf. diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md.in index b3e707e45..008c3c18f 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md.in @@ -115,9 +115,7 @@ Add Linux capabilities Drop Linux capabilities -#### **--cgroup-conf**=*KEY=VALUE* - -When running on cgroup v2, specify the cgroup file to write to and its value. For example **--cgroup-conf=memory.high=1073741824** sets the memory.high limit to 1GB. +@@option cgroup-conf #### **--cgroup-parent**=*path* @@ -143,11 +141,7 @@ The *disabled* option will force the container to not create CGroups, and thus c The *no-conmon* option disables a new CGroup only for the conmon process. The *split* option splits the current cgroup in two sub-cgroups: one for conmon and one for the container payload. It is not possible to set *--cgroup-parent* with *split*. -#### **--chrootdirs**=*path* - -Path to a directory inside the container that should be treated as a `chroot` directory. -Any Podman managed file (e.g., /etc/resolv.conf, /etc/hosts, etc/hostname) that is mounted into the root directory will be mounted into that location as well. -Multiple directories should be separated with a comma. +@@option chrootdirs #### **--cidfile**=*id* @@ -358,9 +352,7 @@ See [**Environment**](#environment) note below for precedence and examples. Read in a line delimited file of environment variables. See **Environment** note below for precedence. -#### **--env-host** - -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) +@@option env-host #### **--expose**=*port* @@ -376,17 +368,7 @@ __--uidmap__ maps host UIDs to container UIDs. For details see __--uidmap__. Note: the **--gidmap** flag cannot be called in conjunction with the **--pod** flag as a gidmap cannot be set on the container level when in a pod. -#### **--group-add**=*group* | *keep-groups* - -Assign additional groups to the primary user running within the container process. - -- `keep-groups` is a special flag that tells Podman to keep the supplementary group access. - -Allows container to use the user's supplementary group access. If file systems or -devices are only accessible by the rootless user's group, this flag tells the OCI -runtime to pass the group access into the container. Currently only available -with the `crun` OCI runtime. Note: `keep-groups` is exclusive, you cannot add any other groups -with this flag. (Not available for remote commands, including Mac and Windows (excluding WSL2) machines) +@@option group-add #### **--health-cmd**=*"command"* | *'["command", "arg1", ...]'* @@ -425,10 +407,7 @@ Container host name Sets the container host name that is available inside the container. Can only be used with a private UTS namespace `--uts=private` (default). If `--pod` is specified and the pod shares the UTS namespace (default) the pod's hostname will be used. -#### **--hostuser**=*name* - -Add a user account to /etc/passwd from the host to the container. The Username -or UID must exist on the host system. +@@option hostuser #### **--http-proxy** @@ -450,20 +429,9 @@ container: Defaults to `true` -#### **--image-volume**=**bind** | *tmpfs* | *ignore* - -Tells Podman how to handle the builtin image volumes. Default is **bind**. - -- **bind**: An anonymous named volume will be created and mounted into the container. -- **tmpfs**: The volume is mounted onto the container as a tmpfs, which allows the users to create -content that disappears when the container is stopped. -- **ignore**: All volumes are just ignored and no action is taken. +@@option image-volume -#### **--init** - -Run an init inside the container that forwards signals and reaps processes. -The container-init binary is mounted at `/run/podman-init`. -Mounting over `/run` will hence break container execution. +@@option init #### **--init-ctr**=*type* @@ -480,9 +448,7 @@ Init containers are only run on pod `start`. Restarting a pod will not execute containers should they be present. Furthermore, init containers can only be created in a pod when that pod is not running. -#### **--init-path**=*path* - -Path to the container-init binary. +@@option init-path #### **--interactive**, **-i** @@ -611,83 +577,7 @@ Tune a container's memory swappiness behavior. Accepts an integer between 0 and This flag is not supported on cgroups V2 systems. -#### **--mount**=*type=TYPE,TYPE-SPECIFIC-OPTION[,...]* - -Attach a filesystem mount to the container - -Current supported mount TYPEs are **bind**, **volume**, **image**, **tmpfs** and **devpts**. <sup>[[1]](#Footnote1)</sup> - - e.g. - - type=bind,source=/path/on/host,destination=/path/in/container - - type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared - - type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared,U=true - - type=volume,source=vol1,destination=/path/in/container,ro=true - - type=tmpfs,tmpfs-size=512M,destination=/path/in/container - - type=image,source=fedora,destination=/fedora-image,rw=true - - type=devpts,destination=/dev/pts - - Common Options: - - · src, source: mount source spec for bind and volume. Mandatory for bind. - - · dst, destination, target: mount destination spec. - - Options specific to volume: - - · ro, readonly: true or false (default). - - . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container. - - · idmap: true or false (default). If specified, create an idmapped mount to the target user namespace in the container. - - Options specific to image: - - · rw, readwrite: true or false (default). - - Options specific to bind: - - · ro, readonly: true or false (default). - - · bind-propagation: shared, slave, private, unbindable, rshared, rslave, runbindable, or rprivate(default). See also mount(2). - - . bind-nonrecursive: do not set up a recursive bind mount. By default it is recursive. - - . relabel: shared, private. - - · idmap: true or false (default). If specified, create an idmapped mount to the target user namespace in the container. - - . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container. - - Options specific to tmpfs: - - · ro, readonly: true or false (default). - - · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux. - - · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux. - - · tmpcopyup: Enable copyup from the image directory at the same location to the tmpfs. Used by default. - - · notmpcopyup: Disable copying files from the image to the tmpfs. - - . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container. - - Options specific to devpts: - - · uid: UID of the file owner (default 0). - - · gid: GID of the file owner (default 0). - - · mode: permission mask for the file (default 600). - - · max: maximum number of PTYs (default 1048576). +@@option mount #### **--name**=*name* @@ -745,9 +635,7 @@ these aliases can be used for name resolution on the given network. This option NOTE: When using CNI a container will only have access to aliases on the first network that it joins. This limitation does not exist with netavark/aardvark-dns. -#### **--no-healthcheck** - -Disable any defined healthchecks for container. +@@option no-healthcheck #### **--no-hosts** @@ -756,11 +644,7 @@ By default, Podman will manage _/etc/hosts_, adding the container's own IP addre **--no-hosts** disables this, and the image's _/etc/hosts_ will be preserved unmodified. This option conflicts with **--add-host**. -#### **--oom-kill-disable** - -Whether to disable OOM Killer for the container or not. - -This flag is not supported on cgroups V2 systems. +@@option oom-kill-disable #### **--oom-score-adj**=*num* @@ -769,15 +653,9 @@ Tune the host's OOM preferences for containers (accepts -1000 to 1000) #### **--os**=*OS* Override the OS, defaults to hosts, of the image to be pulled. For example, `windows`. -#### **--passwd-entry**=*ENTRY* - -Customize the entry that is written to the `/etc/passwd` file within the container when `--passwd` is used. +@@option passwd-entry -The variables $USERNAME, $UID, $GID, $NAME, $HOME are automatically replaced with their value at runtime. - -#### **--personality**=*persona* - -Personality sets the execution domain via Linux personality(2). +@@option personality #### **--pid**=*pid* @@ -788,15 +666,7 @@ Default is to create a private PID namespace for the container - `ns`: join the specified PID namespace - `private`: create a new namespace for the container (default) -#### **--pidfile**=*path* - -When the pidfile location is specified, the container process' PID will be written to the pidfile. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) -If the pidfile option is not specified, the container process' PID will be written to /run/containers/storage/${storage-driver}-containers/$CID/userdata/pidfile. - -After the container is started, the location for the pidfile can be discovered with the following `podman inspect` command: - - $ podman inspect --format '{{ .PidFile }}' $CID - /run/containers/storage/${storage-driver}-containers/$CID/userdata/pidfile +@@option pidfile #### **--pids-limit**=*limit* @@ -944,22 +814,9 @@ directory will be the lower, and the container storage directory will be the upper. Modifications to the mount point are destroyed when the container finishes executing, similar to a tmpfs mount point being unmounted. -#### **--sdnotify**=**container** | *conmon* | *ignore* - -Determines how to use the NOTIFY_SOCKET, as passed with systemd and Type=notify. - -Default is **container**, which means allow the OCI runtime to proxy the socket into the -container to receive ready notification. Podman will set the MAINPID to conmon's pid. -The **conmon** option sets MAINPID to conmon's pid, and sends READY when the container -has started. The socket is never passed to the runtime or the container. -The **ignore** option removes NOTIFY_SOCKET from the environment for itself and child processes, -for the case where some other process above Podman uses NOTIFY_SOCKET and Podman should not use it. - -#### **--seccomp-policy**=*policy* - -Specify the policy to select the seccomp profile. If set to *image*, Podman will look for a "io.containers.seccomp.profile" label in the container-image config and use its value as a seccomp profile. Otherwise, Podman will follow the *default* policy by applying the default profile unless specified otherwise via *--security-opt seccomp* as described below. +@@option sdnotify -Note that this feature is experimental and may change in the future. +@@option seccomp-policy #### **--secret**=*secret[,opt=opt ...]* @@ -1085,11 +942,7 @@ The `container_manage_cgroup` boolean must be enabled for this to be allowed on `setsebool -P container_manage_cgroup true` -#### **--timeout**=*seconds* - -Maximum time a container is allowed to run before conmon sends it the kill -signal. By default containers will run until they exit or are stopped by -`podman stop`. +@@option timeout #### **--tls-verify** @@ -1119,10 +972,7 @@ interactive shell. The default is false. Note: The **-t** option is incompatible with a redirection of the Podman client standard input. -#### **--tz**=*timezone* - -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 +@@option tz #### **--uidmap**=*container_uid:from_uid:amount* @@ -1208,10 +1058,7 @@ Ulimit options You can pass `host` to copy the current configuration from the host. -#### **--umask**=*umask* - -Set the umask inside the container. Defaults to `0022`. -Remote connections use local containers.conf for defaults +@@option umask #### **--unsetenv**=*env* @@ -1219,11 +1066,7 @@ Unset default environment variables for the container. Default environment variables include variables provided natively by Podman, environment variables configured by the image, and environment variables from containers.conf. -#### **--unsetenv-all** - -Unset all default environment variables for the container. Default environment -variables include variables provided natively by Podman, environment variables -configured by the image, and environment variables from containers.conf. +@@option unsetenv-all #### **--user**, **-u**=*user* diff --git a/docs/source/markdown/podman-info.1.md b/docs/source/markdown/podman-info.1.md index 347d8d27b..fc7e1f0e2 100644 --- a/docs/source/markdown/podman-info.1.md +++ b/docs/source/markdown/podman-info.1.md @@ -15,10 +15,6 @@ Displays information pertinent to the host, current storage stats, configured co ## OPTIONS -#### **--debug**, **-D** - -Show additional information - #### **--format**, **-f**=*format* Change output format to "json" or a Go template. diff --git a/docs/source/markdown/podman-kube-down.1.md b/docs/source/markdown/podman-kube-down.1.md new file mode 100644 index 000000000..35725043b --- /dev/null +++ b/docs/source/markdown/podman-kube-down.1.md @@ -0,0 +1,43 @@ +% podman-kube-down(1) + +## NAME +podman-kube-down - Remove containers and pods based on Kubernetes YAML + +## SYNOPSIS +**podman kube down** *file.yml|-* + +## DESCRIPTION +**podman kube down** reads a specified Kubernetes YAML file, tearing down pods that were created by the `podman kube play` command via the same Kubernetes YAML file. Any volumes that were created by the previous `podman kube play` command remain intact. If the YAML file is specified as `-`, `podman kube down` reads the YAML from stdin. + +## EXAMPLES + +Example YAML file `demo.yml`: +``` +apiVersion: v1 +kind: Pod +metadata: +... +spec: + containers: + - command: + - top + - name: container + value: podman + image: foobar +... +``` + +Remove the pod and containers as described in the `demo.yml` file +``` +$ podman kube down demo.yml +52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 +``` + +Remove the pod and containers as described in the`demo.yml` file YAML sent to stdin +``` +$ cat demo.yml | podman kube play - +52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-kube(1)](podman-kube.1.md)**, **[podman-kube-play(1)](podman-kube-play.1.md)**, **[podman-generate-kube(1)](podman-generate-kube.1.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)** diff --git a/docs/source/markdown/podman-kube-play.1.md b/docs/source/markdown/podman-kube-play.1.md index 25248ce99..b3c385fe9 100644 --- a/docs/source/markdown/podman-kube-play.1.md +++ b/docs/source/markdown/podman-kube-play.1.md @@ -1,7 +1,7 @@ % podman-kube-play(1) ## NAME -podman-kube-play - Create containers, pods or volumes based on Kubernetes YAML +podman-kube-play - Create containers, pods and volumes based on Kubernetes YAML ## SYNOPSIS **podman kube play** [*options*] *file.yml|-* @@ -30,6 +30,9 @@ Note: If the `:latest` tag is used, Podman will attempt to pull the image from a Note: The command `podman play kube` is an alias of `podman kube play`, and will perform the same function. +Note: The command `podman kube down` can be used to stop and remove pods or containers based on the same Kubernetes YAML used +by `podman kube play` to create them. + `Kubernetes PersistentVolumeClaims` A Kubernetes PersistentVolumeClaim represents a Podman named volume. Only the PersistentVolumeClaim name is required by Podman to create a volume. Kubernetes annotations can be used to make use of the available options for Podman volumes. @@ -145,11 +148,6 @@ The [username[:password]] to use to authenticate with the registry if required. If one or both values are not supplied, a command line prompt will appear and the value can be entered. The password is entered without echo. -#### **--down** - -Tears down the pods that were created by a previous run of `kube play`. The pods are stopped and then -removed. Any volumes created are left intact. - #### **--help**, **-h** Print usage statement @@ -325,7 +323,7 @@ $ podman kube play demo.yml --network net1:ip=10.89.1.5 --network net2:ip=10.89. Please take into account that networks must be created first using podman-network-create(1). ## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-kube(1)](podman-kube.1.md)**, **[podman-network-create(1)](podman-network-create.1.md)**, **[podman-generate-kube(1)](podman-generate-kube.1.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)** +**[podman(1)](podman.1.md)**, **[podman-kube(1)](podman-kube.1.md)**, **[podman-kube-down(1)](podman-kube-down.1.md)**, **[podman-network-create(1)](podman-network-create.1.md)**, **[podman-generate-kube(1)](podman-generate-kube.1.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)** ## HISTORY December 2018, Originally compiled by Brent Baude (bbaude at redhat dot com) diff --git a/docs/source/markdown/podman-kube.1.md b/docs/source/markdown/podman-kube.1.md index f815ffae2..7a6978a2b 100644 --- a/docs/source/markdown/podman-kube.1.md +++ b/docs/source/markdown/podman-kube.1.md @@ -14,7 +14,8 @@ file input. Containers will be automatically started. | Command | Man Page | Description | | ------- | --------------------------------------------------- | ---------------------------------------------------------------------------- | -| play | [podman-kube-play(1)](podman-kube-play.1.md) | Create containers, pods or volumes based on Kubernetes YAML. | +| down | [podman-kube-down(1)](podman-kube-down.1.md) | Remove containers and pods based on Kubernetes YAML. | +| play | [podman-kube-play(1)](podman-kube-play.1.md) | Create containers, pods and volumes based on Kubernetes YAML. | ## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-container(1)](podman-container.1.md)**, **[podman-generate(1)](podman-generate.1.md)**, **[podman-kube-play(1)](podman-kube-play.1.md)** +**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-container(1)](podman-container.1.md)**, **[podman-generate(1)](podman-generate.1.md)**, **[podman-kube-play(1)](podman-kube-play.1.md)**, **[podman-kube-down(1)](podman-kube-down.1.md)** diff --git a/docs/source/markdown/podman-rm.1.md b/docs/source/markdown/podman-rm.1.md index 1fac3aa34..1dbd1d0c3 100644 --- a/docs/source/markdown/podman-rm.1.md +++ b/docs/source/markdown/podman-rm.1.md @@ -26,6 +26,30 @@ Read container ID from the specified file and remove the container. Can be spec Remove selected container and recursively remove all containers that depend on it. +#### **--filter**=*filter* + +Filter what containers remove. +Multiple filters can be given with multiple uses of the --filter flag. +Filters with the same key work inclusive with the only exception being +`label` which is exclusive. Filters with different keys always work exclusive. + +Valid filters are listed below: + +| **Filter** | **Description** | +| --------------- | -------------------------------------------------------------------------------- | +| id | [ID] Container's ID (accepts regex) | +| name | [Name] Container's name (accepts regex) | +| label | [Key] or [Key=Value] Label assigned to a container | +| exited | [Int] Container's exit code | +| status | [Status] Container's status: 'created', 'exited', 'paused', 'running', 'unknown' | +| ancestor | [ImageName] Image or descendant used to create container | +| before | [ID] or [Name] Containers created before this container | +| since | [ID] or [Name] Containers created since this container | +| volume | [VolumeName] or [MountpointDestination] Volume mounted in container | +| health | [Status] healthy or unhealthy | +| pod | [Pod] name or full or partial ID of pod | +| network | [Network] name or full ID of network | + #### **--force**, **-f** Force the removal of running and paused containers. Forcing a container removal also diff --git a/docs/source/markdown/podman-rmi.1.md b/docs/source/markdown/podman-rmi.1.md index 8d0e5e500..93658daaf 100644 --- a/docs/source/markdown/podman-rmi.1.md +++ b/docs/source/markdown/podman-rmi.1.md @@ -28,6 +28,9 @@ This option will cause podman to remove all containers that are using the image If a specified image does not exist in the local storage, ignore it and do not throw an error. +#### **--no-prune** + +This options will not remove dangling parents of specified image Remove an image by its short ID ``` diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md.in index 8c889f0a5..df4c43c41 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md.in @@ -132,9 +132,7 @@ Add Linux capabilities. Drop Linux capabilities. -#### **--cgroup-conf**=*KEY=VALUE* - -When running on cgroup v2, specify the cgroup file to write to and its value. For example **--cgroup-conf=memory.high=1073741824** sets the memory.high limit to 1GB. +@@option cgroup-conf #### **--cgroup-parent**=*path* @@ -162,11 +160,7 @@ The **disabled** option will force the container to not create CGroups, and thus The **no-conmon** option disables a new CGroup only for the **conmon** process. The **split** option splits the current CGroup in two sub-cgroups: one for conmon and one for the container payload. It is not possible to set **--cgroup-parent** with **split**. -#### **--chrootdirs**=*path* - -Path to a directory inside the container that should be treated as a `chroot` directory. -Any Podman managed file (e.g., /etc/resolv.conf, /etc/hosts, etc/hostname) that is mounted into the root directory will be mounted into that location as well. -Multiple directories should be separated with a comma. +@@option chrootdirs #### **--cidfile**=*file* @@ -393,9 +387,7 @@ See [**Environment**](#environment) note below for precedence and examples. Read in a line delimited file of environment variables. See **Environment** note below for precedence. -#### **--env-host** - -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) +@@option env-host #### **--expose**=*port* @@ -411,17 +403,7 @@ __--uidmap__ maps host UIDs to container UIDs. For details see __--uidmap__. Note: the **--gidmap** flag cannot be called in conjunction with the **--pod** flag as a gidmap cannot be set on the container level when in a pod. -#### **--group-add**=*group* | *keep-groups* - -Assign additional groups to the primary user running within the container process. - -- `keep-groups` is a special flag that tells Podman to keep the supplementary group access. - -Allows container to use the user's supplementary group access. If file systems or -devices are only accessible by the rootless user's group, this flag tells the OCI -runtime to pass the group access into the container. Currently only available -with the `crun` OCI runtime. Note: `keep-groups` is exclusive, you cannot add any other groups -with this flag. (Not available for remote commands, including Mac and Windows (excluding WSL2) machines) +@@option group-add #### **--health-cmd**=*"command"* | *'["command", "arg1", ...]'* @@ -460,10 +442,7 @@ Container host name Sets the container host name that is available inside the container. Can only be used with a private UTS namespace `--uts=private` (default). If `--pod` is specified and the pod shares the UTS namespace (default) the pod's hostname will be used. -#### **--hostuser**=*name* - -Add a user account to /etc/passwd from the host to the container. The Username -or UID must exist on the host system. +@@option hostuser #### **--http-proxy** @@ -480,24 +459,11 @@ proxy environment at container build time.) (This option is not available with t Defaults to **true**. -#### **--image-volume**=**bind** | *tmpfs* | *ignore* - -Tells Podman how to handle the builtin image volumes. Default is **bind**. - -- **bind**: An anonymous named volume will be created and mounted into the container. -- **tmpfs**: The volume is mounted onto the container as a tmpfs, which allows the users to create -content that disappears when the container is stopped. -- **ignore**: All volumes are just ignored and no action is taken. +@@option image-volume -#### **--init** +@@option init -Run an init inside the container that forwards signals and reaps processes. -The container-init binary is mounted at `/run/podman-init`. -Mounting over `/run` will hence break container execution. - -#### **--init-path**=*path* - -Path to the container-init binary. +@@option init-path #### **--interactive**, **-i** @@ -627,83 +593,7 @@ Tune a container's memory swappiness behavior. Accepts an integer between *0* an This flag is not supported on cgroups V2 systems. -#### **--mount**=*type=TYPE,TYPE-SPECIFIC-OPTION[,...]* - -Attach a filesystem mount to the container - -Current supported mount TYPEs are **bind**, **volume**, **image**, **tmpfs** and **devpts**. <sup>[[1]](#Footnote1)</sup> - - e.g. - - type=bind,source=/path/on/host,destination=/path/in/container - - type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared - - type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared,U=true - - type=volume,source=vol1,destination=/path/in/container,ro=true - - type=tmpfs,tmpfs-size=512M,destination=/path/in/container - - type=image,source=fedora,destination=/fedora-image,rw=true - - type=devpts,destination=/dev/pts - - Common Options: - - · src, source: mount source spec for bind and volume. Mandatory for bind. - - · dst, destination, target: mount destination spec. - - Options specific to volume: - - · ro, readonly: true or false (default). - - . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container. - - · idmap: true or false (default). If specified, create an idmapped mount to the target user namespace in the container. - - Options specific to image: - - · rw, readwrite: true or false (default). - - Options specific to bind: - - · ro, readonly: true or false (default). - - · bind-propagation: shared, slave, private, unbindable, rshared, rslave, runbindable, or rprivate(default). See also mount(2). - - . bind-nonrecursive: do not set up a recursive bind mount. By default it is recursive. - - . relabel: shared, private. - - · idmap: true or false (default). If specified, create an idmapped mount to the target user namespace in the container. - - . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container. - - Options specific to tmpfs: - - · ro, readonly: true or false (default). - - · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux. - - · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux. - - · tmpcopyup: Enable copyup from the image directory at the same location to the tmpfs. Used by default. - - · notmpcopyup: Disable copying files from the image to the tmpfs. - - . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container. - - Options specific to devpts: - - · uid: UID of the file owner (default 0). - - · gid: GID of the file owner (default 0). - - · mode: permission mask for the file (default 600). - - · max: maximum number of PTYs (default 1048576). +@@option mount #### **--name**=*name* @@ -762,9 +652,7 @@ these aliases can be used for name resolution on the given network. This option NOTE: When using CNI a container will only have access to aliases on the first network that it joins. This limitation does not exist with netavark/aardvark-dns. -#### **--no-healthcheck** - -Disable any defined healthchecks for container. +@@option no-healthcheck #### **--no-hosts** @@ -773,11 +661,7 @@ By default, Podman will manage _/etc/hosts_, adding the container's own IP addre **--no-hosts** disables this, and the image's _/etc/hosts_ will be preserved unmodified. This option conflicts with **--add-host**. -#### **--oom-kill-disable** - -Whether to disable OOM Killer for the container or not. - -This flag is not supported on cgroups V2 systems. +@@option oom-kill-disable #### **--oom-score-adj**=*num* @@ -791,15 +675,9 @@ Override the OS, defaults to hosts, of the image to be pulled. For example, `win Allow Podman to add entries to /etc/passwd and /etc/group when used in conjunction with the --user option. This is used to override the Podman provided user setup in favor of entrypoint configurations such as libnss-extrausers. -#### **--passwd-entry**=*ENTRY* - -Customize the entry that is written to the `/etc/passwd` file within the container when `--passwd` is used. +@@option passwd-entry -The variables $USERNAME, $UID, $GID, $NAME, $HOME are automatically replaced with their value at runtime. - -#### **--personality**=*persona* - -Personality sets the execution domain via Linux personality(2). +@@option personality #### **--pid**=*mode* @@ -811,15 +689,7 @@ The default is to create a private PID namespace for the container. - **private**: create a new namespace for the container (default) - **ns:**_path_: join the specified PID namespace. -#### **--pidfile**=*path* - -When the pidfile location is specified, the container process' PID will be written to the pidfile. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) -If the pidfile option is not specified, the container process' PID will be written to /run/containers/storage/${storage-driver}-containers/$CID/userdata/pidfile. - -After the container is started, the location for the pidfile can be discovered with the following `podman inspect` command: - - $ podman inspect --format '{{ .PidFile }}' $CID - /run/containers/storage/${storage-driver}-containers/$CID/userdata/pidfile +@@option pidfile #### **--pids-limit**=*limit* @@ -982,22 +852,9 @@ finishes executing, similar to a tmpfs mount point being unmounted. Note: On **SELinux** systems, the rootfs needs the correct label, which is by default **unconfined_u:object_r:container_file_t**. -#### **--sdnotify**=**container** | *conmon* | *ignore* - -Determines how to use the NOTIFY_SOCKET, as passed with systemd and Type=notify. - -Default is **container**, which means allow the OCI runtime to proxy the socket into the -container to receive ready notification. Podman will set the MAINPID to conmon's pid. -The **conmon** option sets MAINPID to conmon's pid, and sends READY when the container -has started. The socket is never passed to the runtime or the container. -The **ignore** option removes NOTIFY_SOCKET from the environment for itself and child processes, -for the case where some other process above Podman uses NOTIFY_SOCKET and Podman should not use it. - -#### **--seccomp-policy**=*policy* - -Specify the policy to select the seccomp profile. If set to *image*, Podman will look for a "io.containers.seccomp.profile" label in the container-image config and use its value as a seccomp profile. Otherwise, Podman will follow the *default* policy by applying the default profile unless specified otherwise via *--security-opt seccomp* as described below. +@@option sdnotify -Note that this feature is experimental and may change in the future. +@@option seccomp-policy #### **--secret**=*secret[,opt=opt ...]* @@ -1139,11 +996,7 @@ The **container_manage_cgroup** boolean must be enabled for this to be allowed o setsebool -P container_manage_cgroup true ``` -#### **--timeout**=*seconds* - -Maximum time a container is allowed to run before conmon sends it the kill -signal. By default containers will run until they exit or are stopped by -`podman stop`. +@@option timeout #### **--tls-verify** @@ -1178,10 +1031,7 @@ interactive shell. The default is **false**. echo "asdf" | podman run --rm -i someimage /bin/cat ``` -#### **--tz**=*timezone* - -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 +@@option tz #### **--uidmap**=*container_uid:from_uid:amount* @@ -1267,10 +1117,7 @@ Note: the **--uidmap** flag cannot be called in conjunction with the **--pod** f Ulimit options. You can use **host** to copy the current configuration from the host. -#### **--umask**=*umask* - -Set the umask inside the container. Defaults to `0022`. -Remote connections use local containers.conf for defaults +@@option umask #### **--unsetenv**=*env* @@ -1278,11 +1125,7 @@ Unset default environment variables for the container. Default environment variables include variables provided natively by Podman, environment variables configured by the image, and environment variables from containers.conf. -#### **--unsetenv-all** - -Unset all default environment variables for the container. Default environment -variables include variables provided natively by Podman, environment variables -configured by the image, and environment variables from containers.conf. +@@option unsetenv-all #### **--user**, **-u**=*user[:group]* |