From a8a02908eaf6e18dc32c59a6ebc84115c2e0062d Mon Sep 17 00:00:00 2001 From: Reinhard Tartler Date: Fri, 28 Nov 2025 09:23:18 -0500 Subject: [PATCH] Cleanup manpage formatting Also address most troff issues. Not all of them are easy, in particular those manpages with long urls and examples that include digests are difficult to render in traditional manpages. Signed-off-by: Reinhard Tartler --- common/docs/Containerfile.5.md | 72 ++++++++--------- common/docs/containerignore.5.md | 103 ++++++++++++++--------- common/docs/containers.conf.5.md | 135 ++++++++++++++++++++----------- 3 files changed, 186 insertions(+), 124 deletions(-) diff --git a/common/docs/Containerfile.5.md b/common/docs/Containerfile.5.md index 3e2bd7aaad..ff64f76979 100644 --- a/common/docs/Containerfile.5.md +++ b/common/docs/Containerfile.5.md @@ -107,67 +107,67 @@ Attach a filesystem mount to the container Current supported mount TYPES are bind, cache, secret and tmpfs. - e.g. +Examples: - mount=type=bind,source=/path/on/host,destination=/path/in/container,relabel=shared + mount=type=bind,source=/path/on/host,destination=/path/in/container,relabel=shared - mount=type=tmpfs,tmpfs-size=512M,destination=/path/in/container + mount=type=tmpfs,tmpfs-size=512M,destination=/path/in/container - mount=type=secret,id=mysecret cat /run/secrets/mysecret + mount=type=secret,id=mysecret cat /run/secrets/mysecret - Common Options: +Common Options: - · src, source: mount source spec for bind and volume. Mandatory for bind. If `from` is specified, `src` is the subpath in the `from` field. +* src, source: mount source spec for bind and volume. Mandatory for bind. If `from` is specified, `src` is the subpath in the `from` field. - · dst, destination, target: mount destination spec. +* dst, destination, target: mount destination spec. - · ro, read-only: true (default) or false. +* ro, read-only: true (default) or false. - Options specific to bind: +Options specific to *bind*: - · bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2). +* bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2). - . bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive. +* bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive. - · from: stage or image name for the root of the source. Defaults to the build context. +* from: stage or image name for the root of the source. Defaults to the build context. - · relabel=shared, z: Relabels src content with a shared label. +* relabel=shared, z: Relabels src content with a shared label. - . relabel=private, Z: Relabels src content with a private label. +* relabel=private, Z: Relabels src content with a private label. - Labeling systems like SELinux require proper labels on the bind mounted content mounted into a container. Without a label, the security system might prevent the processes running in side the container from using the content. By default, container engines do not change the labels set by the OS. The relabel flag tells the engine to relabel file objects on the shared mountz. +Labeling systems like SELinux require proper labels on the bind mounted content mounted into a container. Without a label, the security system might prevent the processes running in side the container from using the content. By default, container engines do not change the labels set by the OS. The relabel flag tells the engine to relabel file objects on the shared mountz. - The relabel=shared and z options tell the engine that two or more containers will share the mount content. The engine labels the content with a shared content label. +The relabel=shared and z options tell the engine that two or more containers will share the mount content. The engine labels the content with a shared content label. - The relabel=private and Z options tell the engine to label the content with a private unshared label. Only the current container can use a private mount. +The relabel=private and Z options tell the engine to label the content with a private unshared label. Only the current container can use a private mount. - Relabeling walks the file system under the mount and changes the label on each file, if the mount has thousands of inodes, this process takes a long time, delaying the start of the container. +Relabeling walks the file system under the mount and changes the label on each file, if the mount has thousands of inodes, this process takes a long time, delaying the start of the container. - · rw, read-write: allows writes on the mount. +* rw, read-write: allows writes on the mount. - Options specific to tmpfs: +Options specific to *tmpfs*: - · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux. +* tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux. - · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux. +* tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux. - · tmpcopyup: Path that is shadowed by the tmpfs mount is recursively copied up to the tmpfs itself. +* tmpcopyup: Path that is shadowed by the tmpfs mount is recursively copied up to the tmpfs itself. - Options specific to cache: +Options specific to *cache*: - · id: Create a separate cache directory for a particular id. +* id: Create a separate cache directory for a particular id. - · mode: File mode for new cache directory in octal. Default 0755. +* mode: File mode for new cache directory in octal. Default 0755. - · ro, readonly: read only cache if set. +* ro, readonly: read only cache if set. - · uid: uid for cache directory. +* uid: uid for cache directory. - · gid: gid for cache directory. +* gid: gid for cache directory. - · from: stage name for the root of the source. Defaults to host cache directory. +* from: stage name for the root of the source. Defaults to host cache directory. - · rw, read-write: allows writes on the mount. +* rw, read-write: allows writes on the mount. **RUN --network** @@ -178,11 +178,11 @@ Syntax: `--network=` **Network types** -| Type | Description | -|----------------------------------------------|----------------------------------------| -| [`default`](#run---networkdefault) (default) | Run in the default network. | -| [`none`](#run---networknone) | Run with no network access. | -| [`host`](#run---networkhost) | Run in the host's network environment. | +| Type | Description | +|-----------|----------------------------------------| +| `default` | Run in the default network. | +| `none` | Run with no network access. | +| `host` | Run in the host's network environment. | ##### RUN --network=default diff --git a/common/docs/containerignore.5.md b/common/docs/containerignore.5.md index b26ef11a43..aa9a496b15 100644 --- a/common/docs/containerignore.5.md +++ b/common/docs/containerignore.5.md @@ -1,4 +1,4 @@ -% ".containerignore" "28" "Sep 2021" "" "Container User Manuals" +% ".containerignore" "5" "Sep 2021" "" "Container User Manuals" # NAME @@ -6,23 +6,27 @@ # INTRODUCTION -Before container engines build an image, they look for a file named .containerignore or .dockerignore in the root -context directory. If one of these file exists, the CLI modifies the context to exclude files and -directories that match patterns specified in the file. This avoids adding them to images using the ADD or COPY -instruction. - -The CLI interprets the .containerignore or .dockerignore file as a newline-separated list of patterns similar to -the file globs of Unix shells. For the purposes of matching, the root of the context is considered to be both the -working and the root directory. For example, the patterns /foo/bar and foo/bar both exclude a file or directory -named bar in the foo subdirectory of PATH or in the root of the git repository located at URL. Neither excludes +Before container engines build an image, they look for a file named +`.containerignore` or `.dockerignore` in the root context directory. If one of +these file exists, the CLI modifies the context to exclude files and +directories that match patterns specified in the file. This avoids adding them +to images using the ADD or COPY instruction. + +The CLI interprets the `.containerignore` or `.dockerignore` file as a +newline-separated list of patterns similar to the file globs of Unix +shells. For the purposes of matching, the root of the context is considered to +be both the working and the root directory. For example, the patterns `/foo/bar` +and `foo/bar` both exclude a file or directory named bar in the foo subdirectory +of PATH or in the root of the git repository located at URL. Neither excludes anything else. -If a line in .containerignore or .dockerignore file starts with # in column 1, then this line is considered as a -comment and is ignored before interpreted by the CLI. +If a line in `.containerignore` or `.dockerignore` file starts with `#` in +column 1, then this line is considered as a comment and is ignored before +interpreted by the CLI. # EXAMPLES -Here is an example .containerignore file: +Here is an example `.containerignore` file: ``` # comment @@ -32,56 +36,77 @@ temp? ``` This file causes the following build behavior: -Rule Behavior -``` -# comment Ignored. -*/temp* Exclude files and directories whose names start with temp in any immediate subdirectory of the root. -For example, the plain file /somedir/temporary.txt is excluded, as is the directory /somedir/temp. -*/*/temp* Exclude files and directories starting with temp from any subdirectory that is two levels below the -root. For example, /somedir/subdir/temporary.txt is excluded. -temp? Exclude files and directories in the root directory whose names are a one-character extension of temp. For example, /tempa and /tempb are excluded. -``` -Matching is done using Go’s filepath.Match rules. A preprocessing step removes leading and trailing whitespace and -eliminates . and .. elements using Go’s filepath.Clean. Lines that are blank after preprocessing are ignored. -Beyond Go’s filepath.Match rules, Docker also supports a special wildcard string ** that matches any number of -directories (including zero). For example, **/*.go will exclude all files that end with .go that are found in all -directories, including the root of the build context. +`#comment`: Lines that start with the `#` character are ignored. + +`*/temp*`: Exclude files and directories whose names start with temp in any +immediate subdirectory of the root. For example, the plain file +/somedir/temporary.txt is excluded, as is the directory /somedir/temp. + +`*/*/temp*`: Exclude files and directories starting with temp from any +subdirectory that is two levels below the root. For example, +/somedir/subdir/temporary.txt is excluded. + +`temp?`: Exclude files and directories in the root directory whose names are a +one-character extension of temp. For example, /tempa and /tempb are excluded. + + +Matching is done using the `filepath.Match` rules: + +* A preprocessing step removes leading and trailing whitespace and eliminates + . and .. elements using the golang `path/filepath` package. +* Lines that are blank after preprocessing are ignored. + +Beyond the `filepath.Match` rules, Docker also supports a special wildcard +string `**` that matches any number of directories (including zero). For +example, `**/*.go` will exclude all files that end with `.go` that are found in +all directories, including the root of the build context. + +Lines starting with `!` (exclamation mark) can be used to make exceptions to +exclusions. The following is an example `.containerignore` file that uses this +mechanism: -Lines starting with ! (exclamation mark) can be used to make exceptions to exclusions. The following is an example .containerignore file that uses this mechanism: ``` *.md !README.md ``` + All markdown files except README.md are excluded from the context. -The placement of ! exception rules influences the behavior: the last line of the .containerignore that matches a -particular file determines whether it is included or excluded. Consider the following example: +The placement of `!` exception rules influences the behavior: the last line of +the `.containerignore` that matches a particular file determines whether it is +included or excluded. Consider the following example: + ``` *.md !README*.md README-secret.md ``` -No markdown files are included in the context except README files other than README-secret.md. + +No markdown files are included in the context except `README` files other than `README-secret.md`. Now consider this example: + ``` *.md README-secret.md !README*.md ``` -All of the README files are included. The middle line has no effect because !README*.md matches README-secret.md and -comes last. -You can even use the .containerignore file to exclude the Containerfile or Dockerfile and .containerignore files. -These files are still sent to the daemon because it needs them to do its job. But the ADD and COPY instructions do -not copy them to the image. +All of the README files are included. The middle line has no effect because +`!README*.md` matches `README-secret.md` and comes last. + +You can even use the .containerignore file to exclude the `Containerfile` or +`Dockerfile` and `.containerignore` files. These files are still sent to the +daemon because it needs them to do its job. But the `ADD` and `COPY` instructions +do not copy them to the image. -Finally, you may want to specify which files to include in the context, rather than which to exclude. To achieve -this, specify * as the first pattern, followed by one or more ! exception patterns. +Finally, you may want to specify which files to include in the context, rather +than which to exclude. To achieve this, specify `*` as the first pattern, +followed by one or more `!` exception patterns. ## SEE ALSO buildah-build(1), podman-build(1), docker-build(1) # HISTORY -*Sep 2021, Compiled by Dan Walsh (dwalsh at redhat dot com) based on docker.com .dockerignore documentation. +*Sep 2021, Compiled by Dan Walsh (dwalsh at redhat dot com) based on docker.com `.dockerignore` documentation. diff --git a/common/docs/containers.conf.5.md b/common/docs/containers.conf.5.md index c0d9d5489b..76ad6b31dd 100644 --- a/common/docs/containers.conf.5.md +++ b/common/docs/containers.conf.5.md @@ -1,21 +1,26 @@ % containers.conf 5 Container engine configuration file # NAME -containers.conf - The container engine configuration file specifies default -configuration options and command-line flags for container engines. +containers.conf - The container engine configuration file specifies default configuration options and command-line flags for container engines. # DESCRIPTION -Container engines like Podman & Buildah read containers.conf file, if it exists -and modify the defaults for running containers on the host. containers.conf uses -a TOML format that can be easily modified and versioned. +Container engines like Podman & Buildah read` containers.conf` file, if it +exists and modify the defaults for running containers on the host. The file +`containers.conf` uses a TOML format that can be easily modified and versioned. Container engines read the __/usr/share/containers/containers.conf__, -__/etc/containers/containers.conf__, and __/etc/containers/containers.conf.d/\*.conf__ -for global configuration that affects all users. -For global configuration that only affects rootless users use __/etc/containers/containers.rootless.conf__, -__/etc/containers/containers.rootless.d/\*.conf__ and __/etc/containers/containers.rootless.d/\$UID/\*.conf__. The UID is the user's uid which podman runs under so it can be used to specify a certain config for only a single user without having to put the config into the user's home directory. -For user specific configuration it reads __\$XDG_CONFIG_HOME/containers/containers.conf__ and -__\$XDG_CONFIG_HOME/containers/containers.conf.d/\*.conf__ files. When `$XDG_CONFIG_HOME` is not set it falls back to using `$HOME/.config` instead. +__/etc/containers/containers.conf__, and +__/etc/containers/containers.conf.d/\*.conf__ for global configuration that +affects all users. For global configuration that only affects rootless users +use __/etc/containers/containers.rootless.conf__, +__/etc/containers/containers.rootless.d/\*.conf__ and +__/etc/containers/containers.rootless.d/\$UID/\*.conf__. The UID is the user's +uid which podman runs under so it can be used to specify a certain config for +only a single user without having to put the config into the user's home +directory. For user specific configuration it reads +__\$XDG_CONFIG_HOME/containers/containers.conf__ and +__\$XDG_CONFIG_HOME/containers/containers.conf.d/\*.conf__ files. When +`$XDG_CONFIG_HOME` is not set it falls back to using `$HOME/.config` instead. Fields specified in containers conf override the default options, as well as options in previously read containers.conf files. @@ -199,7 +204,7 @@ the container. **dns_servers**=[] A list of dns servers to override the DNS configuration passed to the -container. The special value “none” can be specified to disable creation of +container. The special value "none" can be specified to disable creation of /etc/resolv.conf in the container. **env**=["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"] @@ -263,16 +268,17 @@ the `--init` for podman-create and podman-run is set. **interface_name**="" Default way to set interface names inside containers. Defaults to legacy pattern -of ethX, where X is an integer, when left undefined. +of `ethX`, where `X` is an integer, when left undefined. + Options are: - `device` Uses the network_interface name from the network config as interface name. Falls back to the ethX pattern if the network_interface is not set. + `device`: Uses the network_interface name from the network config as interface name. Falls back to the ethX pattern if the network_interface is not set. **ipcns**="shareable" Default way to create a IPC namespace for the container. Options are: `host` Share host IPC Namespace with the container. - `none` Create shareable IPC Namespace for the container without a private /dev/shm. + `none` Create shareable IPC Namespace for the container without a private `/dev/shm`. `private` Create private IPC Namespace for the container, other containers are not allowed to share it. `shareable` Create shareable IPC Namespace for the container. @@ -290,11 +296,14 @@ Indicates whether the container engine uses MAC(SELinux) container separation vi label_users indicates whether to enforce confined users in containers on SELinux systems. This option causes containers to maintain the current user and role field of the calling process. By default SELinux containers run with -the user system_u, and the role system_r. +the user `system_u`, and the role `system_r`. **log_driver**="" -Logging driver for the container. Currently available options are k8s-file, journald, none and passthrough, with json-file aliased to k8s-file for scripting compatibility. The journald driver is used by default if the systemd journal is readable and writable. Otherwise, the k8s-file driver is used. +Logging driver for the container. Currently available options are k8s-file, +journald, none and passthrough, with json-file aliased to k8s-file for +scripting compatibility. The journald driver is used by default if the systemd +journal is readable and writable. Otherwise, the k8s-file driver is used. **log_path**="" @@ -313,7 +322,9 @@ limit is never exceeded. **log_tag**="" -Default format tag for container log messages. This is useful for creating a specific tag for container log messages. Container log messages default to using the truncated container ID as a tag. +Default format tag for container log messages. This is useful for creating a +specific tag for container log messages. Container log messages default to +using the truncated container ID as a tag. **mounts**=[] @@ -325,8 +336,11 @@ Example: [ "type=bind,source=/var/lib/foobar,destination=/var/lib/foobar,ro", ] **netns**="" Default way to create a NET namespace for the container. -The option is mapped to the **--network** argument for the podman commands, it accepts the same values as that option. -For example it can be set to `bridge`, `host`, `none`, `pasta` and more, see the [podman-create(1)](https://docs.podman.io/en/latest/markdown/podman-create.1.html#network-mode-net) +The option is mapped to the **--network** argument for the podman commands, it +accepts the same values as that option. +For example it can be set to `bridge`, `host`, `none`, `pasta` and more, see +the +[podman-create(1)](https://docs.podman.io/en/latest/markdown/podman-create.1.html#network-mode-net) manual for all available options. **no_hosts**=false @@ -423,10 +437,12 @@ plugins. **network_backend**="" -Network backend determines what network driver will be used to set up and tear down container networks. +Network backend determines what network driver will be used to set up and tear +down container networks. Valid values are "cni" and "netavark". -The default value is empty which means that it will automatically choose CNI or netavark. If there are -already containers/images or CNI networks preset it will choose CNI. +The default value is empty which means that it will automatically choose CNI or +netavark. If there are already containers/images or CNI networks preset it will +choose CNI. Before changing this value all containers must be stopped otherwise it is likely that firewall rules and network interfaces might leak on the host. A reboot will fix this. @@ -462,9 +478,11 @@ netavark_plugin_dirs = [ **default_network**="podman" -The name of the default network as seen in `podman network ls`. This option only effects the network assignment when -the bridge network mode is selected, i.e. `--network bridge`. It is the default for rootful containers but not as -rootless. To change the default network mode use the **netns** option under the `[containers]` table. +The name of the default network as seen in `podman network ls`. This option +only effects the network assignment when the bridge network mode is selected, +i.e. `--network bridge`. It is the default for rootful containers but not as +rootless. To change the default network mode use the **netns** option under the +`[containers]` table. Note: This should not be changed while you have any containers using this network. @@ -472,7 +490,8 @@ Note: This should not be changed while you have any containers using this networ The subnet to use for the default network (named above in **default_network**). -Note: This should not be changed if any containers are currently running on the default network. +Note: This should not be changed if any containers are currently running on the +default network. **default_subnet_pools**=[] @@ -503,8 +522,8 @@ Configure which rootless network program to use by default. Valid options are Path to the directory where network configuration files are located. For the CNI backend the default is __/etc/cni/net.d__ as root and __$HOME/.config/cni/net.d__ as rootless. -For the netavark backend "/etc/containers/networks" is used as root -and "$graphroot/networks" as rootless. +For the netavark backend `/etc/containers/networks` is used as root +and `$graphroot/networks` as rootless. **firewall_driver**="" @@ -526,25 +545,29 @@ A list of default pasta options that should be used running pasta. It accepts the pasta cli options, see pasta(1) for the full list of options. ## ENGINE TABLE -The `engine` table contains configuration options used to set up container engines such as Podman and Buildah. +The `engine` table contains configuration options used to set up container +engines such as Podman and Buildah. **active_service**="" -Name of destination for accessing the Podman service. See SERVICE DESTINATION TABLE below. +Name of destination for accessing the Podman service. +See SERVICE DESTINATION TABLE below. **add_compression**=[] -List of compression algorithms. If set makes sure that requested compression variant -for each platform is added to the manifest list keeping original instance intact in -the same manifest list on every `manifest push`. Supported values are (`gzip`, `zstd` and `zstd:chunked`). -`zstd:chunked` is incompatible with encrypting images, and will be treated as `zstd` with a warning -in that case. +List of compression algorithms. If set makes sure that requested compression +variant for each platform is added to the manifest list keeping original +instance intact in the same manifest list on every `manifest push`. Supported +values are (`gzip`, `zstd` and `zstd:chunked`). `zstd:chunked` is incompatible +with encrypting images, and will be treated as `zstd` with a warning in that +case. -Note: This is different from `compression_format` which allows users to select a default -compression format for `push` and `manifest push`, while `add_compression` is limited to -`manifest push` and allows users to append new instances to manifest list with specified compression -algorithms in `add_compression` for each platform. +Note: This is different from `compression_format` which allows users to select +a default compression format for `push` and `manifest push`, while +`add_compression` is limited to `manifest push` and allows users to append new +instances to manifest list with specified compression algorithms in +`add_compression` for each platform. **cgroup_manager**="systemd" @@ -757,7 +780,9 @@ specify an image to pull. **kube_generate_type**="pod" -Default Kubernetes kind/specification of the kubernetes yaml generated with the `podman kube generate` command. The possible options are `pod` and `deployment`. +Default Kubernetes kind/specification of the kubernetes yaml generated with the +`podman kube generate` command. The possible options are `pod` and +`deployment`. **lock_type**="shm" @@ -769,7 +794,10 @@ change the lock type. **multi_image_archive**=false -Allows for creating archives (e.g., tarballs) with more than one image. Some container engines, such as Podman, interpret additional arguments as tags for one image and hence do not store more than one image. The default behavior can be altered with this option. +Allows for creating archives (e.g., tarballs) with more than one image. Some +container engines, such as Podman, interpret additional arguments as tags for +one image and hence do not store more than one image. The default behavior can +be altered with this option. **namespace**="" @@ -826,14 +854,20 @@ Set the exit policy of the pod when the last container exits. Supported policie Pull image before running or creating a container. The default is **missing**. -- **missing**: attempt to pull the latest image from the registries listed in registries.conf if a local image does not exist. Raise an error if the image is not in any listed registry and is not present locally. -- **always**: pull the image from the first registry it is found in as listed in registries.conf. Raise an error if not found in the registries, even if the image is present locally. -- **never**: do not pull the image from the registry, use only the local version. Raise an error if the image is not present locally. +- **missing**: attempt to pull the latest image from the registries listed in + `registries.conf` if a local image does not exist. Raise an error if the image + is not in any listed registry and is not present locally. +- **always**: pull the image from the first registry it is found in as listed + in `registries.conf`. Raise an error if not found in the registries, even if + the image is present locally. +- **never**: do not pull the image from the registry, use only the local + version. Raise an error if the image is not present locally. **remote** = false -Indicates whether the application should be running in remote mode. This flag modifies the ---remote option on container engines. Setting the flag to true will default `podman --remote=true` for access to the remote Podman service. +Indicates whether the application should be running in remote mode. This flag +modifies the `--remote` option on container engines. Setting the flag to true +will default `podman --remote=true` for access to the remote Podman service. **retry** = 3 @@ -841,7 +875,9 @@ Number of times to retry pulling/pushing images in case of failure. **retry_delay** = "" -Delay between retries in case pulling/pushing image fails. If set, container engines will retry at the set interval, otherwise they delay 2 seconds and then exponentially back off. +Delay between retries in case pulling/pushing image fails. If set, container +engines will retry at the set interval, otherwise they delay 2 seconds and then +exponentially back off. **runtime**="" @@ -912,7 +948,8 @@ Specifies the compression format to use when pushing an image. Supported values are: `gzip`, `zstd` and `zstd:chunked`. This field is ignored when pushing images to the docker-daemon and docker-archive formats. It is also ignored when the manifest format is set to v2s2. -`zstd:chunked` is incompatible with encrypting images, and will be treated as `zstd` with a warning +`zstd:chunked` is incompatible with encrypting images, and will be treated as +`zstd` with a warning in that case. **compression_level**="5"