diff options
Diffstat (limited to 'docs/source/markdown/podman-create.1.md.in')
| -rw-r--r-- | docs/source/markdown/podman-create.1.md.in | 170 |
1 files changed, 2 insertions, 168 deletions
diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index f74429848..17ef704e6 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -539,175 +539,9 @@ Without this argument the command will be run as root in the container. #### **--variant**=*VARIANT* Use _VARIANT_ instead of the default architecture variant of the container image. Some images can use multiple variants of the arm architectures, such as arm/v5 and arm/v7. -#### **--volume**, **-v**=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]* +@@option volume -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. 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-separated list and can be: <sup>[[1]](#Footnote1)</sup> (Note when using the remote client, including Mac and Windows (excluding WSL2) machines, the volumes will be mounted from the remote server, not necessarily the client machine.) - -The _options_ is a comma-separated list and can be: - -* **rw**|**ro** -* **z**|**Z** -* [**O**] -* [**U**] -* [**no**]**copy** -* [**no**]**dev** -* [**no**]**exec** -* [**no**]**suid** -* [**r**]**bind** -* [**r**]**shared**|[**r**]**slave**|[**r**]**private**[**r**]**unbindable** - -The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The volume -will be mounted into the container at this directory. - -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 -anonymously 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. If the source does not -exist, Podman will return an error. Users must pre-create the source files or -directories. - -Any source that does 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 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. - - `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. - - `Chowning Volume Mounts` - -By default, Podman does not change the owner and group of source volume -directories mounted into containers. If a container is created in a new user -namespace, the UID and GID in the container may correspond to another UID and -GID on the host. - -The `:U` suffix tells Podman to use the correct host UID and GID based on the -UID and GID within the container, to change recursively the owner and group of -the source volume. - -**Warning** use with caution since this will modify the host filesystem. - - `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 -default, Podman does not change the labels set by the OS. - -To change a label in the container context, you can add either of two suffixes -`:z` or `:Z` to the volume mount. These suffixes tell Podman to relabel file -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. -Only the current container can use a private volume. - -Note: Do not relabel system files and directories. Relabeling system content -might cause other confined services on your machine to fail. For these types -of containers we recommend disabling SELinux separation. The option -`--security-opt label=disable` disables SELinux separation for containers used in the build. -For example if a user wanted to volume mount their entire home directory into a -container, they need to disable SELinux separation. - - $ podman create --security-opt label=disable -v $HOME:/home/user fedora touch /home/user/file - - `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 exist. - - 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 cannot 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 -volume `shared` mounts done under that volume inside container will be -visible on host and vice versa. Making a volume `slave` enables only one -way mount propagation and that is mounts done on host under that volume -will be visible inside container but not the other way around. <sup>[[1]](#Footnote1)</sup> - -To control mount propagation property of a volume one can use the [**r**]**shared**, -[**r**]**slave**, [**r**]**private** or the [**r**]**unbindable** propagation flag. -For mount propagation to work the source mount point (the mount point where source dir -is mounted on) has to have the right propagation properties. For shared volumes, the -source mount point has to be shared. And for slave volumes, the source mount point -has to be either shared or slave. <sup>[[1]](#Footnote1)</sup> - -If you want to recursively mount a volume and all of its submounts into a -container, then you can use the `rbind` option. By default the bind option is -used, and submounts of the source directory will not be mounted into the -container. - -Mounting the volume with the `nosuid` options means that SUID applications on -the volume will not be able to change their privilege. By default volumes -are mounted with `nosuid`. - -Mounting the volume with the noexec option means that no executables on the -volume will be able to be executed within the container. - -Mounting the volume with the nodev option means that no devices on the volume -will be able to be used by processes within the container. By default volumes -are mounted with `nodev`. - -If the `<source-dir>` is a mount point, then "dev", "suid", and "exec" options are -ignored by the kernel. - -Use `df <source-dir>` to figure out the source mount and then use -`findmnt -o TARGET,PROPAGATION <source-mount-dir>` to figure out propagation -properties of source mount. If `findmnt` utility is not available, then one -can look at mount entry for source mount point in `/proc/self/mountinfo`. Look -at `optional fields` and see if any propagation properties are specified. -`shared:X` means mount is `shared`, `master:X` means mount is `slave` and if -nothing is there that means mount is `private`. <sup>[[1]](#Footnote1)</sup> - -To change propagation properties of a mount point use `mount` command. For -example, if one wants to bind mount source directory `/foo` one can do -`mount --bind /foo /foo` and `mount --make-private --make-shared /foo`. This -will convert /foo into a `shared` mount point. Alternatively one can directly -change propagation properties of source mount. Say `/` is source mount for -`/foo`, then use `mount --make-shared /` to convert `/` into a `shared` mount. - -Note: if the user only has access rights via a group, accessing the volume -from inside a rootless container will fail. Use the `--group-add keep-groups` -flag to pass the user's supplementary group access into the container. +Use the **--group-add keep-groups** option to pass the user's supplementary group access into the container. #### **--volumes-from**=*CONTAINER[:OPTIONS]]* |