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
01 A part you add when you need it
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
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
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
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
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
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: 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
| Command | Effect |
|---|---|
snap install <snap>+<comp>[+<comp>...] | install components, and the snap if it is missing |
snap install --dangerous <snap>+<comp>_<rev>.comp | install 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
| Text | When |
|---|---|
component C V for S V2 installed | a component was installed |
component "S+C" is already installed | on stderr, nothing to do |
component C for S removed | a 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 specified | snap component with more than one argument |
"X" action is not supported for components | the 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 snaps | a 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
| Order | Task kind | Summary | Undo |
|---|---|---|---|
| 1 | download-component | Download component "S+C" (R) | none |
| 1 | prepare-component (local file) | Prepare component "<path>" (R) | none |
| 2 | validate-component (store revisions) | Fetch and check assertions for component "S+C" (R) | none |
| 3 | mount-component | Mount component "S+C" (R) | yes |
| 4 | the component's pre-refresh hook (refresh only) | ||
| 5 | unlink-current-component (new component revision on an unchanged snap revision) | Make current revision for component "S+C" unavailable | yes |
| 6 | setup-profiles | Setup component "S+C" (R) security profiles | yes |
| 7 | link-component | Make component "S+C" (R) available to the system | yes |
| 8 | the component's install or post-refresh hook | ||
| 9 | prepare-kernel-modules-components (that type only) | Prepare kernel-modules component "S+C" (R) | yes |
| 10 | discard-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
| Thing | Place |
|---|---|
| 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 record | per 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 withtype,summary,descriptionand optionallyhooks. - Types:
standard,kernel-modules(kernel snaps only) andtest. - The component file carries
meta/component.yaml. - Component hooks:
install,pre-refresh,post-refresh,remove. Their security tag issnap.<snap>+<component>.hook.<hook>. - Hooks of a component receive
SNAP_COMPONENT,SNAP_COMPONENT_NAME,SNAP_COMPONENT_VERSIONandSNAP_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 componentcommand is planned but not implemented; it is implemented, and the same page documents it further down. - The how-to shows one
.compfile name holding two components. A component file holds one component. - The environment variable reference lists
SNAP_COMPONENTSwithout the condition that the snap must declare components.
Further reading
- Work with components: the commands with sample output. See the differences above.
- Snap components:
component.yaml, hooks and theSNAP_COMPONENT*variables. - snap-resource-revision: ties a component file to a revision.
- snap-resource-pair: ties a component revision to a snap revision.
- Use snapctl: component management from inside a snap.
- model:
componentsunder a snap in a model, for kernel-modules components in an image.
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
- snapctl: services, refresh and changes — a snap installing its own components with snapctl
ASSERTIONS · signed statements snapd trusts
- Assertions: snaps and validation — the two assertions that tie a component to a snap revision
HOOKS · code snapd runs inside a snap
- Hooks: install, configure, refresh, remove — the four component hooks and when they run
UBUNTU CORE · install and recovery
- Model, gadget and kernel — components listed in a model for an image
DEVELOPING SNAPS · try, pack, run, debug
- Trying and packing a snap — packing and installing a component file