ISPmanager Lite Documentation

Integration with Let’s Encrypt

How to install an SSL by Let's Encrypt

Introduction


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

The official website.  Let's Encrypt integration page on ISPsystem's website 

Let’s Encrypt provides a number of limits:

  • You can order only 5 certificates per week (TLD, including its subdomains);
  • Let’s Encrypt certificate validity period is 3 months (every 3 months ISPmanager will reissue Let’s Encrypt certificates);
  • All alternative name should be subdomains of the certificate domain. 

More information about additional limits can be found here.

This module is available in ISPmanager 5.131 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.

Add a certificate 


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

  • Navigate to WWW → SSL-certificates. Click the Let's Encrypt button, and fill out the form.
  • 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.

Update the certificate


Every day at 1:30 a.m the system checks what certificates should be updated. The update procedure starts 7 (or fewer 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:

/usr/local/mgr5/sbin/mgrctl -m ispmgr letsencrypt.check.update force_update=yes cert_name=%cert name% user_name=%user name%

Note.

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

When updating a certificate with DNS-verification, new TXT-records will be generated. If the external DNS-server is used, the records won't be added automatically, and the certificate won't be updated. 

Certificate issue procedure 


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 within 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 a 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.  The global alias .well-known/acme-challenge/ on the server leads to the directory /usr/local/mgr5/www/letsencrypt. All verification tokens will be created there.
  • Waiting for successful validation
  • Certificate issue

DNS validation


Let's Encrypt supports DNS-based validation that requires specific TXT records to be inserted into the DNS zone for a domain. Select the DNS validation checkbox when you order a new SSL-certificate.

TXT-records will be automatically added to Domains → Domain names → Records. 

Note.

If the external DNS is used, the process will be suspended for 30 minutes and the warning will be displayed in the panel interface. During that time you need to synchronize the domain resource records on the DNS-server with the records in Domains → Domain names → Records.

If domain validation processes cannot be completed successfully during 24 hours since you ordered a certificate, the system will stop trying to issue the certificate.

Mail domains


Let's Encrypt can be issued for mail domains. Navigate to Mail domains → click Add or Edit → select New Let's Encrypt. The certificate will be also ordered for aliases mail.domain.name, smtp.domain.name, pop.domain.name. If the web-domain with the same name is not created in the control panel, the verification procedure will run via DNS.

Wildcard certificates


Starting from version 5.147.0 ISPmanager supports wildcard SSL certificates. To receive a Wildcard SSL-certificate check the Wildcard box on the order form.

Note.

Domain verification procedure is performed only via DNS.

An alias such as *.domain.name specified manually will be ignored during the order to avoid verification conflicts.

Non-standard situations


Sometimes it may happen that a web-domain is resolved to several cluster nodes. If one of the cluster nodes doesn't have a web-role it cannot pass the HTTP verification. How to solve the issue:

  1. Pass the DNS verification. 
  2. Just wait. After several failures, the  ACME server will find the right address for the HTTP verification. 

Logs


The log file is /usr/local/mgr5/var/ispmgr.log

By default, the logging level is not enough to get all information an administrator may need to solve issues. Complete the following steps:

  1. Go to Settings Logging settings 
  2. Press Ctrl and select ssl, rpc, core_modules.
  3. Click on Maximum