diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/source/Introduction.rst | 2 | ||||
| -rw-r--r-- | docs/source/markdown/podman-create.1.md | 79 | ||||
| -rw-r--r-- | docs/source/markdown/podman-import.1.md | 2 | ||||
| -rw-r--r-- | docs/source/markdown/podman-play-kube.1.md | 4 | ||||
| -rw-r--r-- | docs/source/markdown/podman-run.1.md | 86 |
5 files changed, 155 insertions, 18 deletions
diff --git a/docs/source/Introduction.rst b/docs/source/Introduction.rst index 9fdce6962..3fa86f868 100644 --- a/docs/source/Introduction.rst +++ b/docs/source/Introduction.rst @@ -32,7 +32,7 @@ There’s an old saying that “nobody runs an operating system just to run an o Sometimes we can find a publicly available container image for the exact workload we’re looking for and it will already be packaged exactly how we want. But, more often than not, there’s something that we want to add, remove, or customize. It could be as simple as a configuration setting for security or performance, or as complex as adding a complex workload. Either way, containers make it fairly easy to make the changes we need. -Container Images aren’t actually images, they’re repositories often made up of multiple layers. These layers can easily be added, saved, and shared with others by using a Containerfile (Dockerfile). This single file often contains all the instructions needed to build the new and can easily be shared with others publicly using tools like GitHub. +Container Images aren’t actually images, they’re repositories often made up of multiple layers. These layers can easily be added, saved, and shared with others by using a Containerfile (Dockerfile). This single file often contains all the instructions needed to build a new container image and can easily be shared with others publicly using tools like GitHub. Here's an example of how to build a Nginx web server on top of a Debian base image using the Dockerfile maintained by Nginx and published in GitHub:: diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index ae6dfe03b..059a09ae1 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -149,6 +149,7 @@ Write the container ID to the file #### **\-\-conmon-pidfile**=*path* Write the pid of the `conmon` process to a file. `conmon` runs in a separate process than Podman, so this is necessary when using systemd to restart Podman containers. +(This option is not available with the remote Podman client) #### **\-\-cpu-period**=*limit* @@ -974,11 +975,72 @@ Remote connections use local containers.conf for defaults Set the umask inside the container. Defaults to `0022`. Remote connections use local containers.conf for defaults -#### **\-\-uidmap**=*container_uid:host_uid:amount* +#### **\-\-uidmap**=*container_uid*:*from_uid*:*amount* -UID map for the user namespace. Using this flag will run the container with user namespace enabled. It conflicts with the `--userns` and `--subuidname` flags. +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. -The following example maps uids 0-2000 in the container to the uids 30000-31999 on the host and gids 0-2000 in the container to the gids 30000-31999 on the host. `--uidmap=0:30000:2000` +The _from_uid_ value is based upon the user running the command, either rootful or rootless users. +* rootful user: *container_uid*:*host_uid*:*amount* +* rootless user: *container_uid*:*intermediate_uid*:*amount* + +When **podman create** is called by a privileged user, the option **\-\-uidmap** +works as a direct mapping between host UIDs and container UIDs. + +host UID -> container UID + +The _amount_ specifies the number of consecutive UIDs that will be mapped. +If for example _amount_ is **4** the mapping would look like: + +| host UID | container UID | +| - | - | +| _from_uid_ | _container_uid_ | +| _from_uid_ + 1 | _container_uid_ + 1 | +| _from_uid_ + 2 | _container_uid_ + 2 | +| _from_uid_ + 3 | _container_uid_ + 3 | + +When **podman create** is called by an unprivileged user (i.e. running rootless), +the value _from_uid_ is interpreted as an "intermediate UID". In the rootless +case, host UIDs are not mapped directly to container UIDs. Instead the mapping +happens over two mapping steps: + +host UID -> intermediate UID -> container UID + +The **\-\-uidmap** option only influences the second mapping step. + +The first mapping step is derived by Podman from the contents of the file +_/etc/subuid_ and the UID of the user calling Podman. + +First mapping step: + +| host UID | intermediate UID | +| - | - | +| UID for the user starting Podman | 0 | +| 1st subordinate UID for the user starting Podman | 1 | +| 2nd subordinate UID for the user starting Podman | 2 | +| 3rd subordinate UID for the user starting Podman | 3 | +| nth subordinate UID for the user starting Podman | n | + +To be able to use intermediate UIDs greater than zero, the user needs to have +subordinate UIDs configured in _/etc/subuid_. See **subuid**(5). + +The second mapping step is configured with **\-\-uidmap**. + +If for example _amount_ is **5** the second mapping step would look like: + +| intermediate UID | container UID | +| - | - | +| _from_uid_ | _container_uid_ | +| _from_uid_ + 1 | _container_uid_ + 1 | +| _from_uid_ + 2 | _container_uid_ + 2 | +| _from_uid_ + 3 | _container_uid_ + 3 | +| _from_uid_ + 4 | _container_uid_ + 4 | + +Even if a user does not have any subordinate UIDs in _/etc/subuid_, +**\-\-uidmap** could still be used to map the normal UID of the user to a +container UID by running `podman create --uidmap $container_uid:0:1 --user $container_uid ...`. #### **\-\-ulimit**=*option* @@ -1224,6 +1286,17 @@ 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) +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 + + ## EXAMPLES ### Create a container using a local image diff --git a/docs/source/markdown/podman-import.1.md b/docs/source/markdown/podman-import.1.md index 38c2ab680..171ba4fbd 100644 --- a/docs/source/markdown/podman-import.1.md +++ b/docs/source/markdown/podman-import.1.md @@ -34,7 +34,7 @@ Set commit message for imported image Shows progress on the import -**-verbose** +**\-\-verbose** Print additional debugging information diff --git a/docs/source/markdown/podman-play-kube.1.md b/docs/source/markdown/podman-play-kube.1.md index 91899a8bd..1074c27f8 100644 --- a/docs/source/markdown/podman-play-kube.1.md +++ b/docs/source/markdown/podman-play-kube.1.md @@ -62,6 +62,10 @@ 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. +#### **\-\-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. + #### **\-\-log-driver**=driver Set logging driver for all created containers. diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index 40b271828..b607a65ff 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -167,6 +167,7 @@ Write the container ID to *file*. #### **\-\-conmon-pidfile**=*file* Write the pid of the **conmon** process to a file. As **conmon** runs in a separate process than Podman, this is necessary when using systemd to restart Podman containers. +(This option is not available with the remote Podman client) #### **\-\-cpu-period**=*limit* @@ -1046,23 +1047,72 @@ Remote connections use local containers.conf for defaults Set the umask inside the container. Defaults to `0022`. Remote connections use local containers.conf for defaults -#### **\-\-uidmap**=*container_uid*:*host_uid*:*amount* +#### **\-\-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** flags. -This option can be passed several times to map different ranges. If calling **podman run** -as an unprivileged user, the user needs to have the right to use the mapping. See **subuid**(5). +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. -The following example maps uids 0-1999 in the container to the uids 30000-31999 on the host: **\-\-uidmap=0:30000:2000**. +The _from_uid_ value is based upon the user running the command, either rootful or rootless users. +* rootful user: *container_uid*:*host_uid*:*amount* +* rootless user: *container_uid*:*intermediate_uid*:*amount* -**Important note:** The new user namespace mapping based on **\-\-uidmap** is based on the initial mapping made in the _/etc/subuid_ file. -Assuming there is a _/etc/subuid_ mapping **username:100000:65536**, then **username** is initially mapped to a namespace starting with -uid **100000** for **65536** ids. From here the **\-\-uidmap** mapping to the new namespace starts from **0** again, but is based on the initial mapping. -Meaning **username** is initially mapped to uid **100000** which is referenced as **0** in the following **\-\-uidmap** mapping. In terms of the example -above: The user **username** is mapped to user **100000** of the initial namespace then the -**30000**st id of this namespace (which is uid 130000 in this namespace) is mapped to container namespace user id **0**. (username -> 100000 / 30000 -> 0) +When **podman run** is called by a privileged user, the option **\-\-uidmap** +works as a direct mapping between host UIDs and container UIDs. -_Note_: A minimal mapping has to have at least container uid **0** mapped to the parent user namespace. +host UID -> container UID + +The _amount_ specifies the number of consecutive UIDs that will be mapped. +If for example _amount_ is **4** the mapping would look like: + +| host UID | container UID | +| - | - | +| _from_uid_ | _container_uid_ | +| _from_uid_ + 1 | _container_uid_ + 1 | +| _from_uid_ + 2 | _container_uid_ + 2 | +| _from_uid_ + 3 | _container_uid_ + 3 | + +When **podman run** is called by an unprivileged user (i.e. running rootless), +the value _from_uid_ is interpreted as an "intermediate UID". In the rootless +case, host UIDs are not mapped directly to container UIDs. Instead the mapping +happens over two mapping steps: + +host UID -> intermediate UID -> container UID + +The **\-\-uidmap** option only influences the second mapping step. + +The first mapping step is derived by Podman from the contents of the file +_/etc/subuid_ and the UID of the user calling Podman. + +First mapping step: + +| host UID | intermediate UID | +| - | - | +| UID for the user starting Podman | 0 | +| 1st subordinate UID for the user starting Podman | 1 | +| 2nd subordinate UID for the user starting Podman | 2 | +| 3rd subordinate UID for the user starting Podman | 3 | +| nth subordinate UID for the user starting Podman | n | + +To be able to use intermediate UIDs greater than zero, the user needs to have +subordinate UIDs configured in _/etc/subuid_. See **subuid**(5). + +The second mapping step is configured with **\-\-uidmap**. + +If for example _amount_ is **5** the second mapping step would look like: + +| intermediate UID | container UID | +| - | - | +| _from_uid_ | _container_uid_ | +| _from_uid_ + 1 | _container_uid_ + 1 | +| _from_uid_ + 2 | _container_uid_ + 2 | +| _from_uid_ + 3 | _container_uid_ + 3 | +| _from_uid_ + 4 | _container_uid_ + 4 | + +Even if a user does not have any subordinate UIDs in _/etc/subuid_, +**\-\-uidmap** could still be used to map the normal UID of the user to a +container UID by running `podman run --uidmap $container_uid:0:1 --user $container_uid ...`. #### **\-\-ulimit**=*option* @@ -1305,6 +1355,16 @@ 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) +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 + ## Exit Status The exit code from **podman run** gives information about why the container |