Make installation instructions more comprehensive

[Daniel15]

It was pretty tricky to work out what to do... Hopefully these instructions help someone. Feel free to modify or rewrite anything I've written if you don't like it 😃

[coveralls]

Coverage remained the same at 92.244% when pulling 0991b3e on Daniel15:patch-2 into 7b2203c on joohoi:master.

[joohoi]

Thanks for the PR! I think this is really valuable information for the users. However I feel that while the step 6 (adding NS and A recods) should be added to the installation instructions, the other points should probably be placed under a new title of Troubleshooting for clarity.

[joohoi]

The data for register endpoint can be left out if no whitelisting is needed.

[joohoi]

I feel that in examples it would be better to use address in a private address space defined by RFC 1918

[Yannik]

198.51.100.1 is actually a reserved IP address for documentation purposes: https://tools.ietf.org/html/rfc5737

I'm in favor of keeping it, rather than using a private address.

[joohoi]

Yeah, @Daniel15 cleared that up in the comment, and I learned something. I'm in favor of keeping this as well.

[Yannik]

Ah, didn't see that.

[joohoi]

It could be useful to underline that the TXT content needs to be exactly 43 characters long. That's a common source of confusion.

[jvanasco]

+1 to this. I tried setting a test value to make sure everything worked before hitting the LetsEncrypt API

    --data '{"subdomain": "foo", "txt": "bar"}'

It took me a few tries and diving into source to understand why that failed.

[Daniel15]

198.51.100.0/24 is explicitly reserved for use in documentation (RFC 5737) which is why I used that particular IP. I didn't want readers to mistake it for an actual internal IP. I'll take a look at the rest of your comments this week some time :) Sent from my phone.

…

On Mon, Mar 19, 2018, 1:29 AM Joona Hoikkala ***@***.***> wrote: ***@***.**** requested changes on this pull request. Thanks for the PR! I think this is really valuable information for the users. However I feel that while the step 6 (adding NS and A recods) should be added to the installation instructions, the other points should probably be placed under a new title of Troubleshooting for clarity. ------------------------------ In README.md <#64 (comment)>: > +5) Confirm that acme-dns is working by performing a DNS lookup for one of the predefined records configured in the `config.cfg` file: `dig @198.51.100.1 auth.example.com`. This should be logged in acme-dns' output: +``` +DEBU[0003] Answering question for domain domain=auth.example.com. qtype=A +``` + +If this request times out, ensure that port 53 is open in your firewall. + +6) On your domain's regular DNS server, add an `NS` record for `auth.example.com` pointing to `ns.auth.example.com`, and an `A` record for `ns.auth.example.com` pointing to `198.51.100.1` If using IPv6, use an AAAA record rather than an A record. + +7) Wait a few minutes for DNS changes to propagate + +8) Confirm that DNS lookups for the acme-dns subdomain works as expected: `dig auth.example.com` + +9) Call the `/register` API endpoint to register a test domain: +``` +$ curl -X POST -d "{}" http://auth.example.com/register The data for register endpoint can be left out if no whitelisting is needed. ------------------------------ In README.md <#64 (comment)>: > @@ -111,14 +111,54 @@ Check out how in the INSTALL section. ## Installation +In all the commands listed below: +- `example.com` is your domain name +- `auth.example.com` is the subdomain you want to use for acme-dns +- `198.51.100.1` is the **public** IP address of the system running acme-dns I feel that in examples it would be better to use address in a private address space defined by RFC 1918 <https://tools.ietf.org/html/rfc1918> ------------------------------ In README.md <#64 (comment)>: > + +If this request times out, ensure that port 53 is open in your firewall. + +6) On your domain's regular DNS server, add an `NS` record for `auth.example.com` pointing to `ns.auth.example.com`, and an `A` record for `ns.auth.example.com` pointing to `198.51.100.1` If using IPv6, use an AAAA record rather than an A record. + +7) Wait a few minutes for DNS changes to propagate + +8) Confirm that DNS lookups for the acme-dns subdomain works as expected: `dig auth.example.com` + +9) Call the `/register` API endpoint to register a test domain: +``` +$ curl -X POST -d "{}" http://auth.example.com/register +{"username":"eabcdb41-d89f-4580-826f-3e62e9755ef2","password":"pbAXVjlIOE01xbut7YnAbkhMQIkcwoHO0ek2j4Q0","fulldomain":"d420c923-bbd7-4056-ab64-c3ca54c9b3cf.auth.example.com","subdomain":"d420c923-bbd7-4056-ab64-c3ca54c9b3cf","allowfrom":[]} +``` + +10) Call the `/update` API endpoint to set a test TXT record: It could be useful to underline that the TXT content needs to be exactly 43 characters long. That's a common source of confusion. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#64 (review)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAFnHX8SJ4Hf4TDrminw8l8l17ue7eEMks5tf2xMgaJpZM4Svqnd> .

[joohoi]

198.51.100.0/24 is explicitly reserved for use in documentation (RFC 5737)

Awesome! That's completely fine in this case. TIL :)

[Daniel15]

@joohoi I moved some stuff around, let me know what you think of it now :)

[jvanasco]

A lot of people turn off DNS on their firewall (e.g. iptables, ufw, etc )

I think it would be a good addition to remind people to ensure port 53 is open.

[joohoi]

LGTM! merging

[gregwkeller]

Consider updating the systemd section to include this step:

"As of systemd 232 (released in 2017) you can edit /etc/systemd/resolved.conf and add this line:

DNSStubListener=no"

Otherwise the Stub Listener blocks ACME-DNS