Ispmanager 6 lite, pro, host

/
/
/
Let’s Encrypt certificates

Let’s Encrypt certificates

Let’s Encrypt is a certificate authority that provides free SSL/TLS certificates.

The ispmanager Let’s Encrypt module automates the request, verification, issuance, installation, and renewal of certificates.

This article describes the process of issuing a certificate for the main domain. For more information on issuing a certificate for the mail server and mail domain, please see the SSL certificates for mail article.

Let’s Encrypt rate limits

  • It is possible to issue up to 50 certificates per week per domain
  • Let’s Encrypt certificates are valid for 3 months
  • Let’s Encrypt only issues domain validated (DV) certificates

For more information on rate limits, please see the official Let's Encrypt documentation.

Let’s Encrypt requirements

To issue a certificate, the user must have:

Issuing a Let’s Encrypt certificate

  1. A certificate issue request is generated in ispmanager and sent to Let’s Encrypt.
  2. Let’s Encrypt verifies that the certificate requester owns or has control over the domain.
  3. Let’s Encrypt issues a certificate.
  4. Ispmanager installs the certificate on the site.

Requesting a certificate

There are two ways to request a Let's Encrypt certificate: when creating/editing a site or from the SSL certificates section.

  1. Log in to ispmanager.
  2. Navigate to the Sites section.
  3. Click Create a site or select an existing one and click Edit.
  4. In the SSL certificate field, select the New free from Let's Encrypt option.
  5. Check the Redirect HTTP-requests to HTTPS box so that all requests to the site are made over a secure connection.
  6. Save the changes. In the form that opens, fill in the following fields:

    • Wildcard SSL certificate (optional) — check the box so that the certificate applies to the current domain and all its first-level subdomains

      When issuing a Wildcard certificate, domain ownership validation is mandatorily performed via DNS.

    • DNS validation (optional) — check the box to verify domain ownership via DNS (if DNS validation is not checked, HTTP validation is used)
    • Domain name — specify all domain names the certificate will be issued for (you can specify alternative names for the current domain or up to 99 additional domain names)
    • Mailbox — email of the certificate owner
    • Key length — 2048 or 4096 bits
  7. Click Issue.
  8. If DNS validation was selected for the certificate, and you are using an external NS server as your name server, add the TXT records for validation to the domain DNS zone.

Once issued, the certificate is activated for the site automatically.

  1. Log in to ispmanager.
  2. Navigate to the SSL certificates section.
  3. Hover over the Add certificate button and select the Let’s Encrypt option from the drop-down menu.
  4. In the form that opens, fill in the fields:
    • Enable SSL certificate — check the box to automatically activate the certificate for the site (available if a site with the specified domain name has been created in the panel)
    • Enable SSL certificate for a mail domain — check the box to automatically activate the certificate for the mail domain of the same name (available if a mail domain with the specified domain name has been created in the panel)

    • Wildcard SSL certificate (optional) — check the box so that the certificate applies to all subdomains of the current domain

      When issuing a Wildcard certificate, domain ownership validation is mandatorily performed via DNS.

    • DNS validation (optional) — check the box to verify domain ownership via DNS (if DNS validation is not checked, HTTP validation is used)
    • Username — select the user who owns the domain (available when issuing a certificate as a reseller-level account or above)
    • SSL certificate name — leave unchanged or specify your own
    • Domain — select the primary domain the certificate will be issued for
    • Domain name — specify all domain names the certificate will be issued for (you can specify alternative names for the current domain or up to 99 additional domain names)
    • Mailbox — email of the certificate owner
    • Key length — 2048 or 4096 bits
  5. Click Issue.
  6. If DNS validation was selected for the certificate, and you are using an external NS server as your name server, add the TXT records for validation to the domain DNS zone.

If you checked the Enable SSL certificate box in the certificate settings, the certificate will be activated for the site automatically. Otherwise, enable it manually.

The certificate issue status can be tracked in the log. Notifications about successful issue or errors will appear in the log and in the Notifications section in the upper right corner of the ispmanager interface.

Domain ownership validation

To issue a certificate, Let’s Encrypt must verify that you own the domain you are requesting a certificate for. One of two types of challenges is used for verification: HTTP-01 or DNS-01.

HTTP challenge is used by default if a site with the domain name has been created in the panel.

Let's Encrypt generates a random string (token) and sends it to ispmanager. The token file is automatically added to your site at /usr/local/mgr5/www/letsencrypt and becomes available at http://DOMAIN_NAME/.well-known/acme-challenge/TOKEN_FILE. Let's Encrypt checks the file's availability and its contents via HTTP. If the verification is successful, a certificate is issued.

The token file must be accessible via URL without redirects or restrictions.

If an error occurs when obtaining a certificate due to incorrect file permissions, inability to create a token, or restricted access:

  • use DNS validation
  • wait until the Let’s Encrypt server finds suitable IP addresses for HTTP verification (if the site has multiple IP addresses) or
  • fix the errors and wait for Let’s Encrypt to repeat the verification

