nixos/acme: indicate support for other providers

This commit is contained in:
Lucas Savva 2020-05-01 18:23:16 +01:00
parent 47da7aafdf
commit c9f6e5f161
No known key found for this signature in database
GPG key ID: F9CE6D3DCDC78F2D

View file

@ -6,9 +6,9 @@
<title>SSL/TLS Certificates with ACME</title> <title>SSL/TLS Certificates with ACME</title>
<para> <para>
NixOS supports automatic domain validation &amp; certificate retrieval and NixOS supports automatic domain validation &amp; certificate retrieval and
renewal using the ACME protocol. This is currently only implemented by and renewal using the ACME protocol. Any provider can be used, but by default
for Let's Encrypt. The alternative ACME client <literal>lego</literal> is NixOS uses Let's Encrypt. The alternative ACME client <literal>lego</literal>
used under the hood. is used under the hood.
</para> </para>
<para> <para>
Automatic cert validation and configuration for Apache and Nginx virtual Automatic cert validation and configuration for Apache and Nginx virtual
@ -36,6 +36,13 @@
and cannot be used to administer the certificates in any way. and cannot be used to administer the certificates in any way.
</para> </para>
<para>
Alternatively, you can use a different ACME server by changing the
<literal><xref linkend="opt-security.acme.server" /></literal> option
to a provider of your choosing, or just change the server for one cert with
<literal><xref linkend="opt-security.acme.certs._name_.server" /></literal>.
</para>
<para> <para>
You will need an HTTP server or DNS server for verification. For HTTP, You will need an HTTP server or DNS server for verification. For HTTP,
the server must have a webroot defined that can serve the server must have a webroot defined that can serve
@ -60,7 +67,7 @@
<xref linkend="opt-security.acme.acceptTerms" /> = true; <xref linkend="opt-security.acme.acceptTerms" /> = true;
<xref linkend="opt-security.acme.email" /> = "admin+acme@example.com"; <xref linkend="opt-security.acme.email" /> = "admin+acme@example.com";
services.nginx = { services.nginx = {
<link linkend="opt-services.nginx.enable">enable = true;</link> <link linkend="opt-services.nginx.enable">enable</link> = true;
<link linkend="opt-services.nginx.virtualHosts">virtualHosts</link> = { <link linkend="opt-services.nginx.virtualHosts">virtualHosts</link> = {
"foo.example.com" = { "foo.example.com" = {
<link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true; <link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true;
@ -109,7 +116,7 @@ services.nginx = {
<xref linkend="opt-security.acme.acceptTerms" /> = true; <xref linkend="opt-security.acme.acceptTerms" /> = true;
<xref linkend="opt-security.acme.email" /> = "admin+acme@example.com"; <xref linkend="opt-security.acme.email" /> = "admin+acme@example.com";
services.nginx = { services.nginx = {
<link linkend="opt-services.nginx.enable">enable = true;</link> <link linkend="opt-services.nginx.enable">enable</link> = true;
<link linkend="opt-services.nginx.virtualHosts">virtualHosts</link> = { <link linkend="opt-services.nginx.virtualHosts">virtualHosts</link> = {
"acmechallenge.example.com" = { "acmechallenge.example.com" = {
# Catchall vhost, will redirect users to HTTPS for all vhosts # Catchall vhost, will redirect users to HTTPS for all vhosts
@ -179,7 +186,7 @@ services.httpd = {
<para> <para>
This is useful if you want to generate a wildcard certificate, since This is useful if you want to generate a wildcard certificate, since
Let's Encrypt will only hand out wildcard certs over DNS validation. ACME servers will only hand out wildcard certs over DNS validation.
There a number of supported DNS providers and servers you can utilise, There a number of supported DNS providers and servers you can utilise,
see the <link xlink:href="https://go-acme.github.io/lego/dns/">lego docs</link> see the <link xlink:href="https://go-acme.github.io/lego/dns/">lego docs</link>
for provider/server specific configuration values. For the sake of these for provider/server specific configuration values. For the sake of these
@ -190,7 +197,7 @@ services.httpd = {
services.bind = { services.bind = {
<link linkend="opt-services.bind.enable">enable</link> = true; <link linkend="opt-services.bind.enable">enable</link> = true;
<link linkend="opt-services.bind.extraConfig">extraConfig</link> = '' <link linkend="opt-services.bind.extraConfig">extraConfig</link> = ''
include "/var/secrets/dnskeys.conf"; include "/var/lib/secrets/dnskeys.conf";
''; '';
<link linkend="opt-services.bind.zones">zones</link> = [ <link linkend="opt-services.bind.zones">zones</link> = [
rec { rec {
@ -208,7 +215,7 @@ services.bind = {
<xref linkend="opt-security.acme.certs" />."example.com" = { <xref linkend="opt-security.acme.certs" />."example.com" = {
<link linkend="opt-security.acme.certs._name_.domain">domain</link> = "*.example.com"; <link linkend="opt-security.acme.certs._name_.domain">domain</link> = "*.example.com";
<link linkend="opt-security.acme.certs._name_.dnsProvider">dnsProvider</link> = "rfc2136"; <link linkend="opt-security.acme.certs._name_.dnsProvider">dnsProvider</link> = "rfc2136";
<link linkend="opt-security.acme.certs._name_.credentialsFile">credentialsFile</link> = "/var/secrets/certs.secret"; <link linkend="opt-security.acme.certs._name_.credentialsFile">credentialsFile</link> = "/var/lib/secrets/certs.secret";
# We don't need to wait for propagation since this is a local DNS server # We don't need to wait for propagation since this is a local DNS server
<link linkend="opt-security.acme.certs._name_.dnsPropagationCheck">dnsPropagationCheck</link> = false; <link linkend="opt-security.acme.certs._name_.dnsPropagationCheck">dnsPropagationCheck</link> = false;
}; };
@ -221,27 +228,27 @@ services.bind = {
</para> </para>
<programlisting> <programlisting>
mkdir -p /var/secrets mkdir -p /var/lib/secrets
tsig-keygen rfc2136key.example.com &gt; /var/secrets/dnskeys.conf tsig-keygen rfc2136key.example.com &gt; /var/lib/secrets/dnskeys.conf
chown named:root /var/secrets/dnskeys.conf chown named:root /var/lib/secrets/dnskeys.conf
chmod 400 /var/secrets/dnskeys.conf chmod 400 /var/lib/secrets/dnskeys.conf
# Copy the secret value from the dnskeys.conf, and put it in # Copy the secret value from the dnskeys.conf, and put it in
# RFC2136_TSIG_SECRET below # RFC2136_TSIG_SECRET below
cat &gt; /var/secrets/certs.secret &lt;&lt; EOF cat &gt; /var/lib/secrets/certs.secret &lt;&lt; EOF
RFC2136_NAMESERVER='127.0.0.1:53' RFC2136_NAMESERVER='127.0.0.1:53'
RFC2136_TSIG_ALGORITHM='hmac-sha256.' RFC2136_TSIG_ALGORITHM='hmac-sha256.'
RFC2136_TSIG_KEY='rfc2136key.example.com' RFC2136_TSIG_KEY='rfc2136key.example.com'
RFC2136_TSIG_SECRET='your secret key' RFC2136_TSIG_SECRET='your secret key'
EOF EOF
chmod 400 /var/secrets/certs.secret chmod 400 /var/lib/secrets/certs.secret
</programlisting> </programlisting>
<para> <para>
Now you're all set to generate certs! You should monitor the first invokation Now you're all set to generate certs! You should monitor the first invokation
by running <literal>systemctl start acme-example.com.service &amp; by running <literal>systemctl start acme-example.com.service &amp;
journalctl -fu acme-example.com.service</literal> and watching for errors. journalctl -fu acme-example.com.service</literal> and watching its log output.
</para> </para>
</section> </section>
</chapter> </chapter>