You’re perfectly entitled to your opinion, as I am to mine.
As above, I’m more that happy to help if there is a clear way I can. Clearly I can’t, so I’ll step out of this conversation.
You’re perfectly entitled to your opinion, as I am to mine.
As above, I’m more that happy to help if there is a clear way I can. Clearly I can’t, so I’ll step out of this conversation.
I stopped reading here since you don’t even understand the purpose of HTTPS.
TCM, I’m willing to learn, especially if it is relevant to the current poor state of the initial LE documentation, which is the topic here.
Could be relevant. Glanced over the main page of LE and the documentation. The assumption seems to be that everyone knows what HTTPS is and already agrees that it needs to be widely implemented.
Svavar_Kjarrval, Thank you, that is a very good insight. I had not been able to derive this insight from TCM’s comment myself.
I fully agree. Anyone taking on the task of writing good Starting documentation must begin with the goal of the project (which has, if I recall correctly, been written about very well already, somewhere), and a brief explanation of how HTTPS differs from HTTP, including mention of secure sockets, certificates, and all the other good stuff.
But there is also a psychology to introducing people to a new thing, and of vital importance is keeping it short and written in big letters.
So, maybe one sentence to briefly explain the advantage of switching the Web from HTTP to HTTPS, another to brag about the success so far, and then the instructions for how to switch your server to HTTPS the easy LE way, followed by a link to a list of all the common problems and how to solve each one?
Anyway, this overall layout of new-user documentation is just the sort of thing a technical writer does all the time. Let’s find a technical writer and get our website organized in a helpful, informative, and inspiring way. Let’s do it already. Who decides, and is he or she reading this?
(Sorry in advance for the longwinded post.)
I’ve had many issues with getting letsencrypt certs working on my webservers (running Arch Linux / Nginx). Every guide I’ve looked at online seemed to provide a different set of commands to run, some of which worked partially and some which didn’t work at all. I did manage to piece together the “magic command” which will get a certificate for my domains in the way I wanted, but now I am struggling to get renewing working, though I think I might have it now.
(To give some context, I am a systems administrator for a small web development company. I have a few years of experience in this position, and several years of prior experience hosting personal projects and dealing with Linux.)
Looking at the “Getting Started” docs, here are some questions that it raises (and consequently are potential areas for improvement).
Last time I looked at this section, I don’t think it provided instructions for installing letsencrypt through the native package manager, leaving me to question whether or not cloning the git repo was the “correct” way to do it. The link to https://certbot.eff.org/ fixes that issue, though.
I also did not understand the difference between
letsencrypt-auto, but I think the docs are much clearer on that now. However, now I’m confused as to what the difference is between
certbot. Are they just aliases for the same program? The way I understand it is:
That’s a bit confusing, but if that is correct, then the docs are good in that regard.
This is the most difficult section to understand.
Certbot supports a number of different “plugins” that can be used to obtain and/or install certificates.
Based on what I read in this section, two possible plugins are
webroot, but there may be more. (Is there a list somewhere? I know there is, but there’s no link to it.) The
automates both obtaining and installing certs
This is good and descriptive. Unfortunately for me, this doesn’t work, because I don’t use Apache on a recent Debian OS, so I continue reading:
On other platforms automatic installation is not yet available, so you will have to use the
certonlycommand. Here are some examples:
This is the first time
certonly is mentioned on the entire page, and I have no idea what it does. Is it a plugin? I don’t think so. But for some reason, I don’t use it with the
apache plugin, but I do use it with the
webroot plugin. Why can’t the script infer whether or not I want
certonly based on the plugin I provide? The docs say that
certonly is a “command”…are there other commands? Why didn’t I specify a command when using the
This command will obtain a single cert for example.com, www.example.com, thing.is, and m.thing.is; it will place files below /var/www/example to prove control of the first two domains, and under /var/www/thing for the second pair.
I’m not sure if this is describing the
certonly command (as it implies) or the
Based on the fact that there are two dashes in front of
standalone, it seems that this might be another “plugin”, but I’m not sure about that. This plugin is a bit confusing, but the parenthesized text (and my prior understanding of these plugins) is enough for me to figure out what is going on behind the scenes.
I’d like to get an understanding of what these plugins do and how many of them there are. In order to get to the official docs for the list of plugins, I had to click on the following sequence of links:
So the documentation locations we have are:
letsencrypt --help(discussed later)
The last one looks like it is the most “official”, but I’m not sure about that. Let’s see how well it matches up with what I learned on the “Getting Started” page.
The Certbot client supports a number of different “plugins” that can be used to obtain and/or install certificates.
So far, so good.
Plugins that can obtain a cert are called “authenticators” and can be used with the “certonly” command. Plugins that can install a cert are called “installers”. Plugins that do both can be used with the “certbot run” command, which is the default.
What does “obtain a cert” mean? I think it means that it creates as certificate on the letsencrypt servers after proving domain ownership, downloads it, and saves it to the filesystem ; if so, this could be made clearer. So, these plugins can be used with the “certonly” command…can they also be used without the “certonly” command? Why would I use “certonly” versus leaving it out? There is still no clear explanation of what this does.
Plugins that can install a cert are called “installers”.
What does “install” mean? Does it mean that it puts the certificates somewhere on the file system (typically what is meant by “install”), or does it mean that it automatically modifies the webserver’s config files to enable SSL and point the web server to the correct location for the certs (this is what I think it means)?
Plugins that do both can be used with the “certbot run” command, which is the default.
This is the first time I have seen reference to the “run” command. What does this do? What happens if I leave it off? How is it different from “certonly”?
Then we have a list of plugins and whether or not they are authenticators, installers, or both. The “Notes” for each of the plugins is very helpful. I finally understand what plugins are available for me to use and what exactly they do. Since
nginx is “very experimental”, I don’t choose it, but I want things to be automated as possible, so I am left with choosing “webroot” or “standalone”. I don’t want my server to go down, so I choose “webroot”.
The long descriptions of each of the plugins below is also very helpful. I discover in the “Webroot” section that I have to use
--webroot (still don’t know what
certonly does, but I’ll just go with it for now).
Unfortunately, the provided example command doesn’t work (note that it has been a while since I did this, so perhaps things have changed since then). The fix that I pieced together from various guides on the internet was to include
--server https://acme-v01.api.letsencrypt.org/directory in the command. I have no idea what this is or why I need it, but when I include it, fetching certificates works. This is not mentioned anywhere in the docs.
Perhaps this should be obvious, but it’s something that I didn’t understand for quite a while…you only need to run
letsencrypt successfully once. Each time you run it, it will fetch a brand new certificate and place it in your filesystem with a new name, which is probably undesirable. When your cert is about to expire, you should instead use
letsencrypt renew. As far as I understand it, letsencrypt keeps track of all your previously successful certs and renews them using the exact same parameters. It also skips renewals that aren’t close to expiration yet (unless you specify
--force), so this is a good option for adding to a daily cron job.
The docs give examples of using other options passed to
For example, if you want to use the standalone plugin to renew your certificates, you may want to use a command like
certbot renew --standalone --pre-hook "service nginx stop" --post-hook "service nginx start"
The hooks are nice, but why specify
--standalone? If I used
--standalone when I first got my certs, do I need to specify it explicitly when I renew? What about
--webroot? It works just fine without specifying my plugin, so when would I want to? Only when using hooks?
Later in the “Renewal” section it says:
An alternative form that provides for more fine-grained control over the renewal process (while renewing specified certificates one at a time), is
certbot certonlywith the complete set of subject domains of a specific certificate specified via
At this point I’ve all but given up what
certonly is supposed to be doing. Now it has something to do with renewal too? Will this command actually renew my certificates, or will it fetch new certificates? The next paragraph seems to partially answer my questions:
(… Specifying a subset of the domains creates a new, separate certificate containing only those domains, rather than replacing the original certificate.) The
certonlyform attempts to renew one individual certificate.
certonly creates a new certificate (if it hasn’t seen the set of domains before), or it renews an existing certificate (if it has seen the set of domains before).
If my understanding of these things is correct, then the docs are on the right track, but they could be made clearer. I also just realized (when attempting to run
letsencrypt with the incorrect
--renew parameter) that the binary also has some documentation! Let’s see what that says:
The Let's Encrypt agent can obtain and install HTTPS/TLS/SSL certificates. By default, it will attempt to use a webserver both for obtaining and installing the cert. Major SUBCOMMANDS are: (default) run Obtain & install a cert in your current webserver certonly Obtain cert, but do not install it (aka "auth") install Install a previously obtained cert in a server renew Renew previously obtained certs that are near expiry revoke Revoke a previously obtained certificate rollback Rollback server configuration changes made during install config_changes Show changes made to server config during installation plugins Display information about installed plugins
This helps greatly, and I wish these things were talked about in the docs. I will assume that “SUBCOMMANDS” are the same thing as “commands”. My understanding from this output is:
certonlyobtains, but does not install. This means that it will authenticate with the letsencrypt server, generate the certificate, and download it to my filesystem, but it will not mess with my webserver’s config files. What is the behavior then if I specify
--nginx? Does that combination of parameters even make sense?
Other question that pops up regarding this specific text:
By default, it will attempt to use a webserver both for obtaining and installing the cert.
Does this mean that it will use my existing, running webserver (i.e. nginx), meaning that the
--webroot plugin is used by default (I don’t think so), or it will use it’s own webserver (aka
--standalone)? Which further raises the question, does running the command without specifying a plugin even make sense? If not, it might be good to explicitly say that specifying a plugin is required somewhere in the documentation.
All in all, I think reading the
letsencrypt --help output is necessary (in combination with the online documentation) to understanding which options to pick and how to successfully get a cert. The online documentation could be improved in the following ways:
certonly. Fold in the explanations from the
--helpoutput to make it clear what each command does. Make it clearer that commands are different from plugins, and maybe say that using certain plugins together with some commands doesn’t make sense (if my understanding is correct).
To be clear, all of the above are merely suggestions based on what I found to be confusing when using letsencrypt and reading through the docs.
Thanks denaje, the above critique is very useful because it actually tells us what a real user found unclear and how they understand things now.
To answer this specific question, the
letsencrypt client was officially renamed to
certbot last week. The first release of
certbot is 0.6.0 and commands that refer to
letsencrypt should still work; the
certbot program is the same code base and accepts the same options, but most operating system packages are still called
letsencrypt for the time being because the name change happened so recently.
I’ll try to answer other questions in the form of documentation updates.
The first thing the updated documentation should do is let people know the SERVICE is no longer in beta, but the official client very much is!
The official client is currently version 0.6 and can’t even handle a vhosts file with vhosts in it! While there are plenty of alternative clients that are pretty mature and are no longer in beta, most people are using the official client.
I’m very impressed with the rate at which Let’s Encrypt (the service) has developed, but keep in mind most people are still viewing the service through the official client’s beta lens. Of course the documentation can be improved, it’s less than a year old! But the majority of the documentation revolves around the use of the official client, which is still very beta.
I guess what I’m saying is, you can’t put so much emphasis on the documentation being beta quality when the bulk of that documentation is documenting a beta product.
I’m not sure what you’re saying. Both the client and the service is less than a year old, and the bulk of Let’s Encrypt’s efforts went into the service. That effort resulted in a high quality reliable service that’s now usable by a great number of third-party clients. Effort is now being put in the client, but it has a long way to go before it reaches v1.0 and the documentation reflects that.
I’m not sure why you’d frame this as “nor software should be developed by fixing bugs”, when the client is very much beta and in active development!
Um, yeah, I totally see where you’re coming from. But I’d still rather engage than dismiss. david7364 isn’t trolling or spouting nonsensical hyperbole. While I think he’s misunderstood Let’s Encrypt’s goals and methods, perhaps that’s a perfect example of where the documentation is letting him down.
Thanks! But I have one last question.
You say that (for the time being at least)
letsencrypt commands should still work, but will the config files and certs for new installs go into
etc/letsencrypt/ or into
/etc/certbot/? That’s my biggest concern.
I know this part isn’t up to you, but I’m on FreeBSD, so when the new certbot port comes through I just want to be prepared!
(On a side note, I’m really happy that you guys planned ahead and made the “live” symlinks relative instead of absolute - that’s already come in really really handy!)
It’s still going to be
/etc/letsencrypt. This might change to something else in the long run, but likely with some kind of backwards compatibility mechanism.
Excellent, thanks for the info!
Don’t we face a problem of Managing User Expectations here?
I think the OP has a good point, but I wonder if it wouldn’t make sense to include some sort of “Minimum requirements on competences for an administrator of a Web site to successfully use the LE services.” in the introduction documents, the Getting Started documentation and other various strategic places.
I’m not sure if I feel comfortable seeing people who’s never typed a command in the CLI, who’s never modified a configuration file with a text editor, etc., expecting to install and maintain SSL type certificates with a One Click and Forget, Plug and Play type of action.
Please, don’t get me wrong. I have a very high respect for the skills and the intelligence of the people I’m talking about. They most likely have very high skills in other areas but maybe a slight lack of skills and experience in the Web services and the SSL/TLS area. (And I’m not an expert myself.)
It’s just that they seem to have been given the impression that using LE is close to a One Click activity. My personal experience is that even if using LE is relatively simple for a Web Server Administrator, it’s still not prime time for anyone with zero experience in the subject.
Who’s fault is it? I don’t want to point fingers. But the fact that the Let’s Encrypt presentation documentation lets us all believe that it’s sooo simple is probably sub-optimal. The result is that LE is now facing support questions concerning all types of specific environments, different operating systems, different Web server software and even different Web hosting solutions. I have a hard time to believe such specific support is something LE can continuously provide. And users will more and more require LE to solve the user’s problem on the level of “How do I know what directory I should be in?”.
I strongly believe that:
If a user is using a Web Hosting Service taking care of the server computer, the server software and the Web service software, then it should preferably be the Hosting Service obtaining and maintaining the LE part as well. (Of course, I don’t know how every hosting service is designed, which is exactly my point.)
If an LE user is doing it him- or herself, then there is a minimum set of knowledge requirement to be respected.
Some sort of “warning” about “minimum required skills” should be included in the “Getting Started” type of documentation provided by LE, stating that “If you do this yourself, you should at least know how to do…”. This could help in managing the expectations from new (as well as existing) LE users.
It could also help in reducing the “RTFM” and “Google is your friend” type of reactions that slowly start to pop up on this support site.
Had some time. Did some thinking.
As far as I can see, there are three major building blocks for the Let’s Encrypt solution. At least from a Web Server Administrator’s point of view.
The back-end service, the database and software and what have you to verify that a Certificate Request comes from the Web server it claims to be, to conditionally generate the requested certificate and make it available for some type of download to the requesting Web server.
The client software (the letsencrypt binary and it’s many derivatives). There’s at least one client that’s been provided by the Let’s Encrypt organization, but there seem to be quite a lot of alternatives in different development states and probably with different levels of quality. The client software will typically be able to request a certificate, download the certificate from the Let’s Encrypt server and install the certificate on the Web Server computer. “Installing the certificate” means to store it on the local hard disk in a predefined way. Now, that’s not enough! It’s not used for anything good just yet. See next point.
The glue. The Web service software (Apache, nginx, other) must be taught to use the downloaded certificate. It must be correctly configured not only to start useing the obtained certificate but also how to use it, plus how to deal with visiting Web navigators requests for Web pages that are not protected by any certificate (html pages), like should they be redirected to https or not, configured to use one set of encryption algorithms (which ones?) and decisions need to be made if Windows XP should be supported to the cost of potentially reduced security. Etc. Lots of considerations go into the glue.
These three areas could be explained (probably much better than what I do here) in the official documentation. It will help a new user to understand what’s involved.
My guess is that the Let’s Encrypt certification service (the “back-end”) as such could be better documented than what it is right now.
I also believe that the Let’s Encrypt client software (“letsencrypt”) can be better documented than what it is right now. But, AFAIK the client will soon be handed over to the EFF team. Then it will be the EFF team that shall (and will) document “their” software. For the Let’s Encrypt team to spend efforts documenting something they will soon hand over (unless already done) to someone else, may not be a very stimulating task. I do understand that.
Then there are all the other software “clients”. They must be individually documented by each development team. I could imagine Let’s Encrypt writing up a document pointing to the different clients they know about, potentially with a development status, like “beta”, “release”, “last release date” or “discontinued”, but I understand such information would most likely require a Wiki style setup so that the interested parties (the client development teams), having the incentive to do so, would be able to maintain the status of their own software, as well as to add new software initiatives.
The glue is of course extremely difficult to document. Partially due to the uncountable number of different software combinations (Linux, Windows, Solaris, etc. Nginx, Apache, etc. BTW, Apache V2.2 or V2.4? They’re not the same. Etc.), but also due to the fact that many local decisions must be taken by the Web Server Administrator and his/her management (like Windows XP support for instance).
I can’t imagine anyone trying to provide a simple documentation covering the glue, neither can I imagine a software solution than can cope with all the gluing activity in a fully automated manner for all possible existing software combinations. This is where plug-ins come in.
My personal conclusion:
The certification service could and should be better documented.
The “client” software must be well documented by each development team.
Let’s Encrypt should clearly document how disperse the glue activity can be, that local decisions must be made and that sooner or later manual intervention will likely be required. Quite often on the command line.
Note that the Wikipedia entry for LE currently includes this statement: “On a Linux web server, execution of only two commands is sufficient to set up HTTPS encryption and acquire and install certificates within 20 to 30 seconds.”
This is currently our pledge to the world. If this is currently correct, for all reasonable competencies of users desiring HTTPS access to their server and for all reasonably common server software, then our Get Started page can simply be rewritten by anyone familiar with good, inspiring technical writing to match the loftiness, promise, and simplicity of the link to it that exists on the LE home page.
However, if this is not actually true (and I humbly suggest that it is not, as seen from several of the postings on this thread and many other postings elsewhere in this community), then considerably more high-quality documentation work may be necessary, to document our limitations and to help provide quick and necessary guidance.
I am concerned that we meet our external claims from the beginning, so we don’t start getting negative articles written about LE that might threaten our achieving our goal.
I completely agree with this.
By my standards, the documentation is perfectly clear and I understand what is required of me to obtain an LE cert and get it working. But I’ve been playing with Linux since 1994 and FreeBSD since 2004.
While I think there are several people in the forums being completely unreasonable, the vast majority are simply misunderstanding exactly what the project is. Many don’t seem to understand the difference between a CA and a certificate, much less what needs to happen if they don’t have shell access (or sometimes even what shell access is).
I agree with that, but at the same time Let’s Encrypt is working hard behind the scenes to get hosting companies to implement encryption without the end user being responsible for anything. LE is only months old, they’ve done an impressive amount of work in a very short period of time. Basically, this site (the LE forums) is for people like us. It’s just a bit unfortunate that people without any admin skill or experience are under the impression it’s a “One Click” “Plug and Play” process.
I’m definitely not blaming LE for the mis-communication. I think it’s far more complex than that, just like science reporting in mainstream media - “Scientists report that coffee causes cancer!” The reporting of Let’s Encrypt can be just as deceptive. For example, this site has the following snippets:
Let's Encrypt has completely changed the process of adding a website certificate to your website. Not only have they made access to a certificate completely free, they've also made sure both the installation process and the ability to update your certificate is as simple as possible. This means website owners can offer the benefits of https to their site visitors, without the need to spend extra cash in doing so. Meaning that the traffic going to any website using Let's Encrypt is, in essence, protected.
Nowhere is it even implied that you need basic TLS knowledge or at least the ability to install software on a machine. Even that site’s “bad stuff” section is completely misleading:
The biggest problem with Let's Encrypt is that it democratizes access to https for any website. Yes, on the surface, this should in fact be a positive thing that we're celebrating. Unfortunately human nature comes into play here. When most people (non-geeks/non-IT) see https, immediate and unwavering trust is implied.
That’s the “bad stuff”! Not the need for a little command line skill, or knowledge of whether you have access to Nginx or Apache, or even what Nginx is (“is EngineX that bad guy from Age of Extinction?”)
Let’s Encrypt has no power to stop that kind of reporting, and I don’t think they’re contributing to it. But I also have no idea what they can do to diminish it.
This I’m not so sure I agree with. It’s wrong to mis-communicate the skill level needed, but it’s also wrong to imply there is a minimum level required before you start. There are plenty of people asking exactly the same sort of broken questions that I used to ask many years ago. There are plenty of people who want to learn and are willing to learn, but are being turned off when they think it’s beyond them.
I actively try to re-frame their thinking when they ask broken questions e.g. I try to let them know they don’t have to use the official client, or that LE is primarily a CA and not a piece of software. Sometimes they ask generic Apache config questions, and while I tell them they’re better off finding a guide elsewhere online specific to their OS/webserver, I do try to tell them what they need to look for or pay specific attention to. Playing with tech can be SO rewarding! I don’t want them to give up!
Heh, yeah. I always wince when someone says “I’m using Apache2” Apache 2 came out over 14 years ago! I think you’re using something more modern than that!
Ah, but it doesn’t say WHICH Linux web server!
The Wikipedia statement seems accurate, although I suppose that gradually over time the proportion of Linux web servers on which this only takes one command will increase.
A sweeping generalisation in an encyclopedia cannot represent Let’s Encrypt’s “pledge to the world”. You may have allowed your perception of how difficult it is to use Let’s Encrypt to be swayed too much by the questions asked here, even though the questioners represent only a tiny fraction of the subscribers as we can see by the very high issuance rates for Let’s Encrypt (hundreds of thousands of certificates per week).
tialaramex, I think (but am not sure) that you and I agree that WP is not currently presenting LE’s pledge to the world completely. As a 10-year WP editor, I find the WP part of our failure concerning. One peculiarity about WP is that is requires (but does not enforce consistently) a reference in a “reliable source” for every statement of fact. Currently, the LE article does not comply with WP policy, since only a few of its statements are backed up by reliable sources. The LE website is not considered a RS, and neither are most blogs. I once proposed to the WP community that we accept all unreferenced statements in articles until they are contested by an editor (or a reference is found), but the proposal was defeated, so there are currently no rules and few warnings before articles or parts of articles are deleted for not following policies.
All this is to say that I’m willing to insert a mission statement into the WP article, and I might be able to make it stick. Someone good with words and intimately familiar with LE should write that statement for me. It would be best if that person could get the statement approved by whoever runs LE and published somewhere that sounds reliable.
Don’t forget, a promise of “one command” implies not having to spend many hours figuring out exactly how LE is different from the usual manual certification process. I can’t agree that the many people having problems understanding how to make LE work are a stupid minority whom we have to tolerate. I believe, along with others, that we have a serious current problem (one which might perhaps be easy to solve) with misleading visitors to the LE website about our goals and our current tools.
We do not have control over the world’s reportage, but we do have control over the content of the LE website. This thread has already created links to CertBot on our Startup page. Let’s finish the job. I’ve said above what that means: we have to choose how we describe our goals and then explain how LE as it exists now meets those goals. If our goals include webmasters being able to secure their sites, then we must show exactly how to do that using the LE technology. If we can’t achieve that, then a vital part of our project is still in Beta.
Improving our documentation a good process for us, because it will likely improve both our software and our documentation, so they match (here and elsewhere I’m ignoring the fact that CertBot offers better documentation than LE; I’m only concerned with the LE and WP websites, because that’s where we are failing to be clear and complete about what LE does and how it does it).
About the hundreds of thousands of certificates each week: I’m guessing most are requested by people who have been using manual certification methods who simply want to save the $100 to $300 a year they are currently spending for a website certificate. Money is a powerful motivator. Since we don’t really know how and why so many certificates are being requested, I have to guess, and that’s my guess.
As I stated in an earlier post: Let’s Encrypt is a CA, whose job it is to issue certificates. Given that this is working as expected, and that it’s quite stable, the beta label was dropped. Certbot was moved to another organization and got a new name, and is still very much beta. Again, not saying that documentation shouldn’t be improved, just that I don’t think we should be conflating these issues.
That is not consistent with the numbers I mentioned earlier, which state that more than 90% of the domain names that got a certificate from Let’s Encrypt never had a certificate from any other publicly-trusted CA before.
With regards to the Wikipedia article, my suggestion would be to be a bit more precise with the statement, and make it something like “On a typical Linux web server […]” or “With commonly-used Linux web server software […]”. Wikipedia needs to find a balance between the technical complexity of this topic and the technical know-how of typical readers, so it’s probably not a good idea to add too many details.