Components

managing snaps for administrators for app developers for Ubuntu Core developers

A component is an optional part of a snap that is installed and refreshed and removed with or after its snap. snap install snap+component adds one and snap components lists what is installed and what is available. Each operation is a chain of component tasks inside the snap's change. Components of type kernel-modules add drivers to a kernel snap and can take effect without a reboot.

On the map: administration district

▶ Watch this deck — 7 scenes, ~5 min

01 A part you add when you need it

COMPONENTS gateway 17 of 50acme-agent 2.1fifty gateways run this; one is misbehaving $ sudo snap install acme-agent+diagnostics diagnosticscomponent diagnostics 1.0 for acme-agent 2.1 installedthe snap keeps its revision and its data acme-agent+diagnosticssnapcomponentmore than one: acme-agent+diagnostics+simulator snap not installed yet: the same command installs the snap and its components together
A gateway runs acme-agent 2.1. sudo snap install acme-agent+diagnostics adds the diagnostics component to it and prints component diagnostics 1.0 for acme-agent 2.1 installed. The name is the snap, a plus sign and the component; more plus signs add more components, and the same command installs the snap too when it is missing

snap install <snap>+<component> installs a component, and the snap too if it is missing. Several components are joined with +. The result line is component diagnostics 1.0 for acme-agent 2.1 installed; the version 1.0 and the component simulator are invented.

Fifty gateways run acme-agent, and one of them is misbehaving. The diagnostics kit would help. It isn't on the device, and on the other forty nine it shouldn't be. That's why the publisher ships it as a component: an optional part of the snap that you add only where you need it. You type snap install, the snap's name, a plus sign and the component's name. Snapd answers with one line for the component, and the agent keeps its revision and its data. Need more than one? Add more plus signs. And on a gateway without the snap, the same command installs both.

02 What is on offer

LOOKING $ snap components acme-agentComponent Status Type acme-agent+diagnostics installed standard acme-agent+simulator available standardthe first column is what you paste after snap installtypes: standard, and kernel-modules on kernels $ snap component acme-agent+diagnosticscomponent: acme-agent+diagnosticstype: standardsummary: …description: |… installed: 1.0 (7) 4.10MBversion, revision, size; only for installed components snap info acme-agent lists them too, under components:all of these look only at snaps that are installed
snap components acme-agent prints a table with the columns Component, Status and Type: acme-agent+diagnostics installed standard, and acme-agent+simulator available standard. snap component acme-agent+diagnostics prints the component's type, summary and description, and for an installed component the line installed: 1.0 (7) 4.10MB. snap info also lists components

snap components [<snap>...] prints Component, Status (installed or available) and Type for installed snaps. snap component <snap>+<component> prints the type, summary and description, and installed: <version> (<revision>) <size> when installed. simulator is invented.

How would you even know acme-agent has a diagnostics kit? Ask snapd what's on offer. Snap components gives you a row per component, for every installed snap that has any: its full name, whether it's installed or only available, and its type. The name is printed exactly the way snap install wants it, so you can paste it. You'll mostly see standard, and on kernels, kernel-modules. For the detail, there's snap component, singular, with the same plus name: type, summary, description, and for an installed one, its version, revision and size. Snap info shows a short form too. All of these only look at snaps you already have.

03 The install, task by task for administrators for app developers for Ubuntu Core developers

ONE CHANGE download-componentfrom the storea local file: prepare-component validate-componentfetch and check assertions mount-componentmount the filesetup-profilesthe snap's profiles again link-componentnow availableacme-agent rev 42recorded for this snap revision run-hookits install hook, if any $ snap change 87Done … Mount component "acme-agent+diagnostics" (7)Done … Make component "acme-agent+diagnostics" (7) available to the systema failure undoes the earlier tasks; a download has no undo
The tasks that install acme-agent+diagnostics, in order: download-component from the store, or prepare-component for a local file; validate-component, which fetches and checks assertions; mount-component; setup-profiles for the snap; link-component, which records the component for acme-agent revision 42; and run-hook for the component's install hook. snap change 87 lists them as Done

