pyrox.dev
1<chapter xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xmlns:xi="http://www.w3.org/2001/XInclude"
4 version="5.0"
5 xml:id="module-security-acme">
6
7<title>SSL/TLS Certificates with ACME</title>
8
9<para>NixOS supports automatic domain validation & certificate
10retrieval and renewal using the ACME protocol. This is currently only
11implemented by and for Let's Encrypt. The alternative ACME client
12<literal>simp_le</literal> is used under the hood.</para>
13
14<section><title>Prerequisites</title>
15
16<para>You need to have a running HTTP server for verification. The server must
17have a webroot defined that can serve
18<filename>.well-known/acme-challenge</filename>. This directory must be
19writeable by the user that will run the ACME client.</para>
20
21<para>For instance, this generic snippet could be used for Nginx:
22
23<programlisting>
24http {
25 server {
26 server_name _;
27 listen 80;
28 listen [::]:80;
29
30 location /.well-known/acme-challenge {
31 root /var/www/challenges;
32 }
33
34 location / {
35 return 301 https://$host$request_uri;
36 }
37 }
38}
39</programlisting>
40</para>
41
42</section>
43
44<section><title>Configuring</title>
45
46<para>To enable ACME certificate retrieval & renewal for a certificate for
47<literal>foo.example.com</literal>, add the following in your
48<filename>configuration.nix</filename>:
49
50<programlisting>
51security.acme.certs."foo.example.com" = {
52 webroot = "/var/www/challenges";
53 email = "foo@example.com";
54};
55</programlisting>
56</para>
57
58<para>The private key <filename>key.pem</filename> and certificate
59<filename>fullchain.pem</filename> will be put into
60<filename>/var/lib/acme/foo.example.com</filename>. The target directory can
61be configured with the option <literal>security.acme.directory</literal>.
62</para>
63
64<para>Refer to <xref linkend="ch-options" /> for all available configuration
65options for the <literal>security.acme</literal> module.</para>
66
67</section>
68
69<section><title>Using ACME certificates in Nginx</title>
70<para>In practice ACME is mostly used for retrieval and renewal of
71 certificates that will be used in a webserver like Nginx. A configuration for
72 Nginx that uses the certificates from ACME for
73 <literal>foo.example.com</literal> will look similar to:
74</para>
75
76<programlisting>
77services.nginx.httpConfig = ''
78 server {
79 server_name foo.example.com;
80 listen 443 ssl;
81 ssl_certificate ${config.security.acme.directory}/foo.example.com/fullchain.pem;
82 ssl_certificate_key ${config.security.acme.directory}/foo.example.com/key.pem;
83 root /var/www/foo.example.com/;
84 }
85'';
86</programlisting>
87
88<para>Now Nginx will try to use the certificates that will be retrieved by ACME.
89 ACME needs Nginx (or any other webserver) to function and Nginx needs
90 the certificates to actually start. For this reason the ACME module
91 automatically generates self-signed certificates that will be used by Nginx to
92 start. After that Nginx is used by ACME to retrieve the actual ACME
93 certificates. <literal>security.acme.preliminarySelfsigned</literal> can be
94 used to control whether to generate the self-signed certificates.
95</para>
96</section>
97</chapter>