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

▶ Watch this deck — 8 scenes, ~6 min

01 A line after your command

WARNINGS AND NOTICES $ snap listName Version Rev Trackingphoto-editor 2.4 42 latest/stable WARNING: There is 1 new warning. See 'snap warnings'. snapdan automatic refresh of photo-editorwas held back: the app is open warninga message for people; the snap commandtells you there is one noticea record for programs; a desktop helperwaits for it and shows a notification this warning is the fallback: snapd writes it only when no snap is listening for the notice
A terminal runs snap list and, after the usual output, prints WARNING: There is 1 new warning. See 'snap warnings'. On the right snapd reports that an automatic refresh of photo-editor was held back because the app is open, and sends the event two ways: a warning, a message for people that the snap command announces, and a notice, a record for programs that a desktop helper waits for. The warning is written only when no snap is listening for the notice

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

TWO COMMANDS $ snap okayerror: you must have looked at the warnings beforeacknowledging them. Try 'snap warnings'. $ snap warningslast-occurrence: today at 09:12 UTCwarning: |cannot refresh (photo-editor) due running apps;close running apps to continue refresh. you last looked at:09:30remembered for your user $ snap okayokay, up to 09:30snapd a warning first recorded after 09:30 stays pending: you have not seen it $ snap warningsNo further warnings.snap warnings --all also lists acknowledged warnings · --verbose adds the dates
A terminal: snap okay first fails with you must have looked at the warnings before acknowledging them. Try 'snap warnings'. snap warnings then lists the photo-editor warning with its last occurrence, and the time you looked, 09:30, is remembered for your user. snap okay sends that time to snapd, which acknowledges what was pending up to 09:30, and snap warnings now says No further warnings. A warning first recorded after 09:30 stays pending

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

TIMELINE pendingrecorded againagainsame text: still one warning, its last-occurrence moves snap okayquietrepeat time: 24 h from your last snap warnings listed againlisted again whether or not it happened againthe help says it must happen again: confirmed bug expired28 days after it last happened: forgotten photo-editor's warning is deleted and re-added at each auto-refresh,so snap okay holds it only until the next attempt: a second confirmed bug
A timeline of one warning. It is recorded and pending; when the same message happens again it stays one warning and its last occurrence moves. After snap okay it is quiet for the repeat time, 24 hours by default, counted from the last snap warnings listing, and is then listed again whether or not it happened again, although the help says it must happen again. 28 days after it last happened it expires. The photo-editor refresh warning is deleted and re-added at each auto-refresh, so snap okay lasts only until the next one

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

WHERE IT IS KEPT snapd statewarnings: [ 1 warning ]message, first-added, last-added,last-shown, expire-after, repeat-afteralicebob warning-count: 1warning-timestamp: 09:12on every response while warnings are pending ~/.snap/warnings.json{"timestamp": "09:30"}09:12 is not later than 09:30: no banner ~/.snap/warnings.json(no file yet)banner: WARNING: There is 1 new warning. POST /v2/warnings{"action":"okay",...}last-shown set on theshared entry: quiet for bob too reading is open to every local user · snap okay needs root, polkit or a logged-in user
snapd state holds one warnings list for the system. Every response carries warning-count 1 and warning-timestamp 09:12 to the users alice and bob. Alice's ~/.snap/warnings.json says she last looked at 09:30, so she gets no banner; bob has no file yet, so he gets the banner. Alice's snap okay posts to /v2/warnings and sets last-shown on the shared entry, so it is quiet for bob too. Reading is open to every local user; acknowledging needs root, polkit or a logged-in user

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

NOTICES snapd type: refresh-inhibitkey: -user-id: (none: public)these three identify a notice 09:12 photo-editor heldoccurrences: 1first-occurred: 09:12last-occurred: 09:12 13:12 the held set changes213:12the same triple updates the same notice a clientGET /v2/notices?types=refresh-inhibit&after=...&timeout=...the request waits until a matching notice appears shows a notification a notice expires 7 days after its last occurrence · no snap notices command; snap debug api /v2/notices
snapd records a refresh-inhibit notice with key -, no user id and so public. The first occurrence at 09:12 sets occurrences 1; when the set of held snaps changes at 13:12 the same notice gets occurrences 2 and a new last-occurred. A client sends GET /v2/notices with types, after and timeout, the request waits for a match, and the client shows a notification. Notices expire 7 days after their last occurrence; there is no snap notices command

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

