Automating Web Site Administration Using IIS

Article
06/30/2006

Curt Johnson
Web Technology Writer, IIS Documentation Team
Microsoft Corporation

Updated May 7, 1999
New sample scripts and .vbs download

Contents
Introduction
Windows Script Host (WSH)
IIS Admin Objects and ADSI
Executing Scripts
Examples with Sample Scripts
Examples of Customized Scripts

Introduction

Administering Web sites can be time consuming and costly, especially for people who manage large Internet Service Provider (ISP) installations. To save time and money, many ISPs support only large company Web sites, at the expense of personal Web sites. But is there a cost-effective way to support both? The answer is yes, if you can automate administrative tasks and let users administer their own sites from remote computers. This solution reduces the amount of time and money it takes to manually administer a large installation, without reducing the number of Web sites supported. Microsoft® Internet Information Server (IIS) version 4.0 offers technologies to do this:

Windows Script Host (WSH)
IIS Admin Objects built on top of Active Directory Service Interfaces (ADSI)

With these technologies working together behind the scenes, you can administer sites from the command line of a central computer, and you can group frequently used commands in batch files. Then, all you need to do is run the batch files to add new accounts, change permissions, add a virtual server to a site, and do many other tasks. In addition, you can hand over responsibility for administering personal Web sites directly to users.

In this article, you'll see how to perform common administrative tasks by running the administration scripts. For example, you'll see how to create a new virtual directory on a remote server and then add write access to that directory. You'll also see sample custom scripts that can change Windows NT® permissions on a server.

When you install Microsoft Windows NT Server version 4.0 and IIS, ADSI sample scripts and the WSH environment are installed by default. Although the sample scripts are fully functional, they also serve as templates from which you can customize your own scripts. For the syntax of the sample scripts, see "Sample Administration Scripts" in the Product Documentation for the Windows NT 4.0 Option Pack.

Windows Script Host (WSH)

WSH is a language-independent scripting environment for 32-bit Windows platforms. Microsoft offers both Visual Basic® Scripting Edition (VBScript) and JScript® scripting engines with WSH. Third-party companies supply ActiveX® scripting engines for other languages such as Perl.

WSH can automate administrative tasks on a server, using any scripting language. For example, an administrator can write a script in VBScript to create a new virtual directory, and then, with WSH working in the background, run the script file from the command line to create a new virtual directory on the Web site. In addition, administrators can write a single script to target multiple Web sites or multiple physical servers. For detailed information about WSH, see "About Windows Script Host" in the Product Documentation for the Windows NT 4.0 Option Pack.

IIS Admin Objects and ADSI

The IIS Admin Objects installed with IIS make programmatic administration as straightforward as possible. Based on Microsoft's ADSI, the IIS Admin Objects are compatible with automation and can easily be accessed and manipulated by any language that supports automation, such as VBScript or JScript in Active Server Pages (ASP), Visual Basic, Java, or C++.

When you install IIS, the sample IIS Admin Objects scripts are copied into the following directory by default:

%windir%\System32\Inetsrv\AdminSamples.

The variable %windir% represents the directory where Windows NT Server is installed.

Note This article comes with the latest version of the Adsutil.vbs script. Before working through the examples, please move your current version of Adsutil.vbs to another directory where it won't be overwritten, and download this new version into the %windir%\System32\Inetsrv\AdminSamples directory.

Download the Adsutil.vbs script file.

These scripts can configure your IIS installation, create virtual directories, display information about a Web site (see the example in the following section, "Executing Scripts"), and manage the status of Web sites by stopping, pausing, and starting IIS. Each sample file is annotated with comments showing the syntax and an example.

In addition to running the sample scripts as they are, you can write your own customized scripts by extrapolating from the examples. With customized scripts, you can administer your IIS configuration by changing the settings stored in the metabase. The structure of the metabase parallels the structure of your IIS installation, and the property inheritance feature of the metabase lets you set up IIS configuration settings efficiently. You'll find samples of customized scripts in "Examples of Customized Scripts" later in this article.

For details about the metabase, see "About the Metabase and IIS Admin Objects" and for information about the IIS Admin Objects see "IIS Admin Objects Reference" in the Product Documentation for the Windows NT 4.0 Option Pack.

The IIS Admin Objects Reference is installed as an option for IIS with the Windows NT 4.0 Option Pack. If you haven't installed the reference documentation or are unsure if it's installed, follow these steps:

