Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ddi-spec: define suggested suffixes, mime types, sector sizes for DDIs #88

Merged
merged 2 commits into from
Nov 17, 2023
Merged

ddi-spec: define suggested suffixes, mime types, sector sizes for DDIs #88

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8e3ff25
ddi-spec: minor modernizations
poettering Nov 16, 2023
68dd1d9
ddi-spec: document which suffix, mime type and sector sizes to use fo…
poettering Nov 16, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 21 additions & 7 deletions specs/discoverable_disk_image.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
poettering marked this conversation as resolved.
Show resolved Hide resolved
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
Expand Down
9 changes: 7 additions & 2 deletions specs/extension_image.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.<IMAGE>` file, where `<IMAGE>` must either match the
name of the sysext minus the suffix, or alternatively `extension-release.<IMAGE>` must be tagged with a
Expand All @@ -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).
Expand All @@ -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,
Expand Down