How to monitor the backup cron job and integrate the health check service using CubeBackup hooks.

---

As a self-hosted backup solution, CubeBackup requires you to maintain the backup service on your own machine and deal with the inevitable failures which will occur. A health check service can be invaluable in monitoring your scheduled backups and in setting up alarms to detect issues such as server downtime, backup service crash, or even just an abnormally long backup task.

CubeBackup hooks can be configured to interact with a healthcheck or heartbeat system to build a reliable and practical service. In this case, CubeBackup will run automatic backups and trigger hooks after each regular backup which can be used to send check-in requests to your health check system. Backup failures and missed check-in messages can generate alerts in your health check system.

This article will guide you through the CubeBackup hook integration with Healthchecks.io. If you need to implement other monitoring services, you can use these instructions as a reference.

Sign up for the HealthChecks.io service

Healthchecks.io is a simple and effective cron job monitoring service. It can help monitor your scheduled backup jobs and notify you if they don't run at the expected time or if they finish with errors.

1. Register a HealthChecks.io account. If you already have an active one, please sign in to the HealthChecks.io dashboard.

2. You can either use the default project or create a new one for your backup cron job. Click Add Check to create a new Check for this monitoring task.

   

3. Make sure the Period is the same as the backup interval you've set in CubeBackup.

4. Set the Grace Time to allow enough time that your backup should have reasonably finished (in addition to the normal period), and then click Save.

5. After creating the check, copy the generated ping URL and save it for your hook script.

Create your hook script

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

   -- load required modules
   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 = {Status = "success"}
   }
   end
   
   log.infof("lua hook params %s", inspect(params))
   
   -- send backup status to healthchecks.io
   local http = require("http_client")
   local client = http.client()
   local pingURL = "https://hc-ping.com/3d270…ca971"
   if params.task.Status == "failed" then
     pingURL = pingURL .. "/fail"
   end
   local request = http.request("GET", pingURL)
   local result, err = client:do_request(request)
   
   -- print the hook event and any errors in the CubeBackup log file
   if err then
     log.errorf("ping request failed:%s", err)
   else
     log.infof("ping response %s", result.body)
   end
   

2. Open the hook script using a text editor. Update the pingURL with your own Healthcheck.io ping URL endpoint.

3. 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>

4. You can also see the ping information in your Healthchecks.io dashboard.

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 the BackupDomainComplete hook to be fired.
   

   We recommend that you do not configure the BackupUserComplete and BackupSharedDriveComplete hooks for heath check purposes, or only trigger check-in requests for specific users and Shared drives by adding an if-else statement in your hook script. Otherwise, the rate limit of HealthChecks.io service may result in missing requests from CubeBackup hooks.

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

   [Hooks]
   BackupDomainComplete = "C:\\Program Files\\CubeBackup4\\scripts\\healthchecks_domainBackup.lua"
   BackupUserComplete = ""
   BackupSharedDriveComplete = ""
   RestoreComplete = ""
   ExportComplete = ""
   

   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.

Congratulations!

You've now successfully implemented the Healthchecks.io service for your backup cron job. CubeBackup will fire a hook and issue an HTTP request every time it completes the backup for a domain. Should the backup hook not fire at the expected time, Healthchecks.io will detect the failure and notify you by email.