diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Readme.md | 2 | ||||
| -rw-r--r-- | docs/source/markdown/podman-generate-systemd.1.md | 12 | ||||
| -rw-r--r-- | docs/tutorials/rootless_tutorial.md | 42 |
3 files changed, 54 insertions, 2 deletions
diff --git a/docs/Readme.md b/docs/Readme.md index 4d10cfa56..987a5b8e4 100644 --- a/docs/Readme.md +++ b/docs/Readme.md @@ -1,7 +1,7 @@ # Podman Documentation The online man pages and other documents regarding Podman can be found at -[Read The Docs](https://podman.readthedocs.io/en/latest/index.html). The man pages +[Read The Docs](https://podman.readthedocs.io). The man pages can be found under the [Commands](https://podman.readthedocs.io/en/latest/Commands.html) link on that page. diff --git a/docs/source/markdown/podman-generate-systemd.1.md b/docs/source/markdown/podman-generate-systemd.1.md index fa04f81f9..72031b19b 100644 --- a/docs/source/markdown/podman-generate-systemd.1.md +++ b/docs/source/markdown/podman-generate-systemd.1.md @@ -40,6 +40,18 @@ Override the default stop timeout for the container with the given value. Set the systemd restart policy. The restart-policy must be one of: "no", "on-success", "on-failure", "on-abnormal", "on-watchdog", "on-abort", or "always". The default policy is *on-failure*. +**--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 seperator between the name/id of a container/pod and the prefix. The default is *-*. + ## Examples ### Generate and print a systemd unit file for a container diff --git a/docs/tutorials/rootless_tutorial.md b/docs/tutorials/rootless_tutorial.md index 8e048c746..440e12062 100644 --- a/docs/tutorials/rootless_tutorial.md +++ b/docs/tutorials/rootless_tutorial.md @@ -58,7 +58,7 @@ The number of user namespaces that are allowed on the system is specified in the ### /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 `shadows-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 /etc/subuid and /etc/subgid files. The `shadows-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) 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. @@ -110,6 +110,46 @@ The Podman configuration files for root reside in `/usr/share/containers` with o 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. + +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. + +So, for example, + +``` +> whoami +john + +# a folder which is empty +host> ls /home/john/folder +host> podman run -v /home/john/folder:/container/volume mycontainer /bin/bash + +# Now I'm in the container +root@container> whoami +root +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 + +# I check again +host> ls -l /home/john/folder +total 0 +-rw-r--r-- 1 john john 0 May 20 21:47 test +``` + +We do recognize that this doesn't really match how many people intend to use rootless Podman - they want their UID inside and outside the container to match. Thus, we provide the `--userns=keep-id` flag, which ensures that your user is mapped to its own UID and GID inside the container. + +It is also helpful to distinguish between running Podman as a rootless user, and a container which is built to run rootless. If the container you're trying you run has a `USER` which is not root, then when mounting volumes you **must** use `--userns=keep-id`. This is because the container user would not be able to become `root` and access the mounted volumes. + +Other considerations in regards to volumes: + +- You should always give the full path to the volume you'd like to mount +- The mount point must exist in the container + ## 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/libpod/blob/master/rootless.md) page which lists known issues and solutions to known issues in this environment. |