Skip to content

Latest commit

 

History

History
253 lines (193 loc) · 11.8 KB

README.md

File metadata and controls

253 lines (193 loc) · 11.8 KB

🗃 Auto Backup

hacs_badge

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.

Services

All service parameters are optional.

auto_backup.snapshot_full

Take a snapshot of all home assistant addons and folders.

Parameter Description Type Example
name Backup name. string Automatic Backup {{ now().strftime('%Y-%m-%d') }}
password Optional password to secure backup. string 1234
keep_days The number of days to keep the backup. float 2
exclude Addons/Folders to exclude from the backup. exclude_object {"addons": ["MariaDB"], "folders": ["Local add-ons", "share"]}
backup_path Alternative directory to copy the backup to after creation. directory /usb_drive

Exclude Object

Parameter Description Type Example
addons List of addons to backup (name or slug). list ["Almond", "glances", "core_mariadb"]
folders List of folders to backup. list ["Local add-ons", "homeassistant", "share"]

auto_backup.snapshot_partial

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

Parameter Description Type Example
name Backup name. string Automatic Backup {{ now().strftime('%Y-%m-%d') }}
addons List of addons to backup (name or slug). list ["Almond", "glances", "core_mariadb"]
folders List of folders to backup. list ["Local add-ons", "homeassistant", "share"]
password Optional password to secure backup. string 1234
keep_days The number of days to keep the backup. float 2
backup_path Alternative directory to copy the backup to after creation. directory /usb_drive

auto_backup.purge

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/Folder Names

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
  • local add-ons or addons/local
  • home assistant configuration or homeassistant

Keep Days

The keep_days attribute 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.

Backup Path

The backup_path attribute allows you to specify a directory to copy the snapshot to after creation. This directory must be accessible from Home Assistant. If you are running in docker you 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 copied 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.

Events

Automation Example

  • 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"]}

Sensor

Configuration

Just add auto_backup to your home assistant configuration.yaml file.

# Example configuration.yaml entry
auto_backup:
  auto_purge: true

Configuration Variables

  • auto_purge (boolean) (Optional)

    • Default value: true
    • This option will automatically purge any expired snapshots when creating a new snapshot.

  • backup_timeout (integer) (seconds) (Optional)

    • Default value: 1200 (20 min)
    • You can increase this value if you get timeout errors when creating a snapshot. This can happen with very large snapshots.

Examples

Example: Notify on Snapshot Failure

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

Example: Automatic Backups

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_template:
        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

Example: Exclude from Backup

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

Advanced Example: Generational Backups

Preface

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

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_template:
        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_template:
        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_template:
        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.