Contents
Overview
Let’s Encrypt is an open and automated certificate authority that uses the ACME (Automatic Certificate Management Environment) protocol to provide free TLS/SSL certificates to any compatible client. These certificates can be used to encrypt communication between the web servers and users.
This tutorial will briefly discuss certificate authorities and how Zevenet integration works with Let’s Encrypt, then review how Zevenet uses the certbot (ACME client) in order to make the communication with Let’s encrypt infrastructure.
Zevenet Load Balancer 6.0.3 or higher version includes a tiny certbot wrapper called letsencryptz in order to use the Certbot webroot functionality, the following lines explain how this wrapper works, please take all of this into consideration in order to make it work in production environments.
How does Let’s encrypt validation work?
As a brief webroot functionality description, the webroot plugin works by creating a temporary file for each of your requested domains in the Zevenet file path /usr/local/zevenet/app/letsencryptz/webroot/.well-known/acme-challenge/. Then the Let’s Encrypt validation server makes HTTP requests to validate that the DNS for each requested domain resolves to the server running letsencryptz wrapper and the temporary file for validation purposes is accessible, the following diagram describes a real example:
In the previous diagram, Zevenet Load balancer is behind a Router / Firewall with a public IP address 185.79.20.147 (as an example), the HTTP and HTTPS traffic is natted to internal load balancer with VIP 192.168.101.31 (as an example), where the load balancer is configured with 2 different farms:
HTTPS Farm Name WebHosting via 192.168.101.31:443. This farm is responsible for offering web hosting, different web servers are published along with this to the Internet. For example, test1.zevenet.es, test2.zevenet.es, test3.zevenet.es are testing web pages published on this virtual service among others.
HTTP Farm Name WebhostingRedirect via 192.168.101.31:80. This farm is only used for redirect purposes, it forces all the traffic from HTTP to HTTPS.
The previous diagram describes an SSL Let’s Encrypt Certificate request for the domain test1.zevenet.es as follows:
1. A certificate request is sent from the load balancer itself to the Let’s Encrypt infrastructure.
2. Let’s encrypt detects the new SSL Certificate Request for test1.zevenet.es
3. Let’s encrypt run a DNS IP resolution for the requested host: test1.zevenet.es checking that the result is the public IP, the same origin IP that initiated the request.
4. At this point Let’s encrypt announces to letsencryptz script (webroot cerbot) that it needs to create a file with a HASH in the public path http://test1.zevenet.es/.well-know/acme-challenge/ (80 TCP Port), local Directory /usr/local/zevenet/app/letsencryptz/webroot/.well-known/acme-challenge/. Then, letsencryptz configures a temporal service in order to make this file accessible from the Internet (the farm WebhostingRedirect is going to be modified for this purpose. If there is not farm already configured letsencryptz will create a temporal one in this VIP and Port).
6. As soon as letsencryptz confirms the temporary service creation, Lets Encrypt servers verify that the temporal validation file has been created and the HASH content is correct.
7. Finally, Let’s Encrypt servers reply to the first request with the already created certificate for the Common Name (CN) test1.zevenet.es.
8. Zevenet will store the already created certificate in the local path /usr/local/zevenet/config/ and it is ready to be configured in the farm WebHosting.
At this stage, the new Let’s Encrypt certificate would be used for the HTTPS virtual service.
Let’s Encrypt Automation Commands
As described, the letsencryptz script will automate the required actions to manage your SSL certificates like create, renew, destroy or list, among others. Find below the available commands.
root@zva6k:~# letsencryptz
letsencryptz description:
letsencryptz is a let's encrypt (certbot) wrapper with minimal parameters ready to manage Let's Encrypt certificates for ZEVENET https profiles. Take into account that this wrapper uses certbot webroot feature so the public Let's encrypt architecture requires to connect with a local Virtual IP and port (TCP 80 by default) in order to do a request validation for the requested domain, so as soon as the "obtain" param is used, this script will configure an HTTP farm which will be accessed by Let's encrypt for verification purpose, this configuration is done automatically by this script itself, only ensure that the used Virtual IP and HTTP port 80 is not used by any another load balanced farm, and also ensure that the DNS resolution for the requested domain is reachable from let's encrypt system.
usage:
/usr/local/zevenet/bin/letsencryptz <action> <commands>
action: --obtain | --destroy | --renew | --list | --listconf | --help
--obtain: Request new Certificates using webroot cert-bot module.
commands: --vip <Virtual IP> --farm <Farm Name> --domain <domain1> --domain <domain2> --domain <domainN> --test
--vip: The Virtual IP already configured were to publish a temporal web server, this will be connected by let's encrypt public servers to verify the certificate request. The Virtual IP has to be free on the 80 port in order to be bound by a local process, if it isn't free then use --farm instead.
--farm: The farm name which configures a temporal Service called "letsencryptz", if no farm is used a temporal farm called "letsencryptZevenet" will be configured in the selected Virtual IP.
--domain: The domain which requests the Certificate for, i.e. www.mycompany.com.
--test: Optional parameter, if used the certificate is requested for test purpose.
--destroy: Revoke and delete the indicated Certificate Name, the action is rejected if the given certificate is in use by a farm.
commands: --certname <Certificate Name>
--certname: Certificate Name, this value can be obtained from the action --list.
--renew: Renew the certificates near to expiry, no commands needed
commands: --test --forcerestart --vip <Virtual IP> --farm <Farm Name>
--test: Optional parameter, if used a dry-run is executed, the renew of the certificates is simulated.
--forcerestart: Optional parameter, if used the farms that are using the renewed certificates will be restarted in order to apply the changes.
--vip: The Virtual IP already configured where to publish a temporal web server, this will be connected by let's encrypt public servers to verify the certificate renew. The Virtual IP has to be free on the 80 port in order to be bound by a local process, if it isn't free then use --farm instead.
--farm: The farm name which configures a temporal Service called "letsencryptz", if no farm is used a temporal farm called "letsencryptZevenet" will be configured in the selected Virtual IP.
--list: List all the local certificates managed by let's encrypt and the status, no commands needed.
--listconf: List the Zevenet let's encrypt configuration module (check global.conf file), no commands needed.
--help: Obtain this help.
It will take some time the first time that letsencryptz is executed because the system is going to install unresolved dependencies automatically, also a configuration review is done before to start to use it, Let’s Encrypt requests an email account or contact purposes related with the certificates, this email account will be used along any action done against Let’s Encrypt system, this email can be configured in the main configuration file /usr/local/zevenet/config/global.conf, directive $le_email.
Some usage examples are shown below.
Zevenet Let’s Encrypt certificate creation
This command requests a new certificate for the domain test2.zevenet.es. Take into account that the given VIP will be the internal one, which traffic should be natted from the public IP to the internal one. If Let’s Encrypt is not able to reach this service, the request will be denied.
root@zva6k:~# letsencryptz --obtain --vip 192.168.101.31 --domain test2.zevenet.es WARNING: No farm name specified, a temporal farm with name letsencryptZevenet will be created in VIP 192.168.101.31 port 80. Configuring farm for let's encrypt Certificate Name verification Obtaining Certificate for domains test2.zevenet.es... Saving debug log to /var/log/letsencrypt/letsencrypt.log Plugins selected: Authenticator webroot, Installer None Obtaining a new certificate Non-standard path(s), might not work with crontab installed by your operating system package manager Certificate Request for the domain(s) test2.zevenet.es OK Created Certificate name test2.zevenet.es in PEM format ready for HTTPS profile Destroying webroot configuration for the farm letsencryptZevenet Deleting already configuration for letsencryptZevenet, service letsencryptz Restarting farms using renewed certificates:
Zevenet Let’s Encrypt certificates listing
The execution of this command will show the current certificates managed by Zevenet Let’s Encrypt system.
root@zva6k:~# letsencryptz --list Listing all available certificates for the current configuration in config dir /usr/local/zevenet/config/letsencrypt/ Saving debug log to /var/log/letsencrypt/letsencrypt.log Certificate Name: test1.zevenet.es Domain(s): test1.zevenet.es Expiry Date: 2019-09-19 10:48:02+00:00 (VALID: 77 days) Pem Certificate file: /usr/local/zevenet/config/test1_zevenet_es.pem Certificate Name: test3.zevenet.es Domain(s): test3.zevenet.es Expiry Date: 2019-09-26 06:32:52+00:00 (VALID: 83 days) Pem Certificate file: /usr/local/zevenet/config/test3_zevenet_es.pem
Take into consideration the Field Certificate Name, this field will be recognized by the letsencryptz wrapper as –certname.
Zevenet Let’s Encrypt certificate renewal
The previous command checks if any already generated certificate requires a renewal, in which case the renewal will be done automatically. Take into consideration that if the renewed certificated is in use a farm restart will be required in order to apply the change, please use the option –forcerestart if you want letsencryptz restarts all the required farms to apply the changes.
root@zva6k:~# letsencryptz --renew --vip 192.168.101.31 Renewing all the required certificates Saving debug log to /var/log/letsencrypt/letsencrypt.log Cert not yet due for renewal Cert not yet due for renewal
Zevenet Let’s Encrypt certificate deletion
This command revokes and deletes the given certificate. In case that the system detects that the selected certificate is currently in use by any HTTPS farm, the action will be rejected, in the example above the delete action is rejected because the certificate is in use by the farm testhttps.
root@zva6k:~# letsencryptz --destroy --certname test3.zevenet.es Revoking and deleting certificate(s) test3.zevenet.es for the current configuration... This file can't be deleted because is used by the farm(s): testhttps
As soon as the certificate is unassigned from the farm, the action will be done:
root@zva6k:~# letsencryptz --destroy --certname test3.zevenet.es Revoking and deleting certificate(s) test3.zevenet.es for the current configuration... Saving debug log to /var/log/letsencrypt/letsencrypt.log Deleted certificate(s) test3.zevenet.es in path /usr/local/zevenet/config/test3_zevenet_es.pem
Migrate Let’s Encrypt Certificates to Zevenet
Zevenet Load balancer saves all the configuration files of certbot in the local path /usr/local/zevenet/config/letsencrypt/. In order to move your existing certbot configuration files (by default in /etc/letsencrypt) of another Server to Zevenet, you only have to make a tarball (tar.gz file) of this existing configuration directory in your server and uncompress the content in the Zevenet Let’s Encrypt configuration path. Finally, consider modifying the variable $le_email in the file global.conf to the same email used in the previous requests.
Let’s Encrypt Certificates Clustering support
Zevenet Let’s Encrypt plugin is totally supported with Zevenet Cluster service. All the Let’s Encrypt actions are saved in a configuration file replicated by the Zevenet Cluster Service, so any action executed in the MASTER node will be replicated to the SLAVE node automatically, but any action executed in the SLAVE node related with Let’s Encrypt will be discarded in order to avoid any desynchronization.
Let’s Encrypt certificates automatic renew
Zevenet Let’s Encrypt plugin can be configured in order to check daily if some certificate needs a renew, in case that the system renews automatically a given certificate and it is in use by some farm, then the farm will be restarted automatically in order to apply the certificate change.
In order to configure the automatic renew please do the following:
Create the following cron file /etc/cron.d/letsencryptz with the following content:
root@zva6k:~# cat /etc/cron.d/letsencryptz 00 00 * * * root /usr/local/zevenet/bin/letsencryptz --renew --forcerestart --vip 192.168.101.31
With this configuration, the renew check will be executed daily at 00:00 (midnight). And the VIP 192.168.101.31 will be used in the port 80 for verification purpose from Let’s Encrypt System.
References
Some references used in this article are: