diff options
Diffstat (limited to 'docs/tutorials')
| -rw-r--r-- | docs/tutorials/podman-derivative-api.md | 18 | ||||
| -rw-r--r-- | docs/tutorials/rootless_tutorial.md | 40 |
2 files changed, 56 insertions, 2 deletions
diff --git a/docs/tutorials/podman-derivative-api.md b/docs/tutorials/podman-derivative-api.md index 065b0c4a9..8a1f40fc0 100644 --- a/docs/tutorials/podman-derivative-api.md +++ b/docs/tutorials/podman-derivative-api.md @@ -4,6 +4,20 @@ libpod today is a Golang library and a CLI. The choice of interface you make has advantages and disadvantages. +Using the REST API +--- + +Advantages: + + - Stable, versioned API + - Language-agnostic + - [Well-documented](http://docs.podman.io/en/latest/_static/api.html) API + +Disadvantages: + + - Error handling is less verbose than Golang API + - May be slower + Running as a subprocess --- @@ -35,12 +49,12 @@ Disadvantages: Varlink --- -Some code exists for this; splits the difference. Future uncertain. +The Varlink API is presently deprecated. We do not recommend adopting it for new projects. Making the choice --- A good question to ask first is: Do you want users to be able to use `podman` to manipulate the containers created by your project? -If so, that makes it more likely that you want to run `podman` as a subprocess. If you want a separate image store and a fundamentally +If so, that makes it more likely that you want to run `podman` as a subprocess or using the HTTP API. If you want a separate image store and a fundamentally different experience; if what you're doing with containers is quite different from those created by the `podman` CLI, that may drive you towards vendoring. diff --git a/docs/tutorials/rootless_tutorial.md b/docs/tutorials/rootless_tutorial.md index 8e048c746..93726b3b1 100644 --- a/docs/tutorials/rootless_tutorial.md +++ b/docs/tutorials/rootless_tutorial.md @@ -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. |