Let's make Let's Encrypt easy and simple

Help
103

danb35, “You also have a lot of what appear to be bizarre non sequiturs that you don’t appear to be interested in discussing once you’ve tossed the ideas out there.” I believe you are incorrect. First, demonstrate that I write “non sequiturs”, don’t just throw out a general accusation.

You seem very quick to attack me about “AI”, yet you didn’t wait for my reply concerning it. Prove that I am “not interested in discussing” any ideas I write about. True, there is a short delay (about an hour) involved in this site sending me notice of a posting, but I usually respond to comment threads as soon as I hear about them. Occasionally there must be an additional delay caused by my being busy. But such delays are true for all of us; why attack me in particular for my slowness to respond to questions about my ideas?

It is true that the attacks by a few people here make me want to leave and never come back, but that is a feeling, and a feeling doesn’t make me a “troll”. A troll is usually defined as someone who posts once, provocatively, to get a reaction which they read and enjoy. I engage in sometimes lengthy threads where I defend my ideas. And I do not enjoy the attacks that happen here, no way.

I persist not to annoy, but because I would like to see LE succeed in its goals and promises. I have been working hard in this particular thread to get the Get Started page rewritten so it manages user expectations. Currently, it promises simplicity and universality, neither of which are true for many users, perhaps for most users. I have suggested that we do usage experiments. I have suggested we survey users for their experiences. I have suggested we improve our documentation. I am not a “troll” and I resent being repeatedly attacked in violation of the community guidelines here.

1 Like
104

This thread is getting very flamey. I’d like to encourage everyone to only participate if you can do so in a civilized way. I would also recommend to refrain from repeating the same discussion over and over again, as doing so will hardly lead to any new conclusions. If you think a post is inappropriate, flag it and wait for someone to reply to the flag. Engaging in the discussion even though you think a post is inappropriate only encourages that behaviour.

1 Like
105

pfg, Thank you very much for your intervention. I will follow your advice.

1 Like
106

With that reasoning any loop, any conditional branch in a program is "AI", which is nonsense.

1 Like
107

My colleague Noah and I are proposing some documentation improvements at

in response to @denaje’s feedback. I would be happy to hear from anyone about things we may have missed or that could be phrased or structured more clearly. And thanks again for the detailed comments.

4 Likes
108

One hurdle to overcome is how to configure Apache, Nginx etc to have strong configurations. It really should be anyone’s goal to have an A+ on https://www.ssllabs.com/ssltest/, I think. But precisely what configuration is necessary to achieve that is not clear without some research and more understanding of the technology than the average user has these days.

1 Like
109

I think for that https://mozilla.github.io/server-side-tls/ssl-config-generator/ should be used (and it is easy to use) - when one wants to configure it manually.

1 Like
110

I seem to have learned more from this thread than from searching for documentation, reading how-to’s on other sites and experimenting.

When to use certbot and when to use letsencrypt is still not clear, for instance.

There is no link to the certbot docs on the let’s encrypt site. At least, not a prominent link. It’s not in the menu, fi. I had to find it in this thread.

The forum is a good resource, but too many questions are going unanswered. That is a bit frustrating when googling errors. And I haven’t found a comprehensive error list either, so it’s a bit hard to imagine what goes wrong.

And things do go wrong. Because I don’t understand what I’m doing. Even with the ncurses interface, there’s hardly any feedback. A simple example: when creating a certificate, it could mention that you need to install that cert before it works. That alone has cost me hours of frustration, because the process succeeded, but I didn’t understand.

I have installed certs before, and, frankly, this system isn’t better or easier. And that’s just for a lack of documentation.

Letsencrypt and certbot certainly are nice and work well. But they fail from the ergonomic point of view. Please, include some links for additional info in the ncurses interface, fi.

I know that making how-to’s for each and every possible config isn’t feasible. But there are none now and that is fine if you know what you’re doing, but you have to presume that the vast majority of your potential users are newbies, no matter what their level of expertise is.

And, you know, I’ve spent almost two days on getting certificates for a dozen domains. The answer to my blindness was in this thread. I never could have googled what I didn’t know…

1 Like
111

cyrano, It makes me very unhappy and upset to read your posting. Users of Letsencrypt technology should find it easy to use and easy to find answers when problems arise.

