Page tree
Skip to end of metadata
Go to start of metadata

 

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:

  1. In any programming language, write a shell script to perform the desired actions.
  2. Store the script in the /usr/local/cpanel/scripts/ directory.

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

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:

ParameterTypeDescriptionPossible valuesExample
userstringThe terminated account's username.A valid username.username
killdnsbooleanWhether the system deleted the account's zone files during termination.
  • 1 — The system deleted the zone files.
  • 0 — The system did not delete the zone files.
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 the root user 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 — The cpmove file consists of multiple files.
  • nosplit — The cpmove file consists of a single file.
  • cpuser — The account's new (local) username.
  • splitdir — The directory that contains the cpmove file.

/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 the cpmove file.

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 our 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:

ArgumentTypeDescriptionPossible valuesExample
domainstringThe account's main domain name.A valid domain name.example.com
userstringThe account's username.A valid username.user
passstringThe account's password.A secure password.12345luggage
quotaintegerThe account's disk space quota.
  • An integer value between 1 and 999999 that represents a disk space quota in Megabytes (MB).
  • 0 — The account has unlimited disk space.
0
cpmodstringThe account's cPanel theme.
  • paper_lantern
  • Another valid theme on the server.
paper_lantern
ipstring

Whether the account has a dedicated IP address.

This parameter defaults to n.

  • y — The account has a dedicated IP address.
  • n — The account does not have a dedicated IP address.
n
cgistringWhether the account has CGI access.
  • y — CGI access.
  • n — No CGI access.
y
frontpage Whether the account has Microsoft® FrontPage® Extensions installed.
  • y — Installed.
  • n — Not installed.

    Note:

    In cPanel & WHM version 11.46 and later, this value is always n.

n
maxftpstringThe account's maximum number of FTP accounts.
  • An integer value between 1 and 999999.
  • 0, unlimited, or null — Unlimited.
0
maxsqlstringThe account's maximum number of SQL databases
  • An integer value between 1 and 999999.
  • 0, unlimited, or null — Unlimited.
0
maxpopstringThe account's maximum number of email addresses.
  • An integer value between 1 and 999999.
  • 0, unlimited, or null — Unlimited.
0
maxlststringThe account's maximum number of Mailman mailing lists.
  • An integer value between 1 and 999999.
  • 0, unlimited, or null — Unlimited.
0
maxsubstringThe account's maximum number of subdomains.
  • An integer value between 1 and 999999.
  • 0, unlimited, or null — Unlimited.
0
bwlimitstringThe account's bandwidth quota.
  • An integer value between 1 and 999999.
  • 0, unlimited, or null — Unlimited.
0
hasshellstringWhether the account has shell access.
  • y — Shell access.
  • n — No shell access.
y
ownerstringThe WHM account that owns this account.
  • A valid reseller's username.
  • root
root
planstringThe account's hosting plan (package).A valid package name.reseller_gold
maxparkstring

The account's maximum number of parked domains (aliases).

This parameter defaults to unlimited.

  • A positive integer between one and 999,999.
  • 0, unlimited, or null — The account has unlimited parked domains.
unlimited
maxaddonstring

The account's maximum number of addon domains.

This parameter defaults to unlimited.

  • A positive integer between one and 999,999.
  • 0, unlimited, or null — The account has unlimited parked domains.
unlimited
featureliststring

The account's feature list.

If you do not use this parameter, the function assigns the default feature list to the account.

A valid feature list name on the server.feature_list
contactemailstringThe account's contact email address.A valid email address.user@example.com
use_registered_nameserversbooleanWhether to use the domain's registered nameservers instead of the server's nameservers.
  • y — Use the domain's nameservers.
  • n — Use the server's nameservers.
0
languagestringThe account's locale.A valid locale name.en

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