Edit

Share via

Back up and restore your app in Azure App Service

  • Article

Important

Starting 3/31/2028, Azure App Service custom backups will no longer support backing up linked databases. See Deprecation of linked database backups for more information.

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, you can only back up and restore the production slot. For more information about scaling your App Service plan to use a higher tier, see Scale up an app in Azure.

Automatic vs. custom backups

There are two types of backups in App Service. If your app is in a supported pricing tier, automatic backups are created regularly. 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. Starting 3/31/2028, Azure App Service custom backups will no longer support backing up linked databases.

The following linked databases can be backed up: SQL Database, Azure Database for MySQL, Azure Database for PostgreSQL, MySQL in-app. Note that Azure DB for MySQL - Flexible Server and Azure DB for PostgreSQL - Flexible Server aren't supported in custom backups.
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, and then swap into production.

  1. In your app management pane in the Azure portal, select Backups on the left menu. The Backups page lists all the automatic and custom backups for your app and displays the status of each.

    Screenshot that shows how to open the backups page.

  2. Select the automatic or custom backup to restore. Select its 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 restore your site configuration under Advanced options.

  6. Select Restore.

Create a custom backup

  1. Go to your app management pane in the Azure portal. On the left menu, select Backups.

  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. Repeat in Container.

    To back up the linked databases, select Next: Advanced > Include database, and select the databases to backup.

    Note

    A supported database only appears in this list when its connection string exists 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 manually create settings for in-app MySQL databases, like adding connection strings, the backups might not work correctly.

  4. Select Configure.

    After the storage account and container are configured, you can initiate an on-demand backup at any time. On-demand backups are retained indefinitely.

  5. At the top of the Backups pane, 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

  1. On the Configure custom backups pane, select Set schedule.

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

Back up and restore a linked database

Note

Custom backups with linked databases for App Service support only Single Server tiers of Azure Database for MySQL and PostgreSQL. Since Single Server tiers are being retired, upgrading linked databases to Flexible Server might cause backups to fail. Use native database backup tools to prevent data loss. Standalone MySQL and PostgreSQL servers (for example, on VMs) are unaffected by the Single Server tier retirement. For retirement details, see MySQL Single Server retirement and PostgreSQL Single Server retirement.

For backup and restore of Flexible Servers, see the respective database documentation:

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, take the following steps:

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

Deprecation of linked database backups

Starting 3/31/2028, Azure App Service custom backups will no longer support backing up linked databases. We recommend using the native backup and restore tools provided by each database service instead. To help users prepare for this change, the App Service team will remove the option to include linked databases in new custom backup configurations according to the following schedule:

  • November 2025 – Removal for linked MySQL and PostgreSQL databases
  • April 2026 – Removal for linked Azure SQL and SQL Server databases Custom backups that already include linked databases will continue to back up those databases until 3/31/2028, after which linked databases will no longer be included.

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

To back up and restore over Azure Virtual Network:

  1. When configuring custom backups, select Backup/restore over virtual network integration.
  2. Select Configure to save your settings.

To enable backup/restore over a virtual network for deployment slots, complete the necessary steps specifically for each slot:

  • Virtual network integration is enabled for the deployment slots, or the slot is in a v3 App Service Environment.
  • The option for backup/restore over virtual network integration is selected for deployment slots.

If you don't see the checkbox, or if the checkbox is disabled, verify that your resources fulfill the requirements.

After 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 an app that contains static content that never changes (for example, old blog posts or images).
  • Your app has over 10 GB of content. (That's the maximum 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.

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. 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 as normal: 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 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 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 nonrestorable.

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 and reconfigure the backup schedule, or reconfigure the backup storage.
The website and 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.

How does backup and restore work with 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.

Automate with scripts

You can automate backup management with scripts by 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, 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.

Each backup contains a .zip file with backup data and an .xml file {siteName}-{dateTime}.xml, which lists the contents, including custom domains. When restoring a custom backup, custom domains from the .xml file will be added to the destination app if no DNS conflict exists (i.e., the domain is available for binding), and if the destination app has different custom domains than the .xml file's custom domain list, those custom domains will be removed.

When backing up over Azure Virtual Network, you can't back up the linked database.

Why is my linked database not backed up?

Note

Custom backups with linked databases for App Service support only Single Server tiers of Azure Database for MySQL and PostgreSQL. Since Single Server tiers are being retired, upgrading linked databases to Flexible Server might cause backups to fail. Use native database backup tools to prevent data loss. Standalone MySQL and PostgreSQL servers (for example, on VMs) are unaffected by the Single Server tier retirement. For retirement details, see MySQL Single Server retirement and PostgreSQL Single Server retirement.

For backup and restore of Flexible Servers, see the respective database documentation:

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?

  1. Make a custom backup of the source app to an Azure Storage container.
  2. Download the backup ZIP file and the XML metadata file to your local machine.
  3. Upload both the ZIP and XML files to the target storage account.
  4. In the Backups page of your target app, click Restore on the top menu.
  5. In the Backup details section, choose Storage as the Source. Select the storage account where you uploaded the backup files.
  6. Click Use file in storage account and select the ZIP file to restore.
  7. Configure the remaining settings as outlined in Restore a backup. Confirm and start the restore process.

How do I restore to an app in the same subscription but in a different region?

You can restore an app to a different region within the same subscription. The process follows the same steps outlined in Restore a backup. Ensure that the backup storage for the source app is accessible by the target app. The restoration process in the Azure portal allows selecting an app in a different region as long as it remains within the same subscription.

Where are the automatic backups stored?

Automatic backups are stored in the same datacenter as the App Service. We don't recommend that you rely on automatic backups 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.

Related content