upstream/certbot
1
0
Fork 0
mirror of https://github.com/certbot/certbot.git synced 2026-06-04 14:26:10 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

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

Browse source 
* Add external snap docs and clean up dev docs

* Correctly refer to content identifiers

* Expand plugin interface docs and add line breaks
This commit is contained in:
Brad Warren 2020-10-19 15:30:30 -07:00 committed by GitHub
parent a64e1f0129
commit 88386e8c82
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 62 additions and 84 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

68
certbot/docs/contributing.rst
View file

@ -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

78
tools/snap/README.md
View file

@ -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).