cPanel & WHM Script Hooks

Introduction

cPanel & WHM script hooks allow a list of system-level operations to execute custom code. The system-level operations include: account modifications, installation of server software and backup runs.

Typically, to create a script hook, you will place a shell script (in any language you wish) inside of the /scripts/ directory. To pass data to the script, pass the data 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 execute at the beginning of the script.
• Post hooks execute 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. disallow — Generates a user.lock file. Note: The order of user, reason, and disallow must be maintained.	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. disallow — Generates a user.lock file. Note: The order of user, reason, and disallow must be maintained.	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)
prewwwacct	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.
premodifyacct	See below	Runs before an account is modified.
postmodifyacct	See below	Runs after an account is modified.

More about /scripts/postwwwacct & /scripts/prewwwacct

These scripts will run 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, read the converting hashes passed via ARGV section.

More about /scripts/premodifyacct & /scripts/postmodifyacct

These scripts will run either before ( premodifyacct) or after ( postmodifyacct) an account is modified.

More about /scripts/postkillacct

This script runs after an account is terminated, and it is called with its parameters in a hash:

/scripts/postkillacct %OPTS 

Parameters:

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

Service script hooks

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

Convert hashes passed via ARGV

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

/scripts/$hookname user $user password $password

You will need to convert the ARGV hash 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

The following function will take $argv and convert it into an associative array for PHP.

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 you call this function, you need to pass $argv to it:

$opts = argv2array($argv); 

Now, you can access the username like so:

$opts['user'];