summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorOpenShift Merge Robot <openshift-merge-robot@users.noreply.github.com>2020-07-20 14:11:17 -0400
committerGitHub <noreply@github.com>2020-07-20 14:11:17 -0400
commit0d26a573e3cf8cc5baea84206a86cb83b433b6d5 (patch)
treefc86e361ff0fd566310262399fec67f94da6514a /docs
parente8de509be5b6ff65088a204a5bb5fd32987f561d (diff)
parent020d81f113ea1e11398ea77495cc4b8e05a91d38 (diff)
downloadpodman-0d26a573e3cf8cc5baea84206a86cb83b433b6d5.tar.gz
podman-0d26a573e3cf8cc5baea84206a86cb83b433b6d5.tar.bz2
podman-0d26a573e3cf8cc5baea84206a86cb83b433b6d5.zip
Merge pull request #6895 from QiWang19/pr-3457
Add support for overlay volume mounts in podman.
Diffstat (limited to 'docs')
-rw-r--r--docs/source/markdown/podman-create.1.md68
-rw-r--r--docs/source/markdown/podman-run.1.md43
2 files changed, 93 insertions, 18 deletions
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: <sup>[[1]](#Footnote1)</sup>
+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: <sup>[[1]](#Footnote1)</sup>
-* [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 <dwalsh@redhat.com>
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: <sup>[[1]](#Footnote1)</sup>
* [**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 <somalley@redhat.com>
-July 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
-
June 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
April 2014, Originally compiled by William Henry <whenry@redhat.com> based on docker.com source material and internal work.