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: services.nginx.httpConfig = '' 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.