Error glossary on website, directly linked from Boulder errors

Posting an idea I shared privately:

For some time I’ve had an idea about a dual improvement that could be made to Boulder and to the letsencrypt.org website.

The problem
Error messages presented by ACME clients aren’t good enough for people to solve their own problems.

Beneath that, Boulder’s error messages aren’t as helpful as they could be. Something like “connection timed out” or “NXDOMAIN” doesn’t really cut it if you don’t have an expert level of knowledge.

There have been multiple efforts to improve Boulder’s error messages, but you can only reasonably pack so much information into a single string before it becomes overwhelming.

Proposed improvement
I want errors produced by Boulder to include a link to an error-specific page or anchor on the letsencrypt.org website.

The page would contain a human-friendly explanation and actionable steps to solve the problem.

The extra space to elaborate and ability to convey information visually should improve the ability for users to help themselves before reaching out to (possibly the wrong people) for help.

It might also save client developers from having to include generic text like this (e.g. in Certbot):

To fix these errors, please make sure that your domain name was
entered correctly and the DNS A/AAAA record(s) for that domain
contain(s) the right IP address.

Example
Where the ACME error detail currently produced by Boulder is:

No valid IP addresses found for ic.gov

I propose changing it to something like:

No valid IP addresses found for ic.gov (see https://letsencrypt.org/docs/errors#NO-VALID-IP for more information)

In turn, the anchor/page would contain copy such as (not a well thought-out example, just to demonstrate):

When Let’s Encrypt tried to connect to your domain name in order to verify your control of it, it could not find a public IP address to connect to.

When using HTTP or TLS-ALPN validation, your website must be accessible on the public internet. For example, a random person in the world should be able to connect to it from their mobile device. This means that your domain name must have a DNS record pointing to a public IP address (not a private IP address).

Solution
You need to be able to answer these questions:

  1. What is the public IP address of my website or server?
  2. Who is my DNS host? (You may use <this tool> to identify it).

Once you know the answer to both these questions, login to your DNS host’s control panel, and add a DNS record for your domain, pointing to your server’s public IP address.

If you are unsure how to do this, ask your DNS host. Here are some links from popular DNS hosts showing how to perform the process:

Asking for help
If you continue to have problems with this issue, please post a question under the “Help” section of https://community.letsencrypt.org .


That’s about it.

If it works, and my understanding of how people post threads is not dramatically wrong, we should see help threads where some more substantial problem solving efforts have been made.

Any kind of feedback would be great.

5 Likes

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.