From e2af5ab9b495ca22009b5b251cd2d1df48635872 Mon Sep 17 00:00:00 2001 From: Noah Swartz Date: Fri, 1 Apr 2016 16:42:44 -0700 Subject: [PATCH] updated docs with s/letsencrypt/certbot/g and more --- docs/api/account.rst | 4 +- docs/api/achallenges.rst | 4 +- docs/api/auth_handler.rst | 4 +- docs/api/cb_util.rst | 5 ++ docs/api/client.rst | 4 +- docs/api/configuration.rst | 4 +- docs/api/constants.rst | 4 +- docs/api/continuity_auth.rst | 4 +- docs/api/crypto_util.rst | 4 +- docs/api/display.rst | 16 ++-- docs/api/errors.rst | 4 +- docs/api/index.rst | 4 +- docs/api/interfaces.rst | 4 +- docs/api/le_util.rst | 5 -- docs/api/log.rst | 4 +- docs/api/plugins/common.rst | 4 +- docs/api/plugins/disco.rst | 4 +- docs/api/plugins/manual.rst | 4 +- docs/api/plugins/standalone.rst | 4 +- docs/api/plugins/util.rst | 4 +- docs/api/plugins/webroot.rst | 4 +- docs/api/proof_of_possession.rst | 4 +- docs/api/reporter.rst | 4 +- docs/api/reverter.rst | 4 +- docs/api/storage.rst | 4 +- docs/ciphers.rst | 80 ++++++++--------- docs/contributing.rst | 60 ++++++------- docs/index.rst | 2 +- docs/man/certbot.rst | 1 + docs/man/letsencrypt.rst | 1 - docs/packaging.rst | 2 +- docs/using.rst | 146 +++++++++++++++---------------- 32 files changed, 201 insertions(+), 205 deletions(-) create mode 100644 docs/api/cb_util.rst delete mode 100644 docs/api/le_util.rst create mode 100644 docs/man/certbot.rst delete mode 100644 docs/man/letsencrypt.rst diff --git a/docs/api/account.rst b/docs/api/account.rst index 16c2061a8..fd90230ea 100644 --- a/docs/api/account.rst +++ b/docs/api/account.rst @@ -1,5 +1,5 @@ -:mod:`letsencrypt.account` +:mod:`certbot.account` -------------------------- -.. automodule:: letsencrypt.account +.. automodule:: certbot.account :members: diff --git a/docs/api/achallenges.rst b/docs/api/achallenges.rst index 09cec1702..90dda3f06 100644 --- a/docs/api/achallenges.rst +++ b/docs/api/achallenges.rst @@ -1,5 +1,5 @@ -:mod:`letsencrypt.achallenges` +:mod:`certbot.achallenges` ------------------------------ -.. automodule:: letsencrypt.achallenges +.. automodule:: certbot.achallenges :members: diff --git a/docs/api/auth_handler.rst b/docs/api/auth_handler.rst index 3b168faf8..8819bb1bd 100644 --- a/docs/api/auth_handler.rst +++ b/docs/api/auth_handler.rst @@ -1,5 +1,5 @@ -:mod:`letsencrypt.auth_handler` +:mod:`certbot.auth_handler` ------------------------------- -.. automodule:: letsencrypt.auth_handler +.. automodule:: certbot.auth_handler :members: diff --git a/docs/api/cb_util.rst b/docs/api/cb_util.rst new file mode 100644 index 000000000..066fa906c --- /dev/null +++ b/docs/api/cb_util.rst @@ -0,0 +1,5 @@ +:mod:`certbot.cb_util` +-------------------------- + +.. automodule:: certbot.cb_util + :members: diff --git a/docs/api/client.rst b/docs/api/client.rst index 7fe44df50..00a443cd9 100644 --- a/docs/api/client.rst +++ b/docs/api/client.rst @@ -1,5 +1,5 @@ -:mod:`letsencrypt.client` +:mod:`certbot.client` ------------------------- -.. automodule:: letsencrypt.client +.. automodule:: certbot.client :members: diff --git a/docs/api/configuration.rst b/docs/api/configuration.rst index e92392b99..4e99c73d2 100644 --- a/docs/api/configuration.rst +++ b/docs/api/configuration.rst @@ -1,5 +1,5 @@ -:mod:`letsencrypt.configuration` +:mod:`certbot.configuration` -------------------------------- -.. automodule:: letsencrypt.configuration +.. automodule:: certbot.configuration :members: diff --git a/docs/api/constants.rst b/docs/api/constants.rst index 3a2815b5e..e225056a2 100644 --- a/docs/api/constants.rst +++ b/docs/api/constants.rst @@ -1,5 +1,5 @@ -:mod:`letsencrypt.constants` +:mod:`certbot.constants` ----------------------------------- -.. automodule:: letsencrypt.constants +.. automodule:: certbot.constants :members: diff --git a/docs/api/continuity_auth.rst b/docs/api/continuity_auth.rst index 82869e6f4..3276220f5 100644 --- a/docs/api/continuity_auth.rst +++ b/docs/api/continuity_auth.rst @@ -1,5 +1,5 @@ -:mod:`letsencrypt.continuity_auth` +:mod:`certbot.continuity_auth` ---------------------------------- -.. automodule:: letsencrypt.continuity_auth +.. automodule:: certbot.continuity_auth :members: diff --git a/docs/api/crypto_util.rst b/docs/api/crypto_util.rst index 5d4c77538..2f473944c 100644 --- a/docs/api/crypto_util.rst +++ b/docs/api/crypto_util.rst @@ -1,5 +1,5 @@ -:mod:`letsencrypt.crypto_util` +:mod:`certbot.crypto_util` ------------------------------ -.. automodule:: letsencrypt.crypto_util +.. automodule:: certbot.crypto_util :members: diff --git a/docs/api/display.rst b/docs/api/display.rst index 117a91708..1a18e6534 100644 --- a/docs/api/display.rst +++ b/docs/api/display.rst @@ -1,23 +1,23 @@ -:mod:`letsencrypt.display` +:mod:`certbot.display` -------------------------- -.. automodule:: letsencrypt.display +.. automodule:: certbot.display :members: -:mod:`letsencrypt.display.util` +:mod:`certbot.display.util` =============================== -.. automodule:: letsencrypt.display.util +.. automodule:: certbot.display.util :members: -:mod:`letsencrypt.display.ops` +:mod:`certbot.display.ops` ============================== -.. automodule:: letsencrypt.display.ops +.. automodule:: certbot.display.ops :members: -:mod:`letsencrypt.display.enhancements` +:mod:`certbot.display.enhancements` ======================================= -.. automodule:: letsencrypt.display.enhancements +.. automodule:: certbot.display.enhancements :members: diff --git a/docs/api/errors.rst b/docs/api/errors.rst index 1ad13235c..a9324765b 100644 --- a/docs/api/errors.rst +++ b/docs/api/errors.rst @@ -1,5 +1,5 @@ -:mod:`letsencrypt.errors` +:mod:`certbot.errors` ------------------------- -.. automodule:: letsencrypt.errors +.. automodule:: certbot.errors :members: diff --git a/docs/api/index.rst b/docs/api/index.rst index a2475eeae..be94214c9 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -1,5 +1,5 @@ -:mod:`letsencrypt` +:mod:`certbot` ------------------ -.. automodule:: letsencrypt +.. automodule:: certbot :members: diff --git a/docs/api/interfaces.rst b/docs/api/interfaces.rst index 00b0a1e50..2988b3b87 100644 --- a/docs/api/interfaces.rst +++ b/docs/api/interfaces.rst @@ -1,5 +1,5 @@ -:mod:`letsencrypt.interfaces` +:mod:`certbot.interfaces` ----------------------------- -.. automodule:: letsencrypt.interfaces +.. automodule:: certbot.interfaces :members: diff --git a/docs/api/le_util.rst b/docs/api/le_util.rst deleted file mode 100644 index 8c6b717cf..000000000 --- a/docs/api/le_util.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`letsencrypt.le_util` --------------------------- - -.. automodule:: letsencrypt.le_util - :members: diff --git a/docs/api/log.rst b/docs/api/log.rst index f41c6c4b1..41311de90 100644 --- a/docs/api/log.rst +++ b/docs/api/log.rst @@ -1,5 +1,5 @@ -:mod:`letsencrypt.log` +:mod:`certbot.log` ---------------------- -.. automodule:: letsencrypt.log +.. automodule:: certbot.log :members: diff --git a/docs/api/plugins/common.rst b/docs/api/plugins/common.rst index ca55ba8fb..7cfaf8d70 100644 --- a/docs/api/plugins/common.rst +++ b/docs/api/plugins/common.rst @@ -1,5 +1,5 @@ -:mod:`letsencrypt.plugins.common` +:mod:`certbot.plugins.common` --------------------------------- -.. automodule:: letsencrypt.plugins.common +.. automodule:: certbot.plugins.common :members: diff --git a/docs/api/plugins/disco.rst b/docs/api/plugins/disco.rst index 7bf2b76b4..1a27f0f69 100644 --- a/docs/api/plugins/disco.rst +++ b/docs/api/plugins/disco.rst @@ -1,5 +1,5 @@ -:mod:`letsencrypt.plugins.disco` +:mod:`certbot.plugins.disco` -------------------------------- -.. automodule:: letsencrypt.plugins.disco +.. automodule:: certbot.plugins.disco :members: diff --git a/docs/api/plugins/manual.rst b/docs/api/plugins/manual.rst index 4661ab7df..eea443499 100644 --- a/docs/api/plugins/manual.rst +++ b/docs/api/plugins/manual.rst @@ -1,5 +1,5 @@ -:mod:`letsencrypt.plugins.manual` +:mod:`certbot.plugins.manual` --------------------------------- -.. automodule:: letsencrypt.plugins.manual +.. automodule:: certbot.plugins.manual :members: diff --git a/docs/api/plugins/standalone.rst b/docs/api/plugins/standalone.rst index f5b9d9c24..60aa48b4f 100644 --- a/docs/api/plugins/standalone.rst +++ b/docs/api/plugins/standalone.rst @@ -1,5 +1,5 @@ -:mod:`letsencrypt.plugins.standalone` +:mod:`certbot.plugins.standalone` ------------------------------------- -.. automodule:: letsencrypt.plugins.standalone +.. automodule:: certbot.plugins.standalone :members: diff --git a/docs/api/plugins/util.rst b/docs/api/plugins/util.rst index 6bc8995db..30ab3d49f 100644 --- a/docs/api/plugins/util.rst +++ b/docs/api/plugins/util.rst @@ -1,5 +1,5 @@ -:mod:`letsencrypt.plugins.util` +:mod:`certbot.plugins.util` ------------------------------- -.. automodule:: letsencrypt.plugins.util +.. automodule:: certbot.plugins.util :members: diff --git a/docs/api/plugins/webroot.rst b/docs/api/plugins/webroot.rst index 339d546a5..e1f4523f7 100644 --- a/docs/api/plugins/webroot.rst +++ b/docs/api/plugins/webroot.rst @@ -1,5 +1,5 @@ -:mod:`letsencrypt.plugins.webroot` +:mod:`certbot.plugins.webroot` ---------------------------------- -.. automodule:: letsencrypt.plugins.webroot +.. automodule:: certbot.plugins.webroot :members: diff --git a/docs/api/proof_of_possession.rst b/docs/api/proof_of_possession.rst index db8c6c563..2e7642a45 100644 --- a/docs/api/proof_of_possession.rst +++ b/docs/api/proof_of_possession.rst @@ -1,5 +1,5 @@ -:mod:`letsencrypt.proof_of_possession` +:mod:`certbot.proof_of_possession` -------------------------------------- -.. automodule:: letsencrypt.proof_of_possession +.. automodule:: certbot.proof_of_possession :members: diff --git a/docs/api/reporter.rst b/docs/api/reporter.rst index 03260f9cd..ad71dbb69 100644 --- a/docs/api/reporter.rst +++ b/docs/api/reporter.rst @@ -1,5 +1,5 @@ -:mod:`letsencrypt.reporter` +:mod:`certbot.reporter` --------------------------- -.. automodule:: letsencrypt.reporter +.. automodule:: certbot.reporter :members: diff --git a/docs/api/reverter.rst b/docs/api/reverter.rst index 4c220124f..3e0ac750b 100644 --- a/docs/api/reverter.rst +++ b/docs/api/reverter.rst @@ -1,5 +1,5 @@ -:mod:`letsencrypt.reverter` +:mod:`certbot.reverter` --------------------------- -.. automodule:: letsencrypt.reverter +.. automodule:: certbot.reverter :members: diff --git a/docs/api/storage.rst b/docs/api/storage.rst index 198d85b46..34e3a45c0 100644 --- a/docs/api/storage.rst +++ b/docs/api/storage.rst @@ -1,5 +1,5 @@ -:mod:`letsencrypt.storage` +:mod:`certbot.storage` -------------------------- -.. automodule:: letsencrypt.storage +.. automodule:: certbot.storage :members: diff --git a/docs/ciphers.rst b/docs/ciphers.rst index ef644b7a0..be6784276 100644 --- a/docs/ciphers.rst +++ b/docs/ciphers.rst @@ -17,15 +17,13 @@ Autoupdates Within certain limits, TLS server software can choose what kind of cryptography to use when a client connects. These choices can affect security, compatibility, and performance in complex ways. Most of -these options are independent of a particular certificate. The Let's -Encrypt client tries to provide defaults that we think are most useful -to our users. +these options are independent of a particular certificate. Certbot +tries to provide defaults that we think are most useful to our users. -As described below, the Let's Encrypt client will default to modifying +As described below, Certbot will default to modifying server software's cryptographic settings to keep these up-to-date with -what we think are appropriate defaults when new versions of the Let's -Encrypt client are installed (for example, by an operating system package -manager). +what we think are appropriate defaults when new versions of the Certbot +are installed (for example, by an operating system package manager). When this feature is implemented, this document will be updated to describe how to disable these automatic changes. @@ -54,7 +52,7 @@ improve, others' security. But important information that improves our understanding of the state of the art is published regularly. When enabling TLS support in a compatible web server (which is a separate -step from obtaining a certificate), Let's Encrypt has the ability to +step from obtaining a certificate), Certbot has the ability to update that web server's TLS configuration. Again, this is *different from the cryptographic particulars of the certificate itself*; the certificate as of the initial release will be RSA-signed using one of @@ -80,30 +78,29 @@ art. However, the Let's Encrypt certificate authority does *not* dictate end-users' security policy, and any site is welcome to change its preferences in accordance with its own policy or its administrators' preferences, and use different cryptographic mechanisms or parameters, -or a different priority order, than the defaults provided by the Let's -Encrypt client. +or a different priority order, than the defaults provided by Certbot. -If you don't use the Let's Encrypt client to configure your server -directly, because the client doesn't integrate with your server software -or because you chose not to use this integration, then the cryptographic -defaults haven't been modified, and the cryptography chosen by the server -will still be whatever the default for your software was. For example, -if you obtain a certificate using *standalone* mode and then manually -install it in an IMAP or LDAP server, your cryptographic settings will -not be modified by the client in any way. +If you don't use Certbot to configure your server directly, because the +client doesn't integrate with your server software or because you chose +not to use this integration, then the cryptographic defaults haven't been +modified, and the cryptography chosen by the server will still be whatever +the default for your software was. For example, if you obtain a +certificate using *standalone* mode and then manually install it in an IMAP +or LDAP server, your cryptographic settings will not be modified by the +client in any way. Sources of defaults ------------------- -Initially, the Let's Encrypt client will configure users' servers to -use the cryptographic defaults recommended by the Mozilla project. -These settings are well-reasoned recommendations that carefully -consider client software compatibility. They are described at +Initially, Certbot will configure users' servers to use the cryptographic +defaults recommended by the Mozilla project. These settings are well-reasoned +recommendations that carefully consider client software compatibility. They +are described at https://wiki.mozilla.org/Security/Server_Side_TLS -and the version implemented by the Let's Encrypt client will be the +and the version implemented by Certbot will be the version that was most current as of the release date of each client version. Mozilla offers three separate sets of cryptographic options, which trade off security and compatibility differently. These are @@ -113,12 +110,12 @@ to most-backwards compatible). The client will follow the Mozilla defaults for the *Intermediate* configuration by default, at least with regards to ciphersuites and TLS versions. Mozilla's web site describes which client software will be compatible with each configuration. You can also use -the Qualys SSL Labs site, which the Let's Encrypt software will suggest +the Qualys SSL Labs site, which Certbot will suggest when installing a certificate, to test your server and see whether it will be compatible with particular software versions. -It will be possible to ask the Let's Encrypt client to instead apply -(and track) Modern or Old configurations. +It will be possible to ask Certbot to instead apply (and track) Modern +or Old configurations. The Let's Encrypt project expects to follow the Mozilla recommendations in the future as those recommendations are updated. (For example, some @@ -127,15 +124,15 @@ which uses the ChaCha and Poly1305 algorithms, and which is already implemented by the Chrome browser. Mozilla has delayed recommending ``0xcc13`` over compatibility and standardization concerns, but is likely to recommend it in the future once these concerns have been addressed. At -that point, the Let's Encrypt client would likely follow the Mozilla -recommendations and favor the use of this ciphersuite as well.) +that point, Certbot would likely follow the Mozilla recommendations and favor +the use of this ciphersuite as well.) The Let's Encrypt project may deviate from the Mozilla recommendations in the future if good cause is shown and we believe our users' priorities would be well-served by doing so. In general, please address relevant proposals for changing priorities to the Mozilla security -team first, before asking the Let's Encrypt project to change the -client's priorities. The Mozilla security team is likely to have more +team first, before asking the Let's Encrypt project to change +Certbot's priorities. The Mozilla security team is likely to have more resources and expertise to bring to bear on evaluating reasons why its recommendations should be updated. @@ -144,8 +141,8 @@ small number of alternative configurations (apart from Modern, Intermediate, and Old) that there's reason to believe would be widely used by sysadmins; this would usually be a preferable course to modifying an existing configuration. For example, if many sysadmins want their -servers configured to track a different expert recommendation, Let's -Encrypt could add an option to do so. +servers configured to track a different expert recommendation, Certbot +could add an option to do so. Resources for recommendations @@ -156,9 +153,9 @@ recommendations with sources of expert guidance on ciphersuites and other cryptographic parameters. We're grateful to everyone who contributed suggestions. The recommendations we received are available at -https://github.com/letsencrypt/letsencrypt/wiki/Ciphersuite-guidance +https://github.com/certbot/certbot/wiki/Ciphersuite-guidance -Let's Encrypt client users are welcome to review these authorities to +Certbot users are welcome to review these authorities to better inform their own cryptographic parameter choices. We also welcome suggestions of other resources to add to this list. Please keep in mind that different recommendations may reflect different priorities @@ -172,23 +169,22 @@ This will probably look something like .. code-block:: shell - letsencrypt --cipher-recommendations mozilla-secure - letsencrypt --cipher-recommendations mozilla-intermediate - letsencrypt --cipher-recommendations mozilla-old + certbot --cipher-recommendations mozilla-secure + certbot --cipher-recommendations mozilla-intermediate + certbot --cipher-recommendations mozilla-old to track Mozilla's *Secure*, *Intermediate*, or *Old* recommendations, and .. code-block:: shell - letsencrypt --update-ciphers on + certbot --update-ciphers on -to enable updating ciphers with each new Let's Encrypt client release, -or +to enable updating ciphers with each new Certbot release, or .. code-block:: shell - letsencrypt --update-ciphers off + certbot --update-ciphers off to disable automatic configuration updates. These features have not yet been implemented and this syntax may change then they are implemented. @@ -200,7 +196,7 @@ TODO The status of this feature is tracked as part of issue #1123 in our bug tracker. -https://github.com/letsencrypt/letsencrypt/issues/1123 +https://github.com/certbot/certbot/issues/1123 Prior to implementation of #1123, the client does not actually modify ciphersuites (this is intended to be implemented as a "configuration diff --git a/docs/contributing.rst b/docs/contributing.rst index 69604780c..5a9afd5c5 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -15,14 +15,14 @@ Running a local copy of the client ---------------------------------- Running the client in developer mode from your local tree is a little -different than running ``letsencrypt-auto``. To get set up, do these things +different than running ``certbot-auto``. To get set up, do these things once: .. code-block:: shell - git clone https://github.com/letsencrypt/letsencrypt - cd letsencrypt - ./letsencrypt-auto-source/letsencrypt-auto --os-packages-only + git clone https://github.com/certbot/certbot + cd certbot + ./certbot-auto-source/certbot-auto --os-packages-only ./tools/venv.sh Then in each shell where you're working on the client, do: @@ -36,7 +36,7 @@ client by typing: .. code-block:: shell - letsencrypt + certbot Activating a shell in this way makes it easier to run unit tests with ``tox`` and integration tests, as described below. To reverse this, you @@ -57,8 +57,8 @@ your pull request must have thorough unit test coverage, pass our `integration`_ tests, and be compliant with the :ref:`coding style `. -.. _github issue tracker: https://github.com/letsencrypt/letsencrypt/issues -.. _Good Volunteer Task: https://github.com/letsencrypt/letsencrypt/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+Volunteer+Task%22 +.. _github issue tracker: https://github.com/certbot/certbot/issues +.. _Good Volunteer Task: https://github.com/certbot/certbot/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+Volunteer+Task%22 Testing ------- @@ -97,7 +97,7 @@ Generally it is sufficient to open a pull request and let Github and Travis run integration tests for you. However, if you prefer to run tests, you can use Vagrant, using the Vagrantfile -in Let's Encrypt's repository. To execute the tests on a Vagrant box, the only +in Certbot's repository. To execute the tests on a Vagrant box, the only command you are required to run is:: ./tests/boulder-integration.sh @@ -141,12 +141,12 @@ and ``nginx.wtf`` to 127.0.0.1. You may now run (in a separate terminal):: ./tests/boulder-integration.sh && echo OK || echo FAIL -If you would like to test `letsencrypt_nginx` plugin (highly +If you would like to test `certbot_nginx` plugin (highly encouraged) make sure to install prerequisites as listed in -``letsencrypt-nginx/tests/boulder-integration.sh`` and rerun +``certbot-nginx/tests/boulder-integration.sh`` and rerun the integration tests suite. -.. _Boulder: https://github.com/letsencrypt/boulder +.. _Boulder: https://github.com/certbot/boulder .. _Go: https://golang.org @@ -155,28 +155,28 @@ Code components and layout acme contains all protocol specific code -letsencrypt +certbot all client code Plugin-architecture ------------------- -Let's Encrypt has a plugin architecture to facilitate support for +Certbot has a plugin architecture to facilitate support for different webservers, other TLS servers, and operating systems. The interfaces available for plugins to implement are defined in `interfaces.py`_ and `plugins/common.py`_. The most common kind of plugin is a "Configurator", which is likely to -implement the `~letsencrypt.interfaces.IAuthenticator` and -`~letsencrypt.interfaces.IInstaller` interfaces (though some +implement the `~certbot.interfaces.IAuthenticator` and +`~certbot.interfaces.IInstaller` interfaces (though some Configurators may implement just one of those). -There are also `~letsencrypt.interfaces.IDisplay` plugins, +There are also `~certbot.interfaces.IDisplay` plugins, which implement bindings to alternative UI libraries. -.. _interfaces.py: https://github.com/letsencrypt/letsencrypt/blob/master/letsencrypt/interfaces.py -.. _plugins/common.py: https://github.com/letsencrypt/letsencrypt/blob/master/letsencrypt/plugins/common.py#L34 +.. _interfaces.py: https://github.com/certbot/certbot/blob/master/certbot/interfaces.py +.. _plugins/common.py: https://github.com/certbot/certbot/blob/master/certbot/plugins/common.py#L34 Authenticators @@ -232,7 +232,7 @@ Installer Development --------------------- There are a few existing classes that may be beneficial while -developing a new `~letsencrypt.interfaces.IInstaller`. +developing a new `~certbot.interfaces.IInstaller`. Installers aimed to reconfigure UNIX servers may use Augeas for configuration parsing and can inherit from `~.AugeasConfigurator` class to handle much of the interface. Installers that are unable to use @@ -244,7 +244,7 @@ Display ~~~~~~~ We currently offer a pythondialog and "text" mode for displays. Display -plugins implement the `~letsencrypt.interfaces.IDisplay` +plugins implement the `~certbot.interfaces.IDisplay` interface. .. _dev-plugin: @@ -252,10 +252,10 @@ interface. Writing your own plugin ======================= -Let's Encrypt client supports dynamic discovery of plugins through the +Certbot supports dynamic discovery of plugins through the `setuptools entry points`_. This way you can, for example, create a -custom implementation of `~letsencrypt.interfaces.IAuthenticator` or -the `~letsencrypt.interfaces.IInstaller` without having to merge it +custom implementation of `~certbot.interfaces.IAuthenticator` or +the `~certbot.interfaces.IInstaller` without having to merge it with the core upstream source code. An example is provided in ``examples/plugins/`` directory. @@ -323,7 +323,7 @@ Steps: See `Known Issues`_. If it's not a known issue, fix any errors. .. _Known Issues: - https://github.com/letsencrypt/letsencrypt/wiki/Known-issues + https://github.com/certbot/certbot/wiki/Known-issues Updating the documentation ========================== @@ -345,7 +345,7 @@ Other methods for running the client Vagrant ------- -If you are a Vagrant user, Let's Encrypt comes with a Vagrantfile that +If you are a Vagrant user, Certbot comes with a Vagrantfile that automates setting up a development environment in an Ubuntu 14.04 LTS VM. To set it up, simply run ``vagrant up``. The repository is synced to ``/vagrant``, so you can get started with: @@ -354,7 +354,7 @@ synced to ``/vagrant``, so you can get started with: vagrant ssh cd /vagrant - sudo ./venv/bin/letsencrypt + sudo ./venv/bin/certbot Support for other Linux distributions coming soon. @@ -373,19 +373,19 @@ Docker ------ OSX users will probably find it easiest to set up a Docker container for -development. Let's Encrypt comes with a Dockerfile (``Dockerfile-dev``) +development. Certbot comes with a Dockerfile (``Dockerfile-dev``) for doing so. To use Docker on OSX, install and setup docker-machine using the instructions at https://docs.docker.com/installation/mac/. To build the development Docker image:: - docker build -t letsencrypt -f Dockerfile-dev . + docker build -t certbot -f Dockerfile-dev . Now run tests inside the Docker image: .. code-block:: shell - docker run -it letsencrypt bash + docker run -it certbot bash cd src tox -e py27 @@ -399,7 +399,7 @@ OS-level dependencies can be installed like so: .. code-block:: shell - letsencrypt-auto-source/letsencrypt-auto --os-packages-only + certbot-auto-source/certbot-auto --os-packages-only In general... diff --git a/docs/index.rst b/docs/index.rst index 68289d760..b541e376e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,4 +1,4 @@ -Welcome to the Let's Encrypt client documentation! +Welcome to the Certbot documentation! ================================================== .. toctree:: diff --git a/docs/man/certbot.rst b/docs/man/certbot.rst new file mode 100644 index 000000000..7382d7811 --- /dev/null +++ b/docs/man/certbot.rst @@ -0,0 +1 @@ +.. program-output:: certbot --help all diff --git a/docs/man/letsencrypt.rst b/docs/man/letsencrypt.rst deleted file mode 100644 index 30f33c890..000000000 --- a/docs/man/letsencrypt.rst +++ /dev/null @@ -1 +0,0 @@ -.. program-output:: letsencrypt --help all diff --git a/docs/packaging.rst b/docs/packaging.rst index 5f09b65fa..bd366dbaa 100644 --- a/docs/packaging.rst +++ b/docs/packaging.rst @@ -3,4 +3,4 @@ Packaging Guide =============== Documentation can be found at -https://github.com/letsencrypt/letsencrypt/wiki/Packaging. +https://github.com/certbot/certbot/wiki/Packaging. diff --git a/docs/using.rst b/docs/using.rst index 66c5907ae..2b16e9a27 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -10,12 +10,12 @@ User Guide Installation ============ -.. _letsencrypt-auto: +.. _certbot-auto: -letsencrypt-auto +certbot-auto ---------------- -``letsencrypt-auto`` is a wrapper which installs some dependencies +``certbot-auto`` is a wrapper which installs some dependencies from your OS standard package repositories (e.g. using `apt-get` or `yum`), and for other dependencies it sets up a virtualized Python environment with packages downloaded from PyPI [#venv]_. It also @@ -25,33 +25,33 @@ To install and run the client, just type... .. code-block:: shell - ./letsencrypt-auto + ./certbot-auto -.. hint:: During the beta phase, Let's Encrypt enforces strict rate limits on +.. hint:: During the beta phase, Certbot enforces strict rate limits on the number of certificates issued for one domain. It is recommended to initially use the test server via `--test-cert` until you get the desired certificates. Throughout the documentation, whenever you see references to -``letsencrypt`` script/binary, you can substitute in -``letsencrypt-auto``. For example, to get basic help you would type: +``certbot`` script/binary, you can substitute in +``certbot-auto``. For example, to get basic help you would type: .. code-block:: shell - ./letsencrypt-auto --help + ./certbot-auto --help or for full help, type: .. code-block:: shell - ./letsencrypt-auto --help all + ./certbot-auto --help all -``letsencrypt-auto`` is the recommended method of running the Let's Encrypt +``certbot-auto`` is the recommended method of running the Certbot client beta releases on systems that don't have a packaged version. Debian, Arch Linux, Gentoo, FreeBSD, and OpenBSD now have native packages, so on those -systems you can just install ``letsencrypt`` (and perhaps -``letsencrypt-apache``). If you'd like to run the latest copy from Git, or +systems you can just install ``certbot`` (and perhaps +``certbot-apache``). If you'd like to run the latest copy from Git, or run your own locally modified copy of the client, follow the instructions in the :doc:`contributing`. Some `other methods of installation`_ are discussed below. @@ -60,11 +60,11 @@ below. Plugins ======= -The Let's Encrypt client supports a number of different "plugins" that can be +The Certbot client supports a number of different "plugins" that can be used to obtain and/or install certificates. 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 "letsencrypt run" command, which is the default. +can be used with the "certbot run" command, which is the default. =========== ==== ==== =============================================================== Plugin Auth Inst Notes @@ -79,7 +79,7 @@ standalone_ Y N Uses a "standalone" webserver to obtain a cert. Requires webserver is not supported or not desired. manual_ Y N Helps you obtain a cert by giving you instructions to perform domain validation yourself. -nginx_ Y Y Very experimental and not included in letsencrypt-auto_. +nginx_ Y Y Very experimental and not included in certbot-auto_. =========== ==== ==== =============================================================== There are also a number of third-party plugins for the client, provided by other developers: @@ -93,10 +93,10 @@ s3front_ Y Y Integration with Amazon CloudFront distribution of S3 buck gandi_ Y Y Integration with Gandi's hosting products and API =========== ==== ==== =============================================================== -.. _plesk: https://github.com/plesk/letsencrypt-plesk -.. _haproxy: https://code.greenhost.net/open/letsencrypt-haproxy -.. _s3front: https://github.com/dlapiduz/letsencrypt-s3front -.. _gandi: https://github.com/Gandi/letsencrypt-gandi +.. _plesk: https://github.com/plesk/certbot-plesk +.. _haproxy: https://code.greenhost.net/open/certbot-haproxy +.. _s3front: https://github.com/dlapiduz/certbot-s3front +.. _gandi: https://github.com/Gandi/certbot-gandi Future plugins for IMAP servers, SMTP servers, IRC servers, etc, are likely to be installers but not authenticators. @@ -130,21 +130,21 @@ specified ``--webroot-path``. So, for instance, :: - letsencrypt certonly --webroot -w /var/www/example/ -d www.example.com -d example.com -w /var/www/other -d other.example.net -d another.other.example.net + certbot certonly --webroot -w /var/www/example/ -d www.example.com -d example.com -w /var/www/other -d other.example.net -d another.other.example.net would obtain a single certificate for all of those names, using the ``/var/www/example`` webroot directory for the first two, and ``/var/www/other`` for the second two. The webroot plugin works by creating a temporary file for each of your requested -domains in ``${webroot-path}/.well-known/acme-challenge``. Then the Let's -Encrypt validation server makes HTTP requests to validate that the DNS for each -requested domain resolves to the server running letsencrypt. An example request +domains in ``${webroot-path}/.well-known/acme-challenge``. Then the Certbot +validation server makes HTTP requests to validate that the DNS for each +requested domain resolves to the server running certbot. An example request made to your web server would look like: :: - 66.133.109.36 - - [05/Jan/2016:20:11:24 -0500] "GET /.well-known/acme-challenge/HGr8U1IeTW4kY_Z6UIyaakzOkyQgPr_7ArlLgtZE8SX HTTP/1.1" 200 87 "-" "Mozilla/5.0 (compatible; Let's Encrypt validation server; +https://www.letsencrypt.org)" + 66.133.109.36 - - [05/Jan/2016:20:11:24 -0500] "GET /.well-known/acme-challenge/HGr8U1IeTW4kY_Z6UIyaakzOkyQgPr_7ArlLgtZE8SX HTTP/1.1" 200 87 "-" "Mozilla/5.0 (compatible; Certbot validation server; +https://www.certbot.com)" Note that to use the webroot plugin, your server must be configured to serve files from hidden directories. If ``/.well-known`` is treated specially by @@ -173,7 +173,7 @@ specified port using each requested domain name. Manual ------ -If you'd like to obtain a cert running ``letsencrypt`` on a machine +If you'd like to obtain a cert running ``certbot`` on a machine other than your target webserver or perform the steps for domain validation yourself, you can use the manual plugin. While hidden from the UI, you can use the plugin to obtain a cert by specifying @@ -187,14 +187,14 @@ Nginx In the future, if you're running Nginx you can use this plugin to automatically obtain and install your certificate. The Nginx plugin is still experimental, however, and is not installed with -letsencrypt-auto_. If installed, you can select this plugin on the +certbot-auto_. If installed, you can select this plugin on the command line by including ``--nginx``. Third-party plugins ------------------- These plugins are listed at -https://github.com/letsencrypt/letsencrypt/wiki/Plugins. If you're +https://github.com/certbot/certbot/wiki/Plugins. If you're interested, you can also :ref:`write your own plugin `. Renewal @@ -204,11 +204,11 @@ Renewal days). Make sure you renew the certificates at least once in 3 months. -The ``letsencrypt`` client now supports a ``renew`` action to check +The ``certbot`` client now supports a ``renew`` action to check all installed certificates for impending expiry and attempt to renew them. The simplest form is simply -``letsencrypt renew`` +``certbot renew`` This will attempt to renew any previously-obtained certificates that expire in less than 30 days. The same plugin and options that were used @@ -229,9 +229,9 @@ certificate regardless of its age. (This form is not appropriate to run daily because each certificate will be renewed every day, which will quickly run into the certificate authority rate limit.) -Note that options provided to ``letsencrypt renew`` will apply to +Note that options provided to ``certbot renew`` will apply to *every* certificate for which renewal is attempted; for example, -``letsencrypt renew --rsa-key-size 4096`` would try to replace every +``certbot renew --rsa-key-size 4096`` would try to replace every near-expiry certificate with an equivalent certificate using a 4096-bit RSA public key. If a certificate is successfully renewed using specified options, those options will be saved and used for future @@ -240,10 +240,10 @@ renewals of that certificate. An alternative form that provides for more fine-grained control over the renewal process (while renewing specified certificates one at a time), -is ``letsencrypt certonly`` with the complete set of subject domains of +is ``certbot certonly`` with the complete set of subject domains of a specific certificate specified via `-d` flags, like -``letsencrypt certonly -d example.com -d www.example.com`` +``certbot certonly -d example.com -d www.example.com`` (All of the domains covered by the certificate must be specified in this case in order to renew and replace the old certificate rather @@ -256,7 +256,7 @@ The ``certonly`` form attempts to renew one individual certificate. Please note that the CA will send notification emails to the address you provide if you do not renew certificates that are about to expire. -Let's Encrypt is working hard on improving the renewal process, and we +Certbot is working hard on improving the renewal process, and we apologize for any inconveniences you encounter in integrating these commands into your individual environment. @@ -272,14 +272,14 @@ you prefer to manage everything by hand, this section provides information on where to find necessary files. All generated keys and issued certificates can be found in -``/etc/letsencrypt/live/$domain``. Rather than copying, please point +``/etc/certbot/live/$domain``. Rather than copying, please point your (web) server configuration directly to those files (or create -symlinks). During the renewal_, ``/etc/letsencrypt/live`` is updated +symlinks). During the renewal_, ``/etc/certbot/live`` is updated with the latest necessary files. -.. note:: ``/etc/letsencrypt/archive`` and ``/etc/letsencrypt/keys`` +.. note:: ``/etc/certbot/archive`` and ``/etc/certbot/keys`` contain all previous keys and certificates, while - ``/etc/letsencrypt/live`` symlinks to the latest versions. + ``/etc/certbot/live`` symlinks to the latest versions. The following files are available: @@ -287,7 +287,7 @@ The following files are available: Private key for the certificate. .. warning:: This **must be kept secret at all times**! Never share - it with anyone, including Let's Encrypt developers. You cannot + it with anyone, including Certbot developers. You cannot put it into a safe, however - your server still needs to access this file in order for SSL/TLS to work. @@ -340,7 +340,7 @@ Configuration file ================== It is possible to specify configuration file with -``letsencrypt-auto --config cli.ini`` (or shorter ``-c cli.ini``). An +``certbot-auto --config cli.ini`` (or shorter ``-c cli.ini``). An example configuration file is shown below: .. include:: ../examples/cli.ini @@ -348,9 +348,9 @@ example configuration file is shown below: By default, the following locations are searched: -- ``/etc/letsencrypt/cli.ini`` -- ``$XDG_CONFIG_HOME/letsencrypt/cli.ini`` (or - ``~/.config/letsencrypt/cli.ini`` if ``$XDG_CONFIG_HOME`` is not +- ``/etc/certbot/cli.ini`` +- ``$XDG_CONFIG_HOME/certbot/cli.ini`` (or + ``~/.config/certbot/cli.ini`` if ``$XDG_CONFIG_HOME`` is not set). .. keep it up to date with constants.py @@ -359,21 +359,21 @@ By default, the following locations are searched: Getting help ============ -If you're having problems you can chat with us on `IRC (#letsencrypt @ -Freenode) `_ or -get support on our `forums `_. +If you're having problems you can chat with us on `IRC (#certbot @ +OFTC) `_ or +get support on our `forums `_. If you find a bug in the software, please do report it in our `issue tracker -`_. Remember to +`_. Remember to give us as much information as possible: - copy and paste exact command line used and the output (though mind that the latter might include some personally identifiable information, including your email and domains) -- copy and paste logs from ``/var/log/letsencrypt`` (though mind they +- copy and paste logs from ``/var/log/certbot`` (though mind they also might contain personally identifiable information) -- copy and paste ``letsencrypt --version`` output +- copy and paste ``certbot --version`` output - your operating system, including specific version - specify which installation_ method you've chosen @@ -390,10 +390,10 @@ plugins cannot reach it from inside the Docker container. You should definitely read the :ref:`where-certs` section, in order to know how to manage the certs -manually. https://github.com/letsencrypt/letsencrypt/wiki/Ciphersuite-guidance +manually. https://github.com/certbot/certbot/wiki/Ciphersuite-guidance provides some information about recommended ciphersuites. If none of these make much sense to you, you should definitely use the -letsencrypt-auto_ method, which enables you to use installer plugins +certbot-auto_ method, which enables you to use installer plugins that cover both of those hard topics. If you're still not convinced and have decided to use this method, @@ -402,14 +402,14 @@ to, `install Docker`_, then issue the following command: .. code-block:: shell - sudo docker run -it --rm -p 443:443 -p 80:80 --name letsencrypt \ - -v "/etc/letsencrypt:/etc/letsencrypt" \ - -v "/var/lib/letsencrypt:/var/lib/letsencrypt" \ - quay.io/letsencrypt/letsencrypt:latest auth + sudo docker run -it --rm -p 443:443 -p 80:80 --name certbot \ + -v "/etc/certbot:/etc/certbot" \ + -v "/var/lib/certbot:/var/lib/certbot" \ + quay.io/certbot/certbot:latest auth and follow the instructions (note that ``auth`` command is explicitly used - no installer plugins involved). Your new cert will be available -in ``/etc/letsencrypt/live`` on the host. +in ``/etc/certbot/live`` on the host. .. _Docker: https://docker.com .. _`install Docker`: https://docs.docker.com/userguide/ @@ -420,31 +420,31 @@ Operating System Packages **FreeBSD** - * Port: ``cd /usr/ports/security/py-letsencrypt && make install clean`` - * Package: ``pkg install py27-letsencrypt`` + * Port: ``cd /usr/ports/security/py-certbot make install clean`` + * Package: ``pkg install py27-certbot`` **OpenBSD** - * Port: ``cd /usr/ports/security/letsencrypt/client && make install clean`` - * Package: ``pkg_add letsencrypt`` + * Port: ``cd /usr/ports/security/certbot/client && make install clean`` + * Package: ``pkg_add certbot`` **Arch Linux** .. code-block:: shell - sudo pacman -S letsencrypt letsencrypt-apache + sudo pacman -S certbot certbot-apache **Debian** -If you run Debian Stretch or Debian Sid, you can install letsencrypt packages. +If you run Debian Stretch or Debian Sid, you can install certbot packages. .. code-block:: shell sudo apt-get update - sudo apt-get install letsencrypt python-letsencrypt-apache + sudo apt-get install certbot python-certbot-apache If you don't want to use the Apache plugin, you can omit the -``python-letsencrypt-apache`` package. +``python-certbot-apache`` package. Packages for Debian Jessie are coming in the next few weeks. @@ -452,17 +452,17 @@ Packages for Debian Jessie are coming in the next few weeks. .. code-block:: shell - sudo dnf install letsencrypt + sudo dnf install certbot **Gentoo** -The official Let's Encrypt client is available in Gentoo Portage. If you +The official Certbot client is available in Gentoo Portage. If you want to use the Apache plugin, it has to be installed separately: .. code-block:: shell - emerge -av app-crypt/letsencrypt - emerge -av app-crypt/letsencrypt-apache + emerge -av app-crypt/certbot + emerge -av app-crypt/certbot-apache Currently, only the Apache plugin is included in Portage. However, if you want the nginx plugin, you can use Layman to add the mrueg overlay which @@ -473,7 +473,7 @@ does include the nginx plugin package: emerge -av app-portage/layman layman -S layman -a mrueg - emerge -av app-crypt/letsencrypt-nginx + emerge -av app-crypt/certbot-nginx When using the Apache plugin, you will run into a "cannot find a cert or key directive" error if you're sporting the default Gentoo ``httpd.conf``. @@ -503,7 +503,7 @@ Note: this change is not required for the other plugins. **Other Operating Systems** OS packaging is an ongoing effort. If you'd like to package -Let's Encrypt client for your distribution of choice please have a +Certbot for your distribution of choice please have a look at the :doc:`packaging`. @@ -519,19 +519,19 @@ whole process is described in the :doc:`contributing`. environment, e.g. ``sudo python setup.py install``, ``sudo pip install``, ``sudo ./venv/bin/...``. These modes of operation might corrupt your operating system and are **not supported** by the - Let's Encrypt team! + Certbot team! Comparison of different methods ------------------------------- Unless you have a very specific requirements, we kindly ask you to use -the letsencrypt-auto_ method. It's the fastest, the most thoroughly +the certbot-auto_ method. It's the fastest, the most thoroughly tested and the most reliable way of getting our software and the free SSL certificates! Beyond the methods discussed here, other methods may be possible, such as -installing Let's Encrypt directly with pip from PyPI or downloading a ZIP +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.