216 lines
8.0 KiB
ReStructuredText
216 lines
8.0 KiB
ReStructuredText
=============
|
|
Let's Encrypt
|
|
=============
|
|
|
|
..
|
|
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
!! This file is generated by oca-gen-addon-readme !!
|
|
!! changes will be overwritten. !!
|
|
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
!! source digest: sha256:cdcc2b718b9ac4d05dc0a5b5d624f71c7402f605b11447a79d1d9161938f2a2d
|
|
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
|
|
.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
|
|
:target: https://odoo-community.org/page/development-status
|
|
:alt: Beta
|
|
.. |badge2| image:: https://img.shields.io/badge/licence-AGPL--3-blue.png
|
|
:target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
|
|
:alt: License: AGPL-3
|
|
.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fserver--tools-lightgray.png?logo=github
|
|
:target: https://github.com/OCA/server-tools/tree/16.0/letsencrypt
|
|
:alt: OCA/server-tools
|
|
.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png
|
|
:target: https://translation.odoo-community.org/projects/server-tools-16-0/server-tools-16-0-letsencrypt
|
|
:alt: Translate me on Weblate
|
|
.. |badge5| image:: https://img.shields.io/badge/runboat-Try%20me-875A7B.png
|
|
:target: https://runboat.odoo-community.org/builds?repo=OCA/server-tools&target_branch=16.0
|
|
:alt: Try me on Runboat
|
|
|
|
|badge1| |badge2| |badge3| |badge4| |badge5|
|
|
|
|
This module was written to have your Odoo installation request SSL certificates
|
|
from https://letsencrypt.org automatically.
|
|
|
|
**Table of contents**
|
|
|
|
.. contents::
|
|
:local:
|
|
|
|
Installation
|
|
============
|
|
|
|
After installation, this module generates a private key for your account at
|
|
letsencrypt.org automatically in ``$data_dir/letsencrypt/account.key``. If you
|
|
want or need to use your own account key, replace the file.
|
|
|
|
For certificate requests to work, your site needs to be accessible via plain
|
|
HTTP, see below for configuration examples in case you force your clients to
|
|
the SSL version.
|
|
|
|
After installation, trigger the cronjob `Update letsencrypt certificates` and
|
|
watch your log for messages.
|
|
|
|
Configuration
|
|
=============
|
|
|
|
This addons requests a certificate for the domain named in the configuration
|
|
parameter ``web.base.url`` - if this comes back as ``localhost`` or the like,
|
|
the module doesn't request anything.
|
|
|
|
Futher self-explanatory settings are in Settings -> General Settings. There you
|
|
can add further domains to the CSR, add a custom script that updates your DNS
|
|
and add a script that will be used to reload your web server (if needed).
|
|
The number of domains that can be added to a certificate is
|
|
`capped at 100 <https://letsencrypt.org/docs/rate-limits/>`_. A wildcard
|
|
certificate can be used to avoid that limit.
|
|
|
|
Note that all those domains must be publicly reachable on port 80 via HTTP, and
|
|
they must have an entry for ``.well-known/acme-challenge`` pointing to
|
|
``$datadir/letsencrypt/acme-challenge`` of your odoo instance.
|
|
|
|
Since DNS changes can take some time to propagate, when we respond to a DNS challenge
|
|
and the server tries to check our response, it might fail (and probably will).
|
|
The solution to this is documented in https://tools.ietf.org/html/rfc8555#section-8.2
|
|
and basically is a ``Retry-After`` header under which we can instruct the server to
|
|
retry the challenge.
|
|
At the time these lines were written, Boulder had not implemented this functionality.
|
|
This prompted us to use ``letsencrypt.backoff`` configuration parameter, which is the
|
|
amount of minutes this module will try poll the server to retry validating the answer
|
|
to our challenge, specifically it is the ``deadline`` parameter of ``poll_and_finalize``.
|
|
|
|
Usage
|
|
=====
|
|
|
|
The module sets up a cronjob that requests and renews certificates automatically.
|
|
|
|
Certificates are renewed a month before they expire. Renewal is then attempted
|
|
every day until it succeeds.
|
|
|
|
After the first run, you'll find a file called ``domain.crt`` in
|
|
``$datadir/letsencrypt``, configure your SSL proxy to use this file as certificate.
|
|
|
|
In depth configuration
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If you want to use multiple domains on your CSR then you have to configure them
|
|
from Settings -> General Settings. If you use a wildcard in any of those domains
|
|
then letsencrypt will return a DNS challenge. In order for that challenge to be
|
|
answered you will need to **either** provide a script (as seen in General Settings)
|
|
or install a module that provides support for your DNS provider. In that module
|
|
you will need to create a function in the letsencrypt model with the name
|
|
``_respond_challenge_dns_$DNS_PROVIDER`` where ``$DNS_PROVIDER`` is the name of your
|
|
provider and can be any string with length greater than zero, and add the name
|
|
of your DNS provider in the settings dns_provider selection field.
|
|
|
|
In any case if a script path is inserted in the settings page, it will be run
|
|
in case you want to update multiple DNS servers.
|
|
|
|
A reload command can be set in the Settings as well in case you need to reload
|
|
your web server. This by default is ``sudo /usr/sbin/service nginx reload``
|
|
|
|
|
|
You'll also need a matching sudo configuration, like::
|
|
|
|
your_odoo_user ALL = NOPASSWD: /usr/sbin/service nginx reload
|
|
|
|
Further, if you force users to https, you'll need something like for nginx::
|
|
|
|
if ($scheme = "http") {
|
|
set $redirect_https 1;
|
|
}
|
|
if ($request_uri ~ ^/.well-known/acme-challenge/) {
|
|
set $redirect_https 0;
|
|
}
|
|
if ($redirect_https) {
|
|
rewrite ^ https://$server_name$request_uri? permanent;
|
|
}
|
|
|
|
and this for apache::
|
|
|
|
RewriteEngine On
|
|
RewriteCond %{HTTPS} !=on
|
|
RewriteCond %{REQUEST_URI} "!^/.well-known/"
|
|
RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R,L]
|
|
|
|
In case you need to redirect other nginx sites to your Odoo instance, declare
|
|
an upstream for your odoo instance and do something like::
|
|
|
|
location /.well-known {
|
|
proxy_pass http://yourodooupstream;
|
|
}
|
|
|
|
If you're using a multi-database installation (with or without dbfilter option)
|
|
where /web/databse/selector returns a list of more than one database, then
|
|
you need to add ``letsencrypt`` addon to wide load addons list
|
|
(by default, only ``web`` addon), setting ``--load`` option.
|
|
For example, ``--load=web,letsencrypt``
|
|
|
|
Bug Tracker
|
|
===========
|
|
|
|
Bugs are tracked on `GitHub Issues <https://github.com/OCA/server-tools/issues>`_.
|
|
In case of trouble, please check there if your issue has already been reported.
|
|
If you spotted it first, help us to smash it by providing a detailed and welcomed
|
|
`feedback <https://github.com/OCA/server-tools/issues/new?body=module:%20letsencrypt%0Aversion:%2016.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.
|
|
|
|
Do not contact contributors directly about support or help with technical issues.
|
|
|
|
Credits
|
|
=======
|
|
|
|
Authors
|
|
~~~~~~~
|
|
|
|
* Therp BV
|
|
* Tecnativa
|
|
* Acysos S.L
|
|
|
|
Contributors
|
|
~~~~~~~~~~~~
|
|
|
|
* Holger Brunn <mail@hunki-enterprises.nl>
|
|
* Antonio Espinosa <antonio.espinosa@tecnativa.com>
|
|
* Dave Lasley <dave@laslabs.com>
|
|
* Ronald Portier <ronald@therp.nl>
|
|
* Ignacio Ibeas <ignacio@acysos.com>
|
|
* George Daramouskas <gdaramouskas@therp.nl>
|
|
* Jan Verbeek <jverbeek@therp.nl>
|
|
|
|
Other credits
|
|
~~~~~~~~~~~~~
|
|
|
|
ACME implementation
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
* https://github.com/certbot/certbot/tree/0.22.x/acme
|
|
|
|
Icon
|
|
~~~~
|
|
|
|
* https://helloworld.letsencrypt.org
|
|
|
|
Maintainers
|
|
~~~~~~~~~~~
|
|
|
|
This module is maintained by the OCA.
|
|
|
|
.. image:: https://odoo-community.org/logo.png
|
|
:alt: Odoo Community Association
|
|
:target: https://odoo-community.org
|
|
|
|
OCA, or the Odoo Community Association, is a nonprofit organization whose
|
|
mission is to support the collaborative development of Odoo features and
|
|
promote its widespread use.
|
|
|
|
.. |maintainer-hbrunn| image:: https://github.com/hbrunn.png?size=40px
|
|
:target: https://github.com/hbrunn
|
|
:alt: hbrunn
|
|
|
|
Current `maintainer <https://odoo-community.org/page/maintainer-role>`__:
|
|
|
|
|maintainer-hbrunn|
|
|
|
|
This module is part of the `OCA/server-tools <https://github.com/OCA/server-tools/tree/16.0/letsencrypt>`_ project on GitHub.
|
|
|
|
You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.
|