mirror of
https://github.com/garethgeorge/backrest.git
synced 2025-12-13 09:15:39 +00:00
102 lines
5.7 KiB
Markdown
102 lines
5.7 KiB
Markdown
# 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).
|
|
- 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
|
|
|
|
| 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 |
|
|
|
|
|
|
## 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 }}
|
|
```
|