diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/source/includes.rst | 2 | ||||
| -rw-r--r-- | docs/source/markdown/podman-create.1.md | 2 | ||||
| -rw-r--r-- | docs/source/markdown/podman-pod-ps.1.md | 59 | ||||
| -rw-r--r-- | docs/source/markdown/podman-run.1.md | 2 | ||||
| -rw-r--r-- | docs/tutorials/rootless_tutorial.md | 54 |
5 files changed, 57 insertions, 62 deletions
diff --git a/docs/source/includes.rst b/docs/source/includes.rst index 8d3b6e2db..6e04d77f4 100644 --- a/docs/source/includes.rst +++ b/docs/source/includes.rst @@ -16,4 +16,4 @@ .. _podman run: http://docs.podman.io/en/latest/markdown/podman-run.1.html .. _podman build: http://docs.podman.io/en/latest/markdown/podman-build.1.html .. _podman push: http://docs.podman.io/en/latest/markdown/podman-push.1.html -.. image:: https://github.com/containers/podman/blob/master/logo/podman-logo.png?raw=true +.. image:: https://github.com/containers/podman/blob/main/logo/podman-logo.png?raw=true diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index 2c51b312d..f56b363e0 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -646,7 +646,7 @@ Valid _mode_ values are: - **ns:**_path_: path to a network namespace to join; - **private**: create a new namespace for the container (default) - **slirp4netns[:OPTIONS,...]**: use **slirp4netns**(1) to create a user network stack. This is the default for rootless containers. It is possible to specify these additional options: - - **allow_host_loopback=true|false**: Allow the slirp4netns to reach the host loopback IP (`10.0.2.2`). Default is false. + - **allow_host_loopback=true|false**: Allow the slirp4netns to reach the host loopback IP (`10.0.2.2`, which is added to `/etc/hosts` as `host.containers.internal` for your convenience). Default is false. - **mtu=MTU**: Specify the MTU to use for this network. (Default is `65520`). - **cidr=CIDR**: Specify ip range to use for this network. (Default is `10.0.2.0/24`). - **enable_ipv6=true|false**: Enable IPv6. Default is false. (Required for `outbound_addr6`). diff --git a/docs/source/markdown/podman-pod-ps.1.md b/docs/source/markdown/podman-pod-ps.1.md index c1f5fd5e3..156adccaa 100644 --- a/docs/source/markdown/podman-pod-ps.1.md +++ b/docs/source/markdown/podman-pod-ps.1.md @@ -12,7 +12,9 @@ By default it lists: * pod id * pod name + * the time the pod was created * number of containers attached to pod + * container id of the pod infra container * status of pod as defined by the following table | **Status** | **Description** | @@ -28,15 +30,15 @@ By default it lists: #### **--ctr-names** -Includes the container names in the container info field +Display the container names #### **--ctr-ids** -Includes the container IDs in the container info field +Display the container IDs #### **--ctr-status** -Includes the container statuses in the container info field +Display the container statuses #### **--latest**, **-l** @@ -111,62 +113,55 @@ Print usage statement ``` $ podman pod ps -POD ID NAME STATUS NUMBER OF CONTAINERS -00dfd6fa02c0 jolly_goldstine Running 1 -f4df8692e116 nifty_torvalds Created 2 +POD ID NAME STATUS CREATED INFRA ID # OF CONTAINERS +00dfd6fa02c0 jolly_goldstine Running 31 hours ago ba465ab0a3a4 1 +f4df8692e116 nifty_torvalds Created 10 minutes ago 331693bff40a 2 ``` ``` $ podman pod ps --ctr-names -POD ID NAME STATUS CONTAINER INFO -00dfd6fa02c0 jolly_goldstine Running [ loving_archimedes ] -f4df8692e116 nifty_torvalds Created [ thirsty_hawking ] [ wizardly_golick ] +POD ID NAME STATUS CREATED INFRA ID NAMES +00dfd6fa02c0 jolly_goldstine Running 31 hours ago ba465ab0a3a4 loving_archimedes +f4df8692e116 nifty_torvalds Created 10 minutes ago 331693bff40a thirsty_hawking,wizardly_golick ``` ``` $ podman pod ps --ctr-status --ctr-names --ctr-ids -POD ID NAME STATUS CONTAINER INFO -00dfd6fa02c0 jolly_goldstine Running [ ba465ab0a3a4 loving_archimedes Running ] -f4df8692e116 nifty_torvalds Created [ 331693bff40a thirsty_hawking Created ] [ 8e428daeb89e wizardly_golick Created ] +POD ID NAME STATUS CREATED INFRA ID IDS NAMES STATUS +00dfd6fa02c0 jolly_goldstine Running 31 hours ago ba465ab0a3a4 ba465ab0a3a4 loving_archimedes running +f4df8692e116 nifty_torvalds Created 10 minutes ago 331693bff40a 331693bff40a,8e428daeb89e thirsty_hawking,wizardly_golick configured,configured ``` ``` -$ podman pod ps --format "{{.ID}} {{.ContainerInfo}} {{.Cgroup}}" --ctr-names -00dfd6fa02c0 [ loving_archimedes ] /libpod_parent -f4df8692e116 [ thirsty_hawking ] [ wizardly_golick ] /libpod_parent -``` - -``` -$ podman pod ps --cgroup -POD ID NAME STATUS NUMBER OF CONTAINERS CGROUP USE POD CGROUP -00dfd6fa02c0 jolly_goldstine Running 1 /libpod_parent true -f4df8692e116 nifty_torvalds Created 2 /libpod_parent true +$ podman pod ps --format "{{.ID}} {{.ContainerNames}} {{.Cgroup}}" +00dfd6fa02c0 loving_archimedes /libpod_parent +f4df8692e116 thirsty_hawking,wizardly_golick /libpod_parent ``` ``` $ podman pod ps --sort id --filter ctr-number=2 -POD ID NAME STATUS NUMBER OF CONTAINERS -f4df8692e116 nifty_torvalds Created 2 +POD ID NAME STATUS CREATED INFRA ID # OF CONTAINERS +f4df8692e116 nifty_torvalds Created 10 minutes ago 331693bff40a 2 ``` ``` $ podman pod ps --ctr-ids -POD ID NAME STATUS CONTAINER INFO -00dfd6fa02c0 jolly_goldstine Running [ ba465ab0a3a4 ] -f4df8692e116 nifty_torvalds Created [ 331693bff40a ] [ 8e428daeb89e ] +POD ID NAME STATUS CREATED INFRA ID IDS +00dfd6fa02c0 jolly_goldstine Running 31 hours ago ba465ab0a3a4 ba465ab0a3a4 +f4df8692e116 nifty_torvalds Created 10 minutes ago 331693bff40a 331693bff40a,8e428daeb89e ``` ``` $ podman pod ps --no-trunc --ctr-ids -POD ID NAME STATUS CONTAINER INFO -00dfd6fa02c0a2daaedfdf8fcecd06f22ad114d46d167d71777224735f701866 jolly_goldstine Running [ ba465ab0a3a4e15e3539a1e79c32d1213a02b0989371e274f98e0f1ae9de7050 ] -f4df8692e116a3e6d1d62572644ed36ca475d933808cc3c93435c45aa139314b nifty_torvalds Created [ 331693bff40a0ef2f05a3aba73ce49e3243108911927fff04d1f7fc44dda8022 ] [ 8e428daeb89e69b71e7916a13accfb87d122889442b5c05c2d99cf94a3230e9d ] +POD ID NAME STATUS CREATED INFRA ID IDS +00dfd6fa02c0a2daaedfdf8fcecd06f22ad114d46d167d71777224735f701866 jolly_goldstine Running 31 hours ago ba465ab0a3a4e15e3539a1e79c32d1213a02b0989371e274f98e0f1ae9de7050 ba465ab0a3a4e15e3539a1e79c32d1213a02b0989371e274f98e0f1ae9de7050 +f4df8692e116a3e6d1d62572644ed36ca475d933808cc3c93435c45aa139314b nifty_torvalds Created 10 minutes ago 331693bff40a926b6d52b184e116afd15497610c378d5d4c42945dd6e33b75b0 331693bff40a926b6d52b184e116afd15497610c378d5d4c42945dd6e33b75b0,8e428daeb89e69b71e7916a13accfb87d122889442b5c05c2d99cf94a3230e9d ``` ``` $ podman pod ps --ctr-names -POD ID NAME STATUS CONTAINER INFO -314f4da82d74 hi Created [ jovial_jackson ] [ hopeful_archimedes ] [ vibrant_ptolemy ] [ heuristic_jennings ] [ keen_raman ] [ hopeful_newton ] [ mystifying_bose ] [ silly_lalande ] [ serene_lichterman ] ... +POD ID NAME STATUS CREATED INFRA ID NAMES +314f4da82d74 hi Created 17 hours ago a9f2d2165675 jovial_jackson,hopeful_archimedes,vibrant_ptolemy,heuristic_jennings,keen_raman,hopeful_newton,mystifying_bose,silly_lalande,serene_lichterman ... ``` ## pod ps diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index 6027a14a5..1c3efa0c3 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -680,7 +680,7 @@ Valid _mode_ values are: - **ns:**_path_: path to a network namespace to join; - **private**: create a new namespace for the container (default) - **slirp4netns[:OPTIONS,...]**: use **slirp4netns**(1) to create a user network stack. This is the default for rootless containers. It is possible to specify these additional options: - - **allow_host_loopback=true|false**: Allow the slirp4netns to reach the host loopback IP (`10.0.2.2`). Default is false. + - **allow_host_loopback=true|false**: Allow the slirp4netns to reach the host loopback IP (`10.0.2.2`, which is added to `/etc/hosts` as `host.containers.internal` for your convenience). Default is false. - **mtu=MTU**: Specify the MTU to use for this network. (Default is `65520`). - **cidr=CIDR**: Specify ip range to use for this network. (Default is `10.0.2.0/24`). - **enable_ipv6=true|false**: Enable IPv6. Default is false. (Required for `outbound_addr6`). diff --git a/docs/tutorials/rootless_tutorial.md b/docs/tutorials/rootless_tutorial.md index 18f60ea00..5d20f2cc0 100644 --- a/docs/tutorials/rootless_tutorial.md +++ b/docs/tutorials/rootless_tutorial.md @@ -13,31 +13,31 @@ The alternative OCI runtime support for cgroup V2 can also be turned on at the c ``` podman --runtime crun ``` -or for all commands by changing the value for the "Default OCI runtime" in the containers.conf file either at the system level or at the [user level](#user-configuration-files) from `runtime = "runc"` to `runtime = "crun"`. +or for all commands by changing the value for the "Default OCI runtime" in the `containers.conf` file either at the system level or at the [user level](#user-configuration-files) from `runtime = "runc"` to `runtime = "crun"`. ## Administrator Actions ### Installing Podman -For installing Podman, please see the [installation instructions](https://github.com/containers/podman/blob/master/install.md). +For installing Podman, please see the [installation instructions](https://github.com/containers/podman/blob/main/install.md). ### Building Podman -For building Podman, please see the [installation instructions](https://github.com/containers/podman/blob/master/install.md#building-from-scratch). +For building Podman, please see the [installation instructions](https://github.com/containers/podman/blob/main/install.md#building-from-scratch). -### Install slirp4netns +### Install `slirp4netns` -The [slirp4netns](https://github.com/rootless-containers/slirp4netns) package provides user-mode networking for unprivileged network namespaces and must be installed on the machine in order for Podman to run in a rootless environment. The package is available on most Linux distributions via their package distribution software such as yum, dnf, apt, zypper, etc. If the package is not available, you can build and install slirp4netns from [GitHub](https://github.com/rootless-containers/slirp4netns). +The [slirp4netns](https://github.com/rootless-containers/slirp4netns) package provides user-mode networking for unprivileged network namespaces and must be installed on the machine in order for Podman to run in a rootless environment. The package is available on most Linux distributions via their package distribution software such as `yum`, `dnf`, `apt`, `zypper`, etc. If the package is not available, you can build and install `slirp4netns` from [GitHub](https://github.com/rootless-containers/slirp4netns). -### Ensure fuse-overlayfs is installed +### Ensure `fuse-overlayfs` is installed -When using Podman in a rootless environment, it is recommended to use fuse-overlayfs rather than the VFS file system. For that you need the `fuse-overlayfs` executable available in `$PATH`. +When using Podman in a rootless environment, it is recommended to use `fuse-overlayfs` rather than the VFS file system. For that you need the `fuse-overlayfs` executable available in `$PATH`. Your distribution might already provide it in the `fuse-overlayfs` package, but be aware that you need at least version **0.7.6**. This especially needs to be checked on Ubuntu distributions as `fuse-overlayfs` is not generally installed by default and the 0.7.6 version is not available natively on Ubuntu releases prior to **20.04**. -The fuse-overlayfs project is available from [GitHub](https://github.com/containers/fuse-overlayfs), and provides instructions for easily building a static `fuse-overlayfs` executable. +The `fuse-overlayfs` project is available from [GitHub](https://github.com/containers/fuse-overlayfs), and provides instructions for easily building a static `fuse-overlayfs` executable. -If Podman is used before fuse-overlayfs is installed, it may be necessary to adjust the `storage.conf` file (see "User Configuration Files" below) to change the `driver` option under `[storage]` to `"overlay"` and point the `mount_program` option in `[storage.options]` to the path of the `fuse-overlayfs` executable: +If Podman is used before `fuse-overlayfs` is installed, it may be necessary to adjust the `storage.conf` file (see "User Configuration Files" below) to change the `driver` option under `[storage]` to `"overlay"` and point the `mount_program` option in `[storage.options]` to the path of the `fuse-overlayfs` executable: ``` [storage] @@ -54,13 +54,13 @@ If Podman is used before fuse-overlayfs is installed, it may be necessary to adj ### Enable user namespaces (on RHEL7 machines) -The number of user namespaces that are allowed on the system is specified in the file `/proc/sys/user/max_user_namespaces`. On most Linux platforms this is preset by default and no adjustment is necessary. However on RHEL7 machines a user with root privileges may need to set that to a reasonable value by using this command: `sysctl user.max_user_namespaces=15000`. +The number of user namespaces that are allowed on the system is specified in the file `/proc/sys/user/max_user_namespaces`. On most Linux platforms this is preset by default and no adjustment is necessary. However, on RHEL7 machines, a user with root privileges may need to set that to a reasonable value by using this command: `sysctl user.max_user_namespaces=15000`. -### /etc/subuid and /etc/subgid configuration +### `/etc/subuid` and `/etc/subgid` configuration -Rootless Podman requires the user running it to have a range of UIDs listed in /etc/subuid and /etc/subgid files. The `shadow-utils` or `newuid` package provides these files on different distributions and they must be installed on the system. These files will need someone with root privileges on the system to add or update the entries within them. The following is a summarization from the [How does rootless Podman work?](https://opensource.com/article/19/2/how-does-rootless-podman-work) article by Dan Walsh on [opensource.com](https://opensource.com) +Rootless Podman requires the user running it to have a range of UIDs listed in the files `/etc/subuid` and `/etc/subgid`. The `shadow-utils` or `newuid` package provides these files on different distributions and they must be installed on the system. Root privileges are required to add or update entries within these files. The following is a summary from the [How does rootless Podman work?](https://opensource.com/article/19/2/how-does-rootless-podman-work) article by Dan Walsh on [opensource.com](https://opensource.com) -Update the /etc/subuid and /etc/subgid with fields for each user that will be allowed to create containers that look like the following. Note that the values for each user must be unique and without any overlap. If there is an overlap, there is a potential for a user to use another’s namespace and they could corrupt it. +For each user that will be allowed to create containers, update `/etc/subuid` and `/etc/subgid` for the user with fields that look like the following. Note that the values for each user must be unique. If there is overlap, there is a potential for a user to use another user's namespace and they could corrupt it. ``` cat /etc/subuid @@ -68,17 +68,17 @@ johndoe:100000:65536 test:165536:65536 ``` -The format of this file is USERNAME:UID:RANGE +The format of this file is `USERNAME:UID:RANGE` -* username as listed in /etc/passwd or getpwent. -* The initial uid allocated for the user. +* username as listed in `/etc/passwd` or in the output of [`getpwent`](https://man7.org/linux/man-pages/man3/getpwent.3.html). +* The initial UID allocated for the user. * The size of the range of UIDs allocated for the user. -This means the user johndoe is allocated UIDS 100000-165535 as well as their standard UID in the /etc/passwd file. NOTE: this is not currently supported with network installs. These files must be available locally to the host machine. It is not possible to configure this with LDAP or Active Directory. +This means the user `johndoe` is allocated UIDs 100000-165535 as well as their standard UID in the `/etc/passwd` file. NOTE: this is not currently supported with network installs; these files must be available locally to the host machine. It is not possible to configure this with LDAP or Active Directory. -If you update either the /etc/subuid or the /etc/subgid file, you need to stop all the running containers owned by the user and kill the pause process that is running on the system for that user. This can be done automatically by using the [`podman system migrate`](https://github.com/containers/podman/blob/master/docs/podman-system-migrate.1.md) command which will stop all the containers for the user and will kill the pause process. +If you update either `/etc/subuid` or `/etc/subgid`, you need to stop all the running containers owned by the user and kill the pause process that is running on the system for that user. This can be done automatically by using the [`podman system migrate`](https://github.com/containers/podman/blob/main/docs/source/markdown/podman-system-migrate.1.md) command which will stop all the containers for the user and will kill the pause process. -Rather than updating the files directly, the usermod program can be used to assign UIDs and GIDs to a user. +Rather than updating the files directly, the `usermod` program can be used to assign UIDs and GIDs to a user. ``` usermod --add-subuids 200000-201000 --add-subgids 200000-201000 johndoe @@ -102,13 +102,13 @@ To make the change persist, the administrator will need to add a file with the ` The majority of the work necessary to run Podman in a rootless environment is on the shoulders of the machine’s administrator. -Once the Administrator has completed the setup on the machine and then the configurations for the user in /etc/subuid and /etc/subgid, the user can just start using any Podman command that they wish. +Once the Administrator has completed the setup on the machine and then the configurations for the user in `/etc/subuid` and `/etc/subgid`, the user can just start using any Podman command that they wish. ### User Configuration Files The Podman configuration files for root reside in `/usr/share/containers` with overrides in `/etc/containers`. In the rootless environment they reside in `${XDG_CONFIG_HOME}/containers` (usually `~/.config/containers`) and are owned by each individual user. -The three main configuration files are [containers.conf](https://github.com/containers/common/blob/master/docs/containers.conf.5.md), [storage.conf](https://github.com/containers/storage/blob/master/docs/containers-storage.conf.5.md) and [registries.conf](https://github.com/containers/image/blob/master/docs/containers-registries.conf.5.md). The user can modify these files as they wish. +The three main configuration files are [containers.conf](https://github.com/containers/common/blob/main/docs/containers.conf.5.md), [storage.conf](https://github.com/containers/storage/blob/main/docs/containers-storage.conf.5.md) and [registries.conf](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md). The user can modify these files as they wish. #### containers.conf Podman reads @@ -123,7 +123,7 @@ For `storage.conf` the order is 1. `/etc/containers/storage.conf` 2. `$HOME/.config/containers/storage.conf` -In rootless podman certain fields in `/etc/containers/storage.conf` are ignored. These fields are: +In rootless Podman certain fields in `/etc/containers/storage.conf` are ignored. These fields are: ``` graphroot="" container storage graph dir (default: "/var/lib/containers/storage") @@ -133,7 +133,7 @@ runroot="" container storage run dir (default: "/run/containers/storage") Default directory to store all temporary writable content created by container storage programs. ``` -In rootless podman these fields default to +In rootless Podman these fields default to ``` graphroot="$HOME/.local/share/containers/storage" runroot="$XDG_RUNTIME_DIR/containers" @@ -146,14 +146,14 @@ Registry configuration is read in by this order 2. `/etc/containers/registries.d/*` 3. `HOME/.config/containers/registries.conf` -The files in the home directory should be used to configure rootless podman for personal needs. These files are not created by default. Users can copy the files from `/usr/share/containers` or `/etc/containers` and modify them. +The files in the home directory should be used to configure rootless Podman for personal needs. These files are not created by default. Users can copy the files from `/usr/share/containers` or `/etc/containers` and modify them. #### Authorization files The default authorization file used by the `podman login` and `podman logout` commands reside in `${XDG_RUNTIME_DIR}/containers/auth.json`. ### Using volumes -Rootless Podman is not, and will never be, root; it's not a setuid binary, and gains no privileges when it runs. Instead, Podman makes use of a user namespace to shift the UIDs and GIDs of a block of users it is given access to on the host (via the newuidmap and newgidmap executables) and your own user within the containers that Podman creates. +Rootless Podman is not, and will never be, root; it's not a `setuid` binary, and gains no privileges when it runs. Instead, Podman makes use of a user namespace to shift the UIDs and GIDs of a block of users it is given access to on the host (via the `newuidmap` and `newgidmap` executables) and your own user within the containers that Podman creates. If your container runs with the root user, then `root` in the container is actually your user on the host. UID/GID 1 is the first UID/GID specified in your user's mapping in `/etc/subuid` and `/etc/subgid`, etc. If you mount a directory from the host into a container as a rootless user, and create a file in that directory as root in the container, you'll see it's actually owned by your user on the host. @@ -193,6 +193,6 @@ Other considerations in regards to volumes: ## More information -If you are still experiencing problems running Podman in a rootless environment, please refer to the [Shortcomings of Rootless Podman](https://github.com/containers/podman/blob/master/rootless.md) page which lists known issues and solutions to known issues in this environment. +If you are still experiencing problems running Podman in a rootless environment, please refer to the [Shortcomings of Rootless Podman](https://github.com/containers/podman/blob/main/rootless.md) page which lists known issues and solutions to known issues in this environment. -For more information on Podman and its subcommands, checkout the asciiart demos on the [README.md](../../README.md#commands) page or the [podman.io](https://podman.io) web site. +For more information on Podman and its subcommands, follow the links on the main [README.md](../../README.md#podman-information-for-developers) page or the [podman.io](https://podman.io) web site. |