IIS 7.0 : Managing Configuration - Delegating Configuration (part 2)

Directly Configuring Delegation

Although you can manage the delegation of many IIS features in the IIS Manager, it only allows you to manage the underlying configuration delegation for features that have corresponding UI pages in the IIS Manager. For those features, selecting the IIS Manager delegation state also generates the required configuration delegation settings to control whether the corresponding configuration sections can be used at the site or application level.

However, there are times when you will need to manage configuration delegation directly. One such case is when the configuration section does not have a corresponding IIS Manager feature. For example, IIS 7.0’s URL Filtering feature does not, at the time of this writing, have a UI component. In these cases, you can work with the configuration system directly or the Appcmd command line tool to configure the desired configuration delegation.

The initial ability to delegate a specific configuration section is controlled by the overrideModeDefault attribute on its declaration. Some of the built-in IIS 7.0 configuration sections like <defaultDocument> allow delegation by default by specifying Allow for this attribute in their declarations, and others like <serverRuntime> do not by specifying Deny. This decision is typically made by the developer of the feature that reads this configuration section, based on whether or not the feature configuration should be by default delegated to users who are not server administrators.

Caution

Do not change the overrideModeDefault setting on section declarations to unlock them. The IIS team recommendations for default delegation settings are well reasoned. If you need to override the default setting globally, use Location tags referencing the “*” path (or a null path, “”).

The overrideModeDefault setting on the section declarations in applicationHost.config sets the default value for delegation. You can modify the delegation status of each configuration section by locking or unlocking it. Unlocking sections is often needed in order to be able to specify configuration for certain sections in web.config files of your Web site. Likewise, you may want to lock certain other sections if you do not want the Web sites on your server to be able to override the settings set in applicationHost.config.

To unlock a section, you can use the Appcmd.exe command line tool as follows.

%windir%\system32\inetsrv\AppCmd Unlock Config /section:<SectionName>

Where <SectionName> is the name of the section, for example, “system.webServer/serverRuntime”.

To lock a section that is currently unlocked, you can use the following command.

%windir%\system32\inetsrv\AppCmd Lock Config /section:<SectionName>

Locking or unlocking a section produces a location tag in applicationHost.config that sets the delegation state of the configuration section by setting the overrideMode attribute to Allow or Deny. For example, if we use the unlock command shown previously to unlock the <serverRuntime> section, we will generate the following in applicationHost.config.

    <location path="" overrideMode="Allow">
        <system.webServer>
            <serverRuntime />
        </system.webServer>
    </location>

Likewise, you can lock or unlock configuration sections for a particular configuration path only, by specifying this path in the command. This can allow you, for example, to keep the configuration section locked for the entire server but allow a specific site to override its settings.

%windir%\system32\inetsrv\AppCmd Unlock Config "Default Web Site/"
/section:system.webServer/serverRuntime /commit:apphost

In this example, we unlock the <serverRuntime> section for the “Default Web Site” only and commit these changes to applicationHost.config (this is required). This produces a location tag in applicationHost.config that uses the path attribute to apply itself only to “Default Web Site/”.

This enables you to quickly manage the configuration delegation on a section level. However, sometimes it is necessary to allow the delegation of the section but keep control over a specific setting inside that section.

Additional Configuration for Remote Administration

For a user to manage a site or application remotely using the IIS Manager, it is necessary to assign specific permissions to the content. The service account for the Web Management Service (WMSvc) must have read and write permissions to web.config in order to successfully connect remotely.

Granular Configuration Locking

You have explored the configuration’s ability to lock and unlock sections for delegation and used the location tag for creating settings for a site or directory that override the inherited defaults. Feature delegation controls whether or not the entire section can be used in a configuration file at a certain level. However, there are some cases in which the configuration section contains some configuration that should be delegated and some configuration that should be locked.

To support these scenarios, the configuration system allows you to exercise more fine-grained control over what specific configuration settings should be delegated through granular locking. Granular locking is achieved through the use of special locking directives supported by the configuration system.

To use granular configuration locking, you have to edit the configuration through some means other than the IIS Manager. At this time, the IIS Manager does not support configuring granular locking.

Note

The semantics for granular locking are based on the configuration system for ASP.NET, so if you are familiar with that, you will be ahead of the game.

Granular configuration locking is accomplished by using one of the special attributes listed in Table 2.

Table 2. Granular Configuration Locking

Locking Directive	Used To
lockAttributes	Lock specific attributes to prevent them from being specified.
lockAllAttributesExcept	Lock all attributes on the element other than the specified attributes.
lockElements	Lock the specified elements to prevent them from being specified (and therefore lock all other attributes and child elements of the specified elements)
lockAllElementsExcept	Lock all elements on the current element except the specified elements.
lockItem	Lock the current collection element to prevent it from being removed.

