SSL/TLS Certificates with ACME
NixOS supports automatic domain validation & certificate retrieval and
renewal using the ACME protocol. This is currently only implemented by and
for Let's Encrypt. The alternative ACME client lego is
used under the hood.
Prerequisites
You need to have a running HTTP server for verification. The server must
have a webroot defined that can serve
.well-known/acme-challenge. This directory must be
writeable by the user that will run the ACME client.
For instance, this generic snippet could be used for Nginx:
http {
server {
server_name _;
listen 80;
listen [::]:80;
location /.well-known/acme-challenge {
root /var/www/challenges;
}
location / {
return 301 https://$host$request_uri;
}
}
}
Configuring
To enable ACME certificate retrieval & renewal for a certificate for
foo.example.com, add the following in your
configuration.nix:
."foo.example.com" = {
webroot = "/var/www/challenges";
email = "foo@example.com";
};
The private key key.pem and certificate
fullchain.pem will be put into
/var/lib/acme/foo.example.com.
Refer to for all available configuration
options for the security.acme
module.
Using ACME certificates in Nginx
NixOS supports fetching ACME certificates for you by setting
enableACME
= true; in a virtualHost config. We first create self-signed
placeholder certificates in place of the real ACME certs. The placeholder
certs are overwritten when the ACME certs arrive. For
foo.example.com the config would look like.
services.nginx = {
enable = true;
virtualHosts = {
"foo.example.com" = {
forceSSL = true;
enableACME = true;
locations."/" = {
root = "/var/www";
};
};
};
}