Chapter 14: Working with the Metabase

This chapter examines the metabase, the main repository for IIS configuration information. I’ll begin with an overview of what the metabase is and how it works, and then analyze in detail a sample metabase from a clean install of Windows Server 2003 with IIS 6 installed. The concluding section deals with how to manage the metabase including backing up and restoring IIS configurations and exporting them to other servers.

Overview of Metabase

IIS 4 introduced a hierarchical structure called the metabase for storing IIS configuration information. As an alternative to the Registry, the metabase provides enhanced performance because it can be loaded into memory where its settings can be accessed more quickly. Let’s examine the structure and function of the metabase in IIS 6 and how it differs from previous versions.

Changes in IIS 6

The biggest change in IIS 6 is that the metabase is no longer saved in binary format as metabase.bin, but is instead formatted as a plain text file using the Extensible Markup Language (XML). This makes it possible to edit the metabase file using a text editor such as Notepad. IIS 6 also features edit-while-running, which lets you make changes manually (or programmatically using WMI or ADSI) to the metabase file without stopping IIS first. This helps you minimize downtime on your server when you need to make changes to IIS configuration using the metabase.

Note

Although the metabase files are plain text, they do not use ASCII, but instead use UTF-8, a Unicode-related character set. Notepad supports this format and can therefore be used to edit the metabase directly.

IIS 6 also includes a new metabase history feature that automatically saves backups of the metabase when changes are made to it. That way, if you goof by modifying the metabase so that IIS doesn’t work properly, you can quickly revert to a previous working version of the metabase.

Another new feature of IIS 6 is the ability to export a machine-independent version of the metabase and then import it onto a different IIS 6 machine. This allows you to copy IIS configurations from one machine to another, something that previously required third-party tools. You can also create a template metabase and copy it to multiple IIS 6 machines to deploy multiple web servers with similar configurations. Or, you can export and import only a portion of the metabase, such as a specific website or virtual directory.

IIS 6 also includes a WMI provider for IIS that lets you programmatically edit the metabase using Windows Management Instrumentation (WMI). For backward compatibility, you can modify the metabase using Active Directory Services Interface (ADSI), if you prefer.

Finally, there are about 50 metabase properties that have been removed in version 6 of IIS, and more than 100 new ones added. This is important because it may mean some ADSI scripts written to programmatically modify the IIS 5 metabase may not work with IIS 6, and all such scripts should be carefully tested before using them on the new platform. For more information on metabase properties that were added or removed in IIS 6, see the IIS Help file.

XML Metabase

XML has made significant inroads in the last couple of years as a standard for web services, especially business-to-business (B2B) communications, and it was only a matter of time before it made inroads into Microsoft Windows in general, and IIS in particular (I wouldn’t be surprised if the Registry itself was ported to XML in the next version of Windows). But why was this done for the IIS metabase?

Advantages of XML

One advantage of using industry-standard XML for the metabase instead of the previous proprietary binary format is that it allows administrators to view and modify the metabase using a simple text editor such as Notepad. But why would anyone even want to edit the metabase directly anyway? There are three reasons:

Although IIS Manager is the main tool for configuring IIS, there are some advanced metabase properties that are not accessible from the GUI and can only be viewed and modified by editing the metabase, either manually or programmatically.
In a service provider scenario where your IIS machine is hosting hundreds of websites, using IIS Manager will take forever. It can be much quicker to write a WMI script to simultaneously modify the appropriate metabase properties for multiple sites, and then use this script whenever it is needed.
If you’re administering IIS over a slow network connection such as a 56K remote access modem link, then it may be impractical to use IIS Manager due to the bandwidth required for this tool to respond adequately. Using Notepad to edit the metabase directly, however (or a WMI script to modify it programmatically), uses much less bandwidth than IIS, making it easier to configure IIS over a slow WAN link.

Because the metabase is now a plain text XML file, you can use tools like Windiff (included in the Windows Server 2003 Resource Kit) when the metabase becomes corrupted to find out what’s wrong by comparing a bad version of the metabase with a saved good version. This makes it easier to repair the metabase when it becomes corrupted. Using XML also makes it easier to edit machine-independent information from the metabase to allow it to be restored on a different computer in the case of a critical failure of your IIS machine.

