Child pages
  • Guide to Standardized Hooks - Function Hooks
Skip to end of metadata
Go to start of metadata

 

Introduction

Function hook scripts run automatically, after a specific cPanel API function. You can associate each hook with a single cPanel API 1 or cPanel API 2 function. Because function hooks run after an API function, they cannot block or modify events on the server. 

Warning:

This hook method is deprecated. To convert function hooks to use the Standardized Hooks system, use the API::Module::function Cpanel event in your Hook Action Code.

Basic usage

To create a function hook, perform the following steps:

  1. Write a function hook script.
  2. Store the function hook script in the /usr/local/cpanel/hooks/module/function/ directory, where module is the cPanel API 1 or cPanel API 2 module name, and function is the function name.
    • For example, store a script that runs after the Email::addpop function in the /usr/local/cpanel/hooks/Email/addpop/ directory.
  3. Run the  /usr/local/cpanel/bin/register_hooks script to register the function hook.
    • Run this script every time that you add a new hook script or modify an existing hook script.
    • This script cannot register scripts that have incorrect file permissions.

Scripts

You can write function hook scripts in any programming language.

Warning:

  • Function hook scripts run as the root user.
  • You must set script file permissions to 0700.
  • Function hook scripts cannot produce output. You must silence any header content that your script's interpreter generates.

The system sends two types of data to STDIN whenever it runs a function hook script:

  1. The input parameters from the associated function call, in <cpanelevent> tags.
  2. A hash of user data, in <CPDATA> tags. This data includes the contents of the user's file in the /var/cpanel/users/ directory.

Example XML data  

 Click to view...

The following XML data is an example of the input that a function hook script could receive from STDIN:

<xml>
<cpanelevent>
  <errors></errors>
  <event>addpop</event>
  <module>email</module>
  <params>
    <param0>emailuser</param0>
    <param1>emailpassword</param1>
    <param2>250</param2>
    <param3>testdomain.com</param3>
  </params>
</cpanelevent>
 
<CPDATA>
  <BWLIMIT>unlimited</BWLIMIT>
  <CONTACTEMAIL></CONTACTEMAIL>
  <CONTACTEMAIL2></CONTACTEMAIL2>
  <DEMO>0</DEMO>
  <DOMAIN>testdomain.com</DOMAIN>
  <FEATURELIST>default</FEATURELIST>
  <HASCGI>1</HASCGI>
  <IP>192.168.1.1 </IP>
  <LANG>english</LANG>
  <MAXADDON>100</MAXADDON>
  <MAXFTP>100</MAXFTP>
  <MAXLST>100</MAXLST>
  <MAXMONGREL>4</MAXMONGREL>
  <MAXPARK>100</MAXPARK>
  <MAXPOP>unlimited</MAXPOP>
  <MAXSQL>100</MAXSQL>
  <MAXSUB>100</MAXSUB>
  <OWNER>root</OWNER>
  <PLAN>default</PLAN>
  <RS>paper_lantern</RS>
  <STARTDATE>1244646861</STARTDATE>
  <USER>testdoma</USER>
</CPDATA>
</xml>

Example Perl script

 Click to view...

Warning:

Do not run this type of script on a production server. Password logging is a severe security risk. 

The following Perl script uses the XML data from STDIN to create a log of new email accounts and passwords in the /root/email_password_log file.

#!/usr/bin/perl
 
use strict;
use warnings;
 
use XML::Simple;
use Data::Dumper;
 
my $xml;
 
while (<STDIN>) {
        $xml .= $_;
}
 
my $xml_hashed = XMLin($xml);
 
my $username = $xml_hashed->{'cpanelevent'}->{'params'}->{'email'} . '@' . $xml_hashed->{'cpanelevent'}->{'params'}->{'domain'};
my $password = $xml_hashed->{'cpanelevent'}->{'params'}->{'password'};
 
open(my $fh, ">>", "/root/email_password_log");
print {$fh} "Email Account Created:\n";
print {$fh} "\tusername: $username\n";
print {$fh} "\tpassword: $password\n\n";
close($fh);

Example PHP code

 Click to view...

Important:

Do not read input from STDIN through a CGI application. You must treat this input as a CLI application.

To do this, add the following shebang line to the top of your PHP script:

#!/usr/bin/php-cgi -q

The following PHP code retrieves input from STDIN :

<?php
$stdin_fh = fopen('php://stdin', 'r');
while ($line = fgets( $stdin_fh )) {
    $xml_string .= $line;
}
fclose($stdin_fh);
?>