Skip to content

Gadget snap

Jump to bottom Edit New page
Gustavo Niemeyer edited this page Oct 7, 2016 · 21 revisions

Introduction

The gadget snap is responsible for defining and manipulating the system properties which are specific to one or more devices that will usually look similar to one another from an implementation perspective. This snap must necessarily be produced and signed by the device brand, which is defined via the model assertion. The brand knows where and how that device will be used, and designs the gadget snap accordingly.

For example, the brand may know that the device is actually a special VM to be used on a particular cloud, or it may know that it is going to be manufactured in a particular factory. The gadget snap may encode the mechanisms for device initialization - key generation and identity certification - as well as particular processes for the lifecycle of the device, such as factory resets. It is perfectly possible for different models to share a gadget snap.

Canonical publishes some reference gadget snaps as well as gadget snaps for main Canonical models such as official Ubuntu Core VMs on various certified public clouds, as well as general purpose computing images for popular physical devices like the 64-bit x86 PC and Raspberry Pi 2 and 3.

Defining a gadget snap

A list of one or more layouts that must be present in this volume, their properties and content. In general all of the content of the image is either pre-computed as a part of the gadget snap or must be assembled as a file system from the content provided by the gadget snap.

The gadget snap has a meta/snap.yaml which may have the same metadata as application snaps, but must be defined with type: gadget explicitly. It must also hold an additional meta/gadget.yaml file with the following content:

# Default configuration options for the defined snaps, applied on installation.
defaults:
    <snap id>:
        <key>: <value>

# If device-tree is specified, `dtbs/<filename>` must exist in kernel or
# gadget snap (depends on origin) and `snap_device_tree_origin` and
# and `snap_device_tree` are made available for u-boot and grub .
device-tree: <filename>
device-tree-origin: kernel

# Volumes defining the structure and content for the images to be written
# into one ore more block devices of the gadget device. Each volume in
# in the structure represents a different image for a "disk" in the device.
volumes:

    # Name of volume and image file generated. Must be formed by [a-z-]+.
    <volume name>:

        # 2-digit hex code for MBR disk ID or GUID for GPT disk id.
        id: <id>
                  
        # Bootloader in the volume. Required in at least one volume.
        bootloader: grub | u-boot

        # Which partitioning schema to use. Defaults to gpt.
        schema: mbr | gpt | mbr,gpt

        # Layout of what goes into the volume, their properties and content.
        structure:
          - # Structure is a list of items.

            # Optional structure item name. There's an implementation-specific
            # constraint on the maximum length. The maximum length of a
            # partition name for GPT is 36 characters in the UTF-16 character set.
            name: <name>

            # GPT unique partition id, unsupported on MBR volumes.
            id: <id>

            # Required type of structure. May be specified as a two-hex-digit
            # MBR partition type, a GPT partition type GUID, or both for hybrid
            # schemas. It may also be "mbr" for the Master Boot Record of a disk.
            type: <mbr type> | <gpt guid> | <mbr type>,<gpt guide> | mbr

            # Required size of the structure. Maximum of 446 for the "mbr" type.
            size: <bytes> | <bytes/2^20>M | <bytes/2^30>G

            # The offset from the beginning of the image. Defaults to right after
            # prior structure item.
            offset: <bytes> | <bytes/2^20>M | <bytes/2^30>G

            # Optional location in which the offset of this structure is written
            # into. It may be specified relative to another structure item, and
            # is written in LBA48 pointer format (32-bit little-endian with index
            # of disk sector).
            offset-write: [<name>+]<bytes> |
                          [<name>+]<bytes/2^20>M |
                          [<name>+]<bytes/2^30>G

            filesystem: none | vfat | ext4  # Defaults to none.
            filesystem-label: <label>       # Defaults to structure item name.

            # Content to be copied from gadget snap into the structure. This
            # field takes a list of one of the following formats:
            content:

                # Copy source (relative to gadget base directory) into filesystem
                # at target (relative to root). Directories must end in a slash.
                - source: <filename> | <dir>/
                  target: <filename> | <dir>/

                # Dump image (relative to gadget base directory) of the raw data
                # as-is into the structure at offset. If offset is omitted it
                # defaults to right after prior content item. If size is omitted,
                # defaults to size of contained data.
                - image: <filename>
                  offset: <bytes> | <bytes/2^20>M | <bytes/2^30>G
                  offset-write: (see respective item above)
                  size: <bytes> | <bytes/2^20>M | <bytes/2^30>G

Bootloader configuration

The bootloader configuration is expected to be at the toplevel of the gadget snap. The filename must be either grub.conf or u-boot.conf, depending on which bootloader was specified in the respective gadget.yaml field.

A cloud-init configuration may also be provided at the top level of the gadget snap as cloud.conf.

Sample configuration files may be found in the reference gadget snaps.

The prepare-device hook

WRITE ME

violethaze74 This is the snapd wiki, feel free!

Forum

Clone this wiki locally