Permalink
Browse files

Clean up typos within the standardized hooks code

  • Loading branch information...
1 parent b308dee commit 6510c87b2a146dcff4f14a249fabf5229bde1c1c Matt Dees committed Oct 5, 2011
Showing with 64 additions and 53 deletions.
  1. +7 −5 PasswordLimitations.pm
  2. +6 −6 README.markdown
  3. +34 −30 RollbackHook.pm
  4. +17 −12 StatsLogger.pm
View
@@ -1,11 +1,13 @@
package Example::PasswordLimitations;
-# This implements a custom check for a password where if the length is less than 12, it will deny the event from occuring.
-# This should be considered a standard example of blocking an action from a hook.
+# This implements a custom check for a password where if the length is less than 12, it will deny
+# the event from occuring. This should be considered a standard example of blocking an action from
+# a hook.
#
-# To block an action simply return a value of 0. This value will indicate to the hooks sytem that the event should not be
-# allowed to proceed. In order for an action to be blocked, the hook insertion point (also called context) must indicate
-# that it is blocking. This is told to the underlying subroutine via the 'blocking' key in the $context hash.
+# To block an action simply return a value of 0. This value will indicate to the hooks sytem that
+# the event should not be allowed to proceed. In order for an action to be blocked, the hook
+# insertion point (also called context) must indicate that it is blocking. This is told to the
+# underlying subroutine via the 'blocking' key in the $context hash.
sub passwd_length {
my ( $context, $data ) = @_;
View
@@ -2,26 +2,26 @@ This repo contains examples of how to use the Standardized Hooks system in cPane
It is suggested that you review the Standardized Hooks documentation on http://sdk.cpanel.net/ before reviewing these files.
-# INSTALLATION
+# Installation
WARNING: These hooks will modify the behavior of your cPanel & WHM installation, these should only be installed after the affects of using them is fully understood. *This specifically applies to the "RollbackHook" module which will disable the ability to create accounts.*
-To install these hooks, follow the following instructions:
+Install the example hooks on the cPanel system:
> mkdir -p /var/cpanel/perl5/lib/Example
> cp /path/to/checked/out/modules/*pm /var/cpanel/perl5/lib/Example
-Then to activate a hook:
+Register the hooks with the cPanel system:
> /usr/local/cpanel/bin/manage_hooks add module Example::$modulename
# Information on the Included Libraries
-Each one of these modules implements a set of new functionality in cPanel & WHM. These are intended to be implemented in the simplest way possible.
+Each one of these modules provides new functionality in cPanel & WHM. These are intended to be implemented in the simplest way possible.
## Example::StatsLogger
-This module implements a feature that will make it so a user's log files are copied into their home directory after statistics are processed. This contains in-line information about; how a hook is inserted into the hooks database, the general structure of a hook module, and How to work with statistics processing through the hooks system.
+This module implements a feature that will make it so a user's log files are copied into their home directory after statistics are processed. This contains in-line information about; how a hook is inserted into the hooks database, the general structure of a hook module, and how to work with statistics processing through the hooks system.
## Example::PasswordLimitations
-This module implements a very simple check to ensure that no passwords are created or set with a length less than 12 characters. This module is a simple example of how to deny an event from occurring & and providing a custom error message.
+This module implements a very simple check to ensure that no passwords are created or set with a length less than 12 characters. This module is a simple example of how to deny an event from occurring & providing a custom error message.
## Example::RollbackHook
This module implements a rollback hook, which is a hook that contains logic to back itself out in case a subsequent hook fails.
View
@@ -5,35 +5,38 @@ use Cpanel::DataStore ();
# This module implements an example of a RollbackHook.
# Note: if this module is installed on your server, ACCOUNTS WILL NOT BE ABLE TO BE CREATED.
-# In this example we will Create a log defined by $account_log that specifies where we will store
+# In this example we will create a log defined by $account_log that specifies where we will store
# A YAML datastore of account information. Along with this we will define a rollback hook to remove it
# another hook to display the contents of the log file. finally a hook to deny the event from occuring
# so that the rollback code is triggered.
+# The purpose of the rollback functionality is to allow your hook a way to back out the changes it made.
+# This functionality is critical when writing hooks that deal with external systems, where you may be
+# creating related resources that are only valid for successful cPanel account creation.
+
# Rollback hooks are code that can be executed after a hook is run and a subsequent hook fails.
# For Example:
# 1. Hook1 runs
# 2. Hook2 runs
# 3. Hook3 fails
-#
-# At this point,the standardized hooks sytem will iterate over previously run hooks and check for a 'rollback'
-# attribute that points to another subroutine. So at this point in our stack:
+#
+# At this point,the standardized hooks sytem will iterate over previously run hooks and check for a
+# 'rollback' attribute that points to another subroutine. When the rollback functionality is in use,
+# the order of execution will be:
# 1. Hook1 runs
# 2. Hook2 runs
# 3. Hook3 fails
# 4. Hook2 - no rollback function
# 5. Hook1 - execute rollback function
#
-# This purpose of this system is to allow your hook a way to back out the changes it made. This functionality is
-# critical when writing hooks that deal with external systems where you may be creating an account and the account
-# cannot be recreated.
-#
-# For more information on Rollback hooks, please see the documentation at: http://url/that/is/not/public/yet
+# For more information on Rollback hooks, please see the documentation at:
+# http://url/that/is/not/public/yet
+
+# When working with this hook, it is suggested that you enable "debughooks" option in
+# /var/cpanel/cpanel.config. When # this option is enabled, the hooks system will output a bunch of
+# extra information to /usr/local/cpanel/logs/error_log or STDERR (if used via a shell) about what hook
+# points were passed, what hooks were run, what stage a hook is run in & what data is passed to a hook.
-# When working with this hook, it is suggested that you enable "debughooks" option in /var/cpanel/cpanel.config. When
-# this option is enabled, the hooks system will output a bunch of extra information to /usr/local/cpanel/logs/error_log
-# or STDERR (if used via a shell) about what hook points were passed, what were run, what stage a hook is run in & what data
-# is passed to a hook.
# This feature was used heavily in developing & testing the hooks system.
# See the documentation on how to use this feature at: http://url/that/does/not/exist/yet
@@ -44,7 +47,6 @@ use Cpanel::DataStore ();
# run `bin/manage_hooks add module Example::RollbackHook`
# tail -f /usr/local/cpanel/logs/error_log to watch the hooks roll by.
-
print STDERR "\n\n---\n
\tThe Example::RollbackHook module is installed on this server\n
\tACCOUNTS WILL NOT BE ABLE TO BE CREATED WITH THIS INSTALLED.\n
@@ -67,27 +69,21 @@ sub add_account_to_datastore {
return 1;
}
-# This is the code that is executed after the account creation has been denyied by denied event.
+# This is the code that is executed after the account creation has been denied by deny_event().
sub remote_account_from_datastore {
my ( $context, $data ) = @_;
- $accounts_data = Cpanel::DataStore::load_ref($account_log); # reinstate db
+ $accounts_data = Cpanel::DataStore::load_ref($account_log); # reinstate db
- delete $accounts_data->{ $data->{'user'} }; # Remove entry from db
- Cpanel::DataStore::store_ref( $account_log, $accounts_data ); # Save file
+ delete $accounts_data->{ $data->{'user'} }; # Remove entry from db
+ Cpanel::DataStore::store_ref( $account_log, $accounts_data ); # Save file
return 1;
}
-# This will ensure that the rollback logic is triggered.
-# This will also ensure that accounts can never be created on this server
-sub deny_event {
- return 0, 'This isn\'t allowed because without it, this example would not make a lot of sense';
-}
-
# Display the contents of the accounting file
sub print_contents_of_account_file {
print STDERR "\nDISPLAYING CONTENTS OF $account_log\n\n";
- open ( my $db_fh, '<' ,$account_log ) || return 0, 'Could not obtain lock on log file';
+ open( my $db_fh, '<', $account_log ) || return 0, 'Could not obtain lock on log file';
while ( my $line = readline $db_fh ) {
print STDERR $line;
}
@@ -96,6 +92,12 @@ sub print_contents_of_account_file {
return 1;
}
+# This will ensure that the rollback logic is triggered.
+# This will also ensure that accounts can never be created on this server
+sub deny_event {
+ return 0, 'This isn\'t allowed because without it, this example would not make a lot of sense';
+}
+
sub describe {
my $hook = [
@@ -106,23 +108,25 @@ sub describe {
'stage' => 'pre',
'hook' => 'Example::RollbackHook::add_account_to_datastore',
'rollback' => 'Example::RollbackHook::remote_account_from_datastore',
- 'weight' => 1, # Ensure that this one is run first
+ 'weight' => 1, # Ensure that this one is run first
},
{
'namespace' => 'Whostmgr',
'function' => 'Accounts::Create',
'stage' => 'pre',
'hook' => 'Example::RollbackHook::print_contents_of_account_file',
- 'weight' => 2, # Display the contents of the file.
+ 'weight' => 2, # Display the contents of the file.
},
- # Hook that will always fail so that the rollback code is trigged, remove the hash under this comment
- # to allow an account log to be actually created.
+
+ # Hook that will always fail so that the rollback code is triggered, remove the hash under
+ # this comment to allow an account log to be actually created.
{
'namespace' => 'Whostmgr',
'function' => 'Accounts::Create',
'stage' => 'pre',
'hook' => 'Example::RollbackHook::deny_event',
- 'weight' => 3, #ensure that this is run after the hook that needs to be rolled back.
+ #ensure that this is run after the hook that needs to be rolled back.
+ 'weight' => 3,
},
];
return $hook;
View
@@ -5,29 +5,34 @@ package Example::StatsLogger;
# There are two major parts to a standard hook:
# * The function used to tell the hooks sytstem how it works (the describe method)
-# * The Hooked code (In this case, the copy_logfiles method)
+# * The Hooked code (in this case, the copy_logfiles method)
# The Describe Method
-# When this hook is installed it is run with '/usr/local/cpanel/bin/manage_hooks add module Example::StatsLogger`.
+# This hook can be activated by executing '/usr/local/cpanel/bin/manage_hooks add module Example::StatsLogger`.
# At this point the describe method within this hook is invoked, the data structure that is returned is parsed
# and placed into the hooks database.
# The Hooked Code
-# This is the code where a hook's logic is kept. It is passed 2 parameters:
+# This is the code where a hook's logic is kept. The hook system is made aware of a hook by the information returned
+# from describe() It is passed 2 parameters:
# * The Context - Describes where the hook is being called from
# * Args - The data passed from the code calling it
-# These two pieces of data are documented in full in the "Hook insertion point" documentation, available at url/that/does not/exist/yet
-#
-# In this example, we are taking the information passed in the data that is passed to the hook in the $data string
-# and acting upon it so that we can copy files to the user's homedirectory.
+# These two pieces of data are documented in full in the "Hook insertion point" documentation, available at
+# url/that/does not/exist/yet
-# In some hook insertion points, it's important to note which user is executing the hook. In this case, the hook is run by the user itself
-# rather than executed by root. In cases where you are running code as root, it is important to not perform file operations on files under
-# The user's control, the Cpanel::AccessIds module offers a few methods that address this concern.
+# In this example, the hook system will proxy the attributes related to domlog processing to copy_logfiles() so the
+# respective log files can be copied to the user's homedirectory when domain log statistics run. Because the
+# describe() hash element 'stage' is defined as 'post' the hook action will occur after the various statistic engines
+# parse the log files but prior to the end the larger cPanel operation.
+
+# In some hook insertion points, it's important to note which user is executing the hook. In this case, the hook is
+# run by the user itself rather than executed by root. In cases where you are running code as root, it is important
+# to not perform file operations on files under the user's control, the Cpanel::AccessIds module offers a few methods
+# that address this concern.
# This is the describe subroutine.
-# This subroutine is used by /usr/local/cpanel/bin/manage_hooks
-# so that the hooks database can be properly populated.
+# This subroutine is used by /usr/local/cpanel/bin/manage_hooks to populated the hooks database. Every standard hook
+# MUST have this subroutine.
sub describe {
my $hooks = [
{

0 comments on commit 6510c87

Please sign in to comment.