summaryrefslogtreecommitdiff
path: root/docs/podman-run.1.md
diff options
context:
space:
mode:
authorMatthew Heon <matthew.heon@pm.me>2019-10-17 11:25:28 -0400
committerMatthew Heon <matthew.heon@pm.me>2019-10-17 13:18:17 -0400
commit0d623914d01bcbc10beebf2db966e17da215dfbb (patch)
tree00ef58cddd025309918465e447d34bd5f26b644d /docs/podman-run.1.md
parentd7cbcfadd07e9c79831e51de294b307b00292d49 (diff)
downloadpodman-0d623914d01bcbc10beebf2db966e17da215dfbb.tar.gz
podman-0d623914d01bcbc10beebf2db966e17da215dfbb.tar.bz2
podman-0d623914d01bcbc10beebf2db966e17da215dfbb.zip
Add support for anonymous volumes to `podman run -v`
Previously, when `podman run` encountered a volume mount without separate source and destination (e.g. `-v /run`) we would assume that both were the same - a bind mount of `/run` on the host to `/run` in the container. However, this does not match Docker's behavior - in Docker, this makes an anonymous named volume that will be mounted at `/run`. We already have (more limited) support for these anonymous volumes in the form of image volumes. Extend this support to allow it to be used with user-created volumes coming in from the `-v` flag. This change also affects how named volumes created by the container but given names are treated by `podman run --rm` and `podman rm -v`. Previously, they would be removed with the container in these cases, but this did not match Docker's behaviour. Docker only removed anonymous volumes. With this patch we move to that model as well; `podman run -v testvol:/test` will not have `testvol` survive the container being removed by `podman rm -v`. The sum total of these changes let us turn on volume removal in `--rm` by default. Fixes: #4276 Signed-off-by: Matthew Heon <matthew.heon@pm.me>
Diffstat (limited to 'docs/podman-run.1.md')
-rw-r--r--docs/podman-run.1.md22
1 files changed, 17 insertions, 5 deletions
diff --git a/docs/podman-run.1.md b/docs/podman-run.1.md
index 602aa69ed..9a92aba82 100644
--- a/docs/podman-run.1.md
+++ b/docs/podman-run.1.md
@@ -839,7 +839,7 @@ Set the UTS mode for the container
**NOTE**: the host mode gives the container access to changing the host's hostname and is therefore considered insecure.
-**--volume**, **-v**[=*[HOST-DIR-OR-VOUME-NAME:CONTAINER-DIR[:OPTIONS]]*]
+**--volume**, **-v**[=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*]
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
@@ -853,11 +853,23 @@ create one.
* [`z`|`Z`]
* [`[r]shared`|`[r]slave`|`[r]private`]
-The `/CONTAINER-DIR` must be an absolute path such as `/src/docs`. The `/HOST-DIR`
-must be an absolute path as well. Podman bind-mounts the `HOST-DIR` to the
-path you specify. For example, if you supply the `/foo` value, Podman creates a bind-mount.
+The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The volume
+will be mounted into the container at this directory.
-You can specify multiple **-v** options to mount one or more mounts to a
+Volumes may specify a source as well, as either a directory on the host or the
+name of a named volume. If no source is given, the volume will be created as an
+anonymous named volume with a randomly generated name, and will be removed when
+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.
+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`.
+
+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