Getting to Know the Metabase

The IIS metabase

The IIS metabase plays a major role in your Web server's configuration. However, since Microsoft introduced the metabase in IIS 4.0, little in-depth information has been available about what goes on inside metabase.bin. In this issue, I introduce you to the IIS metabase, then explain what it stores and how to edit and customize its settings.

The metabase is a hierarchical database that stores IIS configuration values. With the introduction of the metabase, Microsoft transferred the most IIS-related settings from the registry to the metabase and added many more settings that allow greater customization. Microsoft made this change in part to let the system take advantage of features that the registry doesn't support. For example, because the metabase contains only settings related to IIS, it's physically smaller than the registry. This smaller size lets the system maintain a copy of the metabase in memory for faster access.

Another improvement is that the metabase supports a Lightweight Directory Access Protocol (LDAP) interface. LDAP is a set of standard interfaces that Active Directory Service Interfaces (ADSI) supports. ADSI uses a set of common objects and interfaces to access directories and other hierarchical data structures. Some might say that just having a standards-based interface rather than the registry access functions is a big improvement; however, the real plus is that ADSI lets you build utilities that let you access and edit the metabase remotely. But before I get into the details of editing, let's review how to protect your metabase.

Protecting Your Metabase
One of the worst things that can happen to IIS is the destruction or corruption of the metabase. Therefore, you need to know how to back up your metabase. To begin the backup process, open Internet Services Manager (ISM). Beneath Internet Information Services, right-click your computer name, then select Backup/Restore Configuration. On the Configuration Backup/Restore dialog box, which Figure 1, page 2, shows, click Create backup. Provide a short but meaningful name for your backup. When you click OK, the system will create the backup file in the system32inetsrvmetaback directory.

The second way to protect your metabase is to hide it. When you hide the metabase, you protect it from anyone who might gain unrestricted file-level access to your system. I recommend renaming your metabase something less tempting than the default metabase.bin. After all, how interesting does recipes.imb look in the my documentsrecipes directory? The IIS installation process creates metabase.bin in your system32inetsrv directory. Moving the metabase requires you to restart IIS either before renaming or after creating a copy of the metabase.

Use the registry to tell IIS the new name and location of the metabase. (Always back up the registry before making changes.) Open a registry editing tool, and add the MetadataFile (REG_SZ) value to the HKEY_LOCAL_MACHINESOFTWAREMicrosoftInetMgrParameters subkey. This value must contain the full path, including drive letter and filename, to your relocated and renamed file. Also, don't forget to remove or replace your original metabase file and move the backup copy you created.

Accessing Metabase Settings
You can use several methods to edit the metabase. Those methods include

The MMC snap-ins are application components that allow limited access to the metabase. Notice the two programming interfaces that are available. The first programming interface is the IIS Admin Base Object (IMSAdminBase), which is Active Template Library (ATL) compatible. IMSAdminBase is ideal for retrieving data from the metabase. However, because IMSAdminBase isn't an ADSI-based interface, carefully consider any decision to create a custom metabase property. (Creating custom properties is an involved process and beyond the scope of this article.) More information about the IMSAdminBase interface is available from the Microsoft Developer Network (MSDN) Online Library (http://msdn.microsoft.com/library/ default.asp?url=/library/psdk/iisref/abre6bol.htm).

The second programmatic interface is ADSI-GetObject. This interface works well for accessing most objects (keys) and values (properties) that make up the metabase. Unfortunately, the ADSI interface has limitations. For example, some entries created with the IMSAdminBase interface aren't ADSI compatible. In addition, installing Site Server or Microsoft Commerce Server 2000 adds several properties that the ADSI interface has trouble setting and retrieving.

An example of where you can use the ADSI objects is in the command-line interface to the metabase. This interface is a set of script files that exists in the inetpubadminscripts directory in Windows 2000 and in the system32inetsrvadminscripts directory in Windows NT 4.0. The most generic of these scripts is adsutil.vbs. Microsoft articles often reference this script when you need to check or modify a specific metabase setting that isn't available from ISM.

