1. CubeBackup Documents
  2. Tutorials
  3. CubeBackup hook Reference

CubeBackup hook Reference

Introduction

Starting from version 4.9, CubeBackup provides hooks for administrators to set up real-time backup status updates, track restore and export events, and execute customized hook scripts automatically.

Triggering the CubeBackup hooks on specific events enables administrators to receive notifications on status updates, monitor scheduled events, or use their own internal system integration for customized reactions. See Use cases for detailed instructions.

When a hook is triggered, CubeBackup will pass the status object params , which contains details of the event, and can be used to automate whatever actions are deemed appropriate in a hook script.

CubeBackup hook scripts should be written in Lua. You can find samples of Lua hook scripts in our Git repository. If you would like to help specifically tailoring hook scripts to meet your company's requirements, please reach out to us at [email protected].

Events

A CubeBackup hook can be set to listen for basic events. If you identify an event to listen for and register a hook script path in the configuration file, CubeBackup will fire the hook and execute the registered script each time the event occurs.

There are five types of events that CubeBackup hooks can be configured to listen for:

  • BackupDomainComplete : a backup job has been completed for an entire domain
  • BackupUserComplete : a backup job has been completed for a user
  • BackupSharedDriveComplete : a backup job has been completed for a Shared drive
  • RestoreComplete : a restore job has been completed
  • ExportComplete : an export job has been completed

Each of these events can be assigned a separate hook script, which will be executed every time that specific event occurs. The Build a hook section describes how to configure a hook and register the hook script in CubeBackup.

Params

CubeBackup hooks pass a params object that contains detailed information about the event that just completed. This information can be used in a variety of ways according to the needs of your company. Please click on the appropriate tab to see a full list of attributes corresponding to each type of event:

{
    hook = "BackupDomainComplete",
    domain = "mydomain.com",
    task = {
        CalendarEventsCount = 0,
        CalendarTotalSize = 0,
        CompletedSharedDriveCount = 1,
        CompletedUserCount = 0,
        ContactsCount = 0,
        ContactsTotalSize = 0,
        DriveFileCount = 0,
        DriveTotalSize = 0,
        Duration = 106,
        ErrorCount = 0,
        Id = 775,
        MailCount = 0,
        MailTotalSize = 0,
        SharedDriveCount = 1,
        SitesFileCount = 0,
        SitesTotalSize = 0,
        StartTime = 1667895253,
        Status = "success",
        TotalFileCount = 0,
        TotalFileSize = 0,
        UserCount = 0
    }
}
{
    hook = "BackupUserComplete",
    task = {
        BackupId = 781,
        CalendarEventsCount = 0,
        CalendarTotalSize = 0,
        ContactsCount = 0,
        ContactsTotalSize = 0,
        DriveFileCount = 0,
        DriveTotalSize = 0,
        Duration = 9,
        ErrorCount = 0,
        Id = 0,
        IsIncrBackup = false,
        MailCount = 10,
        MailTotalSize = 555318,
        OwnerId = "11365...20468",
        OwnerName = "[email protected]",
        OwnerType = "user",
        SitesFileCount = 0,
        SitesTotalSize = 0,
        StartTime = 1667897094,
        Status = "success",
        TotalFileCount = 0,
        TotalFileSize = 0
    },
    user = {
        BackupEnabled = true,
        CalendarIndexSize = 0,
        CalendarStorageSize = 0,
        ContactsIndexSize = 0,
        ContactsStorageSize = 0,
        Deleted = false,
        DriveIndexSize = 0,
        DriveStorageSize = 0,
        FullName = "Example mydomain",
        GmailIndexSize = 15964160,
        GmailStorageSize = 3528730440,
        Id = "11365...20468",
        IsAdmin = true,
        OrgUnitPath = "/Finance Department",
        PrimaryEmail = "[email protected]",
        SitesIndexSize = 0,
        SitesStorageSize = 0,
        Suspended = false,
        TotalDataSize = 3544694600,
        TotalIndexSize = 15964160,
        TotalStorageSize = 3528730440
    }
}
{
    hook = "BackupSharedDriveComplete",
    task = {
        BackupId = 776,
        CalendarEventsCount = 0,
        CalendarTotalSize = 0,
        ContactsCount = 0,
        ContactsTotalSize = 0,
        DriveFileCount = 0,
        DriveTotalSize = 0,
        Duration = 0,
        ErrorCount = 0,
        Id = 0,
        IsIncrBackup = false,
        MailCount = 0,
        MailTotalSize = 0,
        OwnerId = "0ABHT...k9PVA",
        OwnerName = "Example drive",
        OwnerType = "shareddrive",
        SitesFileCount = 0,
        SitesTotalSize = 0,
        StartTime = 1667896566,
        Status = "success",
        TotalFileCount = 0,
        TotalFileSize = 0
    },
    drive = {
        BackgroundImageLink = "https://ssl.gstatic.com/.../background.jpg",
        BackupEnabled = true,
        Deleted = false,
        Id = "0ABHT...k9PVA",
        IndexSize = 28672,
        Name = "Example drive",
        StorageSize = 40139552,
        TotalDataSize = 40168224
    }
}
{
    hook = "RestoreComplete",
    domain = "mydomain.com",
    task = {
        CreatedTime = 1667522925,
        Desc = "Restore 'restore example' to [email protected].",
        Duration = 10,
        ErrorCount = 0,
        FileCount = 1,
        Id = 11,
        Op = "c:[email protected]",
        StartTime = 1667522925,
        Status = "success",
        Type = "gmail",
        UploadedSize = 0
    }
}
{
    hook = "ExportComplete",
    domain = "mydomain.com",
    task = {
        Action = "export",
        CreatedTime = 1667893615,
        Desc = "Export 'export example' in shared drive 'example drive'.",
        Duration = 1,
        ErrorCount = 0,
        ExportedSize = 20050276,
        FileCount = 3,
        Id = 5,
        Identifer = "158ed45beebc928d0e944618b0470906",
        Op = "c:[email protected]",
        SavePath = "/export/j1wzce...ql0zbs.zip",
        StartTime = 1667893615,
        Status = "success",
        Type = "shareddrive",
        ZipSize = 7571986
    }
}

