diff --git a/containers-policy.json.5.md b/containers-policy.json.5.md index 6aa5f80..71d66c5 100644 --- a/containers-policy.json.5.md +++ b/containers-policy.json.5.md @@ -61,18 +61,41 @@ The global `default` set of policy requirements is mandatory; all of the other f ## Supported transports and their scopes +See containers-transports(5) for general documentation about the transports and their reference syntax. + ### `atomic:` -The `atomic:` transport refers to images in an Atomic Registry. +The deprecated `atomic:` transport refers to images in an Atomic Registry. Supported scopes use the form _hostname_[`:`_port_][`/`_namespace_[`/`_imagestream_ [`:`_tag_]]], i.e. either specifying a complete name of a tagged image, or prefix denoting -a host/namespace/image stream or a wildcarded expression for matching all +a host/namespace/image stream, or a wildcarded expression starting with `*.` for matching all subdomains. For wildcarded subdomain matching, `*.example.com` is a valid case, but `example*.*.com` is not. *Note:* The _hostname_ and _port_ refer to the container registry host and port (the one used e.g. for `docker pull`), _not_ to the OpenShift API host and port. +### `containers-storage:` + +Supported scopes have the form `[`_storage-specifier_`]`_image-scope_. + +`[`_storage-specifier_`]` is usually `[`_graph-driver-name_`@`_graph-root_`]`, e.g. `[overlay@/var/lib/containers/storage]`. + +_image-scope_ matching the individual image is +- a named Docker reference *in the fully expanded form*, either using a tag or digest. For example, `docker.io/library/busybox:latest` (*not* `busybox:latest`) +- and/or (depending on which one the user’s input provides) `@`_image-id_ + +More general scopes are prefixes of individual-image scopes, and specify a less-precisely-specified image, or a repository +(by omitting first the image ID, if any; then the digest, if any; and finally a tag, if any), +a repository namespace, or a registry host (by only specifying the host name and possibly a port number). + +Finally, two full-store specifiers matching all images in the store are valid scopes: +- `[`_graph-driver-name_`@`_graph-root_`]` and +- `[`_graph-root_`]` + +Note that some tools like Podman and Buildah hard-code overrides of the signature verification policy for “push” operations, +allowing these oprations regardless of configuration in `policy.json`. + ### `dir:` The `dir:` transport refers to images stored in local directories. @@ -80,10 +103,10 @@ The `dir:` transport refers to images stored in local directories. Supported scopes are paths of directories (either containing a single image or subdirectories possibly containing images). -*Note:* The paths must be absolute and contain no symlinks. Paths violating these requirements may be silently ignored. - -The top-level scope `"/"` is forbidden; use the transport default scope `""`, -for consistency with other transports. +*Note:* +- The paths must be absolute and contain no symlinks. Paths violating these requirements may be silently ignored. +- The top-level scope `"/"` is forbidden; use the transport default scope `""`, + for consistency with other transports. ### `docker:` @@ -93,24 +116,73 @@ Scopes matching individual images are named Docker references *in the fully expa using a tag or digest. For example, `docker.io/library/busybox:latest` (*not* `busybox:latest`). More general scopes are prefixes of individual-image scopes, and specify a repository (by omitting the tag or digest), -a repository namespace, or a registry host (by only specifying the host name) -or a wildcarded expression for matching all subdomains. For wildcarded subdomain +a repository namespace, or a registry host (by only specifying the host name and possibly a port number) +or a wildcarded expression starting with `*.`, for matching all subdomains (not including a port number). For wildcarded subdomain +matching, `*.example.com` is a valid case, but `example*.*.com` is not. + +### `docker-archive:` + +Only the default `""` scope is supported. + +### `docker-daemon:` + +For references using the _algo:digest_ format (referring to an image ID), only the default `""` scope is used. + +For images using a named reference, scopes matching individual images are *in the fully expanded form*, either +using a tag or digest. For example, `docker.io/library/busybox:latest` (*not* `busybox:latest`). + +More general named scopes are prefixes of individual-image scopes, and specify a repository (by omitting the tag or digest), +a repository namespace, or a registry host (by only specifying the host name and possibly a port number) +or a wildcarded expression starting with `*.`, for matching all subdomains (not including a port number). For wildcarded subdomain matching, `*.example.com` is a valid case, but `example*.*.com` is not. ### `oci:` The `oci:` transport refers to images in directories compliant with "Open Container Image Layout Specification". -Supported scopes use the form _directory_`:`_tag_, and _directory_ referring to -a directory containing one or more tags, or any of the parent directories. +Supported scopes are paths to directories +(either containing an OCI layout, or subdirectories possibly containing OCI layout directories). +The _reference_ annotation value, if any, is not used. -*Note:* See `dir:` above for semantics and restrictions on the directory paths, they apply to `oci:` equivalently. +*Note:* +- The paths must be absolute and contain no symlinks. Paths violating these requirements may be silently ignored. +- The top-level scope `"/"` is forbidden; use the transport default scope `""`, + for consistency with other transports. + +### `oci-archive:` + +Supported scopes are paths to OCI archives, and their parent directories +(either containing a single archive, or subdirectories possibly containing archives). +The _reference_ annotation value, if any, is not used. + +*Note:* +- The paths must be absolute and contain no symlinks. Paths violating these requirements may be silently ignored. +- The top-level scope `"/"` is forbidden; use the transport default scope `""`, + for consistency with other transports. + +### `ostree`: + +Supported scopes have the form _repo-path_`:`_image-scope_; _repo_path_ is the path to the OSTree repository. + +_image-scope_ is the _docker_reference_ part of the reference, with with a `:latest` tag implied if no tag is present, +and parent namespaces of the _docker_reference_ value (by omitting the tag, or a prefix speciyfing a higher-level namespace). + +*Note:* +- The _repo_path_ must be absolute and contain no symlinks. Paths violating these requirements may be silently ignored. + +### `sif:` + +Supported scopes are paths to Singularity images, and their parent directories +(either containing images, or subdirectories possibly containing images). + +*Note:* +- The paths must be absolute and contain no symlinks. Paths violating these requirements may be silently ignored. +- The top-level scope `"/"` is forbidden; use the transport default scope `""`, + for consistency with other transports. ### `tarball:` -The `tarball:` transport refers to tarred up container root filesystems. - -Scopes are ignored. +The `tarball:` transport is an implementation detail of some import workflows. Only the default `""` scope is supported. ## Policy Requirements diff --git a/containers-transports.5.md b/containers-transports.5.md index 0f4cacf..8ec42fe 100644 --- a/containers-transports.5.md +++ b/containers-transports.5.md @@ -16,6 +16,8 @@ they are evaluated. For example: if evaluated on a remote server, image names might refer to paths on that server; relative paths are relative to the current directory of the image consumer. + + ### **containers-storage**:[**[**storage-specifier**]**]{image-id|docker-reference[@image-id]} An image located in a local containers storage. @@ -54,7 +56,7 @@ Alternatively, for reading archives, @_source-index_ is a zero-based index in ar (to access untagged images). If neither _docker-reference_ nor @_source_index is specified when reading an archive, the archive must contain exactly one image. -It is further possible to copy data to stdin by specifying `docker-archive:/dev/stdin` but note that the used file must be seekable. +The _path_ can refer to a stream, e.g. `docker-archive:/dev/stdin`. ### **docker-daemon:**_docker-reference|algo:digest_ @@ -66,21 +68,31 @@ The _algo:digest_ refers to the image ID reported by docker-inspect(1). 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_. +The _path_ value terminates at the first `:` character; any further `:` characters are not separators, but a part of _reference_. +The _reference_ is used to set, or match, the `org.opencontainers.image.ref.name` annotation in the top-level index. +If _reference_ is not specified when reading an image, the directory must contain exactly one image. ### **oci-archive:**_path[:reference]_ 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_. +The _path_ value terminates at the first `:` character; any further `:` characters are not separators, but a part of _reference_. +The _reference_ is used to set, or match, the `org.opencontainers.image.ref.name` annotation in the top-level index. +If _reference_ is not specified when reading an archive, the archive must contain exactly one image. ### **ostree:**_docker-reference[@/absolute/repo/path]_ An image in the local ostree(1) repository. _/absolute/repo/path_ defaults to _/ostree/repo_. +### **sif:**_path_ + +An image using the Singularity image format at _path_. + +Only reading images is supported, and not all scripts can be represented in the OCI format. + + + ## Examples The following examples demonstrate how some of the containers transports can be used. diff --git a/containers.conf b/containers.conf index 9bd9249..f1970ab 100644 --- a/containers.conf +++ b/containers.conf @@ -669,6 +669,9 @@ log_driver = "journald" # A value of 0 is treated as no timeout. #volume_plugin_timeout = 5 +# Default timeout in seconds for podmansh logins. +#podmansh_timeout = 30 + # Paths to look for a valid OCI runtime (crun, runc, kata, runsc, krun, etc) [engine.runtimes] #crun = [ diff --git a/containers.conf.5.md b/containers.conf.5.md index c9b399e..a9666b7 100644 --- a/containers.conf.5.md +++ b/containers.conf.5.md @@ -730,6 +730,10 @@ 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. +**podmansh_timeout**=30 + +Number of seconds to wait for podmansh logins. + ## 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.