Contents

This document serves the purpose of gathering all the useful information regarding the construction of and development of the ubuntu-core flavor.

Every ubuntu-core image is composed of a defined set of snaps. The following section gives a quick overview of what each snap is about and includes a handy list of links for the given project.

New images are composed using the ubuntu-image tool and so called model assertions. In our case, model assertions tell ubuntu-image what to compose the created image of. It is the model that defines the base snap to use, the gadget and kernel. There are different model assertions for 16 and 18, for each supported platform.

This is the base filesystem with all the bare-essential libraries and tools for any system to work. Like the core snap, this is required to be present on any 18 core-enabled system. Basically it has to offer any crucial functionality that is needed for a minimal system to function and cannot be easily installed through separate snaps.

core24 for core series 24

LP project: https://code.launchpad.net/snap-core24

Code repository: https://github.com/snapcore/core-base/tree/main

Snap recipe: https://code.launchpad.net/~ubuntu-core-service/+snap/core24

core22 for core series 22

LP project: https://code.launchpad.net/snap-core22

Code repository: https://github.com/snapcore/core-base/tree/core22

Snap recipe: https://code.launchpad.net/~ubuntu-core-service/+snap/core22

core20 for core series 20

LP project: https://code.launchpad.net/snap-core20

Code repository: https://github.com/snapcore/core20

Snap recipe: https://code.launchpad.net/~ubuntu-core-service/+snap/core20

core18 for core series 18

LP project: https://code.launchpad.net/snap-core18

Code repository: https://github.com/snapcore/core18

Snap recipe: https://code.launchpad.net/~ubuntu-core-service/+snap/core18

core for core+snapd series 16

LP project: https://launchpad.net/core-snap

Code repository: https://github.com/snapcore/core

Snap recipe: https://launchpad.net/~snappy-dev/+snap/core

Each supported device has its own gadget snap. Gadget snaps are what defines the device, carrying binaries for the bootloader, declaring the partition layout etc. It is important to keep in mind that the gadget code repositories are also used by classic Ubuntu preinstalled images, although currently separate branches are used.

pi - universal gadget snap for all supported Raspberry Pi devices (pi2, pi3, pi4, cm3, cm4)

LP project: https://code.launchpad.net/snap-pi

Snap UC24 recipe (arm64): https://launchpad.net/~ubuntu-core-service/snap-pi/+snap/pi-24

Snap UC22 recipe (armhf): https://code.launchpad.net/~ubuntu-core-service/+snap/pi-armhf-22

Snap UC22 recipe (arm64): https://code.launchpad.net/~ubuntu-core-service/+snap/pi-arm64-22

Snap UC20 recipe (armhf): https://code.launchpad.net/~ubuntu-core-service/+snap/pi-armhf-20

Snap UC20 recipe (arm64): https://code.launchpad.net/~ubuntu-core-service/+snap/pi-arm64-20

Snap UC18 recipe (armhf): https://code.launchpad.net/~ubuntu-core-service/+snap/pi

Snap UC18 recipe (arm64): https://code.launchpad.net/~ubuntu-core-service/+snap/pi-arm64

Core 22 branch (armhf): https://github.com/snapcore/pi-gadget -b 22-armhf

Core 22 branch (arm64): https://github.com/snapcore/pi-gadget -b 22-arm64

Core 20 branch (armhf): https://github.com/snapcore/pi-gadget -b 20-armhf

Core 20 branch (arm64): https://github.com/snapcore/pi-gadget -b 20-arm64

Core 18 branch (armhf): https://github.com/snapcore/pi-gadget -b 18-armhf

Core 18 branch (arm64): https://github.com/snapcore/pi-gadget -b 18-arm64

dragonboard - the Dragonboard device

LP project: https://code.launchpad.net/snap-dragonboard

Snap recipe 18: https://code.launchpad.net/~canonical-foundations/+snap/dragonboard-18

Snap recipe 16: https://code.launchpad.net/~canonical-foundations/+snap/dragonboard

Core 18 branch: https://github.com/snapcore/dragonboard-gadget -b 18

Core 16 branch: https://github.com/snapcore/dragonboard-gadget -b 16

