Child pages
  • Guide to Standardized Hooks - The manage_hooks Utility
Skip to end of metadata
Go to start of metadata

 

Introduction

Use the manage_hooks utility to connect (register) the hook action code with the event. This utility uses Standardized Hooks System descriptors and a reference to hook action code in order to modify registry entries in the Standardized Hooks database.

Two methods exist to provide registration information to the utility:

  • Provide registration information manually through the command line when you call the manage_hooks utility.
  • Use the describe() method to include registration information in the hook action code itself. 

Either method requires that you use the manage_hooks utility in some capacity.

Synopsis

The bin/manage_hooks utility uses the following syntax:

bin/manage_hooks [action] [type] [reference] [options]

This syntax uses the following arguments:

VariableDescriptionPossible valuesExample
[action]

The action to perform.

Note:

The update_db action exists for hook databases in cPanel & WHM version 11.32.1 and earlier.

In cPanel & WHM version 11.34 and later, the update_db action is not necessary.

  • add — Register a hook.
  • delete — Deregister (remove) a hook.
  • list — List a category's registered hooks. For an example of this action's output, read the List action output section.
  • fullhelp— Display help information for the utility.

Note:

When you use the  --action  descriptor option with scripts, pay particular attention to how the value is presented. If you do not properly express a value, the utility may misinterpret that value as a description option switch.

This only occurs for values that lead with one or more hyphens.

add
[type]

The hook action code's type.

Use this value if the [action] value is add or delete

  • script
  • module
script
[reference]

The hook action code's location.

Use this value if the [action] value is add or delete

  • For scripts, the script's absolute path and filename.
  • For Perl modules, the Perl module's package value.
/myhook
[options]

The desired options.

Important:

If you did not include the describe action in the hook action code, you must include the --category and --event options.

One or more options, in --option value format.

For a list of possible options, read the Options section below.

--category System

Options

OptionsDescriptionPossible valuesExample
--category

The hookable event's category.

If the hook action code does not include the describe method, this option is required

--category Whostmgr
--event

The hookable event name.

If the hook action code does not include the describe method, this option is required

See the desired category's documentation for a list of available events.

--event Accounts::Remove
--stage

When the hook action code executes.

See the desired category's documentation for a list of available stages.

post
--rollback

Additional hook action code to execute when another Standardized Hook that is associated with this event fails.

For more information, read our Rollbacks documentation.

Important:

This option only applies to events with the blocking attribute.

  • For scripts, the script's absolute path and filename.
  • For Perl modules, the Perl module's package value.
--rollback Boo::rollback
--escalateprivs

Whether to escalate the user to root-level privileges before the hook action code executes.

Important:

This option only applies to events with the escalateprivs attribute.

  • 1 — Escalate the user's privileges.
  • 0 — Do not escalate the user's privileges.
--escalateprivs 1
--weight

The hook's priority order. If multiple hooks are registered for the same stage of an event, this value determines which hook action code runs first.

By default, the system assigns the first Standardized Hook that registers with a specific event a weight of 100. Subsequent hook weights default to a value that is 100 higher than the heighest existing value.

A positive integer that represents the hook's priority order.--weight 555
--check

Additional hook action code to execute before the primary hook action code executes.

If the check action code fails, the primary hook action code will not run.

For more information, read our Checks documentation.

  • For scripts, the script's absolute path and filename.
  • For Perl modules, the Perl module's package value.
--check Boo::are_you_sure
--manual

Whether the utility should use only the options that you provide to the utility from the CLI.

This value defaults to 0.

Note:

If the system cannot find any describe method information, it will attempt to use CLI options. 

  • 1 — Use the CLI options. Select this option if hook action code does not usee the describe method.
  • 0 — Use registration information from the describe method.
--manual 1
--actionAn additional hook action.
  • add — Register a hook.
  • delete — Deregister (remove) a hook.
  • list — List a category's registered hooks.
  • fullhelp— Display help information for the utility.
--action add
--output

The output type to use.

This option defaults to HUMAN.

Note:

Use this option with the list action. 

  • HUMAN — Display the list of hooks in human-readable format.
  • JSON — Display the list of hooks in a JSON serialization.
--output HUMAN
--helpPrint basic help information to STDOUT.No value.--help


List action output

The list action returns output that is similar to the following example:

[usr/local/cpanel/bin] $ ./manage_hooks list
Cpanel:
   Api2::StatsBar::stat:
      stage: pre
      weight: 1000
                id: rA73DrbGgM8QXvypjRkvsuLL
      exectype: module
      hook: MyApp::TestStatsBar
Whostmgr:
   Accounts::Create:
      stage: post
      escalateprivs: 0
      weight: 1000
                      id: OtAWTxns6w1wuIGTCmdnydcX
      exectype: script
      hook: /var/cpanel/myapp/testhook_post.php
      --
      stage: pre
      escalateprivs: 0
      weight: 1000
                      id: au9Pf6EdpOKNtWjrQKW_1IZC
      exectype: script
      hook: /var/cpanel/myapp/testhook_pre.php

In this example:

  • The MyApp::TestStatsBar Perl module subroutine in the /var/cpanel/perl5/lib/MyApp.pm file executes the cPanel API 2 StatsBar::Stat function.
  • A PHP script in the /var/cpanel/myapp/testhook_post.php file will execute after you create cPanel accounts. This script will run regardless of the method that you use to create the account (for example, the WHM interface or the /usr/local/cpanel/scripts/wwwacct script).

Perl module examples

The following sections illustrate how to manually add and delete Standardized Hooks with hook action code in a Perl module.

  • These examples assume that the /var/cpanel/perl5/lib/MyApp/ directory contains the WHM.pm module file. 
  • This module contains the  remove()  subroutine that is called prior to an account's removal from the system.

Note:

These examples do not use the describe() method. 

 

Add a hook

The module does use the describe() method:

usr/local/cpanel/bin/manage_hooks add module MyApp::WHM

The module does not use the describe() method:

usr/local/cpanel/bin/manage_hooks add module MyApp::WHM --manual --category Whostmgr --event 'Accounts::Remove' --stage pre --action remove 

Remove a hook

The module does use the describe() method:

usr/local/cpanel/bin/manage_hooks delete module MyApp::WHM

The module does not use the describe() method:

usr/local/cpanel/bin/manage_hooks delete module MyApp::WHM --manual --category Whostmgr --event 'Accounts::Remove' --stage pre --action remove 

Script examples

The following sections illustrate how to manually add and delete a Standardized Hook with hook action code in a script.

  • These examples assume that the  /var/cpanel/myapp/  directory contains the  whm.php  script. 
  • Inside this script, there is logic that can interpret command line arguments, to which a  --do_remove  switch is honored. 
  • The system will call the  /var/cpanel/myapp/whm.php --do_remove  function prior to an account's removal from the system.

Add a hook

The script does use the describe() method:

usr/local/cpanel/bin/manage_hooks add script /var/cpanel/myapp/whm.php

The script does not use the describe() method:

usr/local/cpanel/bin/manage_hooks add script /var/cpanel/myapp/whm.php --manual --category Whostmgr --event 'Accounts::Remove' --stage pre --action='--do_remove'

Remove a hook

The script does use the describe() method:

usr/local/cpanel/bin/manage_hooks delete script /var/cpanel/myapp/whm.php

The script does not use the describe() method:

usr/local/cpanel/bin/manage_hooks delete script /var/cpanel/myapp/whm.php --manual --category Whostmgr --event 'Accounts::Remove' --stage pre --action='--do_remove'