mirror of
https://github.com/garethgeorge/backrest.git
synced 2025-12-14 09:35:41 +00:00
98 lines
2.6 KiB
Markdown
98 lines
2.6 KiB
Markdown
# Command Hook Examples
|
|
|
|
## Introduction
|
|
|
|
Command hooks are a powerful way to extend Backrest's capabilities. They allow you to run arbitrary shell commands in response to lifecycle events. This doc shows examples of command hooks.
|
|
|
|
## Command Hook Options
|
|
|
|
When run on `CONDITION_SNAPSHOT_START` command hooks have the ability to send contorl signals to Backrest based on the exit status of the script. The handling of the exit status is configured by the `Error Behavior` field. The following options are available:
|
|
|
|
- `ON_ERROR_CANCEL` - If the script exits with a non-zero status, the backup operation will be canceled.
|
|
- `ON_ERROR_FATAL` - If the script exits with a non-zero status, it is treated as a backup failure and error notifications are triggered.
|
|
- `ON_ERROR_IGNORE` - If the script exits with a non-zero status, the backup operation will continue and the error will be ignored.
|
|
|
|
#### Check for internet connectivity
|
|
|
|
Add a hook to check for internet connectivity before running a backup.
|
|
|
|
**Condition** `CONDITION_SNAPSHOT_START`
|
|
|
|
**Script**
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
if ping -q -c 1 -W 1 google.com >/dev/null; then
|
|
echo "Internet connection is up"
|
|
exit 0
|
|
else
|
|
echo "Internet connection is down"
|
|
exit 1
|
|
fi
|
|
```
|
|
|
|
**Error Behavior:** `ON_ERROR_CANCEL`
|
|
|
|
#### Check that a target directory exists
|
|
|
|
Add a hook to check that a target directory exists before running a backup.
|
|
|
|
**Condition** `CONDITION_SNAPSHOT_START`
|
|
|
|
**Script**
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
if [ -d /path/to/backup ]; then
|
|
echo "Backup directory exists"
|
|
exit 0
|
|
else
|
|
echo "Backup directory does not exist"
|
|
exit 1
|
|
fi
|
|
```
|
|
|
|
**Error Behavior:** `ON_ERROR_CANCEL`
|
|
|
|
#### Check that the battery is above a certain level
|
|
|
|
Add a hook to check that the battery is above a certain level before running a backup.
|
|
|
|
**Condition** `CONDITION_SNAPSHOT_START`
|
|
|
|
**Script**
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
if [ $(cat /sys/class/power_supply/BAT0/capacity) -gt 80 ]; then
|
|
echo "Battery level is above 20%"
|
|
exit 0
|
|
else
|
|
echo "Battery level is below 20%"
|
|
exit 1
|
|
fi
|
|
```
|
|
|
|
**Error Behavior:** `ON_ERROR_CANCEL`
|
|
|
|
#### Notify a healthcheck service
|
|
|
|
Ping a healthcheck service (e.g. https://healthchecks.io/ in the example) to notify it of backup status (or failure) using a command hook.
|
|
|
|
Note that this hook example takes advantage of the fact that the hook is a golang template to render different commands based on whether an error occurred.
|
|
|
|
**Condition** `CONDITION_SNAPSHOT_END`
|
|
|
|
**Script**
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
{{ if .Error -}}
|
|
curl -fsS --retry 3 https://hc-ping.com/your-uuid/fail
|
|
{{ else -}}
|
|
curl -fsS --retry 3 https://hc-ping.com/your-uuid
|
|
{{ end -}}
|
|
```
|
|
|
|
**Error Behavior:** `ON_ERROR_IGNORE`
|