NixOS supports automatic domain validation & certificate retrieval and renewal using the ACME protocol. Any provider can be used, but by default NixOS uses Let's Encrypt. The alternative ACME client lego is used under the hood. Automatic cert validation and configuration for Apache and Nginx virtual hosts is included in NixOS, however if you would like to generate a wildcard cert or you are not using a web server you will have to configure DNS based validation.

To use the ACME module, you must accept the provider's terms of service by setting to true. The Let's Encrypt ToS can be found here. You must also set an email address to be used when creating accounts with Let's Encrypt. You can set this for all certs with and/or on a per-cert basis with . This address is only used for registration and renewal reminders, and cannot be used to administer the certificates in any way. Alternatively, you can use a different ACME server by changing the option to a provider of your choosing, or just change the server for one cert with . You will need an HTTP server or DNS server for verification. For HTTP, 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 DNS, you must set up credentials with your provider/server for use with lego.

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. = true; = "admin+acme@example.com"; services.nginx = { enable = true; virtualHosts = { "foo.example.com" = { forceSSL = true; enableACME = true; # All serverAliases will be added as extra domain names on the certificate. serverAliases = [ "bar.example.com" ]; locations."/" = { root = "/var/www"; }; }; # We can also add a different vhost and reuse the same certificate # but we have to append extraDomainNames manually. security.acme.certs."foo.example.com".extraDomainNames = [ "baz.example.com" ]; "baz.example.com" = { forceSSL = true; useACMEHost = "foo.example.com"; locations."/" = { root = "/var/www"; }; }; }; }

Using ACME certificates with Apache virtual hosts is identical to using them with Nginx. The attribute names are all the same, just replace "nginx" with "httpd" where appropriate.

First off you will need to set up a virtual host to serve the challenges. This example uses a vhost called certs.example.com, with the intent that you will generate certs for all your vhosts and redirect everyone to HTTPS. = true; = "admin+acme@example.com"; services.nginx = { enable = true; virtualHosts = { "acmechallenge.example.com" = { # Catchall vhost, will redirect users to HTTPS for all vhosts serverAliases = [ "*.example.com" ]; # /var/lib/acme/.challenges must be writable by the ACME user # and readable by the Nginx user. # By default, this is the case. locations."/.well-known/acme-challenge" = { root = "/var/lib/acme/.challenges"; }; locations."/" = { return = "301 https://$host$request_uri"; }; }; }; } # Alternative config for Apache services.httpd = { enable = true; virtualHosts = { "acmechallenge.example.com" = { # Catchall vhost, will redirect users to HTTPS for all vhosts serverAliases = [ "*.example.com" ]; # /var/lib/acme/.challenges must be writable by the ACME user and readable by the Apache user. # By default, this is the case. documentRoot = "/var/lib/acme/.challenges"; extraConfig = '' RewriteEngine On RewriteCond %{HTTPS} off RewriteCond %{REQUEST_URI} !^/\.well-known/acme-challenge [NC] RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} [R=301] ''; }; }; } Now you need to configure ACME to generate a certificate. ."foo.example.com" = { webroot = "/var/lib/acme/.challenges"; email = "foo@example.com"; # Ensure that the web server you use can read the generated certs # Take a look at the group option for the web server you choose. group = "nginx"; # Since we have a wildcard vhost to handle port 80, # we can generate certs for anything! # Just make sure your DNS resolves them. extraDomainNames = [ "mail.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.

This is useful if you want to generate a wildcard certificate, since ACME servers will only hand out wildcard certs over DNS validation. There a number of supported DNS providers and servers you can utilise, see the lego docs for provider/server specific configuration values. For the sake of these docs, we will provide a fully self-hosted example using bind. services.bind = { enable = true; extraConfig = '' include "/var/lib/secrets/dnskeys.conf"; ''; zones = [ rec { name = "example.com"; file = "/var/db/bind/${name}"; master = true; extraConfig = "allow-update { key rfc2136key.example.com.; };"; } ]; } # Now we can configure ACME = true; = "admin+acme@example.com"; ."example.com" = { domain = "*.example.com"; dnsProvider = "rfc2136"; credentialsFile = "/var/lib/secrets/certs.secret"; # We don't need to wait for propagation since this is a local DNS server dnsPropagationCheck = false; }; The dnskeys.conf and certs.secret must be kept secure and thus you should not keep their contents in your Nix config. Instead, generate them one time with these commands: mkdir -p /var/lib/secrets tsig-keygen rfc2136key.example.com > /var/lib/secrets/dnskeys.conf chown named:root /var/lib/secrets/dnskeys.conf chmod 400 /var/lib/secrets/dnskeys.conf # Copy the secret value from the dnskeys.conf, and put it in # RFC2136_TSIG_SECRET below cat > /var/lib/secrets/certs.secret << EOF RFC2136_NAMESERVER='127.0.0.1:53' RFC2136_TSIG_ALGORITHM='hmac-sha256.' RFC2136_TSIG_KEY='rfc2136key.example.com' RFC2136_TSIG_SECRET='your secret key' EOF chmod 400 /var/lib/secrets/certs.secret Now you're all set to generate certs! You should monitor the first invokation by running systemctl start acme-example.com.service & journalctl -fu acme-example.com.service and watching its log output.

Should you need to regenerate a particular certificate in a hurry, such as when a vulnerability is found in Let's Encrypt, there is now a convenient mechanism for doing so. Running systemctl clean --what=state acme-example.com.service will remove all certificate files and the account data for the given domain, allowing you to then systemctl start acme-example.com.service to generate fresh ones.

It is possible that your account credentials file may become corrupt and need to be regenerated. In this scenario lego will produce the error JWS verification error. The solution is to simply delete the associated accounts file and re-run the affected service(s). # Find the accounts folder for the certificate systemctl cat acme-example.com.service | grep -Po 'accounts/[^:]*' export accountdir="$(!!)" # Move this folder to some place else mv /var/lib/acme/.lego/$accountdir{,.bak} # Recreate the folder using systemd-tmpfiles systemd-tmpfiles --create # Get a new account and reissue certificates # Note: Do this for all certs that share the same account email address systemctl start acme-example.com.service