Who decides when a snap updates

purpose for users for administrators for Ubuntu Core developers for app developers

snapd refreshes snaps without being asked and four parties can steer that. The person at the machine can hold and schedule refreshes. A running app delays its own refresh for a limited time. The publisher chooses what each channel offers. A brand can pin revisions for a fleet. Each control has its own reach and its own limit and this deck compares them.

On the map: running snaps district

▶ Watch this deck — 7 scenes, ~5 min

01 Updates arrive without being asked

WHO DECIDES publisherphoto-editor rev 43storestable channel your laptopphoto-editor rev 42asks the store 4 times a day photo-editor rev 43nobody typed anything $ snap refresh --timetimer: 00:00~24:00/4last: today at 07:47 CETnext: today at 12:13 CET ????four places to say: not yet
The publisher releases photo-editor revision 43 to the store's stable channel; the laptop, which asks the store four times a day, moves from revision 42 to 43 without anyone typing a command; snap refresh --time shows the timer, the last check and the next one; four empty places with question marks mark where someone could say not yet

By default snapd checks the store four times a day and refreshes what has a new revision. Four parties can steer that: you, the running app, the publisher and the brand.

The photo editor updated itself overnight. You didn't ask. So who decided, and who could have said: not yet? The publisher released revision 43 to the stable channel you follow. Snapd asks the store about that channel four times a day, and your laptop took it. Nobody typed anything. snap refresh --time shows when it last asked and when it asks next. That's the design. The Ubuntu Core documentation gives the reason: it ensures that security fixes are applied promptly. But that default may not suit a hospital gateway, or you this week. Four parties can say not yet.

02 Four parties, four kinds of control

FOUR PARTIES photo-editor rev 43your laptop publisherwhich revision ison which channel brandwhich revisions itsdevices may run you, the administratorwhen, and whether,this machine refreshes the running appnot while I'm open channelvalidation setholdopen appdecide what is offereddecide when it is taken
Revision 43 travels from left to right past four parties: the publisher decides which revision is on which channel, the brand decides which revisions its devices may run, you the administrator decide when and whether the machine refreshes, and the running app asks for not while it is open. The first two decide what is offered, the last two when it is taken

The publisher and the brand decide which revision a device is offered. The administrator and the running app decide when it is installed.

Follow revision 43 on its way to you. It passes four parties, and each one can slow it down. First the publisher: a revision reaches you only once it's released to the channel you track. Second, on a managed device, the brand: it can say which revisions belong on its devices, and run its own store. Third, whoever has root on the machine. That's you: you can schedule refreshes and hold them. Fourth, the app itself, in one narrow way: while it's open, its refresh waits. Notice the split. The first two decide what's offered. The last two decide when it's taken.

03 "One bad update: hold that snap, refresh the rest"

YOUR CONTROL your laptopphoto-editor42firefoxcore24revision 43 breaks your plug-in $ snap refresh --hold photo-editorGeneral refreshes of "photo-editor"held indefinitelyheld refreshedrefreshedthe rest of the system keeps up $ snap refresh photo-editor44naming the snap still refreshes it: your way to try the fix $ snap refresh --unhold photo-editorRemoved general refresh hold of "photo-editor" without a name, snap refresh --hold pauses automatic refresh of every snap; the refresh deck compares the two
On the laptop photo-editor is at revision 42 and revision 43 breaks a plug-in. snap refresh --hold photo-editor holds general refreshes of it; firefox and core24 refresh while photo-editor stays at 42. snap refresh photo-editor still refreshes it to 44. snap refresh --unhold photo-editor removes the hold

snap refresh --hold <snap> keeps one snap back from automatic and general refreshes while the rest refresh. Naming the snap in snap refresh still refreshes it.

Revision 43 breaks the one plug-in you can't work without. You'd like the laptop to keep updating, just not that snap. snap refresh --hold, followed by the snap's name, does exactly this. Automatic refreshes and a plain snap refresh both skip it, while firefox and core24 keep moving. When the publisher ships 44 with a fix, snap refresh photo-editor still refreshes it, because you named it. That's how you try the fix. If it works, snap refresh --unhold, with the name, lifts the hold. Leave the name out and the hold pauses automatic refresh for everything; the refresh deck compares the two.

