starred/certbot-certbot
1
0
Fork 0
mirror of https://github.com/certbot/certbot.git synced 2026-07-28 08:45:22 +02:00
Code Issues Packages Projects Releases Wiki Activity

fix merge

Browse Source
This commit is contained in:
Noah Swartz
2016-07-14 11:36:04 -07:00
parent c4c1fa3a26 4fa182ab71
commit 19f6b79bcc
142 changed files with 5546 additions and 2061 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/le_util.rst
-5
View File
@@ -1,5 +0,0 @@
:mod:`certbot.le_util`
--------------------------
.. automodule:: certbot.le_util
:members:
docs/api/util.rst
+5
View File
@@ -0,0 +1,5 @@
:mod:`certbot.util`
--------------------------
.. automodule:: certbot.util
:members:
docs/ciphers.rst
+39 -43
View File
@@ -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 Certbot developers 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,26 +169,25 @@ 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.
been implemented and this syntax may change when they are implemented.
TODO
@@ -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
docs/cli-help.txt
+367
View File
@@ -0,0 +1,367 @@
usage:
certbot [SUBCOMMAND] [options] [-d domain] [-d domain] ...
Certbot can obtain and install HTTPS/TLS/SSL certificates. By default,
it will attempt to use a webserver both for obtaining and installing the
cert. Major SUBCOMMANDS are:
(default) run Obtain & install a cert in your current webserver
certonly Obtain cert, but do not install it (aka "auth")
install Install a previously obtained cert in a server
renew Renew previously obtained certs that are near expiry
revoke Revoke a previously obtained certificate
register Perform tasks related to registering with the CA
rollback Rollback server configuration changes made during install
config_changes Show changes made to server config during installation
plugins Display information about installed plugins
optional arguments:
-h, --help show this help message and exit
-c CONFIG_FILE, --config CONFIG_FILE
config file path (default: None)
-v, --verbose This flag can be used multiple times to incrementally
increase the verbosity of output, e.g. -vvv. (default:
-3)
-t, --text Use the text output instead of the curses UI.
(default: False)
-n, --non-interactive, --noninteractive
Run without ever asking for user input. This may
require additional command line flags; the client will
try to explain which ones are required if it finds one
missing (default: False)
--dialog Run using dialog (default: False)
--dry-run Perform a test run of the client, obtaining test
(invalid) certs but not saving them to disk. This can
currently only be used with the 'certonly' and 'renew'
subcommands. Note: Although --dry-run tries to avoid
making any persistent changes on a system, it is not
completely side-effect free: if used with webserver
authenticator plugins like apache and nginx, it makes
and then reverts temporary config changes in order to
obtain test certs, and reloads webservers to deploy
and then roll back those changes. It also calls --pre-
hook and --post-hook commands if they are defined
because they may be necessary to accurately simulate
renewal. --renew-hook commands are not called.
(default: False)
--register-unsafely-without-email
Specifying this flag enables registering an account
with no email address. This is strongly discouraged,
because in the event of key loss or account compromise
you will irrevocably lose access to your account. You
will also be unable to receive notice about impending
expiration or revocation of your certificates. Updates
to the Subscriber Agreement will still affect you, and
will be effective 14 days after posting an update to
the web site. (default: False)
--update-registration
With the register verb, indicates that details
associated with an existing registration, such as the
e-mail address, should be updated, rather than
registering a new account. (default: False)
-m EMAIL, --email EMAIL
Email used for registration and recovery contact.
(default: None)
-d DOMAIN, --domains DOMAIN, --domain DOMAIN
Domain names to apply. For multiple domains you can
use multiple -d flags or enter a comma separated list
of domains as a parameter. (default: [])
--user-agent USER_AGENT
Set a custom user agent string for the client. User
agent strings allow the CA to collect high level
statistics about success rates by OS and plugin. If
you wish to hide your server OS version from the Let's
Encrypt server, set this to "". (default: None)
automation:
Arguments for automating execution & other tweaks
--keep-until-expiring, --keep, --reinstall
If the requested cert matches an existing cert, always
keep the existing one until it is due for renewal (for
the 'run' subcommand this means reinstall the existing
cert) (default: False)
--expand If an existing cert covers some subset of the
requested names, always expand and replace it with the
additional names. (default: False)
--version show program's version number and exit
--force-renewal, --renew-by-default
If a certificate already exists for the requested
domains, renew it now, regardless of whether it is
near expiry. (Often --keep-until-expiring is more
appropriate). Also implies --expand. (default: False)
--allow-subset-of-names
When performing domain validation, do not consider it
a failure if authorizations can not be obtained for a
strict subset of the requested domains. This may be
useful for allowing renewals for multiple domains to
succeed even if some domains no longer point at this
system. This option cannot be used with --csr.
(default: False)
--agree-tos Agree to the ACME Subscriber Agreement (default:
False)
--account ACCOUNT_ID Account ID to use (default: None)
--duplicate Allow making a certificate lineage that duplicates an
existing one (both can be renewed in parallel)
(default: False)
--os-packages-only (letsencrypt-auto only) install OS package
dependencies and then stop (default: False)
--no-self-upgrade (letsencrypt-auto only) prevent the letsencrypt-auto
script from upgrading itself to newer released
versions (default: False)
-q, --quiet Silence all output except errors. Useful for
automation via cron. Implies --non-interactive.
(default: False)
testing:
The following flags are meant for testing purposes only! Do NOT change
them, unless you really know what you're doing!
--debug Show tracebacks in case of errors, and allow
letsencrypt-auto execution on experimental platforms
(default: False)
--no-verify-ssl Disable SSL certificate verification. (default: False)
--tls-sni-01-port TLS_SNI_01_PORT
Port number to perform tls-sni-01 challenge. Boulder
in testing mode defaults to 5001. (default: 443)
--http-01-port HTTP01_PORT
Port used in the SimpleHttp challenge. (default: 80)
--break-my-certs Be willing to replace or renew valid certs with
invalid (testing/staging) certs (default: False)
--test-cert, --staging
Use the staging server to obtain test (invalid) certs;
equivalent to --server https://acme-
staging.api.letsencrypt.org/directory (default: False)
security:
Security parameters & server settings
--rsa-key-size N Size of the RSA key. (default: 2048)
--must-staple Adds the OCSP Must Staple extension to the
certificate. Autoconfigures OCSP Stapling for
supported setups (Apache version >= 2.3.3 ). (default:
False)
--redirect Automatically redirect all HTTP traffic to HTTPS for
the newly authenticated vhost. (default: None)
--no-redirect Do not automatically redirect all HTTP traffic to
HTTPS for the newly authenticated vhost. (default:
None)
--hsts Add the Strict-Transport-Security header to every HTTP
response. Forcing browser to always use SSL for
the domain. Defends against SSL Stripping. (default:
False)
--no-hsts Do not automatically add the Strict-Transport-Security
header to every HTTP response. (default: False)
--uir Add the "Content-Security-Policy: upgrade-insecure-
requests" header to every HTTP response. Forcing the
browser to use https:// for every http:// resource.
(default: None)
--no-uir Do not automatically set the "Content-Security-Policy:
upgrade-insecure-requests" header to every HTTP
response. (default: None)
--staple-ocsp Enables OCSP Stapling. A valid OCSP response is
stapled to the certificate that the server offers
during TLS. (default: None)
--no-staple-ocsp Do not automatically enable OCSP Stapling. (default:
None)
--strict-permissions Require that all configuration files are owned by the
current user; only needed if your config is somewhere
unsafe like /tmp/ (default: False)
renew:
The 'renew' subcommand will attempt to renew all certificates (or more
precisely, certificate lineages) you have previously obtained if they are
close to expiry, and print a summary of the results. By default, 'renew'
will reuse the options used to create obtain or most recently successfully
renew each certificate lineage. You can try it with `--dry-run` first. For
more fine-grained control, you can renew individual lineages with the
`certonly` subcommand. Hooks are available to run commands before and
after renewal; see https://certbot.eff.org/docs/using.html#renewal for
more information on these.
--pre-hook PRE_HOOK Command to be run in a shell before obtaining any
certificates. Intended primarily for renewal, where it
can be used to temporarily shut down a webserver that
might conflict with the standalone plugin. This will
only be called if a certificate is actually to be
obtained/renewed. (default: None)
--post-hook POST_HOOK
Command to be run in a shell after attempting to
obtain/renew certificates. Can be used to deploy
renewed certificates, or to restart any servers that
were stopped by --pre-hook. This is only run if an
attempt was made to obtain/renew a certificate.
(default: None)
--renew-hook RENEW_HOOK
Command to be run in a shell once for each
successfully renewed certificate.For this command, the
shell variable $RENEWED_LINEAGE will point to
theconfig live subdirectory containing the new certs
and keys; the shell variable $RENEWED_DOMAINS will
contain a space-delimited list of renewed cert domains
(default: None)
--disable-hook-validation
Ordinarily the commands specified for --pre-hook
/--post-hook/--renew-hook will be checked for
validity, to see if the programs being run are in the
$PATH, so that mistakes can be caught early, even when
the hooks aren't being run just yet. The validation is
rather simplistic and fails if you use more advanced
shell constructs, so you can use this switch to
disable it. (default: True)
certonly:
Options for modifying how a cert is obtained
--csr CSR Path to a Certificate Signing Request (CSR) in DER
format; note that the .csr file *must* contain a
Subject Alternative Name field for each domain you
want certified. Currently --csr only works with the
'certonly' subcommand' (default: None)
install:
Options for modifying how a cert is deployed
revoke:
Options for revocation of certs
rollback:
Options for reverting config changes
--checkpoints N Revert configuration N number of checkpoints.
(default: 1)
plugins:
Plugin options
--init Initialize plugins. (default: False)
--prepare Initialize and prepare plugins. (default: False)
--authenticators Limit to authenticator plugins only. (default: None)
--installers Limit to installer plugins only. (default: None)
config_changes:
Options for showing a history of config changes
--num NUM How many past revisions you want to be displayed
(default: None)
paths:
Arguments changing execution paths & servers
--cert-path CERT_PATH
Path to where cert is saved (with auth --csr),
installed from or revoked. (default: None)
--key-path KEY_PATH Path to private key for cert installation or
revocation (if account key is missing) (default: None)
--fullchain-path FULLCHAIN_PATH
Accompanying path to a full certificate chain (cert
plus chain). (default: None)
--chain-path CHAIN_PATH
Accompanying path to a certificate chain. (default:
None)
--config-dir CONFIG_DIR
Configuration directory. (default: /etc/letsencrypt)
--work-dir WORK_DIR Working directory. (default: /var/lib/letsencrypt)
--logs-dir LOGS_DIR Logs directory. (default: /var/log/letsencrypt)
--server SERVER ACME Directory Resource URI. (default:
https://acme-v01.api.letsencrypt.org/directory)
plugins:
Certbot client supports an extensible plugins architecture. See 'certbot
plugins' for a list of all installed plugins and their names. You can
force a particular plugin by setting options provided below. Running
--help <plugin_name> will list flags specific to that plugin.
-a AUTHENTICATOR, --authenticator AUTHENTICATOR
Authenticator plugin name. (default: None)
-i INSTALLER, --installer INSTALLER
Installer plugin name (also used to find domains).
(default: None)
--configurator CONFIGURATOR
Name of the plugin that is both an authenticator and
an installer. Should not be used together with
--authenticator or --installer. (default: None)
--apache Obtain and install certs using Apache (default: False)
--nginx Obtain and install certs using Nginx (default: False)
--standalone Obtain certs using a "standalone" webserver. (default:
False)
--manual Provide laborious manual instructions for obtaining a
cert (default: False)
--webroot Obtain certs by placing files in a webroot directory.
(default: False)
standalone:
Automatically use a temporary webserver
--standalone-supported-challenges STANDALONE_SUPPORTED_CHALLENGES
Supported challenges. Preferred in the order they are
listed. (default: tls-sni-01,http-01)
manual:
Manually configure an HTTP server
--manual-test-mode Test mode. Executes the manual command in subprocess.
(default: False)
--manual-public-ip-logging-ok
Automatically allows public IP logging. (default:
False)
nginx:
Nginx Web Server - currently doesn't work
--nginx-server-root NGINX_SERVER_ROOT
Nginx server root directory. (default: /etc/nginx)
--nginx-ctl NGINX_CTL
Path to the 'nginx' binary, used for 'configtest' and
retrieving nginx version number. (default: nginx)
webroot:
Place files in webroot directory
--webroot-path WEBROOT_PATH, -w WEBROOT_PATH
public_html / webroot path. This can be specified
multiple times to handle different domains; each
domain will have the webroot path that preceded it.
For instance: `-w /var/www/example -d example.com -d
www.example.com -w /var/www/thing -d thing.net -d
m.thing.net` (default: [])
--webroot-map WEBROOT_MAP
JSON dictionary mapping domains to webroot paths; this
implies -d for each entry. You may need to escape this
from your shell. E.g.: --webroot-map
'{"eg1.is,m.eg1.is":"/www/eg1/", "eg2.is":"/www/eg2"}'
This option is merged with, but takes precedence over,
-w / -d entries. At present, if you put webroot-map in
a config file, it needs to be on a single line, like:
webroot-map = {"example.com":"/var/www"}. (default:
{})
apache:
Apache Web Server - Alpha
--apache-enmod APACHE_ENMOD
Path to the Apache 'a2enmod' binary. (default:
a2enmod)
--apache-dismod APACHE_DISMOD
Path to the Apache 'a2dismod' binary. (default:
a2dismod)
--apache-le-vhost-ext APACHE_LE_VHOST_EXT
SSL vhost configuration extension. (default: -le-
ssl.conf)
--apache-server-root APACHE_SERVER_ROOT
Apache server root directory. (default: /etc/apache2)
--apache-vhost-root APACHE_VHOST_ROOT
Apache server VirtualHost configuration root (default:
/etc/apache2/sites-available)
--apache-challenge-location APACHE_CHALLENGE_LOCATION
Directory path for challenge configuration. (default:
/etc/apache2)
--apache-handle-modules APACHE_HANDLE_MODULES
Let installer handle enabling required modules for
you.(Only Ubuntu/Debian currently) (default: True)
--apache-handle-sites APACHE_HANDLE_SITES
Let installer handle enabling sites for you.(Only
Ubuntu/Debian currently) (default: True)
null:
Null Installer
docs/conf.py
+8 -8
View File
@@ -64,8 +64,8 @@ source_suffix = '.rst'
master_doc = 'index'
# General information about the project.
project = u'Let\'s Encrypt'
copyright = u'2014-2015, Let\'s Encrypt Project'
project = u'Certbot'
copyright = u'2014-2016 - The Certbot software and documentation are licensed under the Apache 2.0 license as described at https://eff.org/cb-license '
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@@ -225,7 +225,7 @@ html_static_path = ['_static']
#html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
htmlhelp_basename = 'LetsEncryptdoc'
htmlhelp_basename = 'Certbotdoc'
# -- Options for LaTeX output ---------------------------------------------
@@ -247,8 +247,8 @@ latex_elements = {
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
('index', 'LetsEncrypt.tex', u'Let\'s Encrypt Documentation',
u'Let\'s Encrypt Project', 'manual'),
('index', 'Certbot.tex', u'Certbot Documentation',
u'Certbot Project', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
@@ -277,7 +277,7 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'certbot', u'Let\'s Encrypt Documentation',
('index', 'certbot', u'Certbot Documentation',
[project], 7),
('man/certbot', 'certbot', u'certbot script documentation',
[project], 1),
@@ -293,8 +293,8 @@ man_pages = [
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'LetsEncrypt', u'Let\'s Encrypt Documentation',
u'Let\'s Encrypt Project', 'LetsEncrypt', 'One line description of project.',
('index', 'Certbot', u'Certbot Documentation',
u'Certbot Project', 'Certbot', 'One line description of project.',
'Miscellaneous'),
]
docs/contributing.rst
+16 -12
View File
@@ -20,8 +20,8 @@ once:
.. code-block:: shell
git clone https://github.com/letsencrypt/letsencrypt
cd letsencrypt
git clone https://github.com/certbot/certbot
cd certbot
./letsencrypt-auto-source/letsencrypt-auto --os-packages-only
./tools/venv.sh
@@ -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
<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
-------
@@ -71,6 +71,9 @@ The following tools are there to help you:
experimental, non-production Apache2 install on them. ``tox -e
apacheconftest`` can be used to run those specific Apache conf tests.
- ``tox --skip-missing-interpreters`` runs tox while ignoring missing versions
of Python needed for running the tests.
- ``tox -e py27``, ``tox -e py26`` etc, run unit tests for specific Python
versions.
@@ -175,8 +178,8 @@ Configurators may implement just one of those).
There are also `~certbot.interfaces.IDisplay` plugins,
which implement bindings to alternative UI libraries.
.. _interfaces.py: https://github.com/letsencrypt/letsencrypt/blob/master/certbot/interfaces.py
.. _plugins/common.py: https://github.com/letsencrypt/letsencrypt/blob/master/certbot/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
@@ -266,8 +269,7 @@ with the core upstream source code. An example is provided in
it with any necessary API changes.
.. _`setuptools entry points`:
https://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins
http://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points
.. _coding-style:
@@ -297,7 +299,7 @@ Please:
4. Remember to use ``pylint``.
.. _Google Python Style Guide:
https://google-styleguide.googlecode.com/svn/trunk/pyguide.html
https://google.github.io/styleguide/pyguide.html
.. _Sphinx-style: http://sphinx-doc.org/
.. _PEP 8 - Style Guide for Python Code:
https://www.python.org/dev/peps/pep-0008
@@ -314,7 +316,9 @@ Steps:
3. Run ``./pep8.travis.sh`` to do a cursory check of your code style.
Fix any errors.
4. Run ``tox -e lint`` to check for pylint errors. Fix any errors.
5. Run ``tox`` to run the entire test suite including coverage. Fix any errors.
5. 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.
6. If your code touches communication with an ACME server/Boulder, you
should run the integration tests, see `integration`_. See `Known Issues`_
for some common failures that have nothing to do with your code.
@@ -323,7 +327,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
==========================
@@ -333,7 +337,7 @@ commands:
.. code-block:: shell
make -C docs clean html
make -C docs clean html man
This should generate documentation in the ``docs/_build/html``
directory.
docs/index.rst
+1 -1
View File
@@ -1,4 +1,4 @@
Welcome to the Let's Encrypt client documentation!
Welcome to the Certbot documentation!
==================================================
.. toctree::
docs/intro.rst
+3 -3
View File
@@ -1,6 +1,6 @@
============
Introduction
============
=====================
README / Introduction
=====================
.. include:: ../README.rst
.. include:: ../CHANGES.rst
docs/man/certbot.rst
+1 -1
View File
@@ -1 +1 @@
.. program-output:: certbot --help all
.. literalinclude:: ../cli-help.txt
docs/using.rst
+131 -126
View File
@@ -5,66 +5,38 @@ User Guide
.. contents:: Table of Contents
:local:
.. _installation:
Getting Certbot
===============
Installation
============
To get specific instructions for installing Certbot on your OS, we recommend
visiting certbot.eff.org_. If you're offline, you can find some general
instructions `in the README / Introduction <intro.html#installation>`__
.. _letsencrypt-auto:
__ installation_
.. _certbot.eff.org: https://certbot.eff.org
letsencrypt-auto
----------------
.. _certbot-auto:
``letsencrypt-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
provides automated updates.
The name of the certbot command
-------------------------------
To install and run the client, just type...
.. code-block:: shell
./letsencrypt-auto
.. hint:: During the beta phase, Let's Encrypt 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:
.. code-block:: shell
./letsencrypt-auto --help
or for full help, type:
.. code-block:: shell
./letsencrypt-auto --help all
``letsencrypt-auto`` is the recommended method of running the Let's Encrypt
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
run your own locally modified copy of the client, follow the instructions in
the :doc:`contributing`. Some `other methods of installation`_ are discussed
below.
Many platforms now have native packages that give you a ``certbot`` or (for
older packages) ``letsencrypt`` command you can run. On others, the
``certbot-auto`` / ``letsencrypt-auto`` installer and wrapper script is a
stand-in. Throughout the documentation, whenever you see references to
``certbot`` script/binary, you should substitute in the name of the command
that certbot.eff.org_ told you to use on your system (``certbot``,
``letsencrypt``, or ``certbot-auto``).
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,27 +51,10 @@ 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:
=========== ==== ==== ===============================================================
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
=========== ==== ==== ===============================================================
.. _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
Future plugins for IMAP servers, SMTP servers, IRC servers, etc, are likely to
be installers but not authenticators.
There are many third-party-plugins_ available.
Apache
------
@@ -130,16 +85,16 @@ 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 Let's Encrypt
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:
::
@@ -173,7 +128,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
@@ -186,16 +141,49 @@ Nginx
In the future, if you're running Nginx you will hopefully be able to 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
still experimental, however, and is not installed with certbot-auto_. If
installed, you can select this plugin on the command line by including
``--nginx``.
.. _third-party-plugins:
Third-party plugins
-------------------
These plugins are listed at
https://github.com/letsencrypt/letsencrypt/wiki/Plugins. If you're
interested, you can also :ref:`write your own plugin <dev-plugin>`.
There are also a number of third-party plugins for the client, provided by
other developers. Many are beta/experimental, but some are already in
widespread use:
=========== ==== ==== ===============================================================
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 certs via a Varnish server
external_ Y N A plugin for convenient scripting (See also ticket 2782_)
icecast_ N Y Deploy certs to Icecast 2 streaming media servers
pritunl_ N Y Install certs in pritunl distributed OpenVPN servers
proxmox_ N Y Install certs in Proxmox Virtualization servers
postfix_ N Y STARTTLS Everywhere is becoming a Certbot Postfix/Exim plugin
=========== ==== ==== ===============================================================
.. _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
.. _icecast: https://github.com/e00E/lets-encrypt-icecast
.. _varnish: http://git.sesse.net/?p=letsencrypt-varnish-plugin
.. _2782: https://github.com/certbot/certbot/issues/2782
.. _pritunl: https://github.com/kharkevich/letsencrypt-pritunl
.. _proxmox: https://github.com/kharkevich/letsencrypt-proxmox
.. _external: https://github.com/marcan/letsencrypt-external
.. _postfix: https://github.com/EFForg/starttls-everywhere
If you're interested, you can also :ref:`write your own plugin <dev-plugin>`.
Renewal
=======
@@ -204,23 +192,36 @@ 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
at the time the certificate was originally issued will be used for the
renewal attempt, unless you specify other plugins or options.
You can also specify hooks to be run before or after a certificate is
renewed. For example, if you want to use the standalone_ plugin to renew
your certificates, you may want to use a command like
``certbot renew --standalone --pre-hook "service nginx stop" --post-hook "service nginx start"``
This will stop Nginx so standalone can bind to the necessary ports and
then restart Nginx after the plugin is finished. The hooks will only be
run if a certificate is due for renewal, so you can run this command
frequently without unnecessarily stopping your webserver. More
information about renewal hooks can be found by running
``certbot --help renew``.
If you're sure that this command executes successfully without human
intervention, you can add the command to ``crontab`` (since certificates
are only renewed when they're determined to be near expiry, the command
can run on a regular basis, like every week or every day); note that
the current version provides detailed output describing either renewal
success or failure.
can run on a regular basis, like every week or every day). In that case,
you are likely to want to use the ``-q`` or ``--quiet`` quiet flag to
silence all output except errors.
The ``--force-renew`` flag may be helpful for automating renewal;
it causes the expiration time of the certificate(s) to be ignored when
@@ -229,9 +230,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 +241,12 @@ 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
a specific certificate specified via `-d` flags, like
is ``certbot certonly`` with the complete set of subject domains of
a specific certificate specified via `-d` flags. You may also want to
include the ``-n`` or ``--noninteractive`` flag to prevent blocking on
user input (which is useful when running the command from cron).
``letsencrypt certonly -d example.com -d www.example.com``
``certbot certonly -n -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,21 +259,25 @@ 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.
.. _command-line:
Command line options
====================
Certbot supports a lot of command line options. Here's the full list, from
``certbot --help all``:
.. literalinclude:: cli-help.txt
.. _where-certs:
Where are my certificates?
==========================
First of all, we encourage you to use Apache or nginx installers, both
which perform the certificate management automatically. If, however,
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
your (web) server configuration directly to those files (or create
@@ -287,7 +294,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.
@@ -330,8 +337,8 @@ will cause nasty errors served through the browsers!
.. note:: All files are PEM-encoded (as the filename suffix
suggests). If you need other format, such as DER or PFX, then you
could convert using ``openssl``, but this means you will not
benefit from automatic renewal_!
could convert using ``openssl``. You can automate that with
``--renew-hook`` if you're using automatic renewal_.
.. _config-file:
@@ -340,7 +347,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
@@ -359,13 +366,14 @@ By default, the following locations are searched:
Getting help
============
If you're having problems you can chat with us on `IRC (#letsencrypt @
Freenode) <https://webchat.freenode.net?channels=%23letsencrypt>`_ or
get support on our `forums <https://community.letsencrypt.org>`_.
If you're having problems you can chat with us on `IRC (#certbot @
OFTC) <https://webchat.oftc.net?channels=%23certbot>`_ or at
`IRC (#letsencrypt @ freenode) <https://webchat.freenode.net?channels=%23letsencrypt>`_
or get support on the Let's Encrypt `forums <https://community.letsencrypt.org>`_.
If you find a bug in the software, please do report it in our `issue
tracker
<https://github.com/letsencrypt/letsencrypt/issues>`_. Remember to
<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
@@ -373,9 +381,9 @@ give us as much information as possible:
information, including your email and domains)
- copy and paste logs from ``/var/log/letsencrypt`` (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
- specify which installation method you've chosen
Other methods of installation
=============================
@@ -390,10 +398,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,7 +410,7 @@ to, `install Docker`_, then issue the following command:
.. code-block:: shell
sudo docker run -it --rm -p 443:443 -p 80:80 --name letsencrypt \
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" \
quay.io/letsencrypt/letsencrypt:latest auth
@@ -420,7 +428,7 @@ Operating System Packages
**FreeBSD**
* Port: ``cd /usr/ports/security/py-letsencrypt && make install clean``
* Port: ``cd /usr/ports/security/py-certbot && make install clean``
* Package: ``pkg install py27-letsencrypt``
**OpenBSD**
@@ -432,19 +440,19 @@ Operating System Packages
.. code-block:: shell
sudo pacman -S letsencrypt letsencrypt-apache
sudo pacman -S certbot
**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 exist for Debian Jessie via backports. First you'll have to follow the
instructions at http://backports.debian.org/Instructions/ to enable the Jessie backports
@@ -452,7 +460,7 @@ 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 letsencrypt python-letsencrypt-apache -t jessie-backports
**Fedora**
@@ -462,7 +470,7 @@ repo, if you have not already done so. Then run:
**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
@@ -471,8 +479,12 @@ want to use the Apache plugin, it has to be installed separately:
emerge -av app-crypt/letsencrypt-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
does include the nginx plugin package:
Warning!
You can use Layman to add the mrueg overlay which does include a package for the
Certbot Nginx plugin, however, this plugin is known to be buggy and should only
be used with caution after creating a backup up your Nginx configuration.
We strongly recommend you use the app-crypt/letsencrypt package instead until
the Nginx plugin is ready.
.. code-block:: shell
@@ -509,7 +521,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`.
@@ -525,25 +537,18 @@ 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
Unless you have a very specific requirements, we kindly suggest that you use
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!
TLS/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.
.. rubric:: Footnotes
.. [#venv] By using this virtualized Python environment (`virtualenv
<https://virtualenv.pypa.io>`_) we don't pollute the main
OS space with packages from PyPI!