Difference between revisions of "Cool Solution - Let's Encrypt"

From Univention Wiki

Jump to: navigation, search
(move to App Center)
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Version|UCS=4.2}}
 
{{Cool Solutions Disclaimer|Repository=yes}}
 
 
{{#seo:
 
{{#seo:
|title={{#replace:{{FULLPAGENAME}}|Cool Solution - |}} - {{SITENAME}}
+
|title={{#replace:{{#replace:{{#replace:{{#replace:{{FULLPAGENAME}}|'|'}}|&|&}}|"|"}}|Cool Solution - |}} - {{SITENAME}}
 
<!--|description=-->
 
<!--|description=-->
 
}}
 
}}
Follow these instructions to setup certificates issued by [https://letsencrypt.org/getting-started/ Let's Encrypt] Certificate Authority in your UCS servers. For example to enable HTTPS in you website. Or for [http://sdb.univention.de/content/15/230/en/using-your-own-ssl-certificates.html other services] offering SSL/TLS encrypted communication.
 
  
This article explains how to install a small Let's Encrypt client from our [http://wiki.univention.de/index.php?title=Category:Cool_Solutions_Repository cool solution repository] to generate and renew your TLS certificates, and how to configure different services to use them. The client uses the [https://letsencrypt.org/how-it-works/ "ACME"] protocol to negotiate with Let's encrypt servers.
+
Let's Encrypt has been moved to the Univention App Center and can be reached under https://www.univention.com/products/univention-app-center/app-catalog/letsencrypt/.
 
 
__TOC__
 
 
== Requirements ==
 
 
 
* A valid DNS A record pointing to the public IP Address of your UCS server. For example, if the goal is to issue a certificate for service1.example.com, that server should be resolvable from the Internet:
 
 
 
You need an A record pointing to a public IP Address:
 
 
 
<syntaxhighlight lang="bash" >
 
host -t A service1.example.com   
 
service1.example.com has address 1.2.3.4
 
</syntaxhighlight>
 
 
 
== Installation ==
 
 
 
Install the letsencrypt client:
 
<syntaxhighlight lang="bash">
 
univention-install univention-letsencrypt
 
</syntaxhighlight>
 
 
 
After installing the package <code>univention-letsencrypt</code> the client is ready for configuration.
 
 
 
== Configuration ==
 
 
 
The package brings new UCR variables which are read by the scripts in <code>/usr/share/univention-letsencrypt/</code>. By default, <code>letsencrypt/domains</code> is empty and <code>letsencrypt/services/*</code> are set to 'no'.
 
{| class="wikitable"
 
|-
 
!UCR Variable                              || Description                                                                                            || Example
 
|-
 
|<code>letsencrypt/services/apache2</code> || Whether the Apache2 webserver should be configured automatically or not, valid values are "Yes" or "No" ||
 
|-
 
|<code>letsencrypt/services/postfix</code> || Whether the postfix service should be configured automatically or not, valid values are "Yes" or "No"  ||
 
|-
 
|<code>letsencrypt/services/dovecot</code> || Whether the dovecot service should be configured automatically or not, valid values are "Yes" or "No"  ||
 
|-
 
|<code>letsencrypt/domains</code>          || A list of DNS names on which the server is reachable, separated by spaces                              || service1.example.com service2.example.com
 
|}
 
 
 
== Obtaining the certificate ==
 
Set the <code>letsencrypt/domains</code> before running the setup script:
 
 
 
<syntaxhighlight lang="bash">
 
ucr set letsencrypt/domains="service1.example.com"
 
</syntaxhighlight>
 
 
 
Run the setup script <code>'''/usr/share/univention-letsencrypt/setup-letsencrypt'''</code> to automatically register an account, create the needed files and start the certificate creation and validation for the domains saved in the UCR variable '''letsencrypt/domains'''. The script installs a cronjob that periodically checks if the certificates must be renewed. All actions from the script are written into a the log file <code>/var/log/univention/letsencrypt.log</code>.
 
 
 
<syntaxhighlight lang="bash">
 
/usr/share/univention-letsencrypt/setup-letsencrypt
 
</syntaxhighlight>
 
 
 
The certificate is saved in the directory <code>/etc/univention/letsencrypt</code>.
 
 
 
At the end, <code>'''setup-letsencrypt'''</code> checks the three service UCR variables and, if one is found set to "Yes", runs the needed scripts from the <code>setup.d</code> and <code>post-refresh.d</code> directories to configure the Apache2 webserver, postfix, or dovecot. Additional services can be configured by placing appropriate configuration scripts into these directories.
 
 
 
When the list of domains in '''letsencrypt/domains''' changes and <code>'''setup-letsencrypt'''</code> is run again, a prompt asks for deleting the current csr-file and recreates it with the new UCR variable's content.
 
 
 
== Certificate update ==
 
The lifetime of the certificates issued by Let's Encrypt is limited to 90 days.
 
By default, a cron job of univention-letsencrypt will update the certificate on the first day of every month at 3:30am. Services (like postfix, dovecot, apache) that have been setup via univention-letsencrypt will be restarted automatically during this process.
 
The cron interval can be adjusted via the UCR variable <code>letsencrypt/cron</code>. If unset, the value <code>30 3 1 * *</code> is used.
 
 
 
== Troubleshooting ==
 
See the certificate by opening an encrypted connection
 
<pre>openssl s_client -connect service1.example.com:443</pre>
 
 
 
See how long your certificate is valid
 
<pre>openssl s_client -connect service1.example.com:443 | openssl x509 -noout -dates</pre>
 
 
 
'''If setup-letsencrypt fails, you can try the following:'''
 
 
 
Reset Apache SSL settings via UCR
 
<pre>ucr unset apache2/ssl/certificate apache2/ssl/certificatechain apache2/ssl/key</pre>
 
 
 
Unset forced HTTPS
 
<pre>ucr unset apache2/force_https</pre>
 
 
 
Check your Apache configuration
 
<pre>apache2ctl configtest</pre>
 
 
 
Make sure your host is reachable from the internet on the hostname that is configured in the UCR variable <code>letsencrypt/domains</code>.
 
The folder that is being queried by Let's Encrypt is located at <code>/var/www/.well-known/acme-challenge/</code>
 

Latest revision as of 09:44, 11 October 2018

Let's Encrypt has been moved to the Univention App Center and can be reached under https://www.univention.com/products/univention-app-center/app-catalog/letsencrypt/.

Personal tools