Another reason XML is superior to the old proprietary binary metabase format is that XML is an extensible language. This means you can now add your own custom properties to the metabase by extending the schema. See the section “The Metabase Schema File “ later in this chapter for more information.

Finally, the new XML format helps make IIS 6 perform better than earlier versions of the platform. When IIS starts up, the XML metabase can be read and parsed faster than the old binary metabase used in IIS 4 and 5, partly because the XML metabase generally has a smaller footprint than the old binary version.

Tip

It’s a good idea for IIS admins to learn some basic XML for two reasons: to better understand the structure and format of the metabase, and to know the difference between XML that is well-formed and valid and XML that is bad. This will allow you to more easily diagnose metabase corruption arising from bad XML. A good book to reference is XML: The Complete Reference by Heather Williamson from Osborne/McGraw-Hill.

Function

The function of the metabase is to provide a place for IIS to store most of its configuration information, that is, the various settings you can configure using properties sheets in IIS Manager, plus additional settings not accessible from the GUI. Note that I said most configuration information and not all. There are still a few IIS configuration settings that are stored in the Windows Registry and not in the metabase, and these can be found under the following Registry keys:

HKLM\SOFTWARE\Microsoft\InetMgr\Parameters
HKLM\SYSTEM\CurrentControlSet\Services\InetInfo\Parameters
HKLM\SYSTEM\CurrentControlSet\Services\ASP\Parameters
HKLM\SYSTEM\CurrentControlSet\Services\Http\Parameters\LogBufferSize
HKLM\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters
HKLM\SYSTEM\CurrentControlSet\Services\MSFTPSVC\Parameters

For more information on these Registry keys and the values they can contain, see the Registry Reference in IIS Help.

Physical Structure

Let’s now dig into the structure of the metabase so you can see how it’s built and navigate your way around it when you need to change something. I’ll also show you how IIS updates the metabase internally when changes have been made using either IIS Manager, a text editor, or a script. Finally, you’ll look at how IIS maintains the metabase by automatically saving copies of it in the metabase history folder.

Metabase Files

While in previous versions of IIS there was only one metabase file, metabase.bin, in this version there are two files that together make up the metabase:

MetaBase.xml This is a plain-text file formatted in XML that contains the actual configuration information for IIS organized in a hierarchical fashion.
MBSchema.xml This is a plain-text file formatted in XML that contains the schema information for the MetaBase.xml file. The schema determines which IIS settings are stored in the metabase and enforces their data types. Administrators can also extend this schema to define custom metabase properties.

These two metabase files are stored in the \Windows\System32\Inetsrv folder with the following ACLs to control who can access or modify them:

Administrators Full Control

SYSTEM Full Control

Note

While the new edit-while-running feature of IIS 6 allows you to edit the metabase directory, this applies only to the metabase configuration file MetaBase.xml. IIS 6 does not support editing the metabase schema file MBSchema.xml while IIS is running. To modify the MBSchema.xml file, you must use ADSI or Admin Base Objects (ABO) using a C++ program.

In-Memory Metabase

There’s a third component to the metabase, and that’s the in-memory metabase, which contains the latest versions of these two files in volatile RAM. When you boot up a Windows Server 2003 machine with IIS installed, an IIS component called the Metabase Storage Layer reads the files metabase.cml and MBSchema.xml from disk and converts them from XML to binary format. The storage layer then uses Admin Base Objects (ABO), a COM object that provides low-level interfaces for programmatic access, using high- level languages like C++ or C#, to write the metabase into a portion of RAM called the IIS file cache.

For best performance, IIS then uses the in-memory version of the metabase rather than the two files on disk. For example, when you use IIS Manager to make a configuration change to IIS, this change is first written to the in-memory metabase and then periodically flushed to disk to maintain a permanent record of the changes in case a power failure causes the contents of RAM to be lost. You can also force the in-memory metabase to be persisted to disk by manually stopping IIS with IIS Manager.

Note

Just as there are two metabase files on disk, the in-memory metabase has two nodes, a configuration node corresponding to MetaBase.xml and a schema node corresponding to MBSchema.xml.

Operation

