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

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:

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
domainstring

Required

The account's main domain name.

A valid domain name.example.com
userstring

Required

The account's username.

A valid username.user
passstring

Required

The account's password.

A secure password.12345luggage
quotainteger

The account's disk space quota.

This parameter defaults to 0. (unlimited)

  • An integer value between one and 999999 that represents a disk space quota in Megabytes (MB).
  • 0 — The account possesses unlimited disk space.
0
cpmodstring

The account's cPanel theme.

This parameter defaults to the default package's Theme setting.

  • paper_lantern
  • Another valid theme on the server.
paper_lantern
ipstring

Whether the account possesses a dedicated IP address.

This parameter defaults to n.

  • y — The account possesses a dedicated IP address.
  • n — The account does not possess a dedicated IP address.
n
cgistring

Whether the account has CGI access.

This parameter defaults to the default package's CGI Access setting.

  • y — CGI access.
  • nNo CGI access.
y
frontpagestringWhether Microsoft® FrontPage® Extensions exist on the account.
  • y — Installed.
  • nNot installed.

    Note:

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

n
maxftpstring

The account's maximum number of FTP accounts.

This parameter defaults to unlimited.

  • A positive integer between one and 999,999.
  • 0, unlimited, or null — Unlimited.
0
maxsqlstring

The account's maximum number of SQL databases.

This parameter defaults to unlimited.

  • A positive integer between one and 999,999.
  • 0, unlimited, or null — Unlimited.
0
maxpopstring

The account's maximum number of email addresses.

This parameter defaults to unlimited.

  • A positive integer between one and 999,999.
  • 0, unlimited, or null — Unlimited.
0
maxlststring

The account's maximum number of Mailman mailing lists.

This parameter defaults to unlimited.

  • A positive integer between one and 999,999.
  • 0, unlimited, or null — Unlimited.
0
maxsubstring

The account's maximum number of subdomains.

This parameter defaults to unlimited.

  • A positive integer between one and 999,999.
  • 0, unlimited, or null — Unlimited.
0
bwlimitstring

The account's bandwidth quota.

This parameter defaults to unlimited.

  • A positive integer between one and 999,999.
  • 0, unlimited, or null — Unlimited.
0
hasshellstring

Whether the account has shell access.

This parameter defaults to the default package's Shell Access value

  • y — Shell access.
  • n — No shell access.
y
ownerstring

The WHM account that owns this account.

This parameter defaults to the user who runs the script.

  • A valid reseller's username.
  • root
root
planstring

The account's hosting plan (package).

This parameter defaults to unlimited.

A valid package name.default
maxparkstring

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

This parameter defaults to the selected package's Maximum Parked Domains value.

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

The account's maximum number of addon domains.

This parameter defaults to the selected package's Maximum Addon Domains value.

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

The account's feature list.

This parameter defaults to the selected package's Feature List value.

A valid feature list name on the server.default
contactemailstring

The account's contact email address.

This parameter defaults to a null value.

A valid email address.user@example.com
use_registered_nameserversstring

Whether to use the domain's registered nameservers instead of the server's nameservers.

This parameter defaults to n.

  • y — Use the domain's nameservers.
  • n — Use the server's nameservers.
n
languagestring

The account's locale.

This parameter defaults to the selected package's Locale value.

A valid locale name.en
spamassassinstring

Whether Apache SpamAssassin™ is enabled on the account.

Note:

We added this parameter in cPanel & WHM version 70. 

This parameter defaults to y

  • y — Enabled.
  • n — Disabled.
y
spamboxstring

Whether to enable Spam Box on the account.

Note:

  • You must enable Apache SpamAssassin if you call this parameter.
  • We added this parameter in cPanel & WHM version 80.

This parameter defaults to y (enabled).

  • y — Enabled.
  • n — Disabled.
y
max_emailacct_quotastring

The maximum quota for each email address in MB.

Note:

We added this parameter in cPanel & WHM version 70.

This parameter defaults to the selected package's Max Quota per Email Address (MB) value.

  • A positive integer between one and 4,294,967,296.
  • unlimited — Unlimited.
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