Interface management

doc
21

This does not seem right. Which is the previous output? Things do not match with the previous output. Perhaps something was moved round?

1 Like
22

You’re absolutely right! Thanks for mentioning this. snap connections has a different output, but we didn’t change the text to explain this. I’ll fix it now.

1 Like
23

Wording taken by documentation to refer to interface is used in somehow inconsistent way which makes the learning curve steeper yet raises irritations while reading stuff.
Please start with picture provided in Interface Management documentation, by which interface is explained illustratively. According to picture and surrounding text an interface is the connection between plug and slot, cit. " An interface consists of a connection between a slot and a plug .".

Most will guest interface connects snap A with snap B, in some edge cases interface’s plug and slot connected by one single interface might be provided by one single snap - if such case is supported at all - please put this point aside for this discussion.

So, if to go back to stuff learned from mentioned picture every interface has plug-end and slot-end. To be consequent all documentation and snap CLI should account for this property. This is however not the case. At several locations documentation uses the phrase “connect to interface”. Hence in end-result it expands to “connect to connection between snap A and snap B”. I don’t believe this is the goal. I see only one possible use-case for connecting to connection which is logging. However I don’t believe several locations in documentation with phrase “connect to interface” be used really mean debugging, cause those locations in documentation address snap basics (logging is no part of basics).
By the same argumentation documentation article with all known interfaces listed should specify also both ends for each interface: plug and slot. I know this is not possible however one can see which weird conclusion might raise from present documentation form.
CLI needs also to adhere to consistent wording too, e.g. see output of snap interface <app-snap-name>.

It can well be documentation authors mean “connect to snap” when “connect to interface” is used. This way words snap and interface would be have interchangeably by arranged conventions. This also doesn’t help documentation to not be weird cause latter one doesn’t mention conventions.

Existing inconsistency makes hard further documentation reading as with each next section matters escalate. It makes also for reader harder to draw own conclusions, because documentation can’t deliver this way confirmation for reader’s conclusion truthfulness.
Please feel-in in reader’s position, if they are snap newbies they can’t rely on own snap knowledge. While reading they can easily take different point of stand and view than Author’s one.
For instance when encountering an explanation where “connect to interface” is used they may wonder if function provider snap is connecting to consumer’s plug or vice-verse if a snap consuming some common resource is connecting to provider snap’s slot, this makes learning harder.

24

Hello! Thanks so much for taking the time to leave this feedback. And you’re right about the way we mix interface terminology - we can see how this can be confusing.

We’re going to give this problem some thought and try to improve our use of the term - first here in the documentation where we’ll try to make its scope clearer and less confusing.

25

Running this on Ubuntu 22.04 so that might make a difference but a couple things.

If you mention running “snap interface”, might be worth mentioning “snap interface --all”.

Also, “snap help interface” mentions the “–attrs” option to allegedly “show interface attributes”, but using it doesn’t seem to add anything to the output. What should I expect to see in the way of attributes?

26

try snap interface content with and without --attrs.

with the option it should show the paths where the interface provides the content (i guess system-files and serial-port are some others where you could see attributes) … interfaces with attributes are simply relatively rare …

1 Like
27

Ah, quite so, thanks.

28

I might be tempted to add a couple more lines to this page. First, it could be worth adding the variations:

$ snap connections

$ snap connections --all

And perhaps that both connect and disconnect take the “–no-wait” option. None of that is critical, but given that all of that would add only a few extra lines, maybe it’s worth throwing in for completeness.

29

Thanks for the suggestions. I’ve updated the doc to include them all.

30

I don’t care for this definition, “An interface consists of a connection between a slot and a plug.” I like to see this as that an interface is an abstraction that defines a certain level of access to resources; a connection is a specific instance of a plug/interface/slot combination. It’s like object-oriented classes – you can have a single class definition, but numerous instantiations of that class. Does that make sense?

31

Thanks for the suggestion. I’ve tweaked the text slightly to hopefully better reflect your ideas. It’s aimed at a high level for most ordinary users, who will need to know the ideas behind the plug and slot terminology we use.

32

I’d like to suggest that this page needs some screenshots to the GUI method to configure permissions, as well. My goal is to have one single page that I can give to people who are asking questions about snap permissions, slots, interfaces, etc, that shows both the friendly path that we expect most people will use as well as the detailed cli path that is available. As far as I know, there’s no single page that has both.

This blog post has a screenshot.

It also has a code block showing listing of permissions but not how to grant or revoke those permissions.

This page has the listing, granting, revoking, etc down well but doesn’t tell GUI users how to get the similar results by clicking on things.

Thanks

33

Thanks for bringing this up. It’s something I’ve been thinking about too, especially with the maturity of Software application for interface management. I do have it on my todo list, but I’ll make sure I create something over the next 2 week cycle.

34

The example “snap interface audio-playback” shows the slot name as “core”, but these days, it appears to be “snapd”.

35

While this page shows how to use “snap interface” to examine a specific interface, it doesn’t show the more general usage of “snap interface” and “snap interface --all”.

Also, that command supports the “–attrs” option, but the only interface I can see for which that makes any difference is “content”. Are there others?

36

system-files and personal-files should also be in that category…

1 Like
37

The “snap interfaces” command is deprecated in favour of “snap connections.” See:

$ snap interfaces --help

38

AFAIK snap connections still doesn’t list unconnected but available interfaces…

39

Thanks - that’s a really good point. I’ll update the text to say --all lists interfaces with either unconnected plugs or unconnected slots (but not both). I wish there was better output for this.

40

There’s all sorts of variations I wish were available, like a way to ask, “Which plugs and slots are used by a particular snap?” That sort of output would seem to be appropriate for the “snap info” command.

1 Like