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

Script (located in /scripts)	Arguments	Description
postcpbackup	None	Runs after cPanel backup (post /scripts/cpbackup).
prekillacct	See below	Runs before account termination (pre /scripts/killacct).
postkillacct	See below	Runs after account termination (post /scripts/killacct). Note: Parse as a hash as killdns or user could change order.
presuspendacct	username— The suspended account's username. reason — The reason for the account's suspension.	Runs before an account is suspended (pre /scripts/suspendacct).
postsuspendacct	user — The name of the account to be suspended. reason — The reason for the account's suspension.	Runs after an account is suspended (post /scripts/suspendacct).
preunsuspendacct	username — The name of the account to be unsuspended.	Runs before an account is unsuspended (pre /scripts/unsuspendacct).
preupcp	None	Runs before cPanel & WHM updates (post /scripts/upcp).
postupcp	None	Runs after cPanel & WHM updates (post /scripts/upcp).
postupdateuserdomains	None	Runs after generation of the domain list (post /scripts/updateuserdomains).
postunsuspendacct	user — The username corresponding to the account that has been unsuspended.	Runs after an account is unsuspended (post /scripts/unsuspendacct).
prepkgacct	user — The username corresponding to the account that will be packaged.	Runs before an account is packaged into a cpmove file by means of the /scripts/enXim-pkgacct script (typically during the transfer of an account from the Ensim® control panel to a cPanel & WHM server). Note: This hook point is not available for normal, cPanel & WHM-generated cpmove files.
postpkgacct	split/nosplit — Specifies whether the cpmove archive is split into multiple files or is contained in a single file. cpuser — The new (local) cPanel user name user — The original (remote) username splitdir — The directory that contains the cpmove archive.	Runs after an account is packaged into a cpmove file by means of the /scripts/enXim-pkgacct script (typically during the transfer of an account from the Ensim control panel to a cPanel & WHM server). Note: This hook point is not available for normal, cPanel & WHM-generated cpmove files.
prerestoreacct	user — The new (local) cPanel username olduser — The old (remote) username extractdir — The directory to which the cpmove archive will be extracted.	Runs before an account is restored. (pre /scripts/restoreacct)
postrestoreacct	user — The new (local) cPanel username olduser — The old (remote) username domain — The restored account's main domain user_homedir — The new account's home directory	This script runs after an account is restored. (post /scripts/restoreacct)
prewwwact	See below	Runs before account creation (pre /scripts/wwwacct).
postwwwacct	See below	Runs after account creation (post /scripts/wwwacct).
postwwwacctuser	user — The username corresponding to the account that was created.	Runs after user creation

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.
• locale (string) — The localization that the account is using.

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

Note: None of the following hook scripts accept any arguments.

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'];