IIS 7.0 : Configuration File Hierarchy

The IIS 7.0 configuration system is in many ways a complete departure from the metabase, the configuration model that previous IIS versions use. The new architecture reflects requirements that the IIS 7.0 configuration system be more manageable and flexible in supporting key deployment scenarios.

The IIS 7.0 configuration system is based on a hierarchy of XML configuration files, which contain structured XML data that describes the configuration information for IIS and its features. This hierarchy includes the .NET Framework configuration files, machine.config and root web.config; the main IIS configuration file called applicationHost.config; and distributed web.config configuration files located inside the Web site directory structure. One key benefit of this hierarchy is the ability to unify the location of IIS and ASP.NET configuration information. The other is the ability to include IIS configuration together with the Web site’s content, which makes the Web site portable and alleviates the need to have administrative privileges to deploy the Web site.

The configuration files in the hierarchy contain configuration sections, which are structured XML elements that describe configuration settings for specific IIS features. Unlike the property/value model used by the metabase, the structured XML nature of the IIS 7.0 configuration sections helps the configuration become cleaner and easier to understand. This makes configuration self-explanatory, and you can easily edit it by hand. For example, the application developer can place the following configuration in a web.config file located in the root of the Web site to enable the IIS default document feature and configure a specific default document to be used.

<system.webServer>
  <defaultDocument enabled="true">
    <files>
      <add value="home.aspx" />
    </files>
  </defaultDocument>
</system.webServer>

Because the IIS 7.0 configuration system uses the same web.config files as the ASP.NET configuration system, your application can provide both ASP.NET and IIS configuration settings side by side in the same file. Because this file travels with your application content, it enables the application to be deployed to an IIS server simply by copying its contents, without having to modify any central configuration.

At the same time, the server administrator can place server-level IIS configuration, such as the Web site and Application pool definitions, in the server-level applicationHost.config file. This file can also contain the default configuration for other IIS sections, which are by default inherited by all Web sites on the server. Unlike the Web site’s web.config files, which may be accessible to the Web site or application administrator, applicationHost.config is accessible only to the server administrator. Using the configuration-locking mechanisms that the configuration system provides, the administrator can specify which configuration can be modified by applications through the use of distributed web.config files.

All in all, the new configuration file hierarchy offers a lot more flexibility than the IIS 6.0 metabase and enables key deployment and management scenarios. Next, we will look at how the configuration file hierarchy works and the syntax of configuration sections.

Configuration File Hierarchy

The metabase in previous versions of IIS was comprised of a single configuration file, Metabase.xml, that contained a URL-centric configuration tree. Nodes of that tree corresponded to URLs on the server, and each node contained a set of properties that specified the configuration for that URL along with properties inherited from parent nodes. If you are familiar with the IIS 6.0 metabase, you may remember that these nodes are addressed via paths that look something like “LM\W3SVC\1\ROOT”, which translates to “the root of the Web site with ID of 1.”

In IIS 7.0, configuration file hierarchy includes multiple configuration files. Instead of encoding the entire URL hierarchy in a single file, the configuration file hierarchy maps to the URL hierarchy. Each file defines configuration that is implicitly associated with a specific URL level based on the position of this file in the configuration hierarchy. For example, applicationHost.config contains global settings applying to all sites on the server, and web.config, contained in the Web site root, is site-specific—and when contained in an application directory, it is directory-specific. Web.config typically maps to a URL such as http://www.contoso.com/appfolder. Note that the use of web.config to contain distributed configuration information is optional (but enabled by default for certain settings). ApplicationHost.config can and often does contain site- and application-specific settings. There are other configuration files involved with IIS 7.0, but for the sake of simplicity, we’ll focus on the files used to configure sites and applications, as listed in Table 1.

Table 1. IIS 7.0 Configuration Files

File	Location	Configuration Path
machine.config	%windir%\Microsoft .NET\Framework \<version>\config	MACHINE
root web.config	%windir%\Microsoft .NET\Framework \<version>\config	MACHINE/WEBROOT
applicationHost.config	%windir%\system32\inetsrv\config	MACHINE/WEBROOT/APPHOST
distributed web.config files	Web site directory structure	MACHINE/WEBROOT/APPHOST/<SiteName>/<VirtualPath>