Component install tasks, in order: download-component (or prepare-component for a local file), validate-component, mount-component, setup-profiles, link-component, then the component's install hook. download-component and prepare-component have no undo. The change id 87 is invented.

One line of output: component installed. What did snapd actually do to get there? Like every operation, it made a change, a chain of tasks. First the file: downloaded from the store, or prepared, if you gave it one. Then validated, which means fetching the assertions that say this component revision belongs with this snap-revision. Then mounted. Then the snap's security profiles are set up again, to take the component in. Then linked: now it's available, and recorded for this revision of the snap. Last, the component's install hook, if it has one. If a step fails, the earlier ones are undone, and snap change shows every step.

04 A refresh takes them along for administrators for app developers for Ubuntu Core developers

REFRESH revision 42acme-agent 42diagnostics 7simulator 3 $ sudo snap refresh acme-agentrevision 43acme-agent 43 simulatornot defined by revision 43: dropped diagnostics 8the store is asked for therevision that pairs with 43 download-component validate-component mount-component … link-componentinside the snap's refresh change, with the component's pre-refresh and post-refresh hooks around them revision 42 keeps its record: diagnostics 7a revert returns the snap and its components together
Revision 42 of acme-agent has diagnostics revision 7 and simulator revision 3. sudo snap refresh acme-agent moves it to revision 43, which does not define simulator, so simulator is dropped; diagnostics revision 8, the one that pairs with snap revision 43, is installed. The component tasks run inside the snap's refresh change. Revision 42 keeps its record, so a revert brings back 42 with diagnostics 7

A snap refresh also refreshes the components installed for the current revision and drops those the target revision does not define. Components are recorded per snap revision; discard-component removes an old component revision only when no other kept snap revision uses it. Revisions 43, 8 and 3 are invented.

Next week acme-agent refreshes to revision forty three. You added diagnostics by hand. Does it survive? A component revision is made for particular snap revisions, so it can't simply stay as it is. Snapd takes the components installed for the current revision and drops any that forty three doesn't define. For the rest, it asks the store for the revisions that pair with forty three. Their tasks run inside the snap's own refresh change, so the snap and its components move together. The old pairing stays: snapd records components against each snap-revision it keeps, so a revert brings back forty two with diagnostics seven.

05 Taking a component out

REMOVE acme-agent 43diagnostics $ sudo snap remove acme-agent+diagnosticscomponent diagnostics for acme-agent removedsnap stays: same revision, same data $ sudo snap remove acme-agent+diagnosticserror: cannot remove "acme-agent": component"diagnostics" is not installed for revision 43of snap "acme-agent"asking again is refused; nothing changes remove hookunlinkprofiles, without itfile discardedthe installin reverse $ sudo snap remove acme-agentno plus: the snap and all its components one request cannot remove some components and also the whole snap
acme-agent 43 with the diagnostics component. sudo snap remove acme-agent+diagnostics prints component diagnostics for acme-agent removed and only the component goes. Running it again is refused because the component is not installed. Removal is the install in reverse: the remove hook, unlink, the security profiles set up again without it, and the file discarded. sudo snap remove acme-agent removes the snap and all its components; one request cannot do both

snap remove <snap>+<component> removes only the component and prints component diagnostics for acme-agent removed. snap remove <snap> removes the snap and all its components. It is the install in reverse; the file is kept while an older kept snap revision uses it.

The fault's found, and the diagnostics kit can come off the gateway again. The agent should stay exactly as it is. So it's snap remove, with the same plus name. Only the component leaves; the snap stays installed, on its revision, with its data. Ask a second time and snapd refuses, because that component isn't installed. Behind the scenes it's the install in reverse: the component's remove hook, unlink, the profiles set up again without it, and the file discarded. Remove the snap without a plus and everything goes, components included. What you can't do is ask for both in one request.

06 Drivers as components for Ubuntu Core developers for administrators

