ACME: Difference between revisions

(5 intermediate revisions by 4 users not shown)

Line 3:

= Basics =

This process should generate three key files. The naming and usage of

This process should generate three key files. The naming and usage of the three key files is common to all programs and services in NixOS.

the three key files is common to all programs and services in NixOS.

We let <code>sslCertDir =

We let <code>sslCertDir = config.security.acme.certs.${domainName}.directory;</code> in the

config.security.acme.certs.${domainName}.directory;</code> in the

following paragraph.

The three key files and their location are

* <code>sslServerCert = "/var/host.cert";</code> Path to server SSL

* <code>sslServerCert = "/var/host.cert";</code> Path to server SSL certificate. Located at <code>"${sslCertDir}/fullchain.pem"</code>.

certificate.

Located at <code>"${sslCertDir}/~~fullchain~~.pem"</code>.

* <code>sslServerChain = "/var/ca.pem";</code> Path to server SSL chain file. Located at <code>"${sslCertDir}/chain.pem"</code>.

* <code>~~sslServerChain~~ = "/var/ca.~~pem~~";</code> Path to server SSL ~~chain file~~.

* <code>sslServerKey = "/var/host.key";</code> Path to server SSL certificate key. Located at <code>"${sslCertDir}/key.pem"</code>.

~~Located at <code>"${sslCertDir}/chain.pem"</code>.~~

