How to execute commands and trigger appropriate actions in response to particular CubeBackup events using CubeBackup hooks.

---

In addition to email notifications and health checks for real-time events, you can also configure CubeBackup hooks to execute specific actions or code on your backup server.

This script can be combined with the email.lua hook script to add more information to your email notifications, work together with the CubeBackup CLI and the CubeBackup API to build an automatic integration to manage your backup service, or to handle additional use cases according to your needs.

Follow the instructions below to listen for CubeBackup events and execute your custom commands using this hook script.

Create your hook script

1. Download the following hook script sample exec.lua to your backup server.

   -- load required modules
   local cmd = require("cmd")
   local log = require("log")
   
   -- specify commands to be executed
   local command = "df -h"
   local timeout = 60 – measured in seconds
   local result, err = cmd.exec(command, timeout)
   
   -- print the hook event and any errors in the CubeBackup log file
   if err then
     log.errorf("exec failed:%s", err)
   else
     log.infof("%s\n status:%d\n stdout:%s\n stderr:%s", command, result.status, result.stdout, result.stderr)
   end
   

2. Open this hook script using a text editor. Add the commands you wish to run each time the hook fires in the command field. The timeout parameter determines the value after which the command will be terminated.

3. You can also access detailed information for this event using the params object. See Params for a full list of available attributes.

4. (optional) For testing purposes, you can also provide a pre-determined params in the hook scripts to simulate the event status, and confirm that your CubeBackup hook is functioning as intended.

   if params == nil then
     params = {
       domain = "testdomain.com",
       hook = "BackupDomainComplete",
       task = {...}
     }
   end
   

5. Save the changes and test your hook script using the following command. CubeBackup will execute the Lua scripts and echo the information or any errors.

   On Windows:

   "C:\Program Files\CubeBackup4\bin\cbackup.exe" runLua <script_file_path>

   On Linux:

   sudo /opt/cubebackup/bin/cbackup runLua <script_file_path>

Configure the hook event

If everything works properly with this hook script, you can proceed to modify the CubeBackup configuration file.

Note:
Starting with version 4.7, the configuration file is located at <installation directory>/etc/config.toml for fresh installations of CubeBackup. For installations upgraded through the console, or versions prior to 4.7, the configuration file is still located at <installation directory>/bin/config.toml.
     On Windows, the installation directory is located at C:\Program Files\CubeBackup4 by default.
     On Linux, the installation directory is located at /opt/cubebackup by default.

1. Open the config.toml using a text editor. In the [Hooks] section, configure the specific hook scripts for events you wish to listen for. If your config.toml file doesn't contain a [Hooks] section, you will need to add it manually to the end of your configuration file.

2. Use the absolute script path as the value of each hook to be fired. The [Hooks] section should look like the following sample after the modification.
   The [Hooks] section should look similar to the example below.

   [Hooks]
   BackupDomainComplete = "C:\\Program Files\\CubeBackup4\\scripts\\exec_domainBackup.lua"
   BackupUserComplete = "C:\\Program Files\\CubeBackup4\\scripts\\exec_userBackup.lua"
   BackupSharedDriveComplete = "C:\\Program Files\\CubeBackup4\\scripts\\exec_sharedDriveBackup.lua"
   RestoreComplete = "C:\\Program Files\\CubeBackup4\\scripts\\exec_restore.lua"
   ExportComplete = "C:\\Program Files\\CubeBackup4\\scripts\\exec_export.lua"
   

   Tips:
   1. Please use the double-backslash \\ in the file path for Windows operating systems.
   2. For Linux users, please be sure to grant cbuser sufficient permissions to read the script.

3. Be sure to test your hook scripts before running them live. You can do this by initiating a corresponding event directly in the CubeBackup web console to confirm that the script is running properly.