Developer Documentation
Child pages
  • Guide to Standardized Hooks - Script Hooks
Skip to end of metadata
Go to start of metadata

Guide to Standardized Hooks 

Hookable Events

ConvertAddon Functions

Cpanel Functions

PkgAcct Functions

Passwd Functions

RPM::Versions Functions

Stats Functions

System Functions

Whostmgr Functions

Hook Action Code

The describe() Method

The manage_hooks Utility

Debug Mode

Advanced Use

Rollbacks

Checks

Exceptions

Privilege Escalation

Hookable Events in Custom Modules

Deprecated Systems

Custom Event Handlers

Function Hooks

Script Hooks

Universal Password Trap

 

 

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.

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:

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 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 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.
  • n — No CGI access.
y
frontpagestringWhether Microsoft® FrontPage® Extensions exist on the account.
  • 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.
  • 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:

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.

Important:

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:

  • 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

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:
    Manage Hooks
  • 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/debughooks file 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 the cpsrvd daemon:

    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.