From 0b7552ef8b9681186d2864a1c7297be1eb3b7daa Mon Sep 17 00:00:00 2001 From: Peter Eckersley Date: Tue, 1 Dec 2015 15:16:17 -0800 Subject: [PATCH 1/5] Begin cleaning up README.md --- README.rst | 75 +++++++++++++++++++++++++++--------------------------- 1 file changed, 38 insertions(+), 37 deletions(-) diff --git a/README.rst b/README.rst index ce0d1b686..e4dc0896f 100644 --- a/README.rst +++ b/README.rst @@ -3,12 +3,9 @@ Disclaimer ========== -This is a **DEVELOPER PREVIEW** intended for developers and testers only. - -**DO NOT RUN THIS CODE ON A PRODUCTION SERVER. IT WILL INSTALL CERTIFICATES -SIGNED BY A TEST CA, AND WILL CAUSE CERT WARNINGS FOR USERS.** - -Browser-trusted certificates will be available in the coming months. +The Let's Encrypt client is **BETA SOFTWARE**. It contains plenty of bugs and +rough edges, and should be tested thoroughly in staging evironments before use +on production systems. For more information regarding the status of the project, please see https://letsencrypt.org. Be sure to checkout the @@ -17,37 +14,39 @@ https://letsencrypt.org. Be sure to checkout the About the Let's Encrypt Client ============================== +Installation +------------ + +If `letsencrypt` is packaged for your OS, you can install it from there, and +run it by typing `letsencrypt`. Because not all operating systems have +packages yet, we provide a temporary solution via the `letsencrypt-auto` +wrapper script, which obtains some dependencies from your OS and puts others +in an python virtual environment:: + + user@www:~$ git clone https://github.com/letsencrypt/letsencrypt + user@www:~$ cd letsencrypt + user@www:~/letsencrypt$ ./letsencrypt-auto --help + +`letsencrypt-auto` updates to the latest client release automatically. And +since `letsencrypt-auto` is a wrapper to `letsencrypt`, it accepts exactly the +same command line flags and arguments. More details about this script and +other installation methods can be found [in the User +Guide](https://letsencrypt.readthedocs.org/en/latest/using.html#installation) + +Running the client and understanding client plugins +--------------------------------------------------- + +In many cases, you can just run `letsencrypt-auto` or `letsencrypt`, and the +client will guide you through the process of obtaining and installing certs +interactively. + +But to understand what the client is doing in detail, it's important to +understand the way it uses plugins. Please see the [explanation of +plugins](https://letsencrypt.readthedocs.org/en/latest/using.html#plugins) in +the User Guide. + |build-status| |coverage| |docs| |container| -In short: getting and installing SSL/TLS certificates made easy (`watch demo video`_). - -The Let's Encrypt Client is a tool to automatically receive and install -X.509 certificates to enable TLS on servers. The client will -interoperate with the Let's Encrypt CA which will be issuing browser-trusted -certificates for free. - -It's all automated: - -* The tool will prove domain control to the CA and submit a CSR (Certificate - Signing Request). -* If domain control has been proven, a certificate will get issued and the tool - will automatically install it. - -All you need to do to sign a single domain is:: - - user@www:~$ sudo letsencrypt -d www.example.org certonly - -For multiple domains (SAN) use:: - - user@www:~$ sudo letsencrypt -d www.example.org -d example.org certonly - -and if you have a compatible web server (Apache or Nginx), Let's Encrypt can -not only get a new certificate, but also deploy it and configure your -server automatically!:: - - user@www:~$ sudo letsencrypt -d www.example.org run - - **Encrypt ALL the things!** @@ -78,9 +77,11 @@ Current Features * Supports multiple web servers: - - apache/2.x (tested and working on Ubuntu Linux) - - nginx/0.8.48+ (under development) + - apache/2.x (working on Debian 8+ and Ubuntu 12.04+) - standalone (runs its own simple webserver to prove you control a domain) + - webroot (adds files to webroot directories in order to prove control of + domains and obtain certs) + - nginx/0.8.48+ (under development) * The private key is generated locally on your system. * Can talk to the Let's Encrypt (demo) CA or optionally to other ACME From f15c4125d398774111718f94a79bcc1da7481ea5 Mon Sep 17 00:00:00 2001 From: Peter Eckersley Date: Tue, 1 Dec 2015 15:19:25 -0800 Subject: [PATCH 2/5] More-or-less-final README.rst --- README.rst | 117 +++++++++++++++++++++++++++------------------ letsencrypt/cli.py | 5 +- 2 files changed, 73 insertions(+), 49 deletions(-) diff --git a/README.rst b/README.rst index e4dc0896f..b124de7f8 100644 --- a/README.rst +++ b/README.rst @@ -3,7 +3,7 @@ Disclaimer ========== -The Let's Encrypt client is **BETA SOFTWARE**. It contains plenty of bugs and +The Let's Encrypt Client is **BETA SOFTWARE**. It contains plenty of bugs and rough edges, and should be tested thoroughly in staging evironments before use on production systems. @@ -14,40 +14,87 @@ https://letsencrypt.org. Be sure to checkout the About the Let's Encrypt Client ============================== +The Let's Encrypt Client is a fully-featured, extensible client for the Let's +Encrypt CA (or any other CA that speaks the `ACME +`_ +protocol) that can automate the tasks of obtaining certificates and +configuring webservers to use them. + Installation ------------ -If `letsencrypt` is packaged for your OS, you can install it from there, and -run it by typing `letsencrypt`. Because not all operating systems have -packages yet, we provide a temporary solution via the `letsencrypt-auto` +If ``letsencrypt`` is packaged for your OS, you can install it from there, and +run it by typing ``letsencrypt``. Because not all operating systems have +packages yet, we provide a temporary solution via the ``letsencrypt-auto`` wrapper script, which obtains some dependencies from your OS and puts others in an python virtual environment:: - user@www:~$ git clone https://github.com/letsencrypt/letsencrypt - user@www:~$ cd letsencrypt - user@www:~/letsencrypt$ ./letsencrypt-auto --help + user@webserver:~$ git clone https://github.com/letsencrypt/letsencrypt + user@webserver:~$ cd letsencrypt + user@webserver:~/letsencrypt$ ./letsencrypt-auto --help -`letsencrypt-auto` updates to the latest client release automatically. And -since `letsencrypt-auto` is a wrapper to `letsencrypt`, it accepts exactly the -same command line flags and arguments. More details about this script and -other installation methods can be found [in the User -Guide](https://letsencrypt.readthedocs.org/en/latest/using.html#installation) +Or for full command line help, type:: -Running the client and understanding client plugins ---------------------------------------------------- + ./letsencrypt-auto --help all | less -In many cases, you can just run `letsencrypt-auto` or `letsencrypt`, and the +``letsencrypt-auto`` updates to the latest client release automatically. And +since ``letsencrypt-auto`` is a wrapper to ``letsencrypt``, it accepts exactly +the same command line flags and arguments. More details about this script and +other installation methods can be found `in the User Guide +`_. + +How to run the client +--------------------- + +In many cases, you can just run ``letsencrypt-auto`` or ``letsencrypt``, and the client will guide you through the process of obtaining and installing certs interactively. -But to understand what the client is doing in detail, it's important to -understand the way it uses plugins. Please see the [explanation of -plugins](https://letsencrypt.readthedocs.org/en/latest/using.html#plugins) in +You can also tell it exactly what you want it to do. For instance, if you +want to obtain a cert for ``thing.com``, ``www.thing.com``, and +``otherthing.net``, using the Apache plugin to both obtain and install the +certs, you could do this:: + + ./letsencrypt-auto --apache -d thing.com -d www.thing.com -d otherthing.net + +(The first time you run the command, it will make an account, and ask for an +email and agreement to the Let's Encrypt Subscriber Agreement; you can +automate those with ``--email`` and ``--agree-tos``) + +If you want to use a webserver that doesn't have full plugin support yet, you +can still use "standlone" or "webroot" plugins to obtain a certificate:: + + ./letsencrypt-auto certonly --standalone --email admin@thing.com -d thing.com -d www.thing.com -d otherthing.net + + +Understanding the client in more depth +-------------------------------------- + +To understand what the client is doing in detail, it's important to +understand the way it uses plugins. Please see the `explanation of +plugins `_ in the User Guide. +Links +===== + +Documentation: https://letsencrypt.readthedocs.org + +Software project: https://github.com/letsencrypt/letsencrypt + +Notes for developers: https://letsencrypt.readthedocs.org/en/latest/contributing.html + +Main Website: https://letsencrypt.org/ + +IRC Channel: #letsencrypt on `Freenode`_ + +Community: https://community.letsencrypt.org + +Mailing list: `client-dev`_ (to subscribe without a Google account, send an +email to client-dev+subscribe@letsencrypt.org) + |build-status| |coverage| |docs| |container| -**Encrypt ALL the things!** .. |build-status| image:: https://travis-ci.org/letsencrypt/letsencrypt.svg?branch=master @@ -73,7 +120,7 @@ the User Guide. Current Features ----------------- +================ * Supports multiple web servers: @@ -84,7 +131,7 @@ Current Features - nginx/0.8.48+ (under development) * The private key is generated locally on your system. -* Can talk to the Let's Encrypt (demo) CA or optionally to other ACME +* Can talk to the Let's Encrypt CA or optionally to other ACME compliant services. * Can get domain-validated (DV) certificates. * Can revoke certificates. @@ -93,34 +140,10 @@ Current Features runs https only (Apache only) * Fully automated. * Configuration changes are logged and can be reverted. -* Text and ncurses UI. +* Supports ncurses and text (-t) UI, or can be driven entirely from the + command line. * Free and Open Source Software, made with Python. -Installation Instructions -------------------------- - -Official **documentation**, including `installation instructions`_, is -available at https://letsencrypt.readthedocs.org. - - -Links ------ - -Documentation: https://letsencrypt.readthedocs.org - -Software project: https://github.com/letsencrypt/letsencrypt - -Notes for developers: https://letsencrypt.readthedocs.org/en/latest/contributing.html - -Main Website: https://letsencrypt.org/ - -IRC Channel: #letsencrypt on `Freenode`_ - -Community: https://community.letsencrypt.org - -Mailing list: `client-dev`_ (to subscribe without a Google account, send an -email to client-dev+subscribe@letsencrypt.org) - .. _Freenode: https://freenode.net .. _client-dev: https://groups.google.com/a/letsencrypt.org/forum/#!forum/client-dev diff --git a/letsencrypt/cli.py b/letsencrypt/cli.py index 2fae5fe3e..2b2e62262 100644 --- a/letsencrypt/cli.py +++ b/letsencrypt/cli.py @@ -59,6 +59,7 @@ the cert. Major SUBCOMMANDS are: 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 """ @@ -71,7 +72,7 @@ USAGE = SHORT_USAGE + """Choice of server plugins for obtaining and installing c %s --webroot Place files in a server's webroot folder for authentication -OR use different servers to obtain (authenticate) the cert and then install it: +OR use different plugins to obtain (authenticate) the cert and then install it: --authenticator standalone --installer apache @@ -1041,7 +1042,7 @@ def _plugins_parsing(helpful, plugins): helpful.add_group( "plugins", description="Let's Encrypt client supports an " "extensible plugins architecture. See '%(prog)s plugins' for a " - "list of all available plugins and their names. You can force " + "list of all installed plugins and their names. You can force " "a particular plugin by setting options provided below. Further " "down this help message you will find plugin-specific options " "(prefixed by --{plugin_name}).") From 49efc489fc16e94b9ccbe2f8c5b9d878dd106fe7 Mon Sep 17 00:00:00 2001 From: Peter Eckersley Date: Tue, 1 Dec 2015 17:49:49 -0800 Subject: [PATCH 3/5] fixes --- README.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.rst b/README.rst index b124de7f8..be5f04671 100644 --- a/README.rst +++ b/README.rst @@ -50,10 +50,10 @@ In many cases, you can just run ``letsencrypt-auto`` or ``letsencrypt``, and the client will guide you through the process of obtaining and installing certs interactively. -You can also tell it exactly what you want it to do. For instance, if you -want to obtain a cert for ``thing.com``, ``www.thing.com``, and -``otherthing.net``, using the Apache plugin to both obtain and install the -certs, you could do this:: +You can also tell it exactly what you want it to do from the command line. +For instance, if you want to obtain a cert for ``thing.com``, +``www.thing.com``, and ``otherthing.net``, using the Apache plugin to both +obtain and install the certs, you could do this:: ./letsencrypt-auto --apache -d thing.com -d www.thing.com -d otherthing.net @@ -62,7 +62,7 @@ email and agreement to the Let's Encrypt Subscriber Agreement; you can automate those with ``--email`` and ``--agree-tos``) If you want to use a webserver that doesn't have full plugin support yet, you -can still use "standlone" or "webroot" plugins to obtain a certificate:: +can still use "standalone" or "webroot" plugins to obtain a certificate:: ./letsencrypt-auto certonly --standalone --email admin@thing.com -d thing.com -d www.thing.com -d otherthing.net From e27e891615e518d30c3cfcd3b3163f0f01f13ab7 Mon Sep 17 00:00:00 2001 From: Peter Eckersley Date: Tue, 1 Dec 2015 17:50:46 -0800 Subject: [PATCH 4/5] nginx detail --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index be5f04671..99ef68ad7 100644 --- a/README.rst +++ b/README.rst @@ -128,7 +128,7 @@ Current Features - standalone (runs its own simple webserver to prove you control a domain) - webroot (adds files to webroot directories in order to prove control of domains and obtain certs) - - nginx/0.8.48+ (under development) + - nginx/0.8.48+ (highly experimental, not included in letsencrypt-auto) * The private key is generated locally on your system. * Can talk to the Let's Encrypt CA or optionally to other ACME From 1a4dd56f71a34b632da350e850177723d1b61687 Mon Sep 17 00:00:00 2001 From: Peter Eckersley Date: Tue, 1 Dec 2015 18:13:38 -0800 Subject: [PATCH 5/5] Address review comments (sometimes less less is more) --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 99ef68ad7..f38b09cfd 100644 --- a/README.rst +++ b/README.rst @@ -4,7 +4,7 @@ Disclaimer ========== The Let's Encrypt Client is **BETA SOFTWARE**. It contains plenty of bugs and -rough edges, and should be tested thoroughly in staging evironments before use +rough edges, and should be tested thoroughly in staging environments before use on production systems. For more information regarding the status of the project, please see @@ -35,7 +35,7 @@ in an python virtual environment:: Or for full command line help, type:: - ./letsencrypt-auto --help all | less + ./letsencrypt-auto --help all ``letsencrypt-auto`` updates to the latest client release automatically. And since ``letsencrypt-auto`` is a wrapper to ``letsencrypt``, it accepts exactly