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
simp_le 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:
security.acme.certs."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. The target directory can
be configured with the option security.acme.directory.
Refer to for all available configuration
options for the security.acme module.
Using ACME certificates in Nginx
In practice ACME is mostly used for retrieval and renewal of
certificates that will be used in a webserver like Nginx. A configuration for
Nginx that uses the certificates from ACME for
foo.example.com will look similar to:
security.acme.certs."foo.example.com" = {
webroot = "/var/www/challenges";
email = "foo@example.com";
user = "nginx";
group = "nginx";
postRun = "systemctl restart nginx.service";
};
services.nginx.httpConfig = ''
server {
server_name foo.example.com;
listen 80;
listen [::]:80;
location /.well-known/acme-challenge {
root /var/www/challenges;
}
location / {
return 301 https://$host$request_uri;
}
}
server {
server_name foo.example.com;
listen 443 ssl;
ssl_certificate ${config.security.acme.directory}/foo.example.com/fullchain.pem;
ssl_certificate_key ${config.security.acme.directory}/foo.example.com/key.pem;
root /var/www/foo.example.com/;
}
'';
Now Nginx will try to use the certificates that will be retrieved by ACME.
ACME needs Nginx (or any other webserver) to function and Nginx needs
the certificates to actually start. For this reason the ACME module
automatically generates self-signed certificates that will be used by Nginx to
start. After that Nginx is used by ACME to retrieve the actual ACME
certificates. security.acme.preliminarySelfsigned can be
used to control whether to generate the self-signed certificates.