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>
<para>
NixOS supports automatic domain validation &amp; certificate retrieval and
renewal using the ACME protocol. This is currently only implemented by and
for Let's Encrypt. The alternative ACME client <literal>lego</literal> is
used under the hood.
renewal using the ACME protocol. Any provider can be used, but by default
NixOS uses Let's Encrypt. The alternative ACME client <literal>lego</literal>
is used under the hood.
</para>
<para>
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.
</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>
You will need an HTTP server or DNS server for verification. For HTTP,
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.email" /> = "admin+acme@example.com";
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> = {
"foo.example.com" = {
<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.email" /> = "admin+acme@example.com";
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> = {
"acmechallenge.example.com" = {
# Catchall vhost, will redirect users to HTTPS for all vhosts
@ -179,7 +186,7 @@ services.httpd = {
<para>
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,
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
@ -190,7 +197,7 @@ services.httpd = {
services.bind = {
<link linkend="opt-services.bind.enable">enable</link> = true;
<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> = [
rec {
@ -208,7 +215,7 @@ services.bind = {
<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_.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
<link linkend="opt-security.acme.certs._name_.dnsPropagationCheck">dnsPropagationCheck</link> = false;
};
@ -221,27 +228,27 @@ services.bind = {
</para>
<programlisting>
mkdir -p /var/secrets
tsig-keygen rfc2136key.example.com &gt; /var/secrets/dnskeys.conf
chown named:root /var/secrets/dnskeys.conf
chmod 400 /var/secrets/dnskeys.conf
mkdir -p /var/lib/secrets
tsig-keygen rfc2136key.example.com &gt; /var/lib/secrets/dnskeys.conf
chown named:root /var/lib/secrets/dnskeys.conf
chmod 400 /var/lib/secrets/dnskeys.conf
# Copy the secret value from the dnskeys.conf, and put it in
# 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_TSIG_ALGORITHM='hmac-sha256.'
RFC2136_TSIG_KEY='rfc2136key.example.com'
RFC2136_TSIG_SECRET='your secret key'
EOF
chmod 400 /var/secrets/certs.secret
chmod 400 /var/lib/secrets/certs.secret
</programlisting>
<para>
Now you're all set to generate certs! You should monitor the first invokation
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>
</section>
</chapter>