Insert the Windows NT 4.0 CD into your computer's compact disk drive.
On the taskbar, click Start, then Programs, then Windows NT 4.0 Option Pack, and select Windows NT 4.0 Option Pack Setup.
When you see the initial setup screen, click Next.
On the next screen, click Add/Remove.
In the Components window, select Internet Information Server (IIS), and click Show Subcomponents.
Select Documentation, and click Show Subcomponents.
If SDK is selected, then the reference documentation has been installed and you can cancel Windows NT 4.0 Option Pack Setup. If SDK is not selected, continue with the next step.
Select SDK, and click OK.
In the Internet Information Server (IIS) dialog box, click OK.
In the Microsoft Windows NT 4.0 Option Pack Setup dialog box, click Next.
Click Finish.

The IIS Admin Objects Reference contains a list of all the objects with links to the appropriate reference page. The reference page for each object includes:

ADSI and ADSI container information
The ADsPath for the object
Metabase properties accessible by the object
Any additional methods specific to the object

For example, in the "IIS Admin Objects Reference" section of the Product Documentation for the Windows NT 4.0 Option Pack, click IISWebVirtualDir, and you'll find the following information:

The IIsWebVirtualDir object is an ADSI container object.

ADsPath

For the server's root virtual directory,

IIS://MachineName/W3SVC/n/Root

Where MachineName can be any name or "LocalHost".

For a specific virtual directory,

IIS://MachineName/W3SVC/n/Root/vdirName

Where MachineName can be any name or "LocalHost".

Syntax

varReturn = object.{Method}

Parts

varReturn

A variable that receives the return value from the method.

object

A variable that contains the IIsWebVirtualDir object, usually as a result of a previous GetObject operation.

Method

The object method chosen.

May Contain

IIsWebVirtualDir IIsWebDirectory IIsWebFile

You'll also find list of ADSI Object properties as well as metabase properties and methods, along with links to information about each property and method.

Executing Scripts

You can execute a script in one of two ways. Just type the appropriate syntax on the command line.

To execute a script on the command line, type: Cscript.exe ScriptName

To execute a script in a graphical user interface, type: Wscript.exe ScriptName

Alternatively, you can type the syntax into a batch (.bat) file, and execute your scripts from there. If you execute the same script repeatedly, putting it into a batch file saves you from retyping the script every time you want to run it.

Note The examples will not work correctly unless you have downloaded the updated Adsutil.vbs file, as recommended in the previous section.

The following example shows the current settings for the root of the default Web site. On the command line, type:

cscript.exe %windir%\system32\inetsrv\adminsamples\adsutil.vbs enum w3svc/1/root

To execute any other script on the command line, type the following syntax: Cscript.exe path\ScriptName

Instead of typing the syntax on the command line, you can type it into a batch (.bat) file and execute your scripts from there. If you execute the same script repeatedly, putting it into a batch file saves you from retyping the script every time you want to run it.

If you've added the path to the AdminSamples subdirectory, you don't have to type the full path to Cscript.exe. For information about editing the path, see the Windows NT Server documentation.

Also, if you have registered Cscript.exe as your default Script Host, you don't have to type Cscript.exe in front of the scripts to execute them. To learn how to register Cscript.exe, see Step 1 in the next section.

For more information about Cscripte.exe and Wscript.exe, see "Running Scripts Using the Command-Based Script Host" and "Running Scripts Using the Windows-Based Script Host" in the Product Documentation for the Windows NT 4.0 Option Pack.

Examples with Sample Scripts

The following examples show you how ADSI scripts can automate tasks that need to be done repeatedly. The first two examples show how to run the sample scripts and make them work for you. The final two examples show how to create custom scripts to automate various administrative tasks. For a detailed explanation of the syntax, see the Product Documentation for the Windows NT 4.0 Option Pack.

Creating a Virtual Directory

Let's say you want to create a virtual directory called "Test." This directory is on your company's intranet, on a computer named "Server2." Server2 is located in another building, about half a block from your office. Instead of walking over to the other building, you prefer to make this change right from the computer in your office, Server1.

Note For these examples to work, you must change the Windows NT environment variable on Server1 to include the path to the administration scripts. If you don't want to change this variable, you can alternatively run the scripts from their default location: %windir%\System32\Inetsrv\AdminSamples.

To create a virtual directory on another server

Open a command prompt.
At the command prompt of the server you want to administer from, type adsutil and accept the defaults to register Cscript.exe.
If you don't want to register Cscript.exe (because you are running another scripting host by default), then you have to type Cscript.exe in front of the script you are running. For information about Cscript.exe, see the IIS online product documentation.
Now, with the mkwebdir.vbs script, you can quickly create the new directory from the command prompt. Just type the following:

mkwebdir -c Server2 -w "Default Web Site" -v
"Test","C:\Test"

This command creates the Web directory Test on the computer Server2 under the default IIS Web site on that computer.

