borgmatic - Apprise

🔍

New in version 1.8.4 Apprise is a local notification library that "allows you to send a notification to almost all of the most popular notification services 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, run the following to install Apprise so borgmatic can use it:

sudo pipx uninstall borgmatic
sudo pipx install borgmatic[Apprise]

Omit sudo if borgmatic is installed as a non-root user.

Once Apprise is installed, configure borgmatic to notify one or more Apprise services. For example:

apprise:
    services:
        - url: gotify://hostname/token
          label: gotify
        - url: mastodons://access_key@hostname/@user
          label: mastodon
    states:
        - start
        - finish
        - fail

With this configuration, borgmatic pings each of the configured Apprise services when a backup begins, ends, or errors, but only when any of the create, prune, compact, or check actions are run. (By default, if states is not specified, Apprise services are only pinged on error.)

You can optionally customize the contents of the default messages sent to these services:

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

New in version 1.8.9 borgmatic logs are automatically included in the body data sent to your Apprise services when a backup finishes or fails.

You can customize the verbosity of the logs that are sent with borgmatic's --monitoring-verbosity flag. The --list and --stats flags may also be of use. See create action documentation for more information.

New in version 2.0.0Set the defaults for these flags in your borgmatic configuration via the monitoring_verbosity, list, and statistics options.

If you don't want any logs sent, you can disable log sending by setting send_logs to false:

apprise:
    services:
        - url: gotify://hostname/token
          label: gotify
    send_logs: false

Or to limit the size of logs sent to Apprise services:

apprise:
    services:
        - url: gotify://hostname/token
          label: gotify
    logs_size_limit: 500

This may be necessary for some services that reject large requests.

See the configuration reference for details.

Full configuration

apprise:
    # 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.
    services:
        # URL of this Apprise service.
        - url: gotify://hostname/token

          # Label used in borgmatic logs for this Apprise
          # service.
          label: gotify

    # Send borgmatic logs to Apprise services as part of the
    # "finish", "fail", and "log" states. Defaults to true.
    send_logs: false

    # Number of bytes of borgmatic logs to send to Apprise
    # services. Set to 0 to send all logs and disable this
    # truncation. Defaults to 1500.
    logs_size_limit: 100000

    start:
        # Specify the message title. If left unspecified, no
        # title is sent.
        title: Ping!

        # Specify the message body.
        body: Starting backup process.

    finish:
        # Specify the message title. If left unspecified, no
        # title is sent.
        title: Ping!

        # Specify the message body.
        body: Backups successfully made.

    fail:
        # Specify the message title. If left unspecified, no
        # title is sent.
        title: Ping!

        # Specify the message body.
        body: Your backups have failed.

    log:
        # Specify the message title. If left unspecified, no
        # title is sent.
        title: Ping!

        # Specify the message body.
        body: Here is some info about your backups.

    # List of one or more monitoring states to ping for:
    # "start", "finish", "fail", and/or "log". Defaults to
    # pinging for failure only. For each selected state,
    # corresponding configuration for the message title and body
    # should be given. If any is left unspecified, a generic
    # message is emitted instead.
    states:
        - start
        - finish

Improve this documentation

Have an idea on how to make this documentation even better? Use our issue tracker to send your feedback!