WHO RECORDS WHAT a change is created or changes statuschange-updatechange id auto-refresh: the held set changesrefresh-inhibitalways - snap run, while the snap refreshessnap-run-inhibitinstance namethe only type a client can add through the API the prompting backendinterfaces-requests-promptprompt idinterfaces-requests-rule-updaterule id warningthe messagedefined, but nothing in this tree records it;warnings are kept in their own listsome types can be served by their own backend; their notice ids look like <prefix>-<id>
Producers on the left, notice types on the right. A change being created or changing status records change-update, keyed by change id. Auto-refresh records refresh-inhibit when the held set changes, key always -. snap run records snap-run-inhibit, keyed by instance name, the only type a client can add. The prompting backend records interfaces-requests-prompt keyed by prompt id and interfaces-requests-rule-update keyed by rule id. The type warning is defined but nothing in this tree records it

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

READING snapd/v2/notices alice (uid 1000)public notices and her own rootthe same, or withusers=all · user-id=1000others: only admins may use the "users" filter a snap withsnap-refresh-observechange-update, refresh-inhibit,snap-run-inhibit a snap withsnap-interfaces-requests-controlinterfaces-requests-prompt,interfaces-requests-rule-update a snap with neither403: refusedso is any snap that asks fortypes=change-update,warning a snap that names no types gets the ones its interfaces allow · no interface covers warning
Five readers ask snapd's /v2/notices endpoint. alice gets public notices and her own. root gets the same by default and everyone's with users=all or one user's with user-id; anyone else is refused. A snap with snap-refresh-observe gets change-update, refresh-inhibit and snap-run-inhibit. A snap with snap-interfaces-requests-control gets the two prompting types. A snap with neither is refused with 403, as is a request that names one type its interfaces do not cover. No interface covers warning

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 Warnings and noticesRefreshthe app that was open Promptingtwo of the notice types The overlordchanges and their notices Files, data and snapdinterfaces that open the API The snapd REST APIwho may call the daemon snap debugadd a test warningAdministrationback to the district
Roads from Warnings and notices: Refresh, Prompting, the overlord, the files, data and snapd interfaces, the snapd REST API, snap debug, and back to the administration district

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

CommandEffect
snap warningslist pending warnings and record when you looked
snap warnings --allalso list acknowledged warnings
snap warnings --verboseadd first-occurrence, acknowledged, repeats-after, expires-after
snap warnings --abs-timeprint times in RFC 3339 form
snap okayacknowledge 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

SettingDefaultMeaning
repeat24 hourshow long after the listing you acknowledged an acknowledged warning stays quiet
expire28 dayshow 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 beginsRecorded 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 directoryremoving 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

PlaceContent
state, warningsone entry per message: message, first-added, last-added, last-shown, expire-after, repeat-after
every API responsewarning-count and warning-timestamp (the newest last-added among pending warnings) when warnings are pending
~/.snap/warnings.jsonthe 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

TypeKeyRecorded byInterface a snap needs to read it
change-updatechange ida change being created or changing statussnap-refresh-observe
refresh-inhibit-auto-refresh, when the set of held snaps changessnap-refresh-observe
snap-run-inhibitsnap instance namesnap run, through the APIsnap-refresh-observe
interfaces-requests-promptprompt idthe prompting backendsnap-interfaces-requests-control
interfaces-requests-rule-updaterule idthe prompting backendsnap-interfaces-requests-control
warningthe warning messageno producer found in this treenone

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

EndpointWho
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.

MessageWhen
invalid select parameter: "X"warnings
unknown warning action "X"warnings
only admins may use the "user-id" filter, only admins may use the "users" filternotices, caller is not root
snap cannot access specified notice typesnotices, 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

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

TOOLS

ADMINISTRATION · managing a system of snaps

  • Aliases — back to the administration district

DESKTOP · snaps in a user session

INSIDE SNAPD · the daemon itself