The IIS Admin service (inetinfo.exe) is responsible overall for managing metabase operations, including the Metabase Storage Layer and ABO just described. In addition, IIS Admin keeps track of any changes made to metabase files and ensures that the in- memory and on-disk versions of the metabase are periodically synchronized. Finally, IIS Admin is responsible for the operation of the metabase history feature that automatically saves backup copies of the metabase to record a history of changes to the metabase and allow administrators to revert to a previous working version of the metabase should corruption occur.

Automatic Flushing

Whenever changes are made to the in-memory metabase, typically by changing properties sheet settings with IIS Manager, these changes are not flushed immediately to disk. Instead, IIS waits 60 seconds to see if further changes will be made to the in-memory metabase. If none are forthcoming, the MetaBase.xml and MBSchema.xml files are overwritten by the contents of the in-memory metabase nodes, and a new history file pair is created with the major version number incremented by one.

If, however, more than 30 changes are made to the in-memory metabase before the 60 seconds are up, IIS postpones the overwrite for an additional 60 seconds. Such postponements can occur up to a maximum of five times until IIS finally forces flushing the modified files to disk. In other words, metabase flushing occurs a maximum of five minutes after IIS settings are changed using IIS Manager.

If edit-while-running is enabled, however, and the in-memory metabase nodes are modified programmatically using ADSI, these changes are immediately flushed to disk.

Saving to Disk

When you try to stop (or restart) IIS using IIS Manager, IIS first checks the in-memory metabase to see if any configuration changes have been made recently and not persisted to disk. If there are no changes pending, IIS stops as expected. If there are still changes pending, however, the contents of the in-memory metabase overwrite the MetaBase.xml and MBSchema.xml files on disk to ensure a permanent record of the changes, a new metabase history file is saved on disk for both the configuration and schema files, and finally, IIS stops (or restarts). Having IIS operate in this fashion allows administrators to shut down or restart IIS more quickly if no configuration changes have been recently made.

When IIS is started again (or a restart is continued), the Metabase Storage Layer reads the MetaBase.xml and MBSchema.xml files on disk, converts them to binary format, and uses ABO to write them to memory to re-create the two in-memory metabase nodes. If the metabase is corrupt, however, IIS won’t be able to start. See the section “Example of Serious Metabase Corruption” for information on how metabase corruption can arise and how you can recover from it.

History Files

History files are versioned (time-stamped) copies of the metabase that are generated automatically by IIS. These files are saved in a directory called the history folder whose default location is

\Windows\System32\Inetsrv\History

Each versioned copy consists of a pair of files, one a copy of the current MetaBase.xml node in memory and the other of the MBSchema.xml node. These files can be viewed, modified, and deleted only by members of the Administrators group.

History files are created whenever configuration changes have occurred since the last time the in-memory metabase was flushed to disk. More exactly, whenever IIS flushes the in-memory metabase to disk, overwriting the MetaBase.xml and/or MBSchema.xml files, a new history file pair is also created, incrementing the major version number of these files by one.

History File Versioning

Each history file is uniquely identified by two versioning numbers:

Major version This number is incremented by one whenever the in-memory metabase is flushed to disk. This can happen several ways:
By manually restarting IIS using IIS Manager In this situation a new history file is always created whether or not there are in-memory metabase updates waiting to be flushed to disk.
By manually stopping IIS using IIS Manager or by typing net stop iisadmin at the command prompt In this situation also, a new history file is always created whether or not there are in-memory metabase updates waiting to be flushed to disk.
By manually saving the IIS configuration to disk To do this, open IIS Manager, right-click the servername node, and select All Tasks and then Save Configuration To Disk. Note that this only creates a new history file when there are actually unsaved metabase updates in memory. For example, if you open IIS Manager and perform this operation, no history file will be created. But if you open IIS Manager, change a setting on a website or an FTP site, and then perform the operation, there are updates pending in-memory that need to be flushed to disk, so this time the operation will result in a new history file being created.
By waiting until IIS automatically flushes pending in-memory metabase updates to disk This usually happens a few minutes after you make changes to IIS property sheets.
Minor version This number increments by one if the edit-while-running metabase feature is enabled and changes have been manually made to the metabase files on disk. Also, the minor version number is reset to zero whenever the major version number increments by one, that is, whenever the MetaBase.xml and MBSchema.xml files are flushed to disk.

The naming convention IIS uses for history files employs two version numbers, as follows:

