From dbed8d38d5589675470f7a5d2a89f4f35c10c021 Mon Sep 17 00:00:00 2001 From: Daniel J Walsh Date: Sun, 19 Jul 2020 07:29:53 -0400 Subject: [PATCH] Switch references from libpod.conf to containers.conf Signed-off-by: Daniel J Walsh --- docs/source/markdown/libpod.conf.5.md | 114 ++++++++++++++++++ docs/source/markdown/podman-attach.1.md | 4 +- docs/source/markdown/podman-create.1.md | 6 +- docs/source/markdown/podman-events.1.md | 4 +- docs/source/markdown/podman-run.1.md | 6 +- .../markdown/podman-system-migrate.1.md | 2 +- .../markdown/podman-system-renumber.1.md | 6 +- docs/source/markdown/podman.1.md | 8 +- 8 files changed, 132 insertions(+), 18 deletions(-) create mode 100644 docs/source/markdown/libpod.conf.5.md diff --git a/docs/source/markdown/libpod.conf.5.md b/docs/source/markdown/libpod.conf.5.md new file mode 100644 index 000000000000..ca45bccf6aa7 --- /dev/null +++ b/docs/source/markdown/libpod.conf.5.md @@ -0,0 +1,114 @@ +% libpod.conf(5) + +## NAME +libpod.conf - libpod configuration file + +## DESCRIPTION +The libpod.conf file is the default configuration file for all tools using +libpod to manage containers. + +## OPTIONS + +**image_default_transport**="" + Default transport method for pulling and pushing images + +**runtime**="" + Default OCI runtime to use if nothing is specified in **runtimes** + +**runtimes** + For each OCI runtime, specify a list of paths to look for. The first one found is used. If the paths are empty or no valid path was found, then the `$PATH` environment variable will be used as the fallback. + +**conmon_path**="" + Paths to search for the conmon container manager binary. If the paths are empty or no valid path was found, then the `$PATH` environment variable will be used as the fallback. + +**conmon_env_vars**="" + Environment variables to pass into Conmon + +**cgroup_manager**="" + Specify the CGroup Manager to use; valid values are "systemd" and "cgroupfs" + +**lock_type**="" + Specify the locking mechanism to use; valid values are "shm" and "file". Change the default only if you are sure of what you are doing, in general "file" is useful only on platforms where cgo is not available for using the faster "shm" lock type. You may need to run "podman system renumber" after you change the lock type. + +**init_path**="" + Path to the container-init binary, which forwards signals and reaps processes within containers. Note that the container-init binary will only be used when the `--init` for podman-create and podman-run is set. + +**hooks_dir**=["*path*", ...] + + Each `*.json` file in the path configures a hook for Podman containers. For more details on the syntax of the JSON files and the semantics of hook injection, see `oci-hooks(5)`. Podman and libpod currently support both the 1.0.0 and 0.1.0 hook schemas, although the 0.1.0 schema is deprecated. + + Paths listed later in the array have higher precedence (`oci-hooks(5)` discusses directory precedence). + + For the annotation conditions, libpod uses any annotations set in the generated OCI configuration. + + For the bind-mount conditions, only mounts explicitly requested by the caller via `--volume` are considered. Bind mounts that libpod inserts by default (e.g. `/dev/shm`) are not considered. + + Podman and libpod currently support an additional `precreate` state which is called before the runtime's `create` operation. Unlike the other stages, which receive the container state on their standard input, `precreate` hooks receive the proposed runtime configuration on their standard input. They may alter that configuration as they see fit, and write the altered form to their standard output. + + **WARNING**: the `precreate` hook lets you do powerful things, such as adding additional mounts to the runtime configuration. That power also makes it easy to break things. Before reporting libpod errors, try running your container with `precreate` hooks disabled to see if the problem is due to one of your hooks. + +**static_dir**="" + Directory for persistent libpod files (database, etc) + By default this will be configured relative to where containers/storage + stores containers + +**tmp_dir**="" + Directory for temporary files + Must be a tmpfs (wiped after reboot) + +**max_log_size**="" + Maximum size of log files (in bytes) + +**no_pivot_root**="" + Whether to use chroot instead of pivot_root in the runtime + +**cni_config_dir**="" + Directory containing CNI plugin configuration files + +**cni_plugin_dir**="" + Directories where CNI plugin binaries may be located + +**infra_image** = "" + Infra (pause) container image name for pod infra containers. When running a pod, we + start a `pause` process in a container to hold open the namespaces associated with the + pod. This container and process, basically sleep/pause for the lifetime of the pod. + +**infra_command**="" + Command to run the infra container + +**namespace**="" + Default libpod namespace. If libpod is joined to a namespace, it will see only containers and pods + that were created in the same namespace, and will create new containers and pods in that namespace. + The default namespace is "", which corresponds to no namespace. When no namespace is set, all + containers and pods are visible. + +**label**="true|false" + Indicates whether the containers should use label separation by default. + Can be overridden via `--security-opt label=...` on the CLI. + +**num_locks**="" + Number of locks available for containers and pods. Each created container or pod consumes one lock. + The default number available is 2048. + If this is changed, a lock renumbering must be performed, using the `podman system renumber` command. + +**volume_path**="" + Directory where named volumes will be created in using the default volume driver. + By default this will be configured relative to where containers/storage stores containers. + +**network_cmd_path**="" + Path to the command binary to use for setting up a network. It is currently only used for setting up + a slirp4netns network. If "" is used then the binary is looked up using the $PATH environment variable. + +**events_logger**="" + Default method to use when logging events. Valid values are "file", "journald", and "none". + +**detach_keys**="" + Keys sequence used for detaching a container + +## FILES + `/usr/share/containers/libpod.conf`, default libpod configuration path + + `/etc/containers/libpod.conf`, override libpod configuration path + +## HISTORY +Apr 2018, Originally compiled by Nathan Williams diff --git a/docs/source/markdown/podman-attach.1.md b/docs/source/markdown/podman-attach.1.md index d858b74d05af..a01eeebc5af8 100644 --- a/docs/source/markdown/podman-attach.1.md +++ b/docs/source/markdown/podman-attach.1.md @@ -15,7 +15,7 @@ or name, either to view its ongoing output or to control it interactively. You can detach from the container (and leave it running) using a configurable key sequence. The default sequence is `ctrl-p,ctrl-q`. Configure the keys sequence using the **--detach-keys** option, or specifying -it in the **containers.conf** file: see **containers.conf(5)** for more information. +it in the **libpod.conf** file: see **libpod.conf(5)** for more information. ## OPTIONS **--detach-keys**=*sequence* @@ -55,4 +55,4 @@ $ podman attach 1234 $ podman attach --no-stdin foobar ``` ## SEE ALSO -podman(1), podman-exec(1), podman-run(1) +podman(1), podman-exec(1), podman-run(1), containers.conf(5) diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index a85a0b420f90..4466e661675c 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -190,7 +190,7 @@ detached container with **podman attach**. When attached in the tty mode, you can detach from the container (and leave it running) using a configurable key sequence. The default sequence is `ctrl-p,ctrl-q`. Configure the keys sequence using the **--detach-keys** option, or specifying -it in the **containers.conf** file: see **containers.conf(5)** for more information. +it in the **libpod.conf** file: see **libpod.conf(5)** for more information. **--detach-keys**=*sequence* @@ -741,7 +741,7 @@ Security Options - `seccomp=unconfined` : Turn off seccomp confinement for the container - `seccomp=profile.json` : White listed syscalls seccomp Json file to be used as a seccomp filter -Note: Labeling can be disabled for all containers by setting label=false in the **containers.conf** (`/etc/containers/containers.conf`) file. +Note: Labeling can be disabled for all containers by setting label=false in the **libpod.conf** (`/etc/containers/libpod.conf`) file. **--shm-size**=*size* @@ -1110,7 +1110,7 @@ b NOTE: Use the environment variable `TMPDIR` to change the temporary storage location of downloaded container images. Podman defaults to use `/var/tmp`. ## SEE ALSO -subgid(5), subuid(5), containers.conf(5), systemd.unit(5), setsebool(8), slirp4netns(1), fuse-overlayfs(1) +subgid(5), subuid(5), libpod.conf(5), systemd.unit(5), setsebool(8), slirp4netns(1), fuse-overlayfs(1) ## HISTORY October 2017, converted from Docker documentation to Podman by Dan Walsh for Podman diff --git a/docs/source/markdown/podman-events.1.md b/docs/source/markdown/podman-events.1.md index 190c09b53e52..33a666bd7437 100644 --- a/docs/source/markdown/podman-events.1.md +++ b/docs/source/markdown/podman-events.1.md @@ -10,7 +10,7 @@ podman\-events - Monitor Podman events Monitor and print events that occur in Podman. Each event will include a timestamp, a type, a status, name (if applicable), and image (if applicable). The default logging -mechanism is *journald*. This can be changed in containers.conf by changing the `events_logger` +mechanism is *journald*. This can be changed in libpod.conf by changing the `events_logger` value to `file`. Only `file` and `journald` are accepted. A `none` logger is also available but this logging mechanism completely disables events; nothing will be reported by `podman events`. @@ -150,7 +150,7 @@ $ podman events --format json ``` ## SEE ALSO -podman(1) +podman(1), containers.conf(5) ## HISTORY March 2019, Originally compiled by Brent Baude diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index 4c0b82974b02..de1d8aff6a9d 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -208,7 +208,7 @@ Specify the key sequence for detaching a container; _sequence_ is a comma-delimi in which each item can be a single character from the [a-Z] range, or **ctrl**-_value_, where _value_ is one of: **a-z** or **@^[,_**. -This option can also be set in **containers.conf**(5) file. +This option can also be set in **libpod.conf**(5) file. Specifying "" will disable this feature. The default is **ctrl-p,ctrl-q**. @@ -759,7 +759,7 @@ Security Options - **seccomp=unconfined**: Turn off seccomp confinement for the container - **seccomp**=_profile.json_: Allowed syscall list seccomp JSON file to be used as a seccomp filter -Note: Labeling can be disabled for all containers by setting **label=false** in the **containers.conf**(5) file. +Note: Labeling can be disabled for all containers by setting **label=false** in the **libpod.conf**(5) file. **--shm-size**=_number_[_unit_] @@ -1389,7 +1389,7 @@ b NOTE: Use the environment variable `TMPDIR` to change the temporary storage location of downloaded container images. Podman defaults to use `/var/tmp`. ## SEE ALSO -**subgid**(5), **subuid**(5), **containers.conf**(5), **systemd.unit**(5), **setsebool**(8), **slirp4netns**(1), **fuse-overlayfs**(1). +**subgid**(5), **subuid**(5), **libpod.conf**(5), **systemd.unit**(5), **setsebool**(8), **slirp4netns**(1), **fuse-overlayfs**(1). ## HISTORY September 2018, updated by Kunal Kushwaha diff --git a/docs/source/markdown/podman-system-migrate.1.md b/docs/source/markdown/podman-system-migrate.1.md index 29c0ef94b7a5..baabfd14b278 100644 --- a/docs/source/markdown/podman-system-migrate.1.md +++ b/docs/source/markdown/podman-system-migrate.1.md @@ -33,7 +33,7 @@ This can be used after a system upgrade which changes the default OCI runtime to There are no guarantees that the containers will continue to work under the new runtime, as some runtimes support differing options and configurations. ## SEE ALSO -`podman(1)`, `containers.conf(5)`, `usermod(8)` +`podman(1)`, `libpod.conf(5)`, `usermod(8)` ## HISTORY April 2019, Originally compiled by Giuseppe Scrivano (gscrivan at redhat dot com) diff --git a/docs/source/markdown/podman-system-renumber.1.md b/docs/source/markdown/podman-system-renumber.1.md index 51c085606956..071eefe291db 100644 --- a/docs/source/markdown/podman-system-renumber.1.md +++ b/docs/source/markdown/podman-system-renumber.1.md @@ -9,9 +9,9 @@ podman\-system\-renumber - Migrate lock numbers to handle a change in maximum nu ## DESCRIPTION **podman system renumber** renumbers locks used by containers and pods. -Each Podman container and pod is allocated a lock at creation time, up to a maximum number controlled by the **num_locks** parameter in **containers.conf**. +Each Podman container and pod is allocated a lock at creation time, up to a maximum number controlled by the **num_locks** parameter in **libpod.conf**. -When all available locks are exhausted, no further containers and pods can be created until some existing containers and pods are removed. This can be avoided by increasing the number of locks available via modifying **containers.conf** and subsequently running **podman system renumber** to prepare the new locks (and reallocate lock numbers to fit the new struct). +When all available locks are exhausted, no further containers and pods can be created until some existing containers and pods are removed. This can be avoided by increasing the number of locks available via modifying **libpod.conf** and subsequently running **podman system renumber** to prepare the new locks (and reallocate lock numbers to fit the new struct). **podman system renumber** must be called after any changes to **num_locks** - failure to do so will result in errors starting Podman as the number of locks available conflicts with the configured number of locks. @@ -20,7 +20,7 @@ When all available locks are exhausted, no further containers and pods can be cr If possible, avoid calling **podman system renumber** while there are other Podman processes running. ## SEE ALSO -`podman(1)`, `containers.conf(5)` +`podman(1)`, `libpod.conf(5)` ## HISTORY February 2019, Originally compiled by Matt Heon (mheon at redhat dot com) diff --git a/docs/source/markdown/podman.1.md b/docs/source/markdown/podman.1.md index 3dd83721bfe0..330c3c6716c0 100644 --- a/docs/source/markdown/podman.1.md +++ b/docs/source/markdown/podman.1.md @@ -23,7 +23,7 @@ created by the other. **--cgroup-manager**=*manager* -CGroup manager to use for container cgroups. Supported values are cgroupfs or systemd. Default is systemd unless overridden in the containers.conf file. +The CGroup manager to use for container cgroups. Supported values are cgroupfs or systemd. Default is systemd unless overridden in the containers.conf file. Note: Setting this flag can cause certain commands to break when called on containers previously created by the other CGroup manager type. Note: CGroup manager is not supported in rootless mode when using CGroups Version V1. @@ -219,11 +219,11 @@ the exit codes follow the `chroot` standard, see below: **containers.conf** (`/usr/share/containers/containers.conf`) - Podman has builtin defaults for command line options. These defualts can be overridden using the containers.conf configuration files. + Podman has builtin defaults for command line options. These defaults can be overridden using the containers.conf configuration files. -Distributions ship the `/usr/share/containers/containers.conf` file with their defaults. Administrators can override fields in this file by creating the `/etc/containers/containers.conf` file. Users can further modify defaults by creating the `$HOME/.config/containers/containers.conf` file. Podman merges it's builtin defaults with the specify fields from these files, if they exist. Fields specified in the users file override the administrators file, which overrides the distribution files, which override the builtin defaults. +Distributions ship the `/usr/share/containers/containers.conf` file with their default settings. Administrators can override fields in this file by creating the `/etc/containers/containers.conf` file. Users can further modify defaults by creating the `$HOME/.config/containers/containers.conf` file. Podman merges it's builtin defaults with the specify fields from these files, if they exist. Fields specified in the users file override the administrators file, which overrides the distribution's file, which override the built-in defaults. - Podman uses builtin defaults if no containers.conf file is found. +Podman uses builtin defaults if no containers.conf file is found. **mounts.conf** (`/usr/share/containers/mounts.conf`)