The <code>useACMEHost</code> option can be used with a wide variety of services[https://search.nixos.org/options?channel=25.05&query=useACMEHost], which simplifies the configuration and enables the automatic checking of correct private and public key permissions during nixos-rebuild.

* <code>sslServerKey = "/var/host.key";</code> Path to server SSL

~~certificate key.~~

~~Located at <code>"${sslCertDir}/key.pem"</code>.~~

~~Beginning in late 2024, user @ThinkChaos started working on unifying~~

~~modules options to use the same interface for specifying certificates.~~

~~Currently, in 2025-09, the~~ <code>useACMEHost</code> option can be used

with a wide variety of services

[https://search.nixos.org/options?channel=25.05&query=useACMEHost],

which simplifies the configuration and enables the automatic checking

of correct private and public key permissions during nixos-rebuild.

= Obtaining a new certificate =

Line 39:

Line 22:

== Basics ==

You need to agree to the Terms of Service, provide an email address,

You need to agree to the Terms of Service, provide an email address, provide a domain name, and, if any, extra domain names.

provide a domain name, and, if any, extra domain names.

DNS challenge supports obtaining certificates for wildcard domains,

DNS challenge supports obtaining certificates for wildcard domains, such as <code>*.example.org</code>.

such as <code>*.example.org</code>.

Line 76:

Line 57:

defaults.webroot = "/var/lib/acme/acme-challenge/";

# We are using nginx as webserver, therefore set correct key permissions

certs."${domainName}".group = config.services.nginx.group;

certs.${domainName}.group = config.services.nginx.group;

};

Line 85:

Line 66:

services.nginx = {

enable = true;

virtualHosts."${domainName}" = {

virtualHosts.${domainName} = {

forceSSL = true;

useACMEHost = ~~"${~~domainName}";

useACMEHost = domainName;

locations."/.well-known/".root = "/var/lib/acme/acme-challenge/";

};

Line 93:

Line 74:

</syntaxhighlight>

== DNS challenge ==

If you want to use the DNS challenge with nginx, you should also set [https://search.nixos.org/options?show=services.nginx.virtualHosts.%3Cname%3E.acmeRoot service.nginx.virtualHosts.<name>.acmeRoot] to <code>null</code>. <ref>From [https://nixos.org/manual/nixos/stable/#module-security-acme-config-dns-with-vhosts NixOS Manual: ''Using DNS validation with web server virtual hosts'']. [https://github.com/NixOS/nixpkgs/issues/210807 Issue #210807] provides some detail on why this is needed.</ref>

=== With inwx as DNS provider ===

Line 117:

Line 97:

</syntaxhighlight>

Certificates are getting generated for the domain

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<nowiki> upstream documentation] on available providers and their specific configuration for the </nowiki><code>credentialsFile</code> option.

<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.

=== With Cloudflare as DNS provider ===

Line 150:

Line 126:

== Setting file permission with postRun ==

Use the <code>security.acme.certs.*.postRun</code> to set permissions

Use the <code>security.acme.certs.*.postRun</code> to set permissions on the key directory and the key files:

on the key directory and the key files:

Line 182:

Line 157:

Many service modules support obtaining certificates. But if you were

to configure certificate options separately for each service module,

to configure certificate options separately for each service module, it would be time-consuming and risks hitting the certificate renewal

it would be time consuming and risks hitting the certificate renewal

limits of the service provider.

Instead, centrally manage certificate options within the security.acme

Instead, centrally manage certificate options within the security.acme module; then point other services to security.acme with

module; then point other services to security.acme with

<code>useACMEHost</code> option.

Line 201:

Line 174:

services.nginx.virtualHosts."site2.example.org".useACMEHost = "example.org";

</syntaxhighlight>

= Using Let's Encrypt Staging =

~~If you'd like to use the~~ Let's Encrypt [https://letsencrypt.org/docs/staging-environment/ staging environment], ~~eg for its~~ less stringent rate limits~~, set~~

For testing your Let's Encrypt configuration it makes sense to use their [https://letsencrypt.org/docs/staging-environment/ staging environment], because it offers less stringent rate limits.

@@ Line 3: / Line 3: @@
 = Basics =
-This process should generate three key files.  The naming and usage of
+This process should generate three key files.  The naming and usage of the three key files is common to all programs and services in NixOS.
-the three key files is common to all programs and services in NixOS.
-We let <code>sslCertDir =
+We let <code>sslCertDir = config.security.acme.certs.${domainName}.directory;</code> in the
-config.security.acme.certs.${domainName}.directory;</code> in the
 following paragraph.
 The three key files and their location are
-* <code>sslServerCert = "/var/host.cert";</code> Path to server SSL
+* <code>sslServerCert = "/var/host.cert";</code> Path to server SSL certificate. Located at <code>"${sslCertDir}/fullchain.pem"</code>.
-  certificate.
-  Located at <code>"${sslCertDir}/fullchain.pem"</code>.
+* <code>sslServerChain = "/var/ca.pem";</code> Path to server SSL chain file. Located at <code>"${sslCertDir}/chain.pem"</code>.
-* <code>sslServerChain = "/var/ca.pem";</code> Path to server SSL chain file.
+* <code>sslServerKey = "/var/host.key";</code> Path to server SSL certificate key. Located at <code>"${sslCertDir}/key.pem"</code>.
-  Located at <code>"${sslCertDir}/chain.pem"</code>.
+The <code>useACMEHost</code> option can be used with a wide variety of services[https://search.nixos.org/options?channel=25.05&query=useACMEHost], which simplifies the configuration and enables the automatic checking of correct private and public key permissions during nixos-rebuild.
-* <code>sslServerKey = "/var/host.key";</code> Path to server SSL
-  certificate key.
-  Located at <code>"${sslCertDir}/key.pem"</code>.
-Beginning in late 2024, user @ThinkChaos started working on unifying
-modules options to use the same interface for specifying certificates.
-Currently, in 2025-09, the <code>useACMEHost</code> option can be used
-with a wide variety of services
-[https://search.nixos.org/options?channel=25.05&query=useACMEHost],
-which simplifies the configuration and enables the automatic checking
-of correct private and public key permissions during nixos-rebuild.
 = Obtaining a new certificate =
@@ Line 39: / Line 22: @@
 == Basics ==
-You need to agree to the Terms of Service, provide an email address,
+You need to agree to the Terms of Service, provide an email address, provide a domain name, and, if any, extra domain names.
-provide a domain name, and, if any, extra domain names.
-DNS challenge supports obtaining certificates for wildcard domains,
+DNS challenge supports obtaining certificates for wildcard domains, such as <code>*.example.org</code>.
-such as <code>*.example.org</code>.
 <syntaxhighlight lang="nix">
@@ Line 76: / Line 57: @@
      defaults.webroot = "/var/lib/acme/acme-challenge/";
      # We are using nginx as webserver, therefore set correct key permissions
-     certs."${domainName}".group = config.services.nginx.group;
+     certs.${domainName}.group = config.services.nginx.group;
    };
@@ Line 85: / Line 66: @@
    services.nginx = {
      enable = true;
-     virtualHosts."${domainName}" = {
+     virtualHosts.${domainName} = {
        forceSSL = true;
-       useACMEHost = "${domainName}";
+       useACMEHost = domainName;
        locations."/.well-known/".root = "/var/lib/acme/acme-challenge/";
      };
@@ Line 93: / Line 74: @@
 </syntaxhighlight>
 == DNS challenge ==
+If you want to use the DNS challenge with nginx, you should also set [https://search.nixos.org/options?show=services.nginx.virtualHosts.%3Cname%3E.acmeRoot service.nginx.virtualHosts.<name>.acmeRoot] to <code>null</code>. <ref>From [https://nixos.org/manual/nixos/stable/#module-security-acme-config-dns-with-vhosts NixOS Manual: ''Using DNS validation with web server virtual hosts'']. [https://github.com/NixOS/nixpkgs/issues/210807 Issue #210807] provides some detail on why this is needed.</ref>
 === With inwx as DNS provider ===
@@ Line 117: / Line 97: @@
 </syntaxhighlight>
-Certificates are getting generated for the domain
+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<nowiki> upstream documentation] on available providers and their specific configuration for the </nowiki><code>credentialsFile</code> option.
-<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.
 === With Cloudflare as DNS provider ===
@@ Line 150: / Line 126: @@
 == Setting file permission with postRun ==
-Use the <code>security.acme.certs.*.postRun</code> to set permissions
+Use the <code>security.acme.certs.*.postRun</code> to set permissions on the key directory and the key files:
-on the key directory and the key files:
 <syntaxhighlight lang="nix">
@@ Line 182: / Line 157: @@
 Many service modules support obtaining certificates.  But if you were
-to configure certificate options separately for each service module,
+to configure certificate options separately for each service module, it would be time-consuming and risks hitting the certificate renewal
-it would be time consuming and risks hitting the certificate renewal
 limits of the service provider.
-Instead, centrally manage certificate options within the security.acme
+Instead, centrally manage certificate options within the security.acme module; then point other services to security.acme with
-module; then point other services to security.acme with
 <code>useACMEHost</code> option.
@@ Line 201: / Line 174: @@
 services.nginx.virtualHosts."site2.example.org".useACMEHost = "example.org";
 </syntaxhighlight>
 = Using Let's Encrypt Staging =
-If you'd like to use the Let's Encrypt [https://letsencrypt.org/docs/staging-environment/ staging environment], eg for its less stringent rate limits, set
+For testing your Let's Encrypt configuration it makes sense to use their [https://letsencrypt.org/docs/staging-environment/ staging environment], because it offers less stringent rate limits.
 <syntaxhighlight lang="nix">