604b7c139f
* nixos/acme: Fix ordering of cert requests
When subsequent certificates would be added, they would
not wake up nginx correctly due to target units only being triggered
once. We now added more fine-grained systemd dependencies to make sure
nginx always is aware of new certificates and doesn't restart too early
resulting in a crash.
Furthermore, the acme module has been refactored. Mostly to get
rid of the deprecated PermissionStartOnly systemd options which were
deprecated. Below is a summary of changes made.
* Use SERVICE_RESULT to determine status
This was added in systemd v232. we don't have to keep track
of the EXITCODE ourselves anymore.
* Add regression test for requesting mutliple domains
* Deprecate 'directory' option
We now use systemd's StateDirectory option to manage
create and permissions of the acme state directory.
* The webroot is created using a systemd.tmpfiles.rules rule
instead of the preStart script.
* Depend on certs directly
By getting rid of the target units, we make sure ordering
is correct in the case that you add new certs after already
having deployed some.
Reason it broke before: acme-certificates.target would
be in active state, and if you then add a new cert, it
would still be active and hence nginx would restart
without even requesting a new cert. Not good! We
make the dependencies more fine-grained now. this should fix that
* Remove activationDelay option
It complicated the code a lot, and is rather arbitrary. What if
your activation script takes more than activationDelay seconds?
Instead, one should use systemd dependencies to make sure some
action happens before setting the certificate live.
e.g. If you want to wait until your cert is published in DNS DANE /
TLSA, you could create a unit that blocks until it appears in DNS:
```
RequiredBy=acme-${cert}.service
After=acme-${cert}.service
ExecStart=publish-wait-for-dns-script
```
98 lines
3.3 KiB
XML
98 lines
3.3 KiB
XML
<chapter xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
version="5.0"
|
|
xml:id="module-security-acme">
|
|
<title>SSL/TLS Certificates with ACME</title>
|
|
<para>
|
|
NixOS supports automatic domain validation & certificate retrieval and
|
|
renewal using the ACME protocol. This is currently only implemented by and
|
|
for Let's Encrypt. The alternative ACME client <literal>simp_le</literal> is
|
|
used under the hood.
|
|
</para>
|
|
<section xml:id="module-security-acme-prerequisites">
|
|
<title>Prerequisites</title>
|
|
|
|
<para>
|
|
You need to have a running HTTP server for verification. The server must
|
|
have a webroot defined that can serve
|
|
<filename>.well-known/acme-challenge</filename>. This directory must be
|
|
writeable by the user that will run the ACME client.
|
|
</para>
|
|
|
|
<para>
|
|
For instance, this generic snippet could be used for Nginx:
|
|
<programlisting>
|
|
http {
|
|
server {
|
|
server_name _;
|
|
listen 80;
|
|
listen [::]:80;
|
|
|
|
location /.well-known/acme-challenge {
|
|
root /var/www/challenges;
|
|
}
|
|
|
|
location / {
|
|
return 301 https://$host$request_uri;
|
|
}
|
|
}
|
|
}
|
|
</programlisting>
|
|
</para>
|
|
</section>
|
|
<section xml:id="module-security-acme-configuring">
|
|
<title>Configuring</title>
|
|
|
|
<para>
|
|
To enable ACME certificate retrieval & renewal for a certificate for
|
|
<literal>foo.example.com</literal>, add the following in your
|
|
<filename>configuration.nix</filename>:
|
|
<programlisting>
|
|
<xref linkend="opt-security.acme.certs"/>."foo.example.com" = {
|
|
<link linkend="opt-security.acme.certs._name_.webroot">webroot</link> = "/var/www/challenges";
|
|
<link linkend="opt-security.acme.certs._name_.email">email</link> = "foo@example.com";
|
|
};
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
The private key <filename>key.pem</filename> and certificate
|
|
<filename>fullchain.pem</filename> will be put into
|
|
<filename>/var/lib/acme/foo.example.com</filename>.
|
|
</para>
|
|
<para>
|
|
Refer to <xref linkend="ch-options" /> for all available configuration
|
|
options for the <link linkend="opt-security.acme.certs">security.acme</link>
|
|
module.
|
|
</para>
|
|
</section>
|
|
<section xml:id="module-security-acme-nginx">
|
|
<title>Using ACME certificates in Nginx</title>
|
|
|
|
<para>
|
|
NixOS supports fetching ACME certificates for you by setting
|
|
<literal><link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link>
|
|
= true;</literal> in a virtualHost config. We first create self-signed
|
|
placeholder certificates in place of the real ACME certs. The placeholder
|
|
certs are overwritten when the ACME certs arrive. For
|
|
<literal>foo.example.com</literal> the config would look like.
|
|
</para>
|
|
|
|
<programlisting>
|
|
services.nginx = {
|
|
<link linkend="opt-services.nginx.enable">enable = true;</link>
|
|
<link linkend="opt-services.nginx.virtualHosts">virtualHosts</link> = {
|
|
"foo.example.com" = {
|
|
<link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true;
|
|
<link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true;
|
|
locations."/" = {
|
|
<link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.root">root</link> = "/var/www";
|
|
};
|
|
};
|
|
};
|
|
}
|
|
</programlisting>
|
|
</section>
|
|
</chapter>
|