nixos/acme: update documentation #86347

m1cr0man · 2020-04-29T19:36:15Z

Motivation for this change

Revamped the documentation for generating certs as a whole, on top of
adding instructions for DNS validation. I also updated the docs for security.acme.certs.<name>.extraDomains since alt webroots are not supported.

These docs should be updated again when #83474 is merged, since it is unlikely users
want to set up a whole DNS server just for certificates.

Things done

Mic92 · 2020-04-29T21:32:50Z

Thanks for writing this!

emilazy

LGTM. Recommending BIND pains me, but it's good to have a working DNS-01 example :)

flokli

Thanks a lot for writing this together :-) Some comments.

flokli · 2020-04-30T09:44:48Z

nixos/modules/security/acme.nix

-          A list of extra domain names, which are included in the one certificate to be issued, with their
-          own server roots if needed.
+          A list of extra domain names, which are included in the one certificate to be issued.
+          Setting a distinct server root is deprecated and not functional in 20.03+


Suggested change

Setting a distinct server root is deprecated and not functional in 20.03+

Support for configuring distinct challenge webroots has been dropped.

Challenges are saved from the same folder.

I had to think two times here what "server root" means.

This was a way to provide an alternative webroot to serve challenges for that specific domain.

Am I right to assume lego doesn't support that anymore, and we put all challenges into the same folder (and nginx for example defaults the per-vhost acmeRoot option to the same locaiton).

We should also add this to the 20.03 release notes.

Correct, no support from lego. I'll add it to the release notes.

flokli · 2020-04-30T09:49:32Z

nixos/modules/security/acme.xml

@@ -10,88 +10,238 @@
  for Let's Encrypt. The alternative ACME client <literal>lego</literal> is


we support more than Let's Encrypt, via security.acme.server. One could also use Buypass, or an internal ACME server.

Yeah, that was hangover from the original docs. I'll make it more open about other providers :)

flokli · 2020-04-30T09:49:49Z

nixos/modules/security/acme.xml

+   This address is only used for registration and renewal reminders,
+   and cannot be used to administer the certificates in any way.
+  </para>
+


We should add a note here explaining security.acme.server too.

flokli · 2020-04-30T09:50:52Z

nixos/modules/security/acme.xml

