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