From 3d4e4fdc6f444a474beb522d51931f98fa0d96c1 Mon Sep 17 00:00:00 2001 From: Daniel J Walsh Date: Tue, 7 Apr 2020 09:37:17 -0400 Subject: [PATCH] Update man pages to match upstream --- containers-auth.json.5.md | 43 +++++++++++++++++++++++++++++++ containers-certs.d.5.md | 2 +- containers-registries.conf.5.md | 36 ++++++++++++++------------ containers-registries.conf.d.5.md | 36 ++++++++++++++++++++++++++ containers-storage.conf.5.md | 28 +++++++++++++++++--- skopeo.spec | 7 ++++- 6 files changed, 131 insertions(+), 21 deletions(-) create mode 100644 containers-auth.json.5.md create mode 100644 containers-registries.conf.d.5.md diff --git a/containers-auth.json.5.md b/containers-auth.json.5.md new file mode 100644 index 0000000..16e4d7b --- /dev/null +++ b/containers-auth.json.5.md @@ -0,0 +1,43 @@ +% containers-auth.json(5) + +# NAME +containers-auth.json - syntax for the registry authentication file + +# DESCRIPTION + +A credentials file stored at `${XDG_RUNTIME_DIR}/containers/auth.json` in +json format used to authenticate against container image registries. + +## FORMAT + +The auth.json file stores encrypted authentication information for the +user 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` or +`buildah login`. Each entry includes the name of the registry and then an auth +token in the form of a base64 encoded string from the concatenation of the +username, a colon, and the password. + +The following example shows the values found in auth.json after the user logged in to +their accounts on quay.io and docker.io: + +``` +{ + "auths": { + "docker.io": { + "auth": "erfi7sYi89234xJUqaqxgmzcnQ2rRFWM5aJX0EC=" + }, + "quay.io": { + "auth": "juQAqGmz5eR1ipzx8Evn6KGdw8fEa1w5MWczmgY=" + } + } +} +``` + +An entry can be removed by using a `logout` command from a container +tool such as `podman logout` or `buildah logout`. + +# SEE ALSO + buildah-login(1), buildah-logout(1), podman-login(1), podman-logout(1) + +# HISTORY +Feb 2020, Originally compiled by Tom Sweeney diff --git a/containers-certs.d.5.md b/containers-certs.d.5.md index ffd7e4b..1c76152 100644 --- a/containers-certs.d.5.md +++ b/containers-certs.d.5.md @@ -4,7 +4,7 @@ containers-certs.d - Directory for storing custom container-registry TLS configurations # DESCRIPTION -A custom TLS configuration for a container registry can be configured by creating a directory under `/etc/containers/certs.d`. +A custom TLS configuration for a container registry can be configured by creating a directory under `$HOME/.config/containers/certs.d` or `/etc/containers/certs.d`. The name of the directory must correspond to the `host:port` of the registry (e.g., `my-registry.com:5000`). ## Directory Structure diff --git a/containers-registries.conf.5.md b/containers-registries.conf.5.md index c696949..bb34906 100644 --- a/containers-registries.conf.5.md +++ b/containers-registries.conf.5.md @@ -9,7 +9,7 @@ containers-registries.conf - Syntax of System Registry Configuration File The CONTAINERS-REGISTRIES configuration file is a system-wide configuration file for container image registries. The file format is TOML. -By default, the configuration file is located at `/etc/containers/registries.conf`. +Container engines will use the `$HOME/.config/containers/registries.conf` if it exists, otherwise they will use `/etc/containers/registries.conf` # FORMATS @@ -150,7 +150,7 @@ insecure = true Given the above, a pull of `example.com/foo/image:latest` will try: 1. `example-mirror-0.local/mirror-for-foo/image:latest` 2. `example-mirror-1.local/mirrors/foo/image:latest` - 3. `internal-registry-for-example.net/bar/myimage:latest` + 3. `internal-registry-for-example.net/bar/image:latest` in order, and use the first one that exists. @@ -187,26 +187,30 @@ registries = ['registry3.com'] registries = ['registry.untrusted.com', 'registry.unsafe.com'] ``` -## NOTE: RISK OF USING UNQUALIFIED IMAGE NAMES. -Pulling an image that is not fully qualified, i.e., one that includes the -image name but does not include the registry or tag, is not recommended. -There is a risk that the image being pulled could be spoofed. An example -of this would be if a user wanted to pull an image named `foobar` from a -registry and expect it to come from myregistry.com. If myregistry.com is -not first in the search list, an attacker could place a different `foobar` -image at a registry earlier in the search list. Now you would accidentally -run the attackers code rather than the intended content. Registries that -are added to this list should be completely controlled, i.e., not allow -unknown/arbitrary users being able to create accounts with arbitrary names -to prevent an image from being spoofed, squatted or otherwise made -insecure. If it is necessary to use one of these registries, it should be -added at the end of the list. +# NOTE: RISK OF USING UNQUALIFIED IMAGE NAMES +We recommend always using fully qualified image names including the registry +server (full dns name), namespace, image name, and tag +(e.g., registry.redhat.io/ubi8/ubi:latest). When using short names, there is +always an inherent risk that the image being pulled could be spoofed. For +example, a user wants to pull an image named `foobar` from a registry and +expects it to come from myregistry.com. If myregistry.com is not first in the +search list, an attacker could place a different `foobar` image at a registry +earlier in the search list. The user would accidentally pull and run the +attacker's image and code rather than the intended content. We recommend only +adding registries which are completely trusted, i.e. registries which don't +allow unknown or anonymous users to create accounts with arbitrary names. This +will prevent an image from being spoofed, squatted or otherwise made insecure. +If it is necessary to use one of these registries, it should be added at the +end of the list. It is recommended to use fully-qualified images for pulling as the destination registry is unambiguous. Pulling by digest (i.e., quay.io/repository/name@digest) further eliminates the ambiguity of tags. +# SEE ALSO + containers-certs.d(5) + # HISTORY Dec 2019, Warning added for unqualified image names by Tom Sweeney diff --git a/containers-registries.conf.d.5.md b/containers-registries.conf.d.5.md new file mode 100644 index 0000000..1fb079f --- /dev/null +++ b/containers-registries.conf.d.5.md @@ -0,0 +1,36 @@ +% CONTAINERS-REGISTRIES.CONF.D(5) +% Valentin Rothberg +% Mar 2020 + +# NAME +containers-registries.conf.d - directory for drop-in registries.conf files + +# DESCRIPTION +CONTAINERS-REGISTRIES.CONF.D is a system-wide directory for drop-in +configuration files in the `containers-registries.conf(5)` format. + +By default, the directory is located at `/etc/containers/registries.conf.d`. + +# CONFIGURATION PRECEDENCE + +Once the main configuration at `/etc/containers/registries.conf` is loaded, the +files in `/etc/containers/registries.conf.d` are loaded in alpha-numerical +order. Specified fields in a config will overwrite any previous setting. Note +that only files with the `.conf` prefix are loaded, other files and +sub-directories are ignored. + +For instance, setting the `unqualified-search-registries` in +`/etc/containers/registries.conf.d/myregistries.conf` will overwrite previous +settings in `/etc/containers/registries.conf`. The `[[registry]]` tables merged +by overwriting existing items if the prefixes are identical while new ones are +added. + +All drop-in configuration files must be specified in the version 2 of the +`containers-registries.conf(5)` format. + +# SEE ALSO +`containers-registries.conf(5)` + +# HISTORY + +Mar 2020, Originally compiled by Valentin Rothberg diff --git a/containers-storage.conf.5.md b/containers-storage.conf.5.md index 28346aa..aa328a4 100644 --- a/containers-storage.conf.5.md +++ b/containers-storage.conf.5.md @@ -34,6 +34,19 @@ The `storage` table supports the following options: container storage graph dir (default: "/var/lib/containers/storage") Default directory to store all writable content created by container storage programs. +**rootless_storage_path**="$HOME/.local/share/containers/storage" + Storage path for rootless users. By default the graphroot for rootless users +is set to `$XDG_DATA_HOME/containers/storage`, if XDG_DATA_HOME is set. +Otherwise `$HOME/.local/share/containers/storage` is used. This field can +be used if administrators need to change the storage location for all users. + + The rootless storage path supports three substations: + * `$HOME` => Replaced by the users home directory. + * `$UID` => Replaced by the users UID + * `$USER` => Replaced by the users name + + 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). + **runroot**="" container storage run dir (default: "/var/run/containers/storage") Default directory to store all temporary writable content created by container storage programs. @@ -60,8 +73,17 @@ The `storage.options` table supports the following options: 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. Example - remap-user = "storage" - remap-group = "storage" + remap-user = "containers" + remap-group = "containers" + +**root-auto-userns-user**="" + Root-auto-userns-user is a user name which can be used to look up one or more UID/GID ranges in the /etc/subuid and /etc/subgid file. These ranges will be partioned to containers configured to create automatically a user namespace. Containers configured to automatically create a user namespace can still overlap with containers having an explicit mapping set. This setting is ignored when running as rootless. + +**auto-userns-min-size**=1024 + Auto-userns-min-size is the minimum size for a user namespace created automatically. + +**auto-userns-max-size**=65536 + Auto-userns-max-size is the maximum size for a user namespace created automatically. ### STORAGE OPTIONS FOR AUFS TABLE @@ -199,7 +221,7 @@ Now all new content created in these directories will automatically be created w ## FILES -Distributions often provide a `/usr/share/containers/storage.conf` file to define default storage configuration. Administrators can override this file by creating `/etc/containers/storage.conf` to specify their own configuration. The storage.conf file for rootless users is stored in the `$HOME/.config/containers/storage.conf` file. +Distributions often provide a `/usr/share/containers/storage.conf` file to define default storage configuration. Administrators can override this file by creating `/etc/containers/storage.conf` to specify their own configuration. The storage.conf file for rootless users is stored in the `$XDG_CONFIG_HOME/containers/storage.conf` file. If `$XDG_CONFIG_HOME` is not set then the file `$HOME/.config/containers/storage.conf` is used. ## HISTORY May 2017, Originally compiled by Dan Walsh diff --git a/skopeo.spec b/skopeo.spec index 23184b8..2f0e201 100644 --- a/skopeo.spec +++ b/skopeo.spec @@ -46,7 +46,7 @@ Epoch: 1 Epoch: 2 %endif Version: 0.1.42 -Release: 1.0.dev.git%{shortcommit0}%{?dist} +Release: 2.0.dev.git%{shortcommit0}%{?dist} Summary: Inspect container images and repositories on registries License: ASL 2.0 URL: %{git0} @@ -65,6 +65,7 @@ Source11: containers-certs.d.5.md Source12: containers-registries.d.5.md Source13: containers.conf Source14: containers.conf.5.md +Source15: containers-auth.json.5.md %if 0%{?fedora} BuildRequires: go-srpm-macros @@ -325,6 +326,7 @@ go-md2man -in %{SOURCE10} -out %{buildroot}%{_mandir}/man5/containers-transports go-md2man -in %{SOURCE11} -out %{buildroot}%{_mandir}/man5/containers-certs.d.5 go-md2man -in %{SOURCE12} -out %{buildroot}%{_mandir}/man5/containers-registries.d.5 go-md2man -in %{SOURCE14} -out %{buildroot}%{_mandir}/man5/containers.conf.5 +go-md2man -in %{SOURCE15} -out %{buildroot}%{_mandir}/man5/containers-auth.json.5 mkdir -p %{buildroot}%{_datadir}/containers install -m0644 %{SOURCE3} %{buildroot}%{_datadir}/containers/mounts.conf @@ -434,6 +436,9 @@ export GOPATH=%{buildroot}/%{gopath}:$(pwd)/vendor:%{gopath} %{_datadir}/%{name}/test %changelog +* Tue Apr 7 2020 Dan Walsh - 1:0.1.42-2 +- Update man pages to match upstream + * Tue Apr 7 2020 Dan Walsh - 1:0.1.42-1 - Update containers.conf and containers.conf.5.md to upstream