To repeat the validation immediately, go to the Log on the toolbar and click Restart.

DNS challenge is used mandatorily:

  • when a Wildcard certificate is issued
  • when there is no site with the domain name in the panel
  • when a certificate is issued for a mail domain

Let's Encrypt generates TXT records and sends them to ispmanager. The records are placed in the domain's DNS zone, after which ispmanager and Let's Encrypt check their availability. If the verification is successful, a certificate is issued.

If ispmanager is used as a name server, TXT records will be added to the domain's DNS zone and replicated to slave servers (if any) automatically. To view the TXT records:

  1. Go to the DNS management section.
  2. In the form that opens, select a site and click the DNS records button — TXT records with the _acme-challenge.YOUR_DOMAIN names should be displayed. After the certificate is successfully issued, the TXT records are deleted.

If external DNS servers are used, the first attempt to issue a certificate will fail. In this case, TXT records for each specified domain must be added manually in your domain name registrar account.

How to add TXT records in your domain name registrar account
  1. Log in to your domain name registrar account.
  2. Go to the DNS zone resource records and add a TXT record:
    • Specify the subdomain _acme-challenge.YOUR_DOMAIN
    • Copy the TXT record from the notification in ispmanager by clicking the icon :
      • next to the certificate in the SSL certificates section
      • under the Log button on the toolbar in the SSL certificates section or
      • next to a site in the Sites section
  3. If alternative names or additional domains are specified for the domain, add TXT records for them as well.

To repeat the validation immediately after adding TXT records, go to the Log on the toolbar and click Restart.

Enabling a Let’s Encrypt certificate

  1. Navigate to the Sites section.
  2. Select the site you wish to enable the certificate for.
  3. In the SSL certificate field select a certificate from the list.
  4. Save the changes.

To make sure that the certificate was successfully activated for the site, open the site in the browser — a lock sign should appear to the left of the address bar.

Let’s Encrypt event log

To view the event log for requested and valid Let's Encrypt certificates, click Log on the toolbar in the SSL certificates section. You can view the full log or just the log for the most recent certificate issuance attempt.

Entries older than 180 days are removed when the certificate is renewed.

Details

To change the period of log retention, add the LetsencryptLogPeriod parameter to the panel configuration file /usr/local/mgr5/etc/ispmgr.conf with a number of days.

Let’s Encrypt log files

  • /usr/local/mgr5/var/letsencrypt.log — contains debugging information, the URL of the server that is used to issue a certificate, and information about errors during issuance
  • /usr/local/mgr5/var/ispmgr.log — contains the results of calls to the ACME client when issuing, installing and renewing a certificate

You can change the logging level in the Logging settings section (sslcert, rpc, core_module modules).

Let's Encrypt certificate renewal

The need for Let's Encrypt certificate renewal is checked every day using the cron job /usr/local/mgr5/sbin/cron-ispmgr sbin/mgrctl -m ispmgr letsencrypt.check.update.

Auto renewal

By default, certificate renewal attempts start 29 days before its expiration.

Details

To change this time period, add the LetsencryptStartUpdatePeriod parameter to the ispmanager configuration file /usr/local/mgr5/etc/ispmgr.conf with a number of days. We do not recommended specifying values less than 7 and greater than 29, as well as negative values and letters.

If the certificate could not be renewed immediately, attempts will be repeated until its expiration date. Notifications about renewal errors will be sent starting from the second day and every day until the certificate expires.

Manual renewal

Certificates can be renewed manually with the following command:

/usr/local/mgr5/sbin/mgrctl -m ispmgr letsencrypt.check.update force_update=yes cert_name=CERTIFICATE_NAME user_name=USERNAME

When renewing a certificate with DNS validation, new TXT records will be generated for validation. If you are using an external DNS server, add new records to the domain's DNS zone.

Let’s Encrypt technical details

Certificate issuing servers 

During DNS validation, the certificate is immediately issued on the main ACME server. During HTTP validation, it is first issued in the staging environment and only then on the main server. By default, the main and staging Let’s Encrypt servers are used.

Details

To use servers of another certification authority, add the LetsencryptAcmeUrl parameters for the main and LetsencryptAcmeStagingUrl for the staging servers with the required values to the /usr/local/mgr5/etc/ispmgr.conf configuration file.

Changing the ACME server URL may cause authorization errors on the Let's Encrypt server. In this case, existing and pending certificates will need to be reissued.

First, a self-signed certificate is created, which is then replaced with a Let's Encrypt certificate.

Number of certificates issued simultaneously

By default, a maximum of one certificate can be issued at a time. Requests for new certificates have a higher priority than retries of old issues.

Details

To change the number of certificates issued at a time, add the LetsencryptProcessCount parameter with the number of certificates to the panel configuration file /usr/local/mgr5/etc/ispmgr.conf.

Let's Encrypt account

