Only advanced users should use this feature.
We added AutoSSL functionality to cPanel & WHM version 58, and custom AutoSSL provider modules in version 60.
AutoSSL provider modules allow your server's users to automatically secure locally-hosted domains on their accounts with certificates from that SSL certificate provider. We ship the cPanel (powered by Sectigo) provider module with cPanel & WHM, and you can download a plugin to add the Let's Encrypt™ provider module. This document explains how to create your own provider module.
Module development work
When you develop your provider module, we recommend the following workflow:
- Research the supported parameters for your desired SSL certificate provider.
Configure a module that subclasses the
/usr/local/cpanel/Cpanel/SSL/Auto/Provider.pmmodule with overrides that match the supported parameters for your certificate provider.
We advise that you do not directly edit the
Authentication deployment workflow
After you develop and configure your provider module, we recommend the following workflow to deploy the module:
- Navigate to WHM's Manage AutoSSL interface (WHM >> Home >> SSL >> Manage AutoSSL).
- Select the provider module.
- Test the provider module with an account on a non-production server.
- Review the log files to confirm that an SSL certificate provided by the provider secures the account's domains.
AutoSSL provider workflow
AutoSSL provider modules reside in the following directories:
/usr/local/cpanel/Cpanel/SSL/Auto/Provider/directory — cPanel-provided modules.
/var/cpanel/perl/Cpanel/SSL/Auto/Provider/directory — Third-party modules.
For example, a module for the third-party ExampleSSL's module would reside in the
Module function interfaces
The tables below contain the required, recommended, and inherited methods.
You must configure the following methods in the
Cpanel::SSL::Auto::Provider class. If you do not configure a required method, it will fail with a
Key-value pairs that declare each virtual host and which domains within those virtual hosts to secure.
You can provide the following optional methods in your module:
This method indicates the frequency at which AutoSSL performs a check via a cron job.
This value defaults to
This method indicates when to begin the renewal process. If the certificate expires in this number of days or fewer, the system starts the renewal process.
If you do not set this value, the system waits until the certificate expires before it attempts to replace it.
This method executes after AutoSSL prints a provider name prints into the log file.
|This method executes at the end of a full AutoSSL check.|
|This method indicates whether the provider can issue certificates that include wildcard domains. It returns one of the following values:|
This value defaults to
You can override the following optional methods in your module:
The maximum number of domains to request per certificate. This depends on the Certificate Authority's (CA) domain limits.
If you do not set this value, the system assumes that the CA does not limit the number of domains on a certificate.
This method returns a list of additional key-value pairs that define additional properties for the provider module.
This method sends information to the external provider, such as registration data.
This method resets the server's registration with the remote provider.
This method indicates whether the PEM-encoded certificate that you send to it comes from a valid AutoSSL provider and not a valid, non-AutoSSL provider. This method varies depending on the CA and the type of certificate that they issue.
If you do not define this method, the system assumes that nothing comes from this module.
This method defines the provider's name that the interface displays.
return 'Bogus SSL Provider for Testing Purposes';
This method indicates what to run when an administrator renames the account.
This method indicates what to run when the administrator terminates the account.
This method indicatess what to run when a user or administrator removes a domain from the account.
This method performs Domain Control Validation (DCV) as part of the AutoSSL
With this method, AutoSSL will not pass domains to the
The following methods are inherited, and you should not override them:
This method starts the log for the declared user.
If you do not set the
This method appends to an existing log. The
If a log does not exist for the
This method enters the
|This method indents the entries in the log by one level.|
|A Boolean value that indicates the AutoSSL run was for all users.|
|This method outdents the entries in the log by one level.|
|This method returns the time that this class instance started to log, in ISO 8601 time value.|
When AutoSSL finishes a check run, it sets that run's log to completed.
However, this method flags the log as in progress. This is useful when the module uses a separate queue to fetch the AutoSSL certificates, as the cPanel module does.
This method installs an SSL certificate for Exim, Apache, and Dovecot®.
In cPanel & WHM version 60, this method also installs an SSL certificate for
We may expand this method to install certificates for other services in future versions.
You must pass the following required arguments through this method:
You can pass the following optional arguments:
We strongly recommend that you use the
The following AutoSSL module outline demonstrates a minimal set of functionality.
This is not a fully-functional module. This only demonstrates basic workflow. Your implementation will require more internal logic. Also, this module does not demonstrate the necessary API calls that would allow your module to hook into your SSL certificate provider.