diff options
| author | Ed Santiago <santiago@redhat.com> | 2022-03-23 12:29:08 -0600 |
|---|---|---|
| committer | Ed Santiago <santiago@redhat.com> | 2022-03-23 13:49:42 -0600 |
| commit | 9b0c8d23bddd0fccd6a1faa3fa7f5b7e0373f541 (patch) | |
| tree | 37dad6631948e2cfa28165a423c6bf22f9ab4d1e | |
| parent | 73713062806aa4c2db25dc62e2fff47406085dc8 (diff) | |
| download | podman-9b0c8d23bddd0fccd6a1faa3fa7f5b7e0373f541.tar.gz podman-9b0c8d23bddd0fccd6a1faa3fa7f5b7e0373f541.tar.bz2 podman-9b0c8d23bddd0fccd6a1faa3fa7f5b7e0373f541.zip | |
man pages: sort flags, and keep them that way
Command flags (OPTIONS) in man pages have to date been in
haphazard order. Sometimes that order is sensible, e.g.,
most-important options first, but more often they're
just in arbitrary places. This makes life hard for users.
Here, I update the man-page-check Makefile script so it
checks and enforces alphabetical order in OPTIONS sections.
Then -- the hard part -- update all existing man pages to
conform to this requirement.
Signed-off-by: Ed Santiago <santiago@redhat.com>
50 files changed, 605 insertions, 590 deletions
diff --git a/docs/source/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md index c96f60c48..c8707521f 100644 --- a/docs/source/markdown/podman-build.1.md +++ b/docs/source/markdown/podman-build.1.md @@ -312,7 +312,7 @@ environment variable. `export BUILDAH_FORMAT=docker` Overrides the first `FROM` instruction within the Containerfile. If there are multiple FROM instructions in a Containerfile, only the first is changed. -**-h**, **--help** +#### **--help**, **-h** Print usage statement @@ -320,15 +320,15 @@ Print usage statement Pass through HTTP Proxy environment variables. +#### **--ignorefile** + +Path to an alternative .containerignore file. + #### **--iidfile**=*ImageIDfile* Write the built image's ID to the file. When `--platform` is specified more than once, attempting to use this option will trigger an error. -#### **--ignorefile** - -Path to an alternative .containerignore file. - #### **--ipc**=*how* Sets the configuration for IPC namespaces when handling `RUN` instructions. @@ -643,47 +643,62 @@ the user namespace in which `podman` itself is being run should be reused, or it can be the path to a user namespace which is already in use by another process. -#### **--userns-uid-map**=*mapping* +#### **--userns-gid-map**=*mapping* -Directly specifies a UID mapping which should be used to set ownership, at the +Directly specifies a GID mapping which should be used to set ownership, at the filesystem level, on the working container's contents. Commands run when handling `RUN` instructions will default to being run in their own user namespaces, configured using the UID and GID maps. Entries in this map take the form of one or more triples of a starting -in-container UID, a corresponding starting host-level UID, and the number of +in-container GID, a corresponding starting host-level GID, and the number of consecutive IDs which the map entry represents. -This option overrides the *remap-uids* setting in the *options* section of +This option overrides the *remap-gids* setting in the *options* section of /etc/containers/storage.conf. -If this option is not specified, but a global --userns-uid-map setting is +If this option is not specified, but a global --userns-gid-map setting is supplied, settings from the global option will be used. -If none of --userns-uid-map-user, --userns-gid-map-group, or --userns-uid-map -are specified, but --userns-gid-map is specified, the UID map will be set to -use the same numeric values as the GID map. +If none of --userns-uid-map-user, --userns-gid-map-group, or --userns-gid-map +are specified, but --userns-uid-map is specified, the GID map will be set to +use the same numeric values as the UID map. -#### **--userns-gid-map**=*mapping* +#### **--userns-gid-map-group**=*group* -Directly specifies a GID mapping which should be used to set ownership, at the +Specifies that a GID mapping which should be used to set ownership, at the +filesystem level, on the working container's contents, can be found in entries +in the `/etc/subgid` file which correspond to the specified group. +Commands run when handling `RUN` instructions will default to being run in +their own user namespaces, configured using the UID and GID maps. +If --userns-uid-map-user is specified, but --userns-gid-map-group is not +specified, `podman` will assume that the specified user name is also a +suitable group name to use as the default setting for this option. + +**NOTE:** When this option is specified by a rootless user, the specified +mappings are relative to the rootless user namespace in the container, rather +than being relative to the host as it would be when run rootfull. + +#### **--userns-uid-map**=*mapping* + +Directly specifies a UID mapping which should be used to set ownership, at the filesystem level, on the working container's contents. Commands run when handling `RUN` instructions will default to being run in their own user namespaces, configured using the UID and GID maps. Entries in this map take the form of one or more triples of a starting -in-container GID, a corresponding starting host-level GID, and the number of +in-container UID, a corresponding starting host-level UID, and the number of consecutive IDs which the map entry represents. -This option overrides the *remap-gids* setting in the *options* section of +This option overrides the *remap-uids* setting in the *options* section of /etc/containers/storage.conf. -If this option is not specified, but a global --userns-gid-map setting is +If this option is not specified, but a global --userns-uid-map setting is supplied, settings from the global option will be used. -If none of --userns-uid-map-user, --userns-gid-map-group, or --userns-gid-map -are specified, but --userns-uid-map is specified, the GID map will be set to -use the same numeric values as the UID map. +If none of --userns-uid-map-user, --userns-gid-map-group, or --userns-uid-map +are specified, but --userns-gid-map is specified, the UID map will be set to +use the same numeric values as the GID map. #### **--userns-uid-map-user**=*user* @@ -700,21 +715,6 @@ suitable user name to use as the default setting for this option. mappings are relative to the rootless user namespace in the container, rather than being relative to the host as it would be when run rootfull. -#### **--userns-gid-map-group**=*group* - -Specifies that a GID mapping which should be used to set ownership, at the -filesystem level, on the working container's contents, can be found in entries -in the `/etc/subgid` file which correspond to the specified group. -Commands run when handling `RUN` instructions will default to being run in -their own user namespaces, configured using the UID and GID maps. -If --userns-uid-map-user is specified, but --userns-gid-map-group is not -specified, `podman` will assume that the specified user name is also a -suitable group name to use as the default setting for this option. - -**NOTE:** When this option is specified by a rootless user, the specified -mappings are relative to the rootless user namespace in the container, rather -than being relative to the host as it would be when run rootfull. - #### **--uts**=*how* Sets the configuration for UTS namespaces when handling `RUN` instructions. diff --git a/docs/source/markdown/podman-commit.1.md b/docs/source/markdown/podman-commit.1.md index df3c38711..3df931254 100644 --- a/docs/source/markdown/podman-commit.1.md +++ b/docs/source/markdown/podman-commit.1.md @@ -60,14 +60,14 @@ Set commit message for committed image.\ Pause the container when creating an image.\ The default is **false**. -#### **--squash**, **-s** +#### **--quiet**, **-q** -Squash newly built layers into a single new layer.\ +Suppresses output.\ The default is **false**. -#### **--quiet**, **-q** +#### **--squash**, **-s** -Suppresses output.\ +Squash newly built layers into a single new layer.\ The default is **false**. ## EXAMPLES diff --git a/docs/source/markdown/podman-container-checkpoint.1.md b/docs/source/markdown/podman-container-checkpoint.1.md index fcb3cfd0c..5c07cd975 100644 --- a/docs/source/markdown/podman-container-checkpoint.1.md +++ b/docs/source/markdown/podman-container-checkpoint.1.md @@ -35,6 +35,14 @@ to import the *container* on another system and thus enabling container live migration. This checkpoint archive also includes all changes to the *container's* root file-system, if not explicitly disabled using **--ignore-rootfs**. +#### **--file-locks** + +Checkpoint a *container* with file locks. If an application running in the container +is using file locks, this OPTION is required during checkpoint and restore. Otherwise +checkpointing *containers* with file locks is expected to fail. If file locks are not +used, this option is ignored.\ +The default is **false**. + #### **--ignore-rootfs** If a checkpoint is exported to a tar.gz file it is possible with the help of **--ignore-rootfs** to explicitly disable including changes to the root file-system into the checkpoint archive file.\ @@ -119,14 +127,6 @@ restore. Defaults to not checkpointing *containers* with established TCP connections.\ The default is **false**. -#### **--file-locks** - -Checkpoint a *container* with file locks. If an application running in the container -is using file locks, this OPTION is required during checkpoint and restore. Otherwise -checkpointing *containers* with file locks is expected to fail. If file locks are not -used, this option is ignored.\ -The default is **false**. - #### **--with-previous** Check out the *container* with previous criu image files in pre-dump. It only works on `runc 1.0-rc3` or `higher`.\ diff --git a/docs/source/markdown/podman-container-clone.1.md b/docs/source/markdown/podman-container-clone.1.md index 52fa023f3..870bf077c 100644 --- a/docs/source/markdown/podman-container-clone.1.md +++ b/docs/source/markdown/podman-container-clone.1.md @@ -11,25 +11,6 @@ podman\-container\-clone - Creates a copy of an existing container ## OPTIONS -#### **--name** - -Set a custom name for the cloned container. The default if not specified is of the syntax: **<ORIGINAL_NAME>-clone** - -#### **--destroy** - -Remove the original container that we are cloning once used to mimic the configuration. - -#### **--cpus** - -Set a number of CPUs for the container that overrides the original containers CPU limits. If none are specified, the original container's Nano CPUs are used. - -This is shorthand -for **--cpu-period** and **--cpu-quota**, so only **--cpus** or either both the **--cpu-period** and **--cpu-quota** options can be set. - -#### **--cpuset-cpus** - -CPUs in which to allow execution (0-3, 0,1). If none are specified, the original container's CPUset is used. - #### **--cpu-period**=*limit* Set the CPU period for the Completely Fair Scheduler (CFS), which is a @@ -43,6 +24,43 @@ https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-c If none is specified, the original container's cpu period is used +#### **--cpu-quota**=*limit* + +Limit the CPU Completely Fair Scheduler (CFS) quota. + +Limit the container's CPU usage. By default, containers run with the full +CPU resource. The limit is a number in microseconds. If a number is provided, +the container will be allowed to use that much CPU time until the CPU period +ends (controllable via **--cpu-period**). + +On some systems, changing the CPU limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error + +If none is specified, the original container's CPU quota are used. + +#### **--cpu-rt-period**=*microseconds* + +Limit the CPU real-time period in microseconds + +Limit the container's Real Time CPU usage. This option tells the kernel to restrict the container's Real Time CPU usage to the period specified. + +This option is not supported on cgroups V2 systems. + +If none is specified, the original container's CPU runtime period is used. + + +#### **--cpu-rt-runtime**=*microseconds* + +Limit the CPU real-time runtime in microseconds. + +Limit the containers Real Time CPU usage. This option tells the kernel to limit the amount of time in a given CPU period Real Time tasks may consume. Ex: +Period of 1,000,000us and Runtime of 950,000us means that this container could consume 95% of available CPU and leave the remaining 5% to normal priority tasks. + +The sum of all runtimes across containers cannot exceed the amount allotted to the parent cgroup. + +This option is not supported on cgroup V2 systems. + #### **--cpu-shares**=*shares* CPU shares (relative weight) @@ -82,6 +100,17 @@ PID container CPU CPU share If none are specified, the original container's CPU shares are used. +#### **--cpus** + +Set a number of CPUs for the container that overrides the original containers CPU limits. If none are specified, the original container's Nano CPUs are used. + +This is shorthand +for **--cpu-period** and **--cpu-quota**, so only **--cpus** or either both the **--cpu-period** and **--cpu-quota** options can be set. + +#### **--cpuset-cpus** + +CPUs in which to allow execution (0-3, 0,1). If none are specified, the original container's CPUset is used. + #### **--cpuset-mems**=*nodes* Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. @@ -92,42 +121,9 @@ two memory nodes. If none are specified, the original container's CPU memory nodes are used. -#### **--cpu-quota**=*limit* - -Limit the CPU Completely Fair Scheduler (CFS) quota. - -Limit the container's CPU usage. By default, containers run with the full -CPU resource. The limit is a number in microseconds. If a number is provided, -the container will be allowed to use that much CPU time until the CPU period -ends (controllable via **--cpu-period**). - -On some systems, changing the CPU limits may not be allowed for non-root -users. For more details, see -https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error - -If none is specified, the original container's CPU quota are used. - -#### **--cpu-rt-period**=*microseconds* - -Limit the CPU real-time period in microseconds - -Limit the container's Real Time CPU usage. This option tells the kernel to restrict the container's Real Time CPU usage to the period specified. - -This option is not supported on cgroups V2 systems. - -If none is specified, the original container's CPU runtime period is used. - - -#### **--cpu-rt-runtime**=*microseconds* - -Limit the CPU real-time runtime in microseconds. - -Limit the containers Real Time CPU usage. This option tells the kernel to limit the amount of time in a given CPU period Real Time tasks may consume. Ex: -Period of 1,000,000us and Runtime of 950,000us means that this container could consume 95% of available CPU and leave the remaining 5% to normal priority tasks. - -The sum of all runtimes across containers cannot exceed the amount allotted to the parent cgroup. +#### **--destroy** -This option is not supported on cgroup V2 systems. +Remove the original container that we are cloning once used to mimic the configuration. #### **--memory**, **-m**=*limit* @@ -141,6 +137,10 @@ system's page size (the value would be very large, that's millions of trillions) If no memory limits are specified, the original container's will be used. +#### **--name** + +Set a custom name for the cloned container. The default if not specified is of the syntax: **<ORIGINAL_NAME>-clone** + #### **--run** When set to true, this flag runs the newly created container after the diff --git a/docs/source/markdown/podman-container-restore.1.md b/docs/source/markdown/podman-container-restore.1.md index 4016eb1cb..5b1bf82c5 100644 --- a/docs/source/markdown/podman-container-restore.1.md +++ b/docs/source/markdown/podman-container-restore.1.md @@ -16,25 +16,14 @@ Restore all checkpointed *containers*.\ The default is **false**.\ *IMPORTANT: This OPTION does not need a container name or ID as input argument.* -#### **--keep**, **-k** +#### **--file-locks** -Keep all temporary log and statistics files created by `CRIU` during -checkpointing as well as restoring. These files are not deleted if restoring -fails for further debugging. If restoring succeeds these files are -theoretically not needed, but if these files are needed Podman can keep the -files for further analysis. This includes the checkpoint directory with all -files created during checkpointing. The size required by the checkpoint -directory is roughly the same as the amount of memory required by the -processes in the checkpointed *container*.\ -Without the **--keep**, **-k** option the checkpoint will be consumed and cannot be used again.\ +Restore a *container* with file locks. This option is required to +restore file locks from a checkpoint image. If the checkpoint image +does not contain file locks, this option is ignored. Defaults to not +restoring file locks.\ The default is **false**. -#### **--latest**, **-l** - -Instead of providing the *container ID* or *name*, use the last created *container*. If other tools than Podman are used to run *containers* such as `CRI-O`, the last started *container* could be from either tool.\ -The default is **false**.\ -*IMPORTANT: This OPTION is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines. This OPTION does not need a container name or ID as input argument.* - #### **--ignore-rootfs** If a *container* is restored from a checkpoint tar.gz file it is possible that it also contains all root file-system changes. With **--ignore-rootfs** it is possible to explicitly disable applying these root file-system changes to the restored *container*.\ @@ -89,6 +78,25 @@ Import a pre-checkpoint tar.gz file which was exported by Podman. This option must be used with **-i** or **--import**. It only works on `runc 1.0-rc3` or `higher`. *IMPORTANT: This OPTION is not supported on the remote client, including Mac and Windows (excluding WSL2) machines.* +#### **--keep**, **-k** + +Keep all temporary log and statistics files created by `CRIU` during +checkpointing as well as restoring. These files are not deleted if restoring +fails for further debugging. If restoring succeeds these files are +theoretically not needed, but if these files are needed Podman can keep the +files for further analysis. This includes the checkpoint directory with all +files created during checkpointing. The size required by the checkpoint +directory is roughly the same as the amount of memory required by the +processes in the checkpointed *container*.\ +Without the **--keep**, **-k** option the checkpoint will be consumed and cannot be used again.\ +The default is **false**. + +#### **--latest**, **-l** + +Instead of providing the *container ID* or *name*, use the last created *container*. If other tools than Podman are used to run *containers* such as `CRI-O`, the last started *container* could be from either tool.\ +The default is **false**.\ +*IMPORTANT: This OPTION is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines. This OPTION does not need a container name or ID as input argument.* + #### **--name**, **-n**=*name* If a *container* is restored from a checkpoint tar.gz file it is possible to rename it with **--name, -n**. This way it is possible to restore a *container* from a checkpoint multiple times with different @@ -149,14 +157,6 @@ option is ignored. Defaults to not restoring *containers* with established TCP connections.\ The default is **false**. -#### **--file-locks** - -Restore a *container* with file locks. This option is required to -restore file locks from a checkpoint image. If the checkpoint image -does not contain file locks, this option is ignored. Defaults to not -restoring file locks.\ -The default is **false**. - ## EXAMPLE Restores the container "mywebserver". ``` diff --git a/docs/source/markdown/podman-container-runlabel.1.md b/docs/source/markdown/podman-container-runlabel.1.md index ac34b232c..40e5392ce 100644 --- a/docs/source/markdown/podman-container-runlabel.1.md +++ b/docs/source/markdown/podman-container-runlabel.1.md @@ -35,10 +35,6 @@ Path of the containers-auth.json(5) file. Default is ${XDG\_RUNTIME\_DIR}/contai Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE environment variable. `export REGISTRY_AUTH_FILE=path` -#### **--display** - -Display the label's value of the image having populated its environment variables. The runlabel command will not execute if --display is specified. - #### **--cert-dir**=*path* Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. (Default: /etc/containers/certs.d) @@ -48,6 +44,10 @@ Please refer to containers-certs.d(5) for details. (This option is not available 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. +#### **--display** + +Display the label's value of the image having populated its environment variables. The runlabel command will not execute if --display is specified. + #### **--help**, **-h** Print usage statement diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index 506f575fe..7ef5cb2d3 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -65,6 +65,7 @@ and specified with a _tag_. $ podman create oci-archive:/tmp/fedora echo hello ## OPTIONS + #### **--add-host**=*host* Add a custom host-to-IP mapping (host:ip) @@ -114,6 +115,14 @@ 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. + +#### **--cgroup-parent**=*path* + +Path to cgroups under which the cgroup for the container will be created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups will be created if they do not already exist. + #### **--cgroupns**=*mode* Set the cgroup namespace mode for the container. @@ -134,13 +143,11 @@ 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*. -#### **--cgroup-parent**=*path* - -Path to cgroups under which the cgroup for the container will be created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups will be created if they do not already exist. - -#### **--cgroup-conf**=*KEY=VALUE* +#### **--chrootdirs**=*path* -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. +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. #### **--cidfile**=*id* @@ -346,14 +353,14 @@ This option allows arbitrary environment variables that are available for the pr See [**Environment**](#environment) note below for precedence and examples. -#### **--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) - #### **--env-file**=*file* 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) + #### **--expose**=*port* Expose a port, or a range of ports (e.g. --expose=3300-3310) to set up port redirection @@ -406,6 +413,10 @@ The initialization time needed for a container to bootstrap. The value can be ex 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`. +#### **--help** + +Print usage statement + #### **--hostname**=*name*, **-h** Container host name @@ -417,10 +428,6 @@ Sets the container host name that is available inside the container. Can only be Add a user account to /etc/passwd from the host to the container. The Username or UID must exist on the host system. -#### **--help** - -Print usage statement - #### **--http-proxy** By default proxy environment variables are passed into the container if set @@ -761,6 +768,16 @@ 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 + #### **--pids-limit**=*limit* Tune the container's pids limit. Set `-1` to have unlimited pids for the container. (default "4096" on systems that support PIDS cgroups). @@ -1077,23 +1094,6 @@ standard input. 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 -#### **--umask**=*umask* - -Set the umask inside the container. Defaults to `0022`. -Remote connections use local containers.conf for defaults - -#### **--unsetenv**=*env* - -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**=*true|false* - -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. - #### **--uidmap**=*container_uid*:*from_uid*:*amount* Run the container in a new user namespace using the supplied mapping. This @@ -1178,6 +1178,23 @@ 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 + +#### **--unsetenv**=*env* + +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**=*true|false* + +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. + #### **--user**, **-u**=*user* Sets the username or UID used and optionally the groupname or GID for the specified command. @@ -1443,22 +1460,6 @@ The default working directory for running binaries within a container is the roo The image developer can set a different default with the WORKDIR instruction. The operator can override the working directory by using the **-w** option. -#### **--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 - -#### **--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. - ## EXAMPLES ### Create a container using a local image diff --git a/docs/source/markdown/podman-events.1.md b/docs/source/markdown/podman-events.1.md index 7ca52e3e9..741aca3a5 100644 --- a/docs/source/markdown/podman-events.1.md +++ b/docs/source/markdown/podman-events.1.md @@ -70,15 +70,6 @@ The *volume* type will report the following statuses: ## OPTIONS -#### **--help** - -Print usage statement. - -#### **--format** - -Format the output to JSON Lines or using the given Go template. - - #### **--filter**=*filter* Filter events that are displayed. They must be in the format of "filter=value". The following @@ -93,6 +84,14 @@ filters are supported: In the case where an ID is used, the ID may be in its full or shortened form. +#### **--format** + +Format the output to JSON Lines or using the given Go template. + +#### **--help** + +Print usage statement. + #### **--no-trunc** Do not truncate the output (default *true*). diff --git a/docs/source/markdown/podman-export.1.md b/docs/source/markdown/podman-export.1.md index b2ad4e907..53d7e425e 100644 --- a/docs/source/markdown/podman-export.1.md +++ b/docs/source/markdown/podman-export.1.md @@ -24,14 +24,14 @@ Note: `:` is a restricted character and cannot be part of the file name. ## OPTIONS -#### **--output**, **-o** - -Write to a file, default is STDOUT - #### **--help**, **-h** Print usage statement +#### **--output**, **-o** + +Write to a file, default is STDOUT + ## EXAMPLES ``` diff --git a/docs/source/markdown/podman-generate-systemd.1.md b/docs/source/markdown/podman-generate-systemd.1.md index b2b5ee2ca..32d5d2bc4 100644 --- a/docs/source/markdown/podman-generate-systemd.1.md +++ b/docs/source/markdown/podman-generate-systemd.1.md @@ -16,6 +16,16 @@ _Note: If you use this command with the remote client, including Mac and Windows ## OPTIONS +#### **--after**=*dependency_name* + +Add the systemd unit after (`After=`) option, that ordering dependencies between the list of dependencies and this service. This option may be specified more than once. + +User-defined dependencies will be appended to the generated unit file, but any existing options such as needed or defined by default (e.g. `online.target`) will **not** be removed or overridden. + +#### **--container-prefix**=*prefix* + +Set the systemd unit name prefix for containers. The default is *container*. + #### **--files**, **-f** Generate files instead of printing to stdout. The generated files are named {container,pod}-{ID,name}.service and will be placed in the current working directory. @@ -40,13 +50,13 @@ Note that `--new` only works on containers and pods created directly via Podman Do not generate the header including meta data such as the Podman version and the timestamp. -#### **--start-timeout** =*value* +#### **--pod-prefix**=*prefix* -Override the default start timeout for the container with the given value in seconds. +Set the systemd unit name prefix for pods. The default is *pod*. -#### **--stop-timeout** =*value* +#### **--requires**=*dependency_name* -Override the default stop timeout for the container with the given value in seconds. +Set the systemd unit requires (`Requires=`) option. Similar to wants, but declares a stronger requirement dependency. #### **--restart-policy**=*policy* @@ -58,33 +68,17 @@ Set the systemd restart policy. The restart-policy must be one of: "no", "on-su Set the systemd service restartsec value. Configures the time to sleep before restarting a service (as configured with restart-policy). Takes a value in seconds. -#### **--container-prefix**=*prefix* - -Set the systemd unit name prefix for containers. The default is *container*. - -#### **--pod-prefix**=*prefix* - -Set the systemd unit name prefix for pods. The default is *pod*. - #### **--separator**=*separator* Set the systemd unit name separator between the name/id of a container/pod and the prefix. The default is *-*. -#### **--wants**=*dependency_name* - -Add the systemd unit wants (`Wants=`) option, that this service is (weak) dependent on. This option may be specified more than once. This option does not influence the order in which services are started or stopped. - -User-defined dependencies will be appended to the generated unit file, but any existing options such as needed or defined by default (e.g. `online.target`) will **not** be removed or overridden. - -#### **--after**=*dependency_name* - -Add the systemd unit after (`After=`) option, that ordering dependencies between the list of dependencies and this service. This option may be specified more than once. +#### **--start-timeout** =*value* -User-defined dependencies will be appended to the generated unit file, but any existing options such as needed or defined by default (e.g. `online.target`) will **not** be removed or overridden. +Override the default start timeout for the container with the given value in seconds. -#### **--requires**=*dependency_name* +#### **--stop-timeout** =*value* -Set the systemd unit requires (`Requires=`) option. Similar to wants, but declares a stronger requirement dependency. +Override the default stop timeout for the container with the given value in seconds. #### **--template** @@ -92,6 +86,12 @@ Add template specifiers to run multiple services from the systemd unit file. Note that if `--new` was not set to true, it is set to true by default. However, if `--new` is set to `false` explicitly the command will fail. +#### **--wants**=*dependency_name* + +Add the systemd unit wants (`Wants=`) option, that this service is (weak) dependent on. This option may be specified more than once. This option does not influence the order in which services are started or stopped. + +User-defined dependencies will be appended to the generated unit file, but any existing options such as needed or defined by default (e.g. `online.target`) will **not** be removed or overridden. + ## EXAMPLES ### Generate and print a systemd unit file for a container diff --git a/docs/source/markdown/podman-history.1.md b/docs/source/markdown/podman-history.1.md index 4ab2547ea..af35814c2 100644 --- a/docs/source/markdown/podman-history.1.md +++ b/docs/source/markdown/podman-history.1.md @@ -29,6 +29,15 @@ Valid placeholders for the Go template are listed below: ## OPTIONS +Print the numeric IDs only (default *false*). +#### **--format**=*format* + +Alter the output for a format like 'json' or a Go template. + +#### **--help**, **-h** + +Print usage statement + #### **--human**, **-H** Display sizes and dates in human readable format (default *true*). @@ -39,15 +48,6 @@ Do not truncate the output (default *false*). #### **--quiet**, **-q** -Print the numeric IDs only (default *false*). -#### **--format**=*format* - -Alter the output for a format like 'json' or a Go template. - -#### **--help**, **-h** - -Print usage statement - ## EXAMPLES ``` diff --git a/docs/source/markdown/podman-image-scp.1.md b/docs/source/markdown/podman-image-scp.1.md index e08d5b465..1d902da91 100644 --- a/docs/source/markdown/podman-image-scp.1.md +++ b/docs/source/markdown/podman-image-scp.1.md @@ -20,14 +20,14 @@ Note: `::` is used to specify the image name depending on if you are saving or l ## OPTIONS -#### **--quiet**, **-q** - -Suppress the output - #### **--help**, **-h** Print usage statement +#### **--quiet**, **-q** + +Suppress the output + ## EXAMPLES diff --git a/docs/source/markdown/podman-image-sign.1.md b/docs/source/markdown/podman-image-sign.1.md index 7e483a3b2..035e10743 100644 --- a/docs/source/markdown/podman-image-sign.1.md +++ b/docs/source/markdown/podman-image-sign.1.md @@ -15,10 +15,6 @@ By default, the signature will be written into `/var/lib/containers/sigstore` fo ## OPTIONS -#### **--help**, **-h** - -Print usage statement. - #### **--all**, **-a** Sign all the manifests of the multi-architecture image (default false). @@ -39,6 +35,10 @@ Please refer to containers-certs.d(5) for details. (This option is not available Store the signatures in the specified directory. Default: /var/lib/containers/sigstore +#### **--help**, **-h** + +Print usage statement. + #### **--sign-by**=*identity* Override the default identity of the signature. diff --git a/docs/source/markdown/podman-images.1.md b/docs/source/markdown/podman-images.1.md index f1d9d4816..f81ea5a20 100644 --- a/docs/source/markdown/podman-images.1.md +++ b/docs/source/markdown/podman-images.1.md @@ -73,14 +73,14 @@ Valid placeholders for the Go template are listed below: Display the history of image names. If an image gets re-tagged or untagged, then the image name history gets prepended (latest image first). This is especially useful when undoing a tag operation or an image does not contain any name because it has been untagged. -#### **--noheading**, **-n** - -Omit the table headings from the listing of images. - #### **--no-trunc** Do not truncate the output (default *false*). +#### **--noheading**, **-n** + +Omit the table headings from the listing of images. + #### **--quiet**, **-q** Lists only the image IDs. diff --git a/docs/source/markdown/podman-import.1.md b/docs/source/markdown/podman-import.1.md index a79b6cfdd..bfe0291de 100644 --- a/docs/source/markdown/podman-import.1.md +++ b/docs/source/markdown/podman-import.1.md @@ -30,6 +30,10 @@ Apply the following possible instructions to the created image: Can be set multiple times +#### **--help**, **-h** + +Print usage statement + #### **--message**, **-m**=*message* Set commit message for imported image @@ -50,10 +54,6 @@ Set variant of the imported image. Print additional debugging information -#### **--help**, **-h** - -Print usage statement - ## EXAMPLES ``` diff --git a/docs/source/markdown/podman-inspect.1.md b/docs/source/markdown/podman-inspect.1.md index 9eafb7460..a67604ab5 100644 --- a/docs/source/markdown/podman-inspect.1.md +++ b/docs/source/markdown/podman-inspect.1.md @@ -22,11 +22,6 @@ For more inspection options, see also ## OPTIONS -#### **--type**, **-t**=*type* - -Return JSON for the specified type. Type can be 'container', 'image', 'volume', 'network', 'pod', or 'all' (default: all) -(Only meaningful when invoked as *podman inspect*) - #### **--format**, **-f**=*format* Format the output using the given Go template. @@ -43,6 +38,10 @@ This option can be used to inspect the latest pod created when used with --type In addition to normal output, display the total file size if the type is a container. +#### **--type**, **-t**=*type* + +Return JSON for the specified type. Type can be 'container', 'image', 'volume', 'network', 'pod', or 'all' (default: all) +(Only meaningful when invoked as *podman inspect*) ## EXAMPLE diff --git a/docs/source/markdown/podman-load.1.md b/docs/source/markdown/podman-load.1.md index 30e8e82ea..ad32df854 100644 --- a/docs/source/markdown/podman-load.1.md +++ b/docs/source/markdown/podman-load.1.md @@ -26,6 +26,10 @@ Note: `:` is a restricted character and cannot be part of the file name. ## OPTIONS +#### **--help**, **-h** + +Print usage statement + #### **--input**, **-i**=*input* Load the specified input file instead of from stdin. The file can be on the local file system or on a server (e.g., https://server.com/archive.tar) @@ -38,10 +42,6 @@ NOTE: Use the environment variable `TMPDIR` to change the temporary storage loca Suppress the progress output -#### **--help**, **-h** - -Print usage statement - ## EXAMPLES ``` diff --git a/docs/source/markdown/podman-logout.1.md b/docs/source/markdown/podman-logout.1.md index e34c80e95..96ac98f35 100644 --- a/docs/source/markdown/podman-logout.1.md +++ b/docs/source/markdown/podman-logout.1.md @@ -21,6 +21,10 @@ All the cached credentials can be removed by setting the **all** flag. ## OPTIONS +#### **--all**, **-a** + +Remove the cached credentials for all registries in the auth file + #### **--authfile**=*path* Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json. @@ -28,10 +32,6 @@ Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE environment variable. `export REGISTRY_AUTH_FILE=path` -#### **--all**, **-a** - -Remove the cached credentials for all registries in the auth file - #### **--help**, **-h** Print usage statement diff --git a/docs/source/markdown/podman-logs.1.md b/docs/source/markdown/podman-logs.1.md index f62a66c81..e12042030 100644 --- a/docs/source/markdown/podman-logs.1.md +++ b/docs/source/markdown/podman-logs.1.md @@ -39,14 +39,6 @@ strings (e.g. 10m, 1h30m) computed relative to the client machine's time. Suppor time stamps include RFC3339Nano, RFC3339, 2006-01-02T15:04:05, 2006-01-02T15:04:05.999999999, 2006-01-02Z07:00, and 2006-01-02. -#### **--until**=*TIMESTAMP* - -Show logs until TIMESTAMP. The --until option can be Unix timestamps, date formatted timestamps, or Go duration -strings (e.g. 10m, 1h30m) computed relative to the client machine's time. Supported formats for date formatted -time stamps include RFC3339Nano, RFC3339, 2006-01-02T15:04:05, 2006-01-02T15:04:05.999999999, 2006-01-02Z07:00, -and 2006-01-02. - - #### **--tail**=*LINES* Output the specified number of LINES at the end of the logs. LINES must be an integer. Defaults to -1, @@ -56,6 +48,13 @@ which prints all lines Show timestamps in the log outputs. The default is false +#### **--until**=*TIMESTAMP* + +Show logs until TIMESTAMP. The --until option can be Unix timestamps, date formatted timestamps, or Go duration +strings (e.g. 10m, 1h30m) computed relative to the client machine's time. Supported formats for date formatted +time stamps include RFC3339Nano, RFC3339, 2006-01-02T15:04:05, 2006-01-02T15:04:05.999999999, 2006-01-02Z07:00, +and 2006-01-02. + ## EXAMPLE To view a container's logs: diff --git a/docs/source/markdown/podman-machine-init.1.md b/docs/source/markdown/podman-machine-init.1.md index 36db5b1cd..ac258eaae 100644 --- a/docs/source/markdown/podman-machine-init.1.md +++ b/docs/source/markdown/podman-machine-init.1.md @@ -32,6 +32,10 @@ Number of CPUs. Size of the disk for the guest VM in GB. +#### **--help** + +Print usage statement. + #### **--ignition-path** Fully qualified path of the ignition file. @@ -83,10 +87,6 @@ so mounts must be created under the /mnt directory. Driver to use for mounting volumes from the host, such as `virtfs`. -#### **--help** - -Print usage statement. - ## EXAMPLES ``` diff --git a/docs/source/markdown/podman-machine-rm.1.md b/docs/source/markdown/podman-machine-rm.1.md index c9c68d111..4a2c59173 100644 --- a/docs/source/markdown/podman-machine-rm.1.md +++ b/docs/source/markdown/podman-machine-rm.1.md @@ -19,14 +19,14 @@ is used. ## OPTIONS -#### **--help** - -Print usage statement. - #### **--force**, **-f** Stop and delete without confirmation. +#### **--help** + +Print usage statement. + #### **--save-ignition** Do not delete the generated ignition file. diff --git a/docs/source/markdown/podman-machine-set.1.md b/docs/source/markdown/podman-machine-set.1.md index e69779564..ec89cfc28 100644 --- a/docs/source/markdown/podman-machine-set.1.md +++ b/docs/source/markdown/podman-machine-set.1.md @@ -15,6 +15,10 @@ subset can be changed after machine initialization. ## OPTIONS +#### **--help** + +Print usage statement. + #### **--rootful**=*true|false* Whether this machine should prefer rootful (`true`) or rootless (`false`) @@ -24,10 +28,6 @@ machine name (or `podman-machine-default` if no name is specified). API forwarding, if available, will follow this setting. -#### **--help** - -Print usage statement. - ## EXAMPLES To switch the default VM `podman-machine-default` from rootless to rootful: diff --git a/docs/source/markdown/podman-manifest-push.1.md b/docs/source/markdown/podman-manifest-push.1.md index a0011cea8..22e8cae9a 100644 --- a/docs/source/markdown/podman-manifest-push.1.md +++ b/docs/source/markdown/podman-manifest-push.1.md @@ -50,14 +50,14 @@ Manifest list type (oci or v2s2) to use when pushing the list (default is oci). When writing the manifest, suppress progress output -#### **--rm** - -Delete the manifest list or image index from local storage if pushing succeeds. - #### **--remove-signatures** Don't copy signatures when pushing images. +#### **--rm** + +Delete the manifest list or image index from local storage if pushing succeeds. + #### **--sign-by**=*fingerprint* Sign the pushed images using the GPG key that matches the specified fingerprint. diff --git a/docs/source/markdown/podman-network-create.1.md b/docs/source/markdown/podman-network-create.1.md index 5a3224501..479c36318 100644 --- a/docs/source/markdown/podman-network-create.1.md +++ b/docs/source/markdown/podman-network-create.1.md @@ -32,21 +32,6 @@ Special considerations for the *netavark* backend: - The `macvlan` driver requires the `--subnet` option, DHCP is currently not supported. - The `ipvlan` driver is not currently supported. -#### **--opt**=*option*, **-o** - -Set driver specific options. - -All drivers accept the `mtu` option. The `mtu` option sets the Maximum Transmission Unit (MTU) and takes an integer value. - -Additionally the `bridge` driver supports the following option: -- `vlan`: This option assign VLAN tag and enables vlan\_filtering. Defaults to none. - -The `macvlan` and `ipvlan` driver support the following options: -- `parent`: The host device which should be used for the macvlan interface. Defaults to the default route interface. -- `mode`: This option sets the specified ip/macvlan mode on the interface. - - Supported values for `macvlan` are `bridge`, `private`, `vepa`, `passthru`. Defaults to `bridge`. - - Supported values for `ipvlan` are `l2`, `l3`, `l3s`. Defaults to `l2`. - #### **--gateway** Define a gateway for the subnet. If you want to provide a gateway address, you must also provide a @@ -64,20 +49,35 @@ Allocate container IP from a range. The range must be a complete subnet and in must be used with a *subnet* option. Can be specified multiple times. The argument order of the **--subnet**, **--gateway** and **--ip-range** options must match. +#### **--ipv6** + +Enable IPv6 (Dual Stack) networking. If not subnets are given it will allocate a ipv4 and ipv6 subnet. + #### **--label** Set metadata for a network (e.g., --label mykey=value). +#### **--opt**=*option*, **-o** + +Set driver specific options. + +All drivers accept the `mtu` option. The `mtu` option sets the Maximum Transmission Unit (MTU) and takes an integer value. + +Additionally the `bridge` driver supports the following option: +- `vlan`: This option assign VLAN tag and enables vlan\_filtering. Defaults to none. + +The `macvlan` and `ipvlan` driver support the following options: +- `parent`: The host device which should be used for the macvlan interface. Defaults to the default route interface. +- `mode`: This option sets the specified ip/macvlan mode on the interface. + - Supported values for `macvlan` are `bridge`, `private`, `vepa`, `passthru`. Defaults to `bridge`. + - Supported values for `ipvlan` are `l2`, `l3`, `l3s`. Defaults to `l2`. + #### **--subnet** The subnet in CIDR notation. Can be specified multiple times to allocate more than one subnet for this network. The argument order of the **--subnet**, **--gateway** and **--ip-range** options must match. This is useful to set a static ipv4 and ipv6 subnet. -#### **--ipv6** - -Enable IPv6 (Dual Stack) networking. If not subnets are given it will allocate a ipv4 and ipv6 subnet. - ## EXAMPLE Create a network with no options. diff --git a/docs/source/markdown/podman-network-ls.1.md b/docs/source/markdown/podman-network-ls.1.md index d5bdb6a39..b341083f9 100644 --- a/docs/source/markdown/podman-network-ls.1.md +++ b/docs/source/markdown/podman-network-ls.1.md @@ -54,14 +54,14 @@ Valid placeholders for the Go template are listed below: | .NetworkInterface | Name of the network interface on the host | | .Subnets | List of subnets on this network | -#### **--noheading** - -Omit the table headings from the listing of networks. - #### **--no-trunc** Do not truncate the network ID. +#### **--noheading** + +Omit the table headings from the listing of networks. + #### **--quiet**, **-q** The `quiet` option will restrict the output to only the network names. diff --git a/docs/source/markdown/podman-network-prune.1.md b/docs/source/markdown/podman-network-prune.1.md index a1dc5d85c..2c8cf13db 100644 --- a/docs/source/markdown/podman-network-prune.1.md +++ b/docs/source/markdown/podman-network-prune.1.md @@ -12,9 +12,6 @@ has no containers connected or configured to connect to it. It will not remove the so-called default network which goes by the name of *podman*. ## OPTIONS -#### **--force**, **-f** - -Do not prompt for confirmation #### **--filter** @@ -33,6 +30,10 @@ The `label` *filter* accepts two formats. One is the `label`=*key* or `label`=*k The `until` *filter* can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. 10m, 1h30m) computed relative to the machine’s time. +#### **--force**, **-f** + +Do not prompt for confirmation + ## EXAMPLE Prune networks diff --git a/docs/source/markdown/podman-play-kube.1.md b/docs/source/markdown/podman-play-kube.1.md index 310bade34..ad3bd421d 100644 --- a/docs/source/markdown/podman-play-kube.1.md +++ b/docs/source/markdown/podman-play-kube.1.md @@ -148,6 +148,10 @@ value can be entered. The password is entered without echo. Tears down the pods that were created by a previous run of `play kube`. The pods are stopped and then removed. Any volumes created are left intact. +#### **--help**, **-h** + +Print usage statement + #### **--ip**=*IP address* Assign a static ip address to the pod. This option can be specified several times when play kube creates more than one pod. @@ -236,10 +240,6 @@ Require HTTPS and verify certificates when contacting registries (default: true) then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. -#### **--help**, **-h** - -Print usage statement - ## EXAMPLES Recreate the pod and containers as described in a file called `demo.yml` diff --git a/docs/source/markdown/podman-pod-create.1.md b/docs/source/markdown/podman-pod-create.1.md index 8088e1d62..2ae4453c9 100644 --- a/docs/source/markdown/podman-pod-create.1.md +++ b/docs/source/markdown/podman-pod-create.1.md @@ -75,21 +75,6 @@ Set custom DNS search domains in the /etc/resolv.conf file that will be shared b GID map for the user namespace. Using this flag will run the container with user namespace enabled. It conflicts with the `--userns` and `--subgidname` flags. -#### **--uidmap**=*container_uid*:*from_uid*:*amount* - -Run the container in a new user namespace using the supplied mapping. This -option conflicts with the **--userns** and **--subuidname** options. This -option provides a way to map host UIDs to container UIDs. It can be passed -several times to map different ranges. - -#### **--subgidname**=*name* - -Name for GID map from the `/etc/subgid` file. Using this flag will run the container with user namespace enabled. This flag conflicts with `--userns` and `--gidmap`. - -#### **--subuidname**=*name* - -Name for UID map from the `/etc/subuid` file. Using this flag will run the container with user namespace enabled. This flag conflicts with `--userns` and `--uidmap`. - #### **--help**, **-h** Print usage statement. @@ -102,14 +87,14 @@ Set a hostname to the pod Create an infra container and associate it with the pod. An infra container is a lightweight container used to coordinate the shared kernel namespace of a pod. Default: true. -#### **--infra-conmon-pidfile**=*file* - -Write the pid of the infra container's **conmon** process to a file. As **conmon** runs in a separate process than Podman, this is necessary when using systemd to manage Podman containers and pods. - #### **--infra-command**=*command* The command that will be run to start the infra container. Default: "/pause". +#### **--infra-conmon-pidfile**=*file* + +Write the pid of the infra container's **conmon** process to a file. As **conmon** runs in a separate process than Podman, this is necessary when using systemd to manage Podman containers and pods. + #### **--infra-image**=*image* The custom image that will be used for the infra container. Unless specified, Podman builds a custom local image which does not require pulling down an image. @@ -282,6 +267,14 @@ This boolean determines whether or not all containers entering the pod will use Note: This options conflict with **--share=cgroup** since that would set the pod as the cgroup parent but enter the container into the same cgroupNS as the infra container. +#### **--subgidname**=*name* + +Name for GID map from the `/etc/subgid` file. Using this flag will run the container with user namespace enabled. This flag conflicts with `--userns` and `--gidmap`. + +#### **--subuidname**=*name* + +Name for UID map from the `/etc/subuid` file. Using this flag will run the container with user namespace enabled. This flag conflicts with `--userns` and `--uidmap`. + #### **--sysctl**=_name_=_value_ Configure namespace kernel parameters for all containers in the pod. @@ -304,6 +297,13 @@ For the network namespace, only sysctls beginning with net.\* are allowed. Note: if the network namespace is not shared within the pod, these sysctls are not allowed. +#### **--uidmap**=*container_uid*:*from_uid*:*amount* + +Run the container in a new user namespace using the supplied mapping. This +option conflicts with the **--userns** and **--subuidname** options. This +option provides a way to map host UIDs to container UIDs. It can be passed +several times to map different ranges. + #### **--userns**=*mode* 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. diff --git a/docs/source/markdown/podman-pod-inspect.1.md b/docs/source/markdown/podman-pod-inspect.1.md index 75b422306..3105ebaab 100644 --- a/docs/source/markdown/podman-pod-inspect.1.md +++ b/docs/source/markdown/podman-pod-inspect.1.md @@ -11,10 +11,6 @@ Displays configuration and state information about a given pod. It also display that belong to the pod. ## OPTIONS -#### **--latest**, **-l** - -Instead of providing the pod name or ID, use the last created pod. If you use methods other than Podman -to run pods such as CRI-O, the last started pod could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) #### **--format**=*format*, **-f** @@ -39,6 +35,11 @@ Valid placeholders for the Go template are listed below: | .NumContainers | Number of containers in the pod | | .Containers | Pod containers | +#### **--latest**, **-l** + +Instead of providing the pod name or ID, use the last created pod. If you use methods other than Podman +to run pods such as CRI-O, the last started pod could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + ## EXAMPLE ``` # podman pod inspect foobar diff --git a/docs/source/markdown/podman-pod-logs.1.md b/docs/source/markdown/podman-pod-logs.1.md index 880853000..5ef667504 100644 --- a/docs/source/markdown/podman-pod-logs.1.md +++ b/docs/source/markdown/podman-pod-logs.1.md @@ -39,14 +39,6 @@ strings (e.g. 10m, 1h30m) computed relative to the client machine's time. Suppor time stamps include RFC3339Nano, RFC3339, 2006-01-02T15:04:05, 2006-01-02T15:04:05.999999999, 2006-01-02Z07:00, and 2006-01-02. -#### **--until**=*TIMESTAMP* - -Show logs until TIMESTAMP. The --until option can be Unix timestamps, date formatted timestamps, or Go duration -strings (e.g. 10m, 1h30m) computed relative to the client machine's time. Supported formats for date formatted -time stamps include RFC3339Nano, RFC3339, 2006-01-02T15:04:05, 2006-01-02T15:04:05.999999999, 2006-01-02Z07:00, -and 2006-01-02. - - #### **--tail**=*LINES* Output the specified number of LINES at the end of the logs. LINES must be an integer. Defaults to -1, @@ -56,6 +48,13 @@ which prints all lines Show timestamps in the log outputs. The default is false +#### **--until**=*TIMESTAMP* + +Show logs until TIMESTAMP. The --until option can be Unix timestamps, date formatted timestamps, or Go duration +strings (e.g. 10m, 1h30m) computed relative to the client machine's time. Supported formats for date formatted +time stamps include RFC3339Nano, RFC3339, 2006-01-02T15:04:05, 2006-01-02T15:04:05.999999999, 2006-01-02Z07:00, +and 2006-01-02. + ## EXAMPLE To view a pod's logs: diff --git a/docs/source/markdown/podman-pod-ps.1.md b/docs/source/markdown/podman-pod-ps.1.md index 8a9c3f7cc..34f49173a 100644 --- a/docs/source/markdown/podman-pod-ps.1.md +++ b/docs/source/markdown/podman-pod-ps.1.md @@ -28,37 +28,48 @@ By default it lists: ## OPTIONS -#### **--ctr-names** - -Display the container names - #### **--ctr-ids** Display the container IDs +#### **--ctr-names** + +Display the container names + #### **--ctr-status** Display the container statuses -#### **--latest**, **-l** +#### **--filter**, **-f**=*filter* -Show the latest pod created (all states) (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) +Provide filter values. -#### **--noheading** +The *filters* argument format is of `key=value`. If there is more than one *filter*, then pass multiple OPTIONS: **--filter** *foo=bar* **--filter** *bif=baz*. -Omit the table headings from the listing of pods. +Supported filters: -#### **--no-trunc** +| Filter | Description | +| ---------- | -------------------------------------------------------------------------------------------------- | +| *ctr-ids* | Filter by container ID within the pod. | +| *ctr-names* | Filter by container name within the pod. | +| *ctr-number*| Filter by number of containers in the pod. | +| *ctr-status*| Filter by container status within the pod. | +| *id* | Filter by pod ID. | +| *label* | Filter by container with (or without, in the case of label!=[...] is used) the specified labels. | +| *name* | Filter by pod name. | +| *network* | Filter by network name or full ID of network. | +| *status* | Filter by pod status. | +| *until* | Filter by pods created before given timestamp. | -Do not truncate the output (default *false*). +The `ctr-ids`, `ctr-names`, `id`, `name` filters accept `regex` format. -#### **--ns** +The `ctr-status` filter accepts values: `created`, `running`, `paused`, `stopped`, `exited`, `unknown`. -Display namespace information of the pod +The `label` *filter* accepts two formats. One is the `label`=*key* or `label`=*key*=*value*, which removes containers with the specified labels. The other format is the `label!`=*key* or `label!`=*key*=*value*, which removes containers without the specified labels. -#### **--quiet**, **-q** +The `until` *filter* can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. 10m, 1h30m) computed relative to the machine’s time. -Print the numeric IDs of the pods only +The `status` filter accepts values: `stopped`, `running`, `paused`, `exited`, `dead`, `created`, `degraded`. #### **--format**=*format* @@ -78,47 +89,35 @@ Valid placeholders for the Go template are listed below: | .InfraID | Pod infra container ID | | .Networks | Show all networks connected to the infra container | -#### **--sort** - -Sort by created, ID, name, status, or number of containers +#### **--help**, **-h** -Default: created +Print usage statement -#### **--filter**, **-f**=*filter* +#### **--latest**, **-l** -Provide filter values. +Show the latest pod created (all states) (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) -The *filters* argument format is of `key=value`. If there is more than one *filter*, then pass multiple OPTIONS: **--filter** *foo=bar* **--filter** *bif=baz*. +#### **--no-trunc** -Supported filters: +Do not truncate the output (default *false*). -| Filter | Description | -| ---------- | -------------------------------------------------------------------------------------------------- | -| *ctr-ids* | Filter by container ID within the pod. | -| *ctr-names* | Filter by container name within the pod. | -| *ctr-number*| Filter by number of containers in the pod. | -| *ctr-status*| Filter by container status within the pod. | -| *id* | Filter by pod ID. | -| *label* | Filter by container with (or without, in the case of label!=[...] is used) the specified labels. | -| *name* | Filter by pod name. | -| *network* | Filter by network name or full ID of network. | -| *status* | Filter by pod status. | -| *until* | Filter by pods created before given timestamp. | +#### **--noheading** -The `ctr-ids`, `ctr-names`, `id`, `name` filters accept `regex` format. +Omit the table headings from the listing of pods. -The `ctr-status` filter accepts values: `created`, `running`, `paused`, `stopped`, `exited`, `unknown`. +#### **--ns** -The `label` *filter* accepts two formats. One is the `label`=*key* or `label`=*key*=*value*, which removes containers with the specified labels. The other format is the `label!`=*key* or `label!`=*key*=*value*, which removes containers without the specified labels. +Display namespace information of the pod -The `until` *filter* can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. 10m, 1h30m) computed relative to the machine’s time. +#### **--quiet**, **-q** -The `status` filter accepts values: `stopped`, `running`, `paused`, `exited`, `dead`, `created`, `degraded`. +Print the numeric IDs of the pods only +#### **--sort** -#### **--help**, **-h** +Sort by created, ID, name, status, or number of containers -Print usage statement +Default: created ## EXAMPLES diff --git a/docs/source/markdown/podman-pod-rm.1.md b/docs/source/markdown/podman-pod-rm.1.md index ed33c5e57..75a44c6d4 100644 --- a/docs/source/markdown/podman-pod-rm.1.md +++ b/docs/source/markdown/podman-pod-rm.1.md @@ -15,6 +15,10 @@ podman\-pod\-rm - Remove one or more stopped pods and containers Remove all pods. Can be used in conjunction with \-f as well. +#### **--force**, **-f** + +Stop running containers and delete all stopped containers before removal of pod. + #### **--ignore**, **-i** Ignore errors when specified pods are not in the container store. A user might @@ -25,10 +29,6 @@ ExecStop directive of a systemd service referencing that pod. Instead of providing the pod name or ID, remove the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) -#### **--force**, **-f** - -Stop running containers and delete all stopped containers before removal of pod. - #### **--pod-id-file** Read pod ID from the specified file and remove the pod. Can be specified multiple times. diff --git a/docs/source/markdown/podman-pod-stats.1.md b/docs/source/markdown/podman-pod-stats.1.md index 460571add..389540fdf 100644 --- a/docs/source/markdown/podman-pod-stats.1.md +++ b/docs/source/markdown/podman-pod-stats.1.md @@ -15,18 +15,6 @@ Display a live stream of containers in one or more pods resource usage statistic Show all containers. Only running containers are shown by default -#### **--latest**, **-l** - -Instead of providing the pod name or ID, use the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--no-reset** - -Do not clear the terminal/screen in between reporting intervals - -#### **--no-stream** - -Disable streaming pod stats and only pull the first result, default setting is false - #### **--format**=*template* Pretty-print container statistics to JSON or using a Go template @@ -47,6 +35,19 @@ Valid placeholders for the Go template are listed below: | .PIDS | Number of PIDs | When using a GO template, you may precede the format with `table` to print headers. + +#### **--latest**, **-l** + +Instead of providing the pod name or ID, use the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +#### **--no-reset** + +Do not clear the terminal/screen in between reporting intervals + +#### **--no-stream** + +Disable streaming pod stats and only pull the first result, default setting is false + ## EXAMPLE ``` diff --git a/docs/source/markdown/podman-pod-stop.1.md b/docs/source/markdown/podman-pod-stop.1.md index 13d86d1db..bded0ba7d 100644 --- a/docs/source/markdown/podman-pod-stop.1.md +++ b/docs/source/markdown/podman-pod-stop.1.md @@ -25,14 +25,14 @@ ExecStop directive of a systemd service referencing that pod. Instead of providing the pod name or ID, stop the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) -#### **--time**, **-t**=*seconds* - -Seconds to wait before forcibly stopping the containers in the pod. - #### **--pod-id-file** Read pod ID from the specified file and stop the pod. Can be specified multiple times. +#### **--time**, **-t**=*seconds* + +Seconds to wait before forcibly stopping the containers in the pod. + ## EXAMPLE Stop a pod called *mywebserverpod* diff --git a/docs/source/markdown/podman-ps.1.md b/docs/source/markdown/podman-ps.1.md index 5b142d283..6e2a8616c 100644 --- a/docs/source/markdown/podman-ps.1.md +++ b/docs/source/markdown/podman-ps.1.md @@ -100,14 +100,14 @@ Show the latest container created (all states) (This option is not available wit Display namespace information -#### **--noheading** - -Omit the table headings from the listing of containers. - #### **--no-trunc** Do not truncate the output (default *false*). +#### **--noheading** + +Omit the table headings from the listing of containers. + #### **--pod**, **-p** Display the pods the containers are associated with @@ -116,15 +116,15 @@ Display the pods the containers are associated with Print the numeric IDs of the containers only +#### **--size**, **-s** + +Display the total file size + #### **--sort**=*created* Sort by command, created, id, image, names, runningfor, size, or status", Note: Choosing size will sort by size of rootFs, not alphabetically like the rest of the options -#### **--size**, **-s** - -Display the total file size - #### **--sync** Force a sync of container state with the OCI runtime. diff --git a/docs/source/markdown/podman-push.1.md b/docs/source/markdown/podman-push.1.md index c71eecfd2..74555c11b 100644 --- a/docs/source/markdown/podman-push.1.md +++ b/docs/source/markdown/podman-push.1.md @@ -55,12 +55,6 @@ If the authorization state is not found there, $HOME/.docker/config.json is chec Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE environment variable. `export REGISTRY_AUTH_FILE=path` -#### **--creds**=*[username[:password]]* - -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. - #### **--cert-dir**=*path* Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. (Default: /etc/containers/certs.d) @@ -75,6 +69,12 @@ Note: This flag can only be set when using the **dir** transport Specifies the compression format to use. Supported values are: `gzip`, `zstd` and `zstd:chunked`. The default is `gzip`. +#### **--creds**=*[username[:password]]* + +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. + #### **--digestfile** *Digestfile* After copying the image, write the digest of the resulting image to the file. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) diff --git a/docs/source/markdown/podman-rm.1.md b/docs/source/markdown/podman-rm.1.md index 23944270c..1fac3aa34 100644 --- a/docs/source/markdown/podman-rm.1.md +++ b/docs/source/markdown/podman-rm.1.md @@ -18,14 +18,14 @@ Running or unusable containers will not be removed without the **-f** option. Remove all containers. Can be used in conjunction with **-f** as well. -#### **--depend** - -Remove selected container and recursively remove all containers that depend on it. - #### **--cidfile** Read container ID from the specified file and remove the container. Can be specified multiple times. +#### **--depend** + +Remove selected container and recursively remove all containers that depend on it. + #### **--force**, **-f** Force the removal of running and paused containers. Forcing a container removal also diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index 7fa7bda30..ffe84e287 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -130,6 +130,14 @@ 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. + +#### **--cgroup-parent**=*path* + +Path to cgroups under which the cgroup for the container will be created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups will be created if they do not already exist. + #### **--cgroupns**=*mode* Set the cgroup namespace mode for the container. @@ -152,13 +160,11 @@ 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**. -#### **--cgroup-parent**=*path* - -Path to cgroups under which the cgroup for the container will be created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups will be created if they do not already exist. - -#### **--cgroup-conf**=*KEY=VALUE* +#### **--chrootdirs**=*path* -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. +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. #### **--cidfile**=*file* @@ -381,14 +387,14 @@ This option allows arbitrary environment variables that are available for the pr See [**Environment**](#environment) note below for precedence and examples. -#### **--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) - #### **--env-file**=*file* 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) + #### **--expose**=*port* Expose a port, or a range of ports (e.g. **--expose=3300-3310**) to set up port redirection @@ -448,11 +454,6 @@ The initialization time needed for a container to bootstrap. The value can be ex 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**. -#### **--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. - #### **--help** Print usage statement @@ -463,6 +464,11 @@ 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. + #### **--http-proxy** By default proxy environment variables are passed into the container if set @@ -795,6 +801,16 @@ 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 + #### **--pids-limit**=*limit* Tune the container's pids limit. Set to **-1** to have unlimited pids for the container. The default is **4096** on systems that support "pids" cgroup controller. @@ -1150,23 +1166,6 @@ echo "asdf" | podman run --rm -i someimage /bin/cat 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 -#### **--umask**=*umask* - -Set the umask inside the container. Defaults to `0022`. -Remote connections use local containers.conf for defaults - -#### **--unsetenv**=*env* - -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**=*true|false* - -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. - #### **--uidmap**=*container_uid*:*from_uid*:*amount* Run the container in a new user namespace using the supplied mapping. This @@ -1251,6 +1250,23 @@ 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 + +#### **--unsetenv**=*env* + +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**=*true|false* + +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. + #### **--user**, **-u**=[_user_ | _user_:_group_ | _uid_ | _uid_:_gid_ | _user_:_gid_ | _uid_:_group_ ] Sets the username or UID used and optionally the groupname or GID for the specified command. @@ -1519,22 +1535,6 @@ The default working directory for running binaries within a container is the roo The image developer can set a different default with the WORKDIR instruction. The operator can override the working directory by using the **-w** option. -#### **--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 - -#### **--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. - ## Exit Status The exit code from **podman run** gives information about why the container diff --git a/docs/source/markdown/podman-save.1.md b/docs/source/markdown/podman-save.1.md index 0de64e518..aa4900e25 100644 --- a/docs/source/markdown/podman-save.1.md +++ b/docs/source/markdown/podman-save.1.md @@ -29,14 +29,6 @@ Note: `:` is a restricted character and cannot be part of the file name. Compress tarball image layers when pushing to a directory using the 'dir' transport. (default is same compression type, compressed or uncompressed, as source) Note: This flag can only be set with **--format=docker-dir**. -#### **--uncompressed** - -Accept uncompressed layers when using one of the OCI formats. - -#### **--output**, **-o**=*file* - -Write to a file, default is STDOUT - #### **--format**=*format* An image format to produce, one of: @@ -48,18 +40,26 @@ An image format to produce, one of: | **oci-dir** | A directory using the OCI Image Format | | **docker-dir** | **dir** transport (see **containers-transports(5)**) with v2s2 manifest type | +#### **--help**, **-h** + +Print usage statement + #### **--multi-image-archive**, **-m** Allow for creating archives with more than one image. Additional names will be interpreted as images instead of tags. Only supported for **--format=docker-archive**. The default for this option can be modified via the `multi_image_archive="true"|"false"` flag in containers.conf. +#### **--output**, **-o**=*file* + +Write to a file, default is STDOUT + #### **--quiet**, **-q** Suppress the output -#### **--help**, **-h** +#### **--uncompressed** -Print usage statement +Accept uncompressed layers when using one of the OCI formats. ## EXAMPLES diff --git a/docs/source/markdown/podman-search.1.md b/docs/source/markdown/podman-search.1.md index 9c075a1e0..81a67d762 100644 --- a/docs/source/markdown/podman-search.1.md +++ b/docs/source/markdown/podman-search.1.md @@ -70,6 +70,10 @@ Valid placeholders for the Go template are listed below: Note: use .Tag only if the --list-tags is set. +#### **--help**, **-h** + +Print usage statement + #### **--limit**=*limit* Limit the number of results (default 25). @@ -95,10 +99,6 @@ then TLS verification will be used. If set to false, then TLS verification will default registries will be searched through (in /etc/containers/registries.conf), and TLS will be skipped if a default registry is listed in the insecure registries. -#### **--help**, **-h** - -Print usage statement - ## EXAMPLES ``` diff --git a/docs/source/markdown/podman-secret-create.1.md b/docs/source/markdown/podman-secret-create.1.md index 2d504c0ad..e08afb388 100644 --- a/docs/source/markdown/podman-secret-create.1.md +++ b/docs/source/markdown/podman-secret-create.1.md @@ -20,10 +20,6 @@ Secrets will not be committed to an image with `podman commit`, and will not be ## OPTIONS -#### **--env**=*false* - -Read secret data from environment variable - #### **--driver**=*driver* Specify the secret driver (default **file**, which is unencrypted). @@ -32,6 +28,10 @@ Specify the secret driver (default **file**, which is unencrypted). Specify driver specific options +#### **--env**=*false* + +Read secret data from environment variable + #### **--help** Print usage statement. diff --git a/docs/source/markdown/podman-secret-ls.1.md b/docs/source/markdown/podman-secret-ls.1.md index f33ccf41b..3b8535b5d 100644 --- a/docs/source/markdown/podman-secret-ls.1.md +++ b/docs/source/markdown/podman-secret-ls.1.md @@ -12,14 +12,6 @@ Lists all the secrets that exist. The output can be formatted to a Go template u ## OPTIONS -#### **--format**=*format* - -Format secret output using Go template. - -#### **--noheading** - -Omit the table headings from the listing of secrets. . - #### **--filter**, **-f**=*filter=value* Filter output based on conditions given. @@ -32,6 +24,14 @@ Valid filters are listed below: | name | [Name] Secret name (accepts regex) | | id | [ID] Full or partial secret ID | +#### **--format**=*format* + +Format secret output using Go template. + +#### **--noheading** + +Omit the table headings from the listing of secrets. . + ## EXAMPLES ``` diff --git a/docs/source/markdown/podman-start.1.md b/docs/source/markdown/podman-start.1.md index 793f27aa4..6b0433483 100644 --- a/docs/source/markdown/podman-start.1.md +++ b/docs/source/markdown/podman-start.1.md @@ -16,6 +16,10 @@ attach to the container. ## OPTIONS +#### **--all** + +Start all the containers created by Podman, default is only running containers. + #### **--attach**, **-a** Attach container's STDOUT and STDERR. The default is false. This option cannot be used when @@ -25,23 +29,6 @@ starting multiple containers. Specify the key sequence for detaching a container. Format is a single character `[a-Z]` or one or more `ctrl-<value>` characters where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. Specifying "" will disable this feature. The default is *ctrl-p,ctrl-q*. -#### **--interactive**, **-i** - -Attach container's STDIN. The default is false. - -#### **--latest**, **-l** - -Instead of providing the container name or ID, use the last created container. If you use methods other than Podman -to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--sig-proxy** - -Proxy received signals to the process (non-TTY mode only). SIGCHLD, SIGSTOP, and SIGKILL are not proxied. The default is *true* when attaching, *false* otherwise. - -#### **--all** - -Start all the containers created by Podman, default is only running containers. - #### **--filter**, **-f** Filter what containers are going to be started from the given arguments. @@ -66,6 +53,18 @@ Valid filters are listed below: | pod | [Pod] name or full or partial ID of pod | | network | [Network] name or full ID of network | +#### **--interactive**, **-i** + +Attach container's STDIN. The default is false. + +#### **--latest**, **-l** + +Instead of providing the container name or ID, use the last created container. If you use methods other than Podman +to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +#### **--sig-proxy** + +Proxy received signals to the process (non-TTY mode only). SIGCHLD, SIGSTOP, and SIGKILL are not proxied. The default is *true* when attaching, *false* otherwise. ## EXAMPLE diff --git a/docs/source/markdown/podman-stats.1.md b/docs/source/markdown/podman-stats.1.md index a1a156b10..472cbfbcf 100644 --- a/docs/source/markdown/podman-stats.1.md +++ b/docs/source/markdown/podman-stats.1.md @@ -24,23 +24,6 @@ about their networking usage. Show all containers. Only running containers are shown by default -#### **--latest**, **-l** - -Instead of providing the container name or ID, use the last created container. If you use methods other than Podman -to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--no-reset** - -Do not clear the terminal/screen in between reporting intervals - -#### **--no-stream** - -Disable streaming stats and only pull the first result, default setting is false - -#### **--interval**=*seconds*, **-i**=*seconds* - -Time in seconds between stats reports, defaults to 5 seconds. - #### **--format**=*template* Pretty-print container statistics to JSON or using a Go template @@ -61,6 +44,23 @@ Valid placeholders for the Go template are listed below: When using a GO template, you may precede the format with `table` to print headers. +#### **--interval**=*seconds*, **-i**=*seconds* + +Time in seconds between stats reports, defaults to 5 seconds. + +#### **--latest**, **-l** + +Instead of providing the container name or ID, use the last created container. If you use methods other than Podman +to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +#### **--no-reset** + +Do not clear the terminal/screen in between reporting intervals + +#### **--no-stream** + +Disable streaming stats and only pull the first result, default setting is false + ## EXAMPLE ``` diff --git a/docs/source/markdown/podman-system-service.1.md b/docs/source/markdown/podman-system-service.1.md index 17d8ea06a..678f08a20 100644 --- a/docs/source/markdown/podman-system-service.1.md +++ b/docs/source/markdown/podman-system-service.1.md @@ -25,14 +25,6 @@ Note: The default systemd unit files (system and user) change the log-level opti ## OPTIONS -#### **--time**, **-t** - -The time until the session expires in _seconds_. The default is 5 -seconds. A value of `0` means no timeout, therefore the session will not expire. - -The default timeout can be changed via the `service_timeout=VALUE` field in containers.conf. -See **[containers.conf(5)](https://github.com/containers/common/blob/master/docs/containers.conf.5.md)** for more information. - #### **--cors** CORS headers to inject to the HTTP response. The default value is empty string which disables CORS headers. @@ -41,6 +33,14 @@ CORS headers to inject to the HTTP response. The default value is empty string w Print usage statement. +#### **--time**, **-t** + +The time until the session expires in _seconds_. The default is 5 +seconds. A value of `0` means no timeout, therefore the session will not expire. + +The default timeout can be changed via the `service_timeout=VALUE` field in containers.conf. +See **[containers.conf(5)](https://github.com/containers/common/blob/master/docs/containers.conf.5.md)** for more information. + ## EXAMPLES Run an API listening for 5 seconds using the default socket. diff --git a/docs/source/markdown/podman-version.1.md b/docs/source/markdown/podman-version.1.md index 809ce64a6..94fa0fb21 100644 --- a/docs/source/markdown/podman-version.1.md +++ b/docs/source/markdown/podman-version.1.md @@ -12,10 +12,6 @@ OS, and Architecture. ## OPTIONS -#### **--help**, **-h** - -Print usage statement - #### **--format**, **-f**=*format* Change output format to "json" or a Go template. @@ -39,6 +35,10 @@ $ podman version --format '{{.Client.Version}}' 2.0.0 ``` +#### **--help**, **-h** + +Print usage statement + ## SEE ALSO **[podman(1)](podman.1.md)** diff --git a/docs/source/markdown/podman-volume-export.1.md b/docs/source/markdown/podman-volume-export.1.md index ed73e86d0..57b707ae5 100644 --- a/docs/source/markdown/podman-volume-export.1.md +++ b/docs/source/markdown/podman-volume-export.1.md @@ -18,14 +18,13 @@ Note: Following command is not supported by podman-remote. ## OPTIONS -#### **--output**, **-o**=*file* - -Write to a file, default is STDOUT - #### **--help** Print usage statement +#### **--output**, **-o**=*file* + +Write to a file, default is STDOUT ## EXAMPLES diff --git a/docs/source/markdown/podman-volume-prune.1.md b/docs/source/markdown/podman-volume-prune.1.md index 2028e42f2..0127cc12a 100644 --- a/docs/source/markdown/podman-volume-prune.1.md +++ b/docs/source/markdown/podman-volume-prune.1.md @@ -15,10 +15,6 @@ unused volumes. To bypass the confirmation, use the **--force** flag. ## OPTIONS -#### **--force**, **-f** - -Do not prompt for confirmation. - #### **--filter** Provide filter values. @@ -36,6 +32,10 @@ The `label` *filter* accepts two formats. One is the `label`=*key* or `label`=*k The `until` *filter* can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. 10m, 1h30m) computed relative to the machine’s time. +#### **--force**, **-f** + +Do not prompt for confirmation. + #### **--help** Print usage statement diff --git a/docs/source/markdown/podman.1.md b/docs/source/markdown/podman.1.md index 4d3e92dd2..aad12c584 100644 --- a/docs/source/markdown/podman.1.md +++ b/docs/source/markdown/podman.1.md @@ -32,22 +32,14 @@ The CGroup manager to use for container cgroups. Supported values are cgroupfs o Note: Setting this flag can cause certain commands to break when called on containers previously created by the other CGroup manager type. Note: CGroup manager is not supported in rootless mode when using CGroups Version V1. -#### **--network-config-dir**=*directory* - -Path to the directory where network configuration files are located. -For the CNI backend the default is "/etc/cni/net.d" as root -and "$HOME/.config/cni/net.d" as rootless. -For the netavark backend "/etc/containers/networks" is used as root -and "$graphroot/networks" as rootless. +#### **--conmon** +Path of the conmon binary (Default path is configured in `containers.conf`) #### **--connection**, **-c** Connection to use for remote podman, including Mac and Windows (excluding WSL2) machines, (Default connection is configured in `containers.conf`) Setting this option will switch the **--remote** option to true. Remote connections use local containers.conf for default. -#### **--conmon** -Path of the conmon binary (Default path is configured in `containers.conf`) - #### **--events-backend**=*type* Backend to use for storing events. Allowed values are **file**, **journald**, and @@ -98,6 +90,14 @@ When namespace is set, created containers and pods will join the given namespace #### **--network-cmd-path**=*path* Path to the command binary to use for setting up a network. It is currently only used for setting up a slirp4netns network. If "" is used then the binary is looked up using the $PATH environment variable. +#### **--network-config-dir**=*directory* + +Path to the directory where network configuration files are located. +For the CNI backend the default is "/etc/cni/net.d" as root +and "$HOME/.config/cni/net.d" as rootless. +For the netavark backend "/etc/containers/networks" is used as root +and "$graphroot/networks" as rootless. + #### **--noout** Redirect stdout to /dev/null. This command will prevent all stdout from the Podman command. The **--noout** option will not block stderr or stdout from containers. @@ -107,39 +107,6 @@ When true, access to the Podman service will be remote. Defaults to false. Settings can be modified in the containers.conf file. If the CONTAINER_HOST environment variable is set, the **--remote** option defaults to true. -#### **--url**=*value* -URL to access Podman service (default from `containers.conf`, rootless `unix://run/user/$UID/podman/podman.sock` or as root `unix://run/podman/podman.sock`). -Setting this option will switch the **--remote** option to true. - - - `CONTAINER_HOST` is of the format `<schema>://[<user[:<password>]@]<host>[:<port>][<path>]` - -Details: - - `schema` is one of: - * `ssh` (default): a local unix(7) socket on the named `host` and `port`, reachable via SSH - * `tcp`: an unencrypted, unauthenticated TCP connection to the named `host` and `port` - * `unix`: a local unix(7) socket at the specified `path`, or the default for the user - - `user` will default to either `root` or the current running user (`ssh` only) - - `password` has no default (`ssh` only) - - `host` must be provided and is either the IP or name of the machine hosting the Podman service (`ssh` and `tcp`) - - `port` defaults to 22 (`ssh` and `tcp`) - - `path` defaults to either `/run/podman/podman.sock`, or `/run/user/$UID/podman/podman.sock` if running rootless (`unix`), or must be explicitly specified (`ssh`) - -URL value resolution precedence: - - command line value - - environment variable `CONTAINER_HOST` - - `containers.conf` `service_destinations` table - - `unix://run/podman/podman.sock` - -Remote connections use local containers.conf for default. - -Some example URL values in valid formats: - - unix://run/podman/podman.sock - - unix://run/user/$UID/podman/podman.sock - - ssh://notroot@localhost:22/run/user/$UID/podman/podman.sock - - ssh://root@localhost:22/run/podman/podman.sock - - tcp://localhost:34451 - - tcp://127.0.0.1:34451 - #### **--root**=*value* Storage root dir in which data, including images, is stored (default: "/var/lib/containers/storage" for UID 0, "$HOME/.local/share/containers/storage" for other users). @@ -189,6 +156,39 @@ Path to the tmp directory, for libpod runtime content. NOTE --tmpdir is not used for the temporary storage of downloaded images. Use the environment variable `TMPDIR` to change the temporary storage location of downloaded container images. Podman defaults to use `/var/tmp`. +#### **--url**=*value* +URL to access Podman service (default from `containers.conf`, rootless `unix://run/user/$UID/podman/podman.sock` or as root `unix://run/podman/podman.sock`). +Setting this option will switch the **--remote** option to true. + + - `CONTAINER_HOST` is of the format `<schema>://[<user[:<password>]@]<host>[:<port>][<path>]` + +Details: + - `schema` is one of: + * `ssh` (default): a local unix(7) socket on the named `host` and `port`, reachable via SSH + * `tcp`: an unencrypted, unauthenticated TCP connection to the named `host` and `port` + * `unix`: a local unix(7) socket at the specified `path`, or the default for the user + - `user` will default to either `root` or the current running user (`ssh` only) + - `password` has no default (`ssh` only) + - `host` must be provided and is either the IP or name of the machine hosting the Podman service (`ssh` and `tcp`) + - `port` defaults to 22 (`ssh` and `tcp`) + - `path` defaults to either `/run/podman/podman.sock`, or `/run/user/$UID/podman/podman.sock` if running rootless (`unix`), or must be explicitly specified (`ssh`) + +URL value resolution precedence: + - command line value + - environment variable `CONTAINER_HOST` + - `containers.conf` `service_destinations` table + - `unix://run/podman/podman.sock` + +Remote connections use local containers.conf for default. + +Some example URL values in valid formats: + - unix://run/podman/podman.sock + - unix://run/user/$UID/podman/podman.sock + - ssh://notroot@localhost:22/run/user/$UID/podman/podman.sock + - ssh://root@localhost:22/run/podman/podman.sock + - tcp://localhost:34451 + - tcp://127.0.0.1:34451 + #### **--version**, **-v** Print the version diff --git a/hack/xref-helpmsgs-manpages b/hack/xref-helpmsgs-manpages index a447f4da1..33ba43e9b 100755 --- a/hack/xref-helpmsgs-manpages +++ b/hack/xref-helpmsgs-manpages @@ -287,6 +287,7 @@ sub podman_man { my $section = ''; my @most_recent_flags; my $previous_subcmd = ''; + my $previous_flag = ''; while (my $line = <$fh>) { chomp $line; next unless $line; # skip empty lines @@ -294,6 +295,12 @@ sub podman_man { # .md files designate sections with leading double hash if ($line =~ /^##\s*(GLOBAL\s+)?OPTIONS/) { $section = 'flags'; + $previous_flag = ''; + } + elsif ($line =~ /^###\s+\w+\s+OPTIONS/) { + # poaman image trust has sections for set & show + $section = 'flags'; + $previous_flag = ''; } elsif ($line =~ /^\#\#\s+(SUB)?COMMANDS/) { $section = 'commands'; @@ -320,7 +327,7 @@ sub podman_man { # $1 will be changed by recursion _*BEFORE*_ left-hand assignment my $subcmd = $1; if ($previous_subcmd gt $subcmd) { - warn "$ME: $subpath: '$previous_subcmd' and '$subcmd' are out of order\n"; + warn "$ME: $subpath:$.: '$previous_subcmd' and '$subcmd' are out of order\n"; ++$Errs; } $previous_subcmd = $subcmd; @@ -342,9 +349,20 @@ sub podman_man { # If option has long and short form, long must come first. # This is a while-loop because there may be multiple long # option names, e.g. --net/--network + my $is_first = 1; while ($line =~ s/^\*\*(--[a-z0-9-]+)\*\*(=\*[a-zA-Z0-9-]+\*)?(,\s+)?//g) { - $man{$1} = 1; - push @most_recent_flags, $1; + my $flag = $1; + $man{$flag} = 1; + if ($flag lt $previous_flag && $is_first) { + warn "$ME: $subpath:$.: $flag should precede $previous_flag\n"; + ++$Errs; + } + $previous_flag = $flag if $is_first; + push @most_recent_flags, $flag; + + # Further iterations of /g are allowed to be out of order, + # e.g., it's OK for "--namespace, -ns" to precede --nohead + $is_first = 0; } # Short form if ($line =~ s/^\*\*(-[a-zA-Z0-9])\*\*(=\*[a-zA-Z0-9-]+\*)?//g) { |