Managing IIS Metabase Settings

The metabase is one of the most important components in an IIS installation. The metabase is where IIS stores configuration settings for sites and virtual servers. The metabase also contains default settings for sites and virtual servers, such as the global Web Sites properties.

Tip

When you work with the metabase files, it’s important to that you shouldn’t use the Encrypting File System (EFS) to encrypt them. Sensitive values in the metabase are already encrypted, and if you encrypt the metabase files themselves, you’ll unnecessarily slow down IIS.

Examining and Editing the Metabase

In IIS 6.0, IIS stores the metabase configuration in structured Extensible Markup Language (XML) files. The main configuration information is in a file that’s located in the %SystemRoot%\system32\Inetsrv directory and is named MetaBase.xml. You’ll also find a related file called MBSchema.xml, shown in Figure 15-2. MBSchema.xml is an XML Schema file, which tells IIS about the structure of the MetaBase.xml file.

Figure 15-2: MetaBase.xml is a structured XML file that can be viewed in any standard text editor.

You can examine and work with the Metabase files in any standard text editor. However, you should know several things before you do this:

• Each time IIS is started, the server reads the MBSchema.xml file and then uses this file to read and interpret the MetaBase.xml file. IIS must be able to read and store both files in memory in order for IIS to start up properly. If the read fails, IIS won’t start up.

• Although the metabase schema can be extended, you don’t want to edit the MBSchema.xml file directly. Instead, you extend the schema by creating custom properties that are stored in the MetaBase.xml file. Any mistake, though, in creating custom properties could introduce errors that prevent IIS from reading the file and starting.

• You can edit the MetaBase.xml file directly in any standard text editor. If you plan to do this while IIS is running, you must enable the metabase edit- while-running feature. In the IIS snap-in, right-click the computer node and then select Properties. In the Properties dialog box, select Enable Direct Metabase Edit and then click OK. If you don’t enable this feature, you must stop IIS before making changes to the metabase.

• Rather than directly editing MetaBase.xml, you might want to use the IIS administration scripts or Windows scripts to perform editing tasks for you. That way, you reduce the possibility that you’ll introduce errors that prevent IIS from reading the metabase file. Remember, if IIS can’t read this file, the related services won’t start.

• IIS maintains a change history for the metabase that allows you to roll back changes in some instances. To learn more about this important feature, see the section entitled “Understanding IIS Metabase History” in Chapter 16, “IIS Backup & Recovery.”

If you plan to use scripts to work with the metabase, you need to understand the metabase’s structure and know how to locate properties. Every XML element that corresponds to a metabase property has a Location property that specifies the element’s path in the metabase hierarchy. The hierarchy follows this convention:

 /LM/Service/Website 

where LM is a key that represents the local machine; Service is a placeholder that represents an Internet service, such as W3SVC or MSFTPSVC; and Website is a placeholder that represents the site or virtual server instance.

To see how metabase paths are used, consider the following example. The metabase path /LM/W3SVC/1 is the path to the Web site instance installed on the local machine with the tracking ID of 1. In the MetaBase.xml file, you could locate the entries related to this path, and they might look like this:

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

If you’re familiar with HTML or XML, you’ll know that IISWebServer is an XML element. Each property of this XML element corresponds to a specific metabase property. The value assigned to the property is the current value of the related metabase property. For example, according to the previous code sample, the metabase property ServerSize is set to 1 and the complete metabase path to this property is:

/LM/W3SVC/1/ServerSize

The hierarchy can extend downward as well. For example, the metabase path to the root directory or a Web site follows this convention:

/LM/Service/Website/Root

where LM is a key that represents the local machine; Service is a placeholder that represents an Internet service, such as W3SVC or MSFTPSVC; Website is a placeholder that represents the site or virtual server instance; and Root is the virtual directory root of the server instance.

If you examine the MetaBase.xml file, you’d find an IIsWebVirtualDir element for the root directory of the first Web server instance. The stored values might look like this:

<IIsWebVirtualDirLocation ="/LM/W3SVC/1/ROOT"    AccessFlags="AccessRead | AccessScript"    AppFriendlyName="Default Application"    AppIsolated="2"    AppPool    AppRoot="/LM/W3SVC/1/ROOT"    Path="d:\inetpub\wwwroot" > </IIsWebVirtualDir>

Here, the path to any property is the Location value plus the property name, such as:

