Edge hooks - 3to1go

Hooks let Edge run a shell command around each job in a backup cycle:

Pre command: before Edge scans and archives the job. Edge waits for it to finish. Useful for dumping a database into the folder first.
Post command: after the job is done, whether it uploaded, was unchanged, or failed. Cancellation skips the post command.

Hooks run during scheduled cycles and Run Backup Cycle Now. The individual Force Upload action currently bypasses both hooks.

Set up

Open Custom Scripts

In Edge, click Custom Scripts.

Upload a script (optional)

Under Uploaded Items, upload up to 3 files. Only .sh scripts and .txt helper files are allowed, and they must be UTF-8 text. .sh files are made executable, and Windows line endings are converted.

Set the commands

Enter a Pre Command and/or Post Command. Either:

the name of an uploaded script, such as before-backup.sh, or
any shell command, such as curl -fsS https://hc-ping.com/your-id.

Commands run with sh -c inside the Edge container, from the hook scripts folder (/hook-scripts). Each command has a 5-minute timeout, and is stopped if you Cancel operation. Output and non-zero exit codes go to Edge’s logs; a failing hook doesn’t stop the backup. The same commands run for every job. Use THREETOONEGO_JOB_NAME to act on specific jobs. Edge prepares different jobs concurrently, so their hooks can overlap. Keep per-job output separate when your scripts write files.

Environment variables

Variable	Value
`THREETOONEGO_APP`	`edge`
`THREETOONEGO_HOOK_PHASE`	`pre` or `post`
`THREETOONEGO_HOOK_SCRIPTS_DIR`	The hook scripts folder
`THREETOONEGO_EDGE_ID`	This Edge’s ID
`THREETOONEGO_EDGE_INSTANCE_ID`	This installation’s instance ID
`THREETOONEGO_JOB_NAME`	Backup job name
`THREETOONEGO_JOB_ROOT`	Job folder inside the container
`THREETOONEGO_STATE_KEY`	Key used for the job’s local state
`THREETOONEGO_LAST_STATUS`	Job’s last status, such as `success`
`THREETOONEGO_LAST_ERROR_CATEGORY`	Category of the last error, if any
`THREETOONEGO_LAST_ERROR_DETAIL`	Detail of the last error, if any
`THREETOONEGO_STORED_AS`	Filename of the last upload on Central
`THREETOONEGO_PRUNED`	Old snapshots Central removed after the last upload
`THREETOONEGO_DUPLICATE`	`true` if Central already had the last upload
`THREETOONEGO_PENDING_ARCHIVE`	Staged archive waiting to upload, if any
`THREETOONEGO_PENDING_FINGERPRINT`	Fingerprint of the staged archive
`THREETOONEGO_PENDING_TIMESTAMP`	Timestamp of the staged archive
`THREETOONEGO_UPLOAD_ID`	Current upload session ID
`THREETOONEGO_UPLOAD_OFFSET`	Bytes uploaded so far
`THREETOONEGO_NEXT_RETRY_AT`	When a failed upload will retry

In the pre command these describe the job’s state from its previous run. In the post command they describe the run that just finished.

Example: report each job to a health check

after-job.sh

#!/bin/sh
# Ping a health check per job; append /fail when the job needs attention.
url="https://hc-ping.com/your-uuid/$THREETOONEGO_JOB_NAME"
case "$THREETOONEGO_LAST_STATUS" in
  success|skipped_unchanged|skipped_empty) ;;
  *) url="$url/fail" ;;
esac
curl -fsS -m 10 "$url" > /dev/null

Common THREETOONEGO_LAST_STATUS values after a job:

Status	Meaning
`success`	Uploaded to Central
`skipped_unchanged`	Nothing changed since the last backup
`skipped_empty`	The folder had no files to back up
`retry_scheduled`, `waiting_retry`	Upload failed and will be retried
`circuit_open`	Central was unreachable too many times; pausing before retrying
`manual_intervention_required`	Retries ran out; check the job in Edge’s UI
`unexpected_exception`	Something else went wrong; see Edge’s logs

Set Post Command to after-job.sh.

The Edge image is a minimal Alpine image with sh and curl. Other tools, such as database clients, aren’t included. To dump a database before a backup, run the dump on the host on a schedule ahead of Edge’s cycle.

​Set up

​Environment variables

​Example: report each job to a health check

Set up

Environment variables

Example: report each job to a health check