Update man pages and storage.conf

Add update.sh to make getting man pages and configuration files easier

Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
This commit is contained in:
Daniel J Walsh 2020-11-16 09:04:15 -05:00
parent b75d939dd6
commit 5b779794fa
No known key found for this signature in database
GPG Key ID: A2DF901DABE2C028
9 changed files with 188 additions and 8 deletions

View File

@ -6,8 +6,15 @@ containers-auth.json - syntax for the registry authentication file
# DESCRIPTION # DESCRIPTION
A credentials file in JSON format used to authenticate against container image registries. A credentials file in JSON format used to authenticate against container image registries.
On Linux it is stored at `${XDG_RUNTIME_DIR}/containers/auth.json`; 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` 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`, `$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.
## FORMAT ## FORMAT

View File

@ -10,7 +10,7 @@ The mounts.conf file specifies volume mount directories that are automatically m
The format of the mounts.conf is the volume format `/SRC:/DEST`, one mount per line. For example, a mounts.conf with the line `/usr/share/secrets:/run/secrets` would cause the contents of the `/usr/share/secrets` directory on the host to be mounted on the `/run/secrets` directory inside the container. Setting mountpoints allows containers to use the files of the host, for instance, to use the host's subscription to some enterprise Linux distribution. The format of the mounts.conf is the volume format `/SRC:/DEST`, one mount per line. For example, a mounts.conf with the line `/usr/share/secrets:/run/secrets` would cause the contents of the `/usr/share/secrets` directory on the host to be mounted on the `/run/secrets` directory inside the container. Setting mountpoints allows containers to use the files of the host, for instance, to use the host's subscription to some enterprise Linux distribution.
## FILES ## FILES
Some distributions may provide a `/usr/share/containers/mounts.conf` file to provide default mounts, but users can create a `/etc/containers/mounts.conf`, to specify their own special volumes to mount in the container. Some distributions may provide a `/usr/share/containers/mounts.conf` file to provide default mounts, but users can create a `/etc/containers/mounts.conf`, to specify their own special volumes to mount in the container. When Podman runs in rootless mode, the file `$HOME/.config/containers/mounts.conf` will override the default if it exists.
## HISTORY ## HISTORY
Aug 2018, Originally compiled by Valentin Rothberg <vrothberg@suse.com> Aug 2018, Originally compiled by Valentin Rothberg <vrothberg@suse.com>

View File

@ -102,6 +102,75 @@ internet without having to change `Dockerfile`s, or to add redundancy).
*Note*: Redirection and mirrors are currently processed only when reading images, not when pushing *Note*: Redirection and mirrors are currently processed only when reading images, not when pushing
to a registry; that may change in the future. to a registry; that may change in the future.
#### Short-Name Aliasing
The use of unqualified-search registries entails an ambiguity as it is
unclear from which registry a given image, referenced by a short name,
may be pulled from.
As mentioned in the note at the end of this man page, using short names is
subject to the risk of hitting squatted registry namespaces. If the
unqualified-search registries are set to `["registry1.com", "registry2.com"]`
an attacker may take over a namespace of registry1.com such that an image may
be pulled from registry1.com instead of the intended source registry2.com.
While it is highly recommended to always use fully-qualified image references,
existing deployments using short names may not be easily changed. To
circumvent the aforementioned ambiguity, so called short-name aliases can be
configured that point to a fully-qualified image
reference.
Short-name aliases can be configured in the `[aliases]` table in the form of
`"name"="value"` with the left-hand `name` being the short name (e.g., "image")
and the right-hand `value` being the fully-qualified image reference (e.g.,
"registry.com/namespace/image"). Note that neither "name" nor "value" can
include a tag or digest. Moreover, "name" must be a short name and hence
cannot include a registry domain or refer to localhost.
When pulling a short name, the configured aliases table will be used for
resolving the short name. If a matching alias is found, it will be used
without further consulting the unqualified-search registries list. If no
matching alias is found, the behavior can be controlled via the
`short-name-mode` option as described below.
Note that tags and digests are stripped off a user-specified short name for
alias resolution. Hence, "image", "image:tag" and "image@digest" all resolve
to the same alias (i.e., "image"). Stripped off tags and digests are later
appended to the resolved alias.
Further note that drop-in configuration files (see containers-registries.conf.d(5))
can override aliases in the specific loading order of the files. If the "value" of
an alias is empty (i.e., ""), the alias will be erased. However, a given
"name" may only be specified once in a single config file.
#### Short-Name Aliasing: Modes
The `short-name-mode` option supports three modes to control the behaviour of
short-name resolution.
* `enforcing`: If only one unqualified-search registry is set, use it as there
is no ambiguity. If there is more than one registry and the user program is
running in a terminal (i.e., stdout & stdin are a TTY), prompt the user to
select one of the specified search registries. If the program is not running
in a terminal, the ambiguity cannot be resolved which will lead to an error.
* `permissive`: Behaves as enforcing but does not lead to an error if the
program is not running in a terminal. Instead, fallback to using all
unqualified-search registries.
* `disabled`: Use all unqualified-search registries without prompting.
If `short-name-mode` is not specified at all or left empty, default to the
`permissive` mode. If the user-specified short name was not aliased already,
the `enforcing` and `permissive` mode if prompted, will record a new alias
after a successful pull. Note that the recorded alias will be written to
`$XDG_CONFIG_HOME/containers/short-name-aliases.conf` to have a clear
separation between possibly human-edited registries.conf files and the
machine-generated `short-name-aliases-conf`. Note that `$HOME/.config` is used
if `$XDG_CONFIG_HOME` is not set. If an alias is specified in a
`registries.conf` file and also the machine-generated
`short-name-aliases.conf`, the `short-name-aliases.conf` file has precedence.
#### Normalization of docker.io references #### Normalization of docker.io references
The Docker Hub `docker.io` is handled in a special way: every push and pull The Docker Hub `docker.io` is handled in a special way: every push and pull

View File

@ -61,6 +61,11 @@ more general scopes is ignored. For example, if _any_ configuration exists for
`docker.io/library/busybox`, the configuration for `docker.io` is ignored `docker.io/library/busybox`, the configuration for `docker.io` is ignored
(even if some element of the configuration is defined for `docker.io` and not for `docker.io/library/busybox`). (even if some element of the configuration is defined for `docker.io` and not for `docker.io/library/busybox`).
### Built-in Defaults
If no `docker` section can be found for the container image, and no `default-docker` section is configured,
the default directory, `/var/lib/containers/sigstore` for root and `$HOME/.local/share/containers/sigstore` for unprivileged user, will be used for reading and writing signatures.
## Individual Configuration Sections ## Individual Configuration Sections
A single configuration section is selected for a container image using the process A single configuration section is selected for a container image using the process
@ -77,6 +82,7 @@ described above. The configuration section is a YAML mapping, with the followin
This key is optional; if it is missing, no signature storage is defined (no signatures This key is optional; if it is missing, no signature storage is defined (no signatures
are download along with images, adding new signatures is possible only if `sigstore-staging` is defined). are download along with images, adding new signatures is possible only if `sigstore-staging` is defined).
## Examples ## Examples
### Using Containers from Various Origins ### Using Containers from Various Origins

View File

@ -149,7 +149,7 @@ The `storage.options.thinpool` table supports the following options for the `dev
Comma separated list of default options to be used to mount container images. Suggested value "nodev". Mount options are documented in the mount(8) man page. Comma separated list of default options to be used to mount container images. Suggested value "nodev". Mount options are documented in the mount(8) man page.
**size**="" **size**=""
Maximum size of a container image. This flag can be used to set quota on the size of container images. (format: <number>[<unit>], where unit = b (bytes), k (kilobytes), m (megabytes), or g (gigabytes)) Maximum size of a container image. This flag can be used to set quota on the size of container images. (format: <number>[<unit>], where unit = b (bytes), k (kilobytes), m (megabytes), or g (gigabytes))
**use_deferred_deletion**="" **use_deferred_deletion**=""
Marks thinpool device for deferred deletion. If the thinpool is in use when the driver attempts to delete it, the driver will attempt to delete device every 30 seconds until successful, or when it restarts. Deferred deletion permanently deletes the device and all data stored in the device will be lost. (default: true). Marks thinpool device for deferred deletion. If the thinpool is in use when the driver attempts to delete it, the driver will attempt to delete device every 30 seconds until successful, or when it restarts. Deferred deletion permanently deletes the device and all data stored in the device will be lost. (default: true).
@ -167,6 +167,39 @@ The `storage.options.overlay` table supports the following options:
**ignore_chown_errors** = "false" **ignore_chown_errors** = "false"
ignore_chown_errors can be set to allow a non privileged user running with a single UID within a user namespace to run containers. The user can pull and use any image even those with multiple uids. Note multiple UIDs will be squashed down to the default uid in the container. These images will have no separation between the users in the container. (default: false) ignore_chown_errors can be set to allow a non privileged user running with a single UID within a user namespace to run containers. The user can pull and use any image even those with multiple uids. Note multiple UIDs will be squashed down to the default uid in the container. These images will have no separation between the users in the container. (default: false)
**force_mask** = "0000|shared|private"
ForceMask specifies the permissions mask that is used for new files and
directories.
The values "shared" and "private" are accepted. (default: ""). Octal permission
masks are also accepted.
``: Not set
All files/directories, get set with the permissions identified within the
image.
`private`: it is equivalent to 0700.
All files/directories get set with 0700 permissions. The owner has rwx
access to the files. No other users on the system can access the files.
This setting could be used with networked based home directories.
`shared`: it is equivalent to 0755.
The owner has rwx access to the files and everyone else can read, access
and execute them. This setting is useful for sharing containers storage
with other users. For instance, a storage owned by root could be shared
to rootless users as an additional store.
NOTE: All files within the image are made readable and executable by any
user on the system. Even /etc/shadow within your image is now readable by
any user.
`OCTAL`: Users can experiment with other OCTAL Permissions.
Note: The force_mask Flag is an experimental feature, it could change in the
future. When "force_mask" is set the original permission mask is stored in the
"user.containers.override_stat" xattr and the "mount_program" option must be
specified. Mount programs like "/usr/bin/fuse-overlayfs" present the extended
attribute permissions to processes within containers rather then the
"force_mask" permissions.
**mount_program**="" **mount_program**=""
Specifies the path to a custom program to use instead of using kernel defaults Specifies the path to a custom program to use instead of using kernel defaults
for mounting the file system. In rootless mode, without the CAP_SYS_ADMIN for mounting the file system. In rootless mode, without the CAP_SYS_ADMIN
@ -221,7 +254,7 @@ The semanage command above tells SELinux to setup the default labeling of `NEWST
Now all new content created in these directories will automatically be created with the correct label. Now all new content created in these directories will automatically be created with the correct label.
## SEE ALSO ## SEE ALSO
`semanage(8)`, `restorecon(8)`, `mount(8)` `semanage(8)`, `restorecon(8)`, `mount(8)`, `fuse-overlayfs(1)`
## FILES ## FILES

View File

@ -18,8 +18,8 @@
# of these registries, it should be added at the end of the list. # of these registries, it should be added at the end of the list.
# #
# # An array of host[:port] registries to try when pulling an unqualified image, in order. # # An array of host[:port] registries to try when pulling an unqualified image, in order.
unqualified-search-registries = ['registry.fedoraproject.org', 'registry.access.redhat.com', 'registry.centos.org', 'docker.io'] unqualified-search-registries = ["registry.fedoraproject.org", "registry.access.redhat.com", "registry.centos.org", "docker.io"]
#
# [[registry]] # [[registry]]
# # The "prefix" field is used to choose the relevant [[registry]] TOML table; # # The "prefix" field is used to choose the relevant [[registry]] TOML table;
# # (only) the TOML table with the longest match for the input image name # # (only) the TOML table with the longest match for the input image name

View File

@ -46,7 +46,7 @@ Epoch: 1
Epoch: 2 Epoch: 2
%endif %endif
Version: 1.2.1 Version: 1.2.1
Release: 19.dev.git%{shortcommit0}%{?dist} Release: 20.dev.git%{shortcommit0}%{?dist}
Summary: Inspect container images and repositories on registries Summary: Inspect container images and repositories on registries
License: ASL 2.0 License: ASL 2.0
URL: %{git0} URL: %{git0}
@ -449,6 +449,10 @@ export GOPATH=%{buildroot}/%{gopath}:$(pwd)/vendor:%{gopath}
%{_datadir}/%{name}/test %{_datadir}/%{name}/test
%changelog %changelog
* Mon Nov 16 2020 Dan Walsh <dwalsh@fedoraproject.org> - 1:1.2.1-20.dev.git1a3ae14
- Update man pages and storage.conf
- Add update.sh to make getting man pages and configuration files easier
* Fri Nov 13 2020 RH Container Bot <rhcontainerbot@fedoraproject.org> - 1:1.2.1-19.dev.git4ad2c75 * Fri Nov 13 2020 RH Container Bot <rhcontainerbot@fedoraproject.org> - 1:1.2.1-19.dev.git4ad2c75
- autobuilt 4ad2c75 - autobuilt 4ad2c75

View File

@ -82,6 +82,39 @@ mountopt = "nodev,metacopy=on"
# Size is used to set a maximum size of the container image. # Size is used to set a maximum size of the container image.
# size = "" # size = ""
# ForceMask specifies the permissions mask that is used for new files and
# directories.
#
# The values "shared" and "private" are accepted.
# Octal permission masks are also accepted.
#
# "": No value specified.
# All files/directories, get set with the permissions identified within the
# image.
# "private": it is equivalent to 0700.
# All files/directories get set with 0700 permissions. The owner has rwx
# access to the files. No other users on the system can access the files.
# This setting could be used with networked based homedirs.
# "shared": it is equivalent to 0755.
# The owner has rwx access to the files and everyone else can read, access
# and execute them. This setting is useful for sharing containers storage
# with other users. For instance have a storage owned by root but shared
# to rootless users as an additional store.
# NOTE: All files within the image are made readable and executable by any
# user on the system. Even /etc/shadow within your image is now readable by
# any user.
#
# OCTAL: Users can experiment with other OCTAL Permissions.
#
# Note: The force_mask Flag is an experimental feature, it could change in the
# future. When "force_mask" is set the original permission mask is stored in
# the "user.containers.override_stat" xattr and the "mount_program" option must
# be specified. Mount programs like "/usr/bin/fuse-overlayfs" present the
# extended attribute permissions to processes within containers rather then the
# "force_mask" permissions.
#
# force_mask = ""
[storage.options.thinpool] [storage.options.thinpool]
# Storage Options for thinpool # Storage Options for thinpool

28
update.sh Executable file
View File

@ -0,0 +1,28 @@
clone() {
git clone https://github.com/containers/$1.git 2>/dev/null || true
pushd $1
git config pull.rebase false
git pull origin master
popd
}
#!/bin/sh
clone storage
sed -e 's/^driver.*=.*/driver = "overlay"/' -e 's/^mountopt.*=.*/mountopt = "nodev,metacopy=on"/' storage/storage.conf > storage.conf
cp storage/docs/containers-storage.conf.5.md .
clone image
cp image/docs/*md .
sed -e 's/^#.*unqualified-search-registries.*=.*/unqualified-search-registries = ["registry.fedoraproject.org", "registry.access.redhat.com", "registry.centos.org", "docker.io"]/g' image/registries.conf > registries.conf
rm signature-protocols.md
clone common
cp common/docs/*md .
cp common/pkg/config/containers.conf .
sed -e '/\"kill\",/i \
"keyctl",' \
-e '/\"socketcall\",/i \
"socket",' common/pkg/seccomp/seccomp.json > seccomp.json
sed -e 's/^#.*unqualified-search-registries.*=.*/unqualified-search-registries = ["registry.fedoraproject.org", "registry.access.redhat.com", "registry.centos.org", "docker.io"]/g' image/registries.conf > registries.conf
clone podman
cp podman/docs/source/markdown/containers-mounts.conf.5.md .