Anatomy of an IIS7 configuration path

If you have worked with IIS6 and previous versions of IIS, you are most likely familiar with the IIS metabase paths.  You know, the ones that look like LM/W3SVC/1/ROOT.  These metabase paths serve as a mechanism to identify a part of the IIS website hierarchy, or a url therein, for the purposes of read/writing their configuration settings.  For example, the server uses these paths at runtime to retrieve the settings for a particular site, virtual directory, or url in your website, and you use them to manage those settings for your site/virtual directory/url using tools like adsutil.vbs.

As you know, IIS7 repaces the metabase with a whole new configuration system, based on a distributed hierarchy of XML configuration files also used by the .NET Framework/ASP.NET.  This confguration system is fundamentally different from the metabase, and so it should come as no suprise that the way configuration paths work is also different. 

The concept of configuration paths is fundamental to managing and operating an IIS server, so I wanted to spend some time explaining it in hope that this can help everyone enjoy their IIS7 server just a little bit more 🙂  If you have come here wondering exactly what the hell is MACHINE/WEBROOT/APPHOST, you have come to the right place.

If you want to skip the background and go straight to how IIS7 configuration paths work, click here.

IIS6 Metabase paths – a blast from the past

First, lets take a quick detour and look at how metabase paths worked in previous versions of IIS.  The metabase was a centralized configuration file that contained a configuration tree, with each node of the tree containing a list of configuraton properties/values appropriate for it.  The metabase path uniquely identified a node in that tree, so you had something like this:

LM (root node)
    AppPools (application pool node)
        DefaultAppPool (default application pool)
    W3SVC (website node)
        1 (website id = 1)
            ROOT (website root)
                vdir1 (virtual directory path = /vdir1)

     …

The metabase hierarchy contained nodes for both the url hierarchy (the W3SVC node) and non-url objects such as Application Pools, FTP service, etc.  A metabase path for a url could then be constructed as LM/W3SVC/<SITEID>/ROOT/<VIRTUALPATH>, where <SITEID> identifies the site and <VIRTUALPATH> specifies the virtual path of the url.  This path can then be used to read the settings associated with it from the metabase using the ABO APIs, ADSI, WMI, and various scripts and tools including adsutil.vbs, iisweb.vbs, iisdir.vbs, aspnet_regiis, etc.

IIS7 Configuration paths

In IIS7, the configuration system stores configuration in a hierarchy of files, starting with 3 root configuration files, and descending into distributed web.config configuration files that can be present in any directory of your website to affect the configuration for the url namespace to which the directory corresponds.  This hierarchy contains the following:

Framework<version>CONFIGmachine.config (the .NET framework machine.config file, where most .NET sections are declared)
   Framework<version>CONFIGweb.config (the .NET framework root web.config file, where most ASP.NET sections are declared)
       %windir%system32inetsrvapplicationHost.config (the IIS7 global web server configuration file, where all IIS7 configuration sections are declared)
            delegated web.config files (the distributed configuration files that can be present in any virtual directory of your site or its subdirectory)

In this system, a configuration path has the following syntax:

                          MACHINE/WEBROOT/APPHOST/<SiteName>/<VirtualPath>

Where MACHINE, WEBROOT, and APPHOST correspond to the above configuration files, <SiteName> identifies the site, and <VirtualPath> identifies the virtual path.  Note that the site is no longer identified by id, as before, and instead the site name is used (in IIS7, site name is the unique identifier of a site, unlike the ServerComment in IIS6 which was not unique).

The concept of configuration path in the new world has a dual meaning – it can identify both a configuration file in the distributed file hierarchy, AND identify the configuration path (or url) to which configuration settings are applied. 

These concepts are related but not identical, which can be fairly confusing at first.  By default, configuration settings set at a particular file in the hierarchy that has path X are applicable to the configuration path X.  This means that configuration set in applicationHost.config, identified by the configuration path MACHINE/WEBROOT/APPHOST, is applicable to the configuration path MACHINE/WEBROOT/APPHOST and below (due to the hierarchical configuration inherita
nce).  All of the IIS7 configuration settings are by default set at this path, and apply to all sites on the machine.

Likewise, by default, if configuration is written to "MACHINE/WEBROOT/APPHOST/Default Web Site/", it will be placed in the web.config file in the root of "Default Web Site", and apply to all urls in the site.

However, the configuration system supports the concept of location tags, which allow configuration to be set at the configuration path X, but apply only to a child configuration path.  For example, in the applicationHost.config file, it is possible to set configuration like this:

<location path="Default Web Site/vdir1">
   <system.webServer>
      <directoryBrowse enabled="true" />
   </system.webServer>
</location> 

While set at MACHINE/WEBROOT/APPHOST, this configuration is not effective there.  Instead, this configuration applies only to "MACHINE/WEBROOT/APPHOST/Default Web Site/vdir1" and will only be visible when read there.  It is effectively equivalent to specifying the configuration in a web.config file in the "vdir1" virtual directory of the "Default Web Site".

This example reflects the choice you have as an IIS7 administrator when setting configuration for a particular path:

1. Directly at the path itself by placing it in the configuration file that corresponds to the file (creating a delegated, and XCOPY-deployable configuration), or
2. Anywhere above it in the hierarchy, using location tags to apply it to a lower path (creating controlled, centralized configuration). 

You can use this ability to select a set of configuration that is set in an administrator controlled location (such as the applicationHost.config file), and allow the rest of the configuration to be set by the application owner directly in their application using distributed web.config files.  To learn more about configuration locking, see http://www.iis.net/articles/view.aspx/IIS7/Managing-IIS7/Delegation-in-IIS7/Delegating-Permission-in-Config/How-to-Use-Locking-in-IIS7-Configuration.

Finally, a note: the configuration paths in IIS7 DO NOT SPECIFY the actual configuration that you are setting, only the level at which it is set / level at which the configuration applies.  This is somewhat unlike IIS6 metabase paths which sometimes carry information about the object being configured, such as the AppPool node.  In IIS7, all configuration is stored in section and so you need to specify which section you’d like to edit and set its properties in addition to specifying at which level it should be set.

Using IIS7 configuration paths to manage configuration

Armed with the knowledge about IIS7 configuration paths, lets jump into a few examples of managing your IIS7 server that require the use of these paths.  These examples use the AppCmd.exe, although, you will also use the same paths when working with other configuration APIs like Adadmin COM objects, Microsoft.Web.Administration, and WMI.

When working with AppCmd, it is often possible to omit "MACHINE/WEBROOT/APPHOST" when specifying a configuration path, and instead just use the "<SITENAME>/<VIRTUALPATH>" part of it.

1) Finding a site named "Default Web Site"

> %windir%system32inetsrvAppCmd.exe List Site "Default Web Site"

The path to a site is just its name (remember the AppCmd support for omitting the M/W/A part of the path).

2) Finding an application with path /App1 under "Default Web Site"

> %windir%system32inetsrvAppCmd.exe List Site "Default Web Site/App1"

The path to the application is the SITENAME/VirtualPath where VirtualPath is the virtual path of the application.

For more info on the IIS7 site, application, and virtual directory structure and how to manage these objects, see my earlier post about creating IIS7 sites, applications, and virtual directories.

 3) Setting configuration for the root of the "Default Web Site"

> %windir%system32inetsrvAppCmd.exe Set Config "Default Web Site/" /section:directoryBrowse /enabled:true

Applied configuration changes to section "system.webServer/directoryBrowse" for "MACHINE/WEBROOT/APPHOST/Default Web Site/" at configuration commit path "MACHINE/WEBROOT/APPHOST/Default Web Site/"

Note that the tool by default wrote the settings to the web.config in the root of the Default Web Site, because that is what the MACHINE/WEBROOT/APPHOST/Default Web Site/ path corresponds to in the file hierarchy.  These settings will be effective for that same path (and below).

4) Settings configuration for the root of the "Default Web Site", but setting them at the global (applicationHost.config) level.

> %windir%system32inetsrvAppCmd.exe Set Config "Default Web Site/" /section:directoryBrowse /enabled:true /COMMIT:MACHINE/WEBROOT/APPHOST

Applied configuration changes to section "system.webServer/directoryBrowse" for "MACHINE/WEBROOT/APPHOST/Default Web Site/" at configuration commit path "MACHINE/WEBROOT/APPHOST"

Note the usage of the commit parameter to force the configuration path to be MACHINE/WEBROOT/APPHOST, which results in the configuration being written to applicationHost.config with a location tag to apply them to the MACHINE/WEBROOT/APPHOST/Default Web Site/ configuration path.  If you were to open applicationHost.config, you will find the following:

    <location path="Default Web Site">
        <system.webServer>
            <directoryBrowse enabled="true" />
        </system.webServer>
    </location>

If you were to now read the effective configuration for the server at the global level by using the command below, you will notice that directory browsing is turned OFF there (unless you changed that), meaning that it is turned off by default for all websites. 

> %windir%system32inetsrvAppCmd.exe List Config MACHINE/WEBROOT/APPHOST /
section:directoryBrowse

However, if you then see what the settings are for the “Default Web Site/”, you’ll see that directory browsing is turned ON there.  This would be the case if you set that configuration directly at the root web.config for the website using step #3, or set it in applicationHost.config with a location tag in step #4. 

I hope this example helps you understand the IIS7 configuration paths and how to use them to manage your server.  Please comment and let me know if there is anything else that you think needs to be explained here.

Thanks,

Mike