/LM/W3SVC/1/ROOT/AppIsolated

When you work with metabase properties, the inheritance rules discussed in previous chapters still apply. Properties that you set at the Server level can apply to sites, directories within a site, and subdirectories within a directory. Similarly, child nodes could inherit properties that you set for a site or a directory. Inheritance is automatic and works just as discussed in previous chapters.

Modifying Metabase Properties

As you can probably imagine, you can set hundreds of metabase properties. The ones you’ll work with the most relate to global settings for Web servers. You’ll set these properties in the metabase location /LM/W3SVC.

Global values for the Web Service are set using the IIsWebService element in the MetaBase.xml file. The Location attribute of this element corresponds to the metabase location (/LM/W3SVC). Values for individual Web sites and virtual directories are set using the IIsWebServer and IIsWebVirtualDir elements respectively. The Location attribute of these elements is set according to the specific element’s location in the metabase hierarchy.

The properties you’ll want to work with include the following:

• AppAllowDebugging Specifies whether ASP debugging is enabled on the server. When you enable this property, only one thread of execution is allowed for each IIS application you’ve configured on the server. This allows you to debug applications individually. By default, this value is set to FALSE. Set this value to TRUE only for debugging purposes.

• AspAllowSessionState Specifies whether sessions are enabled for applications. When you enable this property, IIS tracks information for user sessions. By default, this value is set to TRUE (enabling sessions). If sessions aren’t used, however, you can achieve better performance by setting this value to FALSE and then enabling sessions within the individual applications as needed using <% @ENABLESESSIONSTATE=TRUE %>.

• AspBufferingOn Specifies whether ASP buffering is enabled. With buffering, output is collected in a buffer before it’s sent to the client. By default, this value is set to TRUE (enabling buffering). If you set this property to FALSE, output from ASP scripts is sent to the client browser as it becomes available.

• AspQueueConnectionTestTimeSets the interval used to determine if a client is still connected to the server. If a request has been in the queue longer than the test time, the server checks to see if the client is still connected before beginning execution. The default value is 3 seconds. This feature is designed to handle the problem of impatient users filling the request queue with numerous requests for the same page. ASP pages can also use the Response.IsClientConnected method to see if the client is still connected.

• AspRequestQueueMaxSpecifies the default limit for ASP requests in the connection queue. The default value is 3000. The way you set this value depends on your applications. If the average request has a very short execution time and the time in the queue is short, you might want to increase this limit (particularly if you have a very busy server).

• AspScriptEngineCacheMaxSpecifies the maximum number of scripts to cache in memory. A hit in the script engine cache means that you can avoid recompiling a template into byte code. The default value is 250.

• AspScriptFileCacheSizeSpecifies the number of precompiled script files to store in the ASP Template Cache. The default value is 500. If you set this property to –1, all script files requested are cached. If you set this property to 0, no script files are cached.

• AspSessionMaxSets the maximum number of concurrent user sessions for ASP applications. By default, the total number of connections isn’t limited.

• AspSessionTimeoutDetermines when ASP sessions time out and have to be refreshed. By default, sessions time out after 10 minutes.

• CacheISAPI Specifies whether ISAPI dynamic-link libraries (DLLs) are cached in memory after use. By default, this property is set to TRUE and ISAPI DLLs remain in the cache until the server is stopped. If the property is FALSE, DLLs are unloaded from memory after use.

• ConnectionTimeout Specifies the time in seconds that the server will wait before disconnecting an inactive connection. The default value is 120 seconds (2 minutes).

• ServerListenBackLog Sets the request queue size. The default value is based on the AcceptEx operating system parameter and on the value of the ServerSize metabase property. If ServerSize is set to 1, the default for this property is 40. If ServerSize is set to 2, the default is 100. Valid values for this property range from 5 to 500.

• ServerSize Specifies the server’s general size in terms of the number of client requests processed per day. A value of 0 indicates fewer than 10,000 requests per day, a value of 1 indicates between 10,000 and 100,000 requests per day, and a value of 2 indicates more than 100,000 requests per day.

Scripting the Metabase

Windows scripts provide another technique you can use to work with the metabase. To access metabase properties in a Windows script, you use the Active Directory Services Interface (ADSI) provider for IIS. This provider allows you to manipulate the IIS administrative objects. Key administrative objects that you’ll work with include IIsComputer, IIsWebServer, and IIsFtpServer. These objects correspond to the like-named elements in the MetaBase.xml file.

