mirror of
https://github.com/certbot/certbot.git
synced 2026-06-14 19:20:09 -04:00
fix whitespaces
Signed-off-by: Peter Conrad <pconrad@pconrad-ltm6.internal.salesforce.com>
This commit is contained in:
Noah Swartz
Peter Conrad
parent
ddad4ce4c6
commit
4e23f91b95
10 changed files with 314 additions and 314 deletions
|
|
@ -5,20 +5,20 @@
|
|||
Challenges
|
||||
==========
|
||||
|
||||
To receive a certificate from Let's Encrypt certificate authority (CA), you must pass a *challenge_* to
|
||||
prove you control each of the domain names that will be listed in the certificate. A challenge is one of
|
||||
To receive a certificate from Let's Encrypt certificate authority (CA), you must pass a *challenge_* to
|
||||
prove you control each of the domain names that will be listed in the certificate. A challenge is one of
|
||||
three tasks that only someone who controls the domain should be able to accomplish:
|
||||
|
||||
* Posting a specified file in a specified location on a web site (See the IETF draft of the `HTTP-01`_ challenge)
|
||||
* Offering a specified temporary certificate on a web site (See the IETF draft of the `TLS-SNI-01`_ challenge)
|
||||
* Offering a specified temporary certificate on a web site (See the IETF draft of the `TLS-SNI-01`_ challenge)
|
||||
* Posting a specified DNS record in the domain name system (See the IETF draft of the `DNS-01`_ challenge)
|
||||
|
||||
The DNS-01 challenge, in particular, requires configuration of a DNS server on
|
||||
port 53, though that's often not the same machine as your webserver.
|
||||
|
||||
It’s possible to complete each type of challenge *automatically* (Certbot directly makes the necessary
|
||||
changes itself, or runs another program that does so), or *manually* (Certbot tells you to make a
|
||||
certain change, and you edit a configuration file of some kind in order to accomplish it). Certbot's
|
||||
It’s possible to complete each type of challenge *automatically* (Certbot directly makes the necessary
|
||||
changes itself, or runs another program that does so), or *manually* (Certbot tells you to make a
|
||||
certain change, and you edit a configuration file of some kind in order to accomplish it). Certbot's
|
||||
design favors performing challenges automatically, and this is the normal case for most users of Certbot.
|
||||
|
||||
.. _TLS-SNI-01: https://tools.ietf.org/html/draft-ietf-acme-acme-03#section-7.3
|
||||
|
|
@ -32,7 +32,7 @@ General tips:
|
|||
|
||||
* Run Certbot on your web server, not on your laptop or another server. It’s usually the easiest way to get a certificate.
|
||||
* Use a tool like the DNSchecker at dnsstuff.com to check your DNS records to make sure
|
||||
there are no serious errors. A DNS error can prevent a certificate authority from
|
||||
there are no serious errors. A DNS error can prevent a certificate authority from
|
||||
issuing a certificate, even if it does not prevent your site from loading in a browser.
|
||||
* If you are using Apache or NGINX plugins, make sure the configuration of your Apache or NGINX server is correct.
|
||||
|
||||
|
|
@ -42,7 +42,7 @@ General tips:
|
|||
HTTP-01 Challenge
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
* Make sure the domain name exists and is already pointed to the public IP address of the server where
|
||||
* Make sure the domain name exists and is already pointed to the public IP address of the server where
|
||||
you’re requesting the certificate.
|
||||
* Make sure port 80 is open, publicly reachable from the Internet, and not blocked by a router or firewall.
|
||||
* When using the Webroot plugin or the manual plugin, make sure the the webroot directory exists and that you
|
||||
|
|
@ -50,12 +50,12 @@ HTTP-01 Challenge
|
|||
then a file placed in `/var/www/example.com/.well-known/acme-challenge/testfile` should appear on
|
||||
your web site at `http://example.com/.well-known/acme-challenge/testfile` (A redirection to HTTPS
|
||||
is OK here and should not stop the challenge from working.)
|
||||
* In some web server configurations, all pages are dynamically generated by some kind of framework,
|
||||
usually using a database backend. In this case, there might not be a particular directory
|
||||
from which the web server can serve filesdirectly. Using the Webroot plugin in this case
|
||||
* In some web server configurations, all pages are dynamically generated by some kind of framework,
|
||||
usually using a database backend. In this case, there might not be a particular directory
|
||||
from which the web server can serve filesdirectly. Using the Webroot plugin in this case
|
||||
requires making a change to your web server configuration first.
|
||||
* Make sure your web server serves files properly from the directory where the challenge
|
||||
file is placed (e. g. `/.well-known/acme-challenge`) to the expected location on the
|
||||
* Make sure your web server serves files properly from the directory where the challenge
|
||||
file is placed (e. g. `/.well-known/acme-challenge`) to the expected location on the
|
||||
website without adding a header or footer.
|
||||
* When using the Standalone plugin, make sure another program is not already listening to port 80 on the server.
|
||||
* When using the Webroot plugin, make sure there is a web server listening on port 80.
|
||||
|
|
@ -66,7 +66,7 @@ HTTP-01 Challenge
|
|||
TLS-SNI-01 Challenge
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* The TLS-SNI-01 challenge doesn’t work with content delivery networks (CDNs)
|
||||
* The TLS-SNI-01 challenge doesn’t work with content delivery networks (CDNs)
|
||||
like CloudFlare and Akamai because the domain name is pointed at the CDN, not directly at your server.
|
||||
* Make sure port 443 is open, publicly reachable from the Internet, and not blocked by a router or firewall.
|
||||
* When using the Apache plugin, make sure you are running Apache and no other web server on port 443.
|
||||
|
|
@ -83,7 +83,7 @@ TLS-SNI-01 Challenge
|
|||
DNS-01 Challenge
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
* When using the manual plugin, make sure your DNS records are correctly updated;
|
||||
* When using the manual plugin, make sure your DNS records are correctly updated;
|
||||
you must be able to make appropriate changes to your DNS zone in order to pass the challenge.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -68,13 +68,13 @@ Certbot accepts a global configuration file that applies its options to all invo
|
|||
of Certbot. Certificate specific configuration choices should be set in the ``.conf``
|
||||
files that can be found in ``/etc/letsencrypt/renewal``.
|
||||
|
||||
By default no cli.ini file is created, after creating one
|
||||
By default no cli.ini file is created, after creating one
|
||||
it is possible to specify the location of this configuration file with
|
||||
``certbot-auto --config cli.ini`` (or shorter ``-c cli.ini``). An
|
||||
example configuration file is shown below:
|
||||
|
||||
.. include:: ../examples/cli.ini
|
||||
:code: ini
|
||||
:code: ini
|
||||
|
||||
By default, the following locations are searched:
|
||||
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ running:
|
|||
|
||||
.. code-block:: shell
|
||||
|
||||
git clone https://github.com/certbot/certbot
|
||||
git clone https://github.com/certbot/certbot
|
||||
|
||||
If you're on macOS, we recommend you skip the rest of this section and instead
|
||||
run Certbot in Docker. You can find instructions for how to do this :ref:`here
|
||||
|
|
@ -31,17 +31,17 @@ a new plugin is introduced.
|
|||
|
||||
.. code-block:: shell
|
||||
|
||||
cd certbot
|
||||
./certbot-auto --os-packages-only
|
||||
./tools/venv.sh
|
||||
cd certbot
|
||||
./certbot-auto --os-packages-only
|
||||
./tools/venv.sh
|
||||
|
||||
Then in each shell where you're working on the client, do:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
source ./venv/bin/activate
|
||||
export SERVER=https://acme-staging.api.letsencrypt.org/directory
|
||||
source tests/integration/_common.sh
|
||||
source ./venv/bin/activate
|
||||
export SERVER=https://acme-staging.api.letsencrypt.org/directory
|
||||
source tests/integration/_common.sh
|
||||
|
||||
After that, your shell will be using the virtual environment, and you run the
|
||||
client by typing `certbot` or `certbot_test`. The latter is an alias that
|
||||
|
|
@ -58,12 +58,12 @@ More information can be found in the `virtualenv docs`_.
|
|||
Find issues to work on
|
||||
----------------------
|
||||
|
||||
You can find the open issues in the `github issue tracker`_. Comparatively
|
||||
easy ones are marked `Good Volunteer Task`_. If you're starting work on
|
||||
You can find the open issues in the `github issue tracker`_. Comparatively
|
||||
easy ones are marked `Good Volunteer Task`_. If you're starting work on
|
||||
something, post a comment to let others know and seek feedback on your plan
|
||||
where appropriate.
|
||||
|
||||
Once you've got a working branch, you can open a pull request. All changes in
|
||||
Once you've got a working branch, you can open a pull request. All changes in
|
||||
your pull request must have thorough unit test coverage, pass our
|
||||
tests, and be compliant with the :ref:`coding style <coding-style>`.
|
||||
|
||||
|
|
@ -113,7 +113,7 @@ and working. Fetch and start Boulder using:
|
|||
|
||||
.. code-block:: shell
|
||||
|
||||
./tests/boulder-fetch.sh
|
||||
./tests/boulder-fetch.sh
|
||||
|
||||
If you have problems with Docker, you may want to try `removing all containers and
|
||||
volumes`_ and making sure you have at least 1GB of memory.
|
||||
|
|
@ -123,14 +123,14 @@ Boulder:
|
|||
|
||||
.. code-block:: shell
|
||||
|
||||
export SERVER=http://localhost:4000/directory
|
||||
source tests/integration/_common.sh
|
||||
export SERVER=http://localhost:4000/directory
|
||||
source tests/integration/_common.sh
|
||||
|
||||
Run the integration tests using:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
./tests/boulder-integration.sh
|
||||
./tests/boulder-integration.sh
|
||||
|
||||
.. _removing all containers and volumes: https://www.digitalocean.com/community/tutorials/how-to-remove-docker-images-containers-and-volumes
|
||||
|
||||
|
|
@ -138,13 +138,13 @@ Code components and layout
|
|||
==========================
|
||||
|
||||
acme
|
||||
contains all protocol specific code
|
||||
contains all protocol specific code
|
||||
certbot
|
||||
main client code
|
||||
main client code
|
||||
certbot-apache and certbot-nginx
|
||||
client code to configure specific web servers
|
||||
client code to configure specific web servers
|
||||
certbot.egg-info
|
||||
configuration for packaging Certbot
|
||||
configuration for packaging Certbot
|
||||
|
||||
|
||||
Plugin-architecture
|
||||
|
|
@ -196,7 +196,7 @@ possibly tweak the security configuration to make it more correct and secure
|
|||
Installer plugins tell the main client about their abilities to do the latter
|
||||
via the :meth:`~.IInstaller.supported_enhancements` call. We currently
|
||||
have two Installers in the tree, the `~.ApacheConfigurator`. and the
|
||||
`~.NginxConfigurator`. External projects have made some progress toward
|
||||
`~.NginxConfigurator`. External projects have made some progress toward
|
||||
support for IIS, Icecast and Plesk.
|
||||
|
||||
Installers and Authenticators will oftentimes be the same class/object
|
||||
|
|
@ -241,10 +241,10 @@ virtualenv like this:
|
|||
|
||||
.. code-block:: shell
|
||||
|
||||
. venv/bin/activate
|
||||
. tests/integration/_common.sh
|
||||
pip install -e examples/plugins/
|
||||
certbot_test plugins
|
||||
. venv/bin/activate
|
||||
. tests/integration/_common.sh
|
||||
pip install -e examples/plugins/
|
||||
certbot_test plugins
|
||||
|
||||
Your plugin should show up in the output of the last command. If not,
|
||||
it was not installed properly.
|
||||
|
|
@ -280,15 +280,15 @@ Please:
|
|||
3. Follow the `Google Python Style Guide`_, with the exception that we use `Sphinx-style`_ documentation::
|
||||
|
||||
def foo(arg):
|
||||
"""Short description.
|
||||
"""Short description.
|
||||
|
||||
:param int arg: Some number.
|
||||
:param int arg: Some number.
|
||||
|
||||
:returns: Argument
|
||||
:rtype: int
|
||||
:returns: Argument
|
||||
:rtype: int
|
||||
|
||||
"""
|
||||
return arg
|
||||
"""
|
||||
return arg
|
||||
|
||||
4. Remember to use ``pylint``.
|
||||
|
||||
|
|
@ -305,14 +305,14 @@ Steps:
|
|||
|
||||
1. Write your code!
|
||||
2. Make sure your environment is set up properly and that you're in your
|
||||
virtualenv. You can do this by running ``./tools/venv.sh``.
|
||||
(this is a **very important** step)
|
||||
virtualenv. You can do this by running ``./tools/venv.sh``.
|
||||
(this is a **very important** step)
|
||||
3. Run ``tox -e lint`` to check for pylint errors. Fix any errors.
|
||||
4. Run ``tox --skip-missing-interpreters`` to run the entire test suite
|
||||
including coverage. The ``--skip-missing-interpreters`` argument ignores
|
||||
missing versions of Python needed for running the tests. Fix any errors.
|
||||
including coverage. The ``--skip-missing-interpreters`` argument ignores
|
||||
missing versions of Python needed for running the tests. Fix any errors.
|
||||
5. If your code touches communication with an ACME server/Boulder, you
|
||||
should run the integration tests, see `integration`_.
|
||||
should run the integration tests, see `integration`_.
|
||||
6. Submit the PR.
|
||||
7. Did your tests pass on Travis? If they didn't, fix any errors.
|
||||
|
||||
|
|
@ -322,7 +322,7 @@ Updating certbot-auto and letsencrypt-auto
|
|||
Updating the scripts
|
||||
--------------------
|
||||
Developers should *not* modify the ``certbot-auto`` and ``letsencrypt-auto`` files
|
||||
in the root directory of the repository. Rather, modify the
|
||||
in the root directory of the repository. Rather, modify the
|
||||
``letsencrypt-auto.template`` and associated platform-specific shell scripts in
|
||||
the ``letsencrypt-auto-source`` and
|
||||
``letsencrypt-auto-source/pieces/bootstrappers`` directory, respectively.
|
||||
|
|
@ -330,16 +330,16 @@ the ``letsencrypt-auto-source`` and
|
|||
Building letsencrypt-auto-source/letsencrypt-auto
|
||||
-------------------------------------------------
|
||||
Once changes to any of the aforementioned files have been made, the
|
||||
``letsencrypt-auto-source/letsencrypt-auto`` script should be updated. In lieu of
|
||||
``letsencrypt-auto-source/letsencrypt-auto`` script should be updated. In lieu of
|
||||
manually updating this script, run the build script, which lives at
|
||||
``letsencrypt-auto-source/build.py``:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
python letsencrypt-auto-source/build.py
|
||||
python letsencrypt-auto-source/build.py
|
||||
|
||||
Running ``build.py`` will update the ``letsencrypt-auto-source/letsencrypt-auto``
|
||||
script. Note that the ``certbot-auto`` and ``letsencrypt-auto`` scripts in the root
|
||||
script. Note that the ``certbot-auto`` and ``letsencrypt-auto`` scripts in the root
|
||||
directory of the repository will remain **unchanged** after this script is run.
|
||||
Your changes will be propagated to these files during the next release of
|
||||
Certbot.
|
||||
|
|
@ -349,12 +349,12 @@ Opening a PR
|
|||
When opening a PR, ensure that the following files are committed:
|
||||
|
||||
1. ``letsencrypt-auto-source/letsencrypt-auto.template`` and
|
||||
``letsencrypt-auto-source/pieces/bootstrappers/*``
|
||||
``letsencrypt-auto-source/pieces/bootstrappers/*``
|
||||
2. ``letsencrypt-auto-source/letsencrypt-auto`` (generated by ``build.py``)
|
||||
|
||||
It might also be a good idea to double check that **no** changes were
|
||||
inadvertently made to the ``certbot-auto`` or ``letsencrypt-auto`` scripts in the
|
||||
root of the repository. These scripts will be updated by the core developers
|
||||
root of the repository. These scripts will be updated by the core developers
|
||||
during the next release.
|
||||
|
||||
|
||||
|
|
@ -366,7 +366,7 @@ commands:
|
|||
|
||||
.. code-block:: shell
|
||||
|
||||
make -C docs clean html man
|
||||
make -C docs clean html man
|
||||
|
||||
This should generate documentation in the ``docs/_build/html``
|
||||
directory.
|
||||
|
|
@ -382,26 +382,26 @@ testing Certbot. This is especially useful for macOS users. To install Docker
|
|||
Compose, follow the instructions at https://docs.docker.com/compose/install/.
|
||||
|
||||
.. note:: Linux users can simply run ``pip install docker-compose`` to get
|
||||
Docker Compose after installing Docker Engine and activating your shell as
|
||||
described in the :ref:`Getting Started <getting_started>` section.
|
||||
Docker Compose after installing Docker Engine and activating your shell as
|
||||
described in the :ref:`Getting Started <getting_started>` section.
|
||||
|
||||
Now you can develop on your host machine, but run Certbot and test your changes
|
||||
in Docker. When using ``docker-compose`` make sure you are inside your clone of
|
||||
the Certbot repository. As an example, you can run the following command to
|
||||
check for linting errors::
|
||||
|
||||
docker-compose run --rm --service-ports development bash -c 'tox -e lint'
|
||||
docker-compose run --rm --service-ports development bash -c 'tox -e lint'
|
||||
|
||||
You can also leave a terminal open running a shell in the Docker container and
|
||||
modify Certbot code in another window. The Certbot repo on your host machine is
|
||||
mounted inside of the container so any changes you make immediately take
|
||||
effect. To do this, run::
|
||||
|
||||
docker-compose run --rm --service-ports development bash
|
||||
docker-compose run --rm --service-ports development bash
|
||||
|
||||
Now running the check for linting errors described above is as easy as::
|
||||
|
||||
tox -e lint
|
||||
tox -e lint
|
||||
|
||||
.. _prerequisites:
|
||||
|
||||
|
|
@ -412,7 +412,7 @@ OS-level dependencies can be installed like so:
|
|||
|
||||
.. code-block:: shell
|
||||
|
||||
letsencrypt-auto-source/letsencrypt-auto --os-packages-only
|
||||
letsencrypt-auto-source/letsencrypt-auto --os-packages-only
|
||||
|
||||
In general...
|
||||
|
||||
|
|
@ -420,7 +420,7 @@ In general...
|
|||
* `Python`_ 2.6/2.7 is required
|
||||
* `Augeas`_ is required for the Python bindings
|
||||
* ``virtualenv`` and ``pip`` are used for managing other python library
|
||||
dependencies
|
||||
dependencies
|
||||
|
||||
.. _Python: https://wiki.python.org/moin/BeginnersGuide/Download
|
||||
.. _Augeas: http://augeas.net/
|
||||
|
|
@ -438,10 +438,10 @@ For squeeze you will need to:
|
|||
FreeBSD
|
||||
-------
|
||||
|
||||
Packages can be installed on FreeBSD using ``pkg``,
|
||||
or any other port-management tool (``portupgrade``, ``portmanager``, etc.)
|
||||
from the pre-built package or can be built and installed from ports.
|
||||
Either way will ensure proper installation of all the dependencies required
|
||||
Packages can be installed on FreeBSD using ``pkg``,
|
||||
or any other port-management tool (``portupgrade``, ``portmanager``, etc.)
|
||||
from the pre-built package or can be built and installed from ports.
|
||||
Either way will ensure proper installation of all the dependencies required
|
||||
for the package.
|
||||
|
||||
FreeBSD by default uses ``tcsh``. In order to activate virtualenv (see
|
||||
|
|
|
|||
162
docs/how.rst
162
docs/how.rst
|
|
@ -40,22 +40,22 @@ when no command is specified. The ``run`` subcommand can also be used to specify
|
|||
a combination_ of distinct authenticator and installer plugins.
|
||||
|
||||
=========== ==== ==== =============================================================== =============================
|
||||
Plugin Auth Inst Notes Challenge types (and port)
|
||||
Plugin Auth Inst Notes Challenge types (and port)
|
||||
=========== ==== ==== =============================================================== =============================
|
||||
apache_ Y Y | Automates obtaining and installing a certificate with Apache :ref:`TLS-SNI-01 <tls_sni_01_challege>` (443)
|
||||
| 2.4 on Debian-based distributions with ``libaugeas0`` 1.0+.
|
||||
webroot_ Y N | Obtains a certificate by writing to the webroot directory of :ref:`HTTP-01 <http_01_challenge>` (80)
|
||||
| an already running webserver.
|
||||
nginx_ Y Y | Automates obtaining and installing a certificate with Nginx. :ref:`TLS-SNI-01 <tls_sni_01_challege>` (443)
|
||||
| Shipped with Certbot 0.9.0.
|
||||
standalone_ Y N | Uses a "standalone" webserver to obtain a certificate. :ref:`HTTP-01 <http_01_challenge>` (80) or
|
||||
| Requires port 80 or 443 to be available. This is useful on :ref:`TLS-SNI-01 <tls_sni_01_challege>` (443)
|
||||
| systems with no webserver, or when direct integration with
|
||||
| the local webserver is not supported or not desired.
|
||||
manual_ Y N | Helps you obtain a certificate by giving you instructions to :ref:`HTTP-01 <http_01_challenge>` (80),
|
||||
| perform domain validation yourself. Additionally allows you :ref:`DNS-01 <dns_01_challenge>` (53) or
|
||||
| to specify scripts to automate the validation task in a :ref:`TLS-SNI-01 <tls_sni_01_challege>` (443)
|
||||
| customized way.
|
||||
apache_ Y Y | Automates obtaining and installing a certificate with Apache :ref:`TLS-SNI-01 <tls_sni_01_challege>` (443)
|
||||
| 2.4 on Debian-based distributions with ``libaugeas0`` 1.0+.
|
||||
webroot_ Y N | Obtains a certificate by writing to the webroot directory of :ref:`HTTP-01 <http_01_challenge>` (80)
|
||||
| an already running webserver.
|
||||
nginx_ Y Y | Automates obtaining and installing a certificate with Nginx. :ref:`TLS-SNI-01 <tls_sni_01_challege>` (443)
|
||||
| Shipped with Certbot 0.9.0.
|
||||
standalone_ Y N | Uses a "standalone" webserver to obtain a certificate. :ref:`HTTP-01 <http_01_challenge>` (80) or
|
||||
| Requires port 80 or 443 to be available. This is useful on :ref:`TLS-SNI-01 <tls_sni_01_challege>` (443)
|
||||
| systems with no webserver, or when direct integration with
|
||||
| the local webserver is not supported or not desired.
|
||||
manual_ Y N | Helps you obtain a certificate by giving you instructions to :ref:`HTTP-01 <http_01_challenge>` (80),
|
||||
| perform domain validation yourself. Additionally allows you :ref:`DNS-01 <dns_01_challenge>` (53) or
|
||||
| to specify scripts to automate the validation task in a :ref:`TLS-SNI-01 <tls_sni_01_challege>` (443)
|
||||
| customized way.
|
||||
=========== ==== ==== =============================================================== =============================
|
||||
|
||||
A few
|
||||
|
|
@ -72,19 +72,19 @@ other developers. Many are beta/experimental, but some are already in
|
|||
widespread use:
|
||||
|
||||
=========== ==== ==== ===============================================================
|
||||
Plugin Auth Inst Notes
|
||||
Plugin Auth Inst Notes
|
||||
=========== ==== ==== ===============================================================
|
||||
plesk_ Y Y Integration with the Plesk web hosting tool
|
||||
haproxy_ Y Y Integration with the HAProxy load balancer
|
||||
s3front_ Y Y Integration with Amazon CloudFront distribution of S3 buckets
|
||||
gandi_ Y Y Integration with Gandi's hosting products and API
|
||||
varnish_ Y N Obtain certificates via a Varnish server
|
||||
external_ Y N A plugin for convenient scripting (See also ticket 2782_)
|
||||
icecast_ N Y Deploy certificates to Icecast 2 streaming media servers
|
||||
pritunl_ N Y Install certificates in pritunl distributed OpenVPN servers
|
||||
proxmox_ N Y Install certificates in Proxmox Virtualization servers
|
||||
postfix_ N Y STARTTLS Everywhere is becoming a Certbot Postfix/Exim plugin
|
||||
heroku_ Y Y Integration with Heroku SSL
|
||||
plesk_ Y Y Integration with the Plesk web hosting tool
|
||||
haproxy_ Y Y Integration with the HAProxy load balancer
|
||||
s3front_ Y Y Integration with Amazon CloudFront distribution of S3 buckets
|
||||
gandi_ Y Y Integration with Gandi's hosting products and API
|
||||
varnish_ Y N Obtain certificates via a Varnish server
|
||||
external_ Y N A plugin for convenient scripting (See also ticket 2782_)
|
||||
icecast_ N Y Deploy certificates to Icecast 2 streaming media servers
|
||||
pritunl_ N Y Install certificates in pritunl distributed OpenVPN servers
|
||||
proxmox_ N Y Install certificates in Proxmox Virtualization servers
|
||||
postfix_ N Y STARTTLS Everywhere is becoming a Certbot Postfix/Exim plugin
|
||||
heroku_ Y Y Integration with Heroku SSL
|
||||
=========== ==== ==== ===============================================================
|
||||
|
||||
.. _plesk: https://github.com/plesk/letsencrypt-plesk
|
||||
|
|
@ -162,87 +162,87 @@ Example usage for HTTP-01::
|
|||
|
||||
.. code-block:: none
|
||||
|
||||
#!/bin/bash
|
||||
echo $CERTBOT_VALIDATION > /var/www/htdocs/.well-known/acme-challenge/$CERTBOT_TOKEN
|
||||
#!/bin/bash
|
||||
echo $CERTBOT_VALIDATION > /var/www/htdocs/.well-known/acme-challenge/$CERTBOT_TOKEN
|
||||
|
||||
/path/to/http/cleanup.sh
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
#!/bin/bash
|
||||
rm -f /var/www/htdocs/.well-known/acme-challenge/$CERTBOT_TOKEN
|
||||
#!/bin/bash
|
||||
rm -f /var/www/htdocs/.well-known/acme-challenge/$CERTBOT_TOKEN
|
||||
|
||||
Example usage for DNS-01 (Cloudflare API v4) (for example purposes only, do not use as-is)::
|
||||
|
||||
certbot certonly --manual --preferred-challenges=dns --manual-auth-hook /path/to/dns/authenticator.sh --manual-cleanup-hook /path/to/dns/cleanup.sh -d secure.example.com
|
||||
certbot certonly --manual --preferred-challenges=dns --manual-auth-hook /path/to/dns/authenticator.sh --manual-cleanup-hook /path/to/dns/cleanup.sh -d secure.example.com
|
||||
|
||||
/path/to/dns/authenticator.sh
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
#!/bin/bash
|
||||
#!/bin/bash
|
||||
|
||||
# Get your API key from https://www.cloudflare.com/a/account/my-account
|
||||
API_KEY="your-api-key"
|
||||
EMAIL="your.email@example.com"
|
||||
# Get your API key from https://www.cloudflare.com/a/account/my-account
|
||||
API_KEY="your-api-key"
|
||||
EMAIL="your.email@example.com"
|
||||
|
||||
# Strip only the top domain to get the zone id
|
||||
DOMAIN=$(expr match "$CERTBOT_DOMAIN" '.*\.\(.*\..*\)')
|
||||
# Strip only the top domain to get the zone id
|
||||
DOMAIN=$(expr match "$CERTBOT_DOMAIN" '.*\.\(.*\..*\)')
|
||||
|
||||
# Get the Cloudflare zone id
|
||||
ZONE_EXTRA_PARAMS="status=active&page=1&per_page=20&order=status&direction=desc&match=all"
|
||||
ZONE_ID=$(curl -s -X GET "https://api.cloudflare.com/client/v4/zones?name=$DOMAIN&$ZONE_EXTRA_PARAMS" \
|
||||
-H "X-Auth-Email: $EMAIL" \
|
||||
-H "X-Auth-Key: $API_KEY" \
|
||||
-H "Content-Type: application/json" | python -c "import sys,json;print(json.load(sys.stdin)['result'][0]['id'])")
|
||||
# Get the Cloudflare zone id
|
||||
ZONE_EXTRA_PARAMS="status=active&page=1&per_page=20&order=status&direction=desc&match=all"
|
||||
ZONE_ID=$(curl -s -X GET "https://api.cloudflare.com/client/v4/zones?name=$DOMAIN&$ZONE_EXTRA_PARAMS" \
|
||||
-H "X-Auth-Email: $EMAIL" \
|
||||
-H "X-Auth-Key: $API_KEY" \
|
||||
-H "Content-Type: application/json" | python -c "import sys,json;print(json.load(sys.stdin)['result'][0]['id'])")
|
||||
|
||||
# Create TXT record
|
||||
CREATE_DOMAIN="_acme-challenge.$CERTBOT_DOMAIN"
|
||||
RECORD_ID=$(curl -s -X POST "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records" \
|
||||
-H "X-Auth-Email: $EMAIL" \
|
||||
-H "X-Auth-Key: $API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
--data '{"type":"TXT","name":"'"$CREATE_DOMAIN"'","content":"'"$CERTBOT_VALIDATION"'","ttl":120}' \
|
||||
| python -c "import sys,json;print(json.load(sys.stdin)['result']['id'])")
|
||||
# Save info for cleanup
|
||||
if [ ! -d /tmp/CERTBOT_$CERTBOT_DOMAIN ];then
|
||||
mkdir -m 0700 /tmp/CERTBOT_$CERTBOT_DOMAIN
|
||||
fi
|
||||
echo $ZONE_ID > /tmp/CERTBOT_$CERTBOT_DOMAIN/ZONE_ID
|
||||
echo $RECORD_ID > /tmp/CERTBOT_$CERTBOT_DOMAIN/RECORD_ID
|
||||
# Create TXT record
|
||||
CREATE_DOMAIN="_acme-challenge.$CERTBOT_DOMAIN"
|
||||
RECORD_ID=$(curl -s -X POST "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records" \
|
||||
-H "X-Auth-Email: $EMAIL" \
|
||||
-H "X-Auth-Key: $API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
--data '{"type":"TXT","name":"'"$CREATE_DOMAIN"'","content":"'"$CERTBOT_VALIDATION"'","ttl":120}' \
|
||||
| python -c "import sys,json;print(json.load(sys.stdin)['result']['id'])")
|
||||
# Save info for cleanup
|
||||
if [ ! -d /tmp/CERTBOT_$CERTBOT_DOMAIN ];then
|
||||
mkdir -m 0700 /tmp/CERTBOT_$CERTBOT_DOMAIN
|
||||
fi
|
||||
echo $ZONE_ID > /tmp/CERTBOT_$CERTBOT_DOMAIN/ZONE_ID
|
||||
echo $RECORD_ID > /tmp/CERTBOT_$CERTBOT_DOMAIN/RECORD_ID
|
||||
|
||||
# Sleep to make sure the change has time to propagate over to DNS
|
||||
sleep 25
|
||||
# Sleep to make sure the change has time to propagate over to DNS
|
||||
sleep 25
|
||||
|
||||
/path/to/dns/cleanup.sh
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
#!/bin/bash
|
||||
#!/bin/bash
|
||||
|
||||
# Get your API key from https://www.cloudflare.com/a/account/my-account
|
||||
API_KEY="your-api-key"
|
||||
EMAIL="your.email@example.com"
|
||||
# Get your API key from https://www.cloudflare.com/a/account/my-account
|
||||
API_KEY="your-api-key"
|
||||
EMAIL="your.email@example.com"
|
||||
|
||||
if [ -f /tmp/CERTBOT_$CERTBOT_DOMAIN/ZONE_ID ]; then
|
||||
ZONE_ID=$(cat /tmp/CERTBOT_$CERTBOT_DOMAIN/ZONE_ID)
|
||||
rm -f /tmp/CERTBOT_$CERTBOT_DOMAIN/ZONE_ID
|
||||
fi
|
||||
if [ -f /tmp/CERTBOT_$CERTBOT_DOMAIN/ZONE_ID ]; then
|
||||
ZONE_ID=$(cat /tmp/CERTBOT_$CERTBOT_DOMAIN/ZONE_ID)
|
||||
rm -f /tmp/CERTBOT_$CERTBOT_DOMAIN/ZONE_ID
|
||||
fi
|
||||
|
||||
if [ -f /tmp/CERTBOT_$CERTBOT_DOMAIN/RECORD_ID ]; then
|
||||
RECORD_ID=$(cat /tmp/CERTBOT_$CERTBOT_DOMAIN/RECORD_ID)
|
||||
rm -f /tmp/CERTBOT_$CERTBOT_DOMAIN/RECORD_ID
|
||||
fi
|
||||
if [ -f /tmp/CERTBOT_$CERTBOT_DOMAIN/RECORD_ID ]; then
|
||||
RECORD_ID=$(cat /tmp/CERTBOT_$CERTBOT_DOMAIN/RECORD_ID)
|
||||
rm -f /tmp/CERTBOT_$CERTBOT_DOMAIN/RECORD_ID
|
||||
fi
|
||||
|
||||
# Remove the challenge TXT record from the zone
|
||||
if [ -n "${ZONE_ID}" ]; then
|
||||
if [ -n "${RECORD_ID}" ]; then
|
||||
curl -s -X DELETE "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records/$RECORD_ID" \
|
||||
-H "X-Auth-Email: $EMAIL" \
|
||||
-H "X-Auth-Key: $API_KEY" \
|
||||
-H "Content-Type: application/json"
|
||||
fi
|
||||
fi
|
||||
# Remove the challenge TXT record from the zone
|
||||
if [ -n "${ZONE_ID}" ]; then
|
||||
if [ -n "${RECORD_ID}" ]; then
|
||||
curl -s -X DELETE "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records/$RECORD_ID" \
|
||||
-H "X-Auth-Email: $EMAIL" \
|
||||
-H "X-Auth-Key: $API_KEY" \
|
||||
-H "Content-Type: application/json"
|
||||
fi
|
||||
fi
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -2,25 +2,25 @@ Welcome to the Certbot documentation!
|
|||
==================================================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:maxdepth: 2
|
||||
|
||||
start
|
||||
start
|
||||
intro
|
||||
what
|
||||
how
|
||||
challenges
|
||||
install
|
||||
using
|
||||
contributing
|
||||
packaging
|
||||
resources
|
||||
install
|
||||
using
|
||||
contributing
|
||||
packaging
|
||||
resources
|
||||
reference
|
||||
configure
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:maxdepth: 1
|
||||
|
||||
api
|
||||
api
|
||||
|
||||
|
||||
Indices and tables
|
||||
|
|
|
|||
124
docs/install.rst
124
docs/install.rst
|
|
@ -3,7 +3,7 @@ Manual Installation
|
|||
=====================
|
||||
|
||||
.. contents:: Table of Contents
|
||||
:local:
|
||||
:local:
|
||||
|
||||
.. Note:: The easiest way to install Certbot is by visiting `certbot.eff.org`_,
|
||||
where you can find the correct installation instructions for many web server
|
||||
|
|
@ -19,7 +19,7 @@ Certbot currently requires Python 2.6, 2.7, or 3.3+. By default, it 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
|
||||
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 <https://github.com/diafygi/letsencrypt-nosudo>`_ or
|
||||
|
|
@ -52,14 +52,14 @@ download and run it as follows::
|
|||
|
||||
user@webserver:~$ wget https://dl.eff.org/certbot-auto
|
||||
user@webserver:~$ chmod a+x ./certbot-auto
|
||||
user@webserver:~$ ./certbot-auto --help
|
||||
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::
|
||||
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
|
||||
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
|
||||
|
||||
The ``certbot-auto`` command updates to the latest client release automatically.
|
||||
Since ``certbot-auto`` is a wrapper to ``certbot``, it accepts exactly
|
||||
|
|
@ -68,7 +68,7 @@ the same command line flags and arguments. For more information, see
|
|||
|
||||
For full command line help, you can type::
|
||||
|
||||
./certbot-auto --help all
|
||||
./certbot-auto --help all
|
||||
|
||||
Running with Docker
|
||||
-------------------
|
||||
|
|
@ -97,10 +97,10 @@ to, `install Docker`_, then issue the following command:
|
|||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo docker run -it --rm -p 443:443 -p 80:80 --name certbot \
|
||||
-v "/etc/letsencrypt:/etc/letsencrypt" \
|
||||
-v "/var/lib/letsencrypt:/var/lib/letsencrypt" \
|
||||
certbot/certbot certonly
|
||||
sudo docker run -it --rm -p 443:443 -p 80:80 --name certbot \
|
||||
-v "/etc/letsencrypt:/etc/letsencrypt" \
|
||||
-v "/var/lib/letsencrypt:/var/lib/letsencrypt" \
|
||||
certbot/certbot certonly
|
||||
|
||||
Running Certbot with the ``certonly`` command will obtain a certificate and place it in the directory
|
||||
``/etc/letsencrypt/live`` on your system. Because Certonly cannot install the certificate from
|
||||
|
|
@ -120,7 +120,7 @@ Operating System Packages
|
|||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo pacman -S certbot
|
||||
sudo pacman -S certbot
|
||||
|
||||
**Debian**
|
||||
|
||||
|
|
@ -128,8 +128,8 @@ If you run Debian Stretch or Debian Sid, you can install certbot packages.
|
|||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo apt-get update
|
||||
sudo apt-get install certbot python-certbot-apache
|
||||
sudo apt-get update
|
||||
sudo apt-get install certbot python-certbot-apache
|
||||
|
||||
If you don't want to use the Apache plugin, you can omit the
|
||||
``python-certbot-apache`` package.
|
||||
|
|
@ -140,18 +140,18 @@ repo, if you have not already done so. Then run:
|
|||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo apt-get install certbot python-certbot-apache -t jessie-backports
|
||||
sudo apt-get install certbot python-certbot-apache -t jessie-backports
|
||||
|
||||
**Fedora**
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo dnf install certbot python2-certbot-apache
|
||||
sudo dnf install certbot python2-certbot-apache
|
||||
|
||||
**FreeBSD**
|
||||
|
||||
* Port: ``cd /usr/ports/security/py-certbot && make install clean``
|
||||
* Package: ``pkg install py27-certbot``
|
||||
* Port: ``cd /usr/ports/security/py-certbot && make install clean``
|
||||
* Package: ``pkg install py27-certbot``
|
||||
|
||||
**Gentoo**
|
||||
|
||||
|
|
@ -160,8 +160,8 @@ want to use the Apache plugin, it has to be installed separately:
|
|||
|
||||
.. code-block:: shell
|
||||
|
||||
emerge -av app-crypt/certbot
|
||||
emerge -av app-crypt/certbot-apache
|
||||
emerge -av app-crypt/certbot
|
||||
emerge -av app-crypt/certbot-apache
|
||||
|
||||
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``.
|
||||
|
|
@ -172,17 +172,17 @@ Change
|
|||
|
||||
.. code-block:: shell
|
||||
|
||||
<IfDefine SSL>
|
||||
LoadModule ssl_module modules/mod_ssl.so
|
||||
</IfDefine>
|
||||
<IfDefine SSL>
|
||||
LoadModule ssl_module modules/mod_ssl.so
|
||||
</IfDefine>
|
||||
|
||||
to
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
#<IfDefine SSL>
|
||||
LoadModule ssl_module modules/mod_ssl.so
|
||||
#</IfDefine>
|
||||
#<IfDefine SSL>
|
||||
LoadModule ssl_module modules/mod_ssl.so
|
||||
#</IfDefine>
|
||||
|
||||
For the time being, this is the only way for the Apache plugin to recognise
|
||||
the appropriate directives when installing the certificate.
|
||||
|
|
@ -190,13 +190,13 @@ Note: this change is not required for the other plugins.
|
|||
|
||||
**NetBSD**
|
||||
|
||||
* Build from source: ``cd /usr/pkgsrc/security/py-certbot && make install clean``
|
||||
* Install pre-compiled package: ``pkg_add py27-certbot``
|
||||
* Build from source: ``cd /usr/pkgsrc/security/py-certbot && make install clean``
|
||||
* Install pre-compiled package: ``pkg_add py27-certbot``
|
||||
|
||||
**OpenBSD**
|
||||
|
||||
* Port: ``cd /usr/ports/security/letsencrypt/client && make install clean``
|
||||
* Package: ``pkg_add letsencrypt``
|
||||
* Port: ``cd /usr/ports/security/letsencrypt/client && make install clean``
|
||||
* Package: ``pkg_add letsencrypt``
|
||||
|
||||
**Other Operating Systems**
|
||||
|
||||
|
|
@ -211,11 +211,11 @@ Installation from source is only supported for developers and the
|
|||
whole process is described in the :doc:`contributing`.
|
||||
|
||||
.. warning:: Please do **not** use ``python setup.py install``, ``python pip
|
||||
install .``, or ``easy_install .``. Please do **not** attempt the
|
||||
installation commands as superuser/root and/or without virtual 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 Certbot team!
|
||||
install .``, or ``easy_install .``. Please do **not** attempt the
|
||||
installation commands as superuser/root and/or without virtual 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 Certbot team!
|
||||
|
||||
Problems with Python virtual environment
|
||||
----------------------------------------
|
||||
|
|
@ -224,15 +224,15 @@ On a low memory system such as VPS with less than 512MB of RAM, the required dep
|
|||
This can be identified if the pip outputs contains something like ``internal compiler error: Killed (program cc1)``.
|
||||
You can workaround this restriction by creating a temporary swapfile::
|
||||
|
||||
user@webserver:~$ sudo fallocate -l 1G /tmp/swapfile
|
||||
user@webserver:~$ sudo chmod 600 /tmp/swapfile
|
||||
user@webserver:~$ sudo mkswap /tmp/swapfile
|
||||
user@webserver:~$ sudo swapon /tmp/swapfile
|
||||
user@webserver:~$ sudo fallocate -l 1G /tmp/swapfile
|
||||
user@webserver:~$ sudo chmod 600 /tmp/swapfile
|
||||
user@webserver:~$ sudo mkswap /tmp/swapfile
|
||||
user@webserver:~$ sudo swapon /tmp/swapfile
|
||||
|
||||
Disable and remove the swapfile once the virtual environment is constructed::
|
||||
|
||||
user@webserver:~$ sudo swapoff /tmp/swapfile
|
||||
user@webserver:~$ sudo rm /tmp/swapfile
|
||||
user@webserver:~$ sudo swapoff /tmp/swapfile
|
||||
user@webserver:~$ sudo rm /tmp/swapfile
|
||||
|
||||
|
||||
.. _getting_certs:
|
||||
|
|
@ -259,9 +259,9 @@ This automates both obtaining *and* installing certificates on an Apache
|
|||
webserver. To specify this plugin on the command line, simply include
|
||||
``--apache``.
|
||||
|
||||
* Apache plugin: (TLS-SNI-01) Tries to edit your Apache configuration files to temporarily serve
|
||||
a Certbot-generated certificate for a specified name. Use the Apache plugin when you're running
|
||||
Certbot on a web server with Apache listening on port 443.
|
||||
* Apache plugin: (TLS-SNI-01) Tries to edit your Apache configuration files to temporarily serve
|
||||
a Certbot-generated certificate for a specified name. Use the Apache plugin when you're running
|
||||
Certbot on a web server with Apache listening on port 443.
|
||||
|
||||
.. _manual:
|
||||
|
||||
|
|
@ -290,7 +290,7 @@ record with specific contents under the domain name consisting of the hostname
|
|||
for which you want a certificate issued, prepended by ``_acme-challenge``.
|
||||
|
||||
For example, for the domain ``example.com``, a zone file entry would look like::
|
||||
_acme-challenge.example.com. 300 IN TXT "gfj9Xq...Rg85nM"
|
||||
_acme-challenge.example.com. 300 IN TXT "gfj9Xq...Rg85nM"
|
||||
|
||||
When using the ``tls-sni`` challenge, ``certbot`` will prepare a self-signed
|
||||
SSL certificate for you with the challenge validation appropriately
|
||||
|
|
@ -303,9 +303,9 @@ perform the authentication procedure and/or clean up after it by using
|
|||
the ``--manual-auth-hook`` and ``--manual-cleanup-hook`` flags. This is
|
||||
described in more depth in the hooks_ section.
|
||||
|
||||
* Manual plugin: (DNS-01 or HTTP-01) Either tells you what changes to make to your configuration or updates
|
||||
your DNS records using an external script (for DNS-01) or your webroot (for HTTP-01). Use the Manual
|
||||
plugin if you have the technical knowledge to make configuration changes yourself when asked to do so.
|
||||
* Manual plugin: (DNS-01 or HTTP-01) Either tells you what changes to make to your configuration or updates
|
||||
your DNS records using an external script (for DNS-01) or your webroot (for HTTP-01). Use the Manual
|
||||
plugin if you have the technical knowledge to make configuration changes yourself when asked to do so.
|
||||
|
||||
.. _nginx:
|
||||
|
||||
|
|
@ -318,11 +318,11 @@ configurations before using it (though you can also revert changes to
|
|||
configurations with ``certbot --nginx rollback``). You can use it by providing
|
||||
the ``--nginx`` flag on the commandline::
|
||||
|
||||
certbot –nginx
|
||||
certbot –nginx
|
||||
|
||||
* NGINX plugin: (TLS-SNI-01) Tries to edit your NGINX configuration files to temporarily serve a
|
||||
Certbot-generated certificate for a specified name. Use the NGINX plugin when you're running
|
||||
Certbot on a web server with NGINX listening on port 443.
|
||||
Certbot-generated certificate for a specified name. Use the NGINX plugin when you're running
|
||||
Certbot on a web server with NGINX listening on port 443.
|
||||
|
||||
.. _standalone:
|
||||
|
||||
|
|
@ -341,18 +341,18 @@ order to perform domain validation, so you may need to stop your
|
|||
existing webserver. To control which port the plugin uses, include
|
||||
one of the options shown below on the command line.
|
||||
|
||||
* ``--preferred-challenges http`` to use port 80
|
||||
* ``--preferred-challenges tls-sni`` to use port 443
|
||||
* ``--preferred-challenges http`` to use port 80
|
||||
* ``--preferred-challenges tls-sni`` to use port 443
|
||||
|
||||
It must still be possible for your machine to accept inbound connections from
|
||||
the Internet on the specified port using each requested domain name.
|
||||
|
||||
.. note:: The ``--standalone-supported-challenges`` option has been
|
||||
deprecated since ``certbot`` version 0.9.0.
|
||||
deprecated since ``certbot`` version 0.9.0.
|
||||
|
||||
* Standalone plugin: (TLS-SNI-01 or HTTP-01) Tries to run a temporary web server listening on either HTTP on
|
||||
port 80 (for HTTP-01) or HTTPS on port 443 (for TLS-SNI-01). Use the Standalone plugin if no existing program
|
||||
is listening to these ports. Choose TLS-SNI-01 or HTTP-01 using the `--preferred-challenges` option.
|
||||
* Standalone plugin: (TLS-SNI-01 or HTTP-01) Tries to run a temporary web server listening on either HTTP on
|
||||
port 80 (for HTTP-01) or HTTPS on port 443 (for TLS-SNI-01). Use the Standalone plugin if no existing program
|
||||
is listening to these ports. Choose TLS-SNI-01 or HTTP-01 using the `--preferred-challenges` option.
|
||||
|
||||
|
||||
.. _webroot:
|
||||
|
|
@ -375,7 +375,7 @@ potentially be a separate directory for each domain. When requesting a
|
|||
certificate for multiple domains, each domain will use the most recently
|
||||
specified ``--webroot-path``. So, for instance::
|
||||
|
||||
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
|
||||
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.
|
||||
|
|
@ -395,8 +395,8 @@ to ensure that files inside ``/.well-known/acme-challenge`` are served by
|
|||
the webserver.
|
||||
|
||||
* Webroot plugin: (HTTP-01) Tries to place a file where it can be served over HTTP on port 80 by a
|
||||
web server running on your system. Use the Webroot plugin when you're running Certbot on
|
||||
a web server with any server application listening on port 80 serving files from a folder on disk in response.
|
||||
web server running on your system. Use the Webroot plugin when you're running Certbot on
|
||||
a web server with any server application listening on port 80 serving files from a folder on disk in response.
|
||||
|
||||
|
||||
.. _combination:
|
||||
|
|
@ -417,7 +417,7 @@ and your origin server, which cannot use the tls-sni-01_ challenge due to the
|
|||
intermediate proxy.
|
||||
|
||||
::
|
||||
certbot run -a webroot -i apache -w /var/www/html -d example.com
|
||||
certbot run -a webroot -i apache -w /var/www/html -d example.com
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -3,11 +3,11 @@ Overview
|
|||
=====================
|
||||
|
||||
.. note::
|
||||
To get started quickly, use the `interactive installation guide <https://certbot.eff.org>`_.
|
||||
To get started quickly, use the `interactive installation guide <https://certbot.eff.org>`_.
|
||||
|
||||
.. include:: ../README.rst
|
||||
:start-after: tag:intro-begin
|
||||
:end-before: tag:intro-end
|
||||
:start-after: tag:intro-begin
|
||||
:end-before: tag:intro-end
|
||||
|
||||
.. include:: what.rst
|
||||
|
||||
|
|
|
|||
|
|
@ -32,10 +32,10 @@ tracker <https://github.com/certbot/certbot/issues>`_. 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)
|
||||
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
|
||||
also might contain personally identifiable information)
|
||||
also might contain personally identifiable information)
|
||||
- copy and paste ``certbot --version`` output
|
||||
- your operating system, including specific version
|
||||
- specify which installation method you've chosen
|
||||
|
|
|
|||
162
docs/using.rst
162
docs/using.rst
|
|
@ -2,7 +2,7 @@ Working with Certificates
|
|||
=========================
|
||||
|
||||
.. contents:: Table of Contents
|
||||
:local:
|
||||
:local:
|
||||
|
||||
Before You Begin
|
||||
================
|
||||
|
|
@ -27,18 +27,18 @@ the ``certificates`` subcommand:
|
|||
|
||||
This returns information in the following format::
|
||||
|
||||
Found the following certs:
|
||||
Certificate Name: example.com
|
||||
Domains: example.com, www.example.com
|
||||
Expiry Date: 2017-02-19 19:53:00+00:00 (VALID: 30 days)
|
||||
Certificate Path: /etc/letsencrypt/live/example.com/fullchain.pem
|
||||
Private Key Path: /etc/letsencrypt/live/example.com/privkey.pem
|
||||
Found the following certs:
|
||||
Certificate Name: example.com
|
||||
Domains: example.com, www.example.com
|
||||
Expiry Date: 2017-02-19 19:53:00+00:00 (VALID: 30 days)
|
||||
Certificate Path: /etc/letsencrypt/live/example.com/fullchain.pem
|
||||
Private Key Path: /etc/letsencrypt/live/example.com/privkey.pem
|
||||
|
||||
``Certificate Name`` shows the name of the certificate. Pass this name
|
||||
using the ``--cert-name`` flag to specify a particular certificate for the ``run``,
|
||||
``certonly``, ``certificates``, ``renew``, and ``delete`` commands. Example::
|
||||
|
||||
certbot certonly --cert-name example.com
|
||||
certbot certonly --cert-name example.com
|
||||
|
||||
.. _updating_certs:
|
||||
|
||||
|
|
@ -82,13 +82,13 @@ Example:
|
|||
|
||||
.. code-block:: none
|
||||
|
||||
certbot --expand -d existing.com,example.com,newdomain.com
|
||||
certbot --expand -d existing.com,example.com,newdomain.com
|
||||
|
||||
If you prefer, you can specify the domains individually like this:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
certbot --expand -d existing.com -d example.com -d newdomain.com
|
||||
certbot --expand -d existing.com -d example.com -d newdomain.com
|
||||
|
||||
Consider using ``--cert-name`` instead of ``--expand``, as it gives more control
|
||||
over which certificate is modified and it lets you remove domains as well as adding them.
|
||||
|
|
@ -116,12 +116,12 @@ by specifying new domains using the ``-d`` or ``--domains`` flag. If certificate
|
|||
previously contained ``example.com`` and ``www.example.com``, it can be modified to only
|
||||
contain ``example.com`` by specifying only ``example.com`` with the ``-d`` or ``--domains`` flag. Example::
|
||||
|
||||
certbot certonly --cert-name example.com -d example.com
|
||||
certbot certonly --cert-name example.com -d example.com
|
||||
|
||||
The same format can be used to expand the set of domains a certificate contains, or to
|
||||
replace that set entirely::
|
||||
|
||||
certbot certonly --cert-name example.com -d example.org,www.example.org
|
||||
certbot certonly --cert-name example.com -d example.org,www.example.org
|
||||
|
||||
|
||||
Revoking certificates
|
||||
|
|
@ -131,13 +131,13 @@ If your account key has been compromised or you otherwise need to revoke a certi
|
|||
use the ``revoke`` command to do so. Note that the ``revoke`` command takes the certificate path
|
||||
(ending in ``cert.pem``), not a certificate name or domain. Example::
|
||||
|
||||
certbot revoke --cert-path /etc/letsencrypt/live/CERTNAME/cert.pem
|
||||
certbot revoke --cert-path /etc/letsencrypt/live/CERTNAME/cert.pem
|
||||
|
||||
You can also specify the reason for revoking your certificate by using the ``reason`` flag.
|
||||
Reasons include ``unspecified`` which is the default, as well as ``keycompromise``,
|
||||
``affiliationchanged``, ``superseded``, and ``cessationofoperation``::
|
||||
|
||||
certbot revoke --cert-path /etc/letsencrypt/live/CERTNAME/cert.pem --reason keycompromise
|
||||
certbot revoke --cert-path /etc/letsencrypt/live/CERTNAME/cert.pem --reason keycompromise
|
||||
|
||||
Additionally, if a certificate
|
||||
is a test certificate obtained via the ``--staging`` or ``--test-cert`` flag, that flag must be passed to the
|
||||
|
|
@ -145,7 +145,7 @@ is a test certificate obtained via the ``--staging`` or ``--test-cert`` flag, th
|
|||
Once a certificate is revoked (or for other certificate management tasks), all of a certificate's
|
||||
relevant files can be removed from the system with the ``delete`` subcommand::
|
||||
|
||||
certbot delete --cert-name example.com
|
||||
certbot delete --cert-name example.com
|
||||
|
||||
.. note:: If you don't use ``delete`` to remove the certificate completely, it will be renewed automatically at the next renewal event.
|
||||
|
||||
|
|
@ -157,8 +157,8 @@ Renewing certificates
|
|||
---------------------
|
||||
|
||||
.. note:: Let's Encrypt CA issues short-lived certificates (90
|
||||
days). Make sure you renew the certificates at least once in 3
|
||||
months.
|
||||
days). Make sure you renew the certificates at least once in 3
|
||||
months.
|
||||
|
||||
As of version 0.10.0, Certbot supports a ``renew`` action to check
|
||||
all installed certificates for impending expiry and attempt to renew
|
||||
|
|
@ -182,7 +182,7 @@ the standalone_ plugin, you might need to stop the webserver
|
|||
before renewing so standalone can bind to the necessary ports, and
|
||||
then restart it after the plugin is finished. Example::
|
||||
|
||||
certbot renew --pre-hook "service nginx stop" --post-hook "service nginx start"
|
||||
certbot renew --pre-hook "service nginx stop" --post-hook "service nginx start"
|
||||
|
||||
If a hook exits with a non-zero exit code, the error will be printed
|
||||
to ``stderr`` but renewal will be attempted anyway. A failing hook
|
||||
|
|
@ -207,34 +207,34 @@ apply appropriate file permissions.
|
|||
|
||||
.. code-block:: none
|
||||
|
||||
#!/bin/sh
|
||||
#!/bin/sh
|
||||
|
||||
set -e
|
||||
set -e
|
||||
|
||||
for domain in $RENEWED_DOMAINS; do
|
||||
case $domain in
|
||||
example.com)
|
||||
daemon_cert_root=/etc/some-daemon/certs
|
||||
for domain in $RENEWED_DOMAINS; do
|
||||
case $domain in
|
||||
example.com)
|
||||
daemon_cert_root=/etc/some-daemon/certs
|
||||
|
||||
# Make sure the certificate and private key files are
|
||||
# never world readable, even just for an instant while
|
||||
# we're copying them into daemon_cert_root.
|
||||
umask 077
|
||||
# Make sure the certificate and private key files are
|
||||
# never world readable, even just for an instant while
|
||||
# we're copying them into daemon_cert_root.
|
||||
umask 077
|
||||
|
||||
cp "$RENEWED_LINEAGE/fullchain.pem" "$daemon_cert_root/$domain.cert"
|
||||
cp "$RENEWED_LINEAGE/privkey.pem" "$daemon_cert_root/$domain.key"
|
||||
cp "$RENEWED_LINEAGE/fullchain.pem" "$daemon_cert_root/$domain.cert"
|
||||
cp "$RENEWED_LINEAGE/privkey.pem" "$daemon_cert_root/$domain.key"
|
||||
|
||||
# Apply the proper file ownership and permissions for
|
||||
# the daemon to read its certificate and key.
|
||||
chown some-daemon "$daemon_cert_root/$domain.cert" \
|
||||
"$daemon_cert_root/$domain.key"
|
||||
chmod 400 "$daemon_cert_root/$domain.cert" \
|
||||
"$daemon_cert_root/$domain.key"
|
||||
# Apply the proper file ownership and permissions for
|
||||
# the daemon to read its certificate and key.
|
||||
chown some-daemon "$daemon_cert_root/$domain.cert" \
|
||||
"$daemon_cert_root/$domain.key"
|
||||
chmod 400 "$daemon_cert_root/$domain.cert" \
|
||||
"$daemon_cert_root/$domain.key"
|
||||
|
||||
service some-daemon restart >/dev/null
|
||||
;;
|
||||
esac
|
||||
done
|
||||
service some-daemon restart >/dev/null
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
You can also specify hooks by placing files in subdirectories of Certbot's
|
||||
configuration directory. Assuming your configuration directory is
|
||||
|
|
@ -307,10 +307,10 @@ apologize for any inconvenience you encounter in integrating these
|
|||
commands into your individual environment.
|
||||
|
||||
.. note:: ``certbot renew`` exit status will only be 1 if a renewal attempt failed.
|
||||
This means ``certbot renew`` exit status will be 0 if no cert needs to be updated.
|
||||
If you write a custom script and expect to run a command only after a cert was actually renewed
|
||||
you will need to use the ``--post-hook`` since the exit status will be 0 both on successful renewal
|
||||
and when renewal is not necessary.
|
||||
This means ``certbot renew`` exit status will be 0 if no cert needs to be updated.
|
||||
If you write a custom script and expect to run a command only after a cert was actually renewed
|
||||
you will need to use the ``--post-hook`` since the exit status will be 0 both on successful renewal
|
||||
and when renewal is not necessary.
|
||||
|
||||
|
||||
|
||||
|
|
@ -327,57 +327,57 @@ symlinks). During the renewal_, ``/etc/letsencrypt/live`` is updated
|
|||
with the latest necessary files.
|
||||
|
||||
.. note:: ``/etc/letsencrypt/archive`` and ``/etc/letsencrypt/keys``
|
||||
contain all previous keys and certificates, while
|
||||
``/etc/letsencrypt/live`` symlinks to the latest versions.
|
||||
contain all previous keys and certificates, while
|
||||
``/etc/letsencrypt/live`` symlinks to the latest versions.
|
||||
|
||||
The following files are available:
|
||||
|
||||
``privkey.pem``
|
||||
Private key for the certificate.
|
||||
Private key for the certificate.
|
||||
|
||||
.. warning:: This **must be kept secret at all times**! Never share
|
||||
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.
|
||||
.. warning:: This **must be kept secret at all times**! Never share
|
||||
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.
|
||||
|
||||
This is what Apache needs for `SSLCertificateKeyFile
|
||||
<https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcertificatekeyfile>`_,
|
||||
and Nginx for `ssl_certificate_key
|
||||
<http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate_key>`_.
|
||||
This is what Apache needs for `SSLCertificateKeyFile
|
||||
<https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcertificatekeyfile>`_,
|
||||
and Nginx for `ssl_certificate_key
|
||||
<http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate_key>`_.
|
||||
|
||||
``fullchain.pem``
|
||||
All certificates, **including** server certificate (aka leaf certificate or
|
||||
end-entity certificate). The server certificate is the first one in this file,
|
||||
followed by any intermediates.
|
||||
All certificates, **including** server certificate (aka leaf certificate or
|
||||
end-entity certificate). The server certificate is the first one in this file,
|
||||
followed by any intermediates.
|
||||
|
||||
This is what Apache >= 2.4.8 needs for `SSLCertificateFile
|
||||
<https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcertificatefile>`_,
|
||||
and what Nginx needs for `ssl_certificate
|
||||
<http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate>`_.
|
||||
This is what Apache >= 2.4.8 needs for `SSLCertificateFile
|
||||
<https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcertificatefile>`_,
|
||||
and what Nginx needs for `ssl_certificate
|
||||
<http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate>`_.
|
||||
|
||||
``cert.pem`` and ``chain.pem`` (less common)
|
||||
``cert.pem`` contains the server certificate by itself, and
|
||||
``chain.pem`` contains the additional intermediate certificate or
|
||||
certificates that web browsers will need in order to validate the
|
||||
server certificate. If you provide one of these files to your web
|
||||
server, you **must** provide both of them, or some browsers will show
|
||||
"This Connection is Untrusted" errors for your site, `some of the time
|
||||
<https://whatsmychaincert.com/>`_.
|
||||
``cert.pem`` contains the server certificate by itself, and
|
||||
``chain.pem`` contains the additional intermediate certificate or
|
||||
certificates that web browsers will need in order to validate the
|
||||
server certificate. If you provide one of these files to your web
|
||||
server, you **must** provide both of them, or some browsers will show
|
||||
"This Connection is Untrusted" errors for your site, `some of the time
|
||||
<https://whatsmychaincert.com/>`_.
|
||||
|
||||
Apache < 2.4.8 needs these for `SSLCertificateFile
|
||||
<https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcertificatefile>`_.
|
||||
and `SSLCertificateChainFile
|
||||
<https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcertificatechainfile>`_,
|
||||
respectively.
|
||||
Apache < 2.4.8 needs these for `SSLCertificateFile
|
||||
<https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcertificatefile>`_.
|
||||
and `SSLCertificateChainFile
|
||||
<https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcertificatechainfile>`_,
|
||||
respectively.
|
||||
|
||||
If you're using OCSP stapling with Nginx >= 1.3.7, ``chain.pem`` should be
|
||||
provided as the `ssl_trusted_certificate
|
||||
<http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_trusted_certificate>`_
|
||||
to validate OCSP responses.
|
||||
If you're using OCSP stapling with Nginx >= 1.3.7, ``chain.pem`` should be
|
||||
provided as the `ssl_trusted_certificate
|
||||
<http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_trusted_certificate>`_
|
||||
to validate OCSP responses.
|
||||
|
||||
.. note:: All files are PEM-encoded.
|
||||
If you need other format, such as DER or PFX, then you
|
||||
could convert using ``openssl``. You can automate that with
|
||||
``--deploy-hook`` if you're using automatic renewal_.
|
||||
If you need other format, such as DER or PFX, then you
|
||||
could convert using ``openssl``. You can automate that with
|
||||
``--deploy-hook`` if you're using automatic renewal_.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -2,14 +2,14 @@
|
|||
What is a Certificate?
|
||||
======================
|
||||
|
||||
A public key or digital *certificate* (formerly called an SSL certificate) uses a public key
|
||||
and a private key to enable secure communication between a client program (web browser, email client,
|
||||
A public key or digital *certificate* (formerly called an SSL certificate) uses a public key
|
||||
and a private key to enable secure communication between a client program (web browser, email client,
|
||||
etc.) and a server over an encrypted SSL (secure socket layer) or TLS (transport layer security) connection.
|
||||
The certificate is used both to encrypt the initial stage of communication (secure key exchange)
|
||||
The certificate is used both to encrypt the initial stage of communication (secure key exchange)
|
||||
and to identify the server. The certificate
|
||||
includes information about the key, information about the server identity, and the digital signature
|
||||
of the certificate issuer. If the issuer is trusted by the software that initiates the communication,
|
||||
and the signature is valid, then the key can be used to communicate securely with the server identified by
|
||||
and the signature is valid, then the key can be used to communicate securely with the server identified by
|
||||
the certificate. Using a certificate is a good way to prevent "man-in-the-middle" attacks, in which
|
||||
someone in between you and the server you think you are talking to is able to insert their own (harmful)
|
||||
content.
|
||||
|
|
@ -23,9 +23,9 @@ Certificates and Lineages
|
|||
Certbot introduces the concept of a *lineage,* which is a collection of all the versions of a certificate
|
||||
plus Certbot configuration information maintained for that certificate from
|
||||
renewal to renewal. Whenever you renew a certificate, Certbot keeps the same configuration unless
|
||||
you explicitly change it, for example by adding or removing domains. If you add domains, you can
|
||||
you explicitly change it, for example by adding or removing domains. If you add domains, you can
|
||||
either add them to an existing lineage or create
|
||||
a new one.
|
||||
a new one.
|
||||
|
||||
See also:
|
||||
:ref:`updating_certs`
|
||||
|
|
|
|||
Loading…
Reference in a new issue