Back up and restore your app in Azure App Service
In Azure App Service, you can easily restore app backups. You can also make on-demand custom backups or configure scheduled custom backups. You can restore a backup by overwriting an existing app or by restoring to a new app or slot. This article shows you how to restore a backup and make custom backups.
Back up and restore is supported in the Basic, Standard, Premium, and Isolated tiers. For the Basic tier, only the production slot can be backed up and restored. For more information about scaling your App Service plan to use a higher tier, see Scale up an app in Azure.
Note
For App Service Environments:
- Automatic backups can be restored to a target app within the App Service Environment itself, not in another App Service Environment.
- Custom backups can be restored to a target app in another App Service Environment, such as from App Service Environment v2 to App Service Environment v3.
- Backups can be restored to a target app of the same OS platform as the source app.
Back up and restore vs. disaster recovery
| Platform | Back up and restore guidance | Disaster recovery guidance |
|---|---|---|
| App Service web apps (Free and Shared pricing tiers) |
If you have web applications deployed to the Free or Shared tier and require access to back up and restore capabilities for these web apps, scale up to the Basic tier or higher. | Bring App Service resources back online in a different Azure region during a regional disaster. Starting March 31, 2025, App Service applications won't be placed in disaster recovery mode during a disaster in an Azure region as explained in the recover from region-wide failure article. We recommend that you implement commonly used disaster recovery techniques to prevent downtime and data loss during a regional disaster. |
| App Service web apps (Basic, Standard, and Premium pricing tiers) |
In Azure App Service, You can make on-demand custom backups or utilize automatic backups. You can restore a backup by overwriting an existing app or by restoring to a new app or slot. Refer to Back up and restore your app in Azure App Service for more info. |
Current guidance regarding how to bring App Service resources back online in a different Azure region during a regional disaster is available at Recover from region-wide failure - Azure App Service. Starting March 31, 2025, Azure App Service web applications will no longer be placed in disaster recovery mode during a disaster in an Azure region as explained in the recover from region-wide failure article. We encourage you to implement commonly used disaster recovery techniques to prevent loss of functionality or data for your web apps if there's a regional disaster. |
| App Service Environment (V2 and V3) | In Azure App Service Environment, You can make on-demand custom backups or use automatic backups. Automatic backups can be restored to a target app within the same App Service Environment, not in another App Service Environment. Custom backups can be restored to a target app in another App Service Environment (such as from a V2 App Service Environment to a V3 App Service Environment). Backups can be restored to a target app of the same OS platform as the source app. Refer to Back up and restore your app in Azure App Service for more details. |
We encourage you to implement disaster recovery guidance for web apps deployed to App Service Environment using commonly used disaster recovery techniques. |
| Azure Functions: Dedicated plan |
When you run your function app in a Dedicated (App Service) plan, required function app content is maintained using built-in storage. In a Dedicated plan, you can make on-demand custom backups or use automatic backups. You can restore a backup by overwriting an existing app or by restoring to a new app or slot. For more information, see Back up and restore your app in Azure App Service. Azure Files isn't used by a Dedicated plan, but if you have misconfigured your app with an Azure Files connection, backup isn't supported. |
Current guidance regarding how to bring function app resources in a Dedicated plan back online in a different Azure region during a regional disaster is available at Recover from region-wide failure - Azure App Service. Starting March 31, 2025, App Service applications won't be placed in disaster recovery mode during a disaster in an Azure region as explained in the recover from region-wide failure article. You should instead plan for reliability in your function apps. You can also refer to commonly used disaster recovery techniques for function apps in a Dedicated plan. |
| Azure Functions: Flex Consumption, Consumption, and Premium plans |
Function apps that run in a Flex Consumption plan, in a Consumption plan, or in a Premium plan can't use custom or automatic backup functionality in App Service. In these dynamic scale plans, function app content is maintained in Azure Storage. Use Azure Storage redundancy options to ensure your storage account meets its availability and durability targets during an outage. You can also download your existing function app project as a .zip file from the Azure portal. |
We strongly encourage you to plan for reliability in your function apps. |
Automatic vs. custom backups
There are two types of backups in App Service. Automatic backups are created for your app regularly as long as it's in a supported pricing tier. Custom backups require initial configuration and can be made on-demand or on a schedule. The following table shows the differences between the two types.
| Feature | Automatic backups | Custom backups |
|---|---|---|
| Pricing tiers | Basic, Standard, Premium, Isolated. | Basic, Standard, Premium, Isolated. |
| Configuration required | No. | Yes. |
| Backup size | 30 GB. | 10 GB, 4 GB of which can be the linked database. |
| Linked database | Not backed up. | The following linked databases can be backed up: SQL Database, Azure Database for MySQL, Azure Database for PostgreSQL, MySQL in-app. |
| Storage account required | No. | Yes. |
| Backup frequency | Hourly, not configurable. | Configurable. |
| Retention | 30 days, not configurable. - Days 1-3: hourly backups retained. - Days 4-14: every third hourly backup retained. - Days 15-30: every sixth hourly backup retained. |
0-30 days or indefinite. |
| Downloadable | No. | Yes, as Azure Storage blobs. |
| Partial backups | Not supported. | Supported. |
| Backups over a virtual network | Not supported. | Supported. |
Restore a backup
Note
App Service stops the target app or target slot while restoring a backup. To minimize downtime for a production app, restore the backup to a deployment slot first, then swap into production.
In your app management page in the Azure portal, in the left menu, select Backups. The Backups page lists all the automatic and custom backups for your app and the status of each.
Select the automatic backup or custom backup to restore by selecting its Restore link.
The Backup details section is automatically populated for you.
Specify the restore destination in Choose a destination. To restore to a new app, select Create new under the App Service box. To restore to a new deployment slot, select Create new under the Deployment slot box.
If you choose an existing slot, all existing data in its file system is erased and overwritten. The production slot has the same name as the app name.
You can choose to restore your site configuration under Advanced options.
Select Restore.
Create a custom backup
On your app management page in the Azure portal, in the left menu, select Backups.
At the top of the Backups page, select Configure custom backups.
In Storage account, select an existing storage account (in the same subscription) or select Create new. Do the same thing in Container.
To back up the linked databases, select Next: Advanced > Include database, and select the databases to backup.
Note
For a supported database to appear in this list, its connection string must exist in the Connection strings section of the Configuration page for your app.
In-app MySQL databases are always backed up without any configuration. If you make settings for in-app MySQL databases manually, such as adding connection strings, the backups might not work correctly.
Select Configure.
Once the storage account and container is configured, you can initiate an on-demand backup at any time. On-demand backups are retained indefinitely.
At the top of the Backups page, select Backup Now.
The custom backup is displayed in the list with a progress indicator. If it fails with an error, you can select the line item to see the error message.
Configure custom scheduled backups
On the Configure custom backups page, select Set schedule.
Configure the backup schedule as desired and then select Configure.
Back up and restore a linked database
Custom backups can include linked databases (except when the backup is configured over Azure Virtual Network). To make sure your backup includes a linked database, do the following:
- Make sure the linked database is supported.
- Create a connection string that points to your database. A database is considered "linked" to your app when there's a valid connection string for it in your app's configuration.
- Follow the steps in Create a custom backup to select the linked database in the Advanced tab.
To restore a database that's included in a custom backup:
- Follow the steps in Restore a backup.
- In Advanced options, select Include database.
For troubleshooting information, see Why is my linked database not backed up?.
Back up and restore over Azure Virtual Network
With custom backups, you can back up your app's files and configuration data to a firewall-protected storage account if the following requirements are fulfilled:
- The app is integrated with a virtual network, or the app is in a v3 App Service Environment.
- The storage account allows access from the virtual network that the app is integrated with, or that the v3 App Service Environment is created with.
To back up and restore over Azure Virtual Network:
- When configuring custom backups, select Backup/restore over virtual network integration.
- Save your settings by selecting Configure.
If you don't see the checkbox, or if the checkbox is disabled, verify that your resources fulfill the requirements.
Once the configuration is saved, any manual backup, scheduled backup, or restore is made through the virtual network. If you make changes to the app, the virtual network, or the storage account that prevent the app from accessing the storage account through the virtual network, the backup or restore operations fail.
Configure partial backups
Partial backups are supported for custom backups (but not for automatic backups). Sometimes you don't want to back up everything on your app. Here are a few examples:
- You set up weekly backups of your app that contains static content that never changes, such as old blog posts or images.
- Your app has over 10 GB of content. (That's the max amount you can back up at a time.)
- You don't want to back up the log files.
To exclude folders and files from being stored in your future backups, create a _backup.filter file in the %HOME%\site\wwwroot folder of your app. Specify the list of files and folders you want to exclude in this file.
Tip
You can access your files by navigating to https://<app-name>.scm.azurewebsites.net/DebugConsole. If prompted, sign in to your Azure account.
Identify the folders that you want to exclude from your backups. For example, say you want to filter out the highlighted folder and files.
Create a file called _backup.filter and put the preceding list in the file, but remove the root %HOME%. List one directory or file per line. The content of the file should be:
\site\wwwroot\Images\brand.png
\site\wwwroot\Images\2014
\site\wwwroot\Images\2013
Upload the _backup.filter file to the D:\home\site\wwwroot\ directory of your site by using FTP or any other method. If you want, you can create the file directly by using Kudu DebugConsole and insert the content there.
Run backups the same way you would normally do it: custom on-demand or custom scheduled. Any files and folders that are specified in _backup.filter are excluded from the future backups.
Note
_backup.filter changes the way a restore works. Without _backup.filter, restoring a backup deletes all existing files in the app and replaces them with the files in the backup. With _backup.filter, any content in the app's file system that's included in _backup.filter is left as is (not deleted).
How backups are stored
After you make one or more backups for your app, the backups are visible on the Containers page of your storage account and your app. In the storage account, each backup consists of a.zip file that contains the backup data and an .xml file that contains a manifest of the .zip file contents. You can unzip and browse through these files if you want to access your backups without actually performing an app restore.
The database backup for the app is stored in the root of the .zip file. For SQL Database, this is a BACPAC file (no file extension) and can be imported. To create a database in Azure SQL Database that's based on the BACPAC export, see Import a BACPAC file to create a database in Azure SQL Database.
Warning
Altering any of the files in your websitebackups container can cause the backup to become invalid and therefore non-restorable.
Error messages
The Backups page shows you the status of each backup. To get log details regarding a failed backup, select the line item in the list. Use the following table to help you troubleshoot your backup. If the failure isn't documented in the table, open a support ticket.
| Error | Fix |
|---|---|
| Storage access failed. | Delete the backup schedule and reconfigure it. Or reconfigure the backup storage. |
| The website + database size exceeds the {0} GB limit for backups. Your content size is {1} GB. | Exclude some files from the backup, or remove the database portion of the backup and use externally offered backups instead. |
| Error occurred while connecting to the database {0} on server {1}: Authentication to host '{1}' for user '<username>' using method 'mysql_native_password' failed with message: Unknown database '<db-name>' | Update the database connection string. |
| Cannot resolve {0}. {1} (CannotResolveStorageAccount) | Delete the backup schedule and reconfigure it. |
| Login failed for user '{0}'. | Update the database connection string. |
| Create Database copy of {0} ({1}) threw an exception. Could not create Database copy. | Use an administrative user in the connection string. |
| The server principal "<name>" is not able to access the database "master" under the current security context. Cannot open database "master" requested by the login. The login failed. Login failed for user '<name>'. | Use an administrative user in the connection string. |
| A network-related or instance-specific error occurred while establishing a connection to SQL Server. The server was not found or was not accessible. Verify that the instance name is correct and that SQL Server is configured to allow remote connections. (provider: Named Pipes Provider, error: 40 - Could not open a connection to SQL Server). | Ensure that the connection string is valid. Allow the app's outbound IPs in the database server settings. |
| Cannot open server "<name>" requested by the login. The login failed. | Ensure that the connection string is valid. |
| Missing mandatory parameters for valid Shared Access Signature. | Delete the backup schedule and reconfigure it. |
| SSL connection is required. Specify SSL options and retry when trying to connect. | SSL connectivity to Azure Database for MySQL and Azure Database for PostgreSQL isn't supported for database backups. Use the native backup feature in the respective database instead. |
Automate with scripts
You can automate backup management with scripts by using Azure CLI or Azure PowerShell.
For samples, see:
Frequently asked questions
- Are the backups incremental updates or complete backups?
- Does Azure Functions support automatic backups?
- What's included in an automatic backup?
- What's included in a custom backup?
- Why is my linked database not backed up?
- What happens if the backup size exceeds the allowable maximum?
- Can I use a storage account that has security features enabled?
- How do I restore to an app in a different subscription?
- How do I restore to an app in the same subscription but in a different region?
- Where are the automatic backups stored?
- How do I stop an automatic backup?
Are the backups incremental updates or complete backups?
Each backup is a complete offline copy of your app, not an incremental update.
Does Azure Functions support automatic backups?
Automatic backups are available for Azure Functions in dedicated (App Service) Basic, Standard, and Premium tiers. Automatic backups aren't supported for function apps in the Consumption or Elastic Premium pricing tiers.
What's included in an automatic backup?
The following table shows which content is backed up in an automatic backup:
| Content | Restored? |
|---|---|
Windows apps: All app content under the %HOME% directory.Linux apps: All app content under the /home directory.Custom containers (Windows and Linux): Content in persistent storage. |
Yes |
| Content of the run-from-ZIP package | No |
| Content from any custom-mounted Azure storage, such as from an Azure Files share | No |
The following table shows which app configurations are restored when you choose to restore app configurations:
| Settings | Restored? |
|---|---|
| Native log settings, including the Azure Storage account and container settings | Yes |
| Application Insights configuration | Yes |
| Health check | Yes |
| Network features, such as private endpoints, hybrid connections, and virtual network integration | No |
| Authentication | No |
| Managed identities | No |
| Custom domains | No |
| TLS/SSL | No |
| Scale out | No |
| Diagnostics with Azure Monitor | No |
| Alerts and Metrics | No |
| Backup | No |
| Associated deployment slots | No |
| Any linked database that custom backup supports | No |
What's included in a custom backup?
A custom backup (on-demand backup or scheduled backup) includes all content and configuration that's included in an automatic backup, plus any linked database, up to the allowable maximum size.
When backing up over Azure Virtual Network, you can't back up the linked database.
Why is my linked database not backed up?
Linked databases are backed up only for custom backups, up to the allowable maximum size. If the maximum backup size (10 GB) or the maximum database size (4 GB) is exceeded, your backup fails. Here are a few common reasons why your linked database isn't backed up:
- Backup of TLS-enabled Azure Database for MySQL isn't supported. If a backup is configured, you get backup failures.
- Backup of TLS-enabled Azure Database for PostgreSQL isn't supported. If a backup is configured, you get backup failures.
- In-app MySQL databases are automatically backed up without any configuration. If you make manual settings for in-app MySQL databases, such as adding connection strings, the backups might not work correctly.
What happens if the backup size exceeds the allowable maximum?
Automatic backups can't be restored if the backup size exceeds the maximum size. Similarly, custom backups fail if the maximum backup size or the maximum database size is exceeded. To reduce your storage size, consider moving files like logs, images, audio, and videos to Azure Storage, for example.
Can I use a storage account that has security features enabled?
You can back up to a firewall-protected storage account if it's part of the same virtual network topology as your app. See Back up and restore over Azure Virtual Network.
How do I restore to an app in a different subscription?
- Make a custom backup to an Azure Storage container.
- Download the backup ZIP file to your local machine.
- On the Backups page for your target app, select Restore in the top menu.
- In Backup details, select Storage in Source.
- Select the preferred storage account.
- In Zip file, select Upload file.
- In Name, select Browse and select the downloaded ZIP file.
- Configure the rest of the sections as described in Restore a backup.
How do I restore to an app in the same subscription but in a different region?
The steps are the same as in How do I restore to an app in a different subscription?.
Where are the automatic backups stored?
Automatic backups are stored in the same datacenter as the App Service. They shouldn't be relied upon as your disaster recovery plan.
How do I stop an automatic backup?
You can't stop automatic backups. The automatic backup is stored on the platform and has no effect on the underlying app instance or its storage.