KERNEL-MODULES pc-kernelthe drivers most boards need wifi-extratype: kernel-modulesonly kernel snaps may define this type $ sudo snap install pc-kernel+wifi-extraprepare-kernel-modules-componentsone extra task in the install chain /var/lib/snapd/kernel/pc-kernel/<rev>modules+ wifi-extrafirmware+ wifi-extra components only: built aside, then swapped inno reboot counted as a resealing task: it runs alone; with a new kernel revision it sets up the next boot
The kernel snap pc-kernel gets the component wifi-extra of type kernel-modules, a type only kernel snaps may define. sudo snap install pc-kernel+wifi-extra adds the task prepare-kernel-modules-components, which rebuilds the drivers tree /var/lib/snapd/kernel/pc-kernel/<rev> so that its modules and firmware include wifi-extra. For a components-only install the tree is built aside and swapped in, with no reboot. The task counts as one that can reseal the disk encryption keys, so it runs alone among such tasks; with a new kernel revision it also sets up the next boot

Components of type kernel-modules exist only for kernel snaps. The task prepare-kernel-modules-components rebuilds the drivers tree under /var/lib/snapd/kernel/<kernel>/<rev>; for a components-only install it builds a temporary tree and swaps the affected directories in, so no reboot is needed. Removing the component runs the same task to clear its modules. The task counts as one that can reseal the disk encryption keys, so it does not run alongside another such task; with a new kernel revision it also sets up the next boot. wifi-extra is invented.

Same mechanism, different job. This batch's WiFi card needs drivers the kernel lacks. Its publisher ships them as a kernel modules component, a type only kernel snaps have. Installing one adds a task to the chain, prepare-kernel-modules-components. It rebuilds the kernel's drivers tree, the modules and firmware of the kernel and its components. When you only add components to the running kernel, snapd builds the new tree to one side and swaps it in: no reboot. snapd counts this task as one that can reseal the disk encryption keys, so it doesn't run alongside another. With a new kernel revision, it also sets up the next boot.

07 Where to go from here

ROADS Components Snap packaginga component on disk Lifecycle hooksthe four component hooks snapctl lifecyclea snap adds its ownAssertions: snapsthe component pairing The overlordchanges, tasks and undoRefreshtakes components along Model, gadget and kernelcomponents in an imageTry and packbuilding a component
Roads from Components: snap packaging, lifecycle hooks, snapctl lifecycle commands, snap assertions, the overlord, refresh, the model, and trying and packing a snap

Roads: packaging, component hooks, snapctl, the pairing assertions, the overlord, refresh, the model, and try and pack.

This deck was about operating components. What they are, and how they're made and signed, is spread over a few others. Packaging shows what a component is on disk and where it's mounted. The hooks deck covers the four component hooks and when they run. The snapctl deck shows a snap installing its own components when it needs them, and the snap assertions show how a component revision is paired with a snap-revision. The overlord explains changes, tasks and undo, and the refresh deck the refresh that takes components along. The model lists components for an image, and try and pack covers building one.

Read more

Commands

CommandEffect
snap install <snap>+<comp>[+<comp>...]install components, and the snap if it is missing
snap install --dangerous <snap>+<comp>_<rev>.compinstall a component from a local file, for an installed snap
snap remove <snap>+<comp>[+<comp>...]remove only the components
snap remove <snap>remove the snap and all its components
snap components [<snap>...]list components of installed snaps: Component, Status, Type
snap component <snap>+<comp>[+<comp>...]show type, summary, description and, if installed, version, revision and size
snap info <snap>includes a components: section

A component file holds one component and is named <snap>+<component>_<revision>.comp.

Output and messages

