Skip to content

pedronis/ifacetool

Repository files navigation

ifacetool provides tooling to work with snap interfaces, in
particular their policies as realized via snap-declarations.

One central feature of ifacetool is simulating what snapd will
do in terms of auto-connections for a group of snaps given snap
metadata and snap-declaration content.

Installation
=============

snap install --beta ifacetool

To operate ifacetool needs to retrieve information from the store, it
can do so using `snapcraft login` credentials. These can be made
available by:

 * snap connect ifacetool:password-manager-service OR
 * setting SNAPCRAFT_STORE_CREDENTIALS as per https://forum.snapcraft.io/t/snapcraft-authentication-options

Commands
=========

fetch
------

ifacetool fetch [--no-decls] [--no-meta] <snap-name>[@rev]...

fetch fetches snap metadata (at the given optional revisions) and snap
declaration content for a set of snaps.

For each snap it creates directories in the current working dir that
look like this:

<snap-name>/
  .snap.json
  revision
  snap.yaml
  plugs.json
  slots.json

snap.yaml is the snap metadata, while plugs/slots.json are the content
of the snap declaration interface rule stanzas.

These directories named after the snaps are the input for all other
commands, they also allow to apply tentative modifications to the
metadata or the snap-declaration rules to test.

For convenience <snap-name> can also be a path pointing to a .snap file or
directly to a local snap.yaml file. The file extension is used to detect this
usage. Snap metadata will then come from those local sources. The snap overall
still needs to exist in the store for its snap-id etc.

auto-connections
-----------------

ifacetool auto-connections [--classic] [--store <store-id>] [--model <brand>/<model>] [-i|--interface <interface>] [--candidates] <target-snap> [<context snap>...]

auto-connections using the input from the corresponding snap directories (see fetch) does two things:

* checks whether all snaps mentioned on the command line can be installed
  according to the rules
* simulates which auto-connections would be established when installing
  target-snap, assuming the presence of the listed context snaps, and prints
  the auto-connecting slot/plug pairs

The output report has two corresponding parts:

* installation report
* auto-connections reported with lines of the form:

  other-snap:plug < target-snap-slot
  other-snap:slot > target-snap-plug
  : target-snap-plug    for any plug that is still left unconnected

  this part can be filtered to only show connections and plugs for a given
  interface using -i|--interface <interface>

--candidates enables listing of candidates that were considered in the case were there was auto-connections but multiple candidates were in play or in the case that no auto-connection was established. For each candidate the result of checking whether it is allowed is displayed:

* `=> ok` allowed
* `=> ok slots-per-plug:*` allowed with `slots-per-plug: *`
* `=> <error>` not allowed with error
* `=> //` same error as the previous candidate

The notation `{<label>: <value>}` displays the label attribute usually
considered to allow auto-connection of interfaces like content, etc...

--store and --model values are used when processing on-store/on-model/on-brand
constraints in the rules.

--classic requests to simulate the behavior as on a classic system, the default is an Ubuntu Core system.

Changelog
==========

0.6
---

 * support --candidates for further debugging
 * based/for snapd 2.57.5+

0.5.1
------

 * switch to craft-store 2.3.0 to enable final snapcraft v7 exported auth

0.5
----

 * support filtering by interface with -i|--interface
 * support --classic

0.4
----

 * refined auto-connections output
 * fetch now supports taking metadata from local .snap/.yaml files
 * clarify license

Ideas
======
review-tools at tag for snap.yaml
can-install snap
can-connect snap-plug snap-slot
allow-installation slot-or-plug
allow-auto-connection plugs and/or slot
allow-connection plug and/or slot
explain snap-name
explain/lint snap-name
[attr matching code]