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

From Univention Wiki

Jump to: navigation, search
(move to App Center)
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Version|UCS=4.2}}
 
{{Cool Solutions Disclaimer|Repository=yes}}
 
 
{{#seo:
 
{{#seo:
 
|title={{#replace:{{#replace:{{#replace:{{#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>
 
 
 
=== Verification fails in AWS or NAT environments ===
 
 
 
In certain scenarios, which incorporate NAT, or cloud environments like AWS, the internal domain verification of the App might fail, despite the DNS being configured correctly and Let's Encrypt being able to issue a certificate for the server.
 
In these cases, adding a manual DNS entry on the system running the Let's Encrypt App can help:
 
 
 
<pre>ucr set hosts/static/<EXTERNAL-IPADDRESS>=<LETS-ENCRYPT-HOSTNAME></pre>
 
 
 
== Migrating to the Let's Encrypt App ==
 
 
 
This cool solution has been released as an app for the Univention App Center.
 
To migrate to the Let's Encrypt app, simply uninstall the Cool Solution package and unset the UCR variables associated with it. Existing host or domain keys below <code>/etc/univention/letsencrypt/</code> won't be removed and will be used by the app later.
 
 
 
<pre>ucr unset letsencrypt/domains letsencrypt/services/apache2 letsencrypt/services/postfix letsencrypt/services/dovecot</pre>
 
 
 
<pre>univention-remove univention-letsencrypt</pre>
 
 
 
After that, install the app from the App Center in the UMC on your server and configure it, as explained in the readme that's being displayed after installation.
 

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