JakeHillion/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

nixos docs: update for Nginx + ACME (#21320)

Browse Source 
Closes #20698.
This commit is contained in:
teh 2017-01-09 05:39:10 +00:00 committed by Franz Pletz
parent 1753d8c878
commit a878365b77
1 changed files with 20 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
nixos/modules/security/acme.xml
View File

@ -67,52 +67,30 @@ options for the <literal>security.acme</literal> module.</para>
</section>
<section><title>Using ACME certificates in Nginx</title>
<para>In practice ACME is mostly used for retrieval and renewal of
certificates that will be used in a webserver like Nginx. A configuration for
Nginx that uses the certificates from ACME for
<literal>foo.example.com</literal> will look similar to:
<para>NixOS supports fetching ACME certificates for you by setting
<literal>enableACME = 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>
security.acme.certs."foo.example.com" = {
webroot = config.security.acme.directory + "/acme-challenge";
email = "foo@example.com";
user = "nginx";
group = "nginx";
postRun = "systemctl restart nginx.service";
};
services.nginx.httpConfig = ''
server {
server_name foo.example.com;
listen 80;
listen [::]:80;
location /.well-known/acme-challenge {
root /var/www/challenges;
}
location / {
return 301 https://$host$request_uri;
}
}
server {
server_name foo.example.com;
listen 443 ssl;
ssl_certificate ${config.security.acme.directory}/foo.example.com/fullchain.pem;
ssl_certificate_key ${config.security.acme.directory}/foo.example.com/key.pem;
root /var/www/foo.example.com/;
}
'';
services.nginx = {
enable = true;
virtualHosts = {
"foo.example.com" = {
forceSSL = true;
enableACME = true;
locations."/" = {
root = "/var/www";
};
};
};
}
</programlisting>
<para>Now Nginx will try to use the certificates that will be retrieved by ACME.
ACME needs Nginx (or any other webserver) to function and Nginx needs
the certificates to actually start. For this reason the ACME module
automatically generates self-signed certificates that will be used by Nginx to
start. After that Nginx is used by ACME to retrieve the actual ACME
certificates. <literal>security.acme.preliminarySelfsigned</literal> can be
used to control whether to generate the self-signed certificates.
</para>
<para>At the moment you still have to restart Nginx after the ACME
certs arrive.</para>
</section>
</chapter>