Metabase_majorversion_minorversion.xml are history files for the MetaBase.xml file.
MBSchema_majorversion_minorversion.xml are history files for the MBSchema.xml file.

Figure 14-1 shows examples of such history files within the metabase history folder. Note that both the major and minor versioning numbers in history filenames are automatically left-padded with zeros by IIS to make ten-digit versioning numbers. Note also that for every MetaBase.xml history file, there is a corresponding MBSchema.xml history file because these history files are always created in pairs, even if only one of them has changed.

click to expand
Figure 14-1: Contents of the metabase history folder

Versioning information for metabase history files is stored differently, depending on whether one refers to major or minor versioning. Major version numbers are stored within the metbase.xml file itself as the HistoryMajorVersionNumber property of the IIS_Global metabase node (I’ll explain what this means in a moment). Minor version numbers are not stored in metbase.xml but are calculated by IIS dynamically by looking at the highest current minor version number of files in the history folder.

Note

Don’t change the HistoryMajorVersionNumber of a metabase file by editing it directly or problems can result.

Configuring History Settings

The new metabase history feature of IIS 6 is enabled by default and should generally not be disabled, as this will make it more difficult to recover the metabase should corruption occur, either due to careless metabase editing or an attack on your server. If you do want to disable this feature, however, you can do so by adding the EnableHistory property to the /LM level of the metabase and setting the value of this property to 0.

Note that the EnableHistory property is not present in the metabase for a default installation of IIS. This is for performance, to keep the size of the metabase small. Specifically, if a property is not present in the metabase, IIS assumes that the property has its default value. Because the default value for the EnableHistory property is 1, this means by default the history feature is enabled. If you disable the history feature by adding the EnableHistory property to the metabase and assigning it the value 0, you have to either remove the property entirely or change its value to 1 to re-enable metabase history.

Another metabase property you can use to configure how the history feature behaves is MaxHistoryFiles, which determines how many history files for each of MetaBase.xml and MBSchema.xml are stored in the file before the oldest ones drop out. By default, this property is set to 10, which means when the eleventh history file is created, the first one is deleted. You can increase this value to save more versions of history files, but before you do this make sure you have sufficient disk space for this purpose. If your disk becomes full, IIS will not be able to create new history files and will automatically shut down until you free up disk space.

You’ll look at how to restore the metabase from history files later in this chapter in the section entitled “Restoring from History Files.”

Error Files

From time to time, you may find files within the history folder named as follows:

MetaBaseError_versionnumber.xml

Here, versionnumber is a ten-digit number starting from zero, incrementing by one each time, and left-padded with zeros, for example

MetaBaseError_0000000000.xml MetaBaseError_0000000001.xml MetaBaseError_0000000002.xml

and so on. These metabase error files are created whenever the MetaBase.xml file is edited directly using Notepad (this requires edit-while-running to be enabled) and the edit creates corruption in the file. This corruption might be a misspelled metabase property, a missing XML tag, a metabase file whose HistoryMajorVersionNumber has been changed and conflicts with the filename itself, and so on. It’s a good idea, after making changes manually to the metabase using a text editor, to see if an error file has been created, which would indicate a problem with the changes you made to the file.

Logical Structure

Now that you’ve looked at the physical structure and operation of the metabase, let’s examine its logical structure, that is, its nature as an XML document. It will help you follow this discussion if you already have some basic knowledge of XML. But I’ll try to keep things simple enough that you can follow even if you don’t know any XML.

Note

You’re going to spend a good part of the following sections learning about the logical structure of the metabase because you need to understand this subject well before you start manually editing your metabase and possibly corrupting it, causing your IIS machine to fail!

XML Terminology

Like any XML document, the Metabase.xml and MBSchema.xml files are hierarchically organized as a collection of elements defined by tags. These elements are defined by opening and closing tags, for example:

<IisComputer>stuff</IIsComputer>

where stuff may be additional elements or ordinary text (in the metabase it is always additional elements or nothing at all).

Elements can also contain additional information by defining attributes for these elements, for example:

<IisComputer Location ="/LM" EnableEditWhileRunning="0" EnableHistory="1" MaxBandwidth="4294967295" MaxHistoryFiles="10"></IIsComputer>

