commit a878365b77e2bad4f11731072c3d2b79d1b40b04 · pyrox.dev/nixpkgs

+20 -42
nixos/modules/security/acme.xml
···

       67
       67
        
       </section>

     

       68
       68
        
       

     

       69
       69
        
       <section><title>Using ACME certificates in Nginx</title>

     

       70
       70
       -
       <para>In practice ACME is mostly used for retrieval and renewal of

     

       71
       71
       -
         certificates that will be used in a webserver like Nginx. A configuration for

     

       72
       72
       -
         Nginx that uses the certificates from ACME for

     

       73
       73
       -
         <literal>foo.example.com</literal> will look similar to:

     

       70
       70
       +
       <para>NixOS supports fetching ACME certificates for you by setting

     

       71
       71
       +
       <literal>enableACME = true;</literal> in a virtualHost config. We

     

       72
       72
       +
       first create self-signed placeholder certificates in place of the

     

       73
       73
       +
       real ACME certs. The placeholder certs are overwritten when the ACME

     

       74
       74
       +
       certs arrive. For <literal>foo.example.com</literal> the config would

     

       75
       75
       +
       look like.

     

       74
       76
        
       </para>

     

       75
       77
        
       

     

       76
       78
        
       <programlisting>

     

       77
       77
       -
       security.acme.certs."foo.example.com" = {

     

       78
       78
       -
         webroot = config.security.acme.directory + "/acme-challenge";

     

       79
       79
       -
         email = "foo@example.com";

     

       80
       80
       -
         user = "nginx";

     

       81
       81
       -
         group = "nginx";

     

       82
       82
       -
         postRun = "systemctl restart nginx.service";

     

       83
       83
       -
       };

     

       84
       84
       -
       services.nginx.httpConfig = ''

     

       85
       85
       -
         server {

     

       86
       86
       -
           server_name foo.example.com;

     

       87
       87
       -
           listen 80;

     

       88
       88
       -
           listen [::]:80;

     

       89
       89
       -
       

     

       90
       90
       -
           location /.well-known/acme-challenge {

     

       91
       91
       -
             root /var/www/challenges;

     

       92
       92
       -
           }

     

       93
       93
       -
       

     

       94
       94
       -
           location / {

     

       95
       95
       -
             return 301 https://$host$request_uri;

     

       96
       96
       -
           }

     

       97
       97
       -
         }

     

       98
       98
       -
       

     

       99
       99
       -
         server {

     

       100
       100
       -
           server_name foo.example.com;

     

       101
       101
       -
           listen 443 ssl;

     

       102
       102
       -
           ssl_certificate     ${config.security.acme.directory}/foo.example.com/fullchain.pem;

     

       103
       103
       -
           ssl_certificate_key ${config.security.acme.directory}/foo.example.com/key.pem;

     

       104
       104
       -
           root /var/www/foo.example.com/;

     

       105
       105
       -
         }

     

       106
       106
       -
       '';

     

       79
       79
       +
       services.nginx = {

     

       80
       80
       +
         enable = true;

     

       81
       81
       +
         virtualHosts = {

     

       82
       82
       +
           "foo.example.com" = {

     

       83
       83
       +
             forceSSL = true;

     

       84
       84
       +
             enableACME = true;

     

       85
       85
       +
             locations."/" = {

     

       86
       86
       +
               root = "/var/www";

     

       87
       87
       +
             };

     

       88
       88
       +
           };

     

       89
       89
       +
         };

     

       90
       90
       +
       }

     

       107
       91
        
       </programlisting>

     

       108
       92
        
       

     

       109
       109
       -
       <para>Now Nginx will try to use the certificates that will be retrieved by ACME.

     

       110
       110
       -
         ACME needs Nginx (or any other webserver) to function and Nginx needs

     

       111
       111
       -
         the certificates to actually start. For this reason the ACME module

     

       112
       112
       -
         automatically generates self-signed certificates that will be used by Nginx to

     

       113
       113
       -
         start. After that Nginx is used by ACME to retrieve the actual ACME

     

       114
       114
       -
         certificates. <literal>security.acme.preliminarySelfsigned</literal> can be

     

       115
       115
       -
         used to control whether to generate the self-signed certificates.

     

       116
       116
       -
       </para>

     

       93
       93
       +
       <para>At the moment you still have to restart Nginx after the ACME

     

       94
       94
       +
       certs arrive.</para>

     

       117
       95
        
       </section>

     

       118
       96
        
       </chapter>