Improved Backup Service for Hass.io that can Automatically Remove Snapshots and Supports Generational Backup Schemes.

While Home Assistant does provide built-in services for creating backups, these are not documented and do not provide a way to automatically remove them, this custom component aims to fix that.

All service parameters are optional.

Take a snapshot of all home assistant addons and folders.

Take a snapshot of the specified home assistant addons and folders.

Purge expired backups.

There are no parameters here, just call the service and it will remove any expired snapshots.

This service is useful if you want to manually specify when to purge snapshots, such as doing a batch delete at 12AM (Note: expired snapshots are automatically purged when creating new snapshots, this can be disabled in the config.

Addon names are case-insensitive and can be the addon name/title, these are the same names seen when creating a partial snapshot through the Hass.io page. They can also be the addons slug (slug must be lowercase).

Folder names are also case-insensitive and use the names seen when creating a partial snapshot through the Hass.io page. Currently, accepted values are (ignoring case):

• ssl
• share
• media
• local add-ons or addons/local
• home assistant configuration or homeassistant

The keep_days parameter allows you to specify how long the backup should be kept for before being deleted. Default is forever. You can specify a float value for keep days, e.g. to keep a backup for 12 hours use 0.5.

The backup_path parameter allows you to specify a directory to download the snapshot to after creation. This directory must be accessible from Home Assistant. If you are running in docker your paths will be relative to the container for example your Home Assistant configuration directory is stored under /config and the share folder is under /share.

The snapshot will still be stored under /backup and show up in the Hass.io snapshots page, it will only be downloaded to the location specified, to immediately delete the snapshot from Hass.io use a negative value for keep_days (-1 will suffice).

A slugified version of the snapshots name will be used for the filename, if a file with that name already exists the snapshots slug will be used instead.

Note: on docker by default you and this integration do not have direct access to the /backup folder, which is why the snapshot is downloaded and not copied.

Automation Example

• Event: auto_backup.snapshot_start, data: {"name": "NAME"}
• Event: auto_backup.snapshot_successful, data: {"name": "NAME", "slug": "SLUG"}
• Event: auto_backup.snapshot_failed, data: {"name": "NAME", "error": "ERROR"}
• Event: auto_backup.purged_snapshots, data: {"snapshots": ["SLUG"]}

After installing Auto Backup via HACS, it can then be setup via the UI, go to the Integrations menu and add Auto Backup.

On Home Assistant 2021.3.0 and above you can use the badge below to automatically start the setup

- alias: "Notify Snapshot Failure"
  trigger:
    platform: event
    event_type: auto_backup.snapshot_failed
  action:
    service: persistent_notification.create
    data:
      title: "Snapshot Failed."
      message: "Name: {{ trigger.event.data.name }}\nError: {{ trigger.event.data.error }}"

Perform a partial backup of the home assistant config folder, mariadb and mosquitto every 3 hours, and store each backup for 2 days.

- alias: Perform Auto Backup
  trigger:
    - platform: time_pattern
      hours: "/3"
  action:
    - service: auto_backup.snapshot_partial
      data:
        name: "AutoBackup: {{ now().strftime('%a, %-I:%M %p (%d/%m/%Y)') }}"
        addons:
          - almond
          - Glances
          - mosquitto broker
          - core_mariadb
        folders:
          - homeassistant
          - Share
          - ssl
          - Local add-ons
        keep_days: 2

- alias: Perform Daily Backup
  trigger:
    - platform: time
      at: "00:00:00"
  action:
    - service: auto_backup.snapshot_full
      data:
        name: "DailyBackup: {{ now().strftime('%A, %B %-d, %Y') }}"
        keep_days: 7
        exclude:
          addons:
            - Portainer
          folders:
            - Local add-ons
            - share

Generational backups (wiki) allow you to store backups over a long period of time while still having frequent enough backups to be useful for recovery. This is done by reducing the frequency of backups as they get older.
Personally I take a snapshot of home assistant every 3 hours for the first 2 days, then each day for a week, and finally each week for a month.

For example, lets say my database has corrupted and I want to restore it.

If its been less than 48 hours since it corrupted then I can restore to the exact point before it corrupted +/- 1.5 hours (if you're monitoring trends you don't want to lose hours worth of data, so 1.5 is pretty good),

If 48 hours have passed then I can restore to any point +/- 12 hours over the past 5 days (minus the two where the db was corrupted).

Over a week I can restore to any point +/- 1 week over the past 3 weeks, while +/- 1 week isn't very useful for restoring a database, it can be useful for subtle thing you don't notice, like if you accidentally deleted something.

This is substantially more efficient than storing a backup every 3 hours for a month, and while you lose some accuracy as the backups get older, most failures (if they even occur) will be noticed within 48 hours,

Also most things other than your database don't change that often so a 4 week old backup of your home assistant config may be the same as 1 day old backup. Also in my case the 3 hourly backup only backs up the important files to save on storage, whereas my daily/weekly backups are full snapshots.

Of course you can tweak these values to your liking, or even add a month/yearly backup schedule 👍.

automation:
  - alias: Perform Auto Backup
    trigger:
      platform: time_pattern # Perform backup every 3 hours.
      hours: "/3"
    action:
      service: auto_backup.snapshot_partial # Only perform a partial snapshot to save storage.
      data:
        name: "AutoBackup: {{ now().strftime('%a, %-I:%M %p (%d/%m/%Y)') }}"
        addons:
          - core_mariadb # It doesn't matter if you use the addon slug or name. Name is easier.
          - core_mosquitto
        folders:
          - homeassistant
          - share
          - ssl
        keep_days: 2

  - alias: Perform Daily Backup
    trigger:
      platform: time
      at: "02:30:00"
    condition:
      condition: time # Perform backup every day except Mondays.
      weekday:
        - tue
        - wed
        - thu
        - fri
        - sat
        - sun
    action:
      service: auto_backup.snapshot_full
      data:
        name: "DailyBackup: {{ now().strftime('%A, %B %-d, %Y') }}"
        keep_days: 7

  - alias: Perform Weekly Backup
    trigger:
      platform: time
      at: "02:30:00"
    condition:
      condition: time # On Mondays perform a weekly backup
      weekday:
        - mon
    action:
      service: auto_backup.snapshot_full
      data:
        name: "WeeklyBackup: {{ now().strftime('%A, %B %-d, %Y') }}"
        keep_days: 28 # Store backup for a month, basically perform 1 backup each week and store for 4 weeks.