Refresh
snap lifecycle for users for administrators for Ubuntu Core developers for snapd developers
snapd checks the store four times a day by default and refreshes every snap that has a new revision. A refresh can be held for all snaps or for named snaps. A snap with a running app is downloaded ahead and refreshed when the app closes or after 14 days. Each refresh is a change that stops the snap's services and switches revisions and it ends by asking the store once more.
On the map: the clocktower
01 Nobody asked for this update
By default snapd checks for new revisions four times a day, at a random moment in each of four windows (00:00~24:00/4). snap refresh --time shows the timer, the last attempt and the next one.
You open your laptop and the photo editor has a new version. You didn't ask for that, so who did, and when? Snapd keeps a timetable. By default it splits the day into four windows and picks a random moment inside each, so that not every machine asks the store in the same minute. At that moment it asks the store about every installed snap, and refreshes the ones that have a new revision. snap refresh --time shows the timer, the last attempt and the next one. A timetable says when a refresh may start, though. A few things can still postpone it.
02 The questions snapd asks before it starts for administrators for Ubuntu Core developers for snapd developers
Before an auto-refresh snapd checks, in order: the store is not set offline, the device is seeded, has a serial (or has failed three times to get one) and a synced clock, no auto-refresh change is in progress, no hold, the scheduled time has come, not held for a metered connection. Store queries are at least 20 minutes apart.
The timer says it's time. That's one of six questions snapd asks, and not the last. It walks the same list every time it wakes up. Is the store set offline? Is the laptop ready: seeded, with a serial, and a synced clock or ten minutes' wait? Is an earlier auto-refresh still running? Is a hold in place? Has the next time on the timer arrived? And is the connection metered, with refresh.metered set to hold? That's off unless you set it, and gives up after 95 days. Only then does it ask the store, and not again for 20 minutes.
03 Two kinds of hold
snap refresh --hold holds the automatic refresh of all snaps; it is the system option refresh.hold. snap refresh --hold photo-editor holds that snap in every refresh of all snaps, but snap refresh photo-editor still refreshes it. A hold with no duration lasts until --unhold, given without names for the first kind and with the snap's name for the second.
You're away for a week and you'd like the photo editor to stay as it is. There are two ways to say that. snap refresh --hold, with no snap names, holds the automatic refresh of every snap; you can still refresh by hand. Name the photo editor, and snapd holds general refreshes of that snap: the automatic one and a plain snap refresh both skip it. snap refresh photo-editor still refreshes it, because you named it. Give a duration, like 72 hours, or none: that's forever, with no cap. snap refresh --unhold with no names lifts the first kind; name the snap to lift the second.
04 The app is open when the update arrives
While one of a snap's apps is running, its automatic refresh is postponed: the new revision is downloaded, and installed when the app closes or after 14 days. A manual refresh of a snap with a running app fails with has running apps.
You've had the photo editor open all afternoon, and an update arrives. Swapping a program out from under you isn't safe, so snapd doesn't. It downloads the new revision now and leaves it waiting. When you close the app, the refresh runs straight away. Start it again in those few seconds and it waits, then opens the new revision. Keep it open for 14 days, though, and snapd refreshes it anyway. Unless a desktop helper snap is watching refreshes, snap warnings reminds you to close the app. And snap refresh photo-editor, run by hand while it's open, fails, naming the app and its process ids.
05 How snapd waits for the app for administrators for Ubuntu Core developers for snapd developers
A busy snap gets a pre-download change. snapd then watches its processes and creates an auto-refresh change when the last one exits. The unlink-current-snap task repeats the check under the run inhibition lock. refresh.max-inhibition-days (default 14) bounds the wait.
Putting a refresh off until you close the app sounds simple. Here's what it takes to do it without a gap where the app could start again. First, a soft check: which of the snap's apps have processes? Services don't count. A busy snap gets a separate pre-download change that only fetches it. Then snapd watches the snap's control groups, and when the last process exits it creates an auto-refresh change for that one snap. There, unlink-current-snap checks again while holding the run inhibition lock, so snap run waits instead of starting. refresh.max-inhibition-days, 14 by default, caps the whole wait.
06 One snap, from revision 41 to 42 for administrators for Ubuntu Core developers for snapd developers
Per snap, a refresh downloads, validates and mounts the new revision while the old one runs, then stops services, unlinks, copies data, sets up profiles, links, and starts services. The services are down between stop-snap-services and start-snap-services. A failure undoes the tasks in reverse and 41 comes back.
Now a different machine. On the gateway there's no app to close, just a daemon that should be running. So how long is acme-agent down while it goes from 41 to 42? Everything that can happen while 41 runs happens first: download, check, mount. Then 41's pre-refresh hook runs and the services stop. The current revision is unlinked, its data copied for 42, the security profiles set up, and 42 is linked. The post-refresh hook runs in 42 and the services start. So the agent is down from stop to start, and no longer. Then snapd tidies up: old revisions, the configure hook, the health check.
07 The change ends by asking the store again for administrators for Ubuntu Core developers for snapd developers
check-rerefresh is the last task of a refresh change. It asks the store again for the snaps the change refreshed and, when a revision with a different epoch is offered, adds its tasks to the same change.
Forty-two is running and the agent is back up. The change still isn't done, and the task that's left looks odd: it goes back to the store. That's check-rerefresh. It waits until every other task is ready, then asks the store again, but only about the snaps this change refreshed. Usually the answer is nothing. It's there for a snap whose data format moved on in steps, which the snap marks with its epoch. The store first offers a revision that can read the old data, and only from there the latest one. So when the data format moves on in steps, you get both steps in one change.
08 Where to go from here
Roads: the overlord, the store, services, remove and revert, the kernel try and validation sets.
A timetable, a few reasons to wait, and a column of tasks. Here's where each piece is explained in full. The overlord deck shows what a change and its tasks are, and how a failure is undone. The store deck covers where new revisions and channels come from. The services deck shows how a daemon is stopped and started around a refresh. Remove and revert covers the old revisions kept on disk, and going back to 41. The try deck covers what a kernel or base refresh adds on Ubuntu Core. And validation sets, which pin revisions during a refresh, live with the snap assertions.
Read more
Refresh options
Set with snap set system <option>=<value>.
| Option | Values | Effect |
|---|---|---|
refresh.timer | a timer string; default 00:00~24:00/4; managed | when auto-refresh may start. A value that cannot be parsed is logged and the default is used |
refresh.schedule | legacy schedule | read only when refresh.timer is empty |
refresh.hold | an RFC 3339 time or forever | no auto-refresh until that time. No upper limit is applied |
refresh.metered | hold or unset | with hold, no auto-refresh on a metered connection, for at most 95 days since the last refresh |
refresh.retain | 2 to 20; default 2 on classic and 3 on Ubuntu Core | revisions of each snap kept on disk |
refresh.max-inhibition-days | 1 to 21; default 14 | how long a running app can postpone its snap's auto-refresh |
refresh.rate-limit | a byte size | limits the download rate of auto-refreshes |
refresh.timer=managed is accepted only when an installed snap from the store has a connected snapd-control plug with refresh-schedule: managed. snapd then starts no auto-refresh by itself.
An auto-refresh waits until the device is seeded, its clock is synchronised or 10 minutes have passed, and it has a model and a serial. snapd also starts an auto-refresh without a serial after three failed attempts to get one.
On classic, a freshly seeded system gets refresh.hold set two hours ahead when no hold is set.
Commands
| Command | Effect |
|---|---|
snap refresh | refresh every snap that has a new revision, except held ones |
snap refresh <snap> | refresh that snap, also when it is held |
snap refresh --list | show what a refresh would do |
snap refresh --time | print timer:, last:, hold: and next:; a held next refresh reads next: <time> (but held); last: is the last auto-refresh attempt that reached the store, not the last successful refresh |
snap refresh --hold[=<duration>] | hold auto-refresh of all snaps; prints Auto-refresh of all snaps held ... |
snap refresh --hold[=<duration>] <snap>... | hold general refreshes of those snaps; prints General refreshes of ... held ... |
snap refresh --unhold [<snap>...] | without names, remove the hold on all snaps; with names, remove those snaps' holds |
snap refresh --transaction=all-snaps | all snaps refresh or none; the default is per-snap |
snap refresh --ignore-validation <snap> | refresh without applying validation sets |
snap warnings | shows cannot refresh (<snaps>) due running apps; close running apps to continue refresh. while a running app postpones a refresh and no snap has snap-refresh-observe connected; it can return soon after snap okay |
Two holds
| Hold on everything | Hold on named snaps | |
|---|---|---|
| Command | snap refresh --hold | snap refresh --hold <snap> |
| Level | auto-refresh | general |
| Stored as | the system option refresh.hold | an entry per snap, holder system |
| Auto-refresh | held | held |
snap refresh | runs | skips the snap |
snap refresh <snap> | runs | runs |
| Limit | none | none |
A general hold on all snaps is refused: holding general refreshes for all snaps is not supported. A held snap shows held under Notes in snap list.
Three mechanisms with similar names
- A hold placed by the administrator, described above. This is the only hold snapd applies today.
- The
gate-auto-refreshhook andsnapctl refresh --hold, with which a snap could hold its own or a dependent snap's refresh for up to 90 days. The feature is permanently disabled; see snapctl: services, refresh and changes. - "Refresh control" in the Ubuntu Core documentation: a gating snap and
validationassertions. See Assertions: snaps and validation.
Validation sets during a refresh
- An auto-refresh first refreshes assertions, including validation sets.
- A refresh of all snaps applies the sets that are in enforce mode. A pinned revision replaces the requested one. A snap whose presence is
invalidfails withcannot refresh snap "<name>" due to enforcing rules of validation set <set>. - Parallel instances are not constrained.
for administrators for Ubuntu Core developers for snapd developers
Tasks of one snap in a refresh change
In order: prerequisites, download-snap, validate-snap, mount-snap, run-hook (pre-refresh), stop-snap-services, remove-aliases, unlink-current-snap, copy-snap-data, setup-profiles, link-snap, auto-connect, set-auto-aliases, setup-aliases, run-hook (post-refresh), start-snap-services, clear-snap and discard-snap for each revision beyond refresh.retain, cleanup, run-hook (configure), run-hook (check-health). One check-rerefresh task ends the change. Kernel, gadget and base snaps add boot tasks; see Try, trying, done.
Change kinds: auto-refresh (summary Auto-refresh snap "<name>", Auto-refresh snaps ... or Auto-refresh <n> snaps) and pre-download (summary Pre-download <names> for auto-refresh).
A failed task undoes the tasks before it in reverse order and the old revision returns; see The overlord.
for administrators for Ubuntu Core developers for snapd developers
When an auto-refresh fails
- A snap whose switch was undone is recorded with the revision that failed. Auto-refresh to that same revision is delayed, starting at 8 hours and growing to 2 weeks, and the delay is doubled when a kernel, gadget, boot base or snapd refresh failed after its reboot. A different revision is tried at once.
snap refresh <snap>by hand is not delayed.
for administrators for Ubuntu Core developers for snapd developers
Refresh awareness in detail
| Item | Value |
|---|---|
| What makes a snap busy | a running app that is not a service and does not set refresh-mode: ignore-running; a running hook other than a confdb hook |
| Not checked | snaps of type snapd and os |
| Error on a manual refresh | snap "<name>" has running apps (<apps>), pids: <pids> |
| Lock file | /var/lib/snapd/inhibit/<snap>.lock |
| Hints | refresh, pre-download, remove, disable |
snap run during a refresh | waits, polling every 500 ms; on a terminal, when no snap has snap-refresh-observe connected, prints snap package "<name>" is being refreshed, please wait |
| Notices | refresh-inhibit and snap-run-inhibit (reading them needs snap-refresh-observe), change-update |
| Desktop notification | snapd posts none itself. A snap with snap-refresh-observe connected, such as a desktop integration snap, reads the notices and tells the user |
| Fallback warning | cannot refresh (<snaps>) due running apps; close running apps to continue refresh., when no snap has snap-refresh-observe connected. It is meant to return 24 hours after snap okay, but snapd re-creates it at every auto-refresh attempt while the app is still open, so it can return within hours (a snapd bug) |
Further reading
- Manage updates: the hold, time and list flags with examples. It gives a 90 day limit for
refresh.holdthat the code does not apply. - Refresh awareness: what a desktop user sees while an update waits for an app to close.
- Timer string format: the full grammar of
refresh.timer. - System options: one section per
snap set systemoption. - Refresh control: gating with validation assertions on Ubuntu Core, a different mechanism from holds.
- Manage validation sets: how an enforced set pins revisions during a refresh.
Roads from here
GETTING SNAPS
- The store — where new revisions and channels come from
RUNNING SNAPS
- The overlord — a refresh is a change made of tasks
- Services — how services are stopped and started around a refresh
- Remove and revert — how many old revisions stay and how to revert
- Who decides when a snap updates — who decides when a snap updates
SNAPCTL · the snap's API into snapd
- snapctl: services, refresh and changes — what remains of snapctl refresh
ASSERTIONS · signed statements snapd trusts
- Assertions: snaps and validation — validation sets that pin revisions during a refresh
UBUNTU CORE · boot
- Try, trying, done — what a kernel or base refresh adds on Ubuntu Core
DESKTOP · snaps in a user session
- The user session agent — how refresh notices reach the desktop