IIS 7.0 : Managing Administration Extensions

The IIS 7.0 configuration system provides a structured mechanism for controlling the behavior of IIS and its features. In a way, the configuration system exposes an object model for IIS, enabling you to inspect and control IIS objects such as sites, application pools, applications, and virtual directories. The configuration system is also extensible through the configuration section schema, which enables additional Web server functionality to expose configuration through its object model.

Though the ability to manage Web server configuration is its primary purpose, the IIS 7.0 configuration system takes the concept of a management object model to the next logical level. It enables configuration sections to also expose dynamic properties and methods that are backed by code instead of static configuration data.

This is done through the use of administration extensions to the configuration system. A great example of the value that administration extensions bring to IIS 7.0 administration is IIS 7.0’s own <applicationPools> configuration section, which contains a collection of application pool definitions and associated configuration. IIS 7.0 also ships a schema extension to this section, adding dynamic attributes and methods backed by the Runtime State and Control API (RSCA). This enables the reader of the <applicationPools> configuration section to also retrieve run-time information for each application pool element, including:

• Its state (started/stopped)

• The list of currently running worker processes in the application pool

• The list of currently executing requests in each worker process

• The list of currently loaded ASP.NET appdomains in each worker process

In addition, it exposes methods that enable the caller to recycle each application pool or unload an ASP.NET appdomain in a particular worker process. All of this functionality is exposed through the same APIs that are used to navigate the configuration object model, blurring the line between static configuration and run-time behavior exposed by IIS objects.

For example, here is a C# script that uses the IIS 7.0 configuration objects to list all application pools on the system, including some of their configuration information and the list of currently executing worker processes (provided by the RSCA administration extension):

    var adminManager = new ActiveXObject("Microsoft.ApplicationHost.AdminManager");

    var appPoolsSection = adminManager.GetAdminSection(
        "system.applicationHost/applicationPools",
         "MACHINE/WEBROOT/APPHOST");

    //
    //  Enumerate the application pools collection
    //
    var appPoolsCollection = appPoolsSection.Collection;
    for(var i = 0; i < appPoolsCollection.Count; i++)
    {
        var appPoolElement = appPoolsCollection.Item(i);

        var name = appPoolElement.GetPropertyByName("name").Value;
   var appPoolStateProperty = appPoolElement.GetPropertyByName("state");
        var state =
                appPoolStateProperty.Schema.PossibleValues.Item
                             (
                               appPoolStateProperty.Value
                             ).Name;
        WScript.Echo("Application Pool *" + name + "* (" + state + ")");

        //
        //  Enumerate the worker processes collection
        //
        var workerProcessesElement =
appPoolElement.ChildElements.Item("workerProcesses");
        var workerProcessCollection = workerProcessesElement.Collection;

        for(var wp = 0; wp < workerProcessCollection.Count; wp++)
        {
            var workerProcess = workerProcessCollection.Item(wp);
            WScript.Echo("  Worker process - " +
workerProcess.GetPropertyByName("processId").Value);
        }
    }

A sample output of this script (which follows) shows the application pools configured on the machine, their state, and the list of active worker processes in each pool. The latter two pieces of information come from the RSCA administration extension, yet the programming experience to access them is indistinguishable from accessing attributes coming from configuration. The sample output looks like this:

Application Pool *DefaultAppPool* (Started)
  Worker process - 2900
Application Pool *Classic .NET AppPool* (Started)

In addition to exposing run-time information through the configuration object model, administration extensions also provide a convenient way to package administration or deployment tasks and expose them as methods on the related configuration sections. Next, you will look at how administration extensions work.

How Administration Extensions Work

An administration extension is a COM object that implements one or more interfaces published by the IIS 7.0 configuration system to provide values of dynamic attributes and/or execute dynamic methods on configuration sections.

