Difference between revisions of "Cool Solution - Let's Encrypt"
From Univention Wiki
(validate UCS 4.2 - add short intro) |
|||
Line 1: | Line 1: | ||
− | {{Version|UCS=4. | + | {{Version|UCS=4.2}} |
{{Cool Solutions Disclaimer|Repository=yes}} | {{Cool Solutions Disclaimer|Repository=yes}} | ||
− | This article explains how to install a small Let's Encrypt client | + | 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. | ||
__TOC__ | __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 == | == Installation == | ||
− | + | ||
− | <syntaxhighlight lang="bash | + | Install the letsencrypt client: |
+ | <syntaxhighlight lang="bash"> | ||
univention-install univention-letsencrypt | univention-install univention-letsencrypt | ||
</syntaxhighlight> | </syntaxhighlight> | ||
+ | |||
+ | After installing the package <code>univention-letsencrypt</code> the client is ready for configuration. | ||
== Configuration == | == Configuration == | ||
− | The package brings | + | |
+ | 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" | {| class="wikitable" | ||
|- | |- | ||
Line 27: | Line 44: | ||
== Obtaining the certificate == | == Obtaining the certificate == | ||
− | Run the 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>. | + | 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>. | The certificate is saved in the directory <code>/etc/univention/letsencrypt</code>. |
Revision as of 10:58, 22 June 2017
Note: Cool Solutions are articles documenting additional functionality based on Univention products. Packages provided by a Cool Solutions Repository are built by Univention, but will not be maintained.
Not all of the shown steps in the article are covered by Univention Support. For questions about your support coverage contact your contact person at Univention before you want to implement one of the shown steps.
Follow these instructions to setup certificates issued by Let's Encrypt Certificate Authority in your UCS servers. For example to enable HTTPS in you website. Or for other services offering SSL/TLS encrypted communication.
This article explains how to install a small Let's Encrypt client from our cool solution repository to generate and renew your TLS certificates, and how to configure different services to use them. The client uses the "ACME" protocol to negotiate with Let's encrypt servers.
Contents
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:
host -t A service1.example.com
service1.example.com has address 1.2.3.4
Installation
Install the letsencrypt client:
univention-install univention-letsencrypt
After installing the package univention-letsencrypt
the client is ready for configuration.
Configuration
The package brings new UCR variables which are read by the scripts in /usr/share/univention-letsencrypt/
. By default, letsencrypt/domains
is empty and letsencrypt/services/*
are set to 'no'.
UCR Variable | Description | Example |
---|---|---|
letsencrypt/services/apache2 |
Whether the Apache2 webserver should be configured automatically or not, valid values are "Yes" or "No" | |
letsencrypt/services/postfix |
Whether the postfix service should be configured automatically or not, valid values are "Yes" or "No" | |
letsencrypt/services/dovecot |
Whether the dovecot service should be configured automatically or not, valid values are "Yes" or "No" | |
letsencrypt/domains |
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 letsencrypt/domains
before running the setup script:
ucr set letsencrypt/domains="service1.example.com"
Run the setup script /usr/share/univention-letsencrypt/setup-letsencrypt
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 /var/log/univention/letsencrypt.log
.
/usr/share/univention-letsencrypt/setup-letsencrypt
The certificate is saved in the directory /etc/univention/letsencrypt
.
At the end, setup-letsencrypt
checks the three service UCR variables and, if one is found set to "Yes", runs the needed scripts from the setup.d
and post-refresh.d
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 setup-letsencrypt
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 letsencrypt/cron
. If unset, the value 30 3 1 * *
is used.