Ispmanager 6 business documentation

/
/
/
Integration with Let’s Encrypt

Integration with 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. Working with Let's Encrypt certificates is possible immediately after installing the control panel. 

Please pay attention, Let’s Encrypt has a number of limits (for more details, check additional limits):

  • You can order only 50 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 names should be subdomains of the certificate domain. 

In ispmanager, you can get a valid self-renewing SSL certificate for your domain.

To do this, you will need a user who has the right to use SSL, and a valid domain name available to the world DNS.

There are two buttons in SSL-certificates (Web-server settings)— Let's Encrypt and Let’s Encrypt Log. Clicking the first button will start the process of the 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.

Before generating a certificate, make sure that the Let's Encrypt function is enabled:

  • Via "Access to functions":
    1. In the Main menu, choose Settings.
    2. In the drop-down menu, select Access to functions.
    3. Choose the group of users and click Perm. (permissions).
    4. In the form User group privileges, double-click on SSL-certificates.
    5. Mark Let's Encrypt and Let's Encrypt log checkboxes and click Enable.
  • In user permission settings:
    1. In the Main menu choose Accounts.
    2. In the drop-down menu, select Users.
    3. Select user and click Perm.
    4. On User permissions form, double-click on SSL-certificates.
    5. Mark Let's Encrypt and Let's Encrypt Log checkboxes and click Enable.

Add a certificate 

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

  • Navigate to Web-server settings → SSL-certificates. Click the Let's Encrypt button, and fill out the form.
  • On the WWW-domain creation form, select the Secure connection (SSL). Let's Encrypt certificate option will be added to the creation form. Specify the required parameters. Next, you will be redirected to the Let's Encrypt certificate creation form.

Certificate update

Every day at 1:30 a.m server time, the system checks which certificates need to be updated.

Certificate auto-renewal

The certificate will be reissued according to the set value of the LetsencryptStartUpdatePeriod parameter (default value is 29 days).

Recommended values are from 7 to 29. It is not recommended to specify values less than 7 and more than 29, as well as negative values and letters.

Manual certificate update

You can also start the update process manually with the letsencrypt.check.update function. If you want to force the update, 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%
Attention! The number of certificates that can be issued for a domain is limited, that's why, do not update your certificates manually too often.

When updating the 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 with the specified parameters is created, then, once in a minute, an attempt is made to obtain a certificate. You can set the maximum number of certificate requests that the control panel will send simultaneously. To do this, change the LetsencryptProcessCount parameter in the ISPmanager configuration file. The default value for this parameter is 1.

If errors occur, they are logged. Retrying to receive is performed every minute. Requests for new certificates take precedence over retrying old ones.

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

If the certificate cannot be obtained within 24 hours, the corresponding notification will be created for the user and administrators. No more attempts will be made.

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

Order of requests:

  • Account creation
  • Authentication
  • Request for domain ownership verification (to verify domain ownership, a token file containing the data obtained during authentication is added to the user's server. This is a file with data that were received after authentication.) There is a global .well-known/acme-challenge/ dependency on the server leading to the /usr/local/mgr5/www/letsencrypt directory. 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.

The necessary TXT-records will be added automatically. To view:

  1. In the Main menu, choose Domains.
  2. In the drop-down menu, select Domain names.
  3. In the form that opens, choose your domain and click Manage DNS records.
Note.
If you use an external DNS server, the process will be suspended for 30 minutes. In the left corner of the panel interface next to the global search field and in the Notifications section (in System status), you will see a notification saying what records you need to add to the external server to receive the certificates.The system will check the records on the Internet every 30 minutes during 24 hours after you have received the first notification. When the required records are available, the certificates will be issued. 

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

Mail domains

To get a certificate for a mail domain, when creating/editing a mail domain, select Secure connection(SSL) - New Let's Encrypt certificate.

Next, enter the aliases that the selected domain uses for mail operation (pop.your_domain.com, mail.your_domain.com, smtp.your_domain.com or others).

If the web-domain with the same name is not created in the control panel, the verification procedure will be run via DNS.

Wildcard certificates

ISPmanager supports Wildcard SSL certificates. To receive a Wildcard SSL-certificate, check the Wildcard box on the order form.

Note!
The domain verification procedure for wildcard-certificates 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. Use DNS verification.
  2. Just wait. After several failures, the ACME server will find the right address for the HTTP verification.

Logs

The log file of ispmanager and Let’s Encrypt interaction is located in /usr/local/mgr5/var/letsencrypt.log. 

The default logging level is not enough for receiving all the information an administrator may need to solve possible issues. To enable logging:

  1. In the Main menu, choose Settings.
  2. In the drop-down list, select Logging settings.
  3. Select sslcert, rpc, and core modules and click Maximum.

 

In this article