Child pages
  • Guide to Standardized Hooks - Script Hooks

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Introduction

Excerpt

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 our WHM Scripts documentation documentation.

Warning
titleWarning:

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.
Note
titleNote:

Before you create a new script hook, check whether the hook exists in our list of available script hooks.

Anchor
argv
argv
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:

Localtab Group


Localtab
activetrue
titlePerl

To convert @ARGV into a usable data structure in Perl, assign it to a hash:

Code Block
languageperl
my %OPTS = @ARGV   

To access the data in the %OPTS hash, assign it to a variable:

Code Block
languageperl
my $username = $OPTS{'user'};



Localtab
titlePHP

To convert @ARGV into a usable data structure in PHP, convert it into an associative array:

Code Block
languagephp
linenumberstrue
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:

Code Block
languagephp
$opts = argv2array($argv);   

To access the data in the $opts variable, you could use the following code:

Code Block
languagephp
$opts['user'];



Localtab
titlePython

To convert @ARGV into a useable data structure in Python, convert it into a dictionary:

Code Block
languagepy
linenumberstrue
#!/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:

Code Block
languagepy
print opts['user']



Anchor
existing
existing
Available script hooks

cPanel & WHM ships with hooks already available for the following scripts and system actions:

/scripts/cpbackup


Panel
bgColor#FFFFFF
borderStylenone

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:

Code Block
languagetext
linenumberstrue
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:

Code Block
languagetext
precpbackup -1


Section


Column
width25%

pre hook script:


Column

/scripts/precpbackup



Section


Column
width25%

post hook script:


Column

/scripts/postcpbackup



/scripts/killacct


Panel
bgColor#FFFFFF
borderStylenone

The /scripts/killacct script's hooks trigger each time that the system deletes an account.

Section


Column
width25%

pre hook script:


Column

/scripts/prekillacct



Section


Column
width25%

post hook script:


Column

/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


Panel
bgColor#FFFFFF
borderStylenone

The /scripts/suspendacct script's hooks trigger each time that the system suspends an account.

Section


Column
width25%

pre hook script:


Column

/scripts/presuspendacct



Section


Column
width25%

post hook script:


Column

/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.
Warning
titleImportant:

These arguments must maintain the following order: username, reason, disallow.


/scripts/unsuspendacct


Panel
bgColor#FFFFFF
borderStylenone

The /scripts/unsuspendacct script's hooks trigger each time that the system unsuspends an account.

Section


Column
width25%

pre hook script:


Column

/scripts/preunsuspendacct


This script accepts the following argument:

  • username — The suspended account's username.
Section


Column
width25%

post hook script:


Column

/scripts/postunsuspendacct


This script accepts the following argument:

  • user — The suspended account's username.

/scripts/upcp


Panel
bgColor#FFFFFF
borderStylenone

The /scripts/upcp script's hooks trigger each time that cPanel & WHM updates.

Section


Column
width25%

pre hook script:


Column

/scripts/preupcp



Section


Column
width25%

post hook script:


Column

/scripts/postupcp



/scripts/updateuserdomains


Panel
bgColor#FFFFFF
borderStylenone

The /scripts/updateuserdomains script's hooks trigger each time that the system generates a domain list.

Section


Column
width25%

pre hook script:


Column

none



Section


Column
width25%

post hook script:


Column

/scripts/postupdateuserdomains



/scripts/enXim-pkgacct


Panel
bgColor#FFFFFF
borderStylenone

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

These hooks do not trigger for cPanel & WHM-generated cpmove files.


Section


Column
width25%

pre hook script:


Column

/scripts/prepkgacct


This script accepts the following argument:

  • user — The account's username.
Section


Column
width25%

post hook script:


Column

/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


Panel
bgColor#FFFFFF
borderStylenone

The /scripts/restoreacct script's hooks trigger each time that the system restores an account.

Section


Column
width25%

pre hook script:


Column

/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.
Section


Column
width25%

post hook script:


Column

/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


Panel
bgColor#FFFFFF
borderStylenone

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.

Section


Column
width25%

pre hook script:


Column

/scripts/prewwwacct



Section


Column
width25%

post hook script:


Column

/scripts/postwwwacct


In these scripts, the @ARGV array passes in a hash that contains the following data:

Multiexcerpt
MultiExcerptNamewwwacct arguments


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 one and 999999 that represents a disk space quota in Megabytes (MB).
  • 0 — The account possesses 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 possesses a dedicated IP address.
  • n — The account does not possess a dedicated IP address.
n
cgistringWhether the account has CGI access.
  • y — CGI access.
  • nNo CGI access.
y
frontpagestringWhether Microsoft® FrontPage® Extensions exist on the account.
  • y — Installed.
  • nNot installed.

    Note
    titleNote:

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


n
maxftpstringThe account's maximum number of FTP accounts.
  • A positive integer between one and 999,999.
  • 0, unlimited, or null — Unlimited.
0
maxsqlstringThe account's maximum number of SQL databases
  • A positive integer between one and 999,999.
  • 0, unlimited, or null — Unlimited.
0
maxpopstringThe account's maximum number of email addresses.
  • A positive integer between one and 999,999.
  • 0, unlimited, or null — Unlimited.
0
maxlststringThe account's maximum number of Mailman mailing lists.
  • A positive integer between one and 999,999.
  • 0, unlimited, or null — Unlimited.
0
maxsubstringThe account's maximum number of subdomains.
  • A positive integer between one and 999,999.
  • 0, unlimited, or null — Unlimited.
0
bwlimitstringThe account's bandwidth quota.
  • A positive integer between one and 999,999.
  • 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 possesses 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 possesses unlimited addon 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_nameserversstringWhether 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
spamassassinstring

Whether Apache SpamAssassin™ is enabled on the account.

Note
titleNote:

We added this parameter in cPanel & WHM version 70. 


  • y — Enabled.
  • n — Disabled.
y
max_emailacct_quotainteger

The maximum size that the account can define when it creates an email account.

Warning
titleImportant:

If you supply a plan value with this parameter, or use this parameter without the plan value, it overrides the hosting plan's defined value.

We recommend that you allow the account's plan to determine this value.


Note
titleNote:
  • The system uses the plan parameter's value if you use it without the max_emailacct_quota parameter.
  • We introduced this parameter in cPanel & WHM version 70.

This parameter defaults to unlimited.

  • unlimited — The account possesses an unlimited quota.
  • A positive integer between one and 4,294,967,296.
unlimited



User creation


Panel
bgColor#FFFFFF
borderStylenone

The following script hooks trigger each time that the system creates a user.

Section


Column
width25%

pre hook script:


Column

none



Section


Column
width25%

post hook script:


Column

/scripts/postwwwacctuser


This script accepts the following argument:

  • user — The new account's username.

Account modification


Panel
bgColor#FFFFFF
borderStylenone

The following script hooks trigger each time that the system modifies an account.

Section


Column
width25%

pre hook script:


Column

/scripts/premodifyacct



Section


Column
width25%

post hook script:


Column

/scripts/postmodifyacct