From 020d81f113ea1e11398ea77495cc4b8e05a91d38 Mon Sep 17 00:00:00 2001 From: Qi Wang Date: Thu, 9 Jul 2020 15:46:14 -0400 Subject: Add support for overlay volume mounts in podman. Add support -v for overlay volume mounts in podman. Signed-off-by: Daniel J Walsh Signed-off-by: Qi Wang --- docs/source/markdown/podman-create.1.md | 68 ++++++++++++++++++++++++++------- docs/source/markdown/podman-run.1.md | 43 +++++++++++++++++++-- 2 files changed, 93 insertions(+), 18 deletions(-) (limited to 'docs/source/markdown') diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index 4466e6616..dd68f5c39 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -811,7 +811,7 @@ Create a tmpfs mount Mount a temporary filesystem (`tmpfs`) mount into a container, for example: -$ podman run -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image +$ podman create -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image This command mounts a `tmpfs` at `/tmp` within the container. The supported mount options are the same as the Linux default `mount` flags. If you do not specify @@ -887,15 +887,20 @@ Set the UTS mode for the container Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, podman bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the podman -container. The `OPTIONS` are a comma delimited list and can be: [[1]](#Footnote1) +container. Similarly, `-v SOURCE-VOLUME:/CONTAINER-DIR` will mount the volume +in the host to the container. If no such named volume exists, Podman will +create one. The `OPTIONS` are a comma delimited list and can be: [[1]](#Footnote1) -* [rw|ro] -* [z|Z] -* [`[r]shared`|`[r]slave`|`[r]private`] -* [`[r]bind`] -* [`noexec`|`exec`] -* [`nodev`|`dev`] -* [`nosuid`|`suid`] +The _options_ is a comma delimited list and can be: + +* **rw**|**ro** +* **z**|**Z** +* [**r**]**shared**|[**r**]**slave**|[**r**]**private** +* [**r**]**bind** +* [**no**]**exec** +* [**no**]**dev** +* [**no**]**suid** +* [**O**] The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The volume will be mounted into the container at this directory. @@ -908,18 +913,22 @@ the container is removed via the `--rm` flag or `podman rm --volumes`. If a volume source is specified, it must be a path on the host or the name of a named volume. Host paths are allowed to be absolute or relative; relative paths are resolved relative to the directory Podman is run in. Any source that does -not begin with a `.` or `/` it will be treated as the name of a named volume. +not begin with a `.` or `/` will be treated as the name of a named volume. If a volume with that name does not exist, it will be created. Volumes created -with names are not anonymous and are not removed by `--rm` and -`podman rm --volumes`. +with names are not anonymous. They are not removed by the `--rm` option and the +`podman rm --volumes` command. You can specify multiple **-v** options to mount one or more volumes into a container. -You can add `:ro` or `:rw` suffix to a volume to mount it read-only or + `Write Protected Volume Mounts` + +You can add `:ro` or `:rw` suffix to a volume to mount it read-only or read-write mode, respectively. By default, the volumes are mounted read-write. See examples. + `Labeling Volume Mounts` + Labeling systems like SELinux require that proper labels are placed on volume content mounted into a container. Without a label, the security system might prevent the processes running inside the container from using the content. By @@ -933,6 +942,37 @@ content label. Shared volume labels allow all containers to read/write content. The `Z` option tells Podman to label the content with a private unshared label. Only the current container can use a private volume. + `Overlay Volume Mounts` + + The `:O` flag tells Podman to mount the directory from the host as a +temporary storage using the `overlay file system`. The container processes +can modify content within the mountpoint which is stored in the +container storage in a separate directory. In overlay terms, the source +directory will be the lower, and the container storage directory will be the +upper. Modifications to the mount point are destroyed when the container +finishes executing, similar to a tmpfs mount point being unmounted. + + Subsequent executions of the container will see the original source directory +content, any changes from previous container executions no longer exists. + + One use case of the overlay mount is sharing the package cache from the +host into the container to allow speeding up builds. + + Note: + + - The `O` flag conflicts with other options listed above. +Content mounted into the container is labeled with the private label. + On SELinux systems, labels in the source directory must be readable +by the container label. Usually containers can read/execute `container_share_t` +and can read/write `container_file_t`. If you can not change the labels on a +source volume, SELinux container separation must be disabled for the container +to work. + - The source directory mounted into the container with an overlay mount +should not be modified, it can cause unexpected failures. It is recommended +that you do not modify the directory until the container finishes running. + + `Mounts propagation` + By default bind mounted volumes are `private`. That means any mounts done inside container will not be visible on host and vice versa. One can change this behavior by specifying a volume mount propagation property. Making a @@ -1110,7 +1150,7 @@ b NOTE: Use the environment variable `TMPDIR` to change the temporary storage location of downloaded container images. Podman defaults to use `/var/tmp`. ## SEE ALSO -subgid(5), subuid(5), libpod.conf(5), systemd.unit(5), setsebool(8), slirp4netns(1), fuse-overlayfs(1) +**subgid**(5), **subuid**(5), **libpod.conf**(5), **systemd.unit**(5), **setsebool**(8), **slirp4netns**(1), **fuse-overlayfs**(1). ## HISTORY October 2017, converted from Docker documentation to Podman by Dan Walsh for Podman diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index de1d8aff6..c69f41a39 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -936,6 +936,7 @@ The _options_ is a comma delimited list and can be: [[1]](#Footnote1) * [**no**]**exec** * [**no**]**dev** * [**no**]**suid** +* [**O**] The _container-dir_ must be an absolute path. @@ -947,7 +948,7 @@ the container is removed via the **--rm** flag or **podman rm --volumes**. If a volume source is specified, it must be a path on the host or the name of a named volume. Host paths are allowed to be absolute or relative; relative paths are resolved relative to the directory Podman is run in. Any source that does -not begin with a **.** or **/** it will be treated as the name of a named volume. +not begin with a **.** or **/** will be treated as the name of a named volume. If a volume with that name does not exist, it will be created. Volumes created with names are not anonymous and are not removed by **--rm** and **podman rm --volumes**. @@ -958,6 +959,8 @@ container. You can add **:ro** or **:rw** option to mount a volume in read-only or read-write mode, respectively. By default, the volumes are mounted read-write. + `Labeling Volume Mounts` + Labeling systems like SELinux require that proper labels are placed on volume content mounted into a container. Without a label, the security system might prevent the processes running inside the container from using the content. By @@ -969,9 +972,41 @@ objects on the shared volumes. The **z** option tells Podman that two containers share the volume content. As a result, Podman labels the content with a shared content label. Shared volume labels allow all containers to read/write content. The **Z** option tells Podman to label the content with a private unshared label. + + `Overlay Volume Mounts` + + The `:O` flag tells Podman to mount the directory from the host as a +temporary storage using the `overlay file system`. The container processes +can modify content within the mountpoint which is stored in the +container storage in a separate directory. In overlay terms, the source +directory will be the lower, and the container storage directory will be the +upper. Modifications to the mount point are destroyed when the container +finishes executing, similar to a tmpfs mount point being unmounted. + + Subsequent executions of the container will see the original source directory +content, any changes from previous container executions no longer exists. + + One use case of the overlay mount is sharing the package cache from the +host into the container to allow speeding up builds. + + Note: + + - The `O` flag conflicts with other options listed above. +Content mounted into the container is labeled with the private label. + On SELinux systems, labels in the source directory must be readable +by the container label. Usually containers can read/execute `container_share_t` +and can read/write `container_file_t`. If you can not change the labels on a +source volume, SELinux container separation must be disabled for the container +to work. + - The source directory mounted into the container with an overlay mount +should not be modified, it can cause unexpected failures. It is recommended +that you do not modify the directory until the container finishes running. + Only the current container can use a private volume. -By default bind mounted volumes are **private**. That means any mounts done + `Mounts propagation` + +By default bind mounted volumes are `private`. That means any mounts done inside container will not be visible on host and vice versa. One can change this behavior by specifying a volume mount propagation property. Making a volume shared mounts done under that volume inside container will be @@ -1228,6 +1263,8 @@ considered as an orphan and wiped if you execute **podman volume prune**: $ podman run -v /var/db:/data1 -i -t fedora bash $ podman run -v data:/data2 -i -t fedora bash + +$ podman run -v /var/cache/dnf:/var/cache/dnf:O -ti fedora dnf -y update ``` Using **--mount** flags to mount a host directory as a container folder, specify @@ -1398,8 +1435,6 @@ October 2017, converted from Docker documentation to Podman by Dan Walsh for Pod November 2015, updated by Sally O'Malley -July 2014, updated by Sven Dowideit - June 2014, updated by Sven Dowideit April 2014, Originally compiled by William Henry based on docker.com source material and internal work. -- cgit v1.2.3-54-g00ecf