Certbot

From NixOS Wiki
Revision as of 19:08, 11 September 2022 by imported>Onny

Certbot is Electronic Frontier Foundation's ACME client, which is written in Python and provides conveniences like automatic web server configuration and a built-in webserver for the HTTP challenge. Certbot is recommended by Let's Encrypt.

Installation

Install certbot in your current environment and enable systemd-timer for automated renewal of certificates

 
/etc/nixos/configuration.nix
services.certbot.enable = true;

Usage

It is possible to use several different methods to generate certificates with different approaches to solve verification. Not all methods are covered here, for more information please consult the upstream documentation.

Generated certificates and keys by using the commands below will be stored as /etc/letsencrypt/live/example.org/fullchain.pem and /etc/letsencrypt/live/example.org/privkey.pem.

To make the keys readable by a third party user or application, you could set custom ACL permissions. In this example we grant the user maddy read permissions for the certificate folder:

# sudo setfacl -R -m u:maddy:rX /etc/letsencrypt/{live,archive}

Manual DNS challenge

The following command will generate a SSL certificate key pair for the domain example.org using the DNS authentication mechanism. After running this command, you'll get asked by the script to paste a specific key into your DNS records for example.org.

# certbot certonly --manual --preferred-challenges dns -d example.org --register-unsafely-without-email --agree-tos

DNS challenge using a plugin

Currently there are several certbot plugins already packaged. While the plugin usage should be similar for most of them, you should look up upstream documentation on how to use thim. In this example we're going to configure and use the plugin for the hosting provider INWX.

Note: Following example describes the usage of an experimental plugin which is still being reviewed as an open PR and might not be ready for production.
Warning: Do not use a plaintext password in production, this is for demonstration only

Installing certbot system wide with specific plugin included

 
/etc/nixos/configuration.nix
environment.etc."letsencrypt/inwx.cfg" = {
  text = ''
    dns_inwx_url = "https://api.domrobot.com/xmlrpc/"
    dns_inwx_username = "username"
    dns_inwx_password = "password"
    dns_inwx_shared_secret = "your_shared_secret"
  '';
  mode = "0600";
};

services.certbot = {
  enable = true;
  package = pkgs.certbot.withPlugins (ps: with ps; [ certbot-dns-inwx ]);
}

Shared secret must be set in the configuration but you only have to configure the value if you're using 2FA on INWX.

Manually generate certificates for example.org using the inwx-plugin

# certbot certonly -a dns-inwx -d example.org --register-unsafely-without-email --agree-tos

Now that a specific domain is configured to get automatically renewed using the plugin, the systemd-timer of the certbot module will automatically renew it.