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 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 Standard, Premium, Isolated. 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. 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.

Automatic backups Custom backups
Pricing tiers Standard, Premium. 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. 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 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 database(s), select Next: Advanced > Include database, and select the database(s) to back up.

    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.

Configure partial backups

Partial backups are supported for custom 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 in preview for Azure Functions in dedicated (App Service) 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 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.

Next Steps

Azure Blob Storage documentation