We added AutoSSL functionality to cPanel & WHM version 58, and custom AutoSSL provider modules in version 60.
This feature is intended for advanced users.
AutoSSL provider modules allow your server's users to automatically secure domains on their accounts with certificates from that SSL certificate provider. We ship the cPanel (powered by Comodo) 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 chosen SSL certificate provider.
- Configure a module that subclasses the
/usr/local/cpanel/Cpanel/SSL/Auto/Provider/Provider.pmmodule with overrides that match the supported parameters for your certificate provider.
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 (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 the account's domains are secured by an SSL certificate provided by the provider.
AutoSSL provider workflow
cPanel-provided AutoSSL provider modules reside in the
Third-party AutoSSL provider modules reside in the
For example, a module for the ExampleSSL third-party provider 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 die with a
Key-value pairs that declare each virtual host and the domains within those virtual hosts to secure.
The following methods are optional, and you can override them in your module:
This method declares when to begin the process of renewal. If the certificate has this many number of days or less before expiration, the system will start the renewal process.
if you do not set this value, the system waits until the certificate expires before it attempts to replace it.
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, which is not likely true.
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 rather than a valid non-AutoSSL provider. This method will vary depending on the Certificate Authority 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 will display.
return 'Bogus SSL Provider for Testing Purposes';
This method declares what to run when an administrator renames the account.
This method declares what to run when the administrator terminates the account.
This method declares what to run when a user or administrator removes a domain from the account.
The following methods are inherited, and you should not override them:
This method starts the log for the user that you declare.
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.|
|This method outdents the entries in the log by one level.|
|This method returns the time that this class instance started to log, in and 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 will also install an SSL certificate for
We may expand this method to install certificates for other services in future versions.
The required options that you must pass through this method are:
The optional option that you can pass through this method is:
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.