The people who reply on this forum have an amazing amount of knowledge about SSL in general and LE in particular; just look at some of their incredibly helpful replies in this forum, outside of this thread. That they apparently do not have the ability or interest to set up a single page that summarizes the frequently-arising questions and that has a big link to this forum as the place to find answers, is inexcusable, especially since this project has been in existence so long, and has accomplished so much in the direction of its goal in making the Web secure.

I’ve tried my best to push, here in this thread, for better documentation, and have frequently gotten attacked, to the point where I mostly gave up. If the attackers (and defenders of their realm) had put that energy into improving the documentation, the project would have benefited greatly. Attacking the messenger is not a good substitute for thoughtful documentation improvement. cyrano’s posting shows that the documentation is stll faulty. Believe me, if I myself knew enough to improve the documentation, I would have done it myself long ago. The people who have the knowledge need to wake up and recognize the area of greatest need in this project.

Note: the above is opinion, not fact. If my opinion is wrong, please explain why instead of attacking me for trying to improve the main weak area of the project.

1 Like
112

Certbot has replaced letsencrypt. In any instance where you would have used letsencrypt, you should now use certbot. If you want to use one of the many alternative clients, that's up to you (and there are plenty of good reasons to use one of them in many circumstances), but you can't reasonably expect the official docs to cover all (or any, really) of them.

Certbot is maintained by the EFF, not by Let's Encrypt proper. The Getting Started page links to the EFF's Certbot page, which itself documents that software.

There are many how-tos, written by many people, in many places. The diversity is kind of a problem, but it's a common one with open-source software. The Certbot page has a walkthrough for many popular webservers and operating systems.

2 Likes
113

No, Dan, for me certbot has NOT replaced letsencrypt.

I had letsencrypt installed and, because it is not explained anywhere, also installed certbot. Nothing got replaced and it is very well possible that some or even all of my troubles are because of having both.

The same question poses itself when it comes to upgrades. Is there an upgrade mechanism? Or a security upgrade system? Ot are these entirely left to the user, to do? And how is the user to know about upgrades and sec patches?

There are not many how-to’s, as you’ve already succeeded in making most of them obsolete.

I mean, how old is this project? It already changed it’s name by the transition to certbot and generated many clones. Very, very confusing.

And nowhere in the docs it is explained what each of these programs do. If you read the docs, you’re bound to be left with the impression that it is a “client” and a “server”. And you can’t use a client without a server, can you?

Now I hear it is not. It is a replacement, from another entity, with other documentation, which shares some of the purpose and some of the commands. But apparently, not all.

If certbot’s purpose is to replace letsencrypt, I’d expect at least a link to those docs in the menu on the letsencrypt website. Now there’s one link on the “getting started” page. Hardly prominent, or easy to find.

What I see in this thread, is people meandering in denial of the problem.

If you want to take on every website maintainer, you need docs for ordinary people, not for geeks that already know half the story.

1 Like
114

That's unlikely. It's the same program, the same code - it has just been renamed, and features have been added, as would have happened without a name change. All configuration files are fully compatible. You could have continued using letsencrypt-auto, and things would've kept working, or you could have switched to certbot-auto, and things would've worked just as well, without any real "upgrade" step, just another installation.

If you're using the letsencrypt-auto or certbot-auto version of the client, the client updates itself whenever it runs. Everything taken care of. If you're using one of the packages provided by your distribution, you'll receive updates as they publish them (as with any other distribution package).

In hindsight, the client development should've been separated from the server/protocol development right away, but that's easy to say now. What's important to know is that Let's Encrypt spawned a new protocol (ACME) that's intended to become an internet standard. In that context, a comparable statement would be "HTTP generated many clones and is very confusing" because there are many different HTTP servers and clients. It's true enough, but the alternative would be a proprietary API and client, giving Let's Encrypt full control over the ecosystem, which does not sound like a good path forward to me. This path might be a bit messier, but once the dust settles the advantages will be obvious.

I don't follow this paragraph. The server is what Let's Encrypt provides - the CA server, which verifies domain ownership and signs your certificate. You should not have to worry about server-related things. Which part of the documentation gave you that impression?

It's a drop-in replacement, configuration is compatible and command-line options are essentially the same as well.
It's really just a name change.

It's hard to discuss the shortcomings of the current documentation and possible improvements without knowing what the actual problem was in your case. Disregarding the confusion about the client being renamed, do you feel like the current certbot documentation would have been sufficient to get you set up, and if not, where is it lacking?

2 Likes
115

Then that would be a problem with the software you've installed, and how you've installed it. The change was announced four months ago:

Of course there is, as with any software. What that mechanism is will depend very much on your operating system and how you installed the software in the first place.

How do you learn of upgrades and security patches for any other software installed on your system?

I have made nothing obsolete, as I'm not involved in the project in any way other than as a user. But yes, there are many how-tos, and as is often the case with open-source software, some are more up-to-date than others. The EFF's Certbot page (which I linked to above) gives specific instructions for many common webservers and operating systems, as I mentioned.

The project has not changed its name. The client software has, for reasons described months ago in the link I gave above and elsewhere. There are no, or at least few, "clones" of the certbot software, but there are many alternative clients. Third parties, unaffiliated with ISRG, LE, or EFF, have written software to fill various needs that the official client didn't satisfy (e.g., running on Windows, requiring fewer dependencies, using different programming languages, integrating into various web hosting control panels, etc.). Since the Let's Encrypt servers use an open protocol for requesting and issuing certificates, anyone with a suitable skill level can write a client to do so and fulfill whatever other needs they may have or perceive.

Yes, choice is bad. Options are bad. Embrace the hegemony.

What each of which programs do? Each of the alternative clients? You expect the Let's Encrypt staff to document software that they didn't write? These clients were written by third parties with no affiliation with EFF or Let's Encrypt. There's no reason to expect that Let's Encrypt would document them.

...and that impression would be correct. The server is run by Let's Encrypt.

Certbot has precisely the same purpose as the original letsencrypt client, and to the best of my knowledge any commands that were valid on the original letsencrypt client should work with certbot. I use one of the alternative clients myself, though, so there are likely changes that I haven't been tracking.

How is it not easy to find? The "Get Started" link is in very large print on the front page of letsencrypt.org. The second paragraph on that page says, "We recommend that most people start with the certbot client", and gives a link to that client's page on eff.org. And there are two links in that paragraph, and one in the following paragraph, not that I think the number of links really matters.

As I see it, the target audience is not "website maintainers"; it is "server administrators." There's a big, and important, difference between the two.

2 Likes
116

I’m sorry. It’s the same problem as this “forum” software you are using. I can’t even work out how to quote…

I have letsenencrypt installed in the root of the disk, and certbot is installed in /home. Maybe that’s a mistake?

As letsencrypt worked for the first domain, without a problem, but didn’t work at all for anything after that, I decided to install certbot. And I followed your how-to. Oviously, this how-to doesn’t take previous installations into account. But, lo and behold, with some searching on this forum, it worked. Or rather, it seemed to work as it reported no errors after fetching certs. But then I was sent on a wild goose chase, as it didn’t work when testing in a browser. And that was because I still needed to install the certs. Which isn’t mentioned in that part of the docs, or on the ncurses interface.

But lacking clear installation instructions, this is what is to be expected, isn’t it?

There is no man page, either. Highly unusual, wouldn’t you say? How am I gonna use this if I have no browser (as sometimes happens to me, in a DC, of all places)?

And no, my distro doesn’t supply packages, as in this case, I’m using Debian Wheezy. In other cases, it might be FreeBSD.

By “not explained”, I mean just a simple text explaining that letsencrypt and certbot are the same (but then, why two?) and which one to use. Is letsencrypt obsolete?

I got the impression that there is a server and a client because that’s how it’s worded and there are no clearly separate docs for the protocol and the client.

Of course the server for the protocol is your side of the story. But how about a typical webserver, containing many domains and many accounts with many certs? That was unclear and I somehow envisioned a client per domain/account and a “server” per physical server, or per letsencrypt account.

All the confusion stems from docs written by developers. Developers tend to use lingo and are so used to that lingo that they can’t seem to grasp that the uninitiated get confused because they simply don’t understand the lingo.

And in this case, for me, the “client” should be named “certificate manager”, or something like that.

1 Like
117

I think that's called FAQ and it is there: FAQ - Let's Encrypt

There is: Go to https://letsencrypt.org/ and (where would you look if you want to find help? - Yes, "support") so click on support in the menu. The first link there is "Community support". And as you see many people seem to find it. :smile:

1 Like
118

Discourse (that's the name of the forum software used here) is really designed to be intuitive, but here is how to do it: Mark the text you want to quote , a quote button will appear, click it.

It does not matter. Just uninstall Let's Encrypt as Certbot is the new client.

There is. However it might only be installed when you've installed Certbot from your distro packages.
But this is true for all software you don't install with the package managment.

Please read this (now...): New Name, New Home for the Let's Encrypt Client Software - Let's Encrypt

This is the "simple text" you requested (also called "explanation").

:confused: Of course... there are...
But users only use the client and should not care about the server.

There are, because the protocol (ACME) is more or less something completly different. I even doubt you have seen a ACME doc anyway. And if that's the case, this is completely right! Because usual users should not have to care about the protocol used. The only doc they need is the client doc.

Of course. Who else could be blamed... ?

There are also many third-party guides/ToDO/HowTo, written by different people.
Have a look: Let Me DuckDuckGo That For You - LMDDGTFY

I think that was a reason why the client was renamed. However "certificate manager" is not a real anme and it sounds lame, so EFF decided to name it "Certbot".

1 Like
119

I'll try to go through the relevant bits of the documentation. Depending on whether you pick apache or something else, you'd get one of the following descriptions:
Apache:

Certbot has a fairly solid beta-quality Apache plugin, which is supported on many platforms, and automates both obtaining and installing certs:
[...]
If you're feeling more conservative and would like to make the changes to your Apache configuration by hand, you can do use the certonly subcommand:

Others:

Since your server architecture doesn't yet support automatic installation you should probably use the certonly command to obtain your certificate.

Do you have any suggestions what this text should be changed to in order to avoid confusion regarding the installation step?

That's a good point, but it's a bit tricky to do this with the letsencrypt-auto / certbot-auto wrappers. Packaged versions of certbot should have manpages available via man. For the -auto scripts, you can use ./certbot-auto --help. All that being said, command-line documentation is certainly not as extensive as the one on the certbot homepage. I feel like that's a quite common approach for modern software projects (I think we're at a point where we can assume a web browser is available for in-depth documentation).

There's no question of "which to use". It's the same project, with a new name. Just like OS X is called OS X right now, but will be called macOS with the next public release. Same software, possibly some new features and a new name, but still the same project. It's compatible and you can switch to the new version or keep using the current release for a reasonable amount of time (it won't "break", but you'll probably stop receiving updates at some point - just like with other software packages).

Looking just at the "Getting started" page and certbot's homepage, I don't see anything that would indicate that you'd need to care about a server component. Do you recall what specifically gave you that impression? Maybe I'm misunderstanding what you're referring to as a server here.

I think the problem here is that there are two "lingos" at play. First of all, we have language that can only be understood by someone familiar with Let's Encrypt/ACME. Getting rid of that language or adding simpler explanations absolutely makes sense, Let's Encrypt should not expect users to know these things. I think the certbot homepage achieves this goal for the most part.

There's also language that is intended for system administrators that know how to setup SSL, and that's where things get tricky. On one hand, we have software that tries to automate that part as well (such as the automatic configuration for apache), so the target audience is not exclusively "sysadmins familiar with SSL." On the other hand, apache is just one part of the story, and there are hundreds of other use-cases where you would still need to know your way around SSL.

That's a good point. The "Getting Started" page uses the term "client" without explaining what a client is in the context of Let's Encrypt. A small addition to the first paragraph could probably establish that.

1 Like
120

[quote="rugk, post:118, topic:15724"]
I got the impression that there is a server and a client

:confused: Of course... there are...But users only use the client and should not care about the server.[/quote]

I'm an oldtimer. A client means a server on the other end. Often, there is some daemon in between the server and the client. Like for smtp. That's what confused me.

It's only an example of the lingo problem...

I'll admit, certbot is a lot sexier. And the error can't be corrected in hindsight, but letsencrypt is an awfully nondescriptive name that tends to lead to typo's. But, most important, it is a pita when googling. And if the docs were complete, we wouldn't have to google...

Gotta run. More later, sorry.

1 Like
121

(I apologize for using my own format for quotations. Don’t understand how to quote here.)

cyrano: “I can’t even work out how to quote.”

Your honesty is refreshing. I tried to figure out quoting and failed too.

“I have letsenencrypt installed in the root of the disk, and certbot is installed in /home. Maybe that’s a mistake?”

I’m not sure; I think that you are supposed to choose any directory and then keep Certbot in that directory, but I’m not sure of that. I think each one of your questions and issues is valid.

cyrano: “All the confusion stems from docs written by developers.”

I agree. Developers don’t get the training they should these days.

In my projects, I grow good documentation as I design, implement, and debug. By the time of advance releases, I don’t usually have to do any further work to give my users complete instructions (whether they need completeness or not). They don’t seem to teach this anywhere anymore, judging from the LE project. Each of the companies I worked for in the 38 years before I retired (Digital Equipment Corporation, Prime Computer, Honeywell Computer/Multics, and about a dozen more) would have fired me for producing software that only had documentation that experts in the technology could understand.

Note that some of the experts here have given you answers to your specific questions. They are happy to do that and do a very good job (they are incredibly patient and knowledgeable), but they simply cannot see that these questions reflect an underlying problem with the LE documentation (as opposed to Certbot, which has somewhat better documentation starting at its home page). That is why they have stopped replying to the topic of this thread, which is my claim that the LE documentation needs improvement. They evidently think that their ability to answer any question about LE or its installation is sufficient as public documentation. That is the way many developers think these days, IMO. They seem to have no ability to put themselves in the shoes of a newcomer to this technology.

cyrano: “…the uninitiated get confused because they simply don’t understand the lingo.”

There needs to be a sort of combined glossary and FAQ that could orient newcomers.

cyrano: “…the ‘client’ should be named ‘certificate manager’, or something like that.”

Yes, great idea. Back in the 1980’s I was confused when people started using the term “email client”. I finally got a straight answer, that it means “email program” (in more modern language, “email app”). Why can’t Certbot be called a “an automated certificate app”? Words like “client” are overused by the terminally smart, who are never confused by them.

rugk: “I think that’s called FAQ and it is there: https://letsencrypt.org/docs/faq/”

Have you looked at it? It covers only the basics, and not all of those. Lots of frequent questions in this forum haven’t made it into the official FAQ.

Notices of updates and help information don’t belong just on websites. They belong in the apps as well (excuse me, the clients).

rugk: “Mark the text you want to quote , a quote button will appear, click it.”

smacks self in forehead Wow, so intuitive, yet I never tried that. Wait. I have tried it, and I just tried it again: I selected some text but no quote button pops up anywhere. What did I do wrong? Does “marking text” mean something different from “selecting text”? Does this forum not work on Firefox 47.0?

rugk: “This is the ‘simple text’ you requested (also called ‘explanation’).”

Disagree. Text stuck in a blog for a particular date is not simple text, since it is not obvious to anyone except someone who would take the time to read the entire website. This is not a reasonable requirement for newcomers.

rugk: “But users only use the client and should not care about the server.”

I think this is exactly the point; why use the word client and confuse newcomers?

rugk: " ‘certificate manager’ is not a real anme and it sounds lame,"

Then call it ACM (Automated Certificate Manager). That sounds spiffy. Anything but ‘client’, which is a technical name relating to the fact that LE happens to define a client API called ACME. I agree that ‘Certbot’ sounds great, and, except for history, I wouldn’t object if LE changed their name to Certbot (with EFF’s permission).

rugk: “That’s a good point, but it’s a bit tricky to do this [provide a man page up front]”

Nonsense. Just include a pointer to the man pages on the homepages of LE and Certbot. Nothing could be easier.

rugk: “First of all, we have language that can only be understood by someone familiar with Let’s Encrypt/ACME. Getting rid of that language or adding simpler explanations absolutely makes sense, Let’s Encrypt should not expect users to know these things.”

Bravo! Let’s improve the documentation before people have to report specific problems.

1 Like
122

See my earlier post:

Edit: Noticed, you saw it. See below.

You can just add them. The website is now open source too:

Do you have JavaScript disabled?

Good point. I just checked https://certbot.eff.org and searched for "client". The word is not mentioned at all...
However on the LE site it is mentioned.

That's not my quote... :expressionless:

This would lead to confusions between ACME and ACM. I think you wanted to make it easier not harder? :wink:

No, just because you have to differentiate: Certbot is the client software you use and Let's Encrypt is the server service you use.

Also not my quote...
That's why you should use the real quote feature.

You may ask why it does not work in the official Discourse forum: https://meta.discourse.org/

1 Like