Edit

Back up and restore your app in Azure App Service

  • Article

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 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 are supported in Basic, Standard, Premium, and Isolated tiers. For 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 ASE itself, not in another ASE.
  • Custom backups can be restored to a target app in another ASE, such as from a V2 ASE to a V3 ASE.
  • Backups can be restored to target app of the same OS platform as the source app.

Back up & restore vs. disaster recovery

Platform Back up & restore guidance Disaster recovery guidance
App Service Web Apps
(Free & Shared Pricing Tier)		 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 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. It's recommended to implement commonly used disaster recovery techniques to prevent downtime and data loss during a regional disaster.
App Service Web Apps
(Basic\Standard\Premium Pricing Tier)		 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 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 & V3) In Azure App Service Environment, You can make on-demand custom backups or utilize automatic backups. Automatic backups can be restored to a target app within the same ASE, not in another ASE. Custom backups can be restored to a target app in another ASE (such as from a V2 ASE to a V3 ASE). Backups can be restored to 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) In Azure Functions, You can make on-demand custom backups or utilize automatic backups. You can restore a backup by overwriting an existing app 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 Azure Functions app (dedicated) 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, 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. Instead, implement Azure Functions geo-disaster recovery.

Additionally you may also refer to commonly used disaster recovery techniques for Azure Functions dedicated.
Azure Functions Consumption & Premium Azure functions deployed to consumption and premium plans don't provide access to custom and automatic backups. Function app's content is in an Azure storage account. Use Azure Storage redundancy options to ensure your storage account meets its availability and durability targets during an outage.

If you created your functions by using the editor in the Azure portal, you can also download your existing function app project as a .zip file.		 We strongly encourage you to implement Azure Functions geo-disaster recovery and reliability.

Automatic vs. custom backups

There are two types of backups in App Service. Automatic backups made 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 3 hourly backup retained.
- Days 15-30: every 6 hourly backup retained.		 0-30 days or indefinite.
Downloadable No. Yes, as Azure Storage blobs.
Partial backups Not supported. Supported.

Restore a backup

Note

App Service stops the target app or target slot while restoring a backup. To minimize downtime for the production app, restore the backup to a deployment slot first, then swap into production.

  1. 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.

    Screenshot that shows how to open the backups page.

  2. Select the automatic backup or custom backup to restore by clicking its Restore link.

    Screenshot that shows how to select the restore link.

  3. The Backup details section is automatically populated for you.

  4. 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.

  5. You can choose to restore your site configuration under Advanced options.

  6. Click Restore.

Create a custom backup

  1. In your app management page in the Azure portal, in the left menu, select Backups.

    Screenshot that shows how to open the backups page.

  2. At the top of the Backups page, select Configure custom backups.

  3. In Storage account, select an existing storage account (in the same subscription) or select Create new. Do the same with 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 backed up always without any configuration. If you make settings for in-app MySQL databases manually, such as adding connection strings, the backups may not work correctly.

  4. Click 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.

  5. At the top of the Backups page, select Backup Now.

    Screenshot that shows how to make an on-demand backup.

    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

  1. In the Configure custom backups page, select Set schedule.

  2. Configure the backup schedule as desired and select Configure.

Back up and restore a linked database

Custom backups can include linked databases. To make sure your backup includes a linked database, do the following:

  1. Make sure the linked database is supported.
  2. 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.
  3. 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:

  1. Follow the steps in Restore a backup.
  2. In Advanced options, select Include database.

For troubleshooting information, see Why is my linked database not backed up.

Configure partial backups

Partial backups are supported for custom backups (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, you want to filter out the highlighted folder and files.

Screenshot that shows files and folders to exclude from backups.

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. So the content of the file should be:

\site\wwwroot\Images\brand.png
\site\wwwroot\Images\2014
\site\wwwroot\Images\2013

Upload _backup.filter file to the D:\home\site\wwwroot\ directory of your site using ftp or any other method. If you wish, you can create the file directly 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 have made 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 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 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 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 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). Check 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. Check 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. Please 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, using the Azure CLI or Azure PowerShell.

For samples, see:

Frequently asked questions

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 or Standard or Premium tiers. Function apps in the Consumption or Elastic Premium pricing tiers aren't supported for automatic backups.

What's included in an automatic backup?

The following table shows which content is backed up in an automatic backup:

Settings Restored?
Windows apps: All app content under %HOME% directory
Linux apps: All app content under /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 configuration is restored when you choose to restore app configuration:

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.

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:

  • Backups of TLS enabled Azure Database for MySQL isn't supported. If a backup is configured, you'll encounter backup failures.
  • Backups of TLS enabled Azure Database for PostgreSQL isn't supported. If a backup is configured, you'll encounter 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 may 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?

The following security features in Azure storage aren't supported for custom backups:

How do I restore to an app in a different subscription?

  1. Make a custom backup to an Azure Storage container.
  2. Download the backup ZIP file to your local machine.
  3. In the Backups page for your target app, select Restore in the top menu.
  4. In Backup details, select Storage in Source.
  5. Select the preferred storage account.
  6. In Zip file, select Upload file.
  7. In Name, select Browse and select the downloaded ZIP file.
  8. Configure the rest of the sections like 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 simple and stored in the same datacenter as the App Service and should not be relied upon as your disaster recovery plan.

How do I stop the automatic backup?

You cannot stop automatic backup. The automatic backup is stored on the platform and has no effect on the underlying app instance or its storage.

Next Steps

Azure Blob Storage documentation