certbot-dns-porkbun 0.2.1

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

Certbot DNS Porkbun Plugin

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

---

---

Table of Contents

1. About
2. Installation
   1. Prerequirements
   2. With pip (recommend)
   3. From source
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.6 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.1.0 installed.

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 .

Usage

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

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
requests	Apache 2.0
zope.interface	ZPL-2.1
setuptools	MIT
pkb_client	MIT
tldextract	BSD 3-Clause

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

License

MIT - Copyright (c) Marvin Heptner