Child pages
  • Guide to Standardized Hooks - The manage_hooks Utility

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Introduction

Excerpt
Use the /usr/local/cpanel/bin/manage_hooks Command Line Interface (CLI) 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 this utility in some capacity.

Synopsis

This utility uses the following syntax:

Code Block
languagetext
bin/manage_hooks [action] [type] [reference] [options]

This syntax uses the following arguments:

VariableDescriptionPossible valuesExample
[action]

The action to perform.

Note
titleNote:

Exercise caution when you use the --action option with scripts. If you do not correctly pass 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 — Register a hook.
  • delete — Deregister (remove) a hook.
  • describe — Describe a hook's action.
  • 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.
  • update_db — Update a hook's database.

    Note
    titleNote:
    • We removed the update_db action in cPanel & WHM version 78.
    • 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
[type]

The hook action code's type.

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

  • script — The hook action code is a script.
  • module — The hook action code is a perl 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.

Warning
titleImportant:

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

Anchor
Options
Options
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.

--stage post
--rollback

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

For more information, read our Rollbacks documentation.

Warning
titleImportant:

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.

Warning
titleImportant:

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 points higher than the highest existing value.

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

Any 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
titleNote:

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 use 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
titleNote:

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


Anchor
list
list
List action output

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

Code Block
[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
titleNote:

These examples do not use the describe() method. 

Add a hook

The module does use the describe() method:

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

The module does not use the describe() method:

Code Block
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:

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

The module does not use the describe() method:

Code Block
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:

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

The script does not use the describe() method:

Code Block
languagebash
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:

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

The script does not use the describe() method:

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