It is linked to the section via the section’s schema definition. For dynamic attributes, the attribute definition can simply specify the COM ProgId of the administration extension’s COM object via the extension schema property. The schema can also contain method definitions for dynamic methods that can accept arguments and return information. For an example of both, we can turn to the RSCA extension schema, contained in Rscaext.xml, that adds the dynamic functionality to the base <sites> and <applicationPools> configuration sections.

  <sectionSchema name="system.applicationHost/sites">
    <collection addElement="site">
      <attribute name="state" type="enum"
extension="Microsoft.ApplicationHost.RscaExtension">
        <enum name="Starting" value="0" />
        <enum name="Started" value="1" />
        <enum name="Stopping" value="2" />
        <enum name="Stopped" value="3" />
        <enum name="Unknown" value="4" />
      </attribute>
      <method name="Start"
extension="Microsoft.ApplicationHost.RscaExtension" />
      <method name="Stop"
extension="Microsoft.ApplicationHost.RscaExtension" />
    </collection>
  </sectionSchema>

The schema adds a state attribute to each <site> element, which is backed by the Microsoft.ApplicationHost.RscaExtension COM object. It also defines the Start and Stop methods that are also backed by that extension.

Note

You may notice that the Rscaext.xml file contains schema definitions for dynamic attributes and methods for already defined <sites> and <applicationPools> configuration sections. This takes advantage of the configuration schema merging support in the configuration system, which enables new schema files to extend existing configuration sections and not just add new ones.

When the configuration script accesses the dynamic properties or invokes the dynamic methods in the configuration section, the administration extension is invoked to provide the attribute value and execute the method. If the caller does not ask for dynamic attributes or invoke methods, then the Administration extension is never created and invoked, and the user continues to work with static configuration only.

Installing Administration Extensions

To install administration extensions, register them with the section schema, either as part of new configuration section definitions or by adding new dynamic attributes and method definitions for existing configuration sections. From the schema perspective, the installation of new Administration extensions is the same as installing new configuration sections .

Because Administration extensions are backed by COM objects, the COM object that implements the required interfaces must be registered on the system (this is typically done with Regsvr32.exe or with Regasm.exe for .NET COM objects). The COM registration information must include the friendly ProgId name that is referenced in the configuration section schema.

Securing Administration Extensions

Unlike configuration sections, Administration extensions contain code and therefore pose a risk to your server. What’s more, Administration extensions are invoked by management tools and scripts that are typically run by Administrators, which enables their code to execute with administrative privileges. In fact, many administration extensions require administrative privileges to operate, including the RSCA extension that is included with IIS 7.0.

This is in contrast with Web server modules that by default execute in IIS worker processes that run under lower privilege identities and can be further sandboxed by ASP.NET’s Code Access Security (for managed modules). Therefore, Administration extensions can pose a significantly higher risk to the server then Web server modules.

The ability to publish configuration section schema is restricted to Administrators (as is the ability to register COM objects on the machine). This eliminates the possibility of untrusted users on the machine being able to register Administration extensions. However, Administrators themselves must exercise caution when installing administrative extensions and be sure to trust the source of each extension.

Table 1 shows some of the configuration system’s typical users that have the ability to load and invoke administration extensions.

Table 1. Users and Privileges for Administration Extensions

User	Execution Privilege
WAS	Does not use extensions
IIS Worker Processes	Does not use extensions
Metabase Compatibility (Inetinfo.exe)	Does not use extensions
WMI Service	Local System
Appcmd	Does not use extensions
IIS Manager (Inetmgr.exe)	Caller (typically Administrator)
Configuration scripts, Microsoft.Web.Administration programs	Caller (typically Administrator)

WAS, IIS worker processes, Metabase Compatibility, and Appcmd.exe all disable the use of administration extensions (for different reasons). However, the WMI service, scripts that use the configuration system COM objects, and .NET programs that use the Microsoft.Web.Administration APIs all have access to running administration extensions and often run (and have to run) with administrative privileges (this happens whenever the caller has administrative privileges). As such, there is no easy way to sandbox administration extensions. Therefore, extreme caution must be taken in installing those extensions on the server.