ACME: Difference between revisions
→DNS challenge: mention services.nginx.virtualHosts.<name>.acmeRoot should also be set to null for nginx. |
Formatting, Wording, Prune |
||
| 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>. | ||
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. | |||
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 = | ||
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"> | ||