- Created by Documentation, last modified on Apr 18, 2018
Introduction
Script hooks execute custom code before and after certain system-level operations. For example, script hooks can run before or after account creation, account modification, server software installation, or backup runs.
To view a list of scripts for which you can create script hooks, read our WHM Scripts documentation.
Warning:
This hook method is deprecated. To convert script hooks to use the Standardized Hooks system, use System or Whostmgr events in your Hook Action Code.
Basic usage
To create a script hook, perform the following steps:
- In any programming language, write a shell script to perform the desired actions.
- Data passes through script hooks via the
@ARGVarray. - The system always executes script hook scripts as the
rootuser.
- Data passes through script hooks via the
- Store the script in the
/usr/local/cpanel/scripts/directory.
Note:
Before you create a new script hook, check whether the hook exists in our list of available script hooks.
Convert @ARGV hashes
Because the system passes some script hooks to a hash through the @ARGV array, you must convert the @ARGV hash into a usable data structure.
Select a tab to view information for that programming language:
To convert @ARGV into a usable data structure in Perl, assign it to a hash:
my %OPTS = @ARGV
To access the data in the %OPTS hash, assign it to a variable:
my $username = $OPTS{'user'};
To convert @ARGV into a usable data structure in PHP, 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; }
Pass the $argv variable through the function to assign the data to the $opts variable:
$opts = argv2array($argv);
To access the data in the $opts variable, you could use the following code:
$opts['user'];
To convert @ARGV into a useable data structure in Python, convert it into a dictionary:
#!/usr/bin/env python import sys opts = dict(zip(*[iter(sys.argv[1:])]*2))
To access the data in the opts dictionary, you could use the following code:
print opts['user']
Available script hooks
cPanel & WHM ships with hooks already available for the following scripts and system actions:
/scripts/cpbackup
The /scripts/cpbackup script's hooks trigger each time that cPanel & WHM runs a backup.
For these script hooks to function correctly, you must add the following lines to the /etc/cpbackup.conf file:
PREBACKUP 1 POSTBACKUP 1
By default, the system triggers the pre hook after it performs checks and validations. To cause the hook to run before the checks and validations (for example, regardless of whether backups are up-to-date), add the following line to the /etc/cpbackup.conf file:
precpbackup -1
pre hook script:
/scripts/precpbackup
post hook script:
/scripts/postcpbackup
/scripts/killacct
The /scripts/killacct script's hooks trigger each time that the system deletes an account.
pre hook script:
/scripts/prekillacct
post hook script:
/scripts/postkillacct
When the system runs the /scripts/postkillacct script, it passes in the %OPTS hash, which contains the following parameters:
| Parameter | Type | Description | Possible values | Example |
|---|---|---|---|---|
user | string | The terminated account's username. | A valid username. | username |
killdns | boolean | Whether the system deleted the account's zone files during termination. |
| 0 |
/scripts/suspendacct
The /scripts/suspendacct script's hooks trigger each time that the system suspends an account.
pre hook script:
/scripts/presuspendacct
post hook script:
/scripts/postsuspendacct
These scripts accept the following arguments:
username— The suspended account's username.reason— The reason for account suspension.disallow— Whether to allow only therootuser to unsuspend the account.
Important:
These arguments must maintain the following order: username, reason, disallow.
/scripts/unsuspendacct
The /scripts/unsuspendacct script's hooks trigger each time that the system unsuspends an account.
pre hook script:
/scripts/preunsuspendacct
This script accepts the following argument:
username— The suspended account's username.
post hook script:
/scripts/postunsuspendacct
This script accepts the following argument:
user— The suspended account's username.
/scripts/upcp
The /scripts/upcp script's hooks trigger each time that cPanel & WHM updates.
pre hook script:
/scripts/preupcp
post hook script:
/scripts/postupcp
/scripts/updateuserdomains
The /scripts/updateuserdomains script's hooks trigger each time that the system generates a domain list.
pre hook script:
none
post hook script:
/scripts/postupdateuserdomains
/scripts/enXim-pkgacct
The /scripts/enXim-pkgacct script's hooks trigger each time that the system packages an account into a cpmove file via this script. Generally, this occurs when an account transfers from the Ensim® control panel to a cPanel & WHM server.
Note:
These hooks do not trigger for cPanel & WHM-generated cpmove files.
pre hook script:
/scripts/prepkgacct
This script accepts the following argument:
user— The account's username.
post hook script:
/scripts/postpkgacct
This script accepts the following argument:
user— The account's original (remote) username.split— Thecpmovefile consists of multiple files.nosplit— Thecpmovefile consists of a single file.cpuser— The account's new (local) username.splitdir— The directory that contains thecpmovefile.
/scripts/restoreacct
The /scripts/restoreacct script's hooks trigger each time that the system restores an account.
pre hook script:
/scripts/prerestoreacct
This script accepts the following arguments:
cpuser— The account's new (local) username.olduser— The account's old (remote) username.extractdir— The directory to which the system will extract thecpmovefile.
post hook script:
/scripts/postrestoreacct
This script accepts the following arguments:
user— The account's new (local) username.olduser— The account's old (remote) username.domain— The account's main domain.user_homedir— The absolute path to the account's home directory.
/scripts/wwwacct
The /scripts/wwwacct script's hooks trigger each time that the system creates a cPanel account.
For more information, read the /scripts/wwwacct script documentation.
pre hook script:
/scripts/prewwwacct
post hook script:
/scripts/postwwwacct
In these scripts, the @ARGV array passes in a hash that contains the following data:
| Argument | Type | Description | Possible values | Example |
|---|---|---|---|---|
domain | string | The account's main domain name. | A valid domain name. | example.com |
user | string | The account's username. | A valid username. | user |
pass | string | The account's password. | A secure password. | 12345luggage |
quota | integer | The account's disk space quota. |
| 0 |
cpmod | string | The account's cPanel theme. |
| paper_lantern |
ip | string | Whether the account has a dedicated IP address. This parameter defaults to |
| n |
cgi | string | Whether the account has CGI access. |
| y |
frontpage | string | Whether Microsoft® FrontPage® Extensions exist on the account. |
| n |
maxftp | string | The account's maximum number of FTP accounts. |
| 0 |
maxsql | string | The account's maximum number of SQL databases |
| 0 |
maxpop | string | The account's maximum number of email addresses. |
| 0 |
maxlst | string | The account's maximum number of Mailman mailing lists. |
| 0 |
maxsub | string | The account's maximum number of subdomains. |
| 0 |
bwlimit | string | The account's bandwidth quota. |
| 0 |
hasshell | string | Whether the account has shell access. |
| y |
owner | string | The WHM account that owns this account. |
| root |
plan | string | The account's hosting plan (package). | A valid package name. | reseller_gold |
maxpark | string | The account's maximum number of parked domains (aliases). This parameter defaults to |
| unlimited |
maxaddon | string | The account's maximum number of addon domains. This parameter defaults to |
| unlimited |
featurelist | string | The account's feature list. If you do not use this parameter, the function assigns the | A valid feature list name on the server. | feature_list |
contactemail | string | The account's contact email address. | A valid email address. | user@example.com |
use_registered_nameservers | string | Whether to use the domain's registered nameservers instead of the server's nameservers. |
| 0 |
language | string | The account's locale. | A valid locale name. | en |
spamassassin | string | Whether Apache SpamAssassin™ is enabled on the account. Note: We added this parameter in cPanel & WHM version 70. |
| y |
max_emailacct_quota | integer | The maximum size that the account can define when it creates an email account. Important: If you supply a We recommend that you allow the account's plan to determine this value. Note:
This parameter defaults to |
| unlimited |
User creation
The following script hooks trigger each time that the system creates a user.
pre hook script:
none
post hook script:
/scripts/postwwwacctuser
This script accepts the following argument:
user— The new account's username.
Account modification
The following script hooks trigger each time that the system modifies an account.
pre hook script:
/scripts/premodifyacct
post hook script:
/scripts/postmodifyacct
Standardized Hooks
About Standardized Hooks
- The Standardized Hooks system triggers scripts or applications whenever a specific action is performed in cPanel & WHM.
- This functionality is useful for developers and system administrators.
Compatible with:
- cPanel 11.32+
- WHM 11.32+
Related Documentation
-
Page:
-
Page:Tweak Settings - Development —
Standardized Hooks - Debug Mode
The Standardized Hooks System’s debug mode helps to troubleshoot hook issues. For more information, read our Guide to Standardized Hooks - Debug Mode documentation.
You can select the following options:
- Debug mode is off. — The system does not display debug information or log it to the error log.
- Debug mode is on. The system displays information about a hook while it executes, but does not log debug data to the error log.
Debug mode is on. The system displays information about a hook while it executes and logs debug data to the error log.
Important:
This setting outputs a large amount of data.
- Debug mode is on. The system displays information about every stage for every hookable event, even if no hooks exist for that stage.
This setting defaults to Debug mode is off.
Note:
If, instead of this setting, you use the
/var/cpanel/debughooksfile to enable debug mode, your locale may revert to the English defaults for JavaScript elements. To fix this problem, run the following commands to disable debug mode and restart thecpsrvddaemon:echo -n > /var/cpanel/debughooks /scripts/restartsrv_cpsrvd
-
Page:WHM API 1 Functions - reorder_hooks — This function changes the order of script hooks.
-
Page:WHM API 1 Functions - delete_hook — This function removes a script hook.
-
Page:WHM API 1 Functions - edit_hook — This function edits a script hook.