How to push event notifications to your mailbox using CubeBackup hooks.

---

In addition to periodic email reports summarizing backup details, you can also implement CubeBackup hooks to trigger email notifications after each specific backup, restore or export event. This can give admins helpful real-time updates outside of the CubeBackup console.

Follow the instructions below to listen for CubeBackup events and push notifications to your mailbox.

Configure SMTP settings

For security and privacy reasons, CubeBackup requires you to use either your own SMTP service, your Gmail SMTP service, or Google Workspace SMTP relay service. Detailed instructions can be found here: CubeBackup SMTP settings.

Create your hook script

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

   -- load required modules
   local email = require("email")
   local log = require("log")
   local inspect = require("inspect")
   
   -- define a predetermined param object for test purposes
   if params == nil then
   params = {
     domain = "testdomain.com",
     hook = "BackupDomainComplete",
     task = {
         ErrorCount = 0,
         Status = "success",
         TotalFileCount = 3,
         TotalFileSize = 2131
     }
   }
   end
   
   log.infof("lua hook params %s", inspect(params))
   
   -- define the function to return data size in human-readable format
   local sizeUnits = {"B", "KB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"}
   
   function ReadableSize(s)
     local i = 1
     while s > 1024 do
       s = s / 1024
       i = i + 1
     end
     return string.format("%.2f %s", s, sizeUnits[i])
   end
   
   -- define the email subject, body and recipient
   local recipient = "[email protected]"
   local subject = "Backup accomplished"
   local html = {}
   table.insert(html, "Backup for " .. params.domain .. " accomplished")
   table.insert(html, "status:" .. params.task.Status)
   table.insert(html, "file count:" .. params.task.TotalFileCount)
   table.insert(html, "file size:" .. ReadableSize(params.task.TotalFileSize))
   table.insert(html, "errors:" .. params.task.ErrorCount)
   html = table.concat(html, "<br />")
   
   local err = email.send(recipient, subject, html)
   
   -- print the hook event and any errors in the CubeBackup log file
   if err then
     log.errorf("send mail failed:%s", err)
   else
     log.infof("mail sent.")
   end
   

2. Open the hook script using a text editor. Customize the subject and recipient of this email report.

3. If necessary, please also adjust the email content in html according to the params of the specific hook event you wish to listen for.

   Tip: The hook scripts in Lua use the .. operator to join strings. For example,

   table.insert(html, "Backup for " .. params.domain .. " accomplished")
   

4. Save the changes and test your hook script using the cbackup runLua 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\\email_domainBackup.lua"
   BackupUserComplete = ""
   BackupSharedDriveComplete = ""
   RestoreComplete = "C:\\Program Files\\CubeBackup4\\scripts\\email_restore.lua"
   ExportComplete = "C:\\Program Files\\CubeBackup4\\scripts\\email_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.