Mike Volodarsky's blog

Formerly the core server PM for IIS 7.0 and ASP.NET, now I run LeanSentry.
UPDATES: New troubleshooting guide released! Fix IIS website hangs →

Most Important AppCmd Commands: Backing up and restoring IIS7 configuration

Welcome to the first post of the "Most Important AppCmd Commands" series.  Have you ever made some changes to a system's state, and then after everything suddenly stopped working, wondered how the hell you are going to get back to a working state?  Well, this post is all about doing just that when you are working with IIS7's configuration.

Usually, the state of the IIS7 server is comprised of the following things: 1) the installed IIS7 files managed by Windows setup, 2) the IIS7 configuration, and 3) your application files.  The first is protected by System File Protection, so its not easy to accidentally mess up, and can be restored by using Windows setup.  The application files are your own, and one would expect to have a backup of these somewhere so that you can recover from making unintended changes to them on the server. 

The IIS7 configuration is our focus here, because its something that is frequently modified by different components during their installation, or by you in order to configure your application to behave in the specific way you need.  In previous versions of IIS, this configuration was stored exclusively in the metabase, which was first a binary (IIS 4) and then an XML (IIS5-6) file in the %windir%system32inetsrv directory.  With IIS7, even though most configuration can be stored in the distributed web.config files within the application hierarchy, and therefore can be backed up with the application itself, a number of settings still need to be stored in a central server configuration file, called applicationHost.config.  This file contains the site/application/virtual directory/application pool definitions, and the default configuration settings for all sites on the machine.

As such, any time you create / delete sites or applications, or set global configuration on the server, applicationHost.config is modified.  If you accidentally make changes to this file that cause undesired behavior, you will often want to restore a previous known-good version of this file instead of trying to modify the file piece by piece to get back to a good state.

To enable this, AppCmd.exe provides the BACKUP object that allows you to easily back-up, and restore the global server configuration.  To get more information about the commands of the BACKUP object, type in: AppCmd backup /?

1) Creating a backup

To create a backup, simply type in:

>AppCmd Add Backup "BackupName"

You can omit the name, in which case AppCmd is going to generate the backup name automatically using the current date and time.  When a backup is created, the following happens:

  1. A directory with the backup name is created under the %windir%system32inetsrvbackup directory.
  2. AppCmd copies the current configuration files into the backup directory, including applicationHost.config (IIS global configuration), administration.config (Admin Tool's configuration), metabase.xml and mbschema.xml.  The last two files contain the metabase data that is still used by some IIS services including SMTP and FTP, that have not been migrated to the new configuration system.  AppCmd only backs up the files that are there, so if you delete any of these files, and then make a backup, the backup will not contain the missing files. 

2) Managing existing backups

To list the backups that exist on the server, type in:

>AppCmd List Backup

This will list the backup objects, including their names that can be used to restore or delete them.  To delete any of these backups if its no longer needed, type in:

>AppCmd List Backup "BackupName"

3) Restoring a backup

To restore a backup, type in:

>AppCmd Restore Backup "BackupName"

This will stop IIS (equivalent to calling IISRESET.EXE /STOP), and overwrite the server's state with the files in the specified backup directory.  Then, IIS will be re-started (equivalent to calling IISRESET.EXE /START).

Managing IIS7 backups with AppCmd 

If you do no want AppCmd to stop IIS (which can take a while), and instead want to stop and start services yourself, you can include the /stop:false parameter.  Typically, only the IISADMIN service requires to be stopped so that the mbschema.xml file can be restored, if services like FTP or SMTP are being used.  Other files, including applicationHost.config and administration.config, are not locked by the configuration system so they can be restored without stopping IIS, and IIS components will pick up the changes.

I recommend that you make backups every time before making significant changes to the IIS7 configuration, which can save you a lot of time when something doesnt go as planned.  I've watched "AppCmd Restore Backup" come to the rescue more times then I can count, so its almost always the first thing that I do when I begin working with a new server, or help someone on the team investigate an issue.

In Windows Server "Longhorn" beta 3, we are adding a Configuration History service that automatically makes configuration backups every 2 minutes whenever configuration is changed.  This often eliminates the need to do manual backups, but not completely - often its desireable to make a backup at a specific point before making changes, so that that exact state is saved and can be restored at any point.  More info on the Configuration History service in a future post ...

Most Important AppCmd Commands

Usually, a day doesnt go by that I dont get a collegue or a partner team in Microsoft asking how to do something or other about AppCmd.exe, the unified command line management tool for the IIS7 server.  Since its inception in the fall of 2005, the tool has been becoming increasingly popular internally - IIS7 setup code, stress and performance automation scripts, and many of Windows partner teams rely on AppCmd to perform IIS7 setup, configuration, and management tasks.  Since another IIS developer and I wrote the tool, we (or actually mostly I) constantly get bombarded by requests to give people commands to do what they want. 

For a while, I've been thinking about blogging about the most commonly used commands to assist people get going with managing IIS7 from the command line - and so the "Most Important AppCmd Commands" post series was born.

Before I jump into the first post, here are some good resources that should be your first stop whenever you need to use AppCmd:

  1. AppCmd command line help. 

    The tool comes with detaled built-in help that describes every object and command supported by the tool.  When in doubt:

    AppCmd /?
    Display the objects supported by appcmd.

    AppCmd Site /?          
    Display the command supported by the "Site" object.

    AppCmd Add Site /?  
    Display the parameters and examples for using the "Add" command on the "Site" object.

  2. AppCmd online guide: http://www.iis.net/default.aspx?tabid=2&subtabid=25&i=954&p=1

    This guide describes the most important parts of AppCmd, and is a good way to discover functionality as well as see examples of its usage.

Without further ado, here is the first post in this series - Backing up and restoring IIS7 configuration.