Merge pull request #2066 from cgwalters/toml-cleanup

storage.conf: Various cleanups

Author: rhatdan

docs/containers-storage-composefs.md

@@ -3,7 +3,6 @@
 ## NAME
 containers-storage-composefs - Information about composefs and containers/storage
 
-
 ## DESCRIPTION
 
 To enable composefs at a baseline requires the following configuration in `containers-storage.conf`:
@@ -13,6 +12,8 @@ To enable composefs at a baseline requires the following configuration in `conta
 use_composefs = "true"
 ```
 
+This value must be a "string bool", it cannot be a native TOML boolean.
+
 However at the current time, composefs requires zstd:chunked images, so first
 you must be sure that zstd:chunked is enabled. For more, see [zstd:chunked](containers-storage-zstd-chunked.md).
 
@@ -23,9 +24,12 @@ latency to image pulls.
 Putting these things together, the following is required (in addition to the above config).
 
 ```
-pull_options = {enable_partial_images = "true", use_hard_links = "false", ostree_repos="", convert_images = "true"}
+[storage.options.pull_options]
+convert_images = "true"
 ```
 
+This value must be a "string bool", it cannot be a native TOML boolean.
+
 ## BUGS
 
 - https://github.com/containers/storage/issues?q=is%3Aissue+is%3Aopen+label%3Aarea%2Fcomposefs

docs/containers-storage-zstd-chunked.md

@@ -16,13 +16,16 @@ to include additional metadata (especially a "table of contents") that includes
 Additionally chunks are compressed separately. This allows a client to dynamically fetch only content which
 it doesn't already have using HTTP range requests.
 
-To enable zstd:chunked requires the following changes to `containers-storage.conf`:
+At the time of this writing, support for this is enabled by default in the code.
+
+You can explicitly enable or disable zstd:chunked with following changes to `containers-storage.conf`:
 
 ```
-pull_options = {enable_partial_images = "true", use_hard_links = "false", ostree_repos=""}
+[storage.overlay.pull_options]
+enable_partial_images = "true" | "false"
 ```
 
-This option may or may not be enabled by default in your distribution/operating system.
+Note that the value of this field must be a "string bool", it cannot be a native TOML boolean.
 
 ## INTERNALS
 

storage.conf

@@ -54,32 +54,31 @@ graphroot = "/var/lib/containers/storage"
 additionalimagestores = [
 ]
 
-# Allows specification of how storage is populated when pulling images. This
-# option can speed the pulling process of images compressed with format
-# zstd:chunked. Containers/storage looks for files within images that are being
-# pulled from a container registry that were previously pulled to the host.  It
-# can copy or create a hard link to the existing file when it finds them,
-# eliminating the need to pull them from the container registry. These options
-# can deduplicate pulling of content, disk storage of content and can allow the
-# kernel to use less memory when running containers.
-
-# containers/storage supports four keys
-#   * enable_partial_images="true" | "false"
-#     Tells containers/storage to look for files previously pulled in storage
-#     rather then always pulling them from the container registry.
-#   * use_hard_links = "false" | "true"
-#     Tells containers/storage to use hard links rather then create new files in
-#     the image, if an identical file already existed in storage.
-#   * ostree_repos = ""
-#     Tells containers/storage where an ostree repository exists that might have
-#     previously pulled content which can be used when attempting to avoid
-#     pulling content from the container registry
-#   * convert_images = "false" | "true"
-#     If set to true, containers/storage will convert images to a
-#     format compatible with partial pulls in order to take advantage
-#     of local deduplication and hard linking.  It is an expensive
-#     operation so it is not enabled by default.
-pull_options = {enable_partial_images = "true", use_hard_links = "false", ostree_repos=""}
+# Options controlling how storage is populated when pulling images. 
+[storage.options.pull_options]
+# Enable the "zstd:chunked" feature, which allows partial pulls, reusing
+# content that already exists on the system. This is enabled by default,
+# but can be explicitly disabled. For more on zstd:chunked, see
+# https://github.com/containers/storage/blob/main/docs/containers-storage-zstd-chunked.md
+# This is a "string bool": "false" | "true" (cannot be native TOML boolean)
+# enable_partial_images = "true"
+
+# Tells containers/storage to use hard links rather then create new files in
+# the image, if an identical file already existed in storage.
+# This is a "string bool": "false" | "true" (cannot be native TOML boolean)
+# use_hard_links = "false"
+
+# Path to an ostree repository that might have
+# previously pulled content which can be used when attempting to avoid
+# pulling content from the container registry
+# ostree_repos=""
+
+# If set to "true", containers/storage will convert images to a
+# format compatible with partial pulls in order to take advantage
+# of local deduplication and hard linking.  It is an expensive
+# operation so it is not enabled by default.
+# This is a "string bool": "false" | "true" (cannot be native TOML boolean)
+# convert_images = "false"
 
 # 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 partitioned
@@ -102,6 +101,7 @@ pull_options = {enable_partial_images = "true", use_hard_links = "false", ostree
 # squashed down to the default uid in the container.  These images will have no
 # separation between the users in the container. Only supported for the overlay
 # and vfs drivers.
+# This is a "string bool": "false" | "true" (cannot be native TOML boolean)
 #ignore_chown_errors = "false"
 
 # Inodes is used to set a maximum inodes of the container image.
@@ -115,9 +115,11 @@ pull_options = {enable_partial_images = "true", use_hard_links = "false", ostree
 mountopt = "nodev"
 
 # Set to skip a PRIVATE bind mount on the storage home directory.
+# This is a "string bool": "false" | "true" (cannot be native TOML boolean)
 # skip_mount_home = "false"
 
 # Set to use composefs to mount data layers with overlay.
+# This is a "string bool": "false" | "true" (cannot be native TOML boolean)
 # use_composefs = "false"
 
 # Size is used to set a maximum size of the container image.