Gardenhouse
Navigation

Florist disk builder

The florist script contains a disk builder, it allows users to construct disk images or flash existing disks based on a static configuration.

Configuration format

Two global variables are set at the top of the config file:

  • ALIGN_MIB - How to align the partitions, if you do not know what this means keep it at 1
  • PADDING_MIB - How much extra space to add to the disk

After that follow the PART entries, each PART line follows the same format: PART <GPT LABEL> <IMAGE:SIZE> <PARTITION TYPE> <UUID> <FS LABEL> <FILESYSTEM>

  • GPT LABEL: The partlabel to assign to the partition, note that this is different from the filesystem label
  • IMAGE: The image to flash onto the partition, with two special keywords esp and empty, esp tells Florist to construct an esp and flash it onto the partition, empty tells Florist to keep the partition empty, the special keywords expect a size in the form of :<SIZE><UNIT>, if the partition should take up the remainder of the disk, size can be set to 0
  • Partition Type: UUID of the partition type as specified in the UAPI Discoverable Partitions Specification
  • UUID: The UUID of the partition, random tells Florist to set a random UUID
  • FS Label: The Filesystem label, this has to be supported by the Filesystem, it’s recommended to use the GPT Label instead
  • Filesystem: The Filesystem of the partition, if Image is set to esp or empty, it will be used to format the partition to specified format, otherwise it can be set to -

After the PART entries, users may specify an ESP_MAP, which allows Florist to automatically populate the ESP of the disk.

ESP_MAP entries follow the format: ESP_MAP <IMAGE> <PATH>

  • IMAGE: The file on the host to copy into the ESP
  • PATH: The path relative to the root of the ESP to copy into

Additionally, Florist has some special placeholders for the image source:

  • %ROOT_N% - The Nth latest built image
  • %VERITY_N% - The Nth latest verity image
  • %EFI_N% - The Nth latest UKI
  • %ROOTLOADER% - The Rootloader efi executable

An disk layout may look like this:

This Layout sets up an A/B root disk image with a 5G ext4 USERDATA and a 512M dynamically generated ESP

ALIGN_MIB=1
PADDING_MIB=0

PART EFI          esp:512M       C12A7328-F81F-11D2-BA4B-00A0C93EC93B random EFI       vfat
PART gh1          %ROOT_1%       4F68BCE3-E8CD-4DB1-96E7-FBCAF984B709 random -         erofs
PART vr1          %VERITY_1%     2C7357ED-EBD2-46D9-AEC1-23D437EC2BF5 random -         -
PART gh0          %ROOT_2%       4F68BCE3-E8CD-4DB1-96E7-FBCAF984B709 random -         erofs
PART vr0          %VERITY_2%     2C7357ED-EBD2-46D9-AEC1-23D437EC2BF5 random -         -
PART USERDATA     empty:5G       4D21B016-B534-45C2-A9FB-5C16E091FD2D random USERDATA  ext4

ESP_MAP %ROOTLOADER%   /EFI/BOOT/BOOTX64.EFI
ESP_MAP %EFI_1%        /EFI/Linux/
ESP_MAP %EFI_2%        /EFI/Linux/

Usage

Florist searches for layout configurations in two paths:

  • <overlay>/gardenhouse/layouts/<profile>/<layout>.cfg
  • <overlay>/gardenhouse/layouts/<layout>.cfg

This allows to specify both global and profile-specific disk layouts.

They can be used through the gardenhouse script:

To create a local disk image:

florist build-disk -o <overlay> -l <layout> -O <output> <profile>

To act on a real disk:

florist build-disk -o <overlay> -l <layout> -D <disk> -f <profile>

Rules under disk mode

When Florist operates in disk mode, it may act on a real disk image, however it strictly follows a set of rules:

  • Partitions are never deleted or shrunk

  • Existing partitions may be reflashed with new content

  • New partitions may be appended after existing ones

  • Existing partitions may be grown (resized larger)

To further guarantee the safety of the disk operation, it is recommended to first run florist with the -n flag, which will start it in dry-run mode and only print the changes to be done but not actually apply them.