XML Metabase

All applications have to store their configuration information somewhere. Traditionally, under Windows, this has been the registry. In the case of IIS, configuration data was instead stored in a binary file called the Metabase. This file could be independently backed up, copied, and modified with the appropriate (and hard to find) tools.

IIS 6 still uses a Metabase, but instead of the hard to use and edit binary format configuration file, a text-based, XML formatted Metabase is used. This provides a number of advantages, which nearly all boil down to the same basic fact?as an XML file, we can edit and extract the elements we want in more than just the IIS manager, even using Notepad.

The same basic feature also means that we can copy configuration information between machines, making it ideal in a multi-machine configuration for sharing site parameters or for setting up Web load balancing clusters where the same parameters must be applied to all the servers supporting the sites we are balancing.

In this section, we're going to look at setting and editing parameters in the file and at how we can share information and configuration settings by extracting information from an XML Metabase and copying it elsewhere.

Structure of the Metabase

The Metabase schema (stored in MBSchema.xml) file contains a description of the expected layout, components, and properties of the main Metabase file. The Metabase itself is stored in the Metabase.xml file. Both of these files can be found in %systemroot%\System32\Inetsrv.

A copy of the Metabase is also kept in memory. The in-memory version of the Metabase is loaded by an IIS component called the Metabase Storage Layer, converting it to an internal, binary format. The Metabase is then copied into the IIS file cache for speedy access. When you use IIS manager to change the configuration, the internal configuration is changed first so that the rest of the IIS system has access to the changes. Periodically, the in-memory copy is then written to disk. If you've enabled the edit while running feature (covered in more depth later in this chapter), this period is 60 seconds?to keep the in-memory copy in sync with the disk version.

In fact, with the edit while running feature enabled, the version in memory is merged with the version on the disk, and the system constantly checks the disk version of the Metabase file to ensure that it's in sync with the in-memory copy.

