This addon enables easy Home Assistant backup creation and sync to OneDrive.
- Dedicated Web UI
- Set backup creation schedule
- Syncs backups to OneDrive (Personal Account only. OneDrive for business not currently supported)
- Additional File Sync to OneDrive
- Supports standard backup retention / Generational backup mode
- Retain backups indefinitely
- Supports multiple Home Assistant instances
- Supports Home Assistant Persistent Notifications
- Supports Home Assistant Events
- Includes Sensor Entities for Dashboards / Automations
This is a free addon but if you enjoy this addon and would like to support the development it >would be much appreciated :)
Installation Instructions
Configuration
Backup Location in OneDrive
Home Assistant Sensor
Events
Restoring from backup
Security and Privacy
FAQ
Feedback / Feature requests
If you've installed Add-ons before this will be pretty straightforward and you can skip reading thorugh all the steps below except the initial authentication parts in steps 7 and 8.
-
From the Home Assistant frontend navigate to the Add-on Store ( Settings -> Add-ons -> Add-on Store [bottom right])
-
Select the Repositories option from the 3-dot menu in the top right corner and add this repository url: https://github.com/lavinir/hassio-onedrive-backup
A Preview channel is also available to get and test newer versions earlier. If you want to participate in the preview channel use the following repository URL instead: https://github.com/lavinir/hassio-onedrive-backup#preview
-
Reload the Add-on page (hard refresh might be required) and scroll down. You should now see a new section titled Home Assistant Onedrive Backup Repository that contains the OneDrive Backup addon.
-
Click Install and wait a few minutes for the addon to download
-
I recommend setting a backup password for your Home Assistant backups. You can do this in the addon Configuration.
-
Start the addon and wait a few seconds for it to start. Once started you can navigate to the addon Web UI.
Important! If you are using a CloudFlare tunnel or similar service you may see this error message:
To resolve this please see the relevant section in the FAQ -
You will need to Authenticate with OneDrive one time to allow the addon access to a dedicated backup folder in your OneDrive account. (If you're interested in the addon permissions and the authentication flow you can see more details below under Security and Privacy). You can do this via the Web Interface, where there will be a banner prompting you to authenticate:
You can use the button to copy the auth code and click on the URL to start the authentication process.You can also do this without the Web Interface by opening the Add-on logs where you will have a similar line telling you to authenticate with the appropriate code.
-
Copy the code and navigate to the url as instructed. You will be asked to login to your Microsoft account and grant permissions to the App that will allow it to store your backups.
.
After consent has been granted you're good to go. The authentication banner will disappear from the Web Interface and will start displaying data.Alternatively, you can also verify in the logs that authentication has indeed succeeded.
All configuration options for the addon can be found under Settings in the addon's Web Interface
The maximum amount of backups to keep locally in Home Assistant
Note that the number of the actual backups can temporarly exceed the set maximum by one due to the fact deletion occurs only after a new backup is created.
The maximum amount of backups to keep in OneDrive
The backup creation frequency in days.
For setting a sub-day frequency you can use a number between 0 and 1, so for example if the value here is set to 0.5, the backup frequency will occur every 12 hours. You should avoid using a value less than 0.083 (~2 hours) as the current enforced minimum sync interval is once an hour.
By setting a value for any of the Generational retention periods (days, weeks, months, years) you are changing the default retention policy of keeping the latest backups only.
Generational backups only effect retention and not backup creation. You should have your Backup interval days set to 1 so that the generational policy has enough available backups to align with the policy.
Generational backups do not override the maximum number of backups configured (applicable to both local and OneDrive backups). You should make sure the max backup number is enough to accomodate your Generational settings. If Max backups was reached and all backups are needed by the Generational backup settings, backups will be removed to align with the Max Backup settings (deleting the oldest backups first)
Will attempt to keep the latest X days set in Generational Days
Will attempt to keep the latest backup from each week, going back X weeks, where X is weeks set in Generational Weeks.
Weeks are aligned to week number of year. First day of week is selected based on your Locale.
Will attempt to keep the latest backup from each month, going back X months, where X is the months set in Generational Months
Will attempt to keep the latest backup from each year, going back X years, where X is the years set in Generational Years
Name to use for the backups created by the add-on.
To avoid collision with backups created outside this addon please use a unique name here.
When enabled the add-on will monitor all local backups whether created by the addon or not
When enabled, the add-on will ignore backups that are automatically created during upgrades (of Home Assistant / Addons)
The password to use to protect the backups created and uploaded to OneDrive.
You need to toggle the "Show unused optional configuration options" to see it in the Configuration screen.
This allows you to set the timeout configured when calling the Home Assistant APIs.
This applies to how long your backups take to create. If you experience timeouts during backup creation, increase this value.
Enables persistent notifications in Home Assistant to notify of backup failures.
When enabled, a partial backup will be created without the media folder
When enabled, a partial backup will be created without the ssl folder
When enabled, a partial backup will be created without the share folder
When enabled, a partial backup will be created without the addons/local folder
This accepts a range of hours from 0 to 23 for which only during these hours backups / syncs will be performed. If a backup is required or sync is pending it will be performed at the first window allowed in the defined hours.
The format of this is one or more ranges seperated by a comma. A range is specified by a dash
Example:
0-2,10,21- [Allowed hours are 00:00-02:59, 10:00-10:59 and 21:00-23:50]
You need to toggle the "Show unused optional configuration options" to see it in the Configuration screen.
If you have more than one Home Assistant installation you want to backup to the same OneDrive account, you can achieve this by specifying different instance names to each installation. Each instance will only look at their own backups and ignore any other instances.
You need to toggle the "Show unused optional configuration options" to see it in the Configuration screen.
This allows you to specify a list of paths for the addon to sync to OneDrive so you can for example sync your Media folder to OneDrive and exclude it from the Backups allowing you to save storage space (as this will only be stored once). Files are stored under a new directory called FileSync under the App Folder. Source folder structure is maintained under this folder.
Sync (sub)folders supported must be under one of the following roots:
- /config
- /ssl
- /share
- /media
- /addons
- /addon_configs
- /homeassistant
Example:
sync_paths:
- /share/
- /media/music/*.mp3
- /share/**/*.zip
You can use '*' as a wild card representing 0 to many characters or **/ to represent an arbitrary depth. In the examples above the paths that will be synced are (1) contents share folder and all subfolders located underneath, (2) all the .mp3 files located inside the /media/music folder (no subfolders included) and (3) all .zip files located in any directory / subdirectory under the /share folder
Currently Sync is only preformed one way (Local -> OneDrive).
When enabled, the FileSync folder on OneDrive will mirror your included Sync Paths meaning any 'extra' content that remains in OneDrive will be removed.
When enabled, Allowed Hours will be ignored for File Syncing and allow syncing to occur in all hours (this does not effect backups, only File Syncing)
When enabled, partial backups will be created excluding the addons specified in this list. You need to specify the addon id (slug) in this list. To find the correct slug you can navigate in Home Assistant to Settings -> Addons and click on an addon. When you are in the addon Info screen you will see the addon slug in the url: https://your.homeassistant.host/hassio/addon/addonslug/info
You can opt to see more / less logs by adjusting the verbosity of the addon logs. Possible values are (verbose, info, warning, error)
Sends anonymous telemetry once a day containing data about which features are enabled in the addon. This helps focus development on relevant features and improve the addon.
What data is sent? A random Guid is generated when you run your addon for the first time (not persisted through uninstall). That is sent along with the following data:
- File Sync Enabled Flag
- Generational Backups Enabled Flag
- Backup Allowed Hours Enabled Flag
- Instance Name Enabled Flag (The instance name is NOT sent)
- Monitor all Local Backups Enabled Flag
- Ignore Upgrade Backups Enabled Flag
- Ignore Allowed Hours for File Sync Enabled Flag
- Addon Version
- Notify On Error Enabled Flag
- Error Reporting Enabled Flag
Sends anonymous error messages (with exceptions) to help identify issues with the addon
Use Dark mode for Addon UI
The add-on has specific permissions to a single folder in your OneDrive known as the App Folder. (More details can be found in the Security and Privacy section.)
The App Folder for the add-on is mapped to : [onedriveroot]/Apps/hassio-onedrive-backup
You can choose to 'pin' specific backups so that they stop counting against the set backup quotas and are never deleted by the addon. This can be set individually for both local and OneDrive through dedicated buttons in the main Dashboard for each backup.
Note - As any 'retained' backup will not count towards your maximum backup quota you could for example, have a maximum of 3 local backups set but chose to retain 2 Local backups. The addon will ignore the retained backups for the quota and will store a maximum of 3 addtional local backups
The add-on creates a native Home Assistant Sensor entity sensor.onedrivebackup which grants visibility to the backup status as well as allows you to create automations on these values as needed.
There are 5 possible states for the sensor:
All backups are fresh and within the maximum set values both locally and on OneDrive. This is the optimal state for the sensor to be in.
Local backups are fresh and within defined limits, however this indicates possible staleness in the OneDrive backups.
Additional visiblity into the full backup state can be found in the Sensor Attributes below.
OneDrive backups are fresh and within defined limits, however this indicates possible staleness in the local backups.
Additional visiblity into the full backup state can be found in the Sensor Attributes below.
Syncing to OneDrive is in progress.
All backups (local and OneDrive) are outside the defined backup interval configured.
The sensor also exposes the following attributes:
Date of the latest backup that exists locally in Home Assistant
Date of the latest backup that exists in OneDrive
Number of backups that exist locally in Home Assistant
Number of backups that exist in OneDrive
When a backup upload is in progress this will show the progress of the upload.
When a backup upload is in progress this will show the transfer speed of the upload.
When a backup download is in progress this shows the progres of the download.
The add-on creates a native Home Assistant Sensor entity sensor.onedrivefilesync which grants visibility to the file sync status as well as allows you to create automations on these values as needed.
There are 2 possible states for the sensor:
All files specified in the Sync Paths are backed up to OneDrive.
Files are being synced to OneDrive.
The sensor also exposes the following attributes:
When a file upload is in progress this will show the progress of the upload.
When a file upload is in progress this will show the transfer speed of the upload.
Upon a failure in the backup process, the addon will fire different events you can use in your automations:
This event will fire when a backup could not be created locally.
This event will fire when a backup upload to OneDrive has failed.
This event will fire when deleting a backup from OneDrive (based on defined retention) has failed.
This event will fire when deleting a local backup from Home Assistant (based on defined retention) has failed.
To restore a backup head to the Settings -> System -> Backups menu. From there you should see all your local backups. You can choose any one from the list and recover Home Assistant from them.
For backups in OneDrive only, you will first want to sync them back locally. This can be done via the Web Interface by clicking the Download backup on the specific backup you wish to restore. It will be automatically uploaded to Home Assistant and visible in the Backups section.
Authentication with OneDrive uses Microsoft's Device Code Flow. At no point is the addon exposed to your account password. Once permission has been granted, a token is cached locally which is used for future authentications. The token only has access to a single special App Folder created by the Application and has no access to any of your OneDrive files outside of this dedicated folder. Granting access to the application does not grant access to me or anyone else access to this folder outside of the current flow for the add-on on your device.
The only things stored locally are:
- Backups (stored in Home Assistant and password protected)
- The authentication token mentioned above in Authentication
Outside the backups uploaded to your OneDrive account, no data is sent anywhere else.
No. Currently OneDrive for Business does not support the special App Folder mentioned above which allows restricting the addo-ons access only to it's own folder and would require full access to the the users entire OneDrive.
The default timeout for backup creation is 30 minutes. For large installations, backup creation could exceed this time. You can increase the timeout value in your configuration.
This can be done using the Allowed hours (Optional) configuration
See how to configure Instance names
The Web UI uses the Blazor framework which relies on injecting Html comments into the dom for tracking purposes for the Blazor components. Service like CloudFlare (e.g. for those using the CloudFlared addon to access Home Assistant outside of their network) have "Auto Minify" features, which can include removing comment blocks from served HTML pages. If this occurs it breaks the Blazor framework and you will receive an appropriate error in the Addon WebUI. Below are instructions to resolve this for a CloudFlare tunnel:
Option 1 - Disable Auto Minify
You can disable auto minify by logging in to the Cloudflare dashboard, selecting your account and website. Then go to the Speed -> Optimization section and uncheck HTML under Auto Minify
Option 2 - Use a Page Rule
If you do not want to do this globally you can also use a Page Rule by going to Rules -> Page Rules instead. You can then select the URL you want to disable HTML minification for (e.g. https://your.homeassistant.host/*) and choose the Auto Minify settings and deselect HTML:
Note: If you want to use a more specific URL just for the addon (though you probably don't really need that) you will need to use the Home Assistant assigned Ingress URL allocated to the Addon. You can get this from the logs when setting them to Verbose
If you use and like this addon and want to show support you could do so by starring the official Repo on GitHub or 
For Bugs / Issues please open an Issue on GitHub
For new suggestions / feedback please use the official repo GitHub Disucssions
