Certbot: Difference between revisions

Latest revision as of 07:48, 7 October 2024

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.

Note: It is recommended to use the the ACME service module, available through security.acme, instead of certbot. Please consult the ACME page on how to use it.

Installation

Note: Following example describes the usage of an experimental module which is still being reviewed as an open PR and might not be ready for production.

Install certbot application and enable systemd-timer for automated renewal of certificates

/etc/nixos/configuration.nix

services.certbot = {
  enable = true;
  agreeTerms = true;
};

Usage

It is possible to use several different methods to generate and configure certificates. Verification is done manually, via web servers or DNS records. 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, readable by the acme group.

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 them. In this example we're going to configure and use the plugin for the hosting provider INWX.

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;
  agreeTerms = 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 configure and 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 renewed using the plugin, the systemd-timer of the certbot module will automatically renew it after expiration.

@@ Line 1: / Line 1: @@
 [https://github.com/certbot/certbot Certbot] is [https://www.eff.org/ 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 [https://letsencrypt.org/ Let's Encrypt].
+{{Note|It is recommended to use the the ACME service module, available through <code>security.acme</code>, instead of ''certbot''. Please consult the [[ACME | ACME page]] on how to use it.}}
 == Installation ==
-Install ''certbot'' in your current environment
+{{Note|Following example describes the usage of an experimental module which is still being reviewed as an open PR and might not be ready for production.}}
-<syntaxhighlight lang="console">
+Install ''certbot'' application and enable ''systemd-timer'' for automated renewal of certificates
-# nix-env -iA nixos.certbot
+{{file|/etc/nixos/configuration.nix|nix|<nowiki>
-</syntaxhighlight>
+services.certbot = {
+  enable = true;
+  agreeTerms = true;
+};
+</nowiki>}}
+== Usage ==
-== Usage ==
+It is possible to use several different methods to generate and configure certificates. Verification is done manually, via web servers or DNS records. Not all methods are covered here, for more information please consult the [https://eff-certbot.readthedocs.io/en/stable/ upstream documentation].
+Generated certificates and keys by using the commands below will be stored as <code>/etc/letsencrypt/live/example.org/fullchain.pem</code> and <code>/etc/letsencrypt/live/example.org/privkey.pem</code>, readable by the <code>acme</code> group.
 === Manual DNS challenge ===
@@ Line 18: / Line 27: @@
 </syntaxhighlight>
-If everthing went well you'll have the certificate and key file stored as <code>/etc/letsencrypt/live/example.org/fullchain.pem</code> and <code>/etc/letsencrypt/live/example.org/privkey.pem</code>
+=== DNS challenge using a plugin ===
+Currently there are several ''certbot'' plugins [https://search.nixos.org/packages?channel=24.05&from=0&size=50&sort=relevance&type=packages&query=certbot-dns already packaged]. While the plugin usage should be similar for most of them, you should look up upstream documentation on how to use them. In this example we're going to configure and use [https://github.com/oGGy990/certbot-dns-inwx the plugin] for the hosting provider [https://www.inwx.com/en INWX].
+{{warning|1=Do not use a plaintext password in production, this is for demonstration only}}
+Installing ''certbot'' system wide with specific plugin included
+{{file|/etc/nixos/configuration.nix|nix|<nowiki>
+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;
+  agreeTerms = true;
+  package = pkgs.certbot.withPlugins (ps: with ps; [ certbot-dns-inwx ]);
+}
+</nowiki>}}
+Shared secret must be set in the configuration but you only have to configure the value if you're using 2FA on INWX.
-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 <code>maddy</code> read permissions for the certificate folder:
+Manually configure and generate certificates for <code>example.org</code> using the ''inwx''-plugin
 <syntaxhighlight lang="console">
-# sudo setfacl -R -m u:maddy:rX /etc/letsencrypt/{live,archive}
+# certbot certonly -a dns-inwx -d example.org --register-unsafely-without-email --agree-tos
 </syntaxhighlight>
+Now that a specific domain is configured to get renewed using the plugin, the ''systemd-timer'' of the ''certbot'' module will automatically renew it after expiration.
+[[Category:Server]]
+[[Category:Applications]]