Image Customizer: Fix verity docs. (#10852)

Author: cwize1

toolkit/tools/imagecustomizer/docs/configuration.md

@@ -50,8 +50,8 @@ The Azure Linux Image Customizer is configured using a YAML (or JSON) file.
 13. If ([overlays](#overlay-type)) are specified, then add the overlay driver
     and update the fstab file with the overlay mount information.
 
-14. If ([verity](#verity-type)) is specified, then add the dm-verity dracut driver
-    and update the grub config.
+14. If a ([verity](#verity-type)) device is specified, then add the dm-verity dracut
+    driver and update the grub config.
 
 15. Regenerate the initramfs file (if needed).
 
@@ -66,8 +66,8 @@ The Azure Linux Image Customizer is configured using a YAML (or JSON) file.
 20. If [--shrink-filesystems](./cli.md#shrink-filesystems) is specified, then shrink
     the file systems.
 
-21. If ([verity](#verity-type)) is specified, then create the hash tree and update the
-    grub config.
+21. If a ([verity](#verity-type)) device is specified, then create the hash tree and
+    update the grub config.
 
 22. If the output format is set to `iso`, copy additional iso media files.
     ([iso](#iso-type))
@@ -125,6 +125,13 @@ os:
             - [end](#end-uint64)
             - [size](#size-uint64)
             - [type](#partition-type-string)
+    - [verity](#verity-verity)
+      - [verity type](#verity-type)
+        - [id](#verity-id)
+        - [name](#verity-name)
+        - [dataDeviceId](#datadeviceid-string)
+        - [hashDeviceId](#hashdeviceid-string)
+        - [corruptionOption](#corruptionoption-string)
     - [filesystems](#filesystems-filesystem)
       - [filesystem type](#filesystem-type)
         - [deviceId](#deviceid-string)
@@ -198,8 +205,8 @@ os:
         - [name](#module-name)
         - [loadMode](#loadmode-string)
         - [options](#options-mapstring-string)
-    - [overlay type](#overlay-type)
-    - [verity type](#verity-type)
+    - [overlays](#overlays-overlay)
+      - [overlay type](#overlay-type)
   - [scripts type](#scripts-type)
     - [postCustomization](#postcustomization-script)
       - [script type](#script-type)
@@ -483,45 +490,58 @@ Example: `noatime,nodiratime`
 
 ## verity type
 
-Specifies the configuration for dm-verity root integrity verification.
+Specifies the configuration for dm-verity integrity verification.
 
-- `dataPartition`: A partition configured with dm-verity, which verifies integrity
-  at each system boot.
+Note: Currently only root partition (`/`) is supported. Support for other partitions
+(e.g. `/usr`) may be added in the future.
 
-  - `idType`: Specifies the type of id for the partition. The options are
-    `id` (partition [id](#id-string)), `part-label` (partition label),
-    `uuid` (filesystem UUID), and `part-uuid` (partition UUID).
+There are multiple ways to configure a verity enabled image. For
+recommendations, see [Verity Image Recommendations](./verity.md).
 
-  - `id`: The unique identifier value of the partition, corresponding to the
-    specified IdType.
+<div id="verity-id"></div>
 
-- `hashPartition`: A partition used exclusively for storing a calculated hash
-  tree.
+### id [string]
 
-- `corruptionOption`: Optional. Specifies the behavior in case of detected
-  corruption. This is configurable with the following options:
-  - `io-error`: Default setting. Fails the I/O operation with an I/O error.
-  - `ignore`: ignores the corruption and continues operation.
-  - `panic`: causes the system to panic (print errors) and then try restarting
-    if corruption is detected.
-  - `restart`: attempts to restart the system upon detecting corruption.
+Required.
 
-Example:
+The ID of the verity object.
+This is used to correlate verity objects with [filesystem](#filesystem-type)
+objects.
 
-```yaml
-os:
-  verity:
-    dataPartition:
-      idType: part-uuid
-      id: 00000000-0000-0000-0000-000000000000
-    hashPartition:
-      idType: part-label
-      Id: hash_partition
-    corruptionOption: panic
-```
+<div id="verity-name"></div>
 
-There are multiple ways to configure a verity enabled image. For
-recommendations, see [Verity Image Recommendations](./verity.md).
+### name [string]
+
+Required.
+
+The name of the device mapper block device.
+
+The value must be:
+
+- `root` for root partition (i.e. `/`)
+
+### dataDeviceId [string]
+
+The ID of the [partition](#partition-type) to use as the verity data partition.
+
+### hashDeviceId [string]
+
+The ID of the [partition](#partition-type) to use as the verity hash partition.
+
+### corruptionOption [string]
+
+Optional.
+
+Specifies how a mismatch between the hash and the data partition is handled.
+
+Supported values:
+
+- `io-error`: Fails the I/O operation with an I/O error.
+- `ignore`: Ignores the corruption and continues operation.
+- `panic`: Causes the system to panic (print errors) and then try restarting.
+- `restart`: Attempts to restart the system.
+
+Default value: `io-error`.
 
 ## additionalFile type
 
@@ -654,8 +674,7 @@ Specifies the mount options for a partition.
 
 Required.
 
-The ID of the partition.
-This is used correlate [partition](#partition-type) objects with filesystem objects.
+The ID of the [partition](#partition-type) or [verity](#verity-type) object.
 
 ### type [string]
 
@@ -885,6 +904,8 @@ os:
 
 ## partition type
 
+<div id="partition-id"></div>
+
 ### id [string]
 
 Required.
@@ -1350,6 +1371,10 @@ os:
     - name: vfio
 ```
 
+### overlays [[overlay](#overlay-type)[]]
+
+Used to add filesystem overlays.
+
 ### selinux [[selinux](#selinux-type)]
 
 Options for configuring SELinux.
@@ -1591,6 +1616,10 @@ Supported options:
 
 Contains the options for provisioning disks and their partitions.
 
+### verity [[verity](#verity-type)[]]
+
+Configure verity block devices.
+
 ### filesystems [[filesystem](#filesystem-type)[]]
 
 Specifies the mount options of the partitions.

toolkit/tools/imagecustomizer/docs/verity.md

@@ -145,12 +145,18 @@ storage:
       end: 3200M
     - id: var
       start: 3200M
+  verity:
+  - id: verityroot
+    name: root
+    dataDeviceId: root
+    hashDeviceId: roothash
+    corruptionOption: panic
   filesystems:
   - deviceId: boot
     type: ext4
     mountPoint:
       path: /boot
-  - deviceId: root
+  - deviceId: verityroot
     type: ext4
     mountPoint:
       path: /
@@ -159,13 +165,6 @@ storage:
     mountPoint:
       path: /var
 os:
-  verity:
-    dataPartition:
-      idType: id
-      id: root
-    hashPartition:
-      idType: id
-      id: roothash
   additionalFiles:
     # Change the directory that the sshd-keygen service writes the SSH host keys to.
   - content: |