Integraion with Let’s Encrypt

From ISPWiki
Jump to: navigation, search


Let’s Encrypt is a free certification authority that provides free X.509 certificated for TLS encryption. An automated process enables to facilitate creation, verification, setup and renewal of SSL certificates for protected web-sites.

For more information, please refer to the official web-site.

Let’s Encrypt provides a number of limits:

  • You can order only 5 certificates per week (TLD, including its subdomains)
  • Wildcard certificates are not supported
  • Let’s Encrypt certificate validity period is 3 months (every 3 months ISPmanager will reissue Let’s Encrypt certificates)

More information about additional limits can be found here.

This module is available in ISPmanager 5.65 and later.

In order to install a plug-in as root, navigate to Modules->Integration.

After you have installed Let’s Encrypt in ISPmanager, you can obtain a self-updated SSL-certificate for your domain. Be sure to create a user with a configured web-domain, and valid domain name available to world-wide DNS.

Once the installation is completed, in the WWW->SSL-certificates module the user will see two new buttons - Let's Encrypt and Let’s Encrypt Log. Clicking the first button will start the process of certificate issue.

The second function will be activated, if you already have the Let's Encrypt certificate in the list of SSL-certificates, and will redirect you to the Event log.

Letsencrypt toolbaren.png

Certificate creation

There are two ways to obtain an Let's Encrypt certificate:

  • Navigate to WWW->SSL-certificates.

Click the Let's Encrypt button, and fill out the form.


Select a user (if your create an SSL as root) and domain.

Enter required data (country id, city, email, etc.) the length of the private key for your certificate.

  • When creating a WWW-domain

When creating a WWW-domain, select the Secure connection (SSL). Let's Encrypt certificate option will be added into the creation form. After you have provided all required information, you will be redirected to the Let's Encrypt certificate creation form.

Certificate update

Let’s Encrypt certificates are updated every day at 1:30 a.m. The update procedure starts 7 (or less days) before the certificate's expiration date.

You can also start the update process manually with the letsencrypt.check.update function. Call the function via the mgrctl utility with the following parameters:

force_update=yes, cert_name=%cert name%, user_name=%user name%

Attention! The number of certificates per domain is limited, that's why do not update your certificates manually too often.

Certificate issue

First, a self-signed certificate is created with provided parameters. Once in 5 minutes, the system is trying to obtain a certificate.

Errors, if any, are logged into the Error log. The second attempt to obtain the certificate will be made in 5 minutes.

You can start the letsencrypt.periodic command via the mgrctl utility.

If the certificate cannot be obtained withing 24 hours, the corresponding notification is created for the user and administrators, and no other attempts are made.

If the certificate is successfully obtained, the self-signed certificate is changed into Let's Encrypt. The user and administrators get notification that the certificate has been successfully issued.

Order of requests:

  • Account creation
  • Authentication
  • Request for domain ownership (in order to verify domain ownership, a new token is added. This is a file with data that were received after authentication, Path to the file .well-known/acme-challenge/%token_name%)
  • Waiting for successful validation
  • Certificate issue
 Note: Starting from ISPmanager 5.84.0 the domain verification procedure was changed. A separate alias .well-known/acme-challenge/ is now created for every   domain
 pointing to the  /usr/local/mgr5/www/letsencrypt directory. All verification tokens will be created there.