backrest/docs/content/2.docs/2.hooks.md

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)
• 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).

Notification Services

Service	Docs
Discord	https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks
Slack	https://api.slack.com/messaging/webhooks
Gotify	https://github.com/gotify/server
Shoutrrr	https://containrrr.dev/shoutrrr/v0.8/
Command	See command cookbook

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 }}