From 9b0c8d23bddd0fccd6a1faa3fa7f5b7e0373f541 Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Wed, 23 Mar 2022 12:29:08 -0600 Subject: 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 --- docs/source/markdown/podman-create.1.md | 95 +++++++++++++++++---------------- 1 file changed, 48 insertions(+), 47 deletions(-) (limited to 'docs/source/markdown/podman-create.1.md') 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 -- cgit v1.2.3-54-g00ecf