Software Development Kit

cPanel & WHM's API [+] cPanel & WHM's API [-]


Modules and Plugins [+] Modules and Plugins [-]


cPanel & WHM Hooks [+] cPanel & WHM Hooks [-]


cPAddons (Site Software) [+] cPAddons (Site Software) [-]


System Administration [+] System Administration [-]


Developer Software [+] Developer Software [-]


Back to All Documentation

cPanel & WHM Script Hooks

Overview

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

To create a script hook, place a shell script, in any language you wish, in the /scripts/ directory. Data is passed to the script through the @ARGV array. These scripts are always executed as the root user.

PICK Remember: There are two categories of script hooks:

  • Pre hooks execute at the beginning of system-level functions.
  • Post hooks execute at the end of system-level functions.

Available script hooks

The following script hooks are available, organized by function.

Accounting script hooks

Script
(located in /scripts)
Arguments Description
postcpbackup None Runs after cPanel backup (post /scripts/cpbackup).
precpbackup None Runs before the cPanel backup (pre /scripts/cpbackup).
note Note: You must update /etc/cpbackup.conf if you wish the precpbackup and postcpbackup script hooks to run. Use a text editor to specify PREBACKUP 1 in /etc/cpbackup.conf for precpbackup, and POSTBACKUP 1 in /etc/cpbackup.conf for postcpbackup.
note Note: You can manually add precpbackup -1 in /etc/cpbackup.conf to run the precpbackup script before any checks or verifications. The script will then run regardless of whether the backups are up to date.
prekillacct See below Runs before account termination (pre /scripts/killacct).
postkillacct See below Runs after account termination (post /scripts/killacct).
Note: You may change the order if you parse as a hash, as killdns, or as user.
presuspendacct
  • username— The suspended account's username.
  • reason — The reason for the account's suspension.
  • disallow — Generates a user.lock file.
    note Note: The order of username, reason, and disallow must be maintained.
Runs before an account is suspended (pre /scripts/suspendacct).
postsuspendacct
  • user — The username for the account to be suspended.
  • reason — The reason for the account's suspension.
  • disallow — Generates a user.lock file.
    note Note: The order of username, reason, and disallow must be maintained.
Runs after an account is suspended (post /scripts/suspendacct).
preunsuspendacct
  • username — The username for 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 the generation of the domain list (post /scripts/updateuserdomains).
postunsuspendacct
  • user — The username that corresponds to the account that has been unsuspended.
Runs after an account is unsuspended (post /scripts/unsuspendacct).
prepkgacct
  • user — The username that corresponds 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. Generally, this occurs when an account is transferred from the Ensim® control panel to a cPanel & WHM server.
note 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 username
  • 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. Generally, this occurs when an account is transferred from the Ensim® control panel to a cPanel & WHM server.
note 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 that corresponds 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 by @ARGV to the hook script, which consists of the following data:

  • user (string) — The username for the account. (For example, user)
  • domain (string) — The domain name. (For example, domain.tld)
  • plan (string) — The package to use for account creation. (For example, reseller_gold)
  • quota (integer) — Disk space quota in MB.
    • Possible values: 0 - 999999.
    • 0 is unlimited.
  • pass (string) — Password to access cPanel. (For example, p@ss!w0rd$123)
  • useip (string) — Whether the domain has a dedicated IP address.
    • y — yes.
    • n — no.
  • hascgi (string) — Whether the domain has cgi access.
    • y — yes.
    • n — no.
  • installfp (string) — Whether the domain has FrontPage extensions installed.
    • y — yes.
    • n — no.
  • hasshell (string) — Whether the domain has shell access.
    • y — yes.
    • n — no.
  • contactemail (string) — The contact email address for the account. (For example, user@otherdomain.tld)
  • cpmod (string) — The cPanel theme name. (For example, x3)
  • maxftp (string) — Maximum number of FTP accounts that the user can create.
    • Possible values: 0 - 999999, unlimited, and null
    • 0 is unlimited.
  • maxsql (string) — Maximum number of SQL databases that the user can create.
    • Possible values: 0 - 999999, unlimited, and null
    • 0 is unlimited.
  • maxpop (string) — Maximum number of email accounts that the user can create.
    • Possible values: 0 - 999999, unlimited, and null
    • 0 is unlimited.
  • maxlst (string) — Maximum number of mailing lists that the user can create.
    • Possible values: 0 - 999999, unlimited, and null
    • 0 is unlimited.
  • maxsub (string) — Maximum number of subdomains that the user can create.
    • Possible values: 0 - 999999, unlimited, and null
    • 0 is unlimited.
  • maxpark (string) — Maximum number of parked domains that the user can create.
    • Possible values: 0 - 999999, unlimited, and null
    • 0 is unlimited.
  • maxaddon (string) — Maximum number of addon domains that the user can create.
    • Possible values: 0 - 999999, unlimited, and null
    • 0 is unlimited.
  • bwlimit (string) — Bandwidth 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 will use.

For information about how to access 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.

Script
(located in /scripts)
Description
QUOTA Disk space quota.
HASCGI Whether CGI privileges are enabled.
HASSPF Whether SPF is enabled.
MAXSUB Maximum amount of subdomains that the user can create.
MAXAADON Maximum amount of addon domains that the user can create.
MAX_DEFER_FAIL_PERCENTAGE Maximum percentage of failed or deferred messages a domain may send per hour.
HASDKIM Whether the account has DKIM enabled.
HASSHELL Whether the domain has shell access enabled.
newuser Used to change an existing username.
contactemail Contact email address for the account.
domain Primary domain for the account.
user Username for the account.
RS Theme desired for the account.
MAX_EMAIL_PER_HOUR Maximum amount of emails relayed by the domain per hour.
reseller Reseller privileges of the account.
MAXFTP Maximum amount of FTP accounts that the user can create.
MAXMONGREL Maximum amount of mongrel instances (Ruby on Rails).
LOCALE Default locale for the account.
MAXLST Maximum number of mailing lists that the user can create.
MAXPARK Maximum number of parked domains that the user can create.
BWLIMIT Bandwidth limit of the account.
MAXPOP Maximum number of email accounts that the user can create.
MAXSQL Maximum number of SQL databases for the account.
OWNER Owner of the account.

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 when the account was terminated. This is a boolean variable, for which a value of 1 indicates that the zone files were deleted.

Convert hashes passed through @ARGV

Some script hooks will be passed to a hash through @ARGV. This means that the script will be called from the command line in a command similar to the following:

/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 that contains the data. 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 as follows:

$opts['user']; 

Topic revision: r18 - 07 Oct 2013 - 19:40:14 - Main.SarahHaney
DevHooks.ScriptHooks moved from AllDocumentation/AutomationIntegration.ScriptHooks on 23 Jul 2009 - 18:42 by Main.JustinSchaefer