Note You don't have to create the physical directory before you run this script. The script creates both the physical and virtual directories for you. Also, the name of the virtual directory can be different from the name of the physical directory.

Changing Access Permission

Now let's say you want to allow users write access on the virtual directory "Test."

To change access for a virtual directory on another server

At the command prompt on Server1, type the following line:

adsutil set w3svc/1/root/test/accesswrite "true"-S:server2

This line adds write access to the virtual directory Test on Server2.

Examples of Customized Scripts

Web server permissions control how users access and interact with specific FTP and Web sites. For example, Web server permissions can control whether users visiting a Web site are allowed to see a particular page, upload information, or run scripts on the site. Unlike Windows NT File System (NTFS) permissions, Web server permissions apply to all users accessing a Web or FTP site. This distinction is very important because NTFS permissions apply only to a specific user or group of users with a valid Windows NT account.

GET/PUT and Dot Notations

The following example contains customized scripts that set permissions on a virtual directory in two ways:

GET/PUT notation: Choose this type for script that contains variables.
Dot notation: Choose this type for hard-coded scripts.

The example also demonstrates how inheritance works. In the first part of the example, the GET/PUT notation denies write permission (sets it to False) from the root level of the default Web site on MyComputer. When you set permission at the root level, all directories below the root level inherit this setting. However, the dot notation (the second part of the example) grants write permission (sets it to True) on the virtual directory named Dir1a, overwriting the inherited setting from the root.

<%
Dim WebServerRootObj
Dim VDirObj
Dim WritePerm

' Open the object for the first virtual Web server root
Set WebServerRootObj = GetObject("IIS://MyComputer/W3SVC/1/Root")

' Deny write access for all directories and files
' for the server (except those already specifically set)
' Using the Put method
WebServerRootObj.Put "AccessWrite", False

' Save the changed value to the metabase
WebServerRootObj.SetInfo

' Get a directory subordinate to the Web server root. Note that this line of code assumes
' Vdir1 has already been created.
Set VDirObj = GetObject("IIS://MyComputer/W3SVC/1/Root/Vdir1/Dir1a")

' Overwrite the inherited value for write access
' using the dot method equivalent to Put
VDirObj.AccessWrite = True

' Save the changed value to the metabase
VDirObj.SetInfo
%>

ADSI ASP Script

The next example shows you how to write a customized script to create a virtual directory with Read, Script, and Directory browsing permission.

<%
'''''''''''''''''''''''''''''''''
' ADSI ASP Sample Program
' This is a sample of how to create a virtual directory using ADSI.
'
'''''''''''''''''''''''''''''''''
Option Explicit
On Error Resume Next

'''''''''''''''''''''''
' First, open the path to the Web server you are
' trying to add a virtual directory to.

Dim ServObj
Dim VdirObj
Dim Testpath

Set ServObj = GetObject("IIS://LocalHost/w3svc/1/Root")
if (Err <>0) then
   Response.Write "GetObject (""IIS://LocalHost/w3svc/1/Root"") Failed! <br>"
   Response.Write "Error! " & Err.Number & "(" & Hex(Err.Number) & "): " & Err.Description & "<br>"
   Response.End
end if

'''''''''''''''''''''''
' Second, Create the virtual directory (Vdir) path
Set VdirObj = ServObj.Create("IIsWebVirtualDir", "MyVdir")
VdirObj.SetInfo
if (Err<>0) then
   Response.Write "CreateObject (""IIS://LocalHost/w3svc/1/Root/MyVdir"") Failed!<br>"
   Response.Write "Error! " & Err.Number & "(" & Hex (Err.Number) & "): " & Err.Description &

"<br>"
   Response.End
end if

''''''''''''''''''''''''
' Finally, create a Path variable containing the virtual root path and
' set the permissions to read, script, and directory browsing
VdirObj.AccessRead = True
VdirObj.AccessScript = True
VdirObj.EnableDirBrowsing = True
Testpath = "C:\Temp"
VdirObj.Put "Path", (Testpath)

VdirObj.SetInfo
if (Err<> 0) then
   Response.Write "Put (""Path"") Failed!"
   Response.Write "Error! " & Err.Number & "(" & Hex (Err.Number) & "): " & Err.Description &

"<br>"
   Response.End
end if

Response.Write "VDIR successfully created"

''''''''''''''''''''''''
' The minimum amount necessary to create a virtual directory has now
' been completed.  If you need to add more, do it here.

%>

Now it's your turn to jump in, create your own scripts, and tailor them to your needs. For details about scripting, see "Automating and Customizing your Operations" in the product documentation for the Windows NT 4.0 Option Pack.