diff --git a/.vscode/settings.json b/.vscode/settings.json index 7c59b4f..3e34208 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -16,5 +16,9 @@ "[python]": { "editor.defaultFormatter": "ms-python.black-formatter" }, - "yaml.customTags": ["!env"] + "yaml.customTags": [ + "!ENV", + "tag:yaml.org,2002:python/name:materialx.emoji.twemoji", + "tag:yaml.org,2002:python/name:materialx.emoji.to_svg" + ] } diff --git a/README.md b/README.md index 4b976f7..2e30cce 100644 --- a/README.md +++ b/README.md @@ -15,32 +15,33 @@ Auto Backup is an Improved Backup Service for Home Assistant that can Automatica For more information and examples check the [documentation](https://jcwillox.github.io/hass-auto-backup). ## Features -* Provides more advanced and configurable [service calls](https://jcwillox.github.io/hass-auto-backup/services). -* [Exclude addons/folders](https://jcwillox.github.io/hass-auto-backup/services) from a backup. -* [Automatically delete backups](https://jcwillox.github.io/hass-auto-backup/services/#keep-days) after an individually specified amount of time. -* [Download backups](https://jcwillox.github.io/hass-auto-backup/services/#download-path) to a specified directory after completion (for example a usb drive). -* Allows the use of [addon names instead of slugs](https://jcwillox.github.io/hass-auto-backup/services/#addon-and-folder-names). -* Provides a [sensor](https://jcwillox.github.io/hass-auto-backup/sensors) to monitor the status of your backups. -* Creates [events](https://jcwillox.github.io/hass-auto-backup/events) for when backups are started/created/failed/deleted. -* Supports [generational backup](https://jcwillox.github.io/hass-auto-backup/advanced-examples/#generational-backups) schemes. + +- Provides more advanced and configurable [service calls](https://jcwillox.github.io/hass-auto-backup/services). +- [Exclude addons/folders](https://jcwillox.github.io/hass-auto-backup/services) from a backup. +- [Automatically delete backups](https://jcwillox.github.io/hass-auto-backup/services/#keep-days) after an individually specified amount of time. +- Backup to [custom locations](https://jcwillox.github.io/hass-auto-backup/services/#custom-locations) such as network storage. +- Allows the use of [addon names instead of slugs](https://jcwillox.github.io/hass-auto-backup/services/#addon-and-folder-names). +- Provides a [sensor](https://jcwillox.github.io/hass-auto-backup/sensors) to monitor the status of your backups. +- Creates [events](https://jcwillox.github.io/hass-auto-backup/events) for when backups are started/created/failed/deleted. +- Supports [generational backup](https://jcwillox.github.io/hass-auto-backup/advanced-examples/#generational-backups) schemes. ## Services [Automation Examples using Services](https://jcwillox.github.io/hass-auto-backup/examples) -* [`auto_backup.backup`](https://jcwillox.github.io/hass-auto-backup/services/#auto_backupbackup) -* [`auto_backup.backup_full`](https://jcwillox.github.io/hass-auto-backup/services/#auto_backupbackup_full) -* [`auto_backup.backup_partial`](https://jcwillox.github.io/hass-auto-backup/services/#auto_backupbackup_partial) -* [`auto_backup.purge`](https://jcwillox.github.io/hass-auto-backup/services/#auto_backupbackup_purge) +- [`auto_backup.backup`](https://jcwillox.github.io/hass-auto-backup/services/#auto_backupbackup) +- [`auto_backup.backup_full`](https://jcwillox.github.io/hass-auto-backup/services/#auto_backupbackup_full) +- [`auto_backup.backup_partial`](https://jcwillox.github.io/hass-auto-backup/services/#auto_backupbackup_partial) +- [`auto_backup.purge`](https://jcwillox.github.io/hass-auto-backup/services/#auto_backupbackup_purge) ## Events [Automation Example using Events](https://jcwillox.github.io/hass-auto-backup/events/#example-automation-using-events) -* [`auto_backup.backup_start`](https://jcwillox.github.io/hass-auto-backup/events) -* [`auto_backup.backup_successful`](https://jcwillox.github.io/hass-auto-backup/events) -* [`auto_backup.backup_failed`](https://jcwillox.github.io/hass-auto-backup/events) -* [`auto_backup.purged_backups`](https://jcwillox.github.io/hass-auto-backup/events) +- [`auto_backup.backup_start`](https://jcwillox.github.io/hass-auto-backup/events) +- [`auto_backup.backup_successful`](https://jcwillox.github.io/hass-auto-backup/events) +- [`auto_backup.backup_failed`](https://jcwillox.github.io/hass-auto-backup/events) +- [`auto_backup.purged_backups`](https://jcwillox.github.io/hass-auto-backup/events) ## Configuration @@ -51,6 +52,7 @@ After installing Auto Backup via [HACS](https://hacs.xyz/), it can then be setup ### Options - **Automatically delete expired backups** + - This option will automatically purge any expired backups when creating a new backup. - **Backup Timeout** diff --git a/docs/index.md b/docs/index.md index 94cb7de..d679764 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,18 +5,19 @@ Auto Backup is an Improved Backup Service for Home Assistant that can Automatica [![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=jcwillox&repository=hass-auto-backup&category=integration) !!! important "" + While Home Assistant does provide built-in services for creating backups, they do not provide the ability to exclude items from a backup, or a way to automatically remove them, this custom component aims to fix that. ## Features -* [x] Provides more advanced and configurable [service calls](services.md). -* [x] [Exclude addons/folders](services.md) from a backup. -* [x] [Automatically delete backups](services.md#keep-days) after an individually specified amount of time. -* [x] [Download backups](services.md#download-path) to a specified directory after completion (for example a usb drive). -* [x] Allows the use of [addon names instead of slugs](services.md#addon-and-folder-names). -* [x] Provides a [sensor](sensors.md) to monitor the status of your backups. -* [x] Creates [events](events.md) for when backups are started/created/failed/deleted. -* [x] Supports [generational backup](advanced-examples.md#generational-backups) schemes. +- [x] Provides more advanced and configurable [service calls](services.md). +- [x] [Exclude addons/folders](services.md) from a backup. +- [x] [Automatically delete backups](services.md#keep-days) after an individually specified amount of time. +- [x] Backup to [custom locations](services.md#custom-locations) such as network storage. +- [x] Allows the use of [addon names instead of slugs](services.md#addon-and-folder-names). +- [x] Provides a [sensor](sensors.md) to monitor the status of your backups. +- [x] Creates [events](events.md) for when backups are started/created/failed/deleted. +- [x] Supports [generational backup](advanced-examples.md#generational-backups) schemes. ## Configuration diff --git a/docs/services.md b/docs/services.md index a693efd..feb1745 100644 --- a/docs/services.md +++ b/docs/services.md @@ -8,16 +8,17 @@ Create a full or partial backup. This is the primary method and includes the functionality of the `backup_full` and `backup_partial` services. -| Parameter | Description | Type | Example | -| -------------------------------------------- | ----------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------- | -| `name` | Optional name, defaults to the current date and time. | `string` | `#!jinja Automatic Backup {{ now().strftime('%Y-%m-%d') }}` | -| [`include_addons`](#addon-and-folder-names) | List of addons to include in the backup (name or slug). Wildcards supported for slugs. | `list` | `#!json ["Almond", "glances", "core_mariadb", "core_*"]` | -| [`include_folders`](#addon-and-folder-names) | List of folders to include in the backup. | `list` | `#!json ["Local add-ons", "homeassistant", "share"]` | -| [`exclude_addons`](#addon-and-folder-names) | List of addons to exclude from the backup (name or slug). Wildcards supported for slugs. | `list` | `#!json ["Almond", "glances", "core_mariadb", "core_*"]` | -| [`exclude_folders`](#addon-and-folder-names) | List of folders to exclude from the backup. | `list` | `#!json ["Local add-ons", "homeassistant", "share"]` | -| `password` | Optional password to secure backup. | `string` | `#!json 1234` | -| [`keep_days`](#keep-days) | The number of days to keep the backup. | `float` | `#!json 2` | -| [`download_path`](#download-path) | Locations to download the backup to after creation. | `list` | `#!json ["/usb_drive"]` | +| Parameter | Description | Type | Example | +| -------------------------------------------- | ---------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------- | +| `name` | Optional name, defaults to the current date and time. | `string` | `#!jinja Automatic Backup {{ now().strftime('%Y-%m-%d') }}` | +| [`include_addons`](#addon-and-folder-names) | List of addons to include in the backup (name or slug). Wildcards supported for slugs. | `list` | `#!json ["Almond", "glances", "core_mariadb", "core_*"]` | +| [`include_folders`](#addon-and-folder-names) | List of folders to include in the backup. | `list` | `#!json ["Local add-ons", "homeassistant", "share"]` | +| [`exclude_addons`](#addon-and-folder-names) | List of addons to exclude from the backup (name or slug). Wildcards supported for slugs. | `list` | `#!json ["Almond", "glances", "core_mariadb", "core_*"]` | +| [`exclude_folders`](#addon-and-folder-names) | List of folders to exclude from the backup. | `list` | `#!json ["Local add-ons", "homeassistant", "share"]` | +| `password` | Optional password to secure backup. | `string` | `#!json 1234` | +| [`keep_days`](#keep-days) | The number of days to keep the backup. | `float` | `#!json 2` | +| [`location`](#custom-locations) | Name of a backup network storage to put backup (or /backup) | `string` | `#!json my_backup_mount` | +| `compressed` | Use compressed archives (default: true) | `bool` | `#!json true` | ??? example "Create a full backup" @@ -81,31 +82,24 @@ Currently, accepted values are (ignoring case): 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`. -### Download Path +### Custom Locations -The `download_path` parameter allows you to specify a location or of list of locations to download the backup 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`. - -!!! tip - The backup will still be stored under `/backup` and show up on the [backups](https://my.home-assistant.io/redirect/backup) page, it will only be copied/downloaded to the location specified, to immediately delete the backup use a negative value for `keep_days` (e.g. `#!yaml keep_days: -1` ). - -!!! info - A slugified version of the backups name will be used for the filename, if a file with that name already exists the backups id (slug) will be used instead. - -!!! note - When running on **Home Assistant Core** backups will be copied not downloaded. When running **Home Assistant Supervised** integrations do not have direct access to the `/backup` folder, which is why the backup is downloaded and not simply copied. +Home Assistant [2023.6](https://www.home-assistant.io/blog/2023/06/07/release-20236/#connect-and-use-your-existing-network-storage) included support for adding custom backup locations, and even changing the default backup location. Auto Backup supports specifying an alternative location using the `location` option. Additional backup locations can be added by navigating to **Settings** → **System** → **Storage**, and clicking the **Add network storage** button. +[![Open your Home Assistant instance and show storage information.](https://my.home-assistant.io/badges/storage.svg)](https://my.home-assistant.io/redirect/storage/) ## `auto_backup.backup_full` Create a full backup with optional exclusions. -| Parameter | Description | Type | Example | -| --------------------------------- | ----------------------------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| `name` | Optional name, defaults to the current date and time. | `string` | `#!jinja Automatic Backup {{ now().strftime('%Y-%m-%d') }}` | -| `exclude` | Addons/Folders to exclude from the backup. | [`Exclude Object`](#exclude-object) | [`#!json {"addons": ["MariaDB"], "folders": ["Local add-ons", "share"]}`](examples.md#excluding-addonsfolders-from-a-backup) | -| `password` | Optional password to secure backup. | `string` | `#!json 1234` | -| [`keep_days`](#keep-days) | The number of days to keep the backup. | `float` | `#!json 2` | -| [`download_path`](#download-path) | Locations to download the backup to after creation. | `list` | `#!json ["/usb_drive"]` | +| Parameter | Description | Type | Example | +| ------------------------------- | ----------------------------------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| `name` | Optional name, defaults to the current date and time. | `string` | `#!jinja Automatic Backup {{ now().strftime('%Y-%m-%d') }}` | +| `exclude` | Addons/Folders to exclude from the backup. | [`Exclude Object`](#exclude-object) | [`#!json {"addons": ["MariaDB"], "folders": ["Local add-ons", "share"]}`](examples.md#excluding-addonsfolders-from-a-backup) | +| `password` | Optional password to secure backup. | `string` | `#!json 1234` | +| [`keep_days`](#keep-days) | The number of days to keep the backup. | `float` | `#!json 2` | +| [`location`](#custom-locations) | Name of a backup network storage to put backup (or /backup) | `string` | `#!json my_backup_mount` | +| `compressed` | Use compressed archives (default: true) | `bool` | `#!json true` | #### Exclude Object @@ -118,14 +112,15 @@ Create a full backup with optional exclusions. Create a partial backup. -| Parameter | Description | Type | Example | -| ------------------------------------ | ----------------------------------------------------- | -------- | ----------------------------------------------------------- | -| `name` | Optional name, defaults to the current date and time. | `string` | `#!jinja Automatic Backup {{ now().strftime('%Y-%m-%d') }}` | -| [`addons`](#addon-and-folder-names) | List of addons to backup (name or slug). | `list` | `#!json ["Almond", "glances", "core_mariadb"]` | -| [`folders`](#addon-and-folder-names) | List of folders to backup. | `list` | `#!json ["Local add-ons", "homeassistant", "share"]` | -| `password` | Optional password to secure backup. | `string` | `#!json 1234` | -| [`keep_days`](#keep-days) | The number of days to keep the backup. | `float` | `#!json 2` | -| [`download_path`](#download-path) | Locations to download the backup to after creation. | `list` | `#!json ["/usb_drive"]` | +| Parameter | Description | Type | Example | +| ------------------------------------ | ----------------------------------------------------------- | -------- | ----------------------------------------------------------- | +| `name` | Optional name, defaults to the current date and time. | `string` | `#!jinja Automatic Backup {{ now().strftime('%Y-%m-%d') }}` | +| [`addons`](#addon-and-folder-names) | List of addons to backup (name or slug). | `list` | `#!json ["Almond", "glances", "core_mariadb"]` | +| [`folders`](#addon-and-folder-names) | List of folders to backup. | `list` | `#!json ["Local add-ons", "homeassistant", "share"]` | +| `password` | Optional password to secure backup. | `string` | `#!json 1234` | +| [`keep_days`](#keep-days) | The number of days to keep the backup. | `float` | `#!json 2` | +| [`location`](#custom-locations) | Name of a backup network storage to put backup (or /backup) | `string` | `#!json my_backup_mount` | +| `compressed` | Use compressed archives (default: true) | `bool` | `#!json true` | ## `auto_backup.purge` @@ -137,4 +132,5 @@ This service is useful if you want to manually specify when to purge backups, such as doing a batch delete at 12AM. !!! info + Expired backups are automatically purged when creating new backups, this can be disabled in the [options menu](index.md#options).