You can use the IIsComputer object to set global IIS properties and to manage metabase backups. Keep in mind that all child nodes (sites, directories, and others) can inherit global properties. The IIsComputer object is an ADSI container object that has this AdsPath:

 IIS://MachineName 

where MachineName can be any computer name or LocalHost, such as

IIS://engsvr01

In VBScript, you could get the IIsComputer object for ENGSVR01 using the following code:

'Initialize variables Dim compObject, serverName serverName = "engsvr01" 'Get IIsWebServer object Set compObject = GetObject("IIS://" & serverName)

Note

A detailed discussion of scripting the metabase is beyond the scope of this book. If you want to learn Windows scripting, a good resource is the Windows 2000 Scripting Bible (John Wiley & Sons, 2000). Once you know how to program Windows scripts, use the IIS online help documentation to get a better understanding of what objects are available and how you can use them.

You can then work with any of the IIsComputer object’s methods and properties, such as these:

'Initialize variables Dim compObject, serverNameserver Name = "engsvr01" 'Get IIsWebServer object Set compObject = GetObject("IIS://" & serverName) 'Restore metabase config from last backup 'backup is stored in the default location compObject.Restore "MyBackup", MD_BACKUP_HIGHEST_VERSION, 0

You use the IIsWebServer object to set metabase properties that apply to a specific Web site and to set inheritable properties for directories and files. Methods are also available to control server operation. For example, you can use the Stop method to stop a site and then use the Start method to start the site.

Web sites are identified according to their index number in the metabase. The first Web site instance created on the server has an index number of 1, the second has an index of 2, and so on. The IIsWebServer object is an ADSI container object that has this AdsPath:

 IIS://MachineName/W3SVC/N 

where MachineName can be any computer name or LocalHost, W3SVC identifies the Web service, and N is the site’s index number. In the following example the AdsPath string specifies the first Web site instance on the server named ENGSVR01:

IIS://engsvr01/W3SVC/1

In VBScript, you can get the IIsWebServer object for the first Web site instance using the following code:

'Initialize variables Dim webObject, serverName, webN serverName = "engsvr01" webN = "1" 'Get IIsWebServer object Set webObject = GetObject("IIS://" & serverName & "/W3SVC/" & webN) 

You can then work with any of the IIsWebServer object’s methods and properties, such as these:

'Initialize variables Dim webObject, serverName, webN serverName = "engsvr01" webN = "1" 'Get IIsWebServer object Set webObject = GetObject("IIS://" & serverName & "/W3SVC/"& webN) 'Stop Web site webObject.Stop 'Turn on ASP Buffering webObject.AspBufferingOn = True 'Save the changed value to the metabase webObject.SetInfo 'Start the Web server webObject.Start

You can use the IIsFtpServer object to set metabase properties that apply to a specific FTP server and to set inheritable metabase properties for directories. As with the IIsWebServer object, methods are also available to control server operation. You can, for example, call the Pause method to pause the FTP server and then call the Continue method to resume operation.

FTP servers are identified according to their index number in the metabase. The first server has an index number of 1, the second has an index of 2, and so on. The IIsFTPServer object is an ADSI container object that has this AdsPath:

 IIS://MachineName/MSFTPSVC/N 

where MachineName can be any computer name or LocalHost, MSFTPSVC identifies the FTP Service, and N is the server’s index number. In the following example the AdsPath string specifies the first FTP server on ENGSVR01:

IIS://engsvr01/MSFTPSVC/1

In VBScript you can get the IIsFtpServer object for the first FTP server instance using the following code:

'Initialize variables Dim ftpObj, serverName, ftpN serverName = "engsvr01" ftpN = "1" 'Get IIsFtpServer object Set ftpObj = GetObject("IIS://" & serverName & "/MSFTPSVC/" & ftpN)

You can then work with any of the IIsFtpServer object’s methods and properties, such as in the following:

'Initialize variables Dim ftpObj, serverName, ftpN serverName = "engsvr01" ftpN = "1" 'Get IIsFtpServer object Set ftpObj = GetObject("IIS://" & serverName & "/MSFTPSVC/"& ftpN) 'Stop FTP Server ftpObj.Stop 'Enable anonymous access ftpObj.AllowAnonymous = True 'Save the changed value to the metabase ftpObj.SetInfo 'Start FTP Server ftpObj.Start