diff --git a/specs/discoverable_disk_image.md b/specs/discoverable_disk_image.md index 0bd91867..f4ac6d37 100644 --- a/specs/discoverable_disk_image.md +++ b/specs/discoverable_disk_image.md @@ -7,17 +7,31 @@ SPDX-License-Identifier: CC-BY-4.0 --- # Discoverable Disk Image (DDI) -DDIs (Discoverable Disk Images) are self-describing file system images that follow the DPS -([Discoverable Partitions Specification](discoverable_partitions_specification.md)), wrapped in a GPT -partition table, that may contain root (or `/usr/`) filesystems, system extensions, configuration extensions, -portable services, containers and more, and are all protected by signed dm-verity all combined into one. -They are designed to be composable and stackable, and provide security by default. +DDIs (Discoverable Disk Images) are self-describing file system images that follow the DPS ([Discoverable +Partitions Specification](discoverable_partitions_specification.md)), wrapped in a GPT partition table, that +may contain root (or `/usr/`) filesystems for bootable OS images, system extensions, configuration +extensions, portable services, containers and more, and shall be protected by signed `dm-verity` all combined +into one. They are designed to be composable and stackable, and provide security by default. ## Image Format The images use the GPT partition table verbatim, so it will not be redefined here. Each partition contains -a standard Linux filesystem (e.g.: squashfs), so again this will not be redefined here. +a standard Linux filesystem (e.g.: `erofs`), so again this will not be redefined here. The [DPS](discoverable_partitions_specification.md) defines the GUIDs to use and the format of the -dm-verity signature partition's JSON content. +`dm-verity` signature partition's JSON content. + +It is recommended to use a sector size of 512 bytes or 4096 for DDIs. Software operating with DDIs should +automatically derive the sector size used for a DDI by looking for the `EFI PART` magic string at offsets 512 +or 4096, as per GPT specification. + +## Naming + +DDIs should use `.raw` as file suffix. A secondary suffix may be used to clarify the specific usage class of +a DDI. For now the two secondary suffixes `.sysext.raw` and `.confext.raw` are defined (for system extension +DDIs and configuration extension DDIs, see [Extension +Images](https://uapi-group.org/specifications/specs/extension_image) for details). + +The MIME type for DDIs is `application/vnd.efi.img`, [as per +IANA](https://www.iana.org/assignments/media-types/application/vnd.efi.img). ## Image Version If the DDI is versioned, the version format described in the diff --git a/specs/extension_image.md b/specs/extension_image.md index afcbfd7b..58ddd3af 100644 --- a/specs/extension_image.md +++ b/specs/extension_image.md @@ -38,6 +38,11 @@ to identify them. Extension Images should be additive, and not override content present in the base image or other DDIs, but this will not be enforced. +## File Suffix +Since extensions images are DDIs, they should carry the `.raw` suffix. In order to make discerning system +extensions and configuration extensions easy it is recommended to use the `.sysext.raw` suffix for system +extensions, and `.confext.raw` for configuration extensions. + ## Identification An Extension Image must contain a `extension-release.` file, where `` must either match the name of the sysext minus the suffix, or alternatively `extension-release.` must be tagged with a @@ -64,7 +69,7 @@ Examples: `"SYSEXT_LEVEL=2"`, `"CONFEXT_LEVEL=15.14"`. If not present, and if `VERSION_ID=` is present instead, then this will be checked instead. -#### `VERSION_ID=` `ID=` `ARCHITECTURE=` +#### `VERSION_ID=`, `ID=`, `ARCHITECTURE=` `VERSION_ID=` and `ID=` are used to match the Extension Image with the root DDI, and `ARCHITECTURE=` is used to match with the host's CPU architecture, as defined in the [`os-release` specification](https://www.freedesktop.org/software/systemd/man/os-release.html). @@ -79,7 +84,7 @@ can be used to also identify the sysext itself, by prefixing them with `SYSEXT_` There are also extension-specific fields that do not apply to 'os-release', `SYSEXT_SCOPE=`, `CONFEXT_SCOPE=` and `ARCHITECTURE=`. -#### `SYSEXT_SCOPE=` `CONFEXT_SCOPE=` +#### `SYSEXT_SCOPE=`, `CONFEXT_SCOPE=` Takes a space-separated list of one or more of the strings `"system"`, `"initrd"` and `"portable"`. This field is optional and indicates what environments the system extension is applicable to: i.e. to regular systems, to initrds, or to [portable service images](https://systemd.io/PORTABLE_SERVICES/). If unspecified,