Techsystech
/
server-tools
mirror of https://github.com/OCA/server-tools.git
3
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
server-tools/letsencrypt/static/description/index.html

547 lines
20 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.15.1: http://docutils.sourceforge.net/" />
<title>Let's Encrypt</title>
<style type="text/css">
/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 7952 2016-07-26 18:15:59Z milde $
:Copyright: This stylesheet has been placed in the public domain.
Default cascading style sheet for the HTML output of Docutils.
See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/
/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
border: 0 }
table.borderless td, table.borderless th {
/* Override padding for "table.docutils td" with "! important".
The right padding separates the table cells. */
padding: 0 0.5em 0 0 ! important }
.first {
/* Override more specific margin styles with "! important". */
margin-top: 0 ! important }
.last, .with-subtitle {
margin-bottom: 0 ! important }
.hidden {
display: none }
.subscript {
vertical-align: sub;
font-size: smaller }
.superscript {
vertical-align: super;
font-size: smaller }
a.toc-backref {
text-decoration: none ;
color: black }
blockquote.epigraph {
margin: 2em 5em ; }
dl.docutils dd {
margin-bottom: 0.5em }
object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
overflow: hidden;
}
/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
font-weight: bold }
*/
div.abstract {
margin: 2em 5em }
div.abstract p.topic-title {
font-weight: bold ;
text-align: center }
div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
margin: 2em ;
border: medium outset ;
padding: 1em }
div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
font-weight: bold ;
font-family: sans-serif }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title, .code .error {
color: red ;
font-weight: bold ;
font-family: sans-serif }
/* Uncomment (and remove this text!) to get reduced vertical space in
compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
margin-bottom: 0.5em }
div.compound .compound-last, div.compound .compound-middle {
margin-top: 0.5em }
*/
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em ;
margin-right: 2em }
div.footer, div.header {
clear: both;
font-size: smaller }
div.line-block {
display: block ;
margin-top: 1em ;
margin-bottom: 1em }
div.line-block div.line-block {
margin-top: 0 ;
margin-bottom: 0 ;
margin-left: 1.5em }
div.sidebar {
margin: 0 0 0.5em 1em ;
border: medium outset ;
padding: 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
clear: right }
div.sidebar p.rubric {
font-family: sans-serif ;
font-size: medium }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
margin: 2em }
h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
margin-top: 0.4em }
h1.title {
text-align: center }
h2.subtitle {
text-align: center }
hr.docutils {
width: 75% }
img.align-left, .figure.align-left, object.align-left, table.align-left {
clear: left ;
float: left ;
margin-right: 1em }
img.align-right, .figure.align-right, object.align-right, table.align-right {
clear: right ;
float: right ;
margin-left: 1em }
img.align-center, .figure.align-center, object.align-center {
display: block;
margin-left: auto;
margin-right: auto;
}
table.align-center {
margin-left: auto;
margin-right: auto;
}
.align-left {
text-align: left }
.align-center {
clear: both ;
text-align: center }
.align-right {
text-align: right }
/* reset inner alignment in figures */
div.align-right {
text-align: inherit }
/* div.align-center * { */
/* text-align: left } */
.align-top {
vertical-align: top }
.align-middle {
vertical-align: middle }
.align-bottom {
vertical-align: bottom }
ol.simple, ul.simple {
margin-bottom: 1em }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.rubric {
font-weight: bold ;
font-size: larger ;
color: maroon ;
text-align: center }
p.sidebar-title {
font-family: sans-serif ;
font-weight: bold ;
font-size: larger }
p.sidebar-subtitle {
font-family: sans-serif ;
font-weight: bold }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
font: inherit }
pre.literal-block, pre.doctest-block, pre.math, pre.code {
margin-left: 2em ;
margin-right: 2em }
pre.code .ln { color: grey; } /* line numbers */
pre.code, code { background-color: #eeeeee }
pre.code .comment, code .comment { color: #5C6576 }
pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
pre.code .literal.string, code .literal.string { color: #0C5404 }
pre.code .name.builtin, code .name.builtin { color: #352B84 }
pre.code .deleted, code .deleted { background-color: #DEB0A1}
pre.code .inserted, code .inserted { background-color: #A3D289}
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
span.option {
white-space: nowrap }
span.pre {
white-space: pre }
span.problematic {
color: red }
span.section-subtitle {
/* font-size relative to parent (h1..h6 element) */
font-size: 80% }
table.citation {
border-left: solid 1px gray;
margin-left: 1px }
table.docinfo {
margin: 2em 4em }
table.docutils {
margin-top: 0.5em ;
margin-bottom: 0.5em }
table.footnote {
border-left: solid 1px black;
margin-left: 1px }
table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
padding-left: 0.5em ;
padding-right: 0.5em ;
vertical-align: top }
table.docutils th.field-name, table.docinfo th.docinfo-name {
font-weight: bold ;
text-align: left ;
white-space: nowrap ;
padding-left: 0 }
/* "booktabs" style (no vertical lines) */
table.docutils.booktabs {
border: 0px;
border-top: 2px solid;
border-bottom: 2px solid;
border-collapse: collapse;
}
table.docutils.booktabs * {
border: 0px;
}
table.docutils.booktabs th {
border-bottom: thin solid;
text-align: left;
}
h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
font-size: 100% }
ul.auto-toc {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="let-s-encrypt">
<h1 class="title">Let’s Encrypt</h1>
<!-- !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!! This file is generated by oca-gen-addon-readme !!
!! changes will be overwritten. !!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -->
<p><a class="reference external" href="https://odoo-community.org/page/development-status"><img alt="Beta" src="https://img.shields.io/badge/maturity-Beta-yellow.png" /></a> <a class="reference external" href="http://www.gnu.org/licenses/agpl-3.0-standalone.html"><img alt="License: AGPL-3" src="https://img.shields.io/badge/licence-AGPL--3-blue.png" /></a> <a class="reference external" href="https://github.com/OCA/server-tools/tree/15.0/letsencrypt"><img alt="OCA/server-tools" src="https://img.shields.io/badge/github-OCA%2Fserver--tools-lightgray.png?logo=github" /></a> <a class="reference external" href="https://translation.odoo-community.org/projects/server-tools-15-0/server-tools-15-0-letsencrypt"><img alt="Translate me on Weblate" src="https://img.shields.io/badge/weblate-Translate%20me-F47D42.png" /></a> <a class="reference external" href="https://runbot.odoo-community.org/runbot/149/15.0"><img alt="Try me on Runbot" src="https://img.shields.io/badge/runbot-Try%20me-875A7B.png" /></a></p>
<p>This module was written to have your Odoo installation request SSL certificates
from <a class="reference external" href="https://letsencrypt.org">https://letsencrypt.org</a> automatically.</p>
<p><strong>Table of contents</strong></p>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><a class="reference internal" href="#installation" id="id1">Installation</a></li>
<li><a class="reference internal" href="#configuration" id="id2">Configuration</a></li>
<li><a class="reference internal" href="#usage" id="id3">Usage</a><ul>
<li><a class="reference internal" href="#in-depth-configuration" id="id4">In depth configuration</a></li>
</ul>
</li>
<li><a class="reference internal" href="#bug-tracker" id="id5">Bug Tracker</a></li>
<li><a class="reference internal" href="#credits" id="id6">Credits</a><ul>
<li><a class="reference internal" href="#authors" id="id7">Authors</a></li>
<li><a class="reference internal" href="#contributors" id="id8">Contributors</a></li>
<li><a class="reference internal" href="#other-credits" id="id9">Other credits</a></li>
<li><a class="reference internal" href="#acme-implementation" id="id10">ACME implementation</a></li>
<li><a class="reference internal" href="#icon" id="id11">Icon</a></li>
<li><a class="reference internal" href="#maintainers" id="id12">Maintainers</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="installation">
<h1><a class="toc-backref" href="#id1">Installation</a></h1>
<p>After installation, this module generates a private key for your account at
letsencrypt.org automatically in <tt class="docutils literal">$data_dir/letsencrypt/account.key</tt>. If you
want or need to use your own account key, replace the file.</p>
<p>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.</p>
<p>After installation, trigger the cronjob <cite>Update letsencrypt certificates</cite> and
watch your log for messages.</p>
</div>
<div class="section" id="configuration">
<h1><a class="toc-backref" href="#id2">Configuration</a></h1>
<p>This addons requests a certificate for the domain named in the configuration
parameter <tt class="docutils literal">web.base.url</tt> - if this comes back as <tt class="docutils literal">localhost</tt> or the like,
the module doesn’t request anything.</p>
<p>Futher self-explanatory settings are in Settings -&gt; 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
<a class="reference external" href="https://letsencrypt.org/docs/rate-limits/">capped at 100</a>. A wildcard
certificate can be used to avoid that limit.</p>
<p>Note that all those domains must be publicly reachable on port 80 via HTTP, and
they must have an entry for <tt class="docutils literal"><span class="pre">.well-known/acme-challenge</span></tt> pointing to
<tt class="docutils literal"><span class="pre">$datadir/letsencrypt/acme-challenge</span></tt> of your odoo instance.</p>
<p>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 <a class="reference external" href="https://tools.ietf.org/html/rfc8555#section-8.2">https://tools.ietf.org/html/rfc8555#section-8.2</a>
and basically is a <tt class="docutils literal"><span class="pre">Retry-After</span></tt> 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 <tt class="docutils literal">letsencrypt.backoff</tt> 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 <tt class="docutils literal">deadline</tt> parameter of <tt class="docutils literal">poll_and_finalize</tt>.</p>
</div>
<div class="section" id="usage">
<h1><a class="toc-backref" href="#id3">Usage</a></h1>
<p>The module sets up a cronjob that requests and renews certificates automatically.</p>
<p>Certificates are renewed a month before they expire. Renewal is then attempted
every day until it succeeds.</p>
<p>After the first run, you’ll find a file called <tt class="docutils literal">domain.crt</tt> in
<tt class="docutils literal">$datadir/letsencrypt</tt>, configure your SSL proxy to use this file as certificate.</p>
<div class="section" id="in-depth-configuration">
<h2><a class="toc-backref" href="#id4">In depth configuration</a></h2>
<p>If you want to use multiple domains on your CSR then you have to configure them
from Settings -&gt; 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 <strong>either</strong> 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
<tt class="docutils literal">_respond_challenge_dns_$DNS_PROVIDER</tt> where <tt class="docutils literal">$DNS_PROVIDER</tt> 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.</p>
<p>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.</p>
<p>A reload command can be set in the Settings as well in case you need to reload
your web server. This by default is <tt class="docutils literal">sudo /usr/sbin/service nginx reload</tt></p>
<p>You’ll also need a matching sudo configuration, like:</p>
<pre class="literal-block">
your_odoo_user ALL = NOPASSWD: /usr/sbin/service nginx reload
</pre>
<p>Further, if you force users to https, you’ll need something like for nginx:</p>
<pre class="literal-block">
if ($scheme = &quot;http&quot;) {
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;
}
</pre>
<p>and this for apache:</p>
<pre class="literal-block">
RewriteEngine On
RewriteCond %{HTTPS} !=on
RewriteCond %{REQUEST_URI} &quot;!^/.well-known/&quot;
RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R,L]
</pre>
<p>In case you need to redirect other nginx sites to your Odoo instance, declare
an upstream for your odoo instance and do something like:</p>
<pre class="literal-block">
location /.well-known {
proxy_pass http://yourodooupstream;
}
</pre>
<p>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 <tt class="docutils literal">letsencrypt</tt> addon to wide load addons list
(by default, only <tt class="docutils literal">web</tt> addon), setting <tt class="docutils literal"><span class="pre">--load</span></tt> option.
For example, <tt class="docutils literal"><span class="pre">--load=web,letsencrypt</span></tt></p>
</div>
</div>
<div class="section" id="bug-tracker">
<h1><a class="toc-backref" href="#id5">Bug Tracker</a></h1>
<p>Bugs are tracked on <a class="reference external" href="https://github.com/OCA/server-tools/issues">GitHub Issues</a>.
In case of trouble, please check there if your issue has already been reported.
If you spotted it first, help us smashing it by providing a detailed and welcomed
<a class="reference external" href="https://github.com/OCA/server-tools/issues/new?body=module:%20letsencrypt%0Aversion:%2015.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**">feedback</a>.</p>
<p>Do not contact contributors directly about support or help with technical issues.</p>
</div>
<div class="section" id="credits">
<h1><a class="toc-backref" href="#id6">Credits</a></h1>
<div class="section" id="authors">
<h2><a class="toc-backref" href="#id7">Authors</a></h2>
<ul class="simple">
<li>Therp BV</li>
<li>Tecnativa</li>
<li>Acysos S.L</li>
</ul>
</div>
<div class="section" id="contributors">
<h2><a class="toc-backref" href="#id8">Contributors</a></h2>
<ul class="simple">
<li>Holger Brunn &lt;<a class="reference external" href="mailto:mail&#64;hunki-enterprises.nl">mail&#64;hunki-enterprises.nl</a>&gt;</li>
<li>Antonio Espinosa &lt;<a class="reference external" href="mailto:antonio.espinosa&#64;tecnativa.com">antonio.espinosa&#64;tecnativa.com</a>&gt;</li>
<li>Dave Lasley &lt;<a class="reference external" href="mailto:dave&#64;laslabs.com">dave&#64;laslabs.com</a>&gt;</li>
<li>Ronald Portier &lt;<a class="reference external" href="mailto:ronald&#64;therp.nl">ronald&#64;therp.nl</a>&gt;</li>
<li>Ignacio Ibeas &lt;<a class="reference external" href="mailto:ignacio&#64;acysos.com">ignacio&#64;acysos.com</a>&gt;</li>
<li>George Daramouskas &lt;<a class="reference external" href="mailto:gdaramouskas&#64;therp.nl">gdaramouskas&#64;therp.nl</a>&gt;</li>
<li>Jan Verbeek &lt;<a class="reference external" href="mailto:jverbeek&#64;therp.nl">jverbeek&#64;therp.nl</a>&gt;</li>
</ul>
</div>
<div class="section" id="other-credits">
<h2><a class="toc-backref" href="#id9">Other credits</a></h2>
</div>
<div class="section" id="acme-implementation">
<h2><a class="toc-backref" href="#id10">ACME implementation</a></h2>
<ul class="simple">
<li><a class="reference external" href="https://github.com/certbot/certbot/tree/0.22.x/acme">https://github.com/certbot/certbot/tree/0.22.x/acme</a></li>
</ul>
</div>
<div class="section" id="icon">
<h2><a class="toc-backref" href="#id11">Icon</a></h2>
<ul class="simple">
<li><a class="reference external" href="https://helloworld.letsencrypt.org">https://helloworld.letsencrypt.org</a></li>
</ul>
</div>
<div class="section" id="maintainers">
<h2><a class="toc-backref" href="#id12">Maintainers</a></h2>
<p>This module is maintained by the OCA.</p>
<a class="reference external image-reference" href="https://odoo-community.org"><img alt="Odoo Community Association" src="https://odoo-community.org/logo.png" /></a>
<p>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.</p>
<p>This module is part of the <a class="reference external" href="https://github.com/OCA/server-tools/tree/15.0/letsencrypt">OCA/server-tools</a> project on GitHub.</p>
<p>You are welcome to contribute. To learn how please visit <a class="reference external" href="https://odoo-community.org/page/Contribute">https://odoo-community.org/page/Contribute</a>.</p>
</div>
</div>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink