Skip to main content

Plugin for certbot to obtain certificates using a DNS TXT record for Porkbun domains

Project description

Certbot DNS Porkbun Plugin

Plugin for certbot to obtain certificates using a DNS TXT record for Porkbun domains


PyPI - Python Version GitHub

PyPI PyPI - Downloads GitHub Workflow Status

Docker Image Version (latest semver) Docker Pulls Docker Image Size (tag) GitHub Workflow Status

certbot-dns-porkbun


Table of Contents

  1. About
  2. Installation
    1. Prerequirements
    2. With pip (recommend)
    3. From source
    4. Snap
  3. Usage
    1. Local installation
    2. Credentials file or cli parameters
    3. Docker
  4. FAQ
  5. Third party notices
  6. License

About

certbot_dns_porkbun is a plugin for certbot. It handles the TXT record for the DNS-01 challenge for Porkbun domains. The plugin takes care of the creation and deletion of the TXT record using the Porkbun API.

Installation

Prerequirements

If you want to use the docker image, then you don't need any requirements other than a working docker installation and can proceed directly with the usage

You need at least version 3.7 of Python installed. If you want to install the plugin with pip, then you must also have pip installed beforehand.

If you already have certbot installed, make sure you have at least version 1.18.0 installed. When you installed certbot as snap then you have to use the snap installation of the plugin.

You can check what version of certbot is installed with this command:

certbot --version

If you don't have certbot installed yet, then the PyPI version of certbot will be installed automatically during the installation.

Note: If you want to run certbot with root privileges, then you need to install the plugin as root too. Otherwise, certbot cannot find the plugin.

With pip (recommend)

Use the following command to install certbot_dns_porkbun with pip:

pip3 install certbot_dns_porkbun

You can also very easily update to the newest version:

pip3 install certbot_dns_porkbun -U

From source

If you prefer to install the plugin from the source code:

git clone https://github.com/infinityofspace/certbot_dns_porkbun.git
cd certbot_dns_porkbun
pip3 install .

Snap

If you use the certbot as snap package then you have to install certbot_dns_porkbun as a snap too:

snap install certbot-dns-porkbun

Now connect the certbot snap installation with the plugin snap installation:

sudo snap connect certbot:plugin certbot-dns-porkbun

The following command should now list dns-porkbun as an installed plugin:

certbot plugins

Usage

Note: By default, Porkbun domains cannot be controlled through the API. This will cause an error when you generate certificates. Ensure that you have enabled API Access in your domain's settings to avoid this. If you haven't already, be sure to also delete the (default) parked domain ALIAS records, as not doing so may cause errors.

Local installation

To check if the plugin is installed and detected properly by certbot, you can use the following command:

certbot plugins

The resulting list should include dns-porkbun if everything went fine.

Credentials file or cli parameters

You can either use cli parameters to pass authentication information to certbot:

...
--dns-porkbun-key <your-porkbun-api-key> \
--dns-porkbun-secret <your-porkbun-api-secret>

Or to prevent your credentials from showing up in your bash history, you can also create a credentials-file porkbun.ini (the name does not matter) with the following content:

dns_porkbun_key=<your-porkbun-api-key>
dns_porkbun_secret=<your-porkbun-api-secret>

And then instead of using the --dns-porkbun-key and --dns-porkbun-secret parameters above you can use

...
--dns-porkbun-credentials </path/to/your/porkbun.ini>

You can also mix these usages, though the cli parameters always take precedence over the ini file.

Examples

Below are some examples of how to use the plugin.


Generate a certificate with a DNS-01 challenge for the domain example.org:

certbot certonly \
  --non-interactive \
  --agree-tos \
  --email <your-email-address> \
  --preferred-challenges dns \
  --authenticator dns-porkbun \
  --dns-porkbun-key <your-porkbun-api-key> \
  --dns-porkbun-secret <your-porkbun-api-secret> \
  --dns-porkbun-propagation-seconds 60 \
  -d "example.com"

Generate a wildcard certificate with a DNS-01 challenge for all subdomains *.example.com (Note: the wildcard certificate does not contain the root domain itself):

certbot certonly \
  --non-interactive \
  --agree-tos \
  --email <your-email-address> \
  --preferred-challenges dns \
  --authenticator dns-porkbun \
  --dns-porkbun-key <your-porkbun-api-key> \
  --dns-porkbun-secret <your-porkbun-api-secret> \
  --dns-porkbun-propagation-seconds 60 \
  -d "*.example.com"

Generate a certificate with a DNS-01 challenge for the domain example.org using a credentials ini file:

certbot certonly \
  --non-interactive \
  --agree-tos \
  --email <your-email-address> \
  --preferred-challenges dns \
  --authenticator dns-porkbun \
  --dns-porkbun-credentials </path/to/your/porkbun.ini> \
  --dns-porkbun-propagation-seconds 60 \
  -d "example.com"

Generate a certificate with a DNS-01 challenge for the domain example.com without an account (i.e. without an email address):

certbot certonly \
  --non-interactive \
  --agree-tos \
  --register-unsafely-without-email \
  --preferred-challenges dns \
  --authenticator dns-porkbun \
  --dns-porkbun-key <your-porkbun-api-key> \
  --dns-porkbun-secret <your-porkbun-api-secret> \
  --dns-porkbun-propagation-seconds 60 \
  -d "example.com"

