diff --git a/docs/source/markdown/options/device-cgroup-rule.md b/docs/source/markdown/options/device-cgroup-rule.md index 528c5e1f00..cceb20e453 100644 --- a/docs/source/markdown/options/device-cgroup-rule.md +++ b/docs/source/markdown/options/device-cgroup-rule.md @@ -4,7 +4,9 @@ ####> are applicable to all of those. #### **--device-cgroup-rule**=*"type major:minor mode"* -Add a rule to the cgroup allowed devices list. The rule is expected to be in the format specified in the Linux kernel documentation (Documentation/cgroup-v1/devices.txt): - - type: a (all), c (char), or b (block); - - major and minor: either a number, or * for all; - - mode: a composition of r (read), w (write), and m (mknod(2)). +Add a rule to the cgroup allowed devices list. The rule is expected to be +in the format specified in the Linux kernel documentation +[admin-guide/cgroup-v1/devices](https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/devices.html): +- *type*: `a` (all), `c` (char), or `b` (block); +- *major* and *minor*: either a number, or `*` for all; +- *mode*: a composition of `r` (read), `w` (write), and `m` (mknod(2)). diff --git a/docs/source/markdown/options/mount.md b/docs/source/markdown/options/mount.md index cc684c2556..9a14b39fd1 100644 --- a/docs/source/markdown/options/mount.md +++ b/docs/source/markdown/options/mount.md @@ -6,97 +6,99 @@ Attach a filesystem mount to the container -Current supported mount TYPEs are **bind**, **devpts**, **glob**, **image**, **ramfs**, **tmpfs** and **volume**. [[1]](#Footnote1) +Current supported mount TYPEs are **bind**, **devpts**, **glob**, **image**, **ramfs**, **tmpfs** and **volume**. - e.g. - type=bind,source=/path/on/host,destination=/path/in/container +Options common to all mount types: - type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared +- *src*, *source*: mount source spec for **bind**, **glob**, and **volume**. + Mandatory for **bind** and **glob**. - type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared,U=true +- *dst*, *destination*, *target*: mount destination spec. - type=devpts,destination=/dev/pts +When source globs are specified without the destination directory, +the files and directories are mounted with their complete path +within the container. When the destination is specified, the +files and directories matching the glob on the base file name +on the destination directory are mounted. The option +`type=glob,src=/foo*,destination=/tmp/bar` tells container engines +to mount host files matching /foo* to the /tmp/bar/ +directory in the container. - type=glob,src=/usr/lib/libfoo*,destination=/usr/lib,ro=true +Options specific to type=**volume**: - type=image,source=fedora,destination=/fedora-image,rw=true +- *ro*, *readonly*: *true* or *false* (default if unspecified: *false*). - type=ramfs,tmpfs-size=512M,destination=/path/in/container +- *U*, *chown*: *true* or *false* (default if unspecified: *false*). Recursively change the owner and group of the source volume based on the UID and GID of the container. - type=tmpfs,tmpfs-size=512M,destination=/path/in/container +- *idmap*: If specified, create an idmapped mount to the target user namespace in the container. + The idmap option supports a custom mapping that can be different than the user namespace used by the container. + The mapping can be specified after the idmap option like: `idmap=uids=0-1-10#10-11-10;gids=0-100-10`. For each triplet, the first value is the + start of the backing file system IDs that are mapped to the second value on the host. The length of this mapping is given in the third value. + Multiple ranges are separated with #. If the specified mapping is prepended with a '@' then the mapping is considered relative to the container + user namespace. The host ID for the mapping is changed to account for the relative position of the container user in the container user namespace. - type=tmpfs,destination=/path/in/container,noswap +Options specific to type=**image**: - type=volume,source=vol1,destination=/path/in/container,ro=true +- *rw*, *readwrite*: *true* or *false* (default if unspecified: *false*). - Common Options: +Options specific to **bind** and **glob**: - · src, source: mount source spec for bind, glob, and volume. Mandatory for bind and glob. +- *ro*, *readonly*: *true* or *false* (default if unspecified: *false*). - · dst, destination, target: mount destination spec. +- *bind-propagation*: *shared*, *slave*, *private*, *unbindable*, *rshared*, *rslave*, *runbindable*, or **rprivate** (default).[[1]](#Footnote1) See also mount(2). - When source globs are specified without the destination directory, - the files and directories are mounted with their complete path - within the container. When the destination is specified, the - files and directories matching the glob on the base file name - on the destination directory are mounted. The option - `type=glob,src=/foo*,destination=/tmp/bar` tells container engines - to mount host files matching /foo* to the /tmp/bar/ - directory in the container. +- *bind-nonrecursive*: do not set up a recursive bind mount. By default it is recursive. - Options specific to volume: +- *relabel*: *shared*, *private*. - · ro, readonly: true or false (default). +- *idmap*: *true* or *false* (default if unspecified: *false*). If true, create an idmapped mount to the target user namespace in the container. - . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container. +- *U*, *chown*: *true* or *false* (default if unspecified: *false*). Recursively change the owner and group of the source volume based on the UID and GID of the container. - · idmap: true or false (default). If specified, create an idmapped mount to the target user namespace in the container. - The idmap option supports a custom mapping that can be different than the user namespace used by the container. - The mapping can be specified after the idmap option like: `idmap=uids=0-1-10#10-11-10;gids=0-100-10`. For each triplet, the first value is the - start of the backing file system IDs that are mapped to the second value on the host. The length of this mapping is given in the third value. - Multiple ranges are separated with #. If the specified mapping is prepended with a '@' then the mapping is considered relative to the container - user namespace. The host ID for the mapping is changed to account for the relative position of the container user in the container user namespace. +- *no-dereference*: do not dereference symlinks but copy the link source into the mount destination. - Options specific to image: +Options specific to type=**tmpfs** and **ramfs**: - · rw, readwrite: true or false (default). +- *ro*, *readonly*: *true* or *false* (default if unspecified: *false*). - Options specific to bind and glob: +- *tmpfs-size*: Size of the tmpfs/ramfs mount, in bytes. Unlimited by default in Linux. - · ro, readonly: true or false (default). +- *tmpfs-mode*: Octal file mode of the tmpfs/ramfs (e.g. 700 or 0700.). - · bind-propagation: shared, slave, private, unbindable, rshared, rslave, runbindable, or rprivate(default). See also mount(2). +- *tmpcopyup*: Enable copyup from the image directory at the same location to the tmpfs/ramfs. Used by default. - . bind-nonrecursive: do not set up a recursive bind mount. By default it is recursive. +- *notmpcopyup*: Disable copying files from the image to the tmpfs/ramfs. - . relabel: shared, private. +- *U*, *chown*: *true* or *false* (default if unspecified: *false*). Recursively change the owner and group of the source volume based on the UID and GID of the container. - · idmap: true or false (default). If specified, create an idmapped mount to the target user namespace in the container. +Options specific to type=**devpts**: - . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container. +- *uid*: numeric UID of the file owner (default: 0). - . no-dereference: do not dereference symlinks but copy the link source into the mount destination. +- *gid*: numeric GID of the file owner (default: 0). - Options specific to tmpfs and ramfs: +- *mode*: octal permission mask for the file (default: 600). - · ro, readonly: true or false (default). +- *max*: maximum number of PTYs (default: 1048576). - · tmpfs-size: Size of the tmpfs/ramfs mount in bytes. Unlimited by default in Linux. +Examples: - · tmpfs-mode: File mode of the tmpfs/ramfs in octal (e.g. 700 or 0700.). +- `type=bind,source=/path/on/host,destination=/path/in/container` - · tmpcopyup: Enable copyup from the image directory at the same location to the tmpfs/ramfs. Used by default. +- `type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared` - · notmpcopyup: Disable copying files from the image to the tmpfs/ramfs. +- `type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared,U=true` - . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container. +- `type=devpts,destination=/dev/pts` - Options specific to devpts: +- `type=glob,src=/usr/lib/libfoo*,destination=/usr/lib,ro=true` - · uid: UID of the file owner (default 0). +- `type=image,source=fedora,destination=/fedora-image,rw=true` - · gid: GID of the file owner (default 0). +- `type=ramfs,tmpfs-size=512M,destination=/path/in/container` - · mode: permission mask for the file (default 600). +- `type=tmpfs,tmpfs-size=512M,destination=/path/in/container` - · max: maximum number of PTYs (default 1048576). +- `type=tmpfs,destination=/path/in/container,noswap` + +- `type=volume,source=vol1,destination=/path/in/container,ro=true` diff --git a/docs/source/markdown/options/network.md b/docs/source/markdown/options/network.md index b3be42b48a..9bb5aa0a27 100644 --- a/docs/source/markdown/options/network.md +++ b/docs/source/markdown/options/network.md @@ -15,10 +15,11 @@ Valid _mode_ values are: - **mac=MAC**: Specify a static mac address for this container. - **interface_name**: Specify a name for the created network interface inside the container. - For example to set a static ipv4 address and a static mac address, use `--network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99`. + For example, to set a static ipv4 address and a static mac address, use `--network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99`. - \[:OPTIONS,...]: Connect to a user-defined network; this is the network name or ID from a network created by **[podman network create](podman-network-create.1.md)**. Using the network name implies the bridge network mode. It is possible to specify the same options described under the bridge mode above. Use the **--network** option multiple times to specify additional networks. -For backwards compatibility it is also possible to specify networks comma separated on the first **--network** argument, however this prevents you from using the options described under the bridge section above. + + For backwards compatibility it is also possible to specify comma-separated networks on the first **--network** argument, however this prevents you from using the options described under the bridge section above. - **none**: Create a network namespace for the container but do not configure network interfaces for it, thus the container has no network connectivity. - **container:**_id_: Reuse another container's network stack. - **host**: Do not create a network namespace, the container uses the host's network. Note: The host mode gives the container full access to local system services such as D-bus and is therefore considered insecure. diff --git a/docs/source/markdown/options/volume.image.md b/docs/source/markdown/options/volume.image.md index b4715f8545..f77a99c4b8 100644 --- a/docs/source/markdown/options/volume.image.md +++ b/docs/source/markdown/options/volume.image.md @@ -7,12 +7,12 @@ Mount a host directory into containers when executing RUN instructions during the build. -The `OPTIONS` are a comma-separated list and can be: [[1]](#Footnote1) +The `OPTIONS` are a comma-separated list and can be one or more of: * [rw|ro] * [z|Z|O] * [U] - * [`[r]shared`|`[r]slave`|`[r]private`] + * [`[r]shared`|`[r]slave`|`[r]private`][[1]](#Footnote1) 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 @@ -24,7 +24,7 @@ You can add the `: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` +`Chowning Volume Mounts` By default, Podman does not change the owner and group of source volume directories mounted. When running using user namespaces, the UID and GID inside @@ -36,7 +36,7 @@ the source volume. **Warning** use with caution since this modifies the host filesystem. - `Labeling Volume Mounts` +`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 @@ -57,11 +57,11 @@ of containers, disabling SELinux separation is recommended. The option `--security-opt label=disable` disables SELinux separation for the container. For example, if a user wanted to volume mount their entire home directory into the build containers, they need to disable SELinux separation. - $ podman build --security-opt label=disable -v $HOME:/home/user . + $ podman build --security-opt label=disable -v $HOME:/home/user . - `Overlay Volume Mounts` +`Overlay Volume Mounts` - The `:O` flag tells Podman to mount the directory from the host as a +The `:O` flag tells Podman to mount the directory from the host as a temporary storage using the Overlay file system. The `RUN` command containers are allowed to modify contents within the mountpoint and are stored in the container storage in a separate directory. In Overlay FS terms the source @@ -69,23 +69,23 @@ directory is the lower, and the container storage directory is the upper. Modifications to the mount point are destroyed when the `RUN` command finishes executing, similar to a tmpfs mount point. - Any subsequent execution of `RUN` commands sees the original source directory +Any subsequent execution of `RUN` commands sees the original source directory content, any changes from previous RUN commands no longer exists. - One use case of the `overlay` mount is sharing the package cache from the +One use case of the `overlay` mount is sharing the package cache from the host into the container to allow speeding up builds. - Note: - - - Overlay mounts are not currently supported in rootless mode. - - The `O` flag is not allowed to be specified with the `Z` or `z` flags. -Content mounted into the container is labeled with the private label. - On SELinux systems, labels in the source directory needs to be readable -by the container label. If not, SELinux container separation must be disabled -for the container to work. - - Modification of the directory volume mounted into the container with an -overlay mount can cause unexpected failures. Do not modify the directory until -the container finishes running. +Note: + +- Overlay mounts are not currently supported in rootless mode. +- The `O` flag is not allowed to be specified with the `Z` or `z` flags. + Content mounted into the container is labeled with the private label. + On SELinux systems, labels in the source directory needs to be readable + by the container label. If not, SELinux container separation must be disabled + for the container to work. +- Modification of the directory volume mounted into the container with an + overlay mount can cause unexpected failures. Do not modify the directory until + the container finishes running. By default bind mounted volumes are `private`. That means any mounts done inside containers are not be visible on the host and vice versa. This behavior diff --git a/docs/source/markdown/options/volume.md b/docs/source/markdown/options/volume.md index fa1dea70b8..116ed4c078 100644 --- a/docs/source/markdown/options/volume.md +++ b/docs/source/markdown/options/volume.md @@ -15,7 +15,7 @@ the `podman rm --volumes` command. (Note when using the remote client, including Mac and Windows (excluding WSL2) machines, the volumes are mounted from the remote server, not necessarily the client machine.) -The _OPTIONS_ is a comma-separated list and can be: [[1]](#Footnote1) +The _OPTIONS_ is a comma-separated list and can be one or more of: * **rw**|**ro** * **z**|**Z** @@ -26,7 +26,7 @@ The _OPTIONS_ is a comma-separated list and can be: [[1]](#Footnote1) * [**no**]**exec** * [**no**]**suid** * [**r**]**bind** -* [**r**]**shared**|[**r**]**slave**|[**r**]**private**[**r**]**unbindable** +* [**r**]**shared**|[**r**]**slave**|[**r**]**private**[**r**]**unbindable** [[1]](#Footnote1) * **idmap**[=**options**] The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The volume @@ -46,13 +46,13 @@ option and the `podman rm --volumes` command. Specify multiple **-v** options to mount one or more volumes into a <>. - `Write Protected Volume Mounts` +`Write Protected Volume Mounts` 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. See examples. - `Chowning Volume Mounts` +`Chowning Volume Mounts` By default, Podman does not change the owner and group of source volume directories mounted into containers. If a <> is created in a new @@ -67,7 +67,7 @@ process takes a long time, delaying the start of the <>. **Warning** use with caution since this modifies the host filesystem. - `Labeling Volume Mounts` +`Labeling Volume Mounts` Labeling systems like SELinux require that proper labels are placed on volume content mounted into a <>. Without a label, the security system @@ -95,11 +95,11 @@ of containers we recommend disabling SELinux separation. The option For example if a user wanted to volume mount their entire home directory into a <>, they need to disable SELinux separation. - $ podman <> --security-opt label=disable -v $HOME:/home/user fedora touch /home/user/file + $ podman <> --security-opt label=disable -v $HOME:/home/user fedora touch /home/user/file - `Overlay Volume Mounts` +`Overlay Volume Mounts` - The `:O` flag tells Podman to mount the directory from the host as a +The `:O` flag tells Podman to mount the directory from the host as a temporary storage using the `overlay file system`. The <> processes can modify content within the mountpoint which is stored in the container storage in a separate directory. In overlay terms, the source @@ -113,31 +113,33 @@ For advanced users, the **overlay** option also supports custom non-volatile remove it on lifecycle completion. Example **:O,upperdir=/some/upper,workdir=/some/work** - Subsequent executions of the container sees the original source directory +Subsequent executions of the container sees the original source directory content, any changes from previous <> executions no longer exist. - One use case of the overlay mount is sharing the package cache from the +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. +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 +On SELinux systems, labels in the source directory must be readable by the <<|pod infra>> container label. Usually containers can read/execute `container_share_t` and can read/write `container_file_t`. If unable to change the labels on a source volume, SELinux container separation must be disabled for the <<|pod or infra>> container to work. - - Do not modify the source directory mounted into the <> with an overlay mount, it can cause unexpected failures. Only modify the directory after the container finishes running. - `Mounts propagation` +Do not modify the source directory mounted into the <> with an overlay mount, +it can cause unexpected failures. Only modify the directory after the container finishes running. -By default bind mounted volumes are `private`. That means any mounts done -inside the <> is not 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 the <> is -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 -is visible inside container but not the other way around. [[1]](#Footnote1) +`Mounts propagation` + +By default, bind-mounted volumes are `private`. That means any mounts done +inside the <> are not visible on the host and vice versa. +One can change this behavior by specifying a volume mount propagation property. +When a volume is `shared`, mounts done under that volume inside the <> +are visible on host and vice versa. Making a volume **slave**[[1]](#Footnote1) +enables only one-way mount propagation: mounts done on the host under that volume +are visible inside the container but not the other way around. To control mount propagation property of a volume one can use the [**r**]**shared**, [**r**]**slave**, [**r**]**private** or the [**r**]**unbindable** propagation flag. @@ -191,7 +193,7 @@ _/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 <> fails. - `Idmapped mount` +`Idmapped mount` If `idmap` is specified, create an idmapped mount to the target user namespace in the container. The idmap option supports a custom mapping