From 0ac508f1330bb881e1e22a851c4f4228bef2f5f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miloslav=20Trma=C4=8D?= Date: Sat, 15 Jul 2023 02:07:47 +0200 Subject: [PATCH] Improve containers-transports(5) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add missing sif: - Add comments about intentionally-excluded atomic: and tarball: - docker-archive: can now transparently handle non-seekable streams - Clarify documentation of references in OCI transports Signed-off-by: Miloslav Trmač --- docs/containers-transports.5.md | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/docs/containers-transports.5.md b/docs/containers-transports.5.md index 0f4cacfe..8ec42fe8 100644 --- a/docs/containers-transports.5.md +++ b/docs/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.