Internet Information Server

Overview

Internet Information Server (IIS) version 4.0 and later expose configuration information and operations through an ADSI interface.

Using this interface you can perform all of the administrative tasks that are normally accessed through the IIS MMC application, such as the creation and manipulation of Web, FTP, NNTP, and SMTP sites.

This can save time. For example, in a load-balanced environment, all the servers in a Web "farm" must contain identical configurations, or in an ISP environment, a single IIS server may host dozens or even hundreds of individual sites.

IIS configuration information is stored in a metabase that has a structure similar to the registry. The metabase is accessible through ADSI using the IIS namespace interface. The IIS namespace exposes objects in a hierarchical fashion.

The IIS ADSI provider is installed with IIS version 4.0 and later. A remote server can be accessed if and only if both computers have IIS installed. When you reference IIS objects, the path to the object must be prefixed with IIS. This indicates that the object resides in the IIS namespace and requires the IIS ADSI provider.

The top-level object in the IIS hierarchy represents the computer on which an IIS server resides. All IIS object paths must start with the name of the computer:

'get a reference to the IIS server on computer Odin
 Set objComputer = GetObject("IIS://Odin")

Once a reference has been made to the IIS computer, you can enumerate and manipulate any IIS resource that resides on that computer.

This chapter demonstrates how to perform IIS backup-related operations, resource enumeration, Web and FTP site creation, virtual directory manipulation, individual file and directory manipulation, and IP address assignment.

Most of the more complex command-line scripts in this chapter use the adsilib.vbs support include file listed in Chapter 14.

Note