The ADSUtil.vbs script takes almost any ADSI command as its first parameter. Common commands such as Get and Set, which let you view and update specific metabase values, are complemented by commands such as Enum, which loops through the values associated with a given key. The disadvantage of this script and others, however, is that you need to understand the structure of the metabase and know exactly which properties you want to update. (For more information about the ADSI interface, see the MSDN Online Library, http://msdn.microsoft.com/library/default.asp.)

To get around this limitation and allow for a more intuitive editing environment, Microsoft introduced MetaEdit 2.1. Microsoft originally introduced this Win32 GUI application in the Microsoft Windows NT Server 4.0 Resource Kit and updated the tool in the Microsoft Windows 2000 Resource Kit. The Microsoft article "FILE: How to Download, Install, and Uninstall the IIS MetaEdit 2.1 Utility" (http://support.microsoft.com/support/kb/articles/q232/0/68.asp) provides information about the utility and the file for download. MetaEdit 2.1 is both Win2K and NT 4.0 compatible.

MetaEdit is an excellent resource on your development and staging servers. The utility provides a window into the metabase on the local machine, and you can use it to update values, modify the underlying schema, and, if you're not careful, even corrupt your metabase.

Metabase Structure
As I mentioned, the metabase is a hierarchical data structure. The metabase uses a key, or node, structure in which the top-level keys represent the local machine (LM) and schema. Beneath these top-level keys is a combination of subkeys and properties. Figure 2 shows the basic structure of some primary keys under the LM. The nodes in Figure 2 are structured based on the tree in which you see them in MetaEdit. Within each node above the line is a sample key name; below the line is the appropriate object name. Each key in the metabase is an instance of an object. The definition for each object name in Figure 2 appears in Table 1. A complete list of the metabase objects with links to their full definitions is available at http://msdn.microsoft.com/library/default.asp? url=/library/psdk/iisref/aore94th.htm.

Similar to a directory path, the path to a key starts at the LM level and concatenates the various keys until you reach the selected key. Another way to view this hierarchy is to open MetaEdit. By expanding the tree below the top-level LM key, as Figure 3 shows, you'll see that the tree structure closely resembles the diagram in Figure 2. To find the object name associated with other keys you see in MetaEdit, select the key in the left pane. In the right pane, you see the list of properties that you've set for that key. Among these properties is one called Key Type, ID 1002. This property is the name of the metabase object that defines that key.

Only those key properties that you've set appear, which is an important design attribute of the metabase. If you haven't defined a property, it doesn't mean that the metabase is corrupt. MetaEdit provides a check menu that reports on properties that are unexpected. Note that just because this check reports a problem with the structure, it doesn't mean that IIS is dissatisfied with the keys and properties. The nature of the metabase's design allows for seemingly inconsistent behavior when a property isn't required; looking at an implementation through MetaEdit won't provide an exact list of properties that is valid for every key of the same type. To find out what properties you can assign to a key based on its key type, you can either dig through the schema and find the cryptic object definition for the key in question or use the object definition from the MSDN library.

In Figure 2, notice that some keys have the same name. For example under the W3SVC key, there is a 1, just as there is under the MSFTPSVC key. I'll discuss this name duplication in more detail next month, when I show you how to use scripts to access the metabase. For now, I just want to point out that the reason you need the complete path when you attempt to access a property for a key is that key names can be duplicated. Object types can also be duplicated, as you'll see for the default.asp keys, both of which are IIsWebFile objects located under different paths in the sample Root directory.

One advantage of the hierarchical structure is that it makes the inheritance of values intuitive. Looking at Figure 2, it's easy to follow how you can set a property such as AuthFlags (ID 6000) at the Web Service (IIsWebService) level and how each Web site (IIsWebServer) can inherit that property. The inheritance can then continue to the virtual directories (IIsWebVirtualDir) under that site. However, in the same way that a key can inherit properties from a parent key, that key can override the inherited properties. If you use MetaEdit to traverse the keys, you'll see that those directories that have a type of security that differs from the site default redefine the AuthFlags property to represent the property you've assigned for that directory.

Inheritance is just one possible attribute that a property can have. Figure 4 shows the Edit Metabase Data dialog box. As you can see, several different fields make up one property. The ID field contains the property's name and its accompanying ID number, neither of which is editable. (The name isn't editable even when you create new entries.)

Below these ID fields are the five Attributes check boxes, each of which represent the properties that you can associate with this key. I've already covered the first attribute, Inherit. The second attribute, Secure, tells tools such as MetaEdit not to display the data associated with a property and, if the data is saved, to encrypt it. Use this attribute to secure passwords or other data that you want to protect, but remember that this attribute is one way. When you mark a property as secure, you can't remove that attribute. The Reference attribute indicates that the associated data is being referenced from another location in Windows. The Reference attribute is usually associated with binary data, which you shouldn't edit from the metabase. (Referenced data is commonly part of some other portion of the OS. Using the metabase to change this data would bypass business rules associated with that data and could corrupt not only the metabase but also the entire OS.) The Volatile attribute requires the metabase to keep the data it stores in this property in its in-memory copy and not write it to the file system. The final attribute, Insert Path, tells the metabase whether, when the metabase retrieves the value, to insert the metabase path of that property into the returned data. Note that the metabase path used is relative to the handle used to retrieve the property.

The User Type drop-down list box lets you define how the metabase will use the data. Table 2 lists the user types that IIS currently recognizes. For most properties, use the Server Type option. The Data Type drop-down list box lets you define the data type when you create the property definition, but you can't edit the data. Table 3 lists the data types that the metabase uses.

Finally, you associate data with the property. You can edit these data properties, but be careful: When you save the change, no quick recovery method exists. In addition, if you select a property that has the MultiSZ data type, the Edit Metabase Data dialog box changes. In addition to the Edit field, which is available for the other data types, another list box appears that lets you edit the individual strings that make up the property.

The Default Web Site Properties
Now that you've learned the details surrounding the metabase's structure, let's look at some of the properties of the Default Web Site. The IIS installation process automatically creates a Default Web Site. IIS assigns this site instance ID 1 in the metabase. IIS assigns each Web site that you create on a server an ID number that is the metabase key name for that site and part of the site's metabase path. This numbering ensures that you can modify the properties of different sites on the same server independently. For example, the path to the settings for the Default Web Site is LM/W3SVC/1. If you add a new Web site, IIS assigns the new site the next available instance ID. (On a newly installed server, the next available instance ID is 3.) After you've added the new site, you can refresh the view in MetaEdit and view the new key's configuration. In this way, IIS can uniquely identify Web sites on a server. When IIS assigns a Web site an instance ID, this ID doesn't change regardless of how you edit the site. However, if you delete the site, IIS will release that ID number. Unlike most database indexes, which don't reuse released numbers, IIS will reuse a released instance ID.

If you look at your newly created site in the metabase, you'll see that the site has a limited number of properties in its keys. For example, if you open ISM, right-click the new site, select Properties, and click the Documents tab, you'll see a list of default documents. However, neither the newly created site nor its root virtual directory has this data. The new Web site inherited this setting from the IIsWebService object, where you'll find property 6006, DefaultDoc.

Next Month
Like so many aspects of the metabase, understanding the structure and basic rules for attributes such as Inheritance makes a significant difference. Next month, I'll discuss features such as script access, some of the basic scripts that Microsoft provides with IIS, and custom-script generation.