This page is intended for authors of third-party Certbot plugins. For many plugins, this page is purely informational and will not require any action (Method 1 at the bottom of the page). Other plugins may need to make changes to remain compatible with all Certbot versions (Method 2 at the bottom of the page).

Certbot v1.18.0 introduced a new way for third-party plugins to register themselves to Certbot. Notably, the certbot.interfaces abc-based classes Plugin, Authenticator and Installer. These are the recommended way to write and register Certbot plugins.

With the release of Certbot v1.19.0, the old zope-based classes (notably IPluginFactory, IPlugin, IAuthenticator, IInstaller) for registering plugins were deprecated and subsequently removed in v2.0.0.

With the release of Certbot v2.0.0, some users may have noticed that their Certbot would crash with an error:

$ certbot plugins
An unexpected error occurred:
AttributeError: module 'certbot.interfaces' has no attribute 'IAuthenticator'

This is due to having a plugin installed that still referenced the old zope-based classes.

We are re-adding empty versions these classes in Certbot v2.1.0 in order to fix compatibility with these third-party plugins. Any plugin which inherits from certbot.plugins.dns_common.DNSAuthenticator, depends on zope.interface and registers to the deprecated zope-based classes, should work again as of Certbot v2.1.0. (example of such a plugin).

These plugins should not require any changes once Certbot v2.1.0 is released.

Third-party plugins that wish to support both new (>= v2.0.0) and old (< v1.18.0) versions of Certbot need to register themselves to both the abc and zope-based plugin interfaces.

Since the abc-based classes do not exist prior to Certbot v1.18.0, there are a number of options to do this in a way that is compatible across all Certbot versions:

import zope.interface

from certbot import interfaces
from certbot.plugins import common
from certbot.plugins import dns_common

# Each method of registering a plugin here will work in every Certbot version,
# except for v2.0.0, but will work in v2.1.0 and later.
#
# All methods require "zope.interface" to be installed, declare this as a dependency
# of your plugin.


# Method 1, recommended for DNS authenticator plugins.
# abc-based registration for Certbot >= v1.18.0 by inheriting from .dns_common.DNSAuthenticator.
# zope-based registration for Certbot < v1.18.0.
#
# NO ACTION REQUIRED: Most DNS plugins are already written this way and will work as of v2.1.0.
@zope.interface.implementer(interfaces.IAuthenticator)
@zope.interface.provider(interfaces.IPluginFactory)
class DNSAuthenticator(dns_common.DNSAuthenticator):
    ...


# Method 2.
# Using custom decorators to perform both abc- and zope-based registration.
#
# ACTION REQUIRED: any plugin which does not inherit from `.dns_common.DNSAuthenticator` will need to
# make changes as shown here.
def register_authenticator(cls):
    try:
        interfaces.Authenticator.register(cls)  # or interfaces.Installer for installers
    except AttributeError:
        pass
    zope.interface.implementer(interfaces.IAuthenticator)(cls)  # or interfaces.IInstaller for installers 
    zope.interface.provider(interfaces.IPluginFactory)(cls)
    return cls 


# ... with or without inheriting from .common.Plugin
@register_authenticator
class Authenticator:
    ...