LetsEncrypt

From Virtualizor Wiki
Jump to: navigation, search

Introduction

Let’s Encrypt is a free, automated, and open Certificate Authority (CA), which issue certificate for your domain names for free after domain name verification and Virtualizor from version 2.8.8 onward has integrated this feature.

With this, you will now be able to manage free certificate issued by Let's Encrypt CA for your domain names from the Virtualizor Admin panel. This feature will allow you to Fetch, Install, or Renew certificates issued by Let's Encrypt CA.

To know more about Let's Encrypt Certificate Authority visit https://letsencrypt.org

Requirements

  1. For proper verification of your domain name, Let's Encrypt requires the domain name to be resolved to your server which will be used to request Let's Encrypt's CA to issue certificate.
  2. Also the port 80 should be free or it should be used by Virtualizor service, this port will be used for domain name verification.

Management console

Let's Encrypt certificate Management Console can be accessed from Virtualizor admin panel under SSL Settings > LetsEncrypt or typing text "LetsEncrypt" in common search box.

Le manage console.png

This console will show if set, domain name and its certificate information as issued by Let's Encrypt CA.

Following information of the certificate will be shown:

  • Domain
The domain name for which this certificate is valid.
  • SAN
Subject Alternative Names on this certificate. List of additional domain names for which this certificate is valid
  • Issued By
Certificate Authority who issued the certificate.
  • Serial No.
Unique serial number for the certificate
  • Valid From
The date and time since the Certificate is valid.
  • Valid Till
The date and time till the Certificate will be considered as valid.
  • Next Renew Date
The day when the certificate will be auto renewed.
  • Installed
This indicates whether this certificate is currently installed on selected server or not.

The above information will be available only if the the certificate issued by Let's Encrypt is available on your Virtualizor server.

GUI Steps

Steps for managing the Let's Encrypt certificates from Virtualizor

Le buttons.png

Install Certificate

In order for Virtualizor to manage certificate request for your domain, it requires following information, which can be added by filling up the configuration form which is triggered when you click on "Install Certificate" button.

Config form.png
Mandatory Information
  • Primary Domain
This is the domain name which will be used as a primary domain in certificate.
  • Contact Email
The email address you enter here will be used by Let's Encrypt CA for communication. Let's Encrypt will be sending you alerts or information regarding your domain's certificate through these email address.
  • Key Size
The Key size entered here will be used as a key length Private Key which will be created to use with the newly issued certificate.
  • Renew Days
You can specify number of days after which the domain certificate issued should get auto renewed. Let's Encrypt issues certificate which remains valid for 90 days from the date of its issuance.
Optional information
  • Staging
You can select this field if you want to fetch the certificate from Let's Encrypt's Staging (Test) servers. Let's Encrypt currently imposes some limit on the number for trusted certificate issued (https://letsencrypt.org/docs/rate-limits/).

So if you are testing the certificate for your domain, then you can use this option, the certificate issued will work fine but will not be a trusted certificate.

  • Force
If you select this option, then the certificate request will be forced to processed.

Example, this can be useful if a certificate for a domain is expiring after 30 days, but you wish to renew it (or request new certificate for same domain) before its renew day.

Certificate Requests

Once the certificate configuration has been saved and all necessary requirements (mentioned in Requirements) are met, then you are ready to manage the certificates from Virtualizor.

Install Certificate

You can request new certificate for your domains, by clicking on "Install Certificate" button. The virtualizor will start processing the request in the background which might take some time. Once the certificate has been issued, it will be fetched and installed your Virtualizor server. Note, if the certificate has not expired, it will not be reissued if you have not set "force" option in configuration.

Renew Certificate

You can manually renew already issued certificate for your domain by clicking "Renew Certificate" button.Note, if certificate renew day has not arrived, the renew request will be skipped if you have not set "force" option in configuration.

Command Line Utility

You can request Issue or Renew of LetsEncrypt Certificate from command line as well.Command Line Utility allows you to save LetsEncrpt Certificate configuration details like DOMAIN NAME, EMAIL ADDRESS, RENEW DAYS, CERTIFICATE PRIVATE KEY LENGTH, STAGING, and Force

To get the command line help of this utility, you can enter on command line:

/usr/local/emps/bin/php /usr/local/virtualizor/scripts/virt_acme.php -h

This will list all available commands and required parameters with their description.

Commands

  • --install, -i
Use this command if you want to fetch the certificate and install it.
  • --renew, -r
Use this command if you want to renew and install the certificate already fetched.
  • --getcfg
