Warnings and notices
managing snaps for users for administrators for snapd developers
A warning is a message snapd keeps for the people who use the system. The snap command announces new warnings and snap warnings lists them and snap okay acknowledges them. Warnings can be listed again a day after you list and acknowledge them and expire 28 days after they last occurred. A notice is a record that something happened which programs read through the API. There are six notice types and a snap needs the matching interface to read them.
On the map: administration district
01 A line after your command
After any command, snap prints WARNING: There is 1 new warning. See 'snap warnings'. when snapd holds warnings you have not seen. Warnings are for people; notices are records that programs read through the API. The refresh warning is recorded only when no snap has snap-refresh-observe connected.
You ran snap list, which has nothing to do with refreshing, and there's an extra line at the bottom. Where did that come from? Snapd had something to tell whoever uses this laptop, and the snap command is how it gets a word in. An automatic refresh of the photo editor was held back, because the app is open. Snapd reports events like that in two ways. A warning is a message for a person. A notice is a record for programs: a desktop helper waits for it and pops up a notification. Here the warning is the fallback, written only when no snap is listening for the notice.
02 Read, then acknowledge
snap warnings lists pending warnings and records, for your user, when you looked. snap okay acknowledges the warnings that were pending at that time; a warning first recorded later stays pending. --all also lists acknowledged warnings; --verbose adds first occurrence, acknowledgement, repeat and expiry.
The line said: see snap warnings. Suppose you're in a hurry and try snap okay first. It's refused: you can't acknowledge what you haven't read. So run snap warnings. It prints each pending warning and when it last happened, and the snap command notes the time, for your user. Snap okay then sends that time to snapd, which acknowledges every warning pending at that moment. That's the point of two steps: a warning that arrives between your reading and your okay isn't swept away. Run snap warnings again: no further warnings. snap warnings --all also lists acknowledged ones, and the --verbose option adds the dates.
03 The life of a warning
One warning exists per message text. Once acknowledged, by default it is listed again 24 hours after the snap warnings listing you acknowledged, whether or not it occurred again, and it expires 28 days after it last occurred. The help says it returns only if it occurs again; the code does not check that (a confirmed bug). The refresh warning is deleted and re-added at each auto-refresh attempt, so snap okay holds it only until the next one (also confirmed).
You've acknowledged the warning. Is that the last you'll hear of it? Three clocks decide. First, there's only one warning per message. If it happens again, snapd moves its last occurrence forward. Second, once you've okayed it, a warning stays quiet for its repeat time, a day by default, counted from your last snap warnings. Then it's listed again, whether or not it happened again. The help text says it must happen again; that's a confirmed bug. Third, twenty eight days after it last happened, snapd forgets it. A second bug: snapd re-creates the photo editor warning at each auto-refresh, so it can return within hours.
04 One list for the system, one bookmark per user for administrators for snapd developers
Warnings live in snapd's state under warnings, once per system. Every response carries warning-count and warning-timestamp; the client shows the banner when that timestamp is later than the one in the user's ~/.snap/warnings.json. snap okay updates the shared list, so it acknowledges for every user.
Alice has read the warning. Then Bob logs in, runs snap list and gets the banner. Is that a second warning? No. There's one list, in snapd's state, for the whole machine. Every answer from snapd carries a count of pending warnings and a timestamp: the newest last occurrence among them. The snap command compares that with your bookmark, the time you last listed warnings, kept in a file in your home. Later means a banner. Bob has no bookmark yet; Alice's is later. But Alice's snap okay changes the shared list, so it's quiet for Bob too. Anyone local can read warnings; acknowledging needs root, polkit or a logged-in user.
05 Notices are for programs for administrators for snapd developers
A notice is identified by user id, type and key. A repeat of the same triple increments occurrences and replaces last-occurred and last-data. Clients read GET /v2/notices with types, keys, after and timeout; with a timeout the request waits for a match. Notices expire 7 days after their last occurrence.
A desktop helper can't read banners in a terminal; it needs to be told. A notice is snapd's record that something happened, identified by a user, a type and a key. The refresh-inhibit notice has no user, so it's public, and its key is always a dash. When the set of held snaps changes, snapd bumps its count and last occurrence. A client asks for some types after a point in time, with a timeout, and waits for a match. Notices expire a week after they last occur. You won't find a snap notices command; snap debug api /v2/notices lists what you may read.
06 Six types, and who records each one for administrators for snapd developers
Types and keys: change-update (change id), refresh-inhibit (-), snap-run-inhibit (instance name; added by snap run), interfaces-requests-prompt (prompt id), interfaces-requests-rule-update (rule id), and warning, for which no producer was found in this tree. Warnings are stored in their own list.
Six kinds of notice, each with one kind of thing behind it. change-update: every change, when it's created or its status moves, keyed by change id. refresh-inhibit: recorded when the set of snaps held back by running apps changes, keyed by a dash. snap-run-inhibit comes from the snap command, when you start an app whose snap is being refreshed, keyed by the snap. It's the only type a client can add, and snapd turns away other programs, as a courtesy, not a security check. Two belong to prompting: one per prompt, one per rule. Warning exists as a type, but nothing in this tree records it.
07 Who may read a notice for administrators for snapd developers
A notice with no user id is public; otherwise only that user and root see it, and only root may use users=all or user-id. A snap needs snap-refresh-observe for change-update, refresh-inhibit and snap-run-inhibit, and snap-interfaces-requests-control for the two prompting types. One uncovered type refuses the whole request; naming no types gives the ones its interfaces allow.
Notices can say which app you started and which files a program asked for. Who may read them? Two filters. First, people: a notice belongs to one user or to nobody, and nobody means public. You get the public ones and your own. Root gets the same, unless it asks for everyone's or one user's, and only root may ask. Second, snaps, on their own socket. The refresh and change types need snap-refresh-observe; the two prompting types need snap-interfaces-requests-control. Name one type your interfaces don't cover and the whole request is refused. Name none and you get what they allow. Nothing covers warning.
08 Where to go from here
Roads: refresh, prompting, the overlord, the interfaces that open snapd's API, the REST API, snap debug, and the administration district.
Warnings and notices are how the rest of snapd speaks up, so the roads lead to whoever is doing the talking. Refresh, for the app that was open when the update arrived. Prompting, in the desktop district, for two of the notice types. The overlord, for the changes behind change-update notices. The files, data and snapd family, for the interfaces that open parts of the API to a snap. The REST API deck, for how the daemon answers and who may call it. Snap debug, where you can add a test warning. And back to the administration district.
Read more
Commands
| Command | Effect |
|---|---|
snap warnings | list pending warnings and record when you looked |
snap warnings --all | also list acknowledged warnings |
snap warnings --verbose | add first-occurrence, acknowledged, repeats-after, expires-after |
snap warnings --abs-time | print times in RFC 3339 form |
snap okay | acknowledge the warnings that were pending when you last listed them |
Output: last-occurrence: and warning: | with the message, warnings separated by ---. With nothing to show: No warnings., or No further warnings. if you have listed warnings before. The banner is WARNING: There is 1 new warning. See 'snap warnings'. or WARNING: There are N new warnings. See 'snap warnings'. snap okay before any snap warnings fails with you must have looked at the warnings before acknowledging them. Try 'snap warnings'.
There is no published documentation page for these two commands.
Warning timings
| Setting | Default | Meaning |
|---|---|---|
| repeat | 24 hours | how long after the listing you acknowledged an acknowledged warning stays quiet |
| expire | 28 days | how long after its last occurrence a warning is kept |
A warning that was never acknowledged is pending. An acknowledged warning is pending again once its repeat time has passed, whether or not it occurred again, and stays so until it expires. The help texts of snap warnings and snap okay say it returns only if it occurs again; the code does not check that (confirmed by reading). The banner is not repeated for such a warning, because the banner looks at the newest occurrence, but snap warnings lists it again.
Three warnings are recorded with a repeat time of zero, so they are pending again right after snap okay: the NFS warning and the two prompting warnings in the table below (confirmed by reading).
The refresh warning is deleted and re-added each time an auto-refresh attempt recalculates which snaps are held, so snap okay holds it only until the next attempt, by default up to four times a day (confirmed by reading).
Examples of warnings
| Message begins | Recorded when |
|---|---|
snap "S" has bad plugs or slots: ... | a snap declares an unknown interface or an invalid plug or slot |
the snapd.apparmor service is disabled; snap applications will likely not start. | at start, when that service is disabled |
cannot refresh (S) due running apps; close running apps to continue refresh. | an automatic refresh is held and no snap has snap-refresh-observe connected; repeat 24 hours |
refresh of snap "S" is blocked as it is not supported for parallel instances: ... | a parallel instance fails the instance checks at refresh |
May not be able to remove user data under NFS mounted snap directory | removing a snap whose user data is on NFS; repeat zero |
"apparmor-prompting" feature flag enabled but no prompting client is present; ... | at start, when prompting is enabled and no client snap is installed; repeat zero; see Prompting |
cannot start prompting backend: ... | at start, when the prompting backend fails; repeat zero |
Other producers include a failed seeding and the use of experimental options that have graduated.
for administrators for snapd developers
Where warnings are kept
| Place | Content |
|---|---|
state, warnings | one entry per message: message, first-added, last-added, last-shown, expire-after, repeat-after |
| every API response | warning-count and warning-timestamp (the newest last-added among pending warnings) when warnings are pending |
~/.snap/warnings.json | the time this user last listed warnings, mode 0600; SNAPD_LAST_WARNING_TIMESTAMP_FILENAME overrides the path |
The client prints the banner when warning-timestamp is later than the time in ~/.snap/warnings.json. snap okay sets last-shown on the shared entries, so it acknowledges for every user.
for administrators for snapd developers
Notice types
| Type | Key | Recorded by | Interface a snap needs to read it |
|---|---|---|---|
change-update | change id | a change being created or changing status | snap-refresh-observe |
refresh-inhibit | - | auto-refresh, when the set of held snaps changes | snap-refresh-observe |
snap-run-inhibit | snap instance name | snap run, through the API | snap-refresh-observe |
interfaces-requests-prompt | prompt id | the prompting backend | snap-interfaces-requests-control |
interfaces-requests-rule-update | rule id | the prompting backend | snap-interfaces-requests-control |
warning | the warning message | no producer found in this tree | none |
for administrators for snapd developers
Notice fields
id, user-id, type, key, first-occurred, last-occurred, last-repeated, occurrences, last-data, repeat-after, expire-after. A key is at most 256 bytes. A notice expires 7 days after its last occurrence. State keys: notices, last-notice-id, last-notice-timestamp. last-repeated moves only when the repeat interval given with the new occurrence has passed; the source marks the handling of the stored repeat-after as unfinished, so do not build on its exact behaviour. Notice types can be served by their own backend; such notice ids have the form <prefix>-<id>.
for administrators for snapd developers
API
| Endpoint | Who |
|---|---|
GET /v2/warnings (select=pending or select=all) | any local user |
POST /v2/warnings ({"action":"okay","timestamp":...}) | authenticated user, root, or polkit io.snapcraft.snapd.manage |
GET /v2/notices, GET /v2/notices/{id} | any local user; a snap with the matching interface |
POST /v2/notices (action: add) | any local user, but only type snap-run-inhibit, with a valid instance name as key, and only when the caller is the snap or snapd program |
Query parameters of GET /v2/notices: types, keys, after, timeout, and for root user-id and users=all. A snap that gives no types gets the types its connected interfaces allow. snap debug api /v2/notices shows the notices you may read; there is no snap notices command.
| Message | When |
|---|---|
invalid select parameter: "X" | warnings |
unknown warning action "X" | warnings |
only admins may use the "user-id" filter, only admins may use the "users" filter | notices, caller is not root |
snap cannot access specified notice types | notices, a snap without the interface for every requested type |
cannot add notice with invalid type "X" | adding any type but snap-run-inhibit |
unexpected command of the calling process (can only record notices from the "snap" command) | adding from another program |
The check on the calling program is described in the source as not being a security check.
Further reading
- snapd REST API:
/v2/warnings,/v2/noticesand/v2/notices/{id}with their filters. - snap-refresh-observe interface: lets a snap read refresh-related notices.
- snap-interfaces-requests-control interface: lets a snap read prompting notices.
- Refresh awareness: what the user sees when a refresh is held; the visible side of
refresh-inhibit.
Roads from here
RUNNING SNAPS
- Refresh — the refresh that waits for a running app
- The overlord — the changes behind change-update notices
INTERFACE FAMILIES · every interface, grouped by what it touches
- "Interfaces: files, data and snapd's own API" — snap-refresh-observe and the other interfaces that open parts of the API
TOOLS
- snap debug: tools for looking inside — adding a test warning through the debug endpoint
ADMINISTRATION · managing a system of snaps
- Aliases — back to the administration district
DESKTOP · snaps in a user session
- AppArmor prompting — the prompts and rules behind two notice types
INSIDE SNAPD · the daemon itself
- The snapd REST API — how the daemon answers and who may call it