diff --git a/NEWS b/NEWS
index 031e2d4..c9531b0 100644
--- a/NEWS
+++ b/NEWS
@@ -1,10 +1,15 @@
+1.8.4.dev0
+ * Add a monitoring hook for sending backup status to a variety of monitoring services via the
+ Apprise library. See the documentation for more information:
+ https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#apprise-hook
+
1.8.3
* #665: BREAKING: Simplify logging logic as follows: Syslog verbosity is now disabled by
default, but setting the "--syslog-verbosity" flag enables it regardless of whether you're at an
interactive console. Additionally, "--log-file-verbosity" and "--monitoring-verbosity" now
default to 1 (info about steps borgmatic is taking) instead of 0. And both syslog logging and
file logging can be enabled simultaneously.
- * #743: Add a monitoring hook for sending backup status and logs to to Grafana Loki. See the
+ * #743: Add a monitoring hook for sending backup status and logs to Grafana Loki. See the
documentation for more information:
https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#loki-hook
* #753: When "archive_name_format" is not set, filter archives using the default archive name
diff --git a/borgmatic/config/schema.yaml b/borgmatic/config/schema.yaml
index f8a10d6..41ce4c7 100644
--- a/borgmatic/config/schema.yaml
+++ b/borgmatic/config/schema.yaml
@@ -1324,12 +1324,12 @@ properties:
example: "gotify://hostname/token"
label:
type: string
- example: mastodon
+ example: gotify
description: |
- A list of Apprise services to publish to with URLs
- and labels. The labels are used for logging.
- A full list of services and their configuration can be found
- at https://github.com/caronc/apprise/wiki.
+ A list of Apprise services to publish to with URLs and
+ labels. The labels are used for logging. A full list of
+ services and their configuration can be found at
+ https://github.com/caronc/apprise/wiki.
example:
- url: "kodi://user@hostname"
label: kodi
diff --git a/docs/how-to/monitor-your-backups.md b/docs/how-to/monitor-your-backups.md
index e7f3a2e..d1081b4 100644
--- a/docs/how-to/monitor-your-backups.md
+++ b/docs/how-to/monitor-your-backups.md
@@ -36,28 +36,24 @@ below for how to configure this.
### Third-party monitoring services
-borgmatic integrates with monitoring services like
-[Healthchecks](https://healthchecks.io/), [Cronitor](https://cronitor.io),
-[Cronhub](https://cronhub.io), [PagerDuty](https://www.pagerduty.com/),
-[ntfy](https://ntfy.sh/), and [Grafana Loki](https://grafana.com/oss/loki/)
-and pings these services whenever borgmatic runs. That way, you'll receive an
-alert when something goes wrong or (for certain hooks) the service doesn't
-hear from borgmatic for a configured interval. See [Healthchecks
-hook](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#healthchecks-hook),
-[Cronitor
-hook](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#cronitor-hook),
-[Cronhub
-hook](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#cronhub-hook),
-[PagerDuty
-hook](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#pagerduty-hook),
-[ntfy
-hook](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#ntfy-hook),
-and [Loki
-hook](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#loki-hook),
-below for how to configure this.
+borgmatic integrates with these monitoring services and libraries, pinging
+them as backups happen:
+
+ * [Healthchecks](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#healthchecks-hook)
+ * [Cronitor](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#cronitor-hook)
+ * [Cronhub](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#cronhub-hook)
+ * [PagerDuty](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#pagerduty-hook)
+ * [ntfy](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#ntfy-hook)
+ * [Grafana Loki](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#loki-hook)
+ * [Apprise](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#apprise-hook)
+
+The idea is that you'll receive an alert when something goes wrong or when the
+service doesn't hear from borgmatic for a configured interval (if supported).
+See the documentation links above for configuration information.
+
+While these services and libraries offer different features, you probably only
+need to use one of them at most.
-While these services offer different features, you probably only need to use
-one of them at most.
### Third-party monitoring software
@@ -146,7 +142,7 @@ healthchecks:
Prior to version 1.8.0 Put
this option in the `hooks:` section of your configuration.
-With this hook in place, borgmatic pings your Healthchecks project when a
+With this configuration, borgmatic pings your Healthchecks project when a
backup begins, ends, or errors, but only when any of the `create`, `prune`,
`compact`, or `check` actions are run.
@@ -190,7 +186,7 @@ cronitor:
Prior to version 1.8.0 Put
this option in the `hooks:` section of your configuration.
-With this hook in place, borgmatic pings your Cronitor monitor when a backup
+With this configuration, borgmatic pings your Cronitor monitor when a backup
begins, ends, or errors, but only when any of the `prune`, `compact`,
`create`, or `check` actions are run. Then, if the actions complete
successfully or errors, borgmatic notifies Cronitor accordingly.
@@ -217,7 +213,7 @@ cronhub:
Prior to version 1.8.0 Put
this option in the `hooks:` section of your configuration.
-With this hook in place, borgmatic pings your Cronhub monitor when a backup
+With this configuration, borgmatic pings your Cronhub monitor when a backup
begins, ends, or errors, but only when any of the `prune`, `compact`,
`create`, or `check` actions are run. Then, if the actions complete
successfully or errors, borgmatic notifies Cronhub accordingly.
@@ -258,7 +254,7 @@ pagerduty:
Prior to version 1.8.0 Put
this option in the `hooks:` section of your configuration.
-With this hook in place, borgmatic creates a PagerDuty event for your service
+With this configuration, borgmatic creates a PagerDuty event for your service
whenever backups fail, but only when any of the `create`, `prune`, `compact`,
or `check` actions are run. Note that borgmatic does not contact PagerDuty
when a backup starts or when it ends without error.
@@ -340,7 +336,7 @@ loki:
url: http://localhost:3100/loki/api/v1/push
```
-With this hook in place, borgmatic sends its logs to your Loki instance as any
+With this configuration, borgmatic sends its logs to your Loki instance as any
of the `prune`, `compact`, `create`, or `check` actions are run. Then, after
the actions complete, borgmatic notifies Loki of success or failure.
@@ -375,6 +371,67 @@ loki:
```
+## Apprise hook
+
+New in version 1.8.4
+[Apprise](https://github.com/caronc/apprise) is a local notification library
+that "allows you to send a notification to almost all of the most popular
+[notification services](https://github.com/caronc/apprise/wiki) available to
+us today such as: Telegram, Discord, Slack, Amazon SNS, Gotify, etc."
+
+Depending on how you installed borgmatic, it may not have come with Apprise.
+For instance, if you originally [installed borgmatic with
+pipx](https://torsion.org/borgmatic/docs/how-to/set-up-backups/#installation),
+run the following to install Apprise so borgmatic can use it:
+
+```bash
+pipx install --editable --force borgmatic[Apprise]
+```
+
+Once Apprise is installed, configure borgmatic to notify one or more [Apprise
+services](https://github.com/caronc/apprise/wiki). For example:
+
+```yaml
+apprise:
+ services:
+ - url: gotify://hostname/token
+ label: gotify
+ - url: mastodons://access_key@hostname/@user
+ label: mastodon
+```
+
+With this configuration, borgmatic pings each of the configured Apprise
+services when a backup begins, ends, or errors, but only when any of the
+`prune`, `compact`, `create`, or `check` actions are run.
+
+You can optionally customize the contents of the default messages sent to
+these services:
+
+```yaml
+apprise:
+ services:
+ - url: gotify://hostname/token
+ label: gotify
+ start:
+ title: Ping!
+ body: Starting backup process.
+ finish:
+ title: Ping!
+ body: Backups successfully made.
+ fail:
+ title: Ping!
+ body: Your backups have failed.
+ states:
+ - start
+ - finish
+ - fail
+```
+
+See the [configuration
+reference](https://torsion.org/borgmatic/docs/reference/configuration/) for
+details.
+
+
## Scripting borgmatic
To consume the output of borgmatic in other software, you can include an
diff --git a/setup.py b/setup.py
index 5e99f7c..bdaa710 100644
--- a/setup.py
+++ b/setup.py
@@ -1,6 +1,6 @@
from setuptools import find_packages, setup
-VERSION = '1.8.3'
+VERSION = '1.8.4.dev0'
setup(
diff --git a/tests/unit/hooks/test_apprise.py b/tests/unit/hooks/test_apprise.py
index b11f769..446507b 100644
--- a/tests/unit/hooks/test_apprise.py
+++ b/tests/unit/hooks/test_apprise.py
@@ -195,7 +195,7 @@ def test_ping_monitor_pings_multiple_services():
)
-def test_ping_monitor_warning_for_no_services():
+def test_ping_monitor_logs_info_for_no_services():
flexmock(module.logger).should_receive('info').once()
module.ping_monitor(
@@ -206,3 +206,18 @@ def test_ping_monitor_warning_for_no_services():
monitoring_log_level=1,
dry_run=False,
)
+
+
+def test_ping_monitor_logs_warning_when_notify_fails():
+ mock_apprise().should_receive('notify').and_return(False)
+ flexmock(module.logger).should_receive('warning').once()
+
+ for state in borgmatic.hooks.monitor.State:
+ module.ping_monitor(
+ {'services': [{'url': f'ntfys://{TOPIC}', 'label': 'ntfys'}]},
+ {},
+ 'config.yaml',
+ state,
+ monitoring_log_level=1,
+ dry_run=False,
+ )