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:
."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";
};
};
};
}