A Let's Encrypt account is created when you first connect to Let's Encrypt. The information about the account is written to files /usr/local/mgr5/tmp/le_account and /usr/local/mgr5/tmp/le_account_dry_run. The same account is used to issue all certificates are issued at the same time, including from different ispmanager accounts, the same Let's Encrypt account is used (if the number of simultaneously issued certificates is set to 2 or more).

Attempts to issue a certificate

The first attempt to issue a certificate is made immediately after clicking the Issue button in the certificate request form. If the certificate is not issued on the first attempt, the second attempt is made in 5 minutes, the third one is made in 10 minutes, the fourth — in 20, and so on exponentially for 24 hours.

Before issuing a certificate, ispmanager checks name servers for the domain. If the domain has no name servers, the certificate log will show the entry: "Unable to determine name servers for the domain YOUR_DOMAIN". Attempts to check the name servers are repeated for 24 hours. If no servers are found, attempts will stop and the certificate order will not be generated.

If the name server check is successful, the first attempt to issue a certificate is made after TXT records are added to the domain in the DNS management section and lasts for 10 seconds. This allows the certificate to be issued immediately if the domain's name servers are managed by ispmanager. If the certificate is not issued on the first attempt, the second attempt is made in 5 minutes, the third one — in 10, the fourth — in 20, and so on exponentially until that interval reaches 24 hours. Attempts are made for the entire lifespan of the issue order. The lifespan depends on the server that issues the certificate and usually lasts about a week.

The need to retry to issue a certificate is checked with a periodic task with an interval of 1 minute.

Details

To change the interval between the checks, add the LetsencryptProcessPeriod parameter with the number of minutes to the panel configuration file /usr/local/mgr5/etc/ispmgr.conf.

 To start a check manually, run the command:

/usr/local/mgr5/sbin/mgrctl -m ispmgr letsencrypt.periodic

TXT record verification

When issuing a certificate using the DNS domain validation, the ispmanager panel checks the existence of the TXT records before Let's Encrypt. This helps avoid exceeding Let's Encrypt request limits in case of errors. Ispmanager verifies TXT records using optimized iterative DNS queries.

Details
  1. The public suffix of the domain is determined (ru, com, net.ru, com.ru, etc.). The list of such suffixes is formed based on the official Public Suffix List (PSL), which is stored in cache /usr/local/mgr5/tmp/le_suffixes.cache and updated as needed, but at most once a week. If the list cannot be obtained, the querying begins with the name servers for top-level domains.

  2. NS records are requested for the suffix from one of the caching servers (by default 8.8.8.8, 8.8.4.4, 77.88.8.8, 77.88.8.1, 1.1.1.1).

    Details

    To change the default caching servers, add the LetsencryptAcmeDigNS parameter with new server IPs to the configuration file /usr/local/mgr5/etc/ispmgr.conf. Each value must start with the "@" symbol. Leave the value blank to use the server's DNS resolving settings.

  3. The IP address for these name servers is requested from the same caching server.
  4. TXT records for the domain the certificate is issued for are requested from the IP address.
  5. If the name server does not contain the TXT records, steps 2–4 are repeated until authoritative name servers are found.
  6. The authoritative name servers are queried for the TXT records.
  7. Authoritative name servers, their addresses and response times are stored in the cache files /usr/local/mgr5/tmp/le_ns.cache, /usr/local/mgr5/tmp/le_ip.cache and /usr/local/mgr5/tmp/le_balancer.cache respectively. During subsequent checks, TXT records are requested directly from the “fastest” cached authoritative server.

This type of queries helps avoid:

  • delays due to slow root servers by skipping them
  • getting outdated TXT records from caching servers by requesting the records directly from authoritative servers
Details

To disable iterative DNS queries, add Option LetsencryptDisableIterativeDig to the panel configuration file /usr/local/mgr5/etc/ispmgr.conf. In this case, TXT records will be requested from caching servers (8.8.8.8 8, etc.).

Handling Let's Encrypt server errors

In case of some the Let's Encrypt server errors, the attempts to issue a certificate are repeated automatically:

  • incorrect nonce (a single-use number generated by Let's Encrypt that the client sings its certificate requests with) — two more attempts to issue a certificate are made consecutively: one using an old nonce, and if it fails — a second one using a new nonce
  • 5XX server errors — attempts to issue a certificate are repeated after the time interval specified in the Retry-After header, or after one second, if Retry-After is absent. If the total response time from the first attempt exceeds 80 seconds, an error notification will appear in the panel. The next attempt will be made after the standard interval or the Retry-After interval, whichever is longer.

  • Let's Encrypt rate limit exceeded — if one of the following errors appear, and the response time exceeds 80 seconds, an attempt will be made to register a new account and create a new order (a maximum of 2 attempts):

    • too many currently pending authorizations
    • too many failed authorizations
    • too many new orders

    The rest Let's Encrypt rate limit errors are handled in the same way as the 5XX server errors.

If an error occurs while connecting to the Let's Encrypt staging environment, the certificate issuance in the staging environment is skipped.

In this article