From 38422a38e752807cda278c71543484ad49c3290c Mon Sep 17 00:00:00 2001 From: TomSweeneyRedHat Date: Wed, 6 Feb 2019 10:43:26 -0500 Subject: Update image-trust man with further comments Signed-off-by: TomSweeneyRedHat After the last update, @mtrmac had some great suggestions which I've incorporated. I've updated the G:oogle doc and have added this PR in case it's easier to see the diffs. Signed-off-by: TomSweeneyRedHat --- docs/podman-image-trust.1.md | 30 ++++++++++++++++++------------ 1 file changed, 18 insertions(+), 12 deletions(-) (limited to 'docs') diff --git a/docs/podman-image-trust.1.md b/docs/podman-image-trust.1.md index 668fee0f3..819035040 100644 --- a/docs/podman-image-trust.1.md +++ b/docs/podman-image-trust.1.md @@ -14,19 +14,29 @@ podman\-trust - Manage container registry image trust policy REGISTRY[/REPOSITORY] # DESCRIPTION -Manages which registries you trust as a source of container images based on its location. The location is determined by the transport and the registry host of the image. Using this container image `docker://docker.io/library/busybox` as an example, `docker` is the transport and `docker.io` is the registry host. +Manages which registries you trust as a source of container images based on its location. The location is determined +by the transport and the registry host of the image. Using this container image `docker://docker.io/library/busybox` +as an example, `docker` is the transport and `docker.io` is the registry host. -The trust policy describes a registry scope (registry and/or repository). This trust can use public keys for signed images. +Trust is defined in **/etc/containers/policy.json** and is enforced when a user attempts to pull +a remote image from a registry. The trust policy in policy.json describes a registry scope (registry and/or repository) for the trust. This trust can use public keys for signed images. -Trust is defined in **/etc/containers/policy.json** and is enforced when a user attempts to pull an image from a registry that is managed by policy.json. +The scope of the trust is evaluated from most specific to the least specific. In other words, a policy may be defined for an entire registry. Or it could be defined for a particular repository in that registry. Or it could be defined down to a specific signed image inside of the registry. -The scope of the trust is evaluated from most specific to the least specific. In other words, a policy may be defined for an entire registry. Or it could be defined for a particular repository in that registry. Or it could be defined down to a specific signed image inside of the registry. See below for examples. +For example, the following list includes valid scope values that could be used in policy.json from most specific to the least specific: + +docker.io/library/busybox:notlatest +docker.io/library/busybox +docker.io/library +docker.io + +If no configuration is found for any of these scopes, the default value (specified by using "default" instead of REGISTRY[/REPOSITORY]) is used. Trust **type** provides a way to: Whitelist ("accept") or -Blacklist ("reject") registries. - +Blacklist ("reject") registries or +Require signature (“signedBy”). Trust may be updated using the command **podman image trust set** for an existing trust scope. @@ -36,10 +46,8 @@ Trust may be updated using the command **podman image trust set** for an existin **-f** **--pubkeysfile** A path to an exported public key on the local system. Key paths - will be referenced in policy.json. Any path may be used but the path - **/etc/pki/containers** is recommended. Options may be used multiple times to - require an image be signed by multiple keys. One of **--pubkeys** or - **--pubkeysfile** is required for the **signedBy** type. + will be referenced in policy.json. Any path to a file may be used but locating the file in **/etc/pki/containers** is recommended. Options may be used multiple times to + require an image be signed by multiple keys. The **--pubkeysfile** option is required for the **signedBy** type. **-t** **--type** The trust type for this policy entry. Accepted values: @@ -84,7 +92,5 @@ Display trust as JSON policy-json(5) # HISTORY - January 2019, updated by Tom Sweeney (tsweeney at redhat dot com) - December 2018, originally compiled by Qi Wang (qiwan at redhat dot com) -- cgit v1.2.3-54-g00ecf