A store of your own

purpose for Ubuntu Core developers for administrators

On the public store a device vendor does not decide which snaps its devices can install or who may publish for them. A dedicated snap store formerly called a brand store lets the vendor control what is available and when. A device uses it because its model names it. Privileges granted to the brand's snaps can be limited to devices of that store. The store service itself is outside snapd.

On the map: getting snaps district

▶ Watch this deck — 7 scenes, ~5 min

01 Anyone's snap, on your gateway

A STORE OF YOUR OWN acme-gateway$ snap install some-gamethe Snap Store, publicacme-agentacme-updateracme-vpn installed: it is public, so the gateway may have it which snaps may it install?who may publish for this device?when does a new revision reach it?on the public store, not acme's call acme's dedicated storeacme-agentacme-updateracme-vpntwo picked public snaps $ snap install some-gamenot foundnot in acme's store, so not on acme's gateway
An acme gateway installs a public game from the public Snap Store, where acme's three snaps sit among everyone else's; three questions the vendor cannot answer there; a dedicated store with acme's snaps and two picked public snaps; the same install now finds nothing

A dedicated snap store, formerly called a brand store, "allows vendors running Ubuntu Core and snap-based devices to control exactly what snaps are available and when".

Somebody logs in to one of your gateways and types snap install, with the name of a game. Should that work? On the public store, it isn't your decision. Acme's gateways follow the public Snap Store, so they can install any public snap, and acme's own snaps sit on the shelf next to everyone else's. Acme doesn't get to say what its gateways are offered, or when. The Ubuntu Core docs describe the alternative: a dedicated snap store, once called a brand store. It lets a vendor control exactly which snaps are available, and when. Ask for that game again, and it isn't there.

02 What a dedicated store adds

PUBLIC · DEDICATED Snap Storeacme's dedicated store accesspublicrestrictedsnaps seen only by the store's users contentcurated by Canonicalcurated by its ownercan include selected snaps from other stores accountsno account delegationroles the brand hands outadminreviewerviewerpublisher on siteno proxy supportproxy snap server support both: hosted and monitored by Canonical · over-the-air updates · refresh control · run by the store, not by snapd
The public Snap Store and a dedicated store side by side: access public or restricted, content curated by Canonical or by the owner with snaps included from other stores, no delegation or four roles, no proxy support or proxy snap server support; both hosted and monitored by Canonical

Compared with the public Snap Store, a dedicated store has restricted access, content curated by its owner, account delegation and proxy support. Both are hosted by Canonical.

You might picture a dedicated store as a server in acme's basement. It isn't. It's the same service, with a different owner for four decisions. Access is restricted, so snaps published there are seen only by that store's users. The content is curated by its owner, and it can include selected snaps from other stores, so the gateway still gets the public snaps it needs. The brand can hand out roles: admin, reviewer, viewer and publisher. And it can sit behind a proxy on site. Canonical hosts and monitors both kinds, and both have over-the-air updates. All of this is the store's side. Snapd implements none of it.

03 One account behind it all

THE BRAND ACCOUNT account: acmean ordinary account,augmented by the store team signing keysgenerates, registers and holds them model: acme-gatewaysigns models that point at the store acme-kernelacme-gadgetregisters kernel and gadget names acme's dedicated storedefines its scope of authority adminreviewerviewerpublishernot admin, reviewer or viewerroles go to other accounts
The brand account acme at the centre, with spokes to its signing keys, the acme-gateway model it signs, the kernel and gadget names it registers and the dedicated store whose authority it defines; the store's roles go to other accounts, not to the brand account

The brand account holds the signing keys, signs models and registers kernel and gadget snap names. Other accounts get the store's roles; the brand account's use is kept strictly limited.

So far, acme decides. Who, exactly, is acme? One account, and you'd better look after it. The docs call it the brand account: an ordinary sign-on account that the store team augments. It generates and holds the brand's signing keys. It signs the models of images that point at the store. It registers the kernel and gadget snap names. And it defines the store's scope of authority. On the gateway, that account is the brand in the model, and also its signer. So the docs ask you to keep its use strictly limited. Daily work goes to accounts with roles; the brand account shouldn't be an admin, reviewer or viewer.