TextWhen
component C V for S V2 installeda component was installed
component "S+C" is already installedon stderr, nothing to do
component C for S removeda component was removed
cannot remove "S": component "C" is not installed for revision R of snap "S"removal of a component that is not installed for the current revision; the request is refused
No components are available for any installed snaps.snap components with nothing to list
no component "C" found for snap "S"snap component with an unknown name
exactly one snap and one or more of its components must be specifiedsnap component with more than one argument
"X" action is not supported for componentsthe API, for anything but install, refresh and remove
unexpected request to remove some components and also the full snap (which would remove all components) for "S"a mixed removal request
kernel-modules components can exist only for kernel snapsa snap of another type declares one

In snap info, a component that is not installed is shown as +one: -- -- -- -- test, not installed; an installed one shows version, date, revision, size and type.

The command line also has a message component C for S is not installed, printed when a removal change ends without removing a component that was asked for. A removal of a component that is not installed is refused by snapd before any change is made, so that message is not what you see in that case.

for administrators for app developers for Ubuntu Core developers

Tasks

OrderTask kindSummaryUndo
1download-componentDownload component "S+C" (R)none
1prepare-component (local file)Prepare component "<path>" (R)none
2validate-component (store revisions)Fetch and check assertions for component "S+C" (R)none
3mount-componentMount component "S+C" (R)yes
4the component's pre-refresh hook (refresh only)
5unlink-current-component (new component revision on an unchanged snap revision)Make current revision for component "S+C" unavailableyes
6setup-profilesSetup component "S+C" (R) security profilesyes
7link-componentMake component "S+C" (R) available to the systemyes
8the component's install or post-refresh hook
9prepare-kernel-modules-components (that type only)Prepare kernel-modules component "S+C" (R)yes
10discard-component (old revision no longer used, snap revision unchanged)Discard previous revision for component "S+C"none

When the component is installed together with its snap, or refreshed with it, its tasks are placed inside the snap's own chain and share the snap's setup-profiles task.

Removal: the component's remove hook, unlink-current-component, prepare-kernel-modules-components with the summary Clear kernel-modules component "S+C" (R), setup-profiles, and discard-component when no other kept snap revision uses the component revision.

The change summary of the snap operation gains with component C or with components C1, C2; a components-only removal is Remove component(s) ....

for administrators for app developers for Ubuntu Core developers

Where things are

ThingPlace
Mount point/snap/<snap>/components/mnt/<component>/<component-rev>
Link for one snap revision/snap/<snap>/components/<snap-rev>/<component>, pointing to ../mnt/<component>/<component-rev>
The file/var/lib/snapd/snaps/<snap>+<component>_<component-rev>.comp
snapd's recordper snap revision, in the snap's sequence in the state, as components
Kernel drivers tree/var/lib/snapd/kernel/<kernel>/<kernel-rev>

for app developers

For publishers

  • A snap declares its components in snap.yaml under components:, each with type, summary, description and optionally hooks.
  • Types: standard, kernel-modules (kernel snaps only) and test.
  • The component file carries meta/component.yaml.
  • Component hooks: install, pre-refresh, post-refresh, remove. Their security tag is snap.<snap>+<component>.hook.<hook>.
  • Hooks of a component receive SNAP_COMPONENT, SNAP_COMPONENT_NAME, SNAP_COMPONENT_VERSION and SNAP_COMPONENT_REVISION.
  • Apps receive SNAP_COMPONENTS=/snap/<snap>/components/<snap-rev>, but only when the snap declares components.

Where the documentation differs

  • The how-to says in one place that a snap component command is planned but not implemented; it is implemented, and the same page documents it further down.
  • The how-to shows one .comp file name holding two components. A component file holds one component.
  • The environment variable reference lists SNAP_COMPONENTS without the condition that the snap must declare components.

Further reading

Roads from here

GETTING SNAPS

  • Snap packaging — what a component is on disk and where it is mounted

RUNNING SNAPS

  • The overlord — changes and tasks and undo
  • Refresh — the snap refresh that takes components along

SNAPCTL · the snap's API into snapd

ASSERTIONS · signed statements snapd trusts

HOOKS · code snapd runs inside a snap

UBUNTU CORE · install and recovery

DEVELOPING SNAPS · try, pack, run, debug