ACME

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.

Setup

DNS Validation

Following example setup generates certificates using DNS validation. Let's Encrypt ToS has to be accepted. Further the contact mail admin+acme@example.com is defined.

security.acme = {
  acceptTerms = true;
  defaults.email = "admin+acme@example.org";
  certs."mx1.example.org" = {
    dnsProvider = "inwx";
    # Supplying password files like this will make your credentials world-readable
    # in the Nix store. This is for demonstration purpose only, do not use this in production.
    environmentFile = "${pkgs.writeText "inwx-creds" ''
      INWX_USERNAME=xxxxxxxxxx
      INWX_PASSWORD=yyyyyyyyyy
    ''}";
  };
};

Certificates are getting generated for the domain mx1.example.org using the DNS provider inwx. See upstream documentation on available providers and their specific configuration for the credentialsFile option.

HTTP Challenge (Nginx)

If you can't (or don't want to) use a DNS challenge, there is also the option to generate certificates automatically using a HTTP challenge. This is done by setting the services.nginx.virtualHosts."foo.example.org".enableACME to true.

See the NixOS manual section SSL/TLS Certificates with ACME for a full example.

Notice that you cannot obtain wildcard certificates this way.

Usage

After successfull generation, certificates can be found in the directory /var/lib/acme. To use certificates in other applications, permissions can be adjusted by setting a group name as a string or reference it.

security.acme.certs."mx1.example.org".group = config.services.maddy.group;

Using Let's Encrypt Staging

If you'd like to use the Let's Encrypt staging environment, eg for its less stringent rate limits, set

security.acme.defaults.server = "https://acme-staging-v02.api.letsencrypt.org/directory";

Navigation menu