github.com/containers/podman/v5@v5.1.0-rc1/docs/source/markdown/options/volume.image.md (about)

     1  ####> This option file is used in:
     2  ####>   podman build, farm build
     3  ####> If file is edited, make sure the changes
     4  ####> are applicable to all of those.
     5  #### **--volume**, **-v**=*[HOST-DIR:CONTAINER-DIR[:OPTIONS]]*
     6  
     7  Mount a host directory into containers when executing RUN instructions during
     8  the build.
     9  
    10  The `OPTIONS` are a comma-separated list and can be one or more of:
    11  
    12     * [rw|ro]
    13     * [z|Z|O]
    14     * [U]
    15     * [`[r]shared`|`[r]slave`|`[r]private`]<sup>[[1]](#Footnote1)</sup>
    16  
    17  The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The `HOST-DIR`
    18  must be an absolute path as well. Podman bind-mounts the `HOST-DIR` to the
    19  specified path when processing RUN instructions.
    20  
    21  You can specify multiple  **-v** options to mount one or more mounts.
    22  
    23  You can add the `:ro` or `:rw` suffix to a volume to mount it read-only or
    24  read-write mode, respectively. By default, the volumes are mounted read-write.
    25  See examples.
    26  
    27  `Chowning Volume Mounts`
    28  
    29  By default, Podman does not change the owner and group of source volume
    30  directories mounted. When running using user namespaces, the UID and GID inside
    31  the namespace may correspond to another UID and GID on the host.
    32  
    33  The `:U` suffix tells Podman to use the correct host UID and GID based on the
    34  UID and GID within the namespace, to change recursively the owner and group of
    35  the source volume.
    36  
    37  **Warning** use with caution since this modifies the host filesystem.
    38  
    39  `Labeling Volume Mounts`
    40  
    41  Labeling systems like SELinux require that proper labels are placed on volume
    42  content mounted into a container. Without a label, the security system might
    43  prevent the processes running inside the container from using the content. By
    44  default, Podman does not change the labels set by the OS.
    45  
    46  To change a label in the container context, add one of these two suffixes
    47  `:z` or `:Z` to the volume mount. These suffixes tell Podman to relabel file
    48  objects on the shared volumes. The `z` option tells Podman that two containers
    49  share the volume content. As a result, Podman labels the content with a shared
    50  content label. Shared volume labels allow all containers to read/write content.
    51  The `Z` option tells Podman to label the content with a private unshared label.
    52  Only the current container can use a private volume.
    53  
    54  Note: Do not relabel system files and directories. Relabeling system content
    55  might cause other confined services on the host machine to fail.  For these types
    56  of containers, disabling SELinux separation is recommended.  The option
    57  `--security-opt label=disable` disables SELinux separation for the container.
    58  For example, if a user wanted to volume mount their entire home directory into the build containers, they need to disable SELinux separation.
    59  
    60      $ podman build --security-opt label=disable -v $HOME:/home/user .
    61  
    62  `Overlay Volume Mounts`
    63  
    64  The `:O` flag tells Podman to mount the directory from the host as a
    65  temporary storage using the Overlay file system. The `RUN` command containers
    66  are allowed to modify contents within the mountpoint and are stored in the
    67  container storage in a separate directory.  In Overlay FS terms the source
    68  directory is the lower, and the container storage directory is the
    69  upper. Modifications to the mount point are destroyed when the `RUN` command
    70  finishes executing, similar to a tmpfs mount point.
    71  
    72  Any subsequent execution of `RUN` commands sees the original source directory
    73  content, any changes from previous RUN commands no longer exists.
    74  
    75  One use case of the `overlay` mount is sharing the package cache from the
    76  host into the container to allow speeding up builds.
    77  
    78  Note:
    79  
    80  - Overlay mounts are not currently supported in rootless mode.
    81  - The `O` flag is not allowed to be specified with the `Z` or `z` flags.
    82    Content mounted into the container is labeled with the private label.
    83    On SELinux systems, labels in the source directory needs to be readable
    84    by the container label. If not, SELinux container separation must be disabled
    85    for the container to work.
    86  - Modification of the directory volume mounted into the container with an
    87    overlay mount can cause unexpected failures. Do not modify the directory until
    88    the container finishes running.
    89  
    90  By default bind mounted volumes are `private`. That means any mounts done
    91  inside containers are not be visible on the host and vice versa. This behavior
    92  can be changed by specifying a volume mount propagation property.
    93  
    94  When the mount propagation policy is set to `shared`, any mounts completed
    95  inside the container on that volume is visible to both the host and
    96  container. When the mount propagation policy is set to `slave`, one way mount
    97  propagation is enabled and any mounts completed on the host for that volume is
    98  visible only inside of the container. To control the mount propagation
    99  property of volume use the `:[r]shared`, `:[r]slave` or `:[r]private`
   100  propagation flag. For mount propagation to work on the source mount point (mount
   101  point where source dir is mounted on) has to have the right propagation properties.
   102  For shared volumes, the source mount point has to be shared. And for slave volumes,
   103  the source mount has to be either shared or slave. <sup>[[1]](#Footnote1)</sup>
   104  
   105  Use `df <source-dir>` to determine the source mount and then use
   106  `findmnt -o TARGET,PROPAGATION <source-mount-dir>` to determine propagation
   107  properties of source mount, if `findmnt` utility is not available, the source
   108  mount point can be determined by looking at the mount entry in
   109  `/proc/self/mountinfo`. Look at `optional fields` and see if any propagation
   110  properties are specified.
   111  `shared:X` means the mount is `shared`, `master:X` means the mount is `slave`
   112  and if nothing is there that means the mount is `private`. <sup>[[1]](#Footnote1)</sup>
   113  
   114  To change propagation properties of a mount point use the `mount` command. For
   115  example, to bind mount the source directory `/foo` do
   116  `mount --bind /foo /foo` and `mount --make-private --make-shared /foo`. This
   117  converts /foo into a `shared` mount point.  The propagation properties of
   118  the source mount can be changed directly. For instance if `/` is the source
   119  mount for `/foo`, then use `mount --make-shared /` to convert `/` into a
   120  `shared` mount.