Configuration

The plugin does not usually require any configuration out of the box.

Before you go diving in the configuration file, we suggest taking a look at the WHM plugin interface “Lets Encrypt SSL” which exposes most of the settings you may need to change.

Daemon Settings

This section documents a number of options that you may modify in /etc/letsencrypt-cpanel.conf, in the format of a JSON dictionary. Please note, this file should either be a valid JSON file, or not be present so default values are used. If the file isn’t valid JSON, the daemon will log errors. We strongly recommend not editing any configuration values directly unless you know what you’re doing.

Name	Description
db	This is the path of the datastore that the daemon uses to track asynchronous jobs. By default, it is /var/lib/letsencrypt-cpanel.db.
insecure	If your server has untrusted (self-signed) service certificates on port 2083 or 2087, you will need to set this to true, or the daemon will be unable to perform renewals. Default false.
hostcert	Setting this to true will issue/renew certificates for your WHM host domain. By default this is false. This process will output results to the log file in /var/log/letsencrypt-cpanel.log and uses the configuration options present below. Upon successfully issuing a certificate, the daemon will set insecure to false, and we recommend restarting the daemon after this but it is not necessary.
hostextranames	String array of what additional names to include on the service certificate. These must not be allocated to cPanel accounts or the service certificate will fail to be issued.
hostdocroot	cPanel is configured to use /usr/local/apache/htdocs as the document root for the default hostname entry in Apache config. By default, this entry is empty and filled out with this path when the configuration entry hostcert is set to true.
disablerenewalmail	Whether to prevent renewal email messages going out, server-wide.
deferred_restarts	Whether to enable the ‘Deferred Restarts’ feature for renewals: Apache will not be restarted by the plugin until all of the renewals are processed. This is powered by the apache_update_no_restart flagfile that is native to cPanel/WHM.
renewal_days_of_week	An array which contains the days of the week where renewals can be processed. For example: ["Monday", "Tuesday", "Wednesday"]
renewal_times_of_day	An array of only two numbers which contain a lower and upper hour during which the processing of renewals can start. Please note, renewals on servers with a large amount of users can take a while to process so it is possible to finish outside of the provided time. Example: [10, 15]
autossl	Whether the plugin AutoSSL feature is enabled.
autossl_max_retries	How many times to try to perform AutoSSL against a virtual host for. Minimum 3.
autossl_skip_patterns	An array of regex patterns of hostnames to avoid when processing AutoSSL. For example, ["^mail\..*", ".*\.foo\.com$"]
autossl_skip_proxy_subdomains	Whether to skip proxy subdomains when issuing certificates. Default false.
autossl_acme_registrations_limit	How many ACME registrations to limit per 3 hour period. Used to ensure that AutoSSL does not use up all of the available rate limit. Default 7.
autossl_expiry_replacement_cutoff	How many days from expiration AutoSSL will try to replace an existing, valid and non-plugin-managed certificate. Default 2. Valid range [1,90].
per_account_delay_secs	How long to sleep between accounts during renewal and AutoSSL. Default 15.
email_admin_destination	Where to send emails bound for the server administrator. Default root@hostname.
disable_success_mail	A bool that determines whether renewal success emails will be disabled globally
disable_mail	A bool that determines whether all renewal emails (failure or success) will be disabled globally
reporting	This item relates to the Reporting feature.
dns_challenge_delay_secs	How long the plugin should wait after updating DNS records to submit a certificate request. This allows for slow DNS cluster updates.
enabled_challenge_methods	Which DCV methods to allow users to issue certificates with. By default, ['http-01','dns-01'].
ui_autochecked_prefixes	This string array controls which prefixes are checked by default in the “Issue” user interface. Its default value of null implies ['www.','mail.']. Setting it to an empty array [] ensures neither option is selected by default.
crypto_rsa_key_size	What size of RSA key to use for certificates. By default, 2048. We do not recommend raising
preferred_issuer_cn	If multiple certificate chains are offered, prefer the one which builds a path to an issuer with this Common Name. Default value DST Root CA X3.

Per-user Settings

These settings are those in each user’s ~/.cpanel/nvdata/letsencrypt-cpanel NVData store, which is in JSON format.

Name	Description
disable_mail	This setting disables the mail sent by the daemon on successful or failed renewal of that user’s certificates, and can be set by the user in the settings page of the plugin.

Post Renewal Hook

In the config, hook_post_renewal is a string that should point to a single file with mode 0700 (both enforced). This file is executed when each certificate is renewed and once when the renewal process is complete. A JSON object is given to the standard input with the following information.

{"Account":"","Domains":null,"Success":true,"Error":"","Certificate":"","Issuer":"","Key":""}

When the process is ended the account string is empty and Success is true. Post each certificate renewal, the account is populated, Domains contains a []string of the domains in the cert, Error is populated if Success=false and cert/issuer/key are populated with the existing cert if certificate can’t be renewed and the new cert if it either failed to installed or everything succeeded.