Within the Metabase file itself, the structure is tree based (as you'd expect from XML), much like the Windows registry. Locations within the Metabase are specified like a directory (using forward slashes), so the root of individual Web sites configured on a server is located within /LM/W3SVC.

The Metabase root where all useful configuration information starts is actually /LM (short for local machine); within this are the main roots of the top-level configuration for IIS, such as configured extensions, Logging settings, the MIME map, and the root of the individual Web services.

Some examples of additional locations within the Metabase are listed in Table 4.1.

If you want to change a value in the Metabase, you will be given a location where you can find the property. There are a variety of ways in which you can edit the Metabase, which I cover next.

Editing the Metabase

The obvious way to edit the Metabase is through IIS manager, but we already know that provides a somewhat limited range compared to the full set of available options.

Three primary ways exist in which we can edit the Metabase and set configuration parameters?direct editing, live editing, and Metabase Explorer. Direct editing requires the use of a simple text editor?notepad will do?or you can use a dedicated XML editor. Live editing also uses a text or XML editor, with a slight twist?we can edit the contents of the Metabase while IIS is still running. Metabase Explorer, part of the IIS 6 Resource Kit, provides a more useful and friendly environment.

Direct Editing

Without making any changes from an initial installation, the only way to edit the Metabase outside of IIS Manager is to stop IIS, edit the file using a text editor, and start IIS again. You can see an example of a Metabase file, here open in Notepad, in Figure 4.1.

The only problem with direct editing is that it requires the entire IIS process to be brought down before the file can be edited and written. This means that all your sites and SMTP and FTP services will be down while you edit and update the configuration.

Live Editing

Live Editing gets rid of this limitation. Instead of waiting until the IIS service is shut down, you can just edit the XML Metabase directly? when you save it changes in the file will be reflected almost instantly in the internal memory-located Metabase, and, if the changes are to elements configurable through IIS Manager, immediately viewable and editable in IIS Manager, too.

To enable live editing?also known as the edit while running system?go into IIS Manager, right-click on the machine you want to configure and select Properties (see Figure 4.2). Then check the Enable Direct Metabase Edit check box. Click OK to accept the changes or click Apply to apply them immediately without closing the Properties box.

Once enabled, you can open the Metabase file in any editor and make changes. The result will be the same as opening it before you enabled the edit while running feature. But each time you save the Metabase, it will be merged with the in-memory version.

Metabase Explorer

Unless you are an XML junkie, editing the Metabase by hand in a text editor, such as Notepad or WordPad, is not going to be much fun. It's much better to use a dedicated tool for editing the information in the Metabase. Although you can find hundreds of different XML editors, none of them currently specialize in editing the IIS Metabase. However, the IIS Resource Kit (available from www.Microsoft.com/downloads) comes with a tool called the Metabase Explorer.

Not exactly a text editor, it does provide a nice easy way to edit and configure all the various options within the Metabase without having to manually trawl through the XML file. You can see an example of Metabase Explorer in action in Figure 4.3.

To edit a property, navigate to the appropriate area?the standard Windows directory/registry tree structure on the left navigates through the major sections, with the properties within the current level shown on the right. To edit a value, just double-click on it.

Occasionally, you need to create new values?the Metabase is not actually pre-populated with all the configurable values. If it were, the file would be huge; one thing of paramount importance in IIS 6 is performance.

To create a property, navigate to the right level, select Edit, and then New. You then need to select whether it's a new key?that is, a navigable folder within the Metabase?or a particular type of property. You need to select the property data type; you will be told which type you need if you need to create a property. For reference, the types are

• String record

• DWORD record

• Binary record

• Multistring record

• Expandable string record

Corrupt the metabase file during an edit like this, and at best you might just affect a minor part of your Web site configuration. At absolute worst, you could take your entire IIS installation down as you worry about restoring the backup copy.

Backup and Recovery

You can back up the Metabase simply by copying the Metabase and schema files to another location. If you want to incorporate the files into your backup routine, just include the %systemroot%\System32\Inetsrv directory, which will also back up a number of other useful files.

Backup copies of the Metabase and schema files are also created automatically by default when the configuration changes.

History and Versioning

IIS incorporates an automatic versioning system that provides you with a history of all the changes you have made to the Metabase. These files are created in the history folder, by default located within the %systemroot%\System32\Inetsrv\History folder. The directory stores pairs of files?a copy of each of the schema and Metabase, even if only one of the files has changed. A change is identified as a modification to the in-memory copy of the Metabase; if it identifies a difference when flushing this to disk, the files are copied to the history directory and the new versions are written out.

Naming and Version Numbers

In addition to creating the history files, IIS uses a special system to identify each version. All copies of the Metabase have the name Metabase_majorversion_minorversion.xml, with the schema using the name format MBScheme_majorversion_minorversion.xml.

The majorversion number is incremented by one when

• IIS is manually restarted using the IIS Manager

• IIS is stopped using IIS Manager or the net stop iisadmin command

• During a manual save of the IIS Configuration

• During a normal flush of the in-memory database when changes have been made

The minorversion number is incremented by one when

• The Metabase is edited while the system is running the edit while in running mode; a version of the Metabase is saved to disk

The minorversion number is always reset when a new major version is incremented.

You can see an example of the history files in Figure 4.4.

History Configuration

Two Metabase properties configure the history file settings. The /LM/EnableHistory settings enables and disables the creation of history files. By default, this setting is set to true (one) so that history files are created. If you want to disable the creation of history files?which I don't recommend?you will need to create this setting and then set the value of the property to 0.

Remember that if you disable the history system, you will lose the automatic backup system. If you have no other backup mechanisms, there might be no other way of recovering from a fault.

You can also configure the number of history files that are kept. By default, only the last 10 copies of the history files are kept?the oldest one is removed each time, so it's always the most recent 10 files.

You can increase or decrease the number of files by editing the /LM/MaxHistoryFiles property. Remember that for even a relatively bare configuration with only a few sites in it, each Metabase file and schema pair will take up about 300KB. With a hundred or so sites, you could easily be looking at 1MB each time. Obviously in these days of multi-gigabyte hard disks, this seems like a fairly low risk situation, but keep it in mind.

Error Files

If you make a change to the Metabase that results in a corrupted file, incorrect Metabase structure, or a truncated entry, you will get a file within the history folder of the form MetabaseError_versionnumber.xml.

Importing/Exporting the Metabase

The command-line script iiscnfg.vbs is a general-purpose script that allows you to save, copy, import, and export information from the Metabase.

Saving Configurations

At its simplest level, the /save command-line option will save a copy of the in-memory Metabase to disk, providing that the configuration has changed.

You can also execute the command from a remote machine using the /s command-line switch?for example, to save the configuration of the machine with the IP address 192.168.1.130

iiscnfg /save /s 192.168.1.130

It will use your existing credentials to authorize the save, or you can supply your own using the /u and /p for user and password information. For example, if we needed to supply the administrator information

iiscnfg /save /s 192.168.1.130 /u CORP\Administrator /p Password

The more useful components of this script are with the export and import tool.

Exporting Configurations

You can directly export configuration information from the Metabase using the iiscnfg script, but you have to specify which part of the Metabase you want to export. For example, if you want to export the individual Web site configurations, you would use

iiscnfg /export /f export.xml /sp /lm/w3svc /inherited /children

A few extras need to be mentioned:

• /f? Specifies the name of the file to which the information will be exported.

• /sp? Specifies the topmost node from the metabase to be exported. In this case, we're exporting everything below /LM/W3SVC.

• /inherited? Tells the script to export everything from the file under that node, including specific elements inherited from further up the file.

• /children? Specifies that all children of this node should be exported to the file.

Importing Configurations

You can also import the information back again. The big benefit here is that you can use it to duplicate Web site definitions, both across the same machine and across different machines.

For example, given the information we've exported previously, we could import that onto another machine to duplicate the site definitions. To do this, we basically run the process in reverse:

iiscnfg /import /f export.xml /sp /lm/w3svc /dp /lm/w3svc /inherited /children

The /sp specifies where within the source file the script should start importing information, and the /dp specifies where within the current Metabase the information should be imported to. In this case, we've loaded the Web site configuration data into the Web site definition section.

However, a few problems exist that you need to be aware of before blindly copying information between machines in the Metabase file:

• Change or remove references to the current machine within the metabase file because these might affect the machine you are copying the details to.

• Change or create the necessary folders on the destination machine.

• Change any system paths, such as the root folder for IIS Web sites or the folders used to store metabase history files, for example.

• Delete or modify properties relating the IUSR or IWAM accounts, which are unique for each machine.

• Delete any AdminACL properties, which are machine specific and cannot be modified by hand.

• Delete any properties specifying or containing passwords.

If you are copying between machines that will all be part of the same cluster and you are setting them up for the first time, you shouldn't have to worry about the folder or file system paths.

Copying Configurations

Previous versions of IIS provided the IISSync.vbs and IISRepl.vbs scripts, which enabled you to exchange configuration information between servers. We can use the iiscnfg.vbs script to do the same; the only difference is that it's exchanging XML Metabase content.

Unlike the export/import process detailed previously, using the copy command automatically removes all the machine-specific entries that would otherwise cause problems.

If you need to copy information, another alternative is to use the IIS Migration Tool, which is part of the IIS Resource Kit and can migrate IIS 6 sites between machines.