lockAttributes, lockAllAttributesExcept

The lockAttributes configuration directive can be specified on a configuration element in order to lock specific attributes on the element and prevent them from being specified at lower configuration levels. The lockAttributes directive specifies a comma-separated list of attribute names that are valid for the current element.

For example, in order to allow the <defaultDocument> section to be delegated but make sure that the feature itself cannot be disabled, we can set the enabled attribute to “true” and then lock it using the lockAttributes directive as follows:

<defaultDocument enabled="true" lockAttributes="enabled">
  <files>
    <add value="Default.htm" />
    <add value="Default.asp" />
    <add value="index.htm" />
    <add value="index.html" />
    <add value="iisstart.htm" />
    <add value="default.aspx" />
  </files>
</defaultDocument>

In this example, lockAttributes instructs IIS 7.0 to disallow any change to the enabled attribute. As a result, if the Web administrator attempts to turn off the default document feature (enabled=“false”) the error message shown in Figure 2 occurs.

Figure 2. Error message due to configuration locking.

As you can see in Figure 4-6, the lock violation is called out and the offending line in web.config is clearly displayed. Removing this line, in this case, clears the error.

The lockAllAttributesExcept form of the attribute lock provides a convenient mechanism for cases in which you want to lock all attributes on the element except for one or two attributes that should be unlocked. In that case, you can use it instead of the lockAttributes element and specify the attributes that you want to keep unlocked.

lockElements, lockAllElementsExcept

The lockElements locking directive allows you to lock a particular child element of the current element (as opposed to an attribute). This prevents this element from being specified at lower configuration levels. The lockElements directive specifies a comma-separated list of element names to lock.

For example, we can use the lockElements directive to prevent the <files> collection of the <defaultDocument> section from being specified, therefore effectively preventing lower configuration levels from changing the contents of the default document list.

<defaultDocument enabled="true" lockElements="files" >
  <files>
    <add value="Default.htm" />
    <add value="Default.asp" />
    <add value="index.htm" />
    <add value="index.html" />
    <add value="iisstart.htm" />
    <add value="default.aspx" />
  </files>
</defaultDocument>

This setup prevents a Web administrator from changing the files in the default document list, but it does permit turning the feature on and off (via the enabled attribute).

The lockElements directive can also be used to do collection locking. By locking the ability to use certain collection elements (such as <add>, <remove>, and <clear>) it is possible to prevent the collection from being changed or prevent elements from being removed while still allowing new elements to be added.

For example, if you lock the <add> element (or the corresponding element that acts as the <add> element for the collection), lower configuration levels will not be able to add new elements to the collection. Likewise, if you lock the <remove> and <clear> elements, lower levels will not be able to remove elements from the collection but will be able to add new ones.

The lockAllElementsExcept directive can be used with configuration elements that have multiple subelements, when you want to lock all of them but one. In practice, we don’t expect that this will be widely used, but it is a possibility to keep in mind should you encounter a situation in which it is applicable.

lockItem

The lockItem directive can be used to lock specific collection elements from being removed or modified, as opposed to preventing all elements in the collection from being removed by locking the <remove> element using lockElements. The lockItem directive is specified on each collection element that is to be locked and accepts Boolean values.

Returning to our example, we want to allow a Web site administrator to be able to add new entries to the list of default pages but not remove Default.aspx from the list. In applicationHost.config, you can lock in the Default.aspx page by finding the configuration section in applicationHost.config as follows.

            <defaultDocument>
               <files>
                   <add value="Default.htm" />
                   <add value="Default.asp" />
                   <add value="index.htm" />
                   <add value="index.html" />
                   <add value="iisstart.htm" />
                   <add value="default.aspx" lockItem="true" />
               </files>
           </defaultDocument>

This will prevent lower configuration levels from being able to explicitly remove the Default.aspx entry, as well as using <clear/> to remove all items from the collection. They will still be able to add new entries to the collection.

An important use of lockItem is implemented in applicationHost.config. If you examine the <modules> section, you’ll notice that modules are added with lockItem set to “true.” This means that if IIS 7.0 encounters a <clear> or <remove> in a web.config or location tag that references the locked module, you will get a locking error. These locks are enabled by default since delegation is enabled for modules in order to permit .NET applications to add modules, a feature that is quite common. However, by delegating the modules section, it is also possible to remove modules in web.config. This could allow a user to inadvertently create an insecure or nonfunctional configuration. To prevent this from occurring, while at the same time ensuring maximum compatibility with .NET, modules are declared with lockItem specified as true.