04 One header points the device at the store

MODEL → STORE modelbrand-id: acmemodel: acme-gatewaystore: acme-storeleft out: the device uses the main store acme-gateway Snap-Device-Store: acme-storesent with its requestsacme's store serial 7f3a · acme-gatewaydevice sessionthe store checks which device is asking store assertion: acme-storefetched while a snap is checked,if the store has one
The acme-gateway model with store: acme-store attached to the gateway; the gateway sends Snap-Device-Store: acme-store with its requests; a device session from its serial tells the store which device asks; snapd fetches the store assertion for acme-store while checking a snap, if the store has one

The model's optional store header names the device's store, and snapd sends it with store requests. A device session based on the serial tells the store which device is asking.

You won't find a switch on the gateway that says use acme's store. So how does it know where to shop? The model says so. It has an optional store header, and a model without one uses the main store. Snapd reads that header and sends the store id along with its store requests. On its own, anybody could claim that, so the store also wants to know who's asking. The gateway signs in to a device session with its serial, issued for acme's model. And when the model names a store, snapd also fetches that store's assertion, if there is one, while it checks a snap.

05 Privileges that stay inside the store

STORE SCOPING acme-agentsnapd-controlsnap-declarationsnapd-control:allow-auto-connection:on-store: [acme-store] acme-gateway · model store: acme-storeacme-agentsnapd-controlsystemmatch: connected at install a generic device · no store in its modelacme-agentsnapd-controlsystemno match: not connected "safeguards against ... auto-connections ... made outside a dedicated snap storewhen a snap is installed on a generic device" on-store narrows the rule it sits in · under allow-installation, snapd refuses the install
acme-agent's snapd-control plug with a snap-declaration rule allow-auto-connection on-store acme-store; on acme-gateway, whose model names acme-store, the plug connects; on a generic device with no store in its model, it does not; the same condition under allow-installation makes snapd refuse the install

A grant with on-store applies only on devices whose model names that store. It narrows only the rule it is in: under allow-auto-connection it stops the connection, under allow-installation snapd also refuses the install.

The store gave acme-agent a powerful permission, because on acme's gateways it needs it. What happens if that snap turns up on somebody else's device? The grant carries a condition: on-store, naming acme's store. Snapd compares it with the store in the device's model. On the gateway they match, and the plug connects by itself. On a generic device with no store in its model, the plug stays unconnected. The docs call it a safeguard against auto-connections outside a dedicated store. The condition narrows only the rule it sits in. Put it on installation too, as the docs' example does, and snapd refuses the install there.

06 When you do not need one

WHEN NOT my device uses only public snapsno store header in the model → the main storeyou still sign your own model and pick your snaps my gateways cannot reach the interneta store proxy on site$ snap set system proxy.store=... cannot set proxy.store to "..."without a matching store assertionthe device must know that store first · see the store deck only my devices get my snaps,and I decide who publishesa dedicated store what a store lists, and for whom, is decided in the store service, not in snapd
Three needs and their answers: only public snaps needs a model with no store header; no internet access needs a store proxy set with proxy.store, which snapd refuses without a matching store assertion; controlling who installs and publishes needs a dedicated store

A model without a store header uses the main store. A network without internet access calls for a store proxy and proxy.store, not necessarily a dedicated store.

Do you need all this to ship a device? Often not. If everything your device needs is public, leave the store header out. The model then uses the main store, and you still sign your own model and pick your snaps. Next, gateways on a factory network with no route out. That's a job for a store proxy, an on-premise cache. Snapd accepts proxy.store only when it has a matching store assertion. Reach for a dedicated store when you need to decide who sees and publishes your snaps, and what your devices are offered. Those decisions are made in the store service, not in snapd.

07 Where to go from here

