Hook Details

Hook Types

Backrest supports hooks in response to operation lifecycle events e.g. in response to the commands it runs on your behalf.

Available event types are

• CONDITION_ANY_ERROR any operation has failed.
• CONDITION_SNAPSHOT_START the start of a backup operation (e.g. corresponds to a call to restic backup, supports error behavior)
• CONDITION_SNAPSHOT_END the end of a backup operation (e.g. corresponds to restic backup completing). Note that Snapshot End will still be called if a backup failed.
• CONDITION_SNAPSHOT_ERROR an error occurred during a backup operation (e.g. restic backup returned a non-zero exit code OR invalid output).
• CONDITION_SNAPSHOT_WARNING a warning occurred during a backup operation (e.g. a file was partially read).
• CONDITION_SNAPSHOT_SUCCESS a backup operation completed successfully.
• Prune hooks:
  • CONDITION_PRUNE_START the start of a prune operation (e.g. corresponds to a call to restic prune, supports error behavior)
  • CONDITION_PRUNE_SUCCESS the end of a prune operation e.g. restic prune completed successfully.
  • CONDITION_PRUNE_ERROR an error occurred during a prune operation (e.g. restic prune returned a non-zero exit code).
• Check hooks:
  • CONDITION_CHECK_START the start of a check operation (e.g. corresponds to a call to restic check, supports error behavior)
  • CONDITION_CHECK_SUCCESS the end of a check operation e.g. restic check completed successfully.
  • CONDITION_CHECK_ERROR an error occurred during a check operation (e.g. restic check returned a non-zero exit code).

Notification Services

Error Behavior

Some hooks can specify an error behavior (today this is only command hooks). This determines what happens when the hook generates an error.

The available error behaviors are:

• ON_ERROR_IGNORE - ignore the error and continue running hooks and the operation.
• ON_ERROR_CANCEL - cancel the operation and do not run any further hooks. The operation is marked as cancelled.
• ON_ERROR_FATAL - cancel the operation and do not run any further hooks. The operation is marked as failed and error handler hooks may be triggered.

Using Templates

Most hooks will generate either a notification or execute a script. The script / notification is typically formatted as a Go template. The https://pkg.go.dev/text/template docs provide a very technical overview of Go template capabilities. See below for info about the available variables and for some examples.

Variables

• Event:v1.Hook_Condition - the event that triggered the backup. This is an enum. Values are one of: Hook_CONDITION_SNAPSHOT_START, Hook_CONDITION_SNAPSHOT_END, Hook_CONDITION_ANY_ERROR, Hook_CONDITION_SNAPSHOT_ERROR .
• Task:string - the name of the task that triggered the hook (e.g. one time backup for plan "foo"
• Repo:v1.Repo - the repo that triggered the backup. This is a struct. Access the name as {{ .Repo.Id }}
• Plan:v1.Plan - the plan that triggered the backup. This is a struct. Access the name as {{ .Plan.Id }}
• SnapshotId:string - the snapshot ID associated with the operation or empty string if none is associated.
• SnapshotStats:restic.BackupProgressEntry - summary of the current backup operation. This is a struct. See examples below for details.
• CurTime:time.Time - the current time. This is a struct. Format as {{ .FormatTime .CurTime }}.
• Duration:time.Duration - the duration of the triggering operation. Format as {{ .FormatDuration .Duration }}.
• Error:string - the error message if an error occurred, or empty string if successful.

Functions

• .Summary - prints a default summary of the current event.
• .FormatTime <time> - formats a time.Time object e.g. as 2024-02-08T03:00:37Z.
• .FormatDuration <duration> - formats a time.Duration object e.g. as 1h2m3s.
• .FormatSizeBytes <int> - formats a number as a size in bytes (e.g. 5MB, 10GB, 30TB, etc...)
• .ShellEscape <string> - escapes a string to safely be used in most shell environments. Should not be relied upon as secure for arbitrary input.
• .JsonMarshal <any> - attempts to marshall any value as JSON. Can also be used with literals e.g. to quote a string with escapes i.e. hello"world -becomes "hello\"world".

Summary Template

The current implementation of .Summary:

Task: "{{ .Task }}" at {{ .FormatTime .CurTime }}
Event: {{ .EventName .Event }}
Repo: {{ .Repo.Id }}
Plan: {{ .Plan.Id }}
Snapshot: {{ .SnapshotId }}
{{ if .Error -}}
Failed to create snapshot: {{ .Error }}
{{ else -}}
{{ if .SnapshotStats -}}

Overview:
- Data added: {{ .FormatSizeBytes .SnapshotStats.DataAdded }}
- Total files processed: {{ .SnapshotStats.TotalFilesProcessed }}
- Total bytes processed: {{ .FormatSizeBytes .SnapshotStats.TotalBytesProcessed }}

Backup Statistics:
- Files new: {{ .SnapshotStats.FilesNew }}
- Files changed: {{ .SnapshotStats.FilesChanged }}
- Files unmodified: {{ .SnapshotStats.FilesUnmodified }}
- Dirs new: {{ .SnapshotStats.DirsNew }}
- Dirs changed: {{ .SnapshotStats.DirsChanged }}
- Dirs unmodified: {{ .SnapshotStats.DirsUnmodified }}
- Data blobs: {{ .SnapshotStats.DataBlobs }}
- Tree blobs: {{ .SnapshotStats.TreeBlobs }}
- Total duration: {{ .SnapshotStats.TotalDuration }}s
{{ end }}
{{ end }}