Use this command to know currently saved LE configuration by Virtualizor
  • --savecfg
Use this command to save passed in certificate parameters which will be used if no parameters are specified when installing or renewing certificate

Parameters

  • -d, --domain [DOMAIN_NAME]
Use this paramter to specify domain name for which certificate is to be requested.
  • --contactemail [email address]
Use this parameter to specify contact email address which will be used by LetsEncrypt to provide you reminders or updates regarding the issued certificate.
  • --renewdays [NUMBER GREATED THAN 0 BUT LESS THAN OR EQUAL TO 80]
Use this parameter to specify after how many days of last fetch or renewal the certificate should be renewed. LetsEncrypt issues certificate which remains valid for 90 days from the date of its issuance or last renew.
  • --keysize [KEY_LENGTH]
Use this parameter to specify key size to be used for LE Certificate's private key. Supported key sizes are: '2048', '3072', '4096', '8192', 'ec-256', 'ec-384'
  • --staging, --test
Use this parameter if you want to fetch dummy certificate from LetsEncrypt Staging server, for trying out before requesting for the issue of actual certificate.
LetsEncrypt has some restrictions on number for real certificates issue for a domain name. Please check Let's Encrypt's official web site for latest updates on this restriction.
  • --force
Use this parameter to force certificate fetch or renew request. If this parameter is not specified, then certificate will be only fetched or renewed when it has been expired or lapsed its specified renew days.

Steps to request certificate

/usr/local/emps/bin/php /usr/local/virtualizor/scripts/virt_acme.php --install -d DOMAIN_NAME --contactemail EMAIL_ADDRESS
This will fetch LE certificate for specified domain DOMAIN_NAME with account registered using email EMAIL_ADDRESS. Once fetched, it will be installed to Virtualizor web server and the web server's configuration will be reloaded to use the new certificate.

Steps to renew certificate

/usr/local/emps/bin/php /usr/local/virtualizor/scripts/virt_acme.php --renew -d DOMAIN_NAME
This will request certificate renew for specified domain DOMAIN_NAME. The certificate will be renewed only when the renew days specified while installing certificate are lapsed since last renew or issue. You can force fully request renewal by appending parameter '--force'

Steps to view saved configurations

/usr/local/emps/bin/php /usr/local/virtualizor/scripts/virt_acme.php --getcfg
This will list the last saved parameters values. The parameters are:
  1. Primary Domain
  2. Contact Email
  3. Key Size
  4. Renew Days
  5. Staging
  6. Force

Steps to save configuration

/usr/local/emps/bin/php /usr/local/virtualizor/scripts/virt_acme.php --savecfg [PARAMETERS LIST]
PARAMETERS LIST
For Primary Domain:
-d DOMAIN_NAME
or
--domain DOMAIN_NAME
For Contact Email:
--contactemail EMAIL_ADDRESS
For Renew Days:
--renewdays RENEW_DAYS
Note: The days specifed must be greater than 0 but not greater than 80. Default value used is: 80
For Certificate's Private Key Length:
--keysize KEY_SIZE
Note: Supported values for this parameter are: 2048, 3072, 4096, 8192, ec-256, ec-384. Default value used is: 4096
For Staging:
--staging
or
--test
Note: If this parameter is not specified while saving configuration, it will be set to none, so if it was set previously, that will get overridden.
For Force:
--force
Note: If this parameter is not specified while saving configuration, it will be set to none, so if it was set previously, that will get overridden.

Logging

Virtualizor logs every last request for renew or install of certificate. This logs can be viewed from Admin Panel under LetsEncrypt's page > Show Logs

You can also view the current progress of certificate request under Tasks page of Virtualizor Admin panel.

Cron

Once the certificate is issued, this certificate will be renewed after every Renew Days specified, by Virtualizor.

Troubleshoot

Possible reasons for request failure

  • ca-bundle.crt file too old
The backend script verifies CA Server's certificate by consulting ca-bundle.crt file (/etc/pki/tls/certs/ca-bundle.crt under CentOS). And if it do not found the CA server's certificate's CA entry in this file, it refuses the request. This can be solved by updating the ca-bundle.crt
The latest ca-bundle can be downloaded from below url:
https://curl.haxx.se/ca/cacert.pem
Download and save it as /etc/pki/tls/certs/ca-bundle.crt (CentOS) after taking backup of old ca-bundle.crt
  • Server date and time is not synced with present time
CURL command fails to verify CA server's certificate if the your server's date and time are not correct. You will have to correctly set present date and time on your server to resolve this issue.