Generate a staging certificate (i.e. temporary testing certificate) with a DNS-01 challenge for the domain example.com:

certbot certonly \
  --non-interactive \
  --agree-tos \
  --email <your-email-address> \
  --preferred-challenges dns \
  --authenticator dns-porkbun \
  --dns-porkbun-key <your-porkbun-api-key> \
  --dns-porkbun-secret <your-porkbun-api-secret> \
  --dns-porkbun-propagation-seconds 60 \
  -d "example.com" \
  --staging

The DNS-01 challenge specification allows to forward the challenge to another domain by CNAME entries and thus to perform the validation from another domain.

For example, we have the domain example.com and mydomain.com. The nameservers of example.com domain are the
Porkbun nameserver and mydomain.com is somewhere else. In order to perform a DNS-01 challenge for the domain mydomain.com, we only need to add this _acme-challenge.mydomain.com to _acme-challenge.example.com CNAME entry in advance:

_acme-challenge.mydomain.com. 600 IN CNAME _acme-challenge.example.com.

Then we can use our Porkbun domain for the actual DNS-01 challenge. The procedure is identical as if we perform a DNS-01 challenge for a Porkbun domain, except that the domain name for which we perform the challenge is now mydomain.com instead of Porkbun's example.com.

certbot certonly \
  --non-interactive \
  --agree-tos \
  --email <your-email-address> \
  --preferred-challenges dns \
  --authenticator dns-porkbun \
  --dns-porkbun-key <your-porkbun-api-key> \
  --dns-porkbun-secret <your-porkbun-api-secret> \
  --dns-porkbun-propagation-seconds 60 \
  -d "mydomain.com"

What happens in the background is that the CNAME entry is followed to the end and then a TXT entry is created with the form _acme-challenge.example.com. for the found example.com Prokbun domain. Thus, during the challenge of this example, the DNS would look like this:

_acme-challenge.mydomain.com. 600 IN CNAME _acme-challenge.example.com.
_acme-challenge.example.com. 60 TXT "a8sdhb09a7sbd08ashd90ashd90a8hsa9usd"

You can find al list of all available certbot cli options in the official documentation of certbot.

Docker

You can simply start a new container and use the same certbot commands to obtain a new certificate:

docker run -v "/etc/letsencrypt:/etc/letsencrypt" -v "/var/log/letsencrypt:/var/log/letsencrypt" infinityofspace/certbot_dns_porkbun:latest \
   certonly \
     --non-interactive \
     --agree-tos \
     --email <your-email-address> \
     --preferred-challenges dns \
     --authenticator dns-porkbun \
     --dns-porkbun-key <your-porkbun-api-key> \
     --dns-porkbun-secret <your-porkbun-api-secret> \
     --dns-porkbun-propagation-seconds 60 \
     -d "example.com"

Or you can use a credentials file:

docker run -v "/etc/letsencrypt:/etc/letsencrypt" -v "/var/log/letsencrypt:/var/log/letsencrypt" -v "/absolute/path/to/your/porkbun.ini:/conf/porkbun.ini" infinityofspace/certbot_dns_porkbun:latest \
   certonly \
     --non-interactive \
     --agree-tos \
     --email <your-email-address> \
     --preferred-challenges dns \
     --authenticator dns-porkbun \
     --dns-porkbun-credentials /conf/porkbun.ini \
     --dns-porkbun-propagation-seconds 60 \
     -d "example.com"

Third party notices

All modules used by this project are listed below:

Name License
certbot Apache 2.0
setuptools MIT
pkb_client MIT
dnspython ISC
tldextract BSD 3-Clause

Furthermore, this readme file contains embeddings of Shields.io.

License

MIT - Copyright (c) Marvin Heptner

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

certbot_dns_porkbun-0.9.tar.gz (6.6 kB view details)

Uploaded Source

Built Distribution

certbot_dns_porkbun-0.9-py3-none-any.whl (7.2 kB view details)

Uploaded Python 3

File details

Details for the file certbot_dns_porkbun-0.9.tar.gz.

File metadata

  • Download URL: certbot_dns_porkbun-0.9.tar.gz
  • Upload date:
  • Size: 6.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for certbot_dns_porkbun-0.9.tar.gz
Algorithm Hash digest
SHA256 623d4a3bb6e9c5039a82eed01908b133ccabdf6cae5cd1ed129dfb115847065f
MD5 56f7a1ea23af141155287e5fea78f494
BLAKE2b-256 0daeb96e653bea82028e62e6dc2fe9b769d818dbaa6f9dddcb518e56bf5c1b78

See more details on using hashes here.

File details

Details for the file certbot_dns_porkbun-0.9-py3-none-any.whl.

File metadata

File hashes

Hashes for certbot_dns_porkbun-0.9-py3-none-any.whl
Algorithm Hash digest
SHA256 2ac69c67633701d15f681aaecd386f1776d55ed3fef0e37b4db65995d317094b
MD5 c8df3b9daae785646a7edfbfbd6e01ce
BLAKE2b-256 dd928ba2c4d940ca3e7f5f0a1c1c6bbc0e13bd91c3e165198828c36e63fa5db4

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page