ROADS A store of your ownThe storewhat snapd asks; proxy.store Model, gadget and kernelthe header that names the store Assertions: identity and storestore assertion, accounts, keys Devices · device hooksthe serial and who asks for it Snap-declaration ruleson-store, on-brand, on-model Validation sets · update controlafter the device ships
Roads from A store of your own: the store client and proxy.store, the model, identity and store assertions, device assertions and device hooks, snap-declaration rules, and validation sets with update control

Roads: the store client, the model, the store assertion, the serial and its hook, store-scoped rules in snap-declarations, validation sets and update control.

A store of your own is mostly a decision about who's in charge. Here's where the moving parts are. The store deck shows what snapd asks a store, and how proxy.store redirects it. The model deck has the header that names the store. Identity and store covers the store assertion, and the accounts and keys behind it. The device assertions and the device hooks show the serial, and how the gadget asks for one. The snap-declaration rules cover on-store, on-brand and on-model. And validation sets and update control are what the brand decides after the device ships.

Read more

Public and dedicated store compared

The table is the one in the Ubuntu Core documentation. Everything in it is done by the store service, not by snapd.

Dedicated snap storeSnap Store
AccessRestrictedPublic
Snaps publishedOnly to dedicated store usersSeen globally
ContentCurated by ownerCurated by Canonical
HostingCanonical hosted and managedCanonical hosted and managed
SecurityMonitored by CanonicalMonitored by Canonical
Over-the-air updatesYesYes
Refresh controlYesYes
Account delegationYesNo
Proxy snap server supportYesNo
Custom dashboardYesNo
Custom API accessYesNo
SubstoresYesNo

What snapd does and what the store does

StepDone by
Name the store in the model's store headerthe brand when it signs the model
Send the store id with requests (Snap-Device-Store)snapd
Sign in with the device's serialsnapd; the store checks it
Decide which snaps that device is offeredthe store
Decide who may publish and reviewthe store's roles set by the brand
Fetch the store assertion when the model names a storesnapd, while checking a snap
Apply on-store rules of a snap-declarationsnapd
Refuse proxy.store without a matching store assertionsnapd

snapd takes the store id from the model. On the generic classic model, or with no model yet, it uses the UBUNTU_STORE_ID environment variable instead.

Store scoping in snapd

on-store is a device scope constraint. snapd checks it against the store header of the device's model, and also accepts a store listed in the store assertion's friendly-stores. A model without a store header matches no on-store list.

Where on-store sitsEffect on a device of another store
allow-auto-connectionthe snap installs; the plug is not connected automatically
allow-installationsnapd refuses the install: installation not allowed by "<plug>" plug rule of interface "<interface>" for "<snap>" snap

The store-scoping page of the Ubuntu Core documentation says a snap cannot be prevented from being installed. In snapd, an on-store condition under allow-installation of a snap-declaration is checked at install time, as its own example shows. A snap whose interfaces have no installation rule installs anywhere.

Things only the brand account does

  • generate, register and hold the signing keys of the brand
  • sign model assertions for images that point at a dedicated store
  • register kernel and gadget snap names (Canonical can also register them)

The documentation recommends that the brand account is not given the Admin, Reviewer or Viewer role, and that two-factor authentication is enabled on it. The keys it generates are kept locally in ~/.snap/gnupg.

Roles in a dedicated store

RoleCan
Adminmanage the store; the highest level of permissions
Reviewerapprove changes to snaps when the store requires reviews
Viewersee and download snaps, for building images or testing
Publisherregister names, upload and release revisions, set collaborators

Words for the same thing

WordWhere
dedicated snap storethe current Ubuntu Core documentation
brand store; IoT App Storeolder and product names for the same thing
non-default storethe snapd code
store proxy; Enterprise Storean on-premise proxy; a different thing

Further reading

Roads from here

GETTING SNAPS

  • The store — what snapd asks a store and how proxy.store redirects it

RUNNING SNAPS

ASSERTIONS · signed statements snapd trusts

HOOKS · code snapd runs inside a snap

POLICY · who may install and connect what

UBUNTU CORE · install and recovery