The IIS4 Administration Objects

Last updated: 12/27/97, Initial Release

Administrating a web site can be time consuming - setting up access permissions, creating applications, defining script mappings and more - and sometimes also a frustrating experience when, for example, you would like to define different read/execute permissions for directories below a common root, which isn't possible. With Internet Information Server 3, all settings were stored in the Registry, either to be modified via the ISM (Internet Service Manager) or some settings even had to be added/changed manually in the Registry. As for web servers, the only thing you really could configure were virtual directories.

You can download IIS4 from Microsoft's web site by pointing your browser to the following location: http://www.microsoft.com/iis/. Go to the download area for IIS4.

The Metabase: IIS4's configuration store

IIS4 has changed this picture radically: you can configure nearly everything you have ever dreamed of up to the file level (yes, you can even have different settings for files in the same directory!). This magic is made possible by the new repository for configuration metadata, the Metabase. The Metabase is faster and more flexible than the Registry and stores IIS configuration parameters in a fast-access, memory-resident data store. It is a hierarchical datastore which mirrors the structure of IIS and each node in the metabase structure is called a key and has multiple configuration values associated with it (see Figure 1 for a general hierarchy).

One thing I didn't mention so far about the Metabase is that it supports inheritance. When you set inheritable configuration keys for both services outlined in Figure 1 (WebService and FtpService), these affect all servers (WebServer and FtpServer). All values set at the server level only affect the specific servers, but are still inheritable. An example would be to set Read permissions on a directory branch which promote to all sub-directories until you set specific other permissions to one of those subdirectories.

Implementation Details of the Metabase

One important thing to know is where this Metabase is stored. The secret information is that it is stored in a binary file called MetaData.bin which is located in the INETSRV directory (which by installation default is located in the SYSTEM32 directory of your Windows NT installation). The file is loaded from disk when IIS starts, stored periodically to disk and closed when the IIS service is stopped.

If you want to relocate the MetaData.bin file from the default location, then open the Registry Editor and navigate to the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\INetMgr\Parameters key. Add a new string value named MetadataFile and enter the full path to the new file (file name must be included). Please note that you first have to stop IIS service before doing so - and of course have the necessary administrative rights to do so.

How can I modify settings in the Metabase? The Metabase is implemented as two sets of API's on top of the raw data (please see Figure 2 for an overview):

• IIS Admin Base Object: This object is designed primarily for C++ programs and eliminates unnecessary overhead from the IISAO like conversions of variant data. Additionally to the improved performance, it has been developed to DCOM standards. An example of a program using this object is the ISM for IIS4 shown in Figure 3.
• IIS Admin Objects (IISAO): Can be used from any language that supports Automation which enables you to use ASP scripts to manage IIS (the HTML Administration of IIS is built upon this - Figure 4 shows a screenshot of HTMLA). These objects are also namespace providers with the Active Directory Services Interfaces (ADSI) standard, which will be discussed shortly.

Introduction to ADSI

To use other ADSI providers than IIS, you can download ADSI 1.0 by pointing your browser to the following location: http://www.microsoft.com/ntserver/info/adsi.htm. Providers supported are Novell Directory Services (NDS), Netware 3.x, LDAP and Windows NT (WinNT).

In today's distributed computing environments it is a challenge to identify and locate resources like network shares, users, print queues and more. Part of the distributed computing environment are directory services that help you to locate all of the resources mentioned - like a phone directory. When you take a look at any company, you will see that there are already many different directory services in place, like Novell Directory Services, NT Directory Services, X.500 - just to name a few.

Users, administrators, and developers face complex challenges that these multiple directories in the organization pose to them. For example end users face multiple logons and a variety of interfaces to information across multiple directories. Managing multiple directories adds extra-complexity to the administrators' tasks and developers face a dilemma - each directory offers unique application interfaces. Developers must choose a specific directory implementation, or support multiple versions of their application.

This is where ADSI comes into play: it provides a single set of directory service interfaces that can be used to manage network resources from different network providers (ODBC provides a similar "insulation layer" for database access). ADSI is divided into namespaces, and the typical namespaces are directory services for various network operating systems. You can use ADSI services to enumerate and manage resources in a directory service, independently of the network environment they are contained in.

