From 10290d462b21e5d9e0457fd936bcc60ed662791d Mon Sep 17 00:00:00 2001 From: Alexander Gramiak Date: Mon, 24 Mar 2025 15:44:19 -0600 Subject: [PATCH] docs: Improve spelling and formatting Signed-off-by: Alexander Gramiak --- docs/source/locale/ja/LC_MESSAGES/markdown.po | 10 ++++----- docs/source/markdown/options/entrypoint.md | 2 +- docs/source/markdown/options/mount.md | 8 +++---- docs/source/markdown/options/publish.md | 2 +- docs/source/markdown/options/secret.md | 4 ++-- docs/source/markdown/options/systemd.md | 2 +- docs/source/markdown/options/umask.md | 2 +- docs/source/markdown/options/volume.md | 12 +++++----- docs/source/markdown/podman-cp.1.md | 8 +++---- docs/source/markdown/podman-image-prune.1.md | 2 +- docs/source/markdown/podman-run.1.md.in | 2 +- .../source/markdown/podman-secret-create.1.md | 2 +- docs/source/markdown/podman-systemd.unit.5.md | 22 +++++++++---------- 13 files changed, 40 insertions(+), 38 deletions(-) diff --git a/docs/source/locale/ja/LC_MESSAGES/markdown.po b/docs/source/locale/ja/LC_MESSAGES/markdown.po index a7c4b48952..4b4f1ae83c 100644 --- a/docs/source/locale/ja/LC_MESSAGES/markdown.po +++ b/docs/source/locale/ja/LC_MESSAGES/markdown.po @@ -10357,8 +10357,8 @@ msgid "" " secrets, this is the path to the secret inside the container." " If a fully qualified path is provided, the secret " "is mounted at that location. Otherwise, the secret " -"is mounted to `/run/secrets/target` for linux " -"containers or `/var/run/secrets/target` for freebsd" +"is mounted to `/run/secrets/target` for Linux " +"containers or `/var/run/secrets/target` for FreeBSD" " containers. If the target is not set, the secret " "is mounted to `/run/secrets/secretname` by default." " For env secrets, this is the environment variable " @@ -11803,7 +11803,7 @@ msgid "" " that two or more 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 " +" Podman to label the content with a private unshared label. Only the " "current container can use a private volume. Relabeling walks the file " "system under the volume and changes the label on each file, if the volume" " has thousands of inodes, this process takes a long time, delaying the " @@ -25306,7 +25306,7 @@ msgstr "" #: ../../source/markdown/podman-run.1.md:2595 msgid "" -"If the container needs a writeable mounted volume by a non root user " +"If the container needs a writable mounted volume by a non root user " "inside the container, use the **U** option. This option tells Podman to " "chown the source volume to match the default UID and GID used within the " "container." @@ -28399,7 +28399,7 @@ msgstr "" #: ../../source/markdown/podman-systemd.unit.5.md:269 msgid "" "The (numeric) GID to run as inside the container. This does not need to " -"match the GID on the host, which can be modified with `UsersNS`, but if " +"match the GID on the host, which can be modified with `UserNS`, but if " "that is not specified, this GID is also used on the host." msgstr "" diff --git a/docs/source/markdown/options/entrypoint.md b/docs/source/markdown/options/entrypoint.md index 8ee5d11a1e..78fb05a818 100644 --- a/docs/source/markdown/options/entrypoint.md +++ b/docs/source/markdown/options/entrypoint.md @@ -15,4 +15,4 @@ passed in via the COMMAND. But, if a user wants to run something else inside the container, the **--entrypoint** option allows a new ENTRYPOINT to be specified. -Specify multi option commands in the form of a json string. +Specify multi option commands in the form of a JSON string. diff --git a/docs/source/markdown/options/mount.md b/docs/source/markdown/options/mount.md index c2e9859767..39dafa9304 100644 --- a/docs/source/markdown/options/mount.md +++ b/docs/source/markdown/options/mount.md @@ -4,7 +4,7 @@ ####> are applicable to all of those. #### **--mount**=*type=TYPE,TYPE-SPECIFIC-OPTION[,...]* -Attach a filesystem mount to the container +Attach a filesystem mount to the container. Current supported mount TYPEs are **artifact**, **bind**, **devpts**, **glob**, **image**, **ramfs**, **tmpfs** and **volume**. @@ -32,7 +32,7 @@ Options specific to type=**artifact**: - *title*: If the artifact source contains multiple blobs a title can be set which is compared against `org.opencontainers.image.title` annotation. -The *src* argument contains the name of the artifact, it must already exist locally. +The *src* argument contains the name of the artifact, which must already exist locally. The *dst* argument contains the target path, if the path in the container is a directory or does not exist the blob title (`org.opencontainers.image.title` annotation) will be used as filename and joined to the path. If the annotation @@ -50,11 +50,11 @@ Options specific to type=**volume**: - *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*: If specified, create an idmapped mount to the target user namespace in the container. - The idmap option is only supported by Podman in rootful mode. The Linux kernel does not allow the use of idmaped file systems for unprivileged users. + The idmap option is only supported by Podman in rootful mode. The Linux kernel does not allow the use of idmapped file systems for unprivileged users. 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 + 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. Options specific to type=**image**: diff --git a/docs/source/markdown/options/publish.md b/docs/source/markdown/options/publish.md index dfe8867567..d55679d235 100644 --- a/docs/source/markdown/options/publish.md +++ b/docs/source/markdown/options/publish.md @@ -23,4 +23,4 @@ If it is not, the container port is randomly assigned a port on the host. Use **podman port** to see the actual mapping: `podman port $CONTAINER $CONTAINERPORT`. Note that the network drivers `macvlan` and `ipvlan` do not support port forwarding, -it will have no effect on these networks. +therefore this option will have no effect on such networks. diff --git a/docs/source/markdown/options/secret.md b/docs/source/markdown/options/secret.md index 3df13c369c..47c336a503 100644 --- a/docs/source/markdown/options/secret.md +++ b/docs/source/markdown/options/secret.md @@ -27,8 +27,8 @@ Secret Options For mounted secrets, this is the path to the secret inside the container. If a fully qualified path is provided, the secret is mounted at that location. Otherwise, the secret is mounted to - `/run/secrets/target` for linux containers or - `/var/run/secrets/target` for freebsd containers. + `/run/secrets/target` for Linux containers or + `/var/run/secrets/target` for FreeBSD containers. If the target is not set, the secret is mounted to `/run/secrets/secretname` by default. For env secrets, this is the environment variable key. Defaults to `secretname`. - `uid=0` : UID of secret. Defaults to 0. Mount secret type only. diff --git a/docs/source/markdown/options/systemd.md b/docs/source/markdown/options/systemd.md index 7bc66565c8..057cf7399d 100644 --- a/docs/source/markdown/options/systemd.md +++ b/docs/source/markdown/options/systemd.md @@ -25,7 +25,7 @@ Running the container in systemd mode causes the following changes: * Podman sets **container_uuid** environment variable in the container to the first 32 characters of the container ID. * Podman does not mount virtual consoles (_/dev/tty\d+_) when running with **--privileged**. -* On cgroup v2, */sys/fs/cgroup* is mounted writeable. +* On cgroup v2, */sys/fs/cgroup* is mounted writable. This allows systemd to run in a confined container without any modifications. diff --git a/docs/source/markdown/options/umask.md b/docs/source/markdown/options/umask.md index 389eba9f49..812c0b00b8 100644 --- a/docs/source/markdown/options/umask.md +++ b/docs/source/markdown/options/umask.md @@ -5,4 +5,4 @@ #### **--umask**=*umask* Set the umask inside the container. Defaults to `0022`. -Remote connections use local containers.conf for defaults +Remote connections use the local `containers.conf` for defaults. diff --git a/docs/source/markdown/options/volume.md b/docs/source/markdown/options/volume.md index cd58827751..fdb88dc0a1 100644 --- a/docs/source/markdown/options/volume.md +++ b/docs/source/markdown/options/volume.md @@ -80,15 +80,17 @@ objects on the shared volumes. The **z** option tells Podman that two or more <> 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 <> can use a private -volume. Note: all containers within a `pod` share the same SELinux label. This +a private unshared label. Only the current <> can use a private +volume. + +Note: all containers within a `pod` share the same SELinux label. This means all containers within said pod can read/write volumes shared into the -container created with the `:Z` on any of one the containers. Relabeling walks -the file system under the volume and changes the label on each file, if the +container created with the `:Z` on any one of the containers. Relabeling walks +the file system under the volume and changes the label on each file; if the volume has thousands of inodes, this process takes a long time, delaying the start of the <>. If the volume was previously relabeled with the `z` option, Podman is optimized to not relabel a second time. If files are -moved into the volume, then the labels can be manually change with the +moved into the volume, then the labels can be manually changed with the `chcon -Rt container_file_t PATH` command. Note: Do not relabel system files and directories. Relabeling system content diff --git a/docs/source/markdown/podman-cp.1.md b/docs/source/markdown/podman-cp.1.md index 14b81296a4..c9282d5b52 100644 --- a/docs/source/markdown/podman-cp.1.md +++ b/docs/source/markdown/podman-cp.1.md @@ -71,9 +71,9 @@ Allow directories to be overwritten with non-directories and vice versa. By def Podman has much stronger capabilities than just `podman cp` to achieve copying files between the host and containers. -Using standard **[podman-mount(1)](podman-mount.1.md)** and **[podman-unmount(1)](podman-unmount.1.md)** takes advantage of the entire linux tool chain, rather than just cp. +Using standard **[podman-mount(1)](podman-mount.1.md)** and **[podman-unmount(1)](podman-unmount.1.md)** takes advantage of the entire Linux tool chain, rather than just `cp`. -copying contents out of a container or into a container, can be achieved with a few simple commands. For example: +Copying contents out of a container or into a container can be achieved with a few simple commands. For example: To copy the `/etc/foobar` directory out of a container and onto `/tmp` on the host, the following commands can be executed: @@ -96,8 +96,8 @@ does not have dnf installed, following commands can be executed: podman umount CONTAINERID By using `podman mount` and `podman unmount`, one can use all of the -standard linux tools for moving files into and out of containers, not just -the cp command. +standard Linux tools for moving files into and out of containers, not just +the `cp` command. ## EXAMPLES diff --git a/docs/source/markdown/podman-image-prune.1.md b/docs/source/markdown/podman-image-prune.1.md index 284de5e80d..bc9705b498 100644 --- a/docs/source/markdown/podman-image-prune.1.md +++ b/docs/source/markdown/podman-image-prune.1.md @@ -19,7 +19,7 @@ Remove dangling images and images that have no associated containers. #### **--build-cache** -Remove persistent build cache create for `--mount=type=cache`. +Remove persistent build cache created for `--mount=type=cache`. #### **--external** diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index 041838b11d..1ca0bd55db 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -623,7 +623,7 @@ $ podman run -v data:/data2 -i -t fedora bash $ podman run -v /var/cache/dnf:/var/cache/dnf:O -ti fedora dnf -y update ``` -If the container needs a writeable mounted volume by a non root user inside the container, use the **U** option. This option tells Podman to chown the source volume to match the default UID and GID used within the container. +If the container needs a writable mounted volume by a non root user inside the container, use the **U** option. This option tells Podman to chown the source volume to match the default UID and GID used within the container. ``` $ podman run -d -e MARIADB_ROOT_PASSWORD=root --user mysql --userns=keep-id -v ~/data:/var/lib/mysql:Z,U mariadb ``` diff --git a/docs/source/markdown/podman-secret-create.1.md b/docs/source/markdown/podman-secret-create.1.md index 68c18fdbb8..70080353db 100644 --- a/docs/source/markdown/podman-secret-create.1.md +++ b/docs/source/markdown/podman-secret-create.1.md @@ -16,7 +16,7 @@ A secret is a blob of sensitive data which a container needs at runtime but is not stored in the image or in source control, such as usernames and passwords, TLS certificates and keys, SSH keys or other important generic strings or binary content (up to 500 kb in size). -Secrets are not committed to an image with `podman commit`, and does not get committed in the archive created by a `podman export` command. +Secrets are not committed to an image with `podman commit`, and do not get committed in the archive created by a `podman export` command. Secrets can also be used to store passwords for `podman login` to authenticate against container registries. diff --git a/docs/source/markdown/podman-systemd.unit.5.md b/docs/source/markdown/podman-systemd.unit.5.md index 6486770962..57329845a3 100644 --- a/docs/source/markdown/podman-systemd.unit.5.md +++ b/docs/source/markdown/podman-systemd.unit.5.md @@ -26,7 +26,7 @@ Distribution defined quadlets: ### Podman rootless unit search path -Quadlet files for non-root users can be placed in the following directories +Quadlet files for non-root users can be placed in the following directories: * $XDG_RUNTIME_DIR/containers/systemd/ * $XDG_CONFIG_HOME/containers/systemd/ or ~/.config/containers/systemd/ @@ -39,7 +39,7 @@ Quadlet supports using symbolic links for the base of the search paths and insid ## DESCRIPTION -Podman supports building, and starting containers (and creating volumes) via systemd by using a +Podman supports building and starting containers (and creating volumes) via systemd by using a [systemd generator](https://www.freedesktop.org/software/systemd/man/systemd.generator.html). These files are read during boot (and when `systemctl daemon-reload` is run) and generate corresponding regular systemd service unit files. Both system and user systemd units are supported. @@ -73,7 +73,7 @@ For rootless containers, when administrators place Quadlet files in the /etc/containers/systemd/users directory, all users' sessions execute the Quadlet when the login session begins. If the administrator places a Quadlet file in the /etc/containers/systemd/users/${UID}/ directory, then only the -user with the matching UID execute the Quadlet when the login +user with the matching UID executes the Quadlet when the login session gets started. For unit files placed in subdirectories within /etc/containers/systemd/user/${UID}/ and the other user unit search paths, Quadlet will recursively search and run the unit files present in these subdirectories. @@ -110,13 +110,13 @@ leaves the job in a "started" state which prevents subsequent activations by the Examples for such cases: - `.container` file with an image that exits after their entrypoint has finished -`` + - `.kube` file pointing to a Kubernetes Yaml file that does not define any containers. E.g. PVCs only ### Enabling unit files The services created by Podman are considered transient by systemd, which means they don't have the same -persistence rules as regular units. In particular, it is not possible to "systemctl enable" them +persistence rules as regular units. In particular, it is not possible to `systemctl enable` them in order for them to become automatically enabled on the next boot. To compensate for this, the generator manually applies the `[Install]` section of the container definition @@ -137,7 +137,7 @@ install an non-enabled unit and then later enabling it by installing the drop-in. -**NOTE:** To express dependencies between containers, use the generated names of the service. In other +**NOTE:** To express dependencies between containers, use the generated names of the services. In other words `WantedBy=other.service`, not `WantedBy=other.container`. The same is true for other kinds of dependencies, too, like `After=other.service`. @@ -246,7 +246,7 @@ that limit the output to only the units you are debugging. ### Implicit network dependencies -Quadlet will add dependencies on the `network-online.target` (as root) or `podman-user-wait-network-online.service` +Quadlet will add dependencies on `network-online.target` (as root) or `podman-user-wait-network-online.service` (as user) by adding `After=` and `Wants=` properties to the unit. This is to ensure that the network is reachable if an image needs to be pulled and by the time the container is started. @@ -460,7 +460,7 @@ DropCapability=CAP_DAC_OVERRIDE CAP_IPC_OWNER Override the default ENTRYPOINT from the image. Equivalent to the Podman `--entrypoint` option. -Specify multi option commands in the form of a json string. +Specify multi option commands in the form of a JSON string. ### `Environment=` @@ -522,7 +522,7 @@ This key can be listed multiple times. ### `Group=` The (numeric) GID to run as inside the container. This does not need to match the GID on the host, -which can be modified with `UsersNS`, but if that is not specified, this GID is also used on the host. +which can be modified with `UserNS`, but if that is not specified, this GID is also used on the host. ### `GroupAdd=` @@ -789,7 +789,7 @@ The format of the rootfs is the same as when passed to `podman run --rootfs`, so Note: On SELinux systems, the rootfs needs the correct label, which is by default unconfined_u:object_r:container_file_t:s0. -### `RunInit=` (default to `false`) +### `RunInit=` (defaults to `false`) If enabled, the container has a minimal init process inside the container that forwards signals and reaps processes. @@ -797,7 +797,7 @@ container that forwards signals and reaps processes. ### `SeccompProfile=` Set the seccomp profile to use in the container. If unset, the default podman profile is used. -Set to either the pathname of a json file, or `unconfined` to disable the seccomp filters. +Set to either the pathname of a JSON file, or `unconfined` to disable the seccomp filters. ### `Secret=`