diff options
Diffstat (limited to 'nixos/modules/security/acme.xml')
| -rw-r--r-- | nixos/modules/security/acme.xml | 60 |
1 files changed, 52 insertions, 8 deletions
diff --git a/nixos/modules/security/acme.xml b/nixos/modules/security/acme.xml index f802faee974..8249da948c6 100644 --- a/nixos/modules/security/acme.xml +++ b/nixos/modules/security/acme.xml @@ -72,7 +72,7 @@ services.nginx = { "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; - # All serverAliases will be added as <link linkend="opt-security.acme.certs._name_.extraDomains">extra domains</link> on the certificate. + # All serverAliases will be added as <link linkend="opt-security.acme.certs._name_.extraDomainNames">extra domain names</link> on the certificate. <link linkend="opt-services.nginx.virtualHosts._name_.serverAliases">serverAliases</link> = [ "bar.example.com" ]; locations."/" = { <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.root">root</link> = "/var/www"; @@ -80,8 +80,8 @@ services.nginx = { }; # We can also add a different vhost and reuse the same certificate - # but we have to append extraDomains manually. - <link linkend="opt-security.acme.certs._name_.extraDomains">security.acme.certs."foo.example.com".extraDomains."baz.example.com"</link> = null; + # but we have to append extraDomainNames manually. + <link linkend="opt-security.acme.certs._name_.extraDomainNames">security.acme.certs."foo.example.com".extraDomainNames</link> = [ "baz.example.com" ]; "baz.example.com" = { <link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true; <link linkend="opt-services.nginx.virtualHosts._name_.useACMEHost">useACMEHost</link> = "foo.example.com"; @@ -115,15 +115,18 @@ services.nginx = { <programlisting> <xref linkend="opt-security.acme.acceptTerms" /> = true; <xref linkend="opt-security.acme.email" /> = "admin+acme@example.com"; + +# /var/lib/acme/.challenges must be writable by the ACME user +# and readable by the Nginx user. The easiest way to achieve +# this is to add the Nginx user to the ACME group. +<link linkend="opt-users.users._name_.extraGroups">users.users.nginx.extraGroups</link> = [ "acme" ]; + services.nginx = { <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 <link linkend="opt-services.nginx.virtualHosts._name_.serverAliases">serverAliases</link> = [ "*.example.com" ]; - # /var/lib/acme/.challenges must be writable by the ACME user - # and readable by the Nginx user. - # By default, this is the case. locations."/.well-known/acme-challenge" = { <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.root">root</link> = "/var/lib/acme/.challenges"; }; @@ -134,6 +137,7 @@ services.nginx = { }; } # Alternative config for Apache +<link linkend="opt-users.users._name_.extraGroups">users.users.wwwrun.extraGroups</link> = [ "acme" ]; services.httpd = { <link linkend="opt-services.httpd.enable">enable = true;</link> <link linkend="opt-services.httpd.virtualHosts">virtualHosts</link> = { @@ -162,10 +166,13 @@ services.httpd = { <xref linkend="opt-security.acme.certs"/>."foo.example.com" = { <link linkend="opt-security.acme.certs._name_.webroot">webroot</link> = "/var/lib/acme/.challenges"; <link linkend="opt-security.acme.certs._name_.email">email</link> = "foo@example.com"; + # Ensure that the web server you use can read the generated certs + # Take a look at the <link linkend="opt-services.nginx.group">group</link> option for the web server you choose. + <link linkend="opt-security.acme.certs._name_.group">group</link> = "nginx"; # Since we have a wildcard vhost to handle port 80, # we can generate certs for anything! # Just make sure your DNS resolves them. - <link linkend="opt-security.acme.certs._name_.extraDomains">extraDomains</link> = [ "mail.example.com" ]; + <link linkend="opt-security.acme.certs._name_.extraDomainNames">extraDomainNames</link> = [ "mail.example.com" ]; }; </programlisting> @@ -187,7 +194,7 @@ services.httpd = { <para> This is useful if you want to generate a wildcard certificate, since ACME servers will only hand out wildcard certs over DNS validation. - There a number of supported DNS providers and servers you can utilise, + There are 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 docs, we will provide a fully self-hosted example using bind. @@ -251,4 +258,41 @@ chmod 400 /var/lib/secrets/certs.secret journalctl -fu acme-example.com.service</literal> and watching its log output. </para> </section> + <section xml:id="module-security-acme-regenerate"> + <title>Regenerating certificates</title> + + <para> + Should you need to regenerate a particular certificate in a hurry, such + as when a vulnerability is found in Let's Encrypt, there is now a convenient + mechanism for doing so. Running + <literal>systemctl clean --what=state acme-example.com.service</literal> + will remove all certificate files and the account data for the given domain, + allowing you to then <literal>systemctl start acme-example.com.service</literal> + to generate fresh ones. + </para> + </section> + <section xml:id="module-security-acme-fix-jws"> + <title>Fixing JWS Verification error</title> + + <para> + It is possible that your account credentials file may become corrupt and need + to be regenerated. In this scenario lego will produce the error <literal>JWS verification error</literal>. + The solution is to simply delete the associated accounts file and + re-run the affected service(s). + </para> + +<programlisting> +# Find the accounts folder for the certificate +systemctl cat acme-example.com.service | grep -Po 'accounts/[^:]*' +export accountdir="$(!!)" +# Move this folder to some place else +mv /var/lib/acme/.lego/$accountdir{,.bak} +# Recreate the folder using systemd-tmpfiles +systemd-tmpfiles --create +# Get a new account and reissue certificates +# Note: Do this for all certs that share the same account email address +systemctl start acme-example.com.service +</programlisting> + + </section> </chapter> |