CustomEventHandler

A CustomEventHandler is a powerful tool that allows you to access operations triggered by the cPanel interface.

As actions are performed within the cPanel interface, API events are called. Before and after each API function runs, the API function searches for a custom event handler as part of its operating process. This allows you to create custom event handlers as pre and post event handlers, meaning that an action is taken prior to an event (pre) or an action is taken after a specific event (post).

Warning: If there are any coding errors within CustomEventHandler.pm the operation will fail.

Remember: If you require a less dangerous and programming language-agnostic solution, you should look into cPanel function hooks. Hook scripts only allow for API2 functions. Stub files indicating hook calls can be found in the sub-directories of /usr/local/cpanel/hooks as files with names similar to *.example.

CustomEvenHandler.pm will need to be created as:

• usr/local/cpanel/Cpanel/CustomEventHandler.pm
  • Remember: This file does not exist by default. You must create the file.

An example CustomEventHandler.pm is located at:

• /usr/local/cpanel/Cpanel/CustomEventHandler.pm.sample

The event() Function

event() is the function within CustomEventHandler.pm that is called when an API1 or API2 call is made within cPanel.

The event() function will be passed the following types of parameters:

• type (string) — The first parameter passed to the module to indicate at what point the API function will run the custom event handler. This parameter will only accept one of the following 2 options as input:
  • pre — Passed to the custom event handler before the API action is performed. This would be used when changing parameters or denying an event.
  • post — Passed after the API action has occurred. This should be used for reading events or modifying the data returned from the event.

• module (string) — The name of the module in which the events are being executed.
  • Example: email

• event (string) — The name of the API function being called.
  • Example: addforward

• cfgref (hash reference) — A hash of the variables passed to the event that function as the API's input parameters.
  • Example: $cfgref->{'fwdemail'} — If email forwarding was the selected option, this hash would contain the email address to which mail will be forwarded.

• dataref (hash reference) — Used in post events. This parameter contains data returned from the API call. In a scenario where the type variable is set to post, this can be used to modify data sent to the interface.
  • Note: In the event that no data is returned by the API call, this parameter will be an empty array.

Remember: event() will be called twice for every API call made: once before the API call and once after the API call.

Important: The value returned by the event will determine whether or not the API call actually occurs. If event() returns 0, undef, a negative number or a blank string when the type parameter is set to pre, the API call will be skipped. In this case, an error will not be raised unless it is explicitly set to do so. By default, event() should return a value of 1.

Important Considerations

CustomEventHandler.pm is parsed by cpsrvd. cpsrvd parses Perl files using an embedded Perl 5.6.2 interpreter with its own module paths. Non-standard modules need to be installed in /usr/local/cpanel/perl.

Any module in /usr/local/cpanel/Cpanel/ is available through the Cpanel:: namespace. All interactions performed by a custom event handler are performed as the user running the API calls. This is important because any file receiving output needs to be writable by all users.

Remember: Most custom event handlers should be filtered by module, function, and type so that they are not run each time an API call is made.

Determining an API Call

Please view API1 and API2's reference material. As a result, you may want to install a debugger version of the custom event handler. You can download the debugger version of CustomEventHandler.pm. To install and use the debugger, follow the instructions contained within the README file. You will need to be familiar with Data::Dumper in order to understand the information that is returned by the debugger. If you require assistance working with the debugger, please refer to the cPanel forum's Developer Corner.

Error Handling

There are a few ways to raise errors within a custom event handler. Most require you to know and understand the API function you are working with and how you would like to raise the error. Some API calls contain a special variable called $Cpanel::CPERROR that allows you to raise an error in the interface similar to errors received, for example, when creating an email account that already exists.

In order to raise the error, you will need to define the context. This is normally set automatically in the $CPanel::context variable. Otherwise, this variable usually contains the module's name in lowercase.

$Cpanel::CPERROR{$Cpanel::context} = "This is an error message"; 

Remember: This is not available to all API calls. If the cPanel interface is capable of throwing an error (such as when a email account is created with a name that already exists), you can set this variable.

You may also raise an error by logging information in the error_log. You can accomplish this by printing to STDERR within your CustomEventHandler.pm. For example:

print STDERR "This is another error message"; 

Note: If you wish to prevent the API function from being completed when an error is received, you will need to have event() return a negative value.

To learn more about how to raise errors in a custom event handler, visit our Cpanel::Logger documentation here.

Example

Denying Events

The following piece of code implements an email blacklist in an account. It will deny all users named support or abuse and raise an error stating these values are reserved usernames.

Download Example

sub event {
    my ( $apiv, $type, $module, $event, $cfgref, $dataref ) = @_;
    return 1 if $module ne "email" || $event ne "addpop";    # Filter out non-email:addpop requests

    my @blacklist = ( "abuse", "support" );    # setup the black list

    if (   $module eq 'email' && $event eq 'addpop' && $type eq 'pre' && ref $cfgref->{'param0'} eq 'ARRAY' )
    {    # determine that the event passed is the correct event
        my $username = $cfgref->{'param0'}->[0];    # Define which variable is the user name

        if ( grep( /$username/, @blacklist ) )
        {                              # if the username is in the blacklist
            $Cpanel::CPERROR{$Cpanel::context} = "Sorry, $username is a reserved username";    # Throw an error
            return;    # tell email::addpop not to proceed
        }
    }
    return 1;          # in every other case, allow the event to proceed
}