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_hooksutility. - 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:
|
Variable |
Description |
Possible values |
Example |
|
[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. |
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 |
|
[reference] |
The hook action code's location. Use this value if the [action] value is add or delete. |
|
/myhook |
|
[options] |
The desired options. Important: If you did not include thedescribe 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
|
Options |
Description |
Possible values |
Example |
|
--category |
The hookable event's category. If the hook action code does not include the describemethod, this option is required. |
|
--category Whostmgr |
|
--event |
The hookable event name. If the hook action code does not include the describemethod, 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 blockingattribute. |
|
--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 theescalateprivs attribute. |
|
--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 100higher 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. |
|
--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. |
|
--manual 1 |
|
--action |
An additional hook action. |
|
--action add |
|
--output |
The output type to use. This option defaults to HUMAN. Note: Use this option with the list action. |
|
--output HUMAN |
|
--help |
Print 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 listCpanel: Api2::StatsBar::stat: stage: pre weight: 1000 id: rA73DrbGgM8QXvypjRkvsuLL exectype: module hook: MyApp::TestStatsBarWhostmgr: 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::TestStatsBarPerl module subroutine in the/var/cpanel/perl5/lib/MyApp.pmfile executes the cPanel API 2StatsBar::Statfunction. - A PHP script in the
/var/cpanel/myapp/testhook_post.phpfile 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/wwwacctscript).
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 theWHM.pmmodule 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 thewhm.phpscript. - Inside this script, there is logic that can interpret command line arguments, to which a
--do_removeswitch is honored. - The system will call the
/var/cpanel/myapp/whm.php --do_removefunction 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' |