04 How long each wait can last

LIMITS 014 days95 daysforever an open app$ snap set system refresh.max-inhibition-days=71 to 21; default 14 a metered connectionafter the last refresh$ snap set system refresh.metered=holdoff unless you set it your hold$ snap refresh --holdno duration means forever some docs say 90 days; the code has no limit held forever also means: no security fixes
Three bars on a time axis: an open app delays its refresh for 14 days by default, settable from 1 to 21 with refresh.max-inhibition-days; a hold on a metered connection, switched on with refresh.metered=hold, ends 95 days after the last refresh; your own snap refresh --hold has no limit and with no duration lasts forever, which also means no security fixes

An open app delays a refresh for 14 days by default (1 to 21). Holding on a metered connection ends after 95 days. An administrator's hold has no limit.

Not yet is fine. But not yet until when? Each wait has a different end, and one has none. An app that stays open delays its own refresh for fourteen days, then snapd refreshes it anyway. refresh.max-inhibition-days sets that from one to twenty-one. Holding on a metered connection is something you switch on, with refresh.metered, and it gives up ninety-five days after the last refresh. Your own hold is the exception: give a duration, or give none and it lasts until you lift it. Some documentation still says ninety days; the code has no limit. And a snap held forever gets no security fixes.

05 "A fleet: the brand's controls" for administrators for Ubuntu Core developers for app developers

THE BRAND'S CONTROL acmeacme-agent 42tested? not yetgateways 414141 414141 414141 validation set: acme-agent 41the devices are held at the tested revision validation set: acme-agent 42, sequence 4 424242 424242 42424242 at the next refresh acme's own storewhat is offered at all, and when store proxy on the factory networkthe schedule and the revisions, mediated on site older: a gating snap approving each revision
The brand acme and nine gateways. A validation set keeps the gateways on acme-agent 41 until acme publishes sequence 4 naming 42, and they move to 42 at their next refresh. acme's own store decides what is offered at all and when; a store proxy on the factory network mediates the schedule and the revisions on site. Older: a gating snap approving each revision

A brand can keep devices at tested revisions with a validation set, control what is offered through its own store, or mediate refreshes through a store proxy.

On your laptop, you're the one a bad update hurts, and you're the one who can hold it. Who does that for a thousand gateways with no keyboard? The Ubuntu Core documentation names the need: holding a snap at a tested revision until a new release is separately validated. The brand has three tools. A validation set pins revisions: the gateways stay on 41 until acme publishes a new sequence that says 42. A dedicated store controls what's offered, and when. A store proxy on site lets a device manager control the schedule and the revisions. There's also an older scheme, a gating snap. Each has its own deck.

06 What a snap can no longer decide for app developers for administrators for Ubuntu Core developers

GONE acme-agentgate-auto-refresha hookhold my refreshsnapd permanently disabled the hook is not runholds placed by snaps areremoved when snapd starts$ snapctl refresh --holdcannot hold outside of gate-auto-refresh hook an app that is not a service: its refresh waits while it runsa service: stopped and started around the refresh $ snapctl refresh --pendinga snap can still ask what is waiting
The snap acme-agent with a gate-auto-refresh hook once asked snapd to hold its refresh. That path is struck through: the feature is permanently disabled, the hook is not run, snapctl refresh --hold fails and holds placed by snaps are removed when snapd starts. What remains: an app that is not a service: its refresh waits while it runs, services are stopped and started around the refresh, and snapctl refresh --pending reports what is waiting

Holding refreshes from a snap's gate-auto-refresh hook is permanently disabled. A snap can still read its refresh state with snapctl refresh --pending.

There used to be a fifth answer: the snap itself. Older material describes a gate-auto-refresh hook, from which a snap could hold its own update. That's over. The code marks the feature as permanently disabled, to be removed in a future release. The hook isn't run, snapctl refresh --hold fails, and holds that snaps placed earlier are dropped when snapd starts. If you publish a snap, don't design around holding your own update. What you can count on: while your app is open its refresh waits, up to that limit, and your services are stopped and started around it. And snapctl refresh --pending still says what's waiting.

07 Where to go from here

