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
01 Updates arrive without being asked
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
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"
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
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
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
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
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
| Party | Control | Reach | Limit |
|---|---|---|---|
| Administrator | snap refresh --hold[=<duration>] | automatic refresh of all snaps | none; no duration means forever |
| Administrator | snap refresh --hold[=<duration>] <snap>... | automatic and general refreshes of those snaps | none; snap refresh <snap> still refreshes |
| Administrator | snap set system refresh.timer=... | when automatic refreshes may start | a schedule, not a hold |
| Administrator | snap set system refresh.metered=hold | automatic refresh on a metered connection | 95 days since the last refresh |
| Administrator | snap revert <snap> | the revision stepped back over is skipped when all snaps are refreshed | until a different revision is offered |
| Running app | being open | that snap's automatic refresh | refresh.max-inhibition-days: 14 by default; 1 to 21 |
| Publisher | releasing to a channel; tracks; branches | every device following that channel | none on the device |
| Publisher | epochs | devices whose data the new revision cannot read | until they pass the migrating revision |
| Brand | validation set (enforced) | the snaps and revisions the set names | until a new sequence or --ignore-validation |
| Brand | dedicated store; store proxy | what its devices are offered | the store's side; outside snapd |
| A snap | gate-auto-refresh hook | nothing | permanently disabled |
The system options behind the commands
Set with snap set system <option>=<value>.
| Option | Value | Effect |
|---|---|---|
refresh.timer | a timer string; default 00:00~24:00/4 | the windows in which an automatic refresh may start |
refresh.hold | an RFC 3339 time or forever | no automatic refresh before that time; written by snap refresh --hold with no names |
refresh.metered | hold or unset | skip automatic refresh on a metered connection for up to 95 days since the last refresh |
refresh.max-inhibition-days | 1 to 21; default 14 | how long an open app can delay its refresh |
refresh.retain | 2 to 20 | how 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.holdin the published "Manage updates" page. The code has no limit forrefresh.hold;foreveris 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 --pendingreportsready,inhibitedornone.snapctl refresh --holdand--proceedfail: thegate-auto-refresh-hookfeature 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
- Manage updates: holds and the refresh options from the administrator's side. Its 90 day limit for
refresh.holdis not applied by the code. - Refresh awareness: what happens when the app is open.
- Refresh control: why a project holds snaps at tested revisions, and the gating-snap mechanism.
- Validation sets: pinning a combination of snaps.
- CVE remediation: automatic refresh as the way security fixes reach Ubuntu Core devices.
- Channels and tracks: the publisher's side.
Roads from here
GETTING SNAPS
- A store of your own — a store where the brand decides what is offered
- Epochs: when new code cannot read old data — an update the publisher makes wait for a data migration
- The store — channels and tracks and risks
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
- snapctl: services, refresh and changes — what remains of snapctl refresh
ASSERTIONS · signed statements snapd trusts
- Validation sets: snaps that belong together — pinning a combination of revisions for a fleet