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>

containers-auth.json.5.md

@@ -6,8 +6,15 @@ containers-auth.json - syntax for the registry authentication file
 # DESCRIPTION
 
 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
 

containers-mounts.conf.5.md

@@ -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.
 
 ## 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
 Aug 2018, Originally compiled by Valentin Rothberg <vrothberg@suse.com>

containers-registries.conf.5.md

@@ -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
 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
 
 The Docker Hub `docker.io` is handled in a special way: every push and pull

containers-registries.d.5.md

@@ -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
 (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
 
 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
    are download along with images, adding new signatures is possible only if `sigstore-staging` is defined).
 
+
 ## Examples
 
 ### Using Containers from Various Origins

containers-storage.conf.5.md

@@ -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.
 
 **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**=""
   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 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**=""
   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
@@ -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.
 
 ## SEE ALSO
-`semanage(8)`, `restorecon(8)`, `mount(8)`
+`semanage(8)`, `restorecon(8)`, `mount(8)`, `fuse-overlayfs(1)`
 
 ## FILES
 

registries.conf

@@ -18,8 +18,8 @@
 # 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.
-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]]
 # # 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

skopeo.spec

@@ -46,7 +46,7 @@ Epoch: 1
 Epoch: 2
 %endif
 Version: 1.2.1
-Release: 19.dev.git%{shortcommit0}%{?dist}
+Release: 20.dev.git%{shortcommit0}%{?dist}
 Summary: Inspect container images and repositories on registries
 License: ASL 2.0
 URL: %{git0}
@@ -449,6 +449,10 @@ export GOPATH=%{buildroot}/%{gopath}:$(pwd)/vendor:%{gopath}
 %{_datadir}/%{name}/test
 
 %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
 - autobuilt 4ad2c75
 

storage.conf

@@ -82,6 +82,39 @@ mountopt = "nodev,metacopy=on"
 # Size is used to set a maximum size of the container image.
 # 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 for thinpool
 

update.sh

@@ -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 .