LetsEncrypt

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.

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 certificate issued by Let's Encrypt is available on your Virtualizor server.

GUI Steps

Steps for managing the Let's Encrypt certificates from Virtualizor

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.

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.
  
  Note : Let's Encrypt has limits for issuing certificates. So if you are facing any error then you can use staging option while attempting to install SSL. Once it works, you can install SSL without staging option.
  
  

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 parameter 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 specified 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

• Error : The specified domain did not resolve to this server: domain-name .
  
  It could be due to internal ip on server.
  You will need a public ip.
  If public ip is already present then check for Curl package .
  If its not present then you can try installing it on your server using :
  
  #CentOS
  yum install curl
  
  #Ubuntu
  apt-get install curl
  
  Then you can try to curl -kv https://domain-name from your server and check if it shows any error.
  
  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.
  
  
• Error : The specified domain did not resolve to this server: domain-name
  
  Check /etc/hosts file if there are unwanted/in-correct entries for that domain.
  Check if domain resolves to correct ip from your own own server.
  If it doesn't then check /etc/resolv.conf if it has correct nameserver entries else you can try adding nameserver 8.8.8.8 and then check .
  
  
• Error : shows connection refused in logs
  
  Domain with Cloudflare will fail to fetch the SSL.
  
  
• Try stopping the firewall, if possible, if SSL is still failing to install .
  

• 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 does not finds 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