mirror of
https://github.com/containers/podman.git
synced 2025-06-19 00:06:43 +08:00
Merge pull request #21010 from edsantiago/docs_formatting
[CI:DOCS] doc cleanup
This commit is contained in:
openshift-merge-bot[bot]
@ -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)).
|
||||
|
||||
@ -6,97 +6,99 @@
|
||||
|
||||
Attach a filesystem mount to the container
|
||||
|
||||
Current supported mount TYPEs are **bind**, **devpts**, **glob**, **image**, **ramfs**, **tmpfs** and **volume**. <sup>[[1]](#Footnote1)</sup>
|
||||
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).<sup>[[1]](#Footnote1)</sup> 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`
|
||||
|
||||
@ -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`.
|
||||
|
||||
- \<network name or ID\>[: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.
|
||||
|
||||
@ -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: <sup>[[1]](#Footnote1)</sup>
|
||||
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`]<sup>[[1]](#Footnote1)</sup>
|
||||
|
||||
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:
|
||||
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.
|
||||
- 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
|
||||
|
||||
@ -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: <sup>[[1]](#Footnote1)</sup>
|
||||
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: <sup>[[1]](#Footnote1)</sup>
|
||||
* [**no**]**exec**
|
||||
* [**no**]**suid**
|
||||
* [**r**]**bind**
|
||||
* [**r**]**shared**|[**r**]**slave**|[**r**]**private**[**r**]**unbindable**
|
||||
* [**r**]**shared**|[**r**]**slave**|[**r**]**private**[**r**]**unbindable** <sup>[[1]](#Footnote1)</sup>
|
||||
* **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
|
||||
<<container|pod>>.
|
||||
|
||||
`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 <<container|pod>> is created in a new
|
||||
@ -67,7 +67,7 @@ process takes a long time, delaying the start of the <<container|pod>>.
|
||||
|
||||
**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|pod>>. 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
|
||||
<<container|pod>>, they need to disable SELinux separation.
|
||||
|
||||
$ podman <<fullsubcommand>> --security-opt label=disable -v $HOME:/home/user fedora touch /home/user/file
|
||||
$ podman <<fullsubcommand>> --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 <<container|pod>> 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 <<container|pod>> 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 <<container|pod>> 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 <<container|pod>> 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 <<container|pod>> 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 <<container|pod>> 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. <sup>[[1]](#Footnote1)</sup>
|
||||
`Mounts propagation`
|
||||
|
||||
By default, bind-mounted volumes are `private`. That means any mounts done
|
||||
inside the <<container|pod>> 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 <<container|pod>>
|
||||
are visible on host and vice versa. Making a volume **slave**<sup>[[1]](#Footnote1)</sup>
|
||||
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 <<container|pod>> 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
|
||||
|
||||
Reference in New Issue
Block a user