You can find our user documentation at

Check out our new API beta site!

Child pages
  • Guide to Standardized Hooks - Universal Password Trap
Skip to end of metadata
Go to start of metadata


The universal password trap hook triggers each time a user's password changes.

 This hook triggers regardless of which method changed the password, and regardless of whether the account is a cPanel or WHM account.


This hook method is deprecated and cPanel, L.L.C. will remove it in cPanel & WHM version 88. To convert function hooks to use the Standardized Hooks system, use the API::Module::function Cpanel event or the Passwd event in your Hook Action Code.

Basic usage

To use the universal password trap hook, perform the following steps:

  1. Write a custom module that contains a process() subroutine.
  2. Store your custom module in the /usr/local/cpanel/Cpanel/ChangePasswd/ directory.

The system attempts to run the process() subroutine for each module file in the /usr/local/cpanel/Cpanel/ChangePasswd/ directory each time that a password changes.


If your script writes to a file, you must create that file before the script runs. 

Module variables


Only transmit or store these variables over an SSL/TLS-encrypted connection. Storage or transmission of password information in plain text is a huge security risk.

Your module can access the following variables:

VariableTypeDescriptionPossible valuesExample
userstringThe account's username.A valid username.username
newpassstringThe account's new password.A secure password.12345luggage
messagestringA status message about the password change process.A valid string.The password changed successfully.
rawoutstringRaw output from the password change process.A valid string.Changing system password for user username.
service_refstringThe cPanel product that changed the password.
  • cPanel
  • WHM
applistarray of hashes

An array of hashes of the services that cPanel & WHM checks whenever a password changes.

An array of hashes of service information.


If the user chose not to update their MySQL® password, the applist value will not list MySQL information. 

 Click to view...
$VAR1 = [ { 'app' => 'system' }, { 'app' => 'ftp' }, { 'app' => 'mail' }, { 'app' => 'mySQL' }]


 Click to view an example Perl module...
# This module will be run as ROOT. If you do not understand the security implications of running 
# this module as root, do not use this module.
# cPanel & WHM calls modules in the /usr/local/cpanel/Cpanel/ChangePasswd/* directory when a user 
# changes their password in cPanel or WHM. This allows you to update your databases or third party
# app with the new password.
# To use this module, move it to /usr/local/cpanel/Cpanel/ChangePasswd/,
# where SampleModule is the name of your module.
package Cpanel::ChangePasswd::SampleModule;
use strict;
# You may use non-XS modules here if they are in @INC (/usr/local/cpanel, /usr/local/cpanel/perl).
# use XXX
sub process {
    my %OPTS = @_;
    my $user = $OPTS{'user'};
    my $newpass = $OPTS{'newpass'};
    my $message = $OPTS{'message'};         
    my $rawout = $OPTS{'rawout'};   
    my $service_ref = $OPTS{'service_ref'};        
    $rawout =~ s/[\n\r]/ /g;
    $message =~ s/[\n\r]/ /g;
    my @SRVLIST;
    sysopen( my $pw_changelog_fh, '/var/cpanel/password_change.log', &Fcntl::O_WRONLY | &Fcntl::O_CREAT | &Fcntl::O_APPEND, 0600 );
    print {$pw_changelog_fh} "$user:$newpass:$message:$rawout:";
    foreach my $service (@{$service_ref}) {
        push @SRVLIST,$service->{'app'};
    print {$pw_changelog_fh} join(',',@SRVLIST) . "\n";

 Click to view an example Perl wrapper...
package Cpanel::ChangePasswd::WrapperModule;
use strict;
sub process {
    my %OPTS    = @_;
    my $user    = $OPTS{'user'};
    my $newpass = $OPTS{'newpass'};
    my $message = $OPTS{'message'};         
    my $rawout  = $OPTS{'rawout'};          
    my $applist = $OPTS{'applist'};    
    $rawout  =~ s/[\n\r]/ /g;
    $message =~ s/[\n\r]/ /g;
    foreach my $app ( @{$applist} ) {
        if ( $app->{'app'} =~ m/mysql/i ) {
            my $path   = '/usr/local/cpanel/Cpanel/ChangePasswd';
            my $script = 'change_password.php';
            system( 'php', '-f', "$path/$script", $user, $newpass );