+<xref linkend="opt-security.acme.acceptTerms" /> = true;
+<xref linkend="opt-security.acme.email" /> = "admin+acme@example.com";
+services.nginx = {
+  <link linkend="opt-services.nginx.enable">enable = true;</link>


Suggested change

<link linkend="opt-services.nginx.enable">enable = true;</link>

<link linkend="opt-services.nginx.enable"> = true;</link>

or does this render differently?

I'd personally prefer the <link linkend="…">…</link> syntax, as used below.

Yeah link renders nothing on its own whereas xref puts in the option path. Although, I noticed the close tag was in the wrong place, fixed now.

flokli · 2020-04-30T09:58:19Z

nixos/modules/security/acme.xml

  </para>
 </section>
 <section xml:id="module-security-acme-configuring">
-  <title>Configuring</title>
+  <title>Manual configuration of HTTP-01 validation</title>


When do we need the manual way?

Doesn't the module system provide a much more convenient way to do this?

I feel it's good to keep this for 2 reasons, one is so people know how to integrate it with existing setups where maybe they do want to use port 80 for things and have a vhost there, and secondly explaining how the system works so that it can be adapted for other web servers is important.

I'm mostly worried about people just quickly skimming over this, and thinking "OMG, is this complicated". But as the easy setup is just on the same page, it should be fine. 🤔

I like this section. It's always good to show as many example setup as possible. It's in a different section clearly stating this is a manual conf. I think this is fine!

flokli · 2020-04-30T09:58:59Z

nixos/modules/security/acme.xml

-   certs are overwritten when the ACME certs arrive. For
-   <literal>foo.example.com</literal> the config would look like.
+   This is useful if you want to generate a wildcard certificate, since
+   Let's Encrypt will only hand out wildcard certs over DNS validation.


Suggested change

Let's Encrypt will only hand out wildcard certs over DNS validation.

ACME servers will only hand out wildcard certs over DNS validation.

flokli · 2020-04-30T10:02:13Z

nixos/modules/security/acme.xml

+   Nix config. Instead, generate them one time with these commands:
+  </para>
+
+<programlisting>


There's no such /var/secrets in nixpkgs. There's /run/keys for nonlocal secrets, and some occurences of/var/lib/secrets for more persistent ones. I'd propose to use the latter in this example.

/var/secrets is a personal preference, I'll change it to /var/lib/secrets 👍

flokli · 2020-04-30T10:02:55Z

nixos/modules/security/acme.xml

+  <para>
+   Now you're all set to generate certs! You should monitor the first invokation
+   by running <literal>systemctl start acme-example.com.service &amp;
+   journalctl -fu acme-example.com.service</literal> and watching for errors.


Suggested change

journalctl -fu acme-example.com.service</literal> and watching for errors.

journalctl -fu acme-example.com.service</literal> and watching for its log output.

That's a bit pessimistic :-D

m1cr0man · 2020-05-01T17:51:30Z

Thanks for the solid review @flokli ! I've made those changes now :)

picnoir

Thanks a lot for this, it's super useful <3!

LGTM.

See the comments for a remark and a couple style nitpicks.

picnoir · 2020-05-01T19:23:38Z

nixos/modules/security/acme.nix

-          A list of extra domain names, which are included in the one certificate to be issued, with their
-          own server roots if needed.
+          A list of extra domain names, which are included in the one certificate to be issued.
+          Setting a distinct server root is deprecated and not functional in 20.03+


This might be off-topic for this PR, but on top of this message, could we generate a eval-time warning using the assertion module

nixpkgs/nixos/modules/misc/assertions.nix

Line 21 in b67bc34

warnings = mkOption {

if acmeRoot!=null here?

Do we plan to backport this commit to 19.09? If not, I think this is safe to assume this option is deprecated and not functional, hence dropping the in 20.03+ part of this message.

Also, maybe it's also time to remove the acme root from this example:

nixpkgs/nixos/modules/security/acme.nix

Line 253 in c9f6e5f

extraDomains = { "www.example.com" = null; "foo.example.com" = "/var/www/foo/"; };

So I actually tried doing that back when I did the DNS-01 update, but I couldn't figure out how to add a deprecation warning to a submodule (which is what the certs are). When I rewrite the whole module I'm actually going to add a warning and a rewrite rule to change them to a list.

picnoir · 2020-05-01T19:28:10Z

nixos/modules/security/acme.xml

+  </para>
+
+  <para>
+   You will need an HTTP server or DNS server for verification. For HTTP,


Suggested change

You will need an HTTP server or DNS server for verification. For HTTP,

You will need an HTTP or DNS server to perform the verification. For an HTTP verification,

Style nitpick, feel free to ignore if you don't like it.

Well, the verification is more of a process so a proper noun rather than a concrete noun, personally I think it reads more naturally the way it is.

picnoir · 2020-05-01T19:29:42Z

nixos/modules/security/acme.xml

   <filename>.well-known/acme-challenge</filename>. This directory must be
-   writeable by the user that will run the ACME client.
+   writeable by the user that will run the ACME client. For DNS, you must


Suggested change

writeable by the user that will run the ACME client. For DNS, you must

writeable by the user that will run the ACME client. For a DNS verification, you must

Style nitpick, feel free to ignore if you don't like it.

picnoir · 2020-05-01T19:34:50Z

nixos/modules/security/acme.xml

+ <para>
+  Automatic cert validation and configuration for Apache and Nginx virtual
+  hosts is included in NixOS, however if you would like to generate a wildcard
+  cert or you are not using a web server you will have to configure DNS


Suggested change

cert or you are not using a web server you will have to configure DNS

cert or you are not using a web server you will have to use a DNS

Style nitpick, feel free to ignore if you don't like it.

picnoir · 2020-05-01T19:40:13Z

nixos/modules/security/acme.xml

  </para>
 </section>
 <section xml:id="module-security-acme-configuring">
-  <title>Configuring</title>
+  <title>Manual configuration of HTTP-01 validation</title>


I like this section. It's always good to show as many example setup as possible. It's in a different section clearly stating this is a manual conf. I think this is fine!

flokli · 2020-05-04T12:13:33Z

Thanks everyone! @m1cr0man this can probably also be backported to 20.03, right?

m1cr0man · 2020-05-04T12:14:52Z

Yeah, it can. I'll create a backport PR.

NANASHI0X74 · 2020-11-08T19:48:50Z

nixos/modules/security/acme.xml

-  }
+    # 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;


This should be commented out or moved out of the services.nginx.virtualhost attribute set I think- at the moment it looks like there should be an option services.nginx.virtualhosts.security.acme.certs.extraDomains, which doesn't exist afaic

nixos/acme: update documentation

47da7aa

ofborg bot added 6.topic: nixos 8.has: module (update) 10.rebuild-darwin: 0 10.rebuild-linux: 1-10 10.rebuild-linux: 1 labels Apr 29, 2020

worldofpeace requested a review from a team April 29, 2020 21:32

emilazy approved these changes Apr 29, 2020

View reviewed changes

flokli requested a review from picnoir April 30, 2020 09:24

flokli reviewed Apr 30, 2020

View reviewed changes

nixos/acme: indicate support for other providers

c9f6e5f

picnoir approved these changes May 1, 2020

View reviewed changes

nixos/acme: fix incorrect example

037ef70

flokli requested review from picnoir and emilazy May 3, 2020 00:28

picnoir approved these changes May 4, 2020

View reviewed changes

flokli merged commit 7457c78 into NixOS:master May 4, 2020

m1cr0man mentioned this pull request May 4, 2020

[20.03] nixos/acme: update documentation #86769

Merged

10 tasks

flokli mentioned this pull request May 11, 2020

acme-dns: init at 0.8 #83474

Closed

10 tasks

m1cr0man deleted the dnsdocs branch October 6, 2020 20:10

NANASHI0X74 reviewed Nov 8, 2020

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

nixos/acme: update documentation #86347

nixos/acme: update documentation #86347

m1cr0man commented Apr 29, 2020

Mic92 commented Apr 29, 2020

emilazy left a comment

flokli left a comment

flokli Apr 30, 2020

m1cr0man May 1, 2020

flokli Apr 30, 2020

m1cr0man May 1, 2020

flokli Apr 30, 2020

flokli Apr 30, 2020

m1cr0man May 1, 2020

flokli Apr 30, 2020

m1cr0man May 1, 2020

flokli May 1, 2020

picnoir May 1, 2020

flokli Apr 30, 2020

flokli Apr 30, 2020

m1cr0man May 1, 2020

flokli Apr 30, 2020

m1cr0man commented May 1, 2020

picnoir left a comment •

edited

picnoir May 1, 2020

picnoir May 1, 2020

m1cr0man May 1, 2020

picnoir May 1, 2020

m1cr0man May 1, 2020

picnoir May 1, 2020

picnoir May 1, 2020

picnoir May 1, 2020

flokli commented May 4, 2020

m1cr0man commented May 4, 2020

NANASHI0X74 Nov 8, 2020

	Setting a distinct server root is deprecated and not functional in 20.03+
	Support for configuring distinct challenge webroots has been dropped.
	Challenges are saved from the same folder.

		@@ -10,88 +10,238 @@
		for Let's Encrypt. The alternative ACME client <literal>lego</literal> is

	<link linkend="opt-services.nginx.enable">enable = true;</link>
	<link linkend="opt-services.nginx.enable"> = true;</link>

	Let's Encrypt will only hand out wildcard certs over DNS validation.
	ACME servers will only hand out wildcard certs over DNS validation.

	journalctl -fu acme-example.com.service</literal> and watching for errors.
	journalctl -fu acme-example.com.service</literal> and watching for its log output.

	You will need an HTTP server or DNS server for verification. For HTTP,
	You will need an HTTP or DNS server to perform the verification. For an HTTP verification,

	writeable by the user that will run the ACME client. For DNS, you must
	writeable by the user that will run the ACME client. For a DNS verification, you must

	cert or you are not using a web server you will have to configure DNS
	cert or you are not using a web server you will have to use a DNS

nixos/acme: update documentation #86347

nixos/acme: update documentation #86347

Conversation

m1cr0man commented Apr 29, 2020

Motivation for this change

Things done

Mic92 commented Apr 29, 2020

emilazy left a comment

Choose a reason for hiding this comment

flokli left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

m1cr0man commented May 1, 2020

picnoir left a comment • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

flokli commented May 4, 2020

m1cr0man commented May 4, 2020

Choose a reason for hiding this comment

picnoir left a comment •

edited