cPanel & WHM Script Hooks

Introduction

cPanel & WHM script hooks allow for custom code to be executed for certain system-level operations such as account modifications, installation of server software, and backup runs.

Most script hooks are created by placing a shell script (in any language you wish) inside of the /scripts/ directory. If any data is passed into the script, it will be passed via @ARGV. These scripts are always executed by the root user.

PICK Remember: There are two categories of script hooks: pre hooks and post hooks.

  • Pre hooks are executed at the beginning of the script.
  • Post hooks are executed at the end of the script's execution.

Available script hooks

Accounting script hooks

Script
(located in /scripts)
Arguments Description
postcpbackup None Runs after cPanel backup
(post /scripts/cpbackup).
prekillacct See below Runs before account termination
(pre /scripts/killacct).
postkillacct See below Runs after account termination
(post /scripts/killacct).
Note: Parse as a hash, since
killdns or user could change order.
presuspendacct user— The suspended account's username
reason — The reason for the account's suspension
Runs before an account is suspended
(pre /scripts/suspendacct).
postsuspendacct user— The suspended account's username
reason — The reason for the account's suspension
Runs after an account is suspended
(post /scripts/suspendacct).
preunsuspendacct user — The name of the account to be unsuspended Runs before an account is unsuspended
(pre /scripts/unsuspendacct).
preupcp None Runs before cPanel & WHM updates
(post /scripts/upcp).
postupcp None Runs after cPanel & WHM updates
(post /scripts/upcp).
postupdateuserdomains None Runs after generation of the domain list
(post /scripts/updateuserdomains).
postunsuspendacct user — The username corresponding to the account that has been unsuspended. Runs after an account is unsuspended
(post /scripts/unsuspendacct).
prepkgacct user — The username corresponding to the account that will be packaged. Runs before an account is packaged into a cpmove file.
(pre /scripts/pkgacct)
postpkgacct split/nosplit — Specifies whether the cpmove archive is split into multiple files or is contained in a single file.
user — The new (local) cPanel user name
remoteuser — The original (remote) username
directory — The directory that contains the cpmove archive.
Runs after an account is packaged into a cpmove file.
(post /scripts/pkgacct)
prerestoreacct user — The new (local) cPanel username
remoteuser — The old (remote) username
extractdirectory — The directory to which the cpmove archive will be extracted.
Runs before an account is restored.
(pre /scripts/restoreacct)
postrestoreacct user — The new (local) cPanel username
remoteuser — The old (remote) username
domain — The restored account's main domain
directory — The new account's home directory
Runs after an account is restored.
(post /scripts/restoreacct)
prewwwact See below Runs before account creation
(pre /scripts/wwwacct).
postwwwacct See below Runs after account creation
(post /scripts/wwwacct).
postwwwacctuser user — The username corresponding to the account that was created. Runs after user creation

More about /scripts/postwwwacct & /scripts/prewwwacct

These scripts will run either before ( prewwwacct) or after ( postwwwacct) an account is created.