Just like the metabase, the IIS 7.0 configuration system uses a configuration path to describe the level in the configuration hierarchy where a particular configuration setting is set. This level corresponds both to the URL namespace at which the configuration is effective and a configuration path used in commands (such as when using Appcmd) to reference the correct configuration store. In this way, the IIS 7.0 configuration file hierarchy maps to the URL namespace and can correspond to an actual configuration file where this configuration is set.

When the configuration system retrieves configuration for a specific configuration path, it merges the contents of each configuration file corresponding to each segment of the path, building an effective configuration set for that path. This works well with the ability to specify distributed web.config files inside the Web site’s directory structure, which may enable any part of the Web site to set specific configuration for its URL namespace simply by including it in a web.config file in the corresponding directory.

In this system, the configuration path for a particular URL becomes MACHINE/WEBROOT/APPHOST/<SiteName>/<VirtualPath>, where the <SiteName> is the name of the site and the <VirtualPath> is the URL’s virtual path. When reading configuration for this path, the server will merge the configuration in machine.config, root web.config, applicationHost.config, and all distributed web.config files that exist in the physical directories corresponding to each segment of the virtual path, starting with the site’s root.

Important

The root web.config corresponding to WEBROOT in the configuration system is the one located in %windir%\Microsoft .NET\Framework \<version>\config. This is not the same as a web.config file that can placed in a Web site’s home directory, which is often referred to as the web root. In the first case, we are talking about web.config used by .NET that is the parent, or root of all Web site web.config files. In the latter case, we’re talking about the web.config found in a Web site’s home folder. The web.config in the Web site’s home folder will inherit configuration settings found in the .NET root web.config.

Server-level configuration for IIS features is stored in the applicationHost.config file. This file stores configuration for sections that only make sense globally on the server, as well as configuration defaults for other sections that are inherited by all URLs on the server unless another file lower in the configuration hierarchy overrides them.

For example, if you wanted to configure the server to disable directory browsing by default, you would put that configuration in the applicationHost.config file. Then, if you wanted to allow directory browsing for the /App1 application in the default Web site, you would place a web.config file containing configuration that enables directory browsing in the physical directory root of the /App1 application. When a request is made to the root of the default Web site, the server will read configuration for the “MACHINE/WEBROOT/APPHOST/Default Web Site/” path and apply the inherited configuration from applicationHost.config that disables the directory browsing. However, when an HTTP request is made to the /App1 application, the server will read configuration for “MACHINE/WEBROOT/APPHOST/Default Web Site/App1/”, which merges the configuration set by the application’s web.config and enables directory browsing for that URL.

machine.config and root web.config

Even though machine.config and the root.web.config are .NET Framework configuration files, they are read and mapped in by the IIS configuration system. This allows IIS 7.0 to share its configuration with ASP.NET in site and application web.config files, consume .NET modules in the managed pipeline, and integrate .NET configuration that is enabled in the IIS Manager. As previously mentioned, machine.config contains machine-wide .NET Framework configuration settings loaded by all .NET applications on the machine, and root web.config contains ASP.NET-specific configuration settings loaded by all ASP.NET applications. These files are modifiable only by machine administrators.

These files are located in the %windir%\Microsoft .NET\.NET Framework \<version>\config, where the <version> is determined by the managedRuntimeVersion setting for the application pool within which the configuration is being read. This way, IIS application pools that are set to use different versions of the .NET Framework automatically include the configuration files for the right .NET Framework version. Note that as in IIS 6.0, an application pool cannot host more than one version of the .NET Framework.

applicationHost.config

The main IIS configuration file is applicationHost.config, which is located in the %windir%\system32\ inetsrv\config directory. It is modifiable only by machine administrators.

ApplicationHost.config contains configuration sections and settings that only make sense globally on the server. For example, it contains site, application, and virtual directory definitions in the <sites> section and the application pool definitions for the <applicationPools> section. Other global sections include the <globalModules> configuration section, which contains a list of native modules that are loaded by all IIS worker processes, and the <httpCompression> section that lists enabled compression schemes and content types that can be compressed. These sections cannot be overridden at lower levels, and the server only reads them at the MACHINE/WEBROOT/APPHOST level.

