Package: certbot-dns-porkbun
Certbot DNS Porkbun PluginPlugin for certbot to obtain certificates using a DNS TXT record for Porkbun domainsTable of ContentsAboutInstallationPrerequirementsWith pip (recommend)From sourceSnapUsageLocal installationCredentials file or cli parametersDockerFAQThird party noticesLicenseAboutcertbot_dns_porkbunis a plugin forcertbot. 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.InstallationPrerequirementsIf 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 theusageYou need at least version3.7of Python installed. If you want to install the plugin with pip, then you must also have
pip installed beforehand.If you already havecertbotinstalled, make sure you have at least version1.18.0installed. When you installedcertbotas snap then you have to use thesnap installationof the plugin.You can check what version ofcertbotis installed with this command:certbot --versionIf 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 installcertbot_dns_porkbunwith pip:pip3 install certbot_dns_porkbunYou can also very easily update to the newest version:pip3 install certbot_dns_porkbun -UFrom sourceIf 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 .SnapIf you use thecertbotas snap package then you have to installcertbot_dns_porkbunas a snap too:snap install certbot-dns-porkbunNow connect thecertbotsnap installation with the plugin snap installation:sudo snap connect certbot:plugin certbot-dns-porkbunThe following command should now listdns-porkbunas an installed plugin:certbot pluginsUsageNote: 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 installationTo check if the plugin is installed and detected properly by certbot, you can use the following command:certbot pluginsThe resulting list should includedns-porkbunif everything went fine.Credentials file or cli parametersYou 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-fileporkbun.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-keyand--dns-porkbun-secretparameters 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.ExamplesBelow are some examples of how to use the plugin.Generate a certificate with a DNS-01 challenge for the domainexample.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 domainexample.orgusing 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 domainexample.comwithout 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
domainexample.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" \
  --stagingThe 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 domainexample.comandmydomain.com. The nameservers ofexample.comdomain are thePorkbun nameserver andmydomain.comis somewhere else.
In order to perform a DNS-01 challenge for the domainmydomain.com, we only need to add this_acme-challenge.mydomain.comto_acme-challenge.example.comCNAME 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 nowmydomain.cominstead of Porkbun'sexample.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 foundexample.comProkbun 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
theofficial documentationofcertbot.DockerYou 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 noticesAll modules used by this project are listed below:NameLicensecertbotApache 2.0setuptoolsMITpkb_clientMITdnspythonISCFurthermore, this readme file contains embeddings ofShields.io.LicenseMIT- Copyright (c) Marvin Heptner