How To: Enable and Use the Event Hooks Plugin

The Event Hooks plugin allows for automation of actions based on the successful completion of other actions. This can allow for some very powerful automation of tasks that aren’t part of the InterWorx code base. Additionally, Event Hoooks can be used to handle otherwise mundane tasks that system administrators would prefer to not worry about.

Note

This example automatically enables specific versions of PHP for a newly created SiteWorx account. The PHP versions must already be installed onto the server via the Webserver page in NodeWorx.

Detailed instructions on how to install and use multiple PHP with InterWorx can be found here.

Enabling the Plugin

  1. Log into NodeWorx, and navigate to NodeWorx > Plugins

  2. Click the Pencil Icon (edit) next to Event Hooks under the Advanced heading

  3. In the popup, select Enabled from the dropdown, and update the Hook Configuration File field with the name and location of the file that contains the configuration details for the event hook

    • The default file name and location is /etc/iworx-hooks.conf

../../_images/event-hook-plugin.png

Creating the Configuration File

  1. Log in to the server at the CLI as root, either via SSH or from the terminal

  2. Using the text editor of choice, create the Event Hooks configuration file with the name and location that was specified in the Hook Configuration File field when enabling the plugin

    • For this example, the vim text editor and the default file name and location will be used

      vim /etc/iworx-hooks.conf

  3. Add the contents of the sample file, below, to the iworx-hooks.conf file:

    # Sample hooks file content
#
# Comments start with pound
#
# Empty lines are fine
#
# Non-empty lines have a minimum of 3 components: Controller, Action, and Script + optional parameters
#
# NOTE 1: This file must be readable by the 'iworx' user
#         and your custom scripts must be executable by the iworx user.
#         They will run as the 'iworx' user, not as root.
#
# NOTE 2: Form variables for the hooked events will be available to your script
#         as environment variables, prefixed with 'iw_'

# run my script after a siteworx account gets added
#Ctrl_Nodeworx_Siteworx add /myscripts/siteworx-account.sh

# run with the --delete parameter after a siteworx account gets deleted
#Ctrl_Nodeworx_Siteworx delete /myscripts/siteworx-account.sh --delete

# run my pointer-added.sh script
#Ctrl_Siteworx_DomainsPointer add /usr/local/bin/pointer-added.sh

    Note

    The sample information does not set up any specific tasks, on its own. It provides further context for the Event Hooks system, and can also be used as a template.

  4. At the bottom of the file, add a line that contains the controller and action to be used, and that also points to the file that contains the script the Event Hook will run

    • For the example, below, add a line to the bottom of the file that tells the server to wait for a successful event where the /nodeworx/siteworx controller is used for the add action. The add action is only used when an account is added to the server.

      When the server sees a successful completion of the event, it should run the script found at /scripts/enable-php.sh:

      # Sample hooks file content
#
# Comments start with pound
#
# Empty lines are fine
#
# Non-empty lines have a minimum of 3 components: Controller, Action, and Script + optional parameters
#
# NOTE 1: This file must be readable by the 'iworx' user
#         and your custom scripts must be executable by the iworx user.
#         They will run as the 'iworx' user, not as root.
#
# NOTE 2: Form variables for the hooked events will be available to your script
#         as environment variables, prefixed with 'iw_'

# run my script after a siteworx account gets added
#Ctrl_Nodeworx_Siteworx add /myscripts/siteworx-account.sh

# run with the --delete parameter after a siteworx account gets deleted
#Ctrl_Nodeworx_Siteworx delete /myscripts/siteworx-account.sh --delete

# run my pointer-added.sh script
#Ctrl_Siteworx_DomainsPointer add /usr/local/bin/pointer-added.sh

# run my enable-php.sh script to enable PHP versions when a SiteWorx account is created
Ctrl_Nodeworx_Siteworx add /scripts/enable-php.sh

  5. Make sure that the iworx-hooks.conf file has the correct permissions. As it must be executable by the iworx user, it must be owned as iworx:iworx

    chown iworx:iworx /etc/iworx-hooks.conf

Creating the Script

  1. Using the text editor of choice, create the file that contains the event hook will run. It must match what is found on the corresponding line in the Event Hooks configuration file

    Replace {/path/script-name.sh} with the name and location of the custom script file

    vim {/path/script-name.sh}

    • For this example, create a file named /scripts/enable-php.sh, and add the following bash script. Replace {myemail@domain.com} with the master NodeWorx user login email and {mysupersecurepassword} with the master NodeWorx user password.

      $iw_master_domain will automatically be populated with the value that was entered into the account creation form in NodeWorx when a new account is created:

      #!/bin/bash

~iworx/bin/nodeworx.pex --login_email {[email protected]} --login_password
{mysupersecurepassword} -c Siteworx -a edit --domain $iw_master_domain
--php_available system-php,/opt/remi/php71,/opt/remi/php72,/opt/remi/php73,/opt/remi/php74 -n

    Warning

    Another, more secure, option may be to create a NodeWorx user, specifically to be used for Event Hooks with limited permissions, and enter those credentials in the script, instead of the master NodeWorx user.

    It is also advisable to set the file permissions so that others cannot read these files.

  2. Make sure that the custom script file has the correct permissions. As it must be executable by the iworx user, it must be owned as iworx:iworx

    chown iworx:iworx /scripts/enable-php.sh
chmod +x /scripts/enable-php.sh