Installing an SSL certificate from Let's Encrypt

Introduction

Let's Encrypt is a non-profit certification authority that provides free X.509 certificates for TLS encryption through an automated process designed to replace the current complex process of manually creating, verifying, signing, installing, and updating certificates for secure websites.

Official website: Let's Encrypt.

You can start working with Let's Encrypt certificates immediately after installing the control panel.

Please note that Let's Encrypt has the following limitations (see the limitations documentation for details):

• Only 50 certificates can be ordered per week (TLD, including its subdomains);
• The validity period of a Let's Encrypt certificate is 3 months (every 3 months, ispmanager reissues Let's Encrypt certificates).

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

To do this, you will need a user with SSL privileges and a valid domain name that is accessible to global DNS.

In the SSL Certificates section, there are buttons for Let's Encrypt and Let's Encrypt Log. Clicking on the first button will start the certificate acquisition process.

The second button is activated if you already have a Let's Encrypt certificate in your certificate list and redirects you to the event log, which displays everything that happens with it.

Before creating a certificate, make sure that Let's Encrypt certificate issuance is allowed:

1. In the Main menu, select Users.
2. In the form that opens, select the user and click the Permissions button.
3. Select SSL Certificates in the form that opens and click the Restrict Features button on the toolbar or in the context menu.
4. In the form that opens, select Let's Encrypt and Log and click Enable.

Creating a certificate

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

• from the SSL Certificates section: click the Let's Encrypt button and fill in the details for issuing the certificate in the window that appears.
• together with a new site: when creating a new site, after clicking the Create button, the Let's Encrypt form will open, where you need to click Issue.

Certificate update

The need to update your certificates issued by Let's Encrypt will be checked every day at 1:30 a.m. server time.

Automatic certificate update

The certificate will be reissued in accordance with the value of the LetsencryptStartUpdatePeriod parameter, which is set to 29 days by default.

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

Manual certificate update

You can also start the certificate update manually. To do this, use the letsencrypt.check.update function. If you want to start the update early, you need to call this function via the mgrctl utility:

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

Please note!

The number of certificates for a domain within a short period of time is limited, so do not abuse manual updates.

When updating a certificate with DNS verification, TXT records will be regenerated. If an external DNS server is used, the records will not be added automatically and the certificate will not be able to update.

Certificate acquisition technology

First, a self-signed certificate with the specified parameters is created, then an attempt to obtain a certificate is made once per minute. You can set the maximum number of certificate requests that the control panel will send at the same time. To do this, change the LetsencryptProcessCount parameter in the ispmanager configuration file. By default, this parameter is set to 1.

If errors occur, they are logged. A retry is performed every minute. Requests for new certificates have a higher priority than retries for old ones.

You can manually run letsencrypt.periodic via the mgrctl utility.

If the certificate cannot be obtained within twenty-four hours, attempts are stopped and notifications are sent to the user and administrators with a message about the failure to obtain the certificate.

If the certificate is obtained successfully, the self-signed certificate is replaced with a Let's Encrypt certificate. The user and administrator receive notifications about the successful completion of the retrieval.

Request procedure

• Create an account;
• Authorization
• Request for domain ownership verification (to verify domain ownership, a token is added to the user's server — a file containing data obtained during authentication. There is a global dependency .well-known/acme-challenge/ on the server, leading to the directory /usr/local/mgr5/www/letsencrypt. All verification tokens will be created in this path);
• Waiting for confirmation of successful verification;
• Obtaining a certificate.

DNS verification

We add the ability to verify domain ownership via TXT records in the domain zone. To obtain a certificate with DNS verification, when ordering a certificate, check the Verify via DNS checkbox.

The necessary TXT records will be automatically added to the Domain Records Management form. To view:

1. In the Main Menu, select DNS Management.
2. On the form that opens, select the site and click the DNS Records button.

Please note!

If you are using an external DNS server, the issuance process will be frozen for 30 minutes, and a notification will be displayed in the interface in the left corner near the global search and in the Notifications section (in Monitoring and Logs) with information about which records need to be entered on the external server to receive certificates. The global network is checked for records every 30 minutes for 24 hours after the first notification is received. Once the necessary records are available, the certificates will be successfully obtained.

If the domain ownership check is unsuccessful within 24 hours after the certificate is ordered, attempts to issue the certificate will be stopped.

Mail domains

To obtain a certificate for a mail domain when creating/editing a mail domain, select New Let's Encrypt certificate. Next, enter the aliases that the selected domain uses for mail (pop.your_domain.com, mail.your_domain.com, smtp.your_domain.com, etc.). If there is no web domain with the same name in the panel, the verification procedure will be forced through DNS.

Wildcard support

ispmanager supports wildcard certificates. To obtain such a certificate, select the Wildcard checkbox on the order form.

Please note

Domain ownership verification when issuing a wildcard certificate is performed exclusively via DNS. A manually specified alias of the form *.domain.name will be ignored when ordering to avoid possible conflicts during verification.

Non-standard situations

If an error is detected during domain verification due to incorrect file access rights, inability to create a token, or closed access to the domain, we recommend using an alternative method of certificate issuance based on DNS records.

1. Use DNS verification.
2. After several failed attempts, the ACME server will successfully find suitable addresses for HTTP verification by trial and error.

Log

The log of ispmanager's interaction with Let's Encrypt is recorded in the file /usr/local/mgr5/var/letsencrypt.log.

By default, the logging level is set too low, and information is not recorded in the file. To enable logging:

1. In the Main menu, select Monitoring and logs.
2. In the list that opens, select Logging settings.
3. Select the sslcert, rpc, core_modules modules and click the Maximum button.