pc - gadget snap for UEFI devices

LP project: https://code.launchpad.net/snap-pc

Snap recipe 24 (amd64, arm64): https://launchpad.net/~ubuntu-core-service/+snap/pc-24

Snap recipe 22 (amd64, arm64): https://code.launchpad.net/~ubuntu-core-service/+snap/pc-22

Snap recipe 20 (amd64): https://code.launchpad.net/~ubuntu-core-service/+snap/pc-amd64-20

Snap recipe 18 (amd64): https://code.launchpad.net/~ubuntu-core-service/+snap/pc-amd64-18

Snap recipe 18 (i386): https://code.launchpad.net/~ubuntu-core-service/+snap/pc-i386-18

Snap recipe 16 (amd64): https://code.launchpad.net/~ubuntu-core-service/+snap/pc-amd64

Snap recipe 16 (i386): https://code.launchpad.net/~ubuntu-core-service/+snap/pc-i386

Core 22 branch (amd64): https://github.com/snapcore/pc-amd64-gadget -b 22

Core 20 branch (amd64): https://github.com/snapcore/pc-amd64-gadget -b 20

Core 18 branch (amd64): https://github.com/snapcore/pc-amd64-gadget -b 18

Core 18 branch (i386): https://github.com/snapcore/pc-i386-gadget -b 18

Core 16 branch (amd64): https://github.com/snapcore/pc-amd64-gadget -b 16

Core 16 branch (i386): https://github.com/snapcore/pc-i386-gadget -b 16

There following gadget snaps are only used for the 16 series. Even though some of those repositories have 18 branches and/or include some snaps in the 18 track, they do not participate in any of the core18 images and should only be used for core16 (core):

pi2

LP project: https://code.launchpad.net/snap-pi2

Core 16 branch: https://github.com/snapcore/pi2-gadget -b master

pi3

LP project: https://code.launchpad.net/snap-pi3

Core 16 branch: https://github.com/snapcore/pi3-gadget -b 16

cm3

LP project: https://code.launchpad.net/snap-cm3

Core 16 branch: https://github.com/snapcore/cm3-gadget -b master

The shim and grub binaries are signed with a private key specific for Ubuntu Core systems. By using a different key to the one for classic systems we ensure that it will be possible to have devices that can start UC but not classic. The procedure to obtain newly signed binaries is:

Copy grub2, grub2-unsigned, and shim source packages from the archive to https://launchpad.net/~ucdev/+archive/ubuntu/uc-build-ppa, including the binary packages generated by them (these should not be rebuilt). Although this is not strictly needed, with this we make sure that the artifacts that need to be signed are stored in the PPA and not pulled from the archive, which might be problematic if we need to re-sign this specific version and the archive has rotated versions (it only stores the latest three) so it gets more difficult to access these assets.

Upload the corresponding grub2-signed and shim-signed source packages, but with a changelog entry that uses epoch 2, that is, version should be 2:. Using a different epoch ensures that if the shim/grub version in the archive bumps we will still pull the package signed with the UC key. (Ideally make it fail the build so only binaries built from the signing PPA exist - this can be done by adding final checks on whether the signature is chained to Canonical certs with "sbverify --cert CanonicalMasterCA.crt ", see https://launchpadlibrarian.net/491880978/shim-signed_1.41_1.43+uc20.4.diff.gz).

Create a bug in grub2-signed and shim-signed projects, see for instance https://bugs.launchpad.net/ubuntu/+source/grub2-signed/+bug/1981997. Subscribe the ~canonical-signing and ~canonical-foundations teams to it.

Once the packages are signed, they should be copied (by somebody with permissions) to https://launchpad.net/~ucdev/+archive/ubuntu/uc-staging-ppa. This PPA is included when building the pc gadget so shim/grub are pulled from there.

The copy-package tool (git clone lp:ubuntu-archive-tools) is used to copy package from the archive to PPAs. For example:

$ ./copy-package -b -s focal-updates --to ppa:ucdev/ubuntu/uc-build-ppa --to-suite focal -e 2.04-1ubuntu26.15 grub2

See https://wiki.ubuntu.com/ArchiveAdministration for more details.

Historically the PPAs used for this process were https://launchpad.net/~canonical-foundations/+archive/ubuntu/uc20-build-ppa and https://launchpad.net/~canonical-foundations/+archive/ubuntu/uc20-staging-ppa.

The snap offering snapd itself. This was once part of the core snap but it has been ripped out as a separate snap since recently.

Code branch: https://github.com/snapcore/snapd

Initramfs is built in https://launchpad.net/~snappy-dev/+archive/ubuntu/image

Initramfs needs to be copied to https://launchpad.net/~canonical-kernel-team/+archive/ubuntu/builder-extra so it is considered in next kernel build.

pi-kernel - the generic Raspberry Pi kernel for all supported Pi devices (pi2, pi3, cm3)

https://snapcraft.io/pi-kernel

dragonboard-kernel

https://snapcraft.io/dragonboard-kernel

pc-kernel

https://snapcraft.io/pc-kernel

For core16 only (not used for core18), legacy snaps:

pi2-kernel - the generic Raspberry Pi kernel, now renamed to pi-kernel.

All available and officially supported model assertions are available on https://github.com/snapcore/models .

One can get the model assertions for the selected supported platform by using the following commands:

Besides the default, signed ones below, we also provide -dangerous and - model assertions.

Generic Raspberry Pi (64-bit): snap known --remote model series=16 model="ubuntu-core-24-pi-arm64" brand-id=canonical

amd64: snap known --remote model series=16 model="ubuntu-core-24-amd64" brand-id=canonical

Besides the default, signed ones below, we also provide -dangerous and - model assertions.

Generic Raspberry Pi (32-bit): snap known --remote model series=16 model="ubuntu-core-22-pi-armhf" brand-id=canonical

Generic Raspberry Pi (64-bit): snap known --remote model series=16 model="ubuntu-core-22-pi-arm64" brand-id=canonical

amd64: snap known --remote model series=16 model="ubuntu-core-22-amd64" brand-id=canonical

Besides the default, signed ones below, we also provide -dangerous and - model assertions.

Generic Raspberry Pi (32-bit): snap known --remote model series=16 model="ubuntu-core-20-pi-armhf" brand-id=canonical

Generic Raspberry Pi (64-bit): snap known --remote model series=16 model="ubuntu-core-20-pi-arm64" brand-id=canonical

amd64: snap known --remote model series=16 model="ubuntu-core-20-amd64" brand-id=canonical

Generic Raspberry Pi: snap known --remote model series=16 model="ubuntu-core-18-pi" brand-id=canonical

Generic Raspberry Pi (64-bit): snap known --remote model series=16 model="ubuntu-core-18-pi-arm64" brand-id=canonical

Dragonboard: snap known --remote model series=16 model="ubuntu-core-18-dragonboard" brand-id=canonical

amd64: snap known --remote model series=16 model="ubuntu-core-18-amd64" brand-id=canonical

i386: snap known --remote model series=16 model="ubuntu-core-18-i386" brand-id=canonical

Obsolete Raspberry Pi 2: snap known --remote model series=16 model="ubuntu-core-18-pi2" brand-id=canonical

Obsolete Raspberry Pi 3: snap known --remote model series=16 model="ubuntu-core-18-pi3" brand-id=canonical

Obsolete Raspberry Pi 3 (64-bit): snap known --remote model series=16 model="ubuntu-core-18-pi3-arm64" brand-id=canonical

Obsolete Raspberry Pi CM3: snap known --remote model series=16 model="ubuntu-core-18-cm3" brand-id=canonical

Raspberry Pi 2: snap known --remote model series=16 model="pi2" brand-id=canonical

Raspberry Pi 3: snap known --remote model series=16 model="pi3" brand-id=canonical

Raspberry Pi CM3: snap known --remote model series=16 model="cm3" brand-id=canonical

Dragonboard: snap known --remote model series=16 model="dragonboard" brand-id=canonical

amd64: snap known --remote model series=16 model="pc-amd64" brand-id=canonical

i386: snap known --remote model series=16 model="pc-i386" brand-id=canonical

See UbuntuCore/CoreSnapAutomation .

For some cases, the 18 snaps use a special 18 track instead of the default one. This means that for those snaps, instead of channels like stable, candidate, beta, edge there's 18/stable, 18/candidate, 18/beta, 18/edge - especially for gadget snaps. Before attempting promotion from one channel to another, always make sure that you are specifying the right track and channel. Otherwise one might promote a core18-targeted snap to the stable channel used by core16 devices. Look at the list of revisions and available tracks/channels before promotion.

The edge, beta and candidate snap promotions are handled by our automation (see above section). Manual promotion is only required when moving a snap from candidate to stable, in which case the following instructions need to be followed. NOTE! For core18/core20/core20+ snaps, always coordinate first with the snapstore team before promoting to stable. Base snap releases always cause huge spikes in bandwidth consumption so we need to make sure there are no other releases/operations in progress that could cause infrastructure issues.

Another important thing to keep in mind is that all base snap releases are released using progressive releases (phased upgrades). So, in fact, only after approximately 36 hours (15% increment roughly every 6 hours) a new version is available for all users in the respective stable channel.

Releasing a new snap to stable:

Run export SNAPCRAFT_EXPERIMENTAL_PROGRESSIVE_RELEASES=y to enable progressive releases (note: might be no longer needed after becoming non-experimental).

Run this command on the same terminal: snapcraft release   stable --progressive 10

depends on whether the snap you are promoting has a specific track you want to use, like 18/.

Example #1 (core18 snap): snapcraft release core18 1234 18/stable,18/candidate --progressive 10

As with every Ubuntu flavor, Ubuntu Core has standard daily builds enabled for UC16, UC18 and UC20 on cdimage. Daily images are being produced for different stability levels and published to their respective directories. Those daily images are only meant to be used for testing and development purposes and are never actually advertised or 'promoted'. Note: the same infrastructure is used when officially releasing a new image, using the 'stable' channel images.

New image builds can be requested by contacting members of the ubuntu-cdimage Launchpad team. It is not possible to do it via the ISO tracker (as it is the case with most other Ubuntu flavors).

Ubuntu Core 16 stable (officially released images): http://cdimage.ubuntu.com/ubuntu-core/16/stable/current/

For edge: http://cdimage.ubuntu.com/ubuntu-core/16/edge/

For beta: http://cdimage.ubuntu.com/ubuntu-core/16/beta/

Ubuntu Core 18 stable (officially released images): http://cdimage.ubuntu.com/ubuntu-core/18/stable/current/

For edge: http://cdimage.ubuntu.com/ubuntu-core/18/edge/

For beta: http://cdimage.ubuntu.com/ubuntu-core/18/beta/

Ubuntu Core 20 stable (officially released images): http://cdimage.ubuntu.com/ubuntu-core/20/stable/current/

For edge: http://cdimage.ubuntu.com/ubuntu-core/20/edge/

For beta: http://cdimage.ubuntu.com/ubuntu-core/20/beta/

Ubuntu Core 20 images are more strictly confined, so for development purposes, to enable developers to install and modify the daily images, there are special dangerous images built daily. Those have separate publish directories. Please see the Ubuntu Core 20 release notes for more info (section grade).

For edge (dangerous): http://cdimage.ubuntu.com/ubuntu-core/20/dangerous-edge/

For beta (dangerous): http://cdimage.ubuntu.com/ubuntu-core/20/dangerous-beta/

See UbuntuCore/ReleaseProcess .

See UbuntuCore/AddingImages .

Ubuntu Appliances are basically Ubuntu Core images with some special snaps preinstalled and preconfigured. Such images can be loaded on the given platform (Pi's mostly right now) to turn it into a home/office appliance. Currently those are built on ubuntu-cdimage and based on UC18.

See UbuntuCore/AddingAppliances .

https://ubuntu.com/core/docs/uc20/inside - Inside Ubuntu Core 20 official documentation outlining how UC20 images work and how the various components interact with each other.

https://ubuntu.com/core/docs/uc20/release-notes - Ubuntu Core 20 release notes, overviewing some of the UC20 new concepts.