# 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`