From 88386e8c826921caf02cb9da468ea0e00c800d97 Mon Sep 17 00:00:00 2001 From: Brad Warren Date: Mon, 19 Oct 2020 15:30:30 -0700 Subject: [PATCH] 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 --- certbot/docs/contributing.rst | 68 ++++++++++++++++++++++++++---- tools/snap/README.md | 78 +---------------------------------- 2 files changed, 62 insertions(+), 84 deletions(-) diff --git a/certbot/docs/contributing.rst b/certbot/docs/contributing.rst index b3e2e9bae..95424630a 100644 --- a/certbot/docs/contributing.rst +++ b/certbot/docs/contributing.rst @@ -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 -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. +pip. .. _`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 diff --git a/tools/snap/README.md b/tools/snap/README.md index ef3bc1225..71babf1a7 100644 --- a/tools/snap/README.md +++ b/tools/snap/README.md @@ -1,58 +1,6 @@ -# Certbot Plugin Snaps +# Certbot Snaps -This is a proof of concept of how a Certbot snap might support plugin snaps -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. +## Local Testing and Development ### 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).