For more information, read "Programming IIS 4.0 with ADSI" (http://15seconds.com/issue/980304.htm) and "An Introduction to the IIS Metabase" (http://msdn.microsoft.com/library/en-us/iisref/html/psdk/asp/aint1aud.asp).

Backing Up and Restoring IIS Configuration Information

Problem

You want to back up and restore IIS configuration information.

Solution

You can reference the required IIS server using the IIS provider and then call the Backup or Restore method. The following script creates a backup called "Weekly Backup of the Metabase" for server Odin:

'weeklybackup.vbs
Const MD_BACKUP_NEXT_VERSION = &HFFFFFFFF
Const MD_BACKUP_FORCE_BACKUP = 4
Const MD_BACKUP_SAVE_FIRST = 2

Set objComputer = GetObject("IIS://odin")
'create a new backup. Assign the next available version number
objComputer.Backup "Weekly backup", MD_BACKUP_NEXT_VERSION _
 , MD_BACKUP_FORCE_BACKUP Or MD_BACKUP_SAVE_FIRST

Discussion

As with computer systems in general, it is important to back up IIS configuration information to ensure recovery in case of system failure. Incomplete creation of IIS objects and invalid property settings through code can cause problems in the operation of the IIS server, and in some cases they can disable access to the site through the MMC administrative interface.

For example, a Web site requires that a corresponding virtual root directory be created. If the root directory is not created or the Web site is not properly identified, it will not appear in the MMC administration console and cause error messages to appear.

To perform backup operations, first get a reference to the IIS computer you want to back up or restore:

'get a reference to the IIS server
 Set objComputer = GetObject("IIS://strServer")

The strServer part of the path represents the name of the IIS computer. The IIS ADSI provider is installed on machines with IIS server installed.

Once a reference to the computer is retrieved, you can perform backup operations. To back up server configuration, invoke the Backup method:

objComputer.Backup strName, nVersion, nFlag

strName is the name of the backup. It can be up to 100 characters and contain spaces.

You can store multiple versions of a backup with the same name. The nVersion parameter identifies the version number. It can be any number between 0 and 9,999. Alternatively, you can pass one of the values listed in Table 15-1 to find the next version number automatically or replace the current version of the backup, which is specified by the strName parameter.

Table 15-1: Backup Version Options
NAME	VALUE	DESCRIPTION
MD_BACKUP_HIGHEST_VERSION	&HFFFFFFFE	Replace the current highest backup version for the specified backup
MD_BACKUP_NEXT_VERSION	&HFFFFFFFF	Find the next available backup version for the corresponding backup

The nFlag parameter can be a combination of the backup values in Table 15-2.

Table 15-2: Backup Values
PROPERTY	VALUE	DESCRIPTION
MD_BACKUP_OVERWRITE	1	Perform backup overwriting any existing versions with the same name and version number
MD_BACKUP_SAVE_FIRST	2	Save metabase data before performing backup
MD_BACKUP_FORCE_BACKUP	4	Force backup even if saving of configuration was not successful

To restore a backup, invoke the Restore method:

objComputer.Restore strName, nVersion, nFlag

The strName parameter is the name of the backup to restore. nVersion is the version to restore. If you want to restore the latest version of the backup, pass the MD_BACKUP_HIGHEST_VERSION value, which will restore the highest version of the specified backup. The nFlag parameter is not used and must be 0.

objComputer.Restore "MyBackups", MD_BACKUP_HIGHEST_VERSION, 0

To delete a backup, invoke the Delete method:

objComputer.DeleteBackup strName, nVersion

The strName parameter is the name of the backup to delete, while nVersion is the version to delete. If you want to restore the latest version of the backup, pass the MD_BACKUP_HIGHEST_VERSION value.

The following script, iisbackup.wsf, provides a generic command-line utility that creates, restores, and deletes backups from a specified IIS computer:

The iisbackup script lists sites of a specified type for a given IIS server:

iisbackup.wsf computer /d | /b | /l | /r [name] [version]

Computer is the computer where IIS resides. This is followed by one of the following switches, which represent the operation you want to perform: /d to delete a backup, /b to perform a backup, /l to list an existing backup, or /r to restore a backup.

If you create, delete, or restore a backup, you must specify a name for the backup. You specify an optional version number for any of these operations. If you omit the version number, the backup option creates a new backup with the next available number while the restore or delete operations affect the backup with the highest version number.

Listing Web Sites

Problem

You want to enumerate individual Web sites on a given IIS computer.

Solution

Reference the IIS Web service object for the computer and then list each site in the service:

'list all Web sites on the Thor Web server
Dim objWebService, objWebSite
WebSet objWebService = GetObject("IIS://Thor/W3SVC")
'loop through each site, find available site #
For Each objWebSite In objWebService
 'check if the object is a Web site
 If objWebSite.Class = "IIsWebServer" Then
 Wscript.Echo objWebSite.Name, objWebSite.ServerComment
 End If
Next

Discussion

The IIS computer object exposes IIS services that are installed on the server. These include news (NNTP), mail (SMTP), FTP, and Web servers.

To get a reference to a service, use the following:

Set objService = IIS://ComputerName/Servicename

ComputerName represents the name of the IIS server and Servicename identifies the service. Table 15-3 lists the IIS service names.

Table 15-3: IIS Service Names
SERVICE NAME	DESCRIPTION
W3SVC	Web service
MSFTPSVC	FTP service
SmtpSvc	SMTP mail service
NNTPSVC	NNTP news service

The following code snippet gets a reference to the Web service on computer Odin:

'get a reference to the Web service on server Odin
Set objService = "IIS://odin/W3SVC"

IIS allows the hosting of multiple sites for each service. The sites are identified with a site name, which is represented internally by a number. If you create a site using the Microsoft Management Console (MMC), you see a "friendly" server comment name assigned to the site in MMC, while internally the site is assigned a number. Sites cannot be programmatically referenced using the server comment.

The default Web site installed with IIS is identified as site 1. The site object's Name property returns the number associated with the site, and the ServerComment property returns the descriptive name assigned to the site, which is what appears in the IIS MMC.

The Active Directory Browser that is included with the ADSI SDK can browse each IIS server metabase. The Metabase Editor displays the details of the IIS objects, as shown in Figure 15-1. Site Server 3.0 includes the Metabase Editor and IIS Resource Kit, although you'll need IIS 4.0 (minimum) to use them.

click to expand
Figure 15-1: The Metabase Editor

Note

A recent version of the Metabase Editor is available on the Web at http://support.microsoft.com/support/kb/articles/q232/0/68.asp.

The following command-line script, listsites.wsf, lists the sites for a specified service on an IIS computer:

The syntax for the listsites.wsf script is as follows:

listsites.wsf computer type

Computer is the server where IIS resides and type is the site type (Web, FTP, SMTP, or NNTP).

For example, to list all FTP sites on the IIS server odin, use this:

listsites.wsf odin FTP

Creating a Site

Problem

You want to create an IIS Web or FTP site.

Solution

To create a Web site, you can reference the Web service (W3SVC) for the IIS server on which you want to create the site. Then call the Create method, specifying the IIsWebServer class. To make a Web site functional, you must create a root virtual directory and create it as a Web application:

Const MediumProtection = 2
Dim objService, objWebSite, objVirtDir
'get a reference to the Web service on server Odin
Set objService = GetObject("IIS://odin/W3SVC")
'create a new Web site and assign it the value of 5 as its 'name'
Set objWebSite = objService.create("IIsWebServer", 5)
'assign a friendly comment to appear in the IIS MMC
objWebSite.ServerComment = "New Web site"
objWebSite.SetInfo

'bind the site to an IP address and distinguished name
objWebSite.ServerBindings = Array("192.168.1.40:80:accounting.acme.com")
objWebSite.SetInfo
'create a virtual ROOT directory for the site
Set objVirtDir = objWebSite.create("IIsWebVirtualDir", "ROOT")
objVirtDir.Accessread = True
objVirtDir.Path = "f:inetpub
ewsite" 'set the Web directory
objVirtDir.SetInfo

'create an application for the ROOT directory
objVirtDir.AppCreate MediumProtection
objVirtDir.AppFriendlyName = "Default Application"
objVirtDir.SetInfo

To create an FTP site, get a reference to either the FTP service (MSFTPSVC) or the IIS server on which you want to create the site. Then call the Create method, specifying the IIsFTPVirtualDir class:

Dim objService, objFTPSite, objVirtDir
'get a reference to the FTP service on server Thor
Set objService = GetObject("IIS://thor/MSFTPSVC")

'create a new FTP site and assign it the value of 6 as its 'name'
Set objFTPSite = objService.create("IIsFTPServer", 6)
'assign a friendly comment to appear in the IIS MMC
objFTPSite.ServerComment = "Accounting FTP Site"

'bind the site to an IP address and distinguished name
objFTPSite.ServerBindings = Array("192.168.1.40:21:ftp.accounting.acme.com")
objFTPSite.SetInfo

'create a virtual ROOT directory for the site
Set objVirtDir = objFTPSite.create("IIsFTPVirtualDir", "ROOT")
objVirtDir.Accessread = True
objVirtDir.Path = "f:inetpubftp" 'set the FTP directory
objVirtDir.SetInfo

Discussion

IIS version 4.0 and later provide the ability to host multiple sites on a single computer. Each site can be accessed through a different URL. To create a Web site, get a reference to the particular service container (Web, FTP, or SMTP) for the server you want to create the site on:

Set objService = GetObject("IIS://server/service")

To get a reference to the Web service on server odin, use this:

Set objWebService = GetObject("IIS://odin/W3SVC")

To create the site, invoke the Create method on the service container object, specifying the object you want to create:

Set objSite = objWebService.Create(strObjectClass, nName)

strObjectClass is the site object type you want to create. Table 15-4 lists the available site object classes.

Table 15-4: IIS Site Object Classes
OBJECT CLASS	DESCRIPTION
WebIIsWebServer	Web server
IIsFTPServer	FTP server
IIsNNTPServer	News server
IIsSMTPServer	SMTP mail server

The site name specified by the nName parameter is not the name used to identify the site when accessing it via a browser, nor is it visible in the IIS MMC management interface. The site name is a whole, positive numeric value. You must manually determine a name that has not already been used.

To simplify the process of determining a name, use the FindNextSite function, which is defined in the adsilib.vbs support file listed in Chapter 14:

FindNextSite(objService)

objService is an instance of an object for the service type you want to find the next site for, such as a Web or FTP service.

'get the next available site number for the FTP service:
Set objWebService = GetObject("IIS://Thor/MSFTPSVC")
Wscript.Echo FindNextSite(objWebService)

The following snippet of code creates a Web site with an internal ID of 5:

Set objWebSite = objWebService.Create("IIsWebServer", 5)

The new site requires that a server comment be assigned to it in order to appear in the IIS MMC application. The comment is set using the site object's ServerComment property:

objWebSite.ServerComment = "New Web site"
objWebSite.SetInfo

The site must be bound to at least one or more addresses. The address is in the format address:port:domainname.

The address is the IP address that is associated with the site. The port is the port number for the service. For a Web service, the default port is 80, and for an FTP service, the port is 21. The port number can be changed from the default port.

The domainname is an optional name that identifies the particular site. It is used if you want to host more than one site on a machine with a single IP address. The ServerBindings property stores the addresses and ports that are bound to the site:

objWebSite.ServerBindings = Array("10.0.0.1:80:accounting.acme.com")

Note

See Solution 15.9 for more details on setting server bindings.

Once a site has been created, add a root directory to it. This is required for Web and FTP sites. The root folder provides entry-level access to the site and points to the first folder that appears in the site.

To create a root directory, invoke the Create method on the site container where the root will appear:

Set objVirtDir = objSite.Create(strVirtDirClass, "ROOT")

strVirtDirClass is the virtual directory class name. For a Web site, this is WebIIsWebVirtualDir, while for FTP this is IIsFTPVirtualDir.

To create a virtual root directory on a Web site, use this:

Set objVirtDir = objWebSite.Create("IIsWebVirtualDir", "ROOT")

A directory path must be set for the virtual directory. This path points to an existing server directory and is set using the Path property.

objVirtDir.Path = "d:inetpubwwwrootintranet"

The root directory is also an IIS Web application:

objVirtDir.AppCreate False
objVirtDir.AppFriendlyName = "Default Application"
objVirtDir.AppIsolated = 2
 objVirtDir.SetInfo

Note

See Solution 15.8 for more details on creating Web applications.

The following command-line script, createsite.wsf, creates a new FTP or Web site for a specified IIS server:

The createsite.wsf script is a command-line script that creates a new FTP or Web site. The syntax is as follows:

createsite.wsf computer type description connection path

Computer is the computer the IIS server resides on. Type is either FTP or Web. Description is the site's friendly name. Connection is the binding string and path is the local directory path to the site.

To create a Web site called "Accounting Site" bound to the IP address 10.0.0.1 on port 80 with a DNS address accounting.acme.com that is stored under the directory d:Webacct, execute the following command line:

createsite Odin Web "Accounting Site" 10.0.0.1:80:accounting.acme.com d:Webacct

To create a FTP site called "FTP Site" bound to the IP address 10.0.0.1 on port 21 with a DNS address ftp.accounting.acme.com that is stored under the directory d:\ftpacct, execute the following command line:

createsite Odin Web "FTP Site" 10.0.0.1:21:ftp.accounting.acme.com d:ftpacct

The createsite script works on IIS 4.0 and later. The default site protection that it assigns is High.

Starting an IIS Site

Problem

You want to start an IIS site.

Solution

You can bind to the site (FTP, Web, or SMTP) that you want to start and then invoke the Start method:

Web'get the Web service for Web site 1 for server ODIN
 Set objWebSite = GetObject("IIS://odin/W3SVC/1")
objWebSite.Start

Discussion

Each IIS site can be started, paused, or stopped using the Start, Stop, or Pause methods, respectively.

The state of a site can be determined by the ServerState property. It returns a numeric value that identifies the state. Table 15-5 lists values that are returned by the ServerState property.

Table 15-5: *ServerState* Property Values
STATE VALUE	DESCRIPTION
1	Site starting
2	Site started
3	Site stopping
4	Site stopped
5	Site pausing
6	Site paused
7	Site continuing

To continue a paused site, use the Continue method.

Deleting a Site

Problem

You want to delete a site.

Solution

Bind to the service (FTP, Web, or SMTP) object for the site you want to delete. Call the Delete method, specifying the appropriate class and name of the site you want to remove:

Web'get the Web service from specified computer
Set objWebService = GetObject("IIS://odin/W3SVC")
'delete the Web server named 3
objWebService.delete "IIsWebServer", 3

Discussion

To delete an IIS object, reference the container object that holds the site you want to delete. Then invoke the Delete method:

objWebService.delete strClass, objectname

strClass represents the object class you want to delete, while objectname represents the name of the object you want to delete. For IIS site objects, the name is represented as a number. You cannot specify the "friendly" name of the site as the site you want to delete.

To simplify the process of determining a name, use the FindNextSite function, which is defined in the adsilib.vbs support file that is listed in Chapter 14:

FindSiteNumber(objWebService, strSiteName, strType)

objService is an instance of an object for the service type you want to find the next site for, such as Web or FTP service, strSiteName is the friendly site name that appears in the IIS MMC, and strType is the site type, which can be Web, FTP, SMTP, or NNTP.

The function returns an empty string if the specified site is not found.

Deleting a site does not delete the contents of the site—it only deletes site configuration information stored in the IIS metabase.

Creating Virtual Web Directories

Problem

You want to create and maintain virtual directories for your Web sites.

Solution

Bind to the parent directory container object where you want to create the virtual directory. Call the Create method, specifying IIsWebVirtualDir as the class to create and the name of the directory:

'get a reference to the root of the first Web site
Set objContainer = GetObject("IIS://odin/W3SVC/1/Root")
'create a virtual directory called AcctDir
Set objVirtDir = objContainer.Create("IIsWebVirtualDir", "AcctDir")
'set the virtual directory to point to a local folder
objVirtDir.Path = "d:datasitesintranet"
objVirtDir.SetInfo

Discussion

A virtual directory is a directory in a Web site that appears to be a physical directory but is actually a link to a separate location. The location may be a directory on the local server, a remote network connection, or a URL to a separate site. By providing a link to a separate location, information can be referenced on a Web site that does not physically reside in the Web site directory structure.

To create a virtual directory, get a reference to the parent directory for the directory you want to create. Then invoke the Create method with the name of the directory and virtual directory object class name. For Web sites the object class is WebIisWebVirtualDir, and for FTP sites it is IIsFTPVirtualDir:

'get a reference to the root of the first Web site
Set objContainer = GetObject("IIS://odin/W3SVC/1/Root")
'create a virtual directory called AcctDir
Set objVirtDir = objContainer.Create("IIsWebVirtualDir", "AcctDir")

The virtual directory requires a location to provide the information. This can be a physical path or a network share, or the location can be redirected to a different Web path.

To set a directory path, set the Path property to a valid directory path:

'set the virtual directory to point to a local folder
objVirtDir.Path = "d:datasitesintranet"

To reference a remote share, set the path property to a valid UNC path. You can associate a user name and password to the share name by setting the UNCUserName and UNCPassword properties:

'set the virtual directory to point to a local folder
objVirtDir.Path = "\odinacctsite"
objVirtDir.UNCUserName = "Webaccess"
objVirtDir.UNCPassword = "xy34ab32"

If you want to specify a domain user for the UNCUserName property, prefix the user name with the domain name separated by a backslash ().

Note that the password properties are not encrypted. If you intend to use it, create a user ID with the minimum access rights.

The virtual directory can also be redirected to a different Web page. To redirect a virtual directory, set the HttpRedirect property to a valid URL. Access to the redirected page is controlled by the site hosting the URL.

'set the virtual directory to point different Web site
objVirtDir.HttpRedirect = "www.accounting.acme.com "

Once the location of the virtual directory is set, invoke the SetInfo method on the virtual directory object to update the settings.

Setting File and Directory Properties

Problem

You want to set a property for a file or directory.

Solution

Get a reference to the object you want to set a property for. The SetInfo method must be called to store any property changes:

'get a reference to the file data.txt in Root directory of site 3 on Thor
Set objFile = GetObject("IIS://thor/W3SVC/3/Root/data.txt")
objFile.AccessWrite = False
objFile.SetInfo

Discussion

IIS allows you to change the properties of individual files and directories, enabling you to configure individual objects within a site differently than the default settings inherited from the root object.

There can be problems binding to directory or file objects. The IIS metabase is structured to inherit all base properties from root objects. For example, by default all files and directories in a new Web site contain the same properties as the root folder.

Instead of storing configuration information for all objects in a site in the metabase, only objects that have properties different than those inherited from root objects are stored.

As a result, any given file or directory in the hierarchy will inherit the settings from its root object. This means most files and directories will not be stored in the metabase, even if they physically exist on the site.

One easy way to see this is to use the Metabase Editor (see Solution 15.2) to view the IIS metabase. Initially, it appears that the metabase mirrors most of the items that appear in the IIS MMC application, but any directory or file that does not have different properties than the root objects will not appear.

So even though all file and directories appear in the IIS MMC, they are not necessarily stored in the metabase. When you make a change to an object in MMC, an item is created for it in the metabase (if it doesn't already exist).

However, if you attempt to access an object programmatically that doesn't exist in the metabase, an error will occur. Before you can modify properties on any object that doesn't exist in the metabase, you must create it first in the metabase, even if it already physically exists in the Web site and appears in the IIS MMC application.

There is no ADSI method to check if a directory or file exists in the metabase. One way to check is to use error handling to determine if the object exists:

On Error Resume Next
'get a reference to the file data.txt in Root directory of site 3 on Thor
Set objFile = GetObject("IIS://thor/W3SVC/3/Root/data.txt")
'check to see if error occurred, object does not exist:
If Err Then Wscript.Echo "Object does not exist in Metabase"

To add a Web or directory object to the metabase, bind to the parent container the object will exist in. Invoke the Create method, specifying the object class and name of the object you are creating. The object class for a Web directory is WebIIsWebDirectory and for a Web file it is WebIIsWebFile.

To create a metabase entry for the default.htm file under the Web root directory for Web site number 3, use this:

'get a reference to the Root directory container for Website 3
Set objIIS = GetObject("IIS://thor/W3SVC/3/Root")
'create an IIsWebFile entry for default.htm
Set objWebFileDir = objIIS.create("IIsWebFile", "default.htm")

The following function checks for the existence of the object and attempts to add it to the metabase if it doesn't exist:

'Description
'Returns specified file or directory object
'Parameters
'strPath File name to search for
'objIISPath IIS object container to retrieve object from
Function GetFileDir(strPath, objIISPath)
Dim strObjectClass, objWebFileDir, objFSO

On Error Resume Next
'attempt to get the object from specified container
Set objWebFileDir = objIISPath.GetObject(strObjectClass, strPath)

'check if error occured - could not get object
If Err Then
 Set objFSO = CreateObject("Scripting.FileSystemObject")
 'check if specified path is a file..
 If objFSO.FileExists(objIISPath.Path & "" & strPath) Then
 'create the file object
 Set objWebFileDir = objIISPath.create("IIsWebFile", strPath)
 'check if specified path is a directory..
 ElseIf objFSO.FolderExists(objIISPath.Path & "" & strPath) Then
 'create the directory object
 Set objWebFileDir = objIISPath.create("IIsWebDirectory", strPath)
 Else
 Set objWebFileDir = Nothing
 End If
End If

Set GetFileDir = objWebFileDir
End Function

When a file or directory object is added to the metabase, no checks are made to see if the file or directory actually physically exists. If the file or directory that is added doesn't exist, no error will occur. The entry will be added to the metabase, but a physical counterpart will not be created. This doesn't show up in the IIS MMC application or affect the server, but it is not good practice to have unused objects floating around.

The GetFileDir routine checks for the existence of a specified file or directory object. If an error occurs, it doesn't exist in the metabase and it attempts to create it, but first checks to determine if the file or directory actually exists. If the file or directory does exist, a new entry is created in the metabase; otherwise, the function returns Nothing.

Set objIIS = GetObject("IIS://Thor/W3SVC/1/Root")
Set objWebFile = GetFileDir("default.txt", objIIS)

Once you have a reference to the Web file object, you can manipulate its properties. All of the properties listed in Table 15-6 can be applied to Web and virtual directories, unless otherwise specified. A number of the properties apply to file objects—this is indicated by an X in the File column. All the properties for each of the following categories are not listed.

Table 15-6: File- and Directory-Related Properties
PROPERTY	DESCRIPTION	FILE
DontLog	Boolean. If True, don't log any access to directory.
EnableDirBrowsing	Boolean. If True, browsers can browse the contents of the directory.
EnableDefaultDoc	Boolean. Enables the default document for the directory if set to True.
AccessRead	Boolean. Provides read access to a folder.	X
AccessWrite	Boolean. Provides write access to a folder.	X
AccessExecute	Boolean. Determines if files can be executed in the folder.	X
AccessScript	Boolean. If True, ASP script files can be executed.	X
ContentIndexed	Boolean. If True, IIS Index server indexes the contents of the folder.

The properties listed in Table 15-6 apply to values on the Directory tab that appears in the Directory Properties dialog box under IIS, as shown in Figure 15-2.

click to expand
Figure 15-2: Directory tab

Web and virtual directories can control if default documents are assigned. Table 15-7 lists properties that are related to the Documents tab shown in Figure 15-3.

Table 15-7: Document Properties
PROPERTY	DESCRIPTION
EnableDefaultDoc	Boolean. Enables the default document for the directory if set to True.
DefaultDoc	Comma-delimited string identifying the default document names (e.g., Default.htm, Default.asp, and iisstart.asp). The EnableDefaultDoc property must be set to True to enable the documents.
EnableDocFooter	Boolean. Enables the document footer if set to True.
DefaultDocFooter	Path to HTML file containing document footer appended to the bottom of each document in the specified directory. The EnableDefaultDoc property must be set to True to enable the document footer.

click to expand
Figure 15-3: Documents tab

All Web objects can have security settings applied to them. This provides very flexible security mechanisms and allows different levels of security to be applied.

Table 15-8 and Table 15-9 list properties that are related to the Authentication Methods dialog box shown in Figure 15-4.

Table 15-8: Anonymous Access Security Properties
PROPERTY	DESCRIPTION
AnonymousUserName	NT anonymous user account.
AnonymousUserPass	NT anonymous account password. This password is unencrypted and can be read as plain text, so create an account with minimal access.
AnonymousPasswordSync	Boolean. Determines if the anonymous user password specified by the AnonymousUserPass property is synchronized with the NT anonymous account specified by the AnonymousUserName property.
AuthAnonymous	Boolean. If set to True, IIS will allow anonymous authentication.

Table 15-9: Basic Authentication Properties
PROPERTY	DESCRIPTION
DefaultLogonDomain	Default NT domain to authenticate clear-text user ID and passwords against.
AuthBasic	Boolean. If set to True, Basic authentication is enabled.

click to expand
Figure 15-4: Authentication Methods dialog box

To configure Anonymous access, set the properties listed in Table 15-8.

To configure basic (clear text) authentication, set the properties listed in Table 15-9.

To configure Windows NT Challenge/Response authentication, set the AuthNTLM property to True.

You use the IPSecurity property to grant and deny access by IP address. (See Solution 15.9 for more information.)

The properties detailed in this section are some of the most used properties that can be applied to file and directory objects, but there are many more properties available to set.

One way to determine what properties map to what values in MMC is to set properties for a "dummy" object using MMC and enumerate the properties for the object. The listprop command-line utility (see Solution 14.5) lists all properties and associated values for any ADSI object:

listprop IIS://odin/W3SVC/1/Root/AppDir

Creating a Web Directory Application

Problem

You want to create a Web directory application.

Solution

You can reference the Web directory that you want to create as a Web application and then call the AppCreate method:

Const MediumProtection = 2
'get a reference to the directory NewApp under the root directory of the first site
Set objNewApp = GetObject("IIS://thor/W3SVC/1/Root/NewApp")
'create a new application for the directory
objNewApp.AppCreate True
objNewApp.AppFriendlyName = "Default Application"
objNewApp.AppIsolated = MediumProtection
objNewApp.SetInfo

Discussion

IIS allows different levels of "protection" to be applied to Web applications. This protection determines how Web application processes are organized in memory.

The lowest level of protection is called in-process. In-process applications run in the same memory space as the Web server itself. The advantage of running your Web site in-process is better performance, and the disadvantage is potential stability problems. If a part of a Web application (such as a DLL) performs an invalid operation, it can affect the operation of the whole Web server. If your Web site is only serving static Web pages and not performing any CGI or ASP operations, in-process can be suitable.

An out-of-process application is the highest level of protection that isolates the application's process from other applications. Each out-of-process application has its own memory space. If one crashes, it will not affect other applications or the operation of the Web server. This is useful for mission-critical applications. The disadvantage is worse performance.

In-process application protection and out-of-process application protection are available on IIS 4.0 and later. IIS version 5.0 and later provide an additional level of application protection called pooled out-of-process. Pooled applications run in a shared process that is separate from the Web server process. Pooling processes balance application integrity and performance, providing better application protection than in-process applications and better performance than out-of-process applications.

The root folder of any IIS Web site is a Web application. All scripts and executables will run in the application protection defined for the site. A site can host multiple Web applications. Virtual and nonvirtual directories can be created as Web applications. Anything executed within the directory will run in the application protection defined for the directory. To create an application, get a reference to the directory object you want to create the application in and invoke the AppCreate method:

Set objVirtDir = GetObject("IIS:/odin/W3SVC/1/Root/AppDir")
objVirtDir.AppCreate bProcess

The bProcess parameter determines whether the application is an in-process or an out-of-process application. If bProcess is True, the application will run in-process; otherwise, it will run out-of-process. Once the application is created, you can set the application-related properties listed in Table 15-10.

Table 15-10: Web Application-Related Properties
PROPERTY	DESCRIPTION
AspScriptTimeout	Maximum time in seconds an ASP script is allowed to execute.
AspSessionTimeout	Idle time in minutes before a user session is disconnected.
AspEnableParentPaths	Boolean. Determines if ASP can reference items below the root application folder.
AspAllowSessionState	Boolean. Determines if ASP can track user state.
AspScriptLanguage	Default script language for application, such as VBScript or JScript.
AspScriptErrorSentToBrowser	Boolean. If True, detailed error information is sent to the client browser. If False, the message stored in the AspScriptErrorMessage property is displayed.
AppIsolated	Determines how application will run in memory:
	0	Low	In-process
	1	High	Out-of-process
	2	Medium (pooled resources, IIS 5.0 only)
	For IIS 4.0 AppIsolated is a Boolean property, where False sets protection to Low and True sets protection to High.

To delete an application, invoke the AppDelete method on the directory:

objDirectory.AppDelete

If you want to delete all applications associated with a specified directory and all directories below it, invoke the AppDeleteRecursive method:

objDirectory.AppDeleteRecursive

All applications below the specified directory will be deleted.

Maintaining Server Bindings

Problem

You want to maintain server bindings.

Solution

You can bind the site for which you want to set the bindings and then set the ServerBindings property.

The following sample binds to the fourth Web site on server thor:

Set objSite = GetObject("IIS://thor/W3SVC/4")
'bind two domain names to the site
objSite.ServerBindings = Array("192.168.1.40:80:sales.acme.com", _
 "192.168.1.40:80:marketing.acme.com")

objSite.SetInfo

Discussion

In order to host multiple sites on a server, each site must be associated with a unique access identifier. An IIS server may only have one physical IP address, but it can host multiple Web sites.

The ability to host multiple sites is accomplished by assigning a fully qualified domain name, such as www.acme.com, to identify sites. This allows any number of sites to be assigned to a server. Using this method, you specify one or more domain names for a site. When a browser makes a request using the domain name, it is sent with the request in the header. IIS checks the header and redirects the browser to the appropriate site.

The ServerBindings property is an array of strings. Each string element in the array contains an IP address, port, and optional site host name delimited by colons. For example, the string 10.0.1.1:80:sales.acme.com represents a server binding for a site located on IP address 10.0.1.1, hosted on port 80, and assigned the domain name sales.acme.com.

If you want to list the server bindings for a site, enumerate each element from the ServerBindings array property. The following script lists all server bindings for the third Web site on server thor:

Set objSite = GetObject("IIS://thor/W3SVC/3")
For Each strBinding In objSite.ServerBindings
 Wscript.Echo strBinding
Next

To set the server bindings, reference the site for which you want to set the bindings. This may be a Web, FTP, NNTP, or SMTP site. Assign the bindings using an array with one or more bindings. The Solution script assigns two domain names to a site: sales.acme.com and marketing.acme.com. Both sites are bound to the same IP address and port.

Any domain names assigned to a site must be resolvable by client programs. The IIS server does not perform any name service (such as DNS or WINS) operations, nor does it check that the domain names assigned to a site are valid.

Setting the ServerBindings property overwrites any existing addresses assigned to the server. To add a new binding, resize the ServerBindings array and set the new binding. The following script adds a binding for marketing.acme.com to the fourth Web site on server thor:

Dim objSite, nF, aBindings
'get a reference to the fourth Web site on server Thor
Set objSite = GetObject("IIS://thor/W3SVC/4")
aBindings = objSite.ServerBindings
ReDim Preserve aBindings(UBound(aBindings) + 1)
aBindings(UBound(aBindings)) = "192.168.1.40:80:marketing.acme.com"
objSite.ServerBindings = aBindings
objSite.SetInfo

Setting IP Security

Problem

You want to use IP addresses or domain names to limit access to IIS resources.

Solution

You can bind to the object for which you want to set IP security and then get the IPSecurity property. You set the appropriate combination of properties for the IPSecurity object to grant or deny access to the resource.

The following sample restricts the IP address 10.5.5.1, the range of addresses 192.5.5.1 to 192.5.5.254, and any addresses from the domain acme.com:

Set objDir = GetObject("IIS://odin/W3SVC/1/ROOT/images")
'get the IPSecurity
Set objIPSecurity = objDir.IPSecurity
'allow all access to directory by default
objIPSecurity.GrantByDefault = True
'deny the address 10.5.5.1 and range of address 192.5.5.x
objIPSecurity.IPDeny = _
 Array("10.5.5.1, 255.255.255.255", "192.5.5.0, 255.255.255.0")

'deny all computer from domain acme.com
objIPSecurity. DomainDeny= _
 Array("acme.com")

objDir.IPSecurity = objIPSecurity
objDir.SetInfo

Discussion

IIS provides security mechanisms to limit or allow access to resources by an individual IP address or a range of IP addresses. This can be applied at the server, site, folder, or file level. This security is provided by the IPSecurity property. By setting IP security, you can limit the access to resources to specific groups of machines based on their IP address or domain name.

With this security method a resource (site, directory, or file) provides either full access or no access. If full access is provided, the IPSecurity property contains a list of addresses that are denied access. If there is no access, the IPSecurity property contains a list of addresses that are allowed.

This method of applying security may sound confusing, but a look at the IIS MMC administration application can clarify things. The IIS MMC provides the ability to grant or deny IP addresses through the File or Directory Security tab. Figure 15-5 illustrates the restrictions applied after the Solution script has been executed on a directory.

click to expand
Figure 15-5: IP Address and Domain Name Restrictions dialog box

The IPSecurity property exposes a number of properties, which are listed in Table 15-11.

Table 15-11: *IPSecurity* Property Structure
PROPERTY	DESCRIPTION
DomainDeny	Array of domain addresses to deny.
DomainGrant	Array of domain addresses to deny.
GrantByDefault	Boolean. Determines if access is granted or denied by default.
IPDeny	Array of IP addresses to deny.
IPGrant	Array of IP addresses to grant.

If the GrantByDefault property is True, default access to the resource is allowed and the DomainDeny and IPDeny properties are read. If the GrantByDefault property is False, default access to the resource is denied and the DomainGrant and IPGrant properties are read.

IPGrant and IPDeny are arrays of IP addresses represented as a string in the format ipaddress, subnet. The IP address is the address associated with one or more machines you want to grant or deny access and the subnet is an IP subnet that can be used to narrow the access to the resource. The following script lists the security settings for the image directory for the first Web site on thor:

Set objDir = GetObject("IIS://thor/W3SVC/1/ROOT/images")
'if access is granted by default list the denied IP addresses and domains,
'otherwise list the granted IP adresses and domains
If objDir.IPSecurity.GrantByDefault Then
 Wscript.Echo "IP Addresses denied access"
 For Each obj In objDir.IPSecurity.IPDeny
 Wscript.Echo obj
 Next
 Wscript.Echo "Domains denied access"
 For Each obj In objDir.IPSecurity.DomainDeny
 Wscript.Echo obj
 Next
Else
 Wscript.Echo "IP Addresses granted access"
 For Each obj In objDir.IPSecurity.IPGrant
 Wscript.Echo obj
 Next
 Wscript.Echo "Domains granted access"
 For Each obj In objDir.IPSecurity.DomainGrant
 Wscript.Echo obj
 Next
End If

If you want to grant or deny access to a specific computer by IP address, add an entry to the array that starts with the IP address followed by a comma and the subnet mask 255.255.255.255. The string 10.0.0.1, 255.255.255.255 would specify the computer with the IP address 10.0.0.1.

If you want to grant or deny access to a group of computers by IP address, add an entry to the array that starts with the IP address followed by a comma and a subnet mask. The IP address in combination with the subnet mask would determine what range of computer addresses that would be granted or denied access to the resource.

DomainGrant and DomainDeny are arrays of domain names that can be granted or denied access to a resource.

The following snippet of code denies access to all computers except the IP address 10.5.5.1, the range of addresses 192.5.5.1 to 192.5.5.254, and any addresses from the domain acme.com:

Set objDir = GetObject("IIS://odin/W3SVC/1/ROOT/images")
'get the IPSecurity
Set objIPSecurity = objDir.IPSecurity
'deny all access to directory by default
objIPSecurity.GrantByDefault = False
'grant the address 10.5.5.1 and range of address 192.5.5.1 to 192.5.5.254
objIPSecurity.IPGrant = _
 Array("10.5.5.1, 255.255.255.255", "192.5.5.0, 255.255.255.0")

'grant all computers from domain acme.com
objIPSecurity.DomainGrant = _
 Array("acme.com")
objDir.IPSecurity = objIPSecurity
objDir.SetInfo

Internet Information Server

Overview

Backing Up and Restoring IIS Configuration Information

Problem

Solution

Discussion

See Also

Listing Web Sites

Problem

Solution

Discussion

See Also

Creating a Site

Problem

Solution

Discussion

See Also

Starting an IIS Site

Problem

Solution

Discussion

See Also

Deleting a Site

Problem

Solution

Discussion

See Also

Creating Virtual Web Directories

Problem

Solution

Discussion

See Also

Setting File and Directory Properties

Problem

Solution

Discussion

Creating a Web Directory Application

Problem

Solution

Discussion

See Also

Maintaining Server Bindings

Problem

Solution

Discussion

See Also

Setting IP Security

Problem

Solution

Discussion

See Also