Add external snap docs and clean up dev docs (#8356)

* Add external snap docs and clean up dev docs * Correctly refer to content identifiers * Expand plugin interface docs and add line breaks
2026-08-03 03:52:02 +02:00 · 2020-10-19 15:30:30 -07:00
parent a64e1f0129
commit 88386e8c82
2 changed files with 62 additions and 84 deletions
@@ -303,7 +303,7 @@ configuration checkpoints and rollback.
 .. _dev-plugin:
 Writing your own plugin
-~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------
 .. note:: The Certbot team is not currently accepting any new DNS plugins
    because we want to rethink our approach to the challenge and resolve some
@@ -338,17 +338,69 @@ it was not installed properly.
 Once you've finished your plugin and published it, you can have your
 users install it system-wide with `pip install`. Note that this will
 only work for users who have Certbot installed from OS packages or via
-pip. Users who run `certbot-auto` are currently unable to use third-party
+pip.
 plugins. It's technically possible to install third-party plugins into
 the virtualenv used by `certbot-auto`, but they will be wiped away when
 `certbot-auto` upgrades. If you'd like your plugin to be used alongside
 the Certbot snap, you will also have to publish your plugin as a snap.
 Certbot's DNS plugins and the README file in ``tools/snap/`` provide a
 starting reference for how to do this.
 .. _`setuptools entry points`:
    https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points
 Writing your own plugin snap
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 If you'd like your plugin to be used alongside the Certbot snap, you
 will also have to publish your plugin as a snap. Plugin snaps are
 regular confined snaps, but normally do not provide any "apps"
 themselves. Plugin snaps export loadable Python modules to the Certbot
 snap.
 When the Certbot snap runs, it will use its version of Python and prefer
 Python modules contained in its own snap over modules contained in
 external snaps. This means that your snap doesn't have to contain things
 like an extra copy of Python, Certbot, or their dependencies, but also
 that if you need a different version of a dependency than is already
 installed in the Certbot snap, the Certbot snap will have to be updated.
 Certbot plugin snaps expose their Python modules to the Certbot snap via a
 `snap content interface`_ where ``certbot-1`` is the value for the ``content``
 attribute. The Certbot snap only uses this to find the names of connected
 plugin snaps and it expects to find the Python modules to be loaded under
 ``lib/python3.8/site-packages/`` in the plugin snap. This location is the
 default when using the ``core20`` `base snap`_ and the `python snapcraft
 plugin`_.
 The Certbot snap also provides a separate content interface which
 you can use to get metadata about the Certbot snap using the ``content``
 identifier ``metadata-1``.
 The script used to generate the snapcraft.yaml files for our own externally
 snapped plugins can be found at
 https://github.com/certbot/certbot/blob/master/tools/snap/generate_dnsplugins_snapcraft.sh.
 Once you have created your own snap, if you have the snap file locally,
 it can be installed for use with Certbot by running:
 .. code-block:: shell
    snap install --classic certbot
    snap set certbot trust-plugin-with-root=ok
    snap install --dangerous your-snap-filename.snap
    sudo snap connect certbot:plugin your-snap-name
    sudo /snap/bin/certbot plugins
 If everything worked, the last command should list your plugin in the
 list of plugins found by Certbot. Once your snap is published to the
 snap store, it will be installable through the name of the snap on the
 snap store without the ``--dangerous`` flag. If you are also using
 Certbot's metadata interface, you can run ``sudo snap connect
 your-snap-name:your-plug-name-for-metadata certbot:certbot-metadata`` to
 connect your snap to it.
 .. _`snap content interface`:
    https://snapcraft.io/docs/content-interface
 .. _`base snap`:
    https://snapcraft.io/docs/base-snaps
 .. _`python snapcraft plugin`:
    https://snapcraft.io/docs/python-plugin
 .. _coding-style:
 Coding style
@@ -1,58 +1,6 @@
-# Certbot Plugin Snaps
+# Certbot Snaps
-This is a proof of concept of how a Certbot snap might support plugin snaps
+## Local Testing and Development
 that add functionality to Certbot using its existing plugin API.
 ## Architecture
 This is a description of how Certbot plugin functionality is exposed via snaps.
 For information on Certbot's plugin architecture itself, see the [Certbot
 documentation on
 plugins](https://certbot.eff.org/docs/contributing.html#plugin-architecture).
 The Certbot snap itself is a classic snap. Plugin snaps are regular confined
 snaps, but normally do not provide any "apps" themselves. Plugin snaps export
 loadable Python modules to the Certbot snap via a snap content interface.
 Certbot itself accepts a `CERTBOT_PLUGIN_PATH` environment variable. This
 support is currently patched but this is intended to be upstreamed. The
 variable, if set, should contain a `:`-separated list of paths to add to
 Certbot's plugin search path.
 The Certbot snap runs Certbot via a wrapper which examines its list of
 connected interfaces, sets `CERTBOT_PLUGIN_PATH` accordingly, and then `exec`s
 Certbot itself.
 ## Use (Production)
 _Note: this production use example assumes that these snaps are available in
 stable channels in the Snap Store, which they aren't yet. See below for
 development instructions._
 To use a Certbot plugin snap, install both the plugin snap and the Certbot snap
 as usual. Plugin snaps are confined as normal; the Certbot snap is a classic
 snap and thus needs `--classic` during installation. For example:
    snap install --classic certbot
    snap set certbot trust-plugin-with-root=ok
    snap install certbot-dns-dnsimple
 Then connect the plugin snap to the main certbot snap as follows. Note that
 this connection allows the plugin snap code to run inside the certbot process,
 which has access to your host system. Only perform this step if you trust the
 plugin author to have "root" on your system.
    sudo snap connect certbot:plugin certbot-dns-dnsimple
 Now certbot will automatically load and use the plugin when it is run. To check
 that this has worked, `certbot plugins` should list the plugin.
 You can now operate the plugin as normal.
 ## Use (Testing and Development)
 To try this out, you'll need to build the snaps (a patched Certbot snap and a
 plugin snap) manually.
 ### Initial VM Set Up
@@ -95,25 +43,3 @@ The instructions below clean up the build environment so it can reliably be used
 5. `rm certbot-dns-dnsimple_*_amd64.snap`
 6. `snapcraft clean --use-lxd`
 7. `cd ..`
 ## Publishing Permissions
 There are security implications to permitting anyone to publish, without
 review, a plugin into the Snap Store which will then run in Certbot's classic
 snap context, with full access to the host system.
 At a minimum, it is clear that this should happen only with the user's explicit
 opt-in action.
 As implemented, Certbot will only load plugins connected via the snap interface
 mechanism, so permission is effectively delegated to what interface connections
 the snap infrastucture will permit.
 We have approval from the snap team to use this design as long as we make it
 explicit what a user is agreeing to when they connect a plugin to the
 Certbot snap. That work was completed in
 https://github.com/certbot/certbot/issues/8013.
 ## Outstanding issues
 [Outstanding items relating to plugin support in Certbot snaps are tracked on GitHub](https://github.com/certbot/certbot/issues?q=is%3Aopen+is%3Aissue+label%3A%22area%3A+snaps%22).