ApplicationHost.config also stores all of the default settings for IIS configuration sections, which are inherited by all other URLs unless another configuration file lower in the configuration hierarchy overrides them. In fact, if you examine the contents of applicationHost.config, you will see that it declares all IIS configuration sections.

    <configSections>
        <sectionGroup name="system.applicationHost">
            <section name="applicationPools" allowDefinition="AppHostOnly"
overrideModeDefault="Deny" />
            <section name="sites" allowDefinition="AppHostOnly"
overrideModeDefault="Deny" />
            <section name="webLimits" allowDefinition="AppHostOnly"
overrideModeDefault="Deny" />
            ...
        </sectionGroup>

        <sectionGroup name="system.webServer">
            <section name="asp" overrideModeDefault="Deny" />
            <section name="caching" overrideModeDefault="Allow" />
            <section name="cgi" overrideModeDefault="Deny" />
            <section name="defaultDocument" overrideModeDefault="Allow" />
            <section name="directoryBrowse" overrideModeDefault="Allow" />
            ...
        </sectionGroup>
    </configSections>

You may notice that these section definitions include an element named allowDefinition that is set in our example to “AppHostOnly”. The allowDefinition settings assign a scope to the section that limits where the section can be used. In this case, the Sites section can only be used in applicationHost.config and is not legal in any other location. It is strongly recommended that you do not edit the allowDefinition settings from the defaults.

Finally, this file also contains information about which configuration sections are allowed to be overridden by lower configuration levels, and which are not. Child override is controlled by the overrideModeDefault attribute in the example just provided of the configuration sections declarations. The server administrator can use this attribute to control the delegation of IIS features to the site administrators.

Distributed web.config Files

The IIS 7.0 configuration hierarchy enables the site directory structure to contain web.config configuration files. These files can specify new configuration settings or override configuration settings set at the server level for the URL namespace corresponding to the directory where they are located (assuming the configuration sections used are unlocked by the administrator).

This is the foundation for the delegated configuration scenario, which enables applications to specify required IIS settings together with their content, and which makes simple xcopy deployment possible.

Finally, because the ASP.NET configuration system also reads these files, they can contain both IIS and ASP.NET configuration settings.

redirection.config

You will also find redirection.config located in the %windir%\system32\ inetsrv\config directory, and it is used to store configuration settings for Shared Configuration. It is not part of the IIS 7.0 configuration hierarchy, but the configuration system uses it to set up redirection for the applicationHost.config file.

When in use, it specifies the location and access details required for IIS 7.0 to load applicationHost.config from a remote network location, instead of the local inetsrv\config directory. This enables multiple IIS 7.0 servers to share a central configuration file for ease of management.

administration.config

The IIS Manager tool uses administration.config (also not part of the IIS 7.0 configuration hierarchy) exclusively to specify its own configuration. It is also located in the %windir%\system32\ inetsrv\config directory.

Among other things, administration.config contains the list of IIS Manager extensions that the tool loads. These extensions provide the features you see in the IIS Manager. Like IIS, the IIS Manager is fully extensible.

Temporary Application Pool .config Files

One of the new IIS 7.0 features is enhanced Application Pool Isolation. At run time, IIS 7.0 reads applicationHost.config configuration and generates filtered copies of it for each application pool, writing them to:

%systemdrive%\inetpub\temp\appPools\<ApplicationPoolName>.config

The filtered configuration files contain only the application pool definitions for the current application pool (other application pool definitions that may contain custom application pool identities are filtered out). Also removed are all site definitions and site-specific configuration specified in location tags for sites that do not have applications in the current application pool.

The temporary configuration file created for each application pool is protected in such a way that only the application pool for which it is created can read the file. This ensures that no worker process (application pool) can read the configuration settings for any other worker process.

The application pool configuration files are not intended to be used for updates, and neither administrators nor developers should edit them directly or indirectly. Their use is completely transparent, but it is part of the configuration system, so we thought it should be called out here.