ROADS youthe running apppublisherbrandoffered: publisher and brand · when it is taken: you and the open app · only your hold has no end Refreshthe timer and the holdsRemove and revertgoing back The storechannels and tracksEpochsa data migration first Validation setspinning a combinationA store of your ownwhat is offered at all snapctl refreshwhat remains of it
Roads from this deck grouped by party: for you, Refresh and Remove and revert; for the running app, Refresh again and snapctl refresh; for the publisher, The store and Epochs; for the brand, Validation sets and A store of your own

The refresh deck has the timer and the holds; the store deck has channels; validation sets and the brand store have their own decks.

Four parties, and each has its own deck or two. Two decide what's offered, two decide when it's taken, and only your own hold has no end. For you, the refresh deck has the timer and both kinds of hold, and remove and revert covers going back. The open app's wait is in the refresh deck too. For the publisher, the store deck covers channels and tracks, and the epochs deck an update that waits for a data migration. For the brand, there are validation sets, and a store of your own. And the snapctl deck shows what remains of snapctl refresh.

Read more

Who can do what

PartyControlReachLimit
Administratorsnap refresh --hold[=<duration>]automatic refresh of all snapsnone; no duration means forever
Administratorsnap refresh --hold[=<duration>] <snap>...automatic and general refreshes of those snapsnone; snap refresh <snap> still refreshes
Administratorsnap set system refresh.timer=...when automatic refreshes may starta schedule, not a hold
Administratorsnap set system refresh.metered=holdautomatic refresh on a metered connection95 days since the last refresh
Administratorsnap revert <snap>the revision stepped back over is skipped when all snaps are refresheduntil a different revision is offered
Running appbeing openthat snap's automatic refreshrefresh.max-inhibition-days: 14 by default; 1 to 21
Publisherreleasing to a channel; tracks; branchesevery device following that channelnone on the device
Publisherepochsdevices whose data the new revision cannot readuntil they pass the migrating revision
Brandvalidation set (enforced)the snaps and revisions the set namesuntil a new sequence or --ignore-validation
Branddedicated store; store proxywhat its devices are offeredthe store's side; outside snapd
A snapgate-auto-refresh hooknothingpermanently disabled

The system options behind the commands

Set with snap set system <option>=<value>.

OptionValueEffect
refresh.timera timer string; default 00:00~24:00/4the windows in which an automatic refresh may start
refresh.holdan RFC 3339 time or foreverno automatic refresh before that time; written by snap refresh --hold with no names
refresh.meteredhold or unsetskip automatic refresh on a metered connection for up to 95 days since the last refresh
refresh.max-inhibition-days1 to 21; default 14how long an open app can delay its refresh
refresh.retain2 to 20how many revisions stay on disk to revert to

Three numbers that are easy to mix up

  • 14 days: the default wait for an open app.
  • 95 days: the limit for a metered-connection hold. Holds placed by snaps (now disabled) were limited to 90 days.
  • 90 days: stated for refresh.hold in the published "Manage updates" page. The code has no limit for refresh.hold; forever is accepted. The cap was removed on purpose in 2022.

Snaps that do not refresh automatically

The published docs say snaps in devmode and snaps installed from a local file "do not update automatically until they've been published and downloaded from the store".

for administrators for Ubuntu Core developers for app developers

What a snap can still do

  • Its apps that are not services postpone the snap's automatic refresh while they run, up to refresh.max-inhibition-days.
  • Its services are stopped before the switch and started after it, unless they set refresh-mode: endure.
  • snapctl refresh --pending reports ready, inhibited or none.
  • snapctl refresh --hold and --proceed fail: the gate-auto-refresh-hook feature is permanently disabled, the hook is not run, and holds placed by snaps are removed when snapd starts. See snapctl: services, refresh and changes.

for administrators for Ubuntu Core developers for app developers

The older fleet mechanism: gating snaps

A gating snap's publisher signs a validation assertion for each approved revision of a gated snap. While the gating snap is installed the gated snap refreshes only to an approved revision. snapd still applies this at refresh. Validation sets are the other documented solution.

Further reading

Roads from here

GETTING SNAPS

RUNNING SNAPS

  • Refresh — the timer and the holds and the refresh change itself
  • Remove and revert — going back after an update you did not want

SNAPCTL · the snap's API into snapd

ASSERTIONS · signed statements snapd trusts