opensource/podman
1
0
Fork 0
mirror of https://github.com/containers/podman.git synced 2025-05-17 15:18:43 +08:00
Code Issues Packages Projects Releases Wiki Activity

rootless_tutorial: modernize

Browse Source 
- We can assume that cgroups v2 and rootless overlayfs are the
  default everywhere.

- Remove RHEL7-only instructions

- add clear '$' and '#' prompts to rootless and root commands

- other minor consistency cleanups

Ref: #20669

Signed-off-by: Ed Santiago <santiago@redhat.com>
This commit is contained in:
Ed Santiago
2023-11-15 07:11:26 -07:00
parent 7dfbc72769
commit 9ea390191b
1 changed files with 25 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
docs/tutorials/rootless_tutorial.md
View File

@ -4,17 +4,6 @@
Prior to allowing users without root privileges to run Podman, the administrator must install or build Podman and complete the following configurations.
## cgroup V2 support
The cgroup V2 Linux kernel feature allows the user to limit the amount of resources a rootless container can use. If the Linux distribution that you are running Podman on is enabled with cgroup V2 then you might need to change the default OCI Runtime. Some older versions of `runc` do not work with cgroup V2, you might have to switch to the alternative OCI runtime `crun`.
The alternative OCI runtime support for cgroup V2 can also be turned on at the command line by using the `--runtime` option:
```
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"`.
## Administrator Actions
### Installing Podman
@ -29,33 +18,6 @@ For building Podman, see the [build instructions](https://podman.io/getting-star
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
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.
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.overlay]` to the path of the `fuse-overlayfs` executable:
```
[storage]
driver = "overlay"
(...)
[storage.options.overlay]
(...)
mount_program = "/usr/bin/fuse-overlayfs"
```
### 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`.
### `/etc/subuid` and `/etc/subgid` configuration
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)
@ -63,7 +25,7 @@ Rootless Podman requires the user running it to have a range of UIDs listed in t
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
# cat /etc/subuid
johndoe:100000:65536
test:165536:65536
```
@ -76,24 +38,24 @@ The format of this file is `USERNAME:UID:RANGE`
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 `/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.
```
usermod --add-subuids 100000-165535 --add-subgids 100000-165535 johndoe
# usermod --add-subuids 100000-165535 --add-subgids 100000-165535 johndoe
grep johndoe /etc/subuid /etc/subgid
/etc/subuid:johndoe:100000:65536
/etc/subgid:johndoe:100000:65536
```
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 running [`podman system migrate`](https://github.com/containers/podman/blob/main/docs/source/markdown/podman-system-migrate.1.md) as that user.
#### Giving access to additional groups
Users can fully map additional groups to a container namespace if
those groups subordinated to the user:
```
usermod --add-subgids 2000-2000 johndoe
# usermod --add-subgids 2000-2000 johndoe
grep johndoe /etc/subgid
```
@ -106,7 +68,7 @@ groups, and `--gidmap="+g102000:@2000"` to map the group `2000` in the host
to the group `102000` in the container:
```
podman run \
$ podman run \
--rm \
--group-add keep-groups \
--gidmap="+g102000:@2000" \
@ -117,6 +79,8 @@ podman run \
### Enable unprivileged `ping`
(It is very unlikely that you will need to do this on a modern distro).
Users running in a non-privileged container may not be able to use the `ping` utility from that container.
If this is required, the administrator must verify that the UID of the user is part of the range in the `/proc/sys/net/ipv4/ping_group_range` file.
@ -142,16 +106,16 @@ The three main configuration files are [containers.conf](https://github.com/cont
Podman reads
1. `/usr/share/containers/containers.conf`
2. `/etc/containers/containers.conf`
3. `$HOME/.config/containers/containers.conf`
3. `${XDG_CONFIG_HOME}/containers.conf`
if they exist in that order. Each file can override the previous for particular fields.
if they exist, in that order. Each file can override the previous for particular fields.
#### storage.conf
For `storage.conf` the order is
1. `/etc/containers/storage.conf`
2. `$HOME/.config/containers/storage.conf`
2. `${XDG_CONFIG_HOME}/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")
@ -163,21 +127,21 @@ runroot=""
```
In rootless Podman these fields default to
```
graphroot="$HOME/.local/share/containers/storage"
runroot="$XDG_RUNTIME_DIR/containers"
graphroot="${XDG_DATA_HOME}/containers/storage"
runroot="${XDG_RUNTIME_DIR}/containers"
```
[$XDG_RUNTIME_DIR](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html#variables) defaults on most systems to `/run/user/$UID`.
#### registries
Registry configuration is read in by this order
Registry configuration is read in this order
1. `/etc/containers/registries.conf`
2. `/etc/containers/registries.d/*`
3. `HOME/.config/containers/registries.conf`
3. `${XDG_CONFIG_HOME}/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.
#### Authorization files
The default authorization file used by the `podman login` and `podman logout` commands reside in `${XDG_RUNTIME_DIR}/containers/auth.json`.
The default authorization file used by the `podman login` and `podman logout` commands is `${XDG_RUNTIME_DIR}/containers/auth.json`.
### Using volumes
@ -188,24 +152,24 @@ If your container runs with the root user, then `root` in the container is actua
So, for example,
```
> whoami
host$ whoami
john
# a folder which is empty
host> ls /home/john/folder
host> podman run -v /home/john/folder:/container/volume mycontainer /bin/bash
host$ ls /home/john/folder
host$ podman run -it -v /home/john/folder:/container/volume mycontainer /bin/bash
# Now I'm in the container
root@container> whoami
root@container# whoami
root
root@container> touch /container/volume/test
root@container> ls -l /container/volume
root@container# touch /container/volume/test
root@container# ls -l /container/volume
total 0
-rw-r--r-- 1 root root 0 May 20 21:47 test
root@container> exit
root@container# exit
# I check again
host> ls -l /home/john/folder
host$ ls -l /home/john/folder
total 0
-rw-r--r-- 1 john john 0 May 20 21:47 test
```