In addition, any errors encountered while executing the hook scripts are returned in the err string. You can send the details to your mailbox or print it in the log files for your own reference.

Build a hook

Follow the instructions below to create a CubeBackup hook and register the hook script.

Create a hook script

  1. Download the appropriate hook sample scripts from our Git repository to your backup server.

  2. Open a script and update the required information based on your own specific details. Please click the corresponding tab below to configure each type of script.

···
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)
···

Customize the subject and recipient of this email report. If necessary, please also adjust the email content in html according to the params of the specific hook event you wish to listen for.

···
local pingURL = "https://hc-ping.com/3d270...ca971"
···

Update the pingURL with your own healthcheck endpoint. For detailed instructions, see How to integrate Healthchecks.io with CubeBackup.

···
local command = "df -h"
local timeout = 60 \-\- measured in seconds
local result, err = cmd.exec(command, timeout)
···

Add your own command to the command field. The timeout parameter determines the value after which the command will be terminated.

Advanced users may modify the Lua scripts or combine the sample scripts to customize hook behavior according to your company's specific needs.

Configure a hook event

  1. Open the CubeBackup configuration file. In the [Hooks] section, register the location of 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 at the end of your 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.

  2. Use the absolute script path as the value of each hook event, and remove the comment character # from the beginning of the line.

    The [Hooks] section should look similar to the example below. 

    [Hooks]
BackupDomainComplete = "/opt/cubebackup/scripts/healthchecks.lua"
BackupUserComplete = ""
BackupSharedDriveComplete = ""
RestoreComplete = "/opt/cubebackup/scripts/email_restore.lua"
ExportComplete = "/opt/cubebackup/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. Configure the SMTP settings for email notifications.
    If you wish to send customized email reports using CubeBackup hooks, it will be necessary to configure your own SMTP service. For detailed instructions on how to do this, see CubeBackup SMTP settings.

Test hook scripts

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, or by testing on your hook scripts using the cbackup runLua command and examining the detailed echo information.

If you run the following command on the backup server, CubeBackup will execute the Lua scripts and echo detailed information as well as any errors directly to the command line.

On Windows:

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

On Linux:

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

You can also provide a pre-determined params object 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

Track CubeBackup hooks

While CubeBackup events are automatically logged in the CubeBackup web console, the triggered hook script and subsequent results are not. To secure your data and track the state of each hook fired, you can log the events processed in the CubeBackup log file at <installation_directory>/log/cube.log.

CubeBackup implements a simple logging package to write new lines to the log file, and allows you to define the formatting output of both info and error log entries.

The example below processes the err and params values and adds them as new entries in the log file.

local log = require("log")
...
log.errorf("error message: %s", err)
log.infof("event details: %s", inspect(params))

All log entries are recorded on a separate line preceded by the date and time of the entry, as in the example below:

2022-11-08T02:35:13.685Z	error	runLua error messages: "Custom SMTP server required."

2022-11-08T02:35:14.449Z	info	runLua event details: {
  domain = "mydomain.com",
  hook = "BackupDomainComplete",
  task = {
    ...
  }
}

Use cases

CubeBackup hooks can be used by administrators to monitor basic events in CubeBackup and program appropriate reactions. We have provided three sample hook scripts for admins to handle the following use cases. Click on the instructions for details on how to configure CubeBackup hooks according to your needs.

Trigger email notifications

Integrate with health check service

Execute custom commands