cPanel Hooks

You may, in some circumstances, want FleetSSL cPanel do perform some actions in response to an event in cPanel.

For example, you may wish for the AutoSSL feature to run immediately when a user adds an addon domain in the user interface.

This page will introduce you briefly to the method by which you can achieve this.

Introducing you to cPanel Standardized Hooks

This is a topic that’s too long to cover here, but we will be using this existing mechanism in cPanel to trigger an event when an addon domain is added.

Please refer to the documentation at:

A Warning

Please keep in mind that we have our reasons for not using hooks in the FleetSSL cPanel plugin, and waiting for AutoSSL to run to issue certificates for new domains.

We cannot provide support for or any guarantees about the operation of the plugin in combination with cPanel Standardized Hooks.

This article documents, but does not advocate their use.

1. Creating the Hook File

We will be writing our hook file in PHP and storing it in the /usr/local/cpanel/3rdparty/bin directory.

Prepare the file and relevant permissions:

touch /usr/local/cpanel/3rdparty/bin/FleetSSLAddonDomainHook.php
chmod 0755 /usr/local/cpanel/3rdparty/bin/FleetSSLAddonDomainHook.php

Edit the file and set its contents to the following:

#!/usr/local/cpanel/3rdparty/bin/php -q
<?php
// This is a third-party hook and is NOT part of FleetSSL cPanel

$input = get_passed_data();

/* 
 * This is the meat of the hook. All it does is run:
 *
 *     le-cp autossl run-for-user USERNAME
 *
 * which should result in a certificate being issued for the new 
 * addon domain.
*/
if (isset($input['data']) && isset($input['data']['user'])) {
  exec('/usr/local/bin/le-cp autossl run-for-user ' . $input['data']['user']);
}

/* No matter what happened, hook succeeded */
echo "0 OK";

/* Boilerplate to read the hook data */
function get_passed_data() {
  $raw_data;
  $stdin_fh = fopen('php://stdin', 'r');
  if (is_resource($stdin_fh)) {
    stream_set_blocking($stdin_fh, 0);
    while (($line = fgets($stdin_fh, 1024)) !== false) {
      $raw_data .= trim($line);
    }
    fclose($stdin_fh);
  }
  if ($raw_data) {
    $input_data = json_decode($raw_data, true);
  } else {
    $input_data = array('context' => array(), 'data' => array(), 'hook' => array());
  }
  return $input_data;
}
?>

2. Registering the Hook

Now that the hook is in place, we need to register it with the cPanel hook system.

This can be done by running:

/usr/local/cpanel/bin/manage_hooks add script \
/usr/local/cpanel/3rdparty/bin/FleetSSLAddonDomainHook.php \
--category Cpanel --event Api2::AddonDomain::addaddondomain \
--stage post --escalateprivs 1 --manual 1

The hook can be deleted by replacing add with delete and running the same command.

3. Testing the Hook

Go add an addon domain via the cPanel user interface.

Once you’ve done that, take a look at your FleetSSL cPanel logs (either in /var/log/letsencrypt-cpanel.log or journalctl -u letsencrypt-cpanel -f, depending if you are on CentOS 6 or 7, respectively).

You should see a message like:

level=info msg="AutoSSL running" Function=processAutoSSLForAccount Retry=false Username=THE_USERNAME WantedNames=[]

around the same time that you added the addon domain.

Whether a certificate is issued or not depends on other factors (such as if the domain is actually pointing to the server), but this should get you going.