Your submission was sent successfully! Close

You have successfully unsubscribed! Close

Thank you for signing up for our newsletter!
In these regular emails you will find the latest updates about Ubuntu and upcoming events where you can meet our team.Close

Create a model assertion

At the heart of custom Ubuntu Core image creation is the model assertion. An assertion is a signed recipe that describes the components that comprise a complete image. An assertion is provided as JSON in a text file which is signed by a GPG key associated with the publisher’s Ubuntu One account.

The model contains:

  • identification information, such as the developer-id and model name.
  • which essential snaps make up the device system.
  • other required or optional snaps that implement the device functionality.

See below for details on how to download and modify a model file to include your own selection of snaps.


1. Download a model file

The quickest way to create a new model assertion is to edit a model that already exists. Reference models for every supported Ubuntu Core device can be found in the snapcore/models GitHub repository.

For this project, we’re going to modify the 64-bit reference model for the Raspberry Pi: ubuntu-core-22-pi-arm64.json.

Download and save the file locally with the following wget command. We’ve called the file my-model.json:

wget -O my-model.json https://raw.githubusercontent.com/snapcore/models/master/ubuntu-core-22-pi-arm64.json

2. Edit the model file

We now need to edit my-model.json using a text editor:

nano my-model.json

The following fields in my-model.json need to be changed:

2.1 "authority-id" and "brand-id"

"authority-id": "canonical",
"brand-id": "canonical",

These properties define the authority responsible for the image. Change both instances of the string “canonical” to your developer id, retrieved with the snapcraft whoami command. (“xSfWKGdLoQBoQx88”, in our example output). This links the image to your Ubuntu One account and ensures that only you can push image updates to devices using your model.

2.2 "timestamp"

    "timestamp": "2020-03-31T12:00:00.0Z", 

This needs to be provided at the end of the process; we’ll come back to this.

2.3 "snaps"

    "snaps": [
        {
            "name": "pi",
            "type": "gadget",
            "default-channel": "22/stable",
            "id": "YbGa9O3dAXl88YLI6Y1bGG74pwBxZyKg"
        },
       ...

This section lists the snaps to be included in the image. pi (shown above), pi-kernel, core22 and snapd are the four snaps required for a functioning Ubuntu Core device.

Additional snaps are included in the same way, with each snap requiring the following fields:

  • name: simply the snap name.
  • type: the type of snap. This is app for standard application snaps.
  • default-channel: the channel to install the snap from.
  • id: a unique snap identifier associated with every published snap. This is snap-id in the output from snap info <snap-name>.

For this tutorial, we’re going to add the AdGuard Home snap, an open source network-wide blocker for advertising and tracking. It’s an ideal candidate for an Ubuntu Core image like this because it benefits from frequent autonomous updates and a confined environment.

To add the AdGuard Home snap to our image, we need to add the following JSON stanza to the snaps section in our my-model.json (note the comma you need to append to the preceding snap entry to show continuation):

        },
	    {
            "name": "adguard-home",
            "type": "app",
            "default-channel": "latest/stable",
            "id": "UXZIkJfJT2SPCGejjnSjOBqJ71yHk8bw"
        }

Snaps do not have dependencies, but they do require the presence of the base snap they were built on. AdGuard Home is built using a base of core22 (see the output from snap info adguard-home --verbose | grep "base:"), which is the default base for our image, so no further edits are necessary.

3. Complete model example

After finishing all your edits, the completed my-model.json text file should now contain the following:

{
    "type": "model",
    "series": "16",
    "model": "ubuntu-core-22-pi-arm64",
    "architecture": "arm64",
    "authority-id": "bJzr2XzZg6Qv6Z53HIeziXyxtn1XItIq",
    "brand-id": "bJzr2XzZg6Qv6Z53HIeziXyxtn1XItIq",
    "timestamp": "2022-04-04T10:40:41+00:00",
    "base": "core22",
    "grade": "signed",
    "snaps": [
        {
            "name": "pi",
            "type": "gadget",
            "default-channel": "22/stable",
            "id": "YbGa9O3dAXl88YLI6Y1bGG74pwBxZyKg"
        },
        {
            "name": "pi-kernel",
            "type": "kernel",
            "default-channel": "22/stable",
            "id": "jeIuP6tfFrvAdic8DMWqHmoaoukAPNbJ"
        },
        {
            "name": "core22",
            "type": "base",
            "default-channel": "latest/stable",
            "id": "amcUKQILKXHHTlmSa7NMdnXSx02dNeeT"
        },
        {
            "name": "snapd",
            "type": "snapd",
            "default-channel": "latest/stable",
            "id": "PMrrV4ml8uWuEUDBT8dSGnKUYbevVhc4"
        },
        {
            "name": "adguard-home",
            "type": "app",
            "default-channel": "latest/stable",
            "id": "UXZIkJfJT2SPCGejjnSjOBqJ71yHk8bw"
        }
    ]
}

After the file has been created, the next step is to sign it. See Sign a model for further details.

This page was last modified 6 months ago. Help improve this document in the forum.