ACME: Difference between revisions

From NixOS Wiki
Sandro (talk | contribs)
Remove maybe confusing mx1 subdomain
Tboston (talk | contribs)
Added wildcard example and clarification on the group usage
Line 2: Line 2:


== Setup ==
== Setup ==
Following example setup generates certificates using DNS validation. [https://letsencrypt.org/repository/ Let's Encrypt ToS] has to be accepted. Further the contact mail <code>admin+acme@example.com</code> is defined.


Following example setup generates certificates using DNS validation. [https://letsencrypt.org/repository/ Let's Encrypt ToS] has to be accepted. Further the contact mail <code>admin+acme@example.com</code> is defined.
Following example setup generates certificates using DNS validation. [https://letsencrypt.org/repository/ Let's Encrypt ToS] has to be accepted. Further the contact mail <code>admin+acme@example.com</code> is defined.
Line 22: Line 23:


Certificates are getting generated for the domain <code>mx1.example.org</code> using the DNS provider <code>inwx</code>. See [https://go-acme.github.io/lego/dns upstream documentation] on available providers and their specific configuration for the <code>credentialsFile</code> option.
Certificates are getting generated for the domain <code>mx1.example.org</code> using the DNS provider <code>inwx</code>. See [https://go-acme.github.io/lego/dns upstream documentation] on available providers and their specific configuration for the <code>credentialsFile</code> 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.<syntaxhighlight lang="nix">
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";
    };
  };
};
</syntaxhighlight>


== Usage ==
== Usage ==
Line 35: Line 53:
<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
security.acme.certs."example.org".group = config.services.nginx.group;
security.acme.certs."example.org".group = config.services.nginx.group;
</syntaxhighlight>Resulting in the following files and permissions<syntaxhighlight lang="bash">
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
</syntaxhighlight>
</syntaxhighlight>



Revision as of 16:22, 4 August 2024

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

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.

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.

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

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