From 95ab15ec682d24bb2f8281b1fcfe6999e62433d0 Mon Sep 17 00:00:00 2001 From: Daniel J Walsh Date: Sun, 2 Jul 2023 07:18:44 -0400 Subject: [PATCH] local build --- containers-auth.json.5.md | 35 ++++++++++++++------------- containers-storage.conf.5.md | 13 +++++++--- containers-transports.5.md | 11 ++++++--- containers.conf | 47 +++++++++++++++++++++++++++++------- containers.conf.5.md | 42 +++++++++++++++++++++++++++----- storage.conf | 11 +++++---- 6 files changed, 115 insertions(+), 44 deletions(-) diff --git a/containers-auth.json.5.md b/containers-auth.json.5.md index 8f83a6c..c5e22b0 100644 --- a/containers-auth.json.5.md +++ b/containers-auth.json.5.md @@ -5,30 +5,33 @@ containers-auth.json - syntax for the registry authentication file # DESCRIPTION -A credentials file in JSON format used to authenticate against container image registries. +A file in JSON format controlling authentication against container image registries. The primary (read/write) file is stored at `${XDG_RUNTIME_DIR}/containers/auth.json` on Linux; on Windows and macOS, at `$HOME/.config/containers/auth.json`. When searching for the credential for a registry, the following files will be read in sequence until the valid credential is found: first reading the primary (read/write) file, or the explicit override using an option of the calling application. -If credentials are not present, search in `${XDG_CONFIG_HOME}/containers/auth.json` (usually `~/.config/containers/auth.json`), `$HOME/.docker/config.json`, `$HOME/.dockercfg`. +If credentials are not present there, +the search continues in `${XDG_CONFIG_HOME}/containers/auth.json` (usually `~/.config/containers/auth.json`), `$HOME/.docker/config.json`, `$HOME/.dockercfg`. -Except the primary (read/write) file, other files are read-only, unless the user use an option of the calling application explicitly points at it as an override. +Except for the primary (read/write) file, other files are read-only unless the user, using an option of the calling application, explicitly points at it as an override. ## FORMAT The auth.json file stores, or references, credentials that allow the user to authenticate -to container image registries. The file can have zero to many entries and -is created by a `login` command from a container tool such as `podman login`, -`buildah login` or `skopeo login`. Each entry either contains a single -hostname (e.g. `docker.io`) or a namespace (e.g. `quay.io/user/image`) as a key -and an auth token in the form of a base64 encoded string as value of `auth`. The -token is built from the concatenation of the username, a colon, and the -password. The registry name can additionally contain a repository name (an image -name without tag or digest) and namespaces. The path (or namespace) is matched -in its hierarchical order when checking for available authentications. For -example, an image pull for `my-registry.local/namespace/user/image:latest` will +to container image registries. +It is primarily managed by a `login` command from a container tool such as `podman login`, +`buildah login`, or `skopeo login`. + +Each entry contains a single hostname (e.g., `docker.io`) or a namespace (e.g., `quay.io/user/image`) as a key, +and credentials in the form of a base64-encoded string as value of `auth`. The +base64-encoded string contains a concatenation of the username, a colon, and the +password. + +When checking for available credentials, the relevant repository is matched +against available keys in its hierarchical order, going from most-specific to least-specific. +For example, an image pull for `my-registry.local/namespace/user/image:latest` will result in a lookup in `auth.json` in the following order: - `my-registry.local/namespace/user/image` @@ -77,10 +80,8 @@ preserving a fallback for `my-registry.local`: An entry can be removed by using a `logout` command from a container tool such as `podman logout` or `buildah logout`. -In addition, credential helpers can be configured for specific registries and the credentials-helper -software can be used to manage the credentials in a more secure way than depending on the base64 encoded authentication -provided by `login`. If the credential helpers are configured for specific registries, the base64 encoded authentication will not be used -for operations concerning credentials of the specified registries. +In addition, credential helpers can be configured for specific registries, and the credentials-helper +software can be used to manage the credentials more securely than storing only base64-encoded credentials in `auth.json`. When the credential helper is in use on a Linux platform, the auth.json file would contain keys that specify the registry domain, and values that specify the suffix of the program to use (i.e. everything after docker-credential-). For example: diff --git a/containers-storage.conf.5.md b/containers-storage.conf.5.md index 672e6b9..9d24e54 100644 --- a/containers-storage.conf.5.md +++ b/containers-storage.conf.5.md @@ -55,6 +55,11 @@ $ restorecon -R -v /NEWSTORAGEPATH A common use case for this field is to provide a local storage directory when user home directories are NFS-mounted (podman does not support container storage over NFS). +**imagestore**="" + Path of imagestore different from `graphroot`, by default storage library stores all images in `graphroot` but if `imagestore` is provided it will store newly pulled images in provided `imagestore` but will keep using `graphroot` for everything else. If user is using `overlay` driver then images which were already part of `graphroot` will still be accessible ( Internally storage library will mount `graphroot` as an `additionalImageStore` to allow this behaviour ). + +A common use case for this field is for the users who want to split the file-system in different parts i.e disk which stores images vs disk used by the container created by the image. + **runroot**="" container storage run dir (default: "/run/containers/storage") Default directory to store all temporary writable content created by container storage programs. The rootless runroot path supports environment variable substitutions (ie. `$HOME/containers/storage`) @@ -88,7 +93,7 @@ container registry. These options can deduplicate pulling of content, disk storage of content and can allow the kernel to use less memory when running containers. -containers/storage supports four keys +containers/storage supports three keys * enable_partial_images="true" | "false" Tells containers/storage to look for files previously pulled in storage rather then always pulling them from the container registry. @@ -105,14 +110,14 @@ containers/storage supports four keys Remap-UIDs/GIDs is the mapping from UIDs/GIDs as they should appear inside of a container, to the UIDs/GIDs outside of the container, and the length of the range of UIDs/GIDs. Additional mapped sets can be listed and will be heeded by libraries, but there are limits to the number of mappings which the kernel will allow when you later attempt to run a container. Example - remap-uids = 0:1668442479:65536 - remap-gids = 0:1668442479:65536 + remap-uids = "0:1668442479:65536" + remap-gids = "0:1668442479:65536" These mappings tell the container engines to map UID 0 inside of the container to UID 1668442479 outside. UID 1 will be mapped to 1668442480. UID 2 will be mapped to 1668442481, etc, for the next 65533 UIDs in succession. **remap-user**="" **remap-group**="" - Remap-User/Group is a user name which can be used to look up one or more UID/GID ranges in the /etc/subuid or /etc/subgid file. Mappings are set up starting with an in-container ID of 0 and then a host-level ID taken from the lowest range that matches the specified name, and using the length of that range. Additional ranges are then assigned, using the ranges which specify the lowest host-level IDs first, to the lowest not-yet-mapped in-container ID, until all of the entries have been used for maps. + Remap-User/Group is a user name which can be used to look up one or more UID/GID ranges in the /etc/subuid or /etc/subgid file. Mappings are set up starting with an in-container ID of 0 and then a host-level ID taken from the lowest range that matches the specified name, and using the length of that range. Additional ranges are then assigned, using the ranges which specify the lowest host-level IDs first, to the lowest not-yet-mapped in-container ID, until all of the entries have been used for maps. This setting overrides the Remap-UIDs/GIDs setting. Example remap-user = "containers" diff --git a/containers-transports.5.md b/containers-transports.5.md index b79f1e5..0f4cacf 100644 --- a/containers-transports.5.md +++ b/containers-transports.5.md @@ -64,12 +64,17 @@ The _algo:digest_ refers to the image ID reported by docker-inspect(1). ### **oci:**_path[:reference]_ -An image compliant with the "Open Container Image Layout Specification" at _path_. -Using a _reference_ is optional and allows for storing multiple images at the same _path_. +An image in a directory structure compliant with the "Open Container Image Layout Specification" at _path_. + +_Path_ terminates at the first `:` character; any further `:` characters are not separators, but a part of _reference_. +Specify a _reference_ to allow storing multiple images within the same _path_. ### **oci-archive:**_path[:reference]_ -An image compliant with the "Open Container Image Layout Specification" stored as a tar(1) archive at _path_. +An image in a tar(1) archive with contents compliant with the "Open Container Image Layout Specification" at _path_. + +_Path_ terminates at the first `:` character; any further `:` characters are not separators, but a part of _reference_. +Specify a _reference_ to allow storing multiple images within the same _path_. ### **ostree:**_docker-reference[@/absolute/repo/path]_ diff --git a/containers.conf b/containers.conf index b506955..9bd9249 100644 --- a/containers.conf +++ b/containers.conf @@ -173,6 +173,12 @@ default_sysctls = [ # #label = true +# 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. +#label_users = false + # Logging driver for the container. Available options: k8s-file and journald. # log_driver = "journald" @@ -308,9 +314,9 @@ log_driver = "journald" # #netavark_plugin_dirs = [ # "/usr/local/libexec/netavark", -# "/usr/libexec/netavark", -# "/usr/local/lib/netavark", -# "/usr/lib/netavark", +# "/usr/libexec/netavark", +# "/usr/local/lib/netavark", +# "/usr/lib/netavark", #] # The network name of the default network to attach pods to. @@ -338,6 +344,13 @@ log_driver = "journald" # {"base" = "10.128.0.0/9", "size" = 24}, #] + + +# Configure which rootless network program to use by default. Valid options are +# `slirp4netns` (default) and `pasta`. +# +#default_rootless_network_cmd = "slirp4netns" + # 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. @@ -353,16 +366,27 @@ log_driver = "journald" # #dns_bind_port = 53 +# 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. +# +#pasta_options = [] + [engine] # Index to the active service # -#active_service = production +#active_service = "production" # The compression format to use when pushing an image. # Valid options are: `gzip`, `zstd` and `zstd:chunked`. # #compression_format = "gzip" +# The compression level to use when pushing an image. +# Valid options depend on the compression format used. +# For gzip, valid options are 1-9, with a default of 5. +# For zstd, valid options are 1-20, with a default of 3. +# +#compression_level = 5 # Cgroup management implementation used for the runtime. # Valid options "systemd" or "cgroupfs" @@ -392,11 +416,16 @@ log_driver = "journald" # short-name aliases defined in containers-registries.conf(5). #compat_api_enforce_docker_hub = true +# The database backend of Podman. Supported values are "boltdb" (default) and +# "sqlite". Please run `podman-system-reset` prior to changing the database +# backend of an existing deployment, to make sure Podman can operate correctly. +#database_backend="boltdb" + # Specify the keys sequence used to detach a container. # Format is a single character [a-Z] or a comma separated sequence of # `ctrl-`, where `` is one of: # `a-z`, `@`, `^`, `[`, `\`, `]`, `^` or `_` -# +# Specifying "" disables this feature. #detach_keys = "ctrl-p,ctrl-q" # Determines whether engine will reserve ports on the host when they are @@ -499,13 +528,13 @@ log_driver = "journald" # faster "shm" lock type. You may need to run "podman system renumber" after # you change the lock type. # -#lock_type** = "shm" +#lock_type = "shm" # MultiImageArchive - if true, the container engine allows for storing archives # (e.g., of the docker-archive transport) with multiple images. By default, # Podman creates single-image archives. # -#multi_image_archive = "false" +#multi_image_archive = false # Default engine namespace # If engine is joined to a namespace, it will see only containers and pods @@ -610,8 +639,8 @@ log_driver = "journald" # map of service destinations # -# [service_destinations] -# [service_destinations.production] +# [engine.service_destinations] +# [engine.service_destinations.production] # URI to access the Podman service # Examples: # rootless "unix://run/user/$UID/podman/podman.sock" (Default) diff --git a/containers.conf.5.md b/containers.conf.5.md index 2b546fe..c9b399e 100644 --- a/containers.conf.5.md +++ b/containers.conf.5.md @@ -111,8 +111,7 @@ default_capabilities = [ ``` Note, by default container engines using containers.conf, run with less -capabilities than Docker. Docker runs additionally with "AUDIT_WRITE", "MKNOD", -"NET_RAW", "CHROOT". If you need to add one of these capabilities for a +capabilities than Docker. Docker runs additionally with "AUDIT_WRITE", "MKNOD" and "NET_RAW". If you need to add one of these capabilities for a particular container, you can use the --cap-add option or edit your system's containers.conf. **default_sysctls**=[] @@ -208,6 +207,13 @@ the container. Indicates whether the container engine uses MAC(SELinux) container separation via labeling. This option is ignored on disabled systems. +**label_users**=false + +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. + **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. @@ -379,6 +385,11 @@ default_subnet_pools = [ ] ``` +**default_rootless_network_cmd**="slirp4netns" + +Configure which rootless network program to use by default. Valid options are +`slirp4netns` (default) and `pasta`. + **network_config_dir**="/etc/cni/net.d/" Path to the directory where network configuration files are located. @@ -394,6 +405,11 @@ mode and dns enabled. Using an alternate port might be useful if other dns services should run on the machine. +**pasta_options** = [] + +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. @@ -430,6 +446,12 @@ conmon_path=[ ] ``` +**database_backend**="boltdb" + +The database backend of Podman. Supported values are "boltdb" (default) and +"sqlite". Please run `podman-system-reset` prior to changing the database +backend of an existing deployment, to make sure Podman can operate correctly. + **detach_keys**="ctrl-p,ctrl-q" Keys sequence used for detaching a container. @@ -437,6 +459,7 @@ Specify the keys sequence used to detach a container. Format is a single character `[a-Z]` or a comma separated sequence of `ctrl-`, where `` is one of: `a-z`, `@`, `^`, `[`, `\`, `]`, `^` or `_` +Specifying "" disables this feature. **enable_port_reservation**=true @@ -696,14 +719,21 @@ not be by other drivers. Determines whether file copied into a container will have changed ownership to the primary uid/gid of the container. -**compression_format**="" +**compression_format**="gzip" Specifies the compression format to use when pushing an image. Supported values are: `gzip`, `zstd` and `zstd:chunked`. -## SERVICE DESTINATION TABLE -The `service_destinations` table contains configuration options used to set up remote connections to the podman service for the podman API. +**compression_level**="5" -**[service_destinations.{name}]** +The compression level to use when pushing an image. Valid options +depend on the compression format used. For gzip, valid options are +1-9, with a default of 5. For zstd, valid options are 1-20, with a +default of 3. + +## SERVICE DESTINATION TABLE +The `engine.service_destinations` table contains configuration options used to set up remote connections to the podman service for the podman API. + +**[engine.service_destinations.{name}]** URI to access the Podman service **uri="ssh://user@production.example.com/run/user/1001/podman/podman.sock"** diff --git a/storage.conf b/storage.conf index b914c3f..db5e541 100644 --- a/storage.conf +++ b/storage.conf @@ -55,7 +55,7 @@ additionalimagestores = [ # can deduplicate pulling of content, disk storage of content and can allow the # kernel to use less memory when running containers. -# containers/storage supports four keys +# containers/storage supports three keys # * enable_partial_images="true" | "false" # Tells containers/storage to look for files previously pulled in storage # rather then always pulling them from the container registry. @@ -75,8 +75,8 @@ pull_options = {enable_partial_images = "false", use_hard_links = "false", ostre # mappings which the kernel will allow when you later attempt to run a # container. # -# remap-uids = 0:1668442479:65536 -# remap-gids = 0:1668442479:65536 +# remap-uids = "0:1668442479:65536" +# remap-gids = "0:1668442479:65536" # Remap-User/Group is a user name which can be used to look up one or more UID/GID # ranges in the /etc/subuid or /etc/subgid file. Mappings are set up starting @@ -84,7 +84,8 @@ pull_options = {enable_partial_images = "false", use_hard_links = "false", ostre # range that matches the specified name, and using the length of that range. # Additional ranges are then assigned, using the ranges which specify the # lowest host-level IDs first, to the lowest not-yet-mapped in-container ID, -# until all of the entries have been used for maps. +# until all of the entries have been used for maps. This setting overrides the +# Remap-UIDs/GIDs setting. # # remap-user = "containers" # remap-group = "containers" @@ -100,7 +101,7 @@ pull_options = {enable_partial_images = "false", use_hard_links = "false", ostre # Auto-userns-min-size is the minimum size for a user namespace created automatically. # auto-userns-min-size=1024 # -# Auto-userns-max-size is the minimum size for a user namespace created automatically. +# Auto-userns-max-size is the maximum size for a user namespace created automatically. # auto-userns-max-size=65536 [storage.options.overlay]