Certbot: Difference between revisions

From NixOS Wiki
imported>Onny
Add info about renewal of certificates
imported>Onny
Add information about automated renewal
Line 3: Line 3:
== Installation ==
== Installation ==


Install ''certbot'' in your current environment
Install ''certbot'' in your current environment and enable ''systemd-timer'' for automated renewal of certificates
<syntaxhighlight lang="console">
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
# nix-env -iA nixos.certbot
services.certbot.enable = true;
</syntaxhighlight>
</nowiki>}}


== Usage ==
== Usage ==
Line 47: Line 47:
};
};


environment.systemPackages = with pkgs; [
services.certbot = {
   ( certbot.withPlugins (ps: with ps; [ certbot-dns-inwx ]) )
  enable = true;
];
   package = pkgs.certbot.withPlugins (ps: with ps; [ certbot-dns-inwx ]);
}
</nowiki>}}
</nowiki>}}
Shared secret must be set in the configuration but you only have to configure the value if you're using 2FA on 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 <code>example.org</code> using the ''inwx''-plugin
Manually generate certificates for <code>example.org</code> using the ''inwx''-plugin
<syntaxhighlight lang="console">
<syntaxhighlight lang="console">
# certbot certonly -a dns-inwx -d example.org --register-unsafely-without-email --agree-tos
# certbot certonly -a dns-inwx -d example.org --register-unsafely-without-email --agree-tos
</syntaxhighlight>
</syntaxhighlight>


=== Automated renewal of certificates ===
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.
 
Certificates invalidate after a specific time, often aften several months. You can renew them manually after that period using following command
<syntaxhighlight lang="console">
# certbot renew
</syntaxhighlight>

Revision as of 19:08, 11 September 2022

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.