ACME - Revision history

Starfish2228: /* HTTP challenge */ remove redundant quoting

2026-03-21T14:55:46Z

HTTP challenge: remove redundant quoting

← Older revision		Revision as of 14:55, 21 March 2026
Line 57:		Line 57:
	defaults.webroot = "/var/lib/acme/acme-challenge/";		defaults.webroot = "/var/lib/acme/acme-challenge/";
	# We are using nginx as webserver, therefore set correct key permissions		# 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 66:		Line 66:
	services.nginx = {		services.nginx = {
	enable = true;		enable = true;
	virtualHosts."${domainName}" = {		virtualHosts.${domainName} = {
	forceSSL = true;		forceSSL = true;
	useACMEHost = ~~"${~~domainName}";		useACMEHost = domainName;
	locations."/.well-known/".root = "/var/lib/acme/acme-challenge/";		locations."/.well-known/".root = "/var/lib/acme/acme-challenge/";
	};		};

Baodrate: add citation for nginx acmeroot setting advice

2026-02-02T22:17:46Z

add citation for nginx acmeroot setting advice

← Older revision		Revision as of 22:17, 2 February 2026
Line 75:		Line 75:
	</syntaxhighlight>		</syntaxhighlight>
	== DNS challenge ==		== 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>.		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 ===		=== With inwx as DNS provider ===

Hexa: Formatting, Wording, Prune

2025-12-14T18:56:39Z

Formatting, Wording, Prune

← Older revision		Revision as of 18:56, 14 December 2025
Line 3:		Line 3:
	= Basics =		= 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.		following paragraph.

Line 18:		Line 16:
	* <code>sslServerKey = "/var/host.key";</code> Path to server SSL certificate key. Located at <code>"${sslCertDir}/key.pem"</code>.		* <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~~		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.
	~~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 =		= Obtaining a new certificate =
Line 31:		Line 22:
	== Basics ==		== 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">		<syntaxhighlight lang="nix">
Line 85:		Line 74:

	</syntaxhighlight>		</syntaxhighlight>


	== DNS challenge ==		== 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>.		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>.
Line 110:		Line 97:
	</syntaxhighlight>		</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 ===		=== With Cloudflare as DNS provider ===
Line 143:		Line 126:
	== Setting file permission with postRun ==		== 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">		<syntaxhighlight lang="nix">
Line 175:		Line 157:

	Many service modules support obtaining certificates. But if you were		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.		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.		<code>useACMEHost</code> option.

Line 194:		Line 174:
	services.nginx.virtualHosts."site2.example.org".useACMEHost = "example.org";		services.nginx.virtualHosts."site2.example.org".useACMEHost = "example.org";
	</syntaxhighlight>		</syntaxhighlight>


	= Using Let's Encrypt Staging =		= 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">		<syntaxhighlight lang="nix">

Raboof: /* DNS challenge */ mention services.nginx.virtualHosts..acmeRoot should also be set to null for nginx.

2025-10-24T14:09:35Z

DNS challenge: mention services.nginx.virtualHosts.<name>.acmeRoot should also be set to null for nginx.

← Older revision		Revision as of 14:09, 24 October 2025
Line 88:		Line 88:

	== DNS challenge ==		== 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>.

	=== With inwx as DNS provider ===		=== With inwx as DNS provider ===

Tie-ling: update formatting

2025-09-19T06:58:11Z

update formatting

← Older revision		Revision as of 06:58, 19 September 2025
Line 12:		Line 12:
	The three key files and their location are		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.		* <code>sslServerChain = "/var/ca.pem";</code> Path to server SSL chain file. Located at <code>"${sslCertDir}/chain.pem"</code>.
	Located at <code>"${sslCertDir}/chain.pem"</code>.

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

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

Tie-ling: fix formatting

2025-09-19T06:56:12Z

fix formatting

← Older revision		Revision as of 06:56, 19 September 2025
Line 13:		Line 13:

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

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

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

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

Tie-ling: expanded on basics and interoperation

2025-09-19T06:54:47Z

expanded on basics and interoperation

Show changes

Scotch7881: Undo revision 23637 by Scotch7881 (talk)

2025-07-15T10:18:28Z

Undo revision 23637 by Scotch7881 (talk)

← Older revision		Revision as of 10:18, 15 July 2025
Line 1:		Line 1:
	NixOS ~~支持通过~~ ACME ~~协议实现自动域名验证、证书获取及续期。可以使用任何服务提供商，但~~ NixOS ~~默认使用~~ Let's ~~Encrypt。底层使用的是替代~~ ACME ~~客户端 lego。~~		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 [https://go-acme.github.io/lego/ lego] is used under the hood.

	== Setup ==		== Setup ==
	=== DNS-01 Challenge ===		=== DNS-01 Challenge ===
	~~下面的示例设置通过DNS验证生成证书。需接受~~ [https://letsencrypt.org/repository/ Let's Encrypt ToS] ~~的服务条款（ToS）。同时，指定联系邮箱为~~<code>admin+acme@example.com</code>。		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.

	<syntaxhighlight lang="nix">		<syntaxhighlight lang="nix">

Scotch7881 at 10:39, 13 July 2025

2025-07-13T10:39:03Z

← Older revision		Revision as of 10:39, 13 July 2025
Line 1:		Line 1:
	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 [https://go-acme.github.io/lego/ lego] is used under the hood.~~		NixOS 支持通过 ACME 协议实现自动域名验证、证书获取及续期。可以使用任何服务提供商，但 NixOS 默认使用 Let's Encrypt。底层使用的是替代 ACME 客户端 lego。

	== Setup ==		== Setup ==
	=== DNS-01 Challenge ===		=== DNS-01 Challenge ===
	~~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.~~		下面的示例设置通过DNS验证生成证书。需接受 [https://letsencrypt.org/repository/ Let's Encrypt ToS] 的服务条款（ToS）。同时，指定联系邮箱为<code>admin+acme@example.com</code>。

	<syntaxhighlight lang="nix">		<syntaxhighlight lang="nix">

WoutSwinkels: /* Setup */

2024-10-10T20:20:39Z

Setup

@@ Line 2: / Line 2: @@
 == 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.
@@ Line 37: / Line 38: @@
    };
 };
 </syntaxhighlight>