ACME

NixOS 支持通过 ACME 协议实现自动域名验证、证书获取及续期。可以使用任何服务提供商，但 NixOS 默认使用 Let's Encrypt。底层使用的是替代 ACME 客户端 lego。

Setup

DNS-01 Challenge

下面的示例设置通过DNS验证生成证书。需接受 Let's Encrypt ToS 的服务条款（ToS）。同时，指定联系邮箱为admin+acme@example.com。

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.

The next example issues a wildcard certificate and uses Cloudflare for validation. We're also adding the group "nginx" here so that the certificate files can be used by nginx later on.

security.acme = {
  acceptTerms = true;
  defaults.email = "admin@example.org";
  certs = {
    "example.org" = {
      domain = "*.example.org";
      group = "nginx";
      dnsProvider = "cloudflare";
      # location of your CLOUDFLARE_DNS_API_TOKEN=[value]
      # https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#EnvironmentFile=
      environmentFile = "/home/admin/cloudflare";
    };
  };
};

HTTP-01 Challenge

Besides DNS validation it is also possible to obtain certificates by placing a file on your webserver at http://example.org/.well-known/acme-challenge. Instead of using the dnsProvider option, we use the webroot option.

security.acme = {
  acceptTerms = true;
  defaults.email = "admin@example.org";
  certs."example.org" = {
    # An acme system user is created. This user belongs to the acme group and the home directory is /var/lib/acme.
    # This user will try to make the directory .well-known/acme-challenge/ under the webroot directory.
    webroot = "/var/lib/acme";
  };
};

We need to make sure that our webserver knows where to redirect http://example.org/.well-known/acme-challenge to. If you use nginx this can be done as follows:

location /.well-known/acme-challenge/ {
  rewrite /.well-known/acme-challenge/(.*) /$1 break;
  root /var/lib/acme/.well-known/acme-challenge;
}

Usage

After successfull generation, certificates can be found in the directory /var/lib/acme. When using certificates in other applications it may be required to change permissions. The group of the certificate files can be adjusted by setting the group option as a string

security.acme.certs."example.org".group = "nginx";

or reference.

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

Resulting in the following files and permissions

lrwxrwxrwx 1 acme nginx   13 Aug  4 12:57 cert.pem -> fullchain.pem
-rw-r----- 1 acme nginx 1567 Aug  4 12:57 chain.pem
-rw-r----- 1 acme nginx 2865 Aug  4 12:57 fullchain.pem
-rw-r----- 1 acme nginx 3092 Aug  4 12:57 full.pem
-rw-r----- 1 acme nginx  227 Aug  4 12:57 key.pem

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

See also

• NixOS manual on SSL/TLS Certificates with ACME