From 9fe6836c014428b2d7781a050d9d9312306e0d6d Mon Sep 17 00:00:00 2001 From: Brad Warren Date: Thu, 14 Jul 2016 15:05:41 -0700 Subject: [PATCH 01/16] remove coupling between README and docs introduction --- README.rst | 195 +----------------------------------------- docs/intro.rst | 4 +- docs/intro_common.rst | 192 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 195 insertions(+), 196 deletions(-) create mode 100644 docs/intro_common.rst diff --git a/README.rst b/README.rst index c71079f9a..06cb3f8bc 100644 --- a/README.rst +++ b/README.rst @@ -1,194 +1 @@ -.. notice for github users - -Disclaimer -========== - -Certbot (previously, the Let's Encrypt client) is **BETA SOFTWARE**. It -contains plenty of bugs and 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 -https://letsencrypt.org. Be sure to checkout the -`Frequently Asked Questions (FAQ) `_. - -About Certbot -============================== - -Certbot 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. This client runs on Unix-based operating -systems. - -Until May 2016, Certbot was named simply ``letsencrypt`` or ``letsencrypt-auto``, -depending on install method. Instructions on the Internet, and some pieces of the -software, may still refer to this older name. - -Contributing ------------- - -If you'd like to contribute to this project please read `Developer Guide -`_. - -.. _installation: - -Installation ------------- - -If ``certbot`` (or ``letsencrypt``) is packaged for your Unix OS (visit -certbot.eff.org_ to find out), you can install it -from there, and run it by typing ``certbot`` (or ``letsencrypt``). Because -not all operating systems have packages yet, we provide a temporary solution -via the ``certbot-auto`` wrapper script, which obtains some dependencies from -your OS and puts others in a python virtual environment:: - - user@webserver:~$ wget https://dl.eff.org/certbot-auto - user@webserver:~$ chmod a+x ./certbot-auto - user@webserver:~$ ./certbot-auto --help - -.. hint:: The certbot-auto download is protected by HTTPS, which is pretty good, but if you'd like to - double check the integrity of the ``certbot-auto`` script, you can use these steps for verification before running it:: - - user@server:~$ wget -N https://dl.eff.org/certbot-auto.asc - user@server:~$ gpg2 --recv-key A2CFB51FA275A7286234E7B24D17C995CD9775F2 - user@server:~$ gpg2 --trusted-key 4D17C995CD9775F2 --verify certbot-auto.asc certbot-auto - -And for full command line help, you can type:: - - ./certbot-auto --help all - -``certbot-auto`` updates to the latest client release automatically. And -since ``certbot-auto`` is a wrapper to ``certbot``, 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 ``certbot-auto`` or ``certbot``, 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 from the command line. -For instance, if you want to obtain a cert for ``example.com``, -``www.example.com``, and ``other.example.net``, using the Apache plugin to both -obtain and install the certs, you could do this:: - - ./certbot-auto --apache -d example.com -d www.example.com -d other.example.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 "standalone" or "webroot" plugins to obtain a certificate:: - - ./certbot-auto certonly --standalone --email admin@example.com -d example.com -d www.example.com -d other.example.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://certbot.eff.org/docs - -Software project: https://github.com/certbot/certbot - -Notes for developers: https://certbot.eff.org/docs/contributing.html - -Main Website: https://letsencrypt.org/ - -IRC Channel: #letsencrypt on `Freenode`_ or #certbot on `OFTC`_ - -Community: https://community.letsencrypt.org - -ACME spec: http://ietf-wg-acme.github.io/acme/ - -ACME working area in github: https://github.com/ietf-wg-acme/acme - - -Mailing list: `client-dev`_ (to subscribe without a Google account, send an -email to client-dev+subscribe@letsencrypt.org) - -|build-status| |coverage| |docs| |container| - - - -.. |build-status| image:: https://travis-ci.org/certbot/certbot.svg?branch=master - :target: https://travis-ci.org/certbot/certbot - :alt: Travis CI status - -.. |coverage| image:: https://coveralls.io/repos/certbot/certbot/badge.svg?branch=master - :target: https://coveralls.io/r/certbot/certbot - :alt: Coverage status - -.. |docs| image:: https://readthedocs.org/projects/letsencrypt/badge/ - :target: https://readthedocs.org/projects/letsencrypt/ - :alt: Documentation status - -.. |container| image:: https://quay.io/repository/letsencrypt/letsencrypt/status - :target: https://quay.io/repository/letsencrypt/letsencrypt - :alt: Docker Repository on Quay.io - -.. _`installation instructions`: - https://letsencrypt.readthedocs.org/en/latest/using.html - -.. _watch demo video: https://www.youtube.com/watch?v=Gas_sSB-5SU - -System Requirements -=================== - -The Let's Encrypt Client presently only runs on Unix-ish OSes that include -Python 2.6 or 2.7; Python 3.x support will hopefully be added in the future. The -client requires root access in order to write to ``/etc/letsencrypt``, -``/var/log/letsencrypt``, ``/var/lib/letsencrypt``; to bind to ports 80 and 443 -(if you use the ``standalone`` plugin) and to read and modify webserver -configurations (if you use the ``apache`` or ``nginx`` plugins). If none of -these apply to you, it is theoretically possible to run without root privileges, -but for most users who want to avoid running an ACME client as root, either -`letsencrypt-nosudo `_ or -`simp_le `_ are more appropriate choices. - -The Apache plugin currently requires a Debian-based OS with augeas version -1.0; this includes Ubuntu 12.04+ and Debian 7+. - - -Current Features -================ - -* Supports multiple web servers: - - - 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+ (highly experimental, not included in certbot-auto) - -* The private key is generated locally on your system. -* Can talk to the Let's Encrypt CA or optionally to other ACME - compliant services. -* Can get domain-validated (DV) certificates. -* Can revoke certificates. -* Adjustable RSA key bit-length (2048 (default), 4096, ...). -* Can optionally install a http -> https redirect, so your site effectively - runs https only (Apache only) -* Fully automated. -* Configuration changes are logged and can be reverted. -* Supports ncurses and text (-t) UI, or can be driven entirely from the - command line. -* Free and Open Source Software, made with Python. - - -.. _Freenode: https://webchat.freenode.net?channels=%23letsencrypt -.. _OFTC: https://webchat.oftc.net?channels=%23certbot -.. _client-dev: https://groups.google.com/a/letsencrypt.org/forum/#!forum/client-dev -.. _certbot.eff.org: https://certbot.eff.org/ +.. include:: docs/intro_common.rst diff --git a/docs/intro.rst b/docs/intro.rst index 2fffbec68..b841aece9 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -1,6 +1,6 @@ ===================== -README / Introduction +Introduction ===================== -.. include:: ../README.rst +.. include:: intro_common.rst .. include:: ../CHANGES.rst diff --git a/docs/intro_common.rst b/docs/intro_common.rst new file mode 100644 index 000000000..30da17fa1 --- /dev/null +++ b/docs/intro_common.rst @@ -0,0 +1,192 @@ +Disclaimer +========== + +Certbot (previously, the Let's Encrypt client) is **BETA SOFTWARE**. It +contains plenty of bugs and 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 +https://letsencrypt.org. Be sure to checkout the +`Frequently Asked Questions (FAQ) `_. + +About Certbot +============================== + +Certbot 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. This client runs on Unix-based operating +systems. + +Until May 2016, Certbot was named simply ``letsencrypt`` or ``letsencrypt-auto``, +depending on install method. Instructions on the Internet, and some pieces of the +software, may still refer to this older name. + +Contributing +------------ + +If you'd like to contribute to this project please read `Developer Guide +`_. + +.. _installation: + +Installation +------------ + +If ``certbot`` (or ``letsencrypt``) is packaged for your Unix OS (visit +certbot.eff.org_ to find out), you can install it +from there, and run it by typing ``certbot`` (or ``letsencrypt``). Because +not all operating systems have packages yet, we provide a temporary solution +via the ``certbot-auto`` wrapper script, which obtains some dependencies from +your OS and puts others in a python virtual environment:: + + user@webserver:~$ wget https://dl.eff.org/certbot-auto + user@webserver:~$ chmod a+x ./certbot-auto + user@webserver:~$ ./certbot-auto --help + +.. hint:: The certbot-auto download is protected by HTTPS, which is pretty good, but if you'd like to + double check the integrity of the ``certbot-auto`` script, you can use these steps for verification before running it:: + + user@server:~$ wget -N https://dl.eff.org/certbot-auto.asc + user@server:~$ gpg2 --recv-key A2CFB51FA275A7286234E7B24D17C995CD9775F2 + user@server:~$ gpg2 --trusted-key 4D17C995CD9775F2 --verify certbot-auto.asc certbot-auto + +And for full command line help, you can type:: + + ./certbot-auto --help all + +``certbot-auto`` updates to the latest client release automatically. And +since ``certbot-auto`` is a wrapper to ``certbot``, 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 ``certbot-auto`` or ``certbot``, 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 from the command line. +For instance, if you want to obtain a cert for ``example.com``, +``www.example.com``, and ``other.example.net``, using the Apache plugin to both +obtain and install the certs, you could do this:: + + ./certbot-auto --apache -d example.com -d www.example.com -d other.example.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 "standalone" or "webroot" plugins to obtain a certificate:: + + ./certbot-auto certonly --standalone --email admin@example.com -d example.com -d www.example.com -d other.example.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://certbot.eff.org/docs + +Software project: https://github.com/certbot/certbot + +Notes for developers: https://certbot.eff.org/docs/contributing.html + +Main Website: https://letsencrypt.org/ + +IRC Channel: #letsencrypt on `Freenode`_ or #certbot on `OFTC`_ + +Community: https://community.letsencrypt.org + +ACME spec: http://ietf-wg-acme.github.io/acme/ + +ACME working area in github: https://github.com/ietf-wg-acme/acme + + +Mailing list: `client-dev`_ (to subscribe without a Google account, send an +email to client-dev+subscribe@letsencrypt.org) + +|build-status| |coverage| |docs| |container| + + + +.. |build-status| image:: https://travis-ci.org/certbot/certbot.svg?branch=master + :target: https://travis-ci.org/certbot/certbot + :alt: Travis CI status + +.. |coverage| image:: https://coveralls.io/repos/certbot/certbot/badge.svg?branch=master + :target: https://coveralls.io/r/certbot/certbot + :alt: Coverage status + +.. |docs| image:: https://readthedocs.org/projects/letsencrypt/badge/ + :target: https://readthedocs.org/projects/letsencrypt/ + :alt: Documentation status + +.. |container| image:: https://quay.io/repository/letsencrypt/letsencrypt/status + :target: https://quay.io/repository/letsencrypt/letsencrypt + :alt: Docker Repository on Quay.io + +.. _`installation instructions`: + https://letsencrypt.readthedocs.org/en/latest/using.html + +.. _watch demo video: https://www.youtube.com/watch?v=Gas_sSB-5SU + +System Requirements +=================== + +The Let's Encrypt Client presently only runs on Unix-ish OSes that include +Python 2.6 or 2.7; Python 3.x support will hopefully be added in the future. The +client requires root access in order to write to ``/etc/letsencrypt``, +``/var/log/letsencrypt``, ``/var/lib/letsencrypt``; to bind to ports 80 and 443 +(if you use the ``standalone`` plugin) and to read and modify webserver +configurations (if you use the ``apache`` or ``nginx`` plugins). If none of +these apply to you, it is theoretically possible to run without root privileges, +but for most users who want to avoid running an ACME client as root, either +`letsencrypt-nosudo `_ or +`simp_le `_ are more appropriate choices. + +The Apache plugin currently requires a Debian-based OS with augeas version +1.0; this includes Ubuntu 12.04+ and Debian 7+. + + +Current Features +================ + +* Supports multiple web servers: + + - 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+ (highly experimental, not included in certbot-auto) + +* The private key is generated locally on your system. +* Can talk to the Let's Encrypt CA or optionally to other ACME + compliant services. +* Can get domain-validated (DV) certificates. +* Can revoke certificates. +* Adjustable RSA key bit-length (2048 (default), 4096, ...). +* Can optionally install a http -> https redirect, so your site effectively + runs https only (Apache only) +* Fully automated. +* Configuration changes are logged and can be reverted. +* Supports ncurses and text (-t) UI, or can be driven entirely from the + command line. +* Free and Open Source Software, made with Python. + + +.. _Freenode: https://webchat.freenode.net?channels=%23letsencrypt +.. _OFTC: https://webchat.oftc.net?channels=%23certbot +.. _client-dev: https://groups.google.com/a/letsencrypt.org/forum/#!forum/client-dev +.. _certbot.eff.org: https://certbot.eff.org/ From 26ac17a4a1fa2718719f5e1ecd50207ef6e6dba0 Mon Sep 17 00:00:00 2001 From: Brad Warren Date: Thu, 14 Jul 2016 15:07:32 -0700 Subject: [PATCH 02/16] Add quick install page --- docs/index.rst | 1 + docs/install.rst | 3 +++ 2 files changed, 4 insertions(+) create mode 100644 docs/install.rst diff --git a/docs/index.rst b/docs/index.rst index b541e376e..dab1f6201 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,6 +5,7 @@ Welcome to the Certbot documentation! :maxdepth: 2 intro + install using contributing packaging diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 000000000..d21ddaf44 --- /dev/null +++ b/docs/install.rst @@ -0,0 +1,3 @@ +===================== +Quick Installation +===================== From 129f78a7f5e7d5370f153cb1ec4ee5e3ca269fd9 Mon Sep 17 00:00:00 2001 From: Brad Warren Date: Thu, 14 Jul 2016 15:11:39 -0700 Subject: [PATCH 03/16] Add resources page --- docs/index.rst | 1 + docs/resources.rst | 3 +++ 2 files changed, 4 insertions(+) create mode 100644 docs/resources.rst diff --git a/docs/index.rst b/docs/index.rst index dab1f6201..746080864 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,6 +9,7 @@ Welcome to the Certbot documentation! using contributing packaging + resources .. toctree:: :maxdepth: 1 diff --git a/docs/resources.rst b/docs/resources.rst new file mode 100644 index 000000000..7f9fb93b6 --- /dev/null +++ b/docs/resources.rst @@ -0,0 +1,3 @@ +===================== +Resources +===================== From 7b029afb10192954805ea2c7104131e6a0152e5a Mon Sep 17 00:00:00 2001 From: Jason Grinblat Date: Thu, 14 Jul 2016 16:11:01 -0700 Subject: [PATCH 04/16] Adds new introduction and refactors the old introduction --- docs/current_features.rst | 25 +++++ docs/install.rst | 28 ++++++ docs/intro.rst | 3 + docs/intro_common.rst | 192 +------------------------------------- docs/resources.rst | 47 ++++++++++ docs/using.rst | 24 ++++- 6 files changed, 130 insertions(+), 189 deletions(-) create mode 100644 docs/current_features.rst diff --git a/docs/current_features.rst b/docs/current_features.rst new file mode 100644 index 000000000..5bb037756 --- /dev/null +++ b/docs/current_features.rst @@ -0,0 +1,25 @@ +===================== +Current Features +===================== + +* Supports multiple web servers: + + - 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+ (highly experimental, not included in certbot-auto) + +* The private key is generated locally on your system. +* Can talk to the Let's Encrypt CA or optionally to other ACME + compliant services. +* Can get domain-validated (DV) certificates. +* Can revoke certificates. +* Adjustable RSA key bit-length (2048 (default), 4096, ...). +* Can optionally install a http -> https redirect, so your site effectively + runs https only (Apache only) +* Fully automated. +* Configuration changes are logged and can be reverted. +* Supports ncurses and text (-t) UI, or can be driven entirely from the + command line. +* Free and Open Source Software, made with Python. \ No newline at end of file diff --git a/docs/install.rst b/docs/install.rst index d21ddaf44..1bccdad0c 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -1,3 +1,31 @@ ===================== Quick Installation ===================== + +If ``certbot`` (or ``letsencrypt``) is packaged for your Unix OS (visit +certbot.eff.org_ to find out), you can install it +from there, and run it by typing ``certbot`` (or ``letsencrypt``). Because +not all operating systems have packages yet, we provide a temporary solution +via the ``certbot-auto`` wrapper script, which obtains some dependencies from +your OS and puts others in a python virtual environment:: + + user@webserver:~$ wget https://dl.eff.org/certbot-auto + user@webserver:~$ chmod a+x ./certbot-auto + user@webserver:~$ ./certbot-auto --help + +.. hint:: The certbot-auto download is protected by HTTPS, which is pretty good, but if you'd like to + double check the integrity of the ``certbot-auto`` script, you can use these steps for verification before running it:: + + user@server:~$ wget -N https://dl.eff.org/certbot-auto.asc + user@server:~$ gpg2 --recv-key A2CFB51FA275A7286234E7B24D17C995CD9775F2 + user@server:~$ gpg2 --trusted-key 4D17C995CD9775F2 --verify certbot-auto.asc certbot-auto + +And for full command line help, you can type:: + + ./certbot-auto --help all + +``certbot-auto`` updates to the latest client release automatically. And +since ``certbot-auto`` is a wrapper to ``certbot``, 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 +`_. \ No newline at end of file diff --git a/docs/intro.rst b/docs/intro.rst index b841aece9..5122487bf 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -3,4 +3,7 @@ Introduction ===================== .. include:: intro_common.rst +.. include:: current_features.rst .. include:: ../CHANGES.rst + +For extensive documentation on using and contributing to Certbot, go to https://certbot.eff.org/docs. \ No newline at end of file diff --git a/docs/intro_common.rst b/docs/intro_common.rst index 30da17fa1..4ca286f07 100644 --- a/docs/intro_common.rst +++ b/docs/intro_common.rst @@ -1,192 +1,8 @@ -Disclaimer -========== -Certbot (previously, the Let's Encrypt client) is **BETA SOFTWARE**. It -contains plenty of bugs and rough edges, and should be tested thoroughly in -staging environments before use on production systems. +Certbot is part of EFF’s effort to encrypt the entire Internet. Secure communication over the Web relies on HTTPS, which requires the use of a digital certificate that lets browsers verify the identify of web servers (e.g., is that really google.com?). Web servers obtain their certificates from trusted third parties called certificate authorities (CAs). Certbot is an easy-to-use client that fetches a certificate from Let’s Encrypt—an open certificate authority launched by the EFF, Mozilla, and others—and deploys it to a web server. -For more information regarding the status of the project, please see -https://letsencrypt.org. Be sure to checkout the -`Frequently Asked Questions (FAQ) `_. +Anyone who has gone through the trouble of setting up a secure website knows what a hassle getting and maintaining a certificate is. Certbot and Let’s Encrypt can automate away the pain and let you turn on and manage HTTPS with simple commands. Using Certbot and Let's Encrypt is free, so there’s no need to arrange payment. -About Certbot -============================== +How you use Certbot depends on the configuration of your web server. The best way to get started is to use our `interactive guide`_. It generates instructions based on your configuration settings. You’ll need root or administrator access to your web server to run Certbot. -Certbot 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. This client runs on Unix-based operating -systems. - -Until May 2016, Certbot was named simply ``letsencrypt`` or ``letsencrypt-auto``, -depending on install method. Instructions on the Internet, and some pieces of the -software, may still refer to this older name. - -Contributing ------------- - -If you'd like to contribute to this project please read `Developer Guide -`_. - -.. _installation: - -Installation ------------- - -If ``certbot`` (or ``letsencrypt``) is packaged for your Unix OS (visit -certbot.eff.org_ to find out), you can install it -from there, and run it by typing ``certbot`` (or ``letsencrypt``). Because -not all operating systems have packages yet, we provide a temporary solution -via the ``certbot-auto`` wrapper script, which obtains some dependencies from -your OS and puts others in a python virtual environment:: - - user@webserver:~$ wget https://dl.eff.org/certbot-auto - user@webserver:~$ chmod a+x ./certbot-auto - user@webserver:~$ ./certbot-auto --help - -.. hint:: The certbot-auto download is protected by HTTPS, which is pretty good, but if you'd like to - double check the integrity of the ``certbot-auto`` script, you can use these steps for verification before running it:: - - user@server:~$ wget -N https://dl.eff.org/certbot-auto.asc - user@server:~$ gpg2 --recv-key A2CFB51FA275A7286234E7B24D17C995CD9775F2 - user@server:~$ gpg2 --trusted-key 4D17C995CD9775F2 --verify certbot-auto.asc certbot-auto - -And for full command line help, you can type:: - - ./certbot-auto --help all - -``certbot-auto`` updates to the latest client release automatically. And -since ``certbot-auto`` is a wrapper to ``certbot``, 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 ``certbot-auto`` or ``certbot``, 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 from the command line. -For instance, if you want to obtain a cert for ``example.com``, -``www.example.com``, and ``other.example.net``, using the Apache plugin to both -obtain and install the certs, you could do this:: - - ./certbot-auto --apache -d example.com -d www.example.com -d other.example.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 "standalone" or "webroot" plugins to obtain a certificate:: - - ./certbot-auto certonly --standalone --email admin@example.com -d example.com -d www.example.com -d other.example.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://certbot.eff.org/docs - -Software project: https://github.com/certbot/certbot - -Notes for developers: https://certbot.eff.org/docs/contributing.html - -Main Website: https://letsencrypt.org/ - -IRC Channel: #letsencrypt on `Freenode`_ or #certbot on `OFTC`_ - -Community: https://community.letsencrypt.org - -ACME spec: http://ietf-wg-acme.github.io/acme/ - -ACME working area in github: https://github.com/ietf-wg-acme/acme - - -Mailing list: `client-dev`_ (to subscribe without a Google account, send an -email to client-dev+subscribe@letsencrypt.org) - -|build-status| |coverage| |docs| |container| - - - -.. |build-status| image:: https://travis-ci.org/certbot/certbot.svg?branch=master - :target: https://travis-ci.org/certbot/certbot - :alt: Travis CI status - -.. |coverage| image:: https://coveralls.io/repos/certbot/certbot/badge.svg?branch=master - :target: https://coveralls.io/r/certbot/certbot - :alt: Coverage status - -.. |docs| image:: https://readthedocs.org/projects/letsencrypt/badge/ - :target: https://readthedocs.org/projects/letsencrypt/ - :alt: Documentation status - -.. |container| image:: https://quay.io/repository/letsencrypt/letsencrypt/status - :target: https://quay.io/repository/letsencrypt/letsencrypt - :alt: Docker Repository on Quay.io - -.. _`installation instructions`: - https://letsencrypt.readthedocs.org/en/latest/using.html - -.. _watch demo video: https://www.youtube.com/watch?v=Gas_sSB-5SU - -System Requirements -=================== - -The Let's Encrypt Client presently only runs on Unix-ish OSes that include -Python 2.6 or 2.7; Python 3.x support will hopefully be added in the future. The -client requires root access in order to write to ``/etc/letsencrypt``, -``/var/log/letsencrypt``, ``/var/lib/letsencrypt``; to bind to ports 80 and 443 -(if you use the ``standalone`` plugin) and to read and modify webserver -configurations (if you use the ``apache`` or ``nginx`` plugins). If none of -these apply to you, it is theoretically possible to run without root privileges, -but for most users who want to avoid running an ACME client as root, either -`letsencrypt-nosudo `_ or -`simp_le `_ are more appropriate choices. - -The Apache plugin currently requires a Debian-based OS with augeas version -1.0; this includes Ubuntu 12.04+ and Debian 7+. - - -Current Features -================ - -* Supports multiple web servers: - - - 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+ (highly experimental, not included in certbot-auto) - -* The private key is generated locally on your system. -* Can talk to the Let's Encrypt CA or optionally to other ACME - compliant services. -* Can get domain-validated (DV) certificates. -* Can revoke certificates. -* Adjustable RSA key bit-length (2048 (default), 4096, ...). -* Can optionally install a http -> https redirect, so your site effectively - runs https only (Apache only) -* Fully automated. -* Configuration changes are logged and can be reverted. -* Supports ncurses and text (-t) UI, or can be driven entirely from the - command line. -* Free and Open Source Software, made with Python. - - -.. _Freenode: https://webchat.freenode.net?channels=%23letsencrypt -.. _OFTC: https://webchat.oftc.net?channels=%23certbot -.. _client-dev: https://groups.google.com/a/letsencrypt.org/forum/#!forum/client-dev -.. _certbot.eff.org: https://certbot.eff.org/ +If you’re using a hosted service and don’t have direct access to your web server, you might not be able to use Certbot. Check with your hosting provider for documentation about uploading certificates or using certificates issues by Let’s Encrypt. \ No newline at end of file diff --git a/docs/resources.rst b/docs/resources.rst index 7f9fb93b6..94b5a9d58 100644 --- a/docs/resources.rst +++ b/docs/resources.rst @@ -1,3 +1,50 @@ ===================== Resources ===================== + +Documentation: https://certbot.eff.org/docs + +Software project: https://github.com/certbot/certbot + +Notes for developers: https://certbot.eff.org/docs/contributing.html + +Main Website: https://letsencrypt.org/ + +Let's Encrypt FAQ: https://community.letsencrypt.org/t/frequently-asked-questions-faq/26#topic-title + +IRC Channel: #letsencrypt on `Freenode`_ or #certbot on `OFTC`_ + +Community: https://community.letsencrypt.org + +ACME spec: http://ietf-wg-acme.github.io/acme/ + +ACME working area in github: https://github.com/ietf-wg-acme/acme + + +Mailing list: `client-dev`_ (to subscribe without a Google account, send an +email to client-dev+subscribe@letsencrypt.org) + +|build-status| |coverage| |docs| |container| + + + +.. |build-status| image:: https://travis-ci.org/certbot/certbot.svg?branch=master + :target: https://travis-ci.org/certbot/certbot + :alt: Travis CI status + +.. |coverage| image:: https://coveralls.io/repos/certbot/certbot/badge.svg?branch=master + :target: https://coveralls.io/r/certbot/certbot + :alt: Coverage status + +.. |docs| image:: https://readthedocs.org/projects/letsencrypt/badge/ + :target: https://readthedocs.org/projects/letsencrypt/ + :alt: Documentation status + +.. |container| image:: https://quay.io/repository/letsencrypt/letsencrypt/status + :target: https://quay.io/repository/letsencrypt/letsencrypt + :alt: Docker Repository on Quay.io + +.. _`installation instructions`: + https://letsencrypt.readthedocs.org/en/latest/using.html + +.. _watch demo video: https://www.youtube.com/watch?v=Gas_sSB-5SU diff --git a/docs/using.rst b/docs/using.rst index 806dfb340..6620c2575 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -5,12 +5,31 @@ User Guide .. contents:: Table of Contents :local: + +System Requirements +=================== + +The Let's Encrypt Client presently only runs on Unix-ish OSes that include +Python 2.6 or 2.7; Python 3.x support will hopefully be added in the future. The +client requires root access in order to write to ``/etc/letsencrypt``, +``/var/log/letsencrypt``, ``/var/lib/letsencrypt``; to bind to ports 80 and 443 +(if you use the ``standalone`` plugin) and to read and modify webserver +configurations (if you use the ``apache`` or ``nginx`` plugins). If none of +these apply to you, it is theoretically possible to run without root privileges, +but for most users who want to avoid running an ACME client as root, either +`letsencrypt-nosudo `_ or +`simp_le `_ are more appropriate choices. + +The Apache plugin currently requires a Debian-based OS with augeas version +1.0; this includes Ubuntu 12.04+ and Debian 7+. + + Getting Certbot =============== To get specific instructions for installing Certbot on your OS, we recommend visiting certbot.eff.org_. If you're offline, you can find some general -instructions `in the README / Introduction `__ +instructions `Quick Installation `__ __ installation_ .. _certbot.eff.org: https://certbot.eff.org @@ -552,3 +571,6 @@ Beyond the methods discussed here, other methods may be possible, such as installing Certbot directly with pip from PyPI or downloading a ZIP archive from GitHub may be technically possible but are not presently recommended or supported. + +.. include:: current_features.rst +.. include:: ../CHANGES.rst From fd308f8ce1d51ab30af42f8b40914a28cf3a2480 Mon Sep 17 00:00:00 2001 From: Brad Warren Date: Fri, 15 Jul 2016 09:34:12 -0700 Subject: [PATCH 05/16] Make current features a subsection --- docs/current_features.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/current_features.rst b/docs/current_features.rst index 5bb037756..16c26af01 100644 --- a/docs/current_features.rst +++ b/docs/current_features.rst @@ -1,4 +1,3 @@ -===================== Current Features ===================== @@ -22,4 +21,4 @@ Current Features * Configuration changes are logged and can be reverted. * Supports ncurses and text (-t) UI, or can be driven entirely from the command line. -* Free and Open Source Software, made with Python. \ No newline at end of file +* Free and Open Source Software, made with Python. From 8be5849a9e9f7497e19fd71e5a42861434fca7b2 Mon Sep 17 00:00:00 2001 From: Brad Warren Date: Fri, 15 Jul 2016 09:35:42 -0700 Subject: [PATCH 06/16] Flip README and intro --- README.rst | 4 ++++ docs/intro.rst | 4 ---- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index 06cb3f8bc..e7bac2fde 100644 --- a/README.rst +++ b/README.rst @@ -1 +1,5 @@ .. include:: docs/intro_common.rst +.. include:: docs/current_features.rst +.. include:: CHANGES.rst + +For extensive documentation on using and contributing to Certbot, go to https://certbot.eff.org/docs. diff --git a/docs/intro.rst b/docs/intro.rst index 5122487bf..65c862f69 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -3,7 +3,3 @@ Introduction ===================== .. include:: intro_common.rst -.. include:: current_features.rst -.. include:: ../CHANGES.rst - -For extensive documentation on using and contributing to Certbot, go to https://certbot.eff.org/docs. \ No newline at end of file From 37c8abf1e5a8045f869de06b9e851b76dbe919a4 Mon Sep 17 00:00:00 2001 From: Brad Warren Date: Fri, 15 Jul 2016 09:36:44 -0700 Subject: [PATCH 07/16] Fix interactive guide link --- docs/intro_common.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/intro_common.rst b/docs/intro_common.rst index 4ca286f07..630e07b51 100644 --- a/docs/intro_common.rst +++ b/docs/intro_common.rst @@ -3,6 +3,6 @@ Certbot is part of EFF’s effort to encrypt the entire Internet. Secure communi Anyone who has gone through the trouble of setting up a secure website knows what a hassle getting and maintaining a certificate is. Certbot and Let’s Encrypt can automate away the pain and let you turn on and manage HTTPS with simple commands. Using Certbot and Let's Encrypt is free, so there’s no need to arrange payment. -How you use Certbot depends on the configuration of your web server. The best way to get started is to use our `interactive guide`_. It generates instructions based on your configuration settings. You’ll need root or administrator access to your web server to run Certbot. +How you use Certbot depends on the configuration of your web server. The best way to get started is to use our `interactive guide `_. It generates instructions based on your configuration settings. You’ll need root or administrator access to your web server to run Certbot. -If you’re using a hosted service and don’t have direct access to your web server, you might not be able to use Certbot. Check with your hosting provider for documentation about uploading certificates or using certificates issues by Let’s Encrypt. \ No newline at end of file +If you’re using a hosted service and don’t have direct access to your web server, you might not be able to use Certbot. Check with your hosting provider for documentation about uploading certificates or using certificates issues by Let’s Encrypt. From 9fb235850731a6c7a6eadd2650108b3564da9d22 Mon Sep 17 00:00:00 2001 From: Brad Warren Date: Wed, 20 Jul 2016 14:59:42 -0700 Subject: [PATCH 08/16] Move text back into README --- README.rst | 43 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 40 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index e7bac2fde..9be732c3b 100644 --- a/README.rst +++ b/README.rst @@ -1,5 +1,42 @@ -.. include:: docs/intro_common.rst -.. include:: docs/current_features.rst -.. include:: CHANGES.rst +.. This file contains of a series of comments that are used to include sections of this README in other files. Do not modify these comments unless you know what you are doing. tag:intro-begin + +Certbot is part of EFF’s effort to encrypt the entire Internet. Secure communication over the Web relies on HTTPS, which requires the use of a digital certificate that lets browsers verify the identify of web servers (e.g., is that really google.com?). Web servers obtain their certificates from trusted third parties called certificate authorities (CAs). Certbot is an easy-to-use client that fetches a certificate from Let’s Encrypt—an open certificate authority launched by the EFF, Mozilla, and others—and deploys it to a web server. + +Anyone who has gone through the trouble of setting up a secure website knows what a hassle getting and maintaining a certificate is. Certbot and Let’s Encrypt can automate away the pain and let you turn on and manage HTTPS with simple commands. Using Certbot and Let's Encrypt is free, so there’s no need to arrange payment. + +How you use Certbot depends on the configuration of your web server. The best way to get started is to use our `interactive guide `_. It generates instructions based on your configuration settings. You’ll need root or administrator access to your web server to run Certbot. + +If you’re using a hosted service and don’t have direct access to your web server, you might not be able to use Certbot. Check with your hosting provider for documentation about uploading certificates or using certificates issues by Let’s Encrypt. + +.. Do not modify this comment unless you know what you're doing. tag:intro-end + +.. Do not modify this comment unless you know what you're doing. tag:features-begin + +Current Features +===================== + +* Supports multiple web servers: + + - 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+ (highly experimental, not included in certbot-auto) + +* The private key is generated locally on your system. +* Can talk to the Let's Encrypt CA or optionally to other ACME + compliant services. +* Can get domain-validated (DV) certificates. +* Can revoke certificates. +* Adjustable RSA key bit-length (2048 (default), 4096, ...). +* Can optionally install a http -> https redirect, so your site effectively + runs https only (Apache only) +* Fully automated. +* Configuration changes are logged and can be reverted. +* Supports ncurses and text (-t) UI, or can be driven entirely from the + command line. +* Free and Open Source Software, made with Python. + +.. Do not modify this comment unless you know what you're doing. tag:features-end For extensive documentation on using and contributing to Certbot, go to https://certbot.eff.org/docs. From e67144434471a5c07db6e1c624c7d3f6d182de6f Mon Sep 17 00:00:00 2001 From: Brad Warren Date: Wed, 20 Jul 2016 14:59:50 -0700 Subject: [PATCH 09/16] Make intro.rst include README --- docs/intro.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/intro.rst b/docs/intro.rst index 65c862f69..90c3761ec 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -2,4 +2,6 @@ Introduction ===================== -.. include:: intro_common.rst +.. include:: ../README.rst + :start-after: tag:intro-begin + :end-before: tag:intro-end From 642d67b3eb880aa036ab3644a0e777082b987d6a Mon Sep 17 00:00:00 2001 From: Brad Warren Date: Wed, 20 Jul 2016 15:00:33 -0700 Subject: [PATCH 10/16] Remove intro_common.rst --- docs/intro_common.rst | 8 -------- 1 file changed, 8 deletions(-) delete mode 100644 docs/intro_common.rst diff --git a/docs/intro_common.rst b/docs/intro_common.rst deleted file mode 100644 index 630e07b51..000000000 --- a/docs/intro_common.rst +++ /dev/null @@ -1,8 +0,0 @@ - -Certbot is part of EFF’s effort to encrypt the entire Internet. Secure communication over the Web relies on HTTPS, which requires the use of a digital certificate that lets browsers verify the identify of web servers (e.g., is that really google.com?). Web servers obtain their certificates from trusted third parties called certificate authorities (CAs). Certbot is an easy-to-use client that fetches a certificate from Let’s Encrypt—an open certificate authority launched by the EFF, Mozilla, and others—and deploys it to a web server. - -Anyone who has gone through the trouble of setting up a secure website knows what a hassle getting and maintaining a certificate is. Certbot and Let’s Encrypt can automate away the pain and let you turn on and manage HTTPS with simple commands. Using Certbot and Let's Encrypt is free, so there’s no need to arrange payment. - -How you use Certbot depends on the configuration of your web server. The best way to get started is to use our `interactive guide `_. It generates instructions based on your configuration settings. You’ll need root or administrator access to your web server to run Certbot. - -If you’re using a hosted service and don’t have direct access to your web server, you might not be able to use Certbot. Check with your hosting provider for documentation about uploading certificates or using certificates issues by Let’s Encrypt. From b9198591811217b406edb479e8c0d5fb3ba1614f Mon Sep 17 00:00:00 2001 From: Brad Warren Date: Wed, 20 Jul 2016 15:01:55 -0700 Subject: [PATCH 11/16] Include README for current_features in using.rst. --- docs/using.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/using.rst b/docs/using.rst index 6620c2575..ac0ce3bcd 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -572,5 +572,7 @@ installing Certbot directly with pip from PyPI or downloading a ZIP archive from GitHub may be technically possible but are not presently recommended or supported. -.. include:: current_features.rst +.. include:: ../README.rst + :start-after: tag:features-begin + :end-before: tag:features-end .. include:: ../CHANGES.rst From 4eb9ea7b720d70bc941355d98c126aa0a0f7eceb Mon Sep 17 00:00:00 2001 From: Brad Warren Date: Wed, 20 Jul 2016 15:02:10 -0700 Subject: [PATCH 12/16] Remove current_features.rst --- docs/current_features.rst | 24 ------------------------ 1 file changed, 24 deletions(-) delete mode 100644 docs/current_features.rst diff --git a/docs/current_features.rst b/docs/current_features.rst deleted file mode 100644 index 16c26af01..000000000 --- a/docs/current_features.rst +++ /dev/null @@ -1,24 +0,0 @@ -Current Features -===================== - -* Supports multiple web servers: - - - 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+ (highly experimental, not included in certbot-auto) - -* The private key is generated locally on your system. -* Can talk to the Let's Encrypt CA or optionally to other ACME - compliant services. -* Can get domain-validated (DV) certificates. -* Can revoke certificates. -* Adjustable RSA key bit-length (2048 (default), 4096, ...). -* Can optionally install a http -> https redirect, so your site effectively - runs https only (Apache only) -* Fully automated. -* Configuration changes are logged and can be reverted. -* Supports ncurses and text (-t) UI, or can be driven entirely from the - command line. -* Free and Open Source Software, made with Python. From 0c68a8cd6e6ee9ee4e84c3b878cd0bf2f4a6f87c Mon Sep 17 00:00:00 2001 From: Brad Warren Date: Wed, 20 Jul 2016 15:19:21 -0700 Subject: [PATCH 13/16] Fix broken links --- docs/install.rst | 4 +++- docs/resources.rst | 4 ++++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/install.rst b/docs/install.rst index 1bccdad0c..e79a3b596 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -28,4 +28,6 @@ And for full command line help, you can type:: since ``certbot-auto`` is a wrapper to ``certbot``, 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 -`_. \ No newline at end of file +`_. + +.. _certbot.eff.org: https://certbot.eff.org/ diff --git a/docs/resources.rst b/docs/resources.rst index 94b5a9d58..a284f4a3d 100644 --- a/docs/resources.rst +++ b/docs/resources.rst @@ -48,3 +48,7 @@ email to client-dev+subscribe@letsencrypt.org) https://letsencrypt.readthedocs.org/en/latest/using.html .. _watch demo video: https://www.youtube.com/watch?v=Gas_sSB-5SU + +.. _Freenode: https://webchat.freenode.net?channels=%23letsencrypt +.. _OFTC: https://webchat.oftc.net?channels=%23certbot +.. _client-dev: https://groups.google.com/a/letsencrypt.org/forum/#!forum/client-dev From 07eaa4a61b603889cb9b9a8dd01840ccc235758e Mon Sep 17 00:00:00 2001 From: Brad Warren Date: Thu, 28 Jul 2016 17:11:07 -0700 Subject: [PATCH 14/16] Clarify need for root privileges --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 9be732c3b..f2f1b1191 100644 --- a/README.rst +++ b/README.rst @@ -4,7 +4,7 @@ Certbot is part of EFF’s effort to encrypt the entire Internet. Secure communi Anyone who has gone through the trouble of setting up a secure website knows what a hassle getting and maintaining a certificate is. Certbot and Let’s Encrypt can automate away the pain and let you turn on and manage HTTPS with simple commands. Using Certbot and Let's Encrypt is free, so there’s no need to arrange payment. -How you use Certbot depends on the configuration of your web server. The best way to get started is to use our `interactive guide `_. It generates instructions based on your configuration settings. You’ll need root or administrator access to your web server to run Certbot. +How you use Certbot depends on the configuration of your web server. The best way to get started is to use our `interactive guide `_. It generates instructions based on your configuration settings. In most cases, you’ll need root or administrator access to your web server to run Certbot. More information about the privileges Certbot requires can be found in our `FAQ `_. If you’re using a hosted service and don’t have direct access to your web server, you might not be able to use Certbot. Check with your hosting provider for documentation about uploading certificates or using certificates issues by Let’s Encrypt. From eeb0948a96423f194150e2c675c7a1af79342a3d Mon Sep 17 00:00:00 2001 From: Brad Warren Date: Thu, 28 Jul 2016 17:14:04 -0700 Subject: [PATCH 15/16] point devs specifically at developer guide --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index f2f1b1191..bea900889 100644 --- a/README.rst +++ b/README.rst @@ -39,4 +39,4 @@ Current Features .. Do not modify this comment unless you know what you're doing. tag:features-end -For extensive documentation on using and contributing to Certbot, go to https://certbot.eff.org/docs. +For extensive documentation on using and contributing to Certbot, go to https://certbot.eff.org/docs. If you would like to contribute to the project, you should read our `developer guide `. From fbf8a2715765931bdd68dbaa57778e886c804c29 Mon Sep 17 00:00:00 2001 From: Peter Eckersley Date: Thu, 28 Jul 2016 19:05:08 -0700 Subject: [PATCH 16/16] Slight tweaks --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index bea900889..fe66f8af2 100644 --- a/README.rst +++ b/README.rst @@ -4,7 +4,7 @@ Certbot is part of EFF’s effort to encrypt the entire Internet. Secure communi Anyone who has gone through the trouble of setting up a secure website knows what a hassle getting and maintaining a certificate is. Certbot and Let’s Encrypt can automate away the pain and let you turn on and manage HTTPS with simple commands. Using Certbot and Let's Encrypt is free, so there’s no need to arrange payment. -How you use Certbot depends on the configuration of your web server. The best way to get started is to use our `interactive guide `_. It generates instructions based on your configuration settings. In most cases, you’ll need root or administrator access to your web server to run Certbot. More information about the privileges Certbot requires can be found in our `FAQ `_. +How you use Certbot depends on the configuration of your web server. The best way to get started is to use our `interactive guide `_. It generates instructions based on your configuration settings. In most cases, you’ll need `root or administrator access `_ to your web server to run Certbot. If you’re using a hosted service and don’t have direct access to your web server, you might not be able to use Certbot. Check with your hosting provider for documentation about uploading certificates or using certificates issues by Let’s Encrypt. @@ -39,4 +39,4 @@ Current Features .. Do not modify this comment unless you know what you're doing. tag:features-end -For extensive documentation on using and contributing to Certbot, go to https://certbot.eff.org/docs. If you would like to contribute to the project, you should read our `developer guide `. +For extensive documentation on using and contributing to Certbot, go to https://certbot.eff.org/docs. If you would like to contribute to the project or run the latest code from git, you should read our `developer guide `.