The snap-declaration assertion defines several important properties of a snap, including its snap-id, the official name, the publisher. However, it’s mainly used to control what plugs or slots a snap is allowed to use, and if a snap is allowed to use a plug/slot, what other slots/plugs should connect to that plug/slot on this snap.
This assertion is downloaded with the snap when installing a snap from a store and includes details on the actions to take when performing the installation.
snap-declaration assertions for all installed snaps can be seen by running
snap known snap-declaration.
Snap-declaration assertion fields
The format is as follows:
type: snap-declaration authority-id: <authority account id> revision: <int> series: <series this assertion was created for> snap-id: <string> snap-name: <string> publisher-id: <the owner of this snap-id space> timestamp: <UTC datetime> refresh-control: <list of snap-ids that have gated updates> - [snap-id1] - [snap-id2] - ... aliases: <optional listing of explicit aliases granted to this snap> - name: [alias1] target: [target-command1] - ... plugs: <map from [interface] to plug side rules> [interface]: <optional plug side rules for [interface]> allow-installation: <true|false> deny-installation: <true|false> allow-connection: <true|false> deny-connection: <true|false> allow-auto-connection: <true|false> deny-auto-connection: <true|false> ... slots: <map from [interface] to slot side rules> [interface]: <optional slot side rules for [interface]> ... <similar options as rule entries for plugs> sign-key-sha3-384: <key id> # Encoded key id of signing key <signature> # Encoded signature
The index is the tuple <
snap-id is a key with the same format as the account ids.
This assertion gives control on several aspects of the snap behaviour to the the authority:
refresh-controlgives a list of snaps that are gated when the one specified by
snap-idis installed, so they are not automatically refreshed until they are “validated”. Validation is performed by using validation asserts, which specify the revision of the gated snap that should be installed if the gating snap has been installed.
aliasesgives a list of the explict aliases that we want to automatically enable when installing the snap. Aliases provide short names for applications contained in the snap, so we do not need to use the full command name
slotsdefine flags per interface. This lets define restrictions on how the snap plugs/slots used by the snap are handled. For instance, we can allow or deny connections with
deny-auto-connectionwe let snapd know if it should automatically connect plugs/slots on snap installation.
See Connection management (below) for more details on these restrictions, and see snap-declaration store scoping for more information on how auto-connections can be linked to a brand store.
See Assertion format for more details on fields common to most assertions.
The overall structure of the snap-declaration has two top-level keys, plugs and slots, which affect the plugs and slots of the snap respectively. Beneath these keys are the names of interfaces, and for each interface key is an map which has 6 possible keys:
Each of these keys can either have a static value of true/false in the assertion or can be a more complex object/list which then is “evaluated” by snapd on a device to determine the actual value, be it true or false. If there is no such a rule in the snap-declaration for an interface plug/slot that a snap is using, then the base-declaration from inside snapd is used to populate rules, more on that below.
deny-* variant of keys are almost never used in snap-declarations and are instead mainly used in the base-declaration inside snapd to express more complex default behaviours, for example some interfaces should auto-connect only on classic but not on Core or vice versa, and having
deny-* keys makes this simpler/easier to express, but when granting snap-declarations for brand store users,
allow-* keys are almost always used so this document only covers allow-* keys below.
The allow-installation key is the first key that is evaluated when the snap is being installed. If this evaluates to false, the snap cannot be installed if the interface plug or slot for which
allow-installation evaluated to false exists in the snap.
allow-installation is not evaluated for interfaces which do not exist in the snap and thus do not affect installation. An example would be the snapd-control interface, which has in the base-declaration the static
allow-installation: false rule for plugs:
snapd-control: allow-installation: false deny-auto-connection: true
If a snap does not plug snapd-control then this rule does not apply, but if the snap does declare a snapd-control plug and there are no other rules for this snap about snapd-control then snap installation will fail. To allow installation of such a snap, the snap-declaration must be edited such that allow-installation evaluates to true.
Snap interfaces which have allow-installation set to false for their plugs in the base-declaration are said to be “super-privileged” meaning they cannot be used at all without a snap-declaration assertion.
allow-connection key is the next key to be evaluated, after the snap is allowed to be installed.
This key will control whether a connection is permitted at all and usually is used to ensure that only “compatible” plugs and slots are connected to each other. A great example is the content interface, where the following (abbreviated) rule from the base-declaration is used to ensure that a candidate plug and slot content interface have matching content attribute values.
slots: content: allow-connection: plug-attributes: content: $SLOT(content)
This can be read as
allow-connection evaluating to true only when the plug has an attribute “content” and the value of the plug attribute is the same as the slot attribute “content” value. That is to say these plug and slots are compatible because content does not match for the plug and slot:
slots: foo-content: interface: content content: specific-files plugs: foo-content: interface: content content: specific-files
While the following plug and slots are not compatible:
slots: foo-content: interface: content content: other-files plugs: foo-content: interface: content content: specific-files
allow-auto-connection key is the final key to consider when snapd is considering automatic connection of interface plugs and slots.
If this key evaluates to true, then this plug/slot combination is considered a valid candidate for automatic connection. This is the most common key used when granting snap-declaration assertions since many interfaces are not super-privileged, so they do not need
allow-installation set in the assertion and they also do not have any
allow-connection rules in the base-declaration, so the only thing that needs to be setup is
Example snap-declaration assertion
The following is an example
snap-declaration assertion from the modem-manager snap:
type: snap-declaration format: 1 authority-id: canonical revision: 9 series: 16 snap-id: KtwxgRlwCAVKFw92BUdt1WloH1Va3QPo plugs: modem-manager: allow-auto-connection: true publisher-id: canonical slots: modem-manager: allow-connection: true snap-name: modem-manager timestamp: 2016-10-25T15:35:43.646671Z sign-key-sha3-384: BWDEoaqyr25nF5SNCvEv2v7QnM9QsfCc0PBMYD_i2NGSQ32EF2d4D0hqUel3m8ul AcLBUgQAAQoABgUCWA970AAABF0QAMw+M28Rrm0m/3Gm5PYesQcQWKhGwmN0j3qfYG2LsSRiM0TU j7K7hvCPc9v0P4sL6Ewv/CEZAkVxPYd9eUMqiyKYBRMp9QeiL7KW3RWdHok0FUN7ia7ZxcPlpKoM uwV7qYDKktw/TJWX9bK15W6DnghlKtU464u7IqcHVmH2YzPBbcpJBuIhLHgYC2K5oj3ZvIjHqnV/ ELRDtwW3UTTkonycc2IUTCd10qu590z7DWzORWdts9ZARBJXfc3lohYkSd1v4wDYZHRO9RF/bJix LBALp3kUR6X3OnLLJQAjVhIEY70B/5kLApuhrOpmi84Uawf+Uh91Ze++Bwatrw6QGw9cwkFgoLaj 9neiV4y6HvQh7gsgXap1XOZeOeWVMISgqaXGER78Lx6nc6/Loz8Yhjp4p9xi2Ia4j7fLpXMkWIU4 aoGudS1hQBsbeiNQvG6I+DraMN7xypMbOkGKwqNJ7prU63D3BmZiFl17ajT3SfffEO1/H6qqRVFS A8X9HXVGPmI2TGst36cBgjdd9f+jj9ZqISKs8jdHfPKEpOBdH4wo1rodXO1y/GxZeP2Z710qep4t 8ynSRPi0l3boyM15D3IfnXMjLzUoace9vC6gltOHpW8GFPZvheQwknRvtfwRpZM2VsgaSw6cuz3+ 7K/m9/Ff04A86/gvRlzduXIjEvKJ