cPanel/WHM Script Hooks

Introduction

cPanel/WHM script hooks allow for custom code to be executed for certain system-level operations such as account modifications, installation of server software, and backup runs.

Most script hooks are created by placing a shell script (in any language you wish) inside of the /scripts/ directory. If any data is passed into the script, it will be passed via @ARGV. These scripts are always executed by the root user.

Remember: There are two categories of script hooks: pre hooks and post hooks.

• Pre hooks are executed at the beginning of the script.
• Post hooks are executed at the end of the script's execution.

Available script hooks

Accounting script hooks

More about /scripts/postwwwacct & /scripts/prewwwacct

These scripts will run either before (prewwwacct) or after (postwwwacct) an account is created.

Within these scripts, a hash is passed via ARGV to the hook script, consisting of the following data:

• user (string) — User name of the account. Example: user
• domain (string) — Domain name. Example: domain.tld
• plan (string) — Package to use for account creation. Example: reseller_gold
• quota (integer) — Disk space quota in MB.
  • Possible values: 0-999999.
  • 0 is unlimited.
• pass (string) — Password to access cPanel. Example: p@ss!w0rd$123
• useip (string) — Whether or not the domain has a dedicated IP address.
  • y — yes.
  • n — no.
• hascgi (string) — Whether or not the domain has cgi access.
  • y — yes.
  • n — no.
• installfp (string) — Whether or not the domain has FrontPage extensions installed.
  • y — yes.
  • n — no.
• hasshell (string) — Whether or not the domain has shell/SSH access.
  • y — yes.
  • n — no.
• contactemail (string) — Contact email address for the account. Example: user@otherdomain.tld
• cpmod (string) — cPanel theme name. Example: x3
• maxftp (string) — Maximum number of FTP accounts the user can create.
  • Possible values: 0-999999, unlimited, and null
  • 0 is unlimited.
• maxsql (string) — Maximum number of SQL databases the user can create.
  • Possible values: 0-999999, unlimited, and null
  • 0 is unlimited.
• maxpop (string) — Maximum number of email accounts the user can create.
  • Possible values: 0-999999, unlimited, and null
  • 0 is unlimited.
• maxlst (string) — Maximum number of mailing lists the user can create.
  • Possible values: 0-999999, unlimited, and null
  • 0 is unlimited.
• maxsub (string) — Maximum number of subdomains the user can create.
  • Possible values: 0-999999, unlimited, and null
  • 0 is unlimited.
• maxpark (string) — Maximum number of parked domains the user can create.
  • Possible values: 0-999999, unlimited, and null
  • 0 is unlimited.
• maxaddon (string) — Maximum number of addon domains the user can create.
  • Possible values: 0-999999, unlimited, and null
  • 0 is unlimited.
• bwlimit (string) — Bandiwdth limit in MB.
  • Possible values: 0-999999, unlimited, and null
  • 0 is unlimited.
• useregns (boolean) — Whether to use the registered nameservers for the domain instead of the ones configured on the server.
  • 1 — yes.
  • 0 — no.
• owner (string) — Owner of the account.

If you need infomation about accessing the data passed to postwwwacct or prewwwacct, please see the section on converting hashes passed via ARGV.

More about /scripts/postkillacct

This script runs after an account is terminated.

It is called with its parameters in a hash:

/scripts/postkillacct %OPTS

Parameters:

• OPTS{'user'} — Username of the terminated account.
• OPTS{'killdns'} — Whether the zone files were deleted during account termination. This is a boolean variable and will either be 1 (yes) or 0 (no).

Service script hooks

Converting hashes passed via ARGV

Some of script hooks will be passed a hash via ARGV, meaning that the script will be called from the command line in a similar method to:

/scripts/$hookname user $user password $password

This will need to be converted into a usable data structure (see below).

Perl

my %OPTS = @ARGV

Now %OPTS will be a normal Perl hash containing the data, so it can be accessed as follows:

my $username = $OPTS{‘user’};

$username will now contain the value of $user.

PHP

PHP is a little more complicated for accessing this type of information. The following function will take $argv and convert it into an associative array.

function argv2array ($argv) {
        $opts = array();
        $argv0 = array_shift($argv);

        while(count($argv)) {
                $key = array_shift($argv);
                $value = array_shift($argv);
                $opts[$key] = $value;
        }
        return $opts;
}

When calling this, it needs to be passed $argv. So, you will call it as follows:

$opts = argv2array($argv);

Now, you can access the username like so:

$opts[‘user’];