Within these scripts, a hash consisting of the following data is passed via ARGV to the hook script:

  • user (string) — User name of the account. Example: user
  • domain (string) — Domain name. Example: domain.tld
  • plan (string) — Package to use for account creation. Example: reseller_gold
  • quota (integer) — Disk space quota in MB.
    • Possible values: 0-999999.
    • 0 is unlimited.
  • pass (string) — Password to access cPanel. Example: p@ss!w0rd$123
  • useip (string) — Whether or not the domain has a dedicated IP address.
    • y — yes.
    • n — no.
  • hascgi (string) — Whether or not the domain has cgi access.
    • y — yes.
    • n — no.
  • installfp (string) — Whether or not the domain has FrontPage extensions installed.
    • y — yes.
    • n — no.
  • hasshell (string) — Whether or not the domain has shell/SSH access.
    • y — yes.
    • n — no.
  • contactemail (string) — Contact email address for the account. Example: user@otherdomain.tld
  • cpmod (string) — cPanel theme name. Example: x3
  • maxftp (string) — Maximum number of FTP accounts the user can create.
    • Possible values: 0-999999, unlimited, and null
    • 0 is unlimited.
  • maxsql (string) — Maximum number of SQL databases the user can create.
    • Possible values: 0-999999, unlimited, and null
    • 0 is unlimited.
  • maxpop (string) — Maximum number of email accounts the user can create.
    • Possible values: 0-999999, unlimited, and null
    • 0 is unlimited.
  • maxlst (string) — Maximum number of mailing lists the user can create.
    • Possible values: 0-999999, unlimited, and null
    • 0 is unlimited.
  • maxsub (string) — Maximum number of subdomains the user can create.
    • Possible values: 0-999999, unlimited, and null
    • 0 is unlimited.
  • maxpark (string) — Maximum number of parked domains the user can create.
    • Possible values: 0-999999, unlimited, and null
    • 0 is unlimited.
  • maxaddon (string) — Maximum number of addon domains the user can create.
    • Possible values: 0-999999, unlimited, and null
    • 0 is unlimited.
  • bwlimit (string) — Bandiwdth limit in MB.
    • Possible values: 0-999999, unlimited, and null
    • 0 is unlimited.
  • useregns (boolean) — Whether to use the registered nameservers for the domain instead of the ones configured on the server.
    • 1 — yes.
    • 0 — no.
  • owner (string) — Owner of the account.

If you need infomation about accessing the data passed to postwwwacct or prewwwacct, please see the section on converting hashes passed via ARGV.

More about /scripts/postkillacct

This script runs after an account is terminated.

It is called with its parameters in a hash:

/scripts/postkillacct %OPTS 

Parameters:

  • OPTS{'user'} — Username of the terminated account.
  • OPTS{'killdns'} — Whether the zone files were deleted during account termination. This is a boolean variable and will either be 1 (yes) or 0 (no).

Service script hooks

noteNote: None of the following hook scripts accept any arguments.

Script
(located in /scripts)
Description
precourierup Runs before Courier updates
(pre /scripts/courierup)
postcourierinstall Runs after Courier updates
(post /scripts/courierup)
postcourierup Runs after Courier updates
(post /scripts/courierup)
postcourier-authlibup Runs after courier-authlib package updates
postcourier-imapup Runs after courier-imap package updates
predovecotup Runs before Dovecot updates
(pre /scripts/dovecotup)
postdovecotup Runs after Dovecot updates
(post /scripts/dovecotup)
predovecotup Runs before Dovecot updates
(pre /scripts/dovecotup)
preeximup Runs before Exim updates
(pre /scripts/eximup)
posteximup Runs after Exim updates
(post /scripts/eximup)
preftpup Runs before FTP updates
(pre /scripts/ftpup)
postftpinstall Runs after FTP server updates
(post /scripts/ftpup)
postftpup Runs after FTP server updates
(post /scripts/ftpup)
premysqlup Runs before MySQL updates
(pre /scripts/mysqlup)
postmysqlinstall Runs after MySQL updates
(post /scripts/mysqlup)
postmysqlup Runs after MySQL updates
(post /scripts/mysqlup)
prensdup Runs before NSD updates
(pre /scripts/nsdup)
postnsdup Runs after NSD updates
(post /scripts/nsdup)

Converting hashes passed via ARGV

Some of script hooks will be passed a hash via ARGV, meaning that the script will be called from the command line in a similar method to:

/scripts/$hookname user $user password $password

This will need to be converted into a usable data structure (see below).

Perl

my %OPTS = @ARGV 

Now %OPTS will be a normal Perl hash containing the data, so it can be accessed as follows:

my $username = $OPTS{'user'}; 

$username will now contain the value of $user.

PHP

PHP is a little more complicated for accessing this type of information. The following function will take $argv and 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; } 

When calling this, it needs to be passed $argv. So, you will call it as follows:

$opts = argv2array($argv); 

Now, you can access the username like so:

$opts['user']; 
Topic revision: r11 - 21 Mar 2011 - 21:33:28 - Main.JustinSchaefer
DevHooks.ScriptHooks moved from AllDocumentation/AutomationIntegration.ScriptHooks on 23 Jul 2009 - 18:42 by Main.JustinSchaefer - put it back