How do you address objects in the ADSI namespace? Microsoft has made it as simple as possible for us, because it is an URL-like notion:

This address can already be used to access the root directory of the first web server in the IIS namespace (please refer to Figure 5 on the IISAO hierarchy). Before diving into using the IIS namespace, I'd like to show you how to enumerate all namespaces that are available via ADSI:

Set ns = GetObject("ADS:")
For Each obj in ns
Response.Write obj.name & "<BR>" & vbCRLF
Next

The call to GetObject returns objects contained in any ADSI namespace, which in this example is the ADS namespace of ADSI itself. The For…Each loop enumerates all namespaces available - if you haven't installed ADSI 1.0 additionally to IIS4, then only IIS will be returned as an ADSI provider.

Using the IISAO

Now that you know about the basics of ADSI, we can start exploring the IIS namespace that is provided by the IISAO objects. When you take a look at Figure 5, you will notice that the IISAO hierarchy resembles exactly the Metabase hierarchy presented in Figure 1. The items in rectangles, when combined, give a valid ADSI path to the respective IISAO object that is named next to the item.

If you are used to the ISM and it displaying long names for Web servers, you might wonder why they are numbered in the IIS namespace and where the long name is obtained from: the name displayed in ISM is taken from the ServerCommentbelow shows you how to enumerate all web property of the IIsWebServer object. The sample code servers configured on the local machine and displaying the server's name:

Set theService = GetObject("IIS://localhost/W3SVC")
For Each theServer in theService
  If (theServer.Class = "IIsWebServer") Then
     Response.Write theServer.ServerComment & " has ADsPath of " 
     Response.Write theServer.ADsPath & "<BR>"
  End If
Next

After GetObject has returned the IIsWebService object, all child objects are enumerated using a For…Each statement. Because there are not only IIsWebServer objects that are direct children of the IIsWebService object (see Figure 1), you have to check for the correct class of the object (in our case class IIsWebServer). It is always a good idea to reassure yourself that the object you are about to use is of the correct class, otherwise an error will be generated when you try to access properties that are not available for the current object. To simply enumerate all child objects, replace the ServerComment property with the Name property and remove the If check. The ADsPath property used in this example displays the ADSI path to the object that is being enumerated.

You can easily write an ASP script that traverses the entire tree for a given Web server. Listing 1 shows you how to implement this behavior using the recursive function PrintChildren to traverse the entire tree for the first Web server. Notice that every ADSI object supports the Name property.

Enumerating the hierarchy of a Web server (or parts of it) is already a nice feature, however, creating new or modifying existing parts of the hierarchy is what makes the IIS namespace really cool. A good example is how to create a new virtual directory for an existing Web server:

Set root = GetObject("IIS://localhost/W3SVC/1/Root")
Set newVDir = root.Create("IIsWebVirtualDir","ADSIExamples")
newVDir.Path = "e:\iis3\server2\ADSI"
newVDir.EnableDirBrowsing = True
newVDir.AccessScript = True
newVDir.AccessRead = False
newVDir.SetInfo

First, the root directory of the Web server is obtained. Next, using the Create method of this object, a new object of class IIsWebVirtualDir named "ADSIExamples" is created and inserted into the tree below the parent object. The following statements set the physical path, permissions to allow directory browsing and script access, as well as disabling read access to this directory. The last line's SetInfo method call stores the modified object properties, however, they are not committed immediately to minimize round trips.

You can create new Web servers, new directories, modify existing servers as well as all other objects. If you want to see which properties you can set or which methods are supported by specific objects in the IISAO hierarchy, then please refer to the section "IIS Administration" in the Programmer's Reference for Internet Information Server of the IIS Documentation.

Though I have presented only a few examples on how to use IISAO, you now should have a good understanding of the new administration features and objects that come with Internet Information Server 4. If you want to dive more into programming IISAO, I can only recommend to read the source code of the HTML Administration for IIS, which is written entirely in ASP using IISAO. Where is it located? Here is a way you will always find it:

Response.Write GetObject("IIS://localhost/W3SVC/1/Root/IISAdmin").Path