Configuration

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

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.
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]

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.