This element contains five attributes with string values assigned to them. To make things easier to read, additional spaces, tabs, and carriage returns can be inserted without changing the meaning of the elements. For example:

<IIsComputer     Location ="/LM"           EnableEditWhileRunning="0"           EnableHistory="1"           MaxBandwidth="4294967295"           MaxHistoryFiles="10"      > </IIsComputer>

IIS employs such a “structured text” approach to make it easier for human eyes to read and modify the metabase using a text editor.

XML elements and attributes are case-sensitive, so be sure you type lower- and uppercase letters properly when you modify the metabase.

And that’s about all you really need to know about XML to work with the XML metabase!

Metabase Terminology

Now let’s look more specifically at XML terminology as it applies to the metabase. First of all, the two metabase files must begin with a standard XML declaration indicating that the files are XML documents. This declaration is the statement:

<?xml version ="1.0"?>

Note

The XML 1.0 specification also requires a <!DOCTYPE> statement to identify the schema (if any) that is associated with an XML document. IIS metabase files do not contain this statement, however, and in this sense (and this sense only) they are not valid XML documents.

When you edit the metabase by hand, you can insert comments in the form of text separated by  tags, just as in HTML. These comments can document changes you have made so you can refer back later and understand what you did. However, insert these comments sparingly because they increase the size of the metabase—and don’t place comments above the IIS_Global node.

Another terminology issue is that XML elements (pairs of tags) in the metabase represent something called keys. An example is the IIsComputer key discussed previously, which is represented in the metabase by the <IIsComputer> and </IIsComputer> start and end tags.

The name of a metabase key is usually referred to as the KeyType property for the key. For example, the key defined by the tag pair <IIsComputer></IIsComputer> has the value "IIsComputer" for its KeyType property.

Note

Another name for KeyType is Admin Base Object (ABO) class name.

Metabase keys are analogous to Registry keys in the Windows Registry and hold metabase configuration information in the form of attributes and their values. A good analogy is to think of a metabase key as a folder that can contain name/value pairs in the form of attributes. Metabase keys can also contain other metabase keys in hierarchical fashion, with their corresponding tags properly nested and not overlapping.

Each metabase key must contain a Location attribute that indicates the location of this key in the metabase. In other words, there are two ways in which the metabase is structured hierarchically:

Elements (expressed as pairs of tags) Can be nested to create a hierarchical structure of tags.
Keys (defined by names of elements) Can be assigned a hierarchical location using Location attributes (another name for key is node).

Note that these two methods of describing the structure of the metabase do not coincide, and it’s the latter that really matters as far as the logical structure of the metabase is concerned.

Location Attributes

The true hierarchical structure of the metabase can only be understood if you grasp the meaning of Location attributes. Each metabase key contains a Location attribute that specifies where the key resides compared to other keys in the metabase. For example, in a default installation of IIS there is one website created, namely the Default Web Site. The metabase key for this website has the name IIsWebServer and is expressed in XML as the pair of tags <IIsWebServer> and </IIsWebServer>. By default, the name/value pair of the Location attribute for this key is

Location ="/LM/W3SVC/1"

This means that the IIsWebserver key is a child node of the IIsWebService key whose location is /LM/W3SVC, which is a child node of the IIsComputer key whose location is /LM, which is itself a child node of the IIsRoot key whose location is “/”. In other words, you can represent the location of the metabase node (key) for the Default Web Site within the logical structure of the metabase in the following hierarchical fashion:

IIsRoot    IIsComputer       IIsWebService          IIsWebserver

However, the corresponding elements for these keys are not organized hierarchically, but instead are organized linearly (all on the same level) as follows:

<IIsRoot> ... <\IIsRoot> ... <IIsComputer> ... <\IIsComputer> ... <IIsWebService> ... <\IIsWebService> ... <IIsWebserver> ... <\IIsWebserver> ...

Properties

The term property is essentially synonymous with “attribute” when talking about the metabase. Properties specify the actual configuration information for IIS, and there are two different types of properties found in the metabase:

In-schema Attributes that have their data types and permitted values that are enforced by the metabase schema (the MBSchema.xml file). In other words, for every unique KeyType property, there is a corresponding portion of the schema that defines what types and values of attributes are permitted for the key defined by that KeyType.
Custom Attributes that can be used to override default settings for properties defined in the schema.

Here’s an example from the metabase to illustrate the difference between these two types of properties:

<IIsComputer     Location ="/LM"           EnableEditWhileRunning="0"           EnableHistory="1"           MaxBandwidth="4294967295"           MaxHistoryFiles="10"      > </IIsComputer>

The preceding shows an in-schema metabase property with a KeyType of IIsComputer, a location of /LM, and four additional name/value attribute pairs containing general IIS configuration information about whether edit-while-running is enabled or disabled, whether the metabase history feature is enabled or disabled, and so on.

Now, here’s an example of a custom metabase property:

<IIsConfigObject     Location ="/LM/IISADMIN/EXTENSIONS/DCOMCLSIDS"      >      <Custom           Name="MD_IISADMIN_EXTENSIONS"                      Value="{61738644-F196-11D0-9953-00C04FD919C1}"           Type="MULTISZ"           UserType="IIS_MD_UT_SERVER"           Attributes="NO_ATTRIBUTES"      /> </IIsConfigObject>

Keys like the preceding that are named IIsConfigObject are special in IIS because they can contain any property and are not named using a KeyType value. Also, there can be multiple keys with the same name of IIsConfigObject within the metabase.

Because keys like IIsConfigObject can occur multiple times in the MetaBase.xml file, how are they distinguished from one another? By their Location attribute! In other words, metabase keys are uniquely defined by two things, their name (KeyType property) and location (Location attribute). While custom properties can have the same KeyType, no two properties (or keys or nodes) within the metabase can have the same Location attribute.

Another example like this is the IIsWebServer key, of which there will be more than one if you create additional websites on your IIS machine. The keys for different websites are also distinguished by their Location property, which is of the form

Location="/LM/W3SVC/siteID"

where siteID is the numerical identifier that IIS randomly generates for each site and that can be displayed by selecting the Web Sites node in IIS Manager.

Property Inheritance

A feature that helps keep the footprint (size) of the metabase to a minimum is property inheritance. This feature improves IIS performance by reducing the amount of cache memory required to hold the in-memory metabase and improving the time IIS needs to read and write configuration information to the metabase.

The way property inheritance works is simple: if a key is a child key of another key (based on the values of their Location attributes), then inheritable properties that are not explicitly set for the child key are inherited from the parent key. For example, if you use IIS Manager to configure the Web Sites node to enable HTTP Keep-Alives, then every website under this node will automatically inherit this setting. However, in the metabase, only the Web Sites node (represented by the IIsWebService property) actually has this HTTP Keep-Alives property explicitly defined in the form of the AllowKeepAlive attribute:

<IIsWebService     Location ="/LM/W3SVC"           AllowKeepAlive="TRUE"           AnonymousUserName="IUSR_ESRV220B" ... </IIswebService>

For comparison, the AllowKeepAlive attribute is not even present in the IIsWebServer property, which represents the Default Web Site node in IIS Manager:

<IIsWebServer     Location ="/LM/W3SVC/1"           AppPool           DefaultDoc="Default.htm,Default.asp,index.htm,iisstart.htm"           ServerBindings=":80:"           ServerComment="Default Web Site"           ServerSize="1"      > </IIsWebServer>

As you can see from the preceding, the IIsWebServer key has only six attributes specifying configuration information specific to the Default Web Site: the key’s location in the metabase, the application pool to which the site is assigned, the default documents for the site (included because iisstart.htm is used for this site only), the TCP port number used for communication with HTTP clients, the friendly name for the site in IIS Manager, and a ServerSize attribute that is used internally to indicate that this is a medium-sized site that is configured to handle between 10,000 and 100,000 hits per day.

By comparison, the IIsWebService property has over 100 attributes contained within it. Property inheritance thus reduces the number of attributes needed by the Default Web Site (and other websites) from over a hundred to a mere handful. Of course, as soon as you start changing the configuration settings for the Default Web Site using IIS Manager, more attributes will start to appear in the IIsWebServer property to override the default settings of the IIsWebService property.

Note

While IIS_Global is the highest-level key that can have properties (attributes) defined, no properties configured at this level can be inherited by the IIS_ROOT key beneath it. The IIS_ROOT key is the highest-level key that can have properties inherited by child keys below it.