Automating Administration for IIS 5.0

  • Article

Curt Johnson, Web Technology Writer
Internet Information Services Documentation Team
Microsoft Corporation

Administering Web sites can be time consuming and costly, especially for people who manage large 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 Services (IIS) offers technologies can help you do all that:

  • Windows Script Host (WSH)

  • IIS Admin Objects and 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 perform many other tasks.

This article explains how to perform common administrative tasks by running the sample ADSI scripts installed with IIS. For example, you'll see how to create a new virtual directory on a remote server and then change the write access to that directory. You'll also see sample custom scripts that can change Windows permissions on a server. These examples show how sample scripts can give you faster, more cost-effective administration.

When you install Windows® 2000 Server 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 detailed information about WSH and ADSI scripts, see "Administration Scripts" in the IIS 5.0 online product documentation (installed by default with IIS).

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 program in VBScript to create a new virtual directory, and then, with WSH, 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 more information, see the Windows Script Host material in the Windows documentation.

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 be easily 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:

Inetpub\AdminScripts

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. The scripts are annotated to give you guidelines in creating your own customized scripts.

In addition to running the sample scripts as they are, you can customize your own scripts by extrapolating from the examples. With custom 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. For an example of customized scripts, see "Customizing Scripts Example" later in this article.

For details about ADSI Objects and how they can configure the metabase, see "ADSI Object Methods" in the IIS 5.0 online product documentation.

Executing Scripts

When you installed Windows 2000 and IIS, you also installed Adsutil.vbs, an IIS administration utility that runs on VBScript with ADSI to manipulate the IIS configuration. You should run this script with CScript, which is installed with WSH. For information about Cscript.exe, see the IIS 5.0 online product documentation.

You can execute an administration script by typing the appropriate syntax on the command line. The following example shows the current settings for the root of the default Web site.

cscript.exe inetpub\adminscripts\adsutil.vbs enum w3svc/1/root

To execute any other script on the command line, type:

Cscript.exe path\ScriptName

Instead of typing the syntax on the command line, you can type it in 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 Inetpub\AdminScripts directory to your environment, you don't have to type the full path to Cscript.exe. For information about editing your path, see the Windows 2000 online documentation.

Note: If you have registered Cscript.exe as your default scripting 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 the first two steps in the next section.

Examples

The following examples show you how ADSI scripts can automate tasks that ISPs must perform over and over. 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 script to automate various tasks. For a detailed explanation of the syntax, see the IIS 5.0 online product documentation.

Changing Permissions

This example shows you how to change permissions for a virtual directory located on a different server. Let's say you want to grant Write permissions on a virtual directory called Test. This Web site is on your company's intranet on a computer named Server2, located in another building. Instead of walking over to the other building, you prefer to make this change from the computer in your office (Server1).

This example assumes that you've added the path to the administration scripts to the Windows environment path or that you are running the scripts in the C:\Inetpub\AdminScripts directory, where they reside.

To change permissions for a Web site on another server

  1. On your administration server, open a command prompt.

  2. 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 want to run, as in the example in the previous section, "Executing Scripts."

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

    4. 



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



where

**test** is the virtual directory on which permissions are reset.

**accesswrite** changes Write permissions.

true grants Write permissions.

**-S:server2** names the server where the Web site is located.



Users can now upload files to the virtual directory Test on Server2.


Creating a Web Site


This example creates a new Web site with the sample ADSI scripts. Let's say you want to create a Web site on your production Web server for a new client that you will be hosting. Repetitive work of creating site after site can easily be automated by running the Mkw3site.vbs script.


This example assumes that you've set the path to the administration scripts, or that you are running the scripts in the C:\Inetpub\AdminScripts directory, where they reside. The following procedure tells you how to set the path to the administration scripts.


To add a path to the Windows environment


    

  1. On the Windows 2000 Desktop, right click My Computer.
    

    2. 

  2. Select Properties.
    

    3. 

  3. On the System Properties dialog box, click the Advanced tab.
    

    4. 

  4. Click the Environment Variables button.
    

    5. 

  5. In the System Variables box, select the line beginning with the word Path.
    

    Bb727082.autoad01(en-us,TechNet.10).gif
    

    6. 

  6. Click the Edit button.
    

    7. 

  7. In the Edit System Variable dialog box, put the cursor at the end of the line in the Variable Value box.
    

    8. 

  8. Type the following to add the path to the sample ADSI scripts:
    

    ;C:\Inetpub\AdminScripts
    

    Note The line begins with a semicolon because each element in the path variable must be separated by a semicolon.
    

    9. 



Once you've set the path, you can create a Web site with the following procedure.


To create the Web site


    

  1. On your administration server, open a command prompt.
    

    2. 

  2. If you have not registered Cscript.exe, register it as described in Step 2 of the previous example. See "Changing Permissions" earlier in this discussion.
    

    3. 

  3. At the command prompt on the server, type the following line:
    

    4. 



mkw3site -r c:\webs\customer1 --DontStart -t "Customer 1 Site" -o 80
-i 172.16.100.1



where

**mkw3site** includes the script to make the Web site.

**–r** defines the root directory of the Web.

**-–DontStart** creates the Web site in a stopped state. To start the Web site, you must activate it through the IIS snap-in or from the command line by typing **net start w3svc**.

**–t** defines the title of the Web site.

**–o** defines the port number.

**–i** defines the IP address for the Web.



Writing Customized Scripts


The following ASP samples show you how to write your own scripts. The first sample shows how a script can set permissions and the second one shows how to set up a virtual directory with directory browsing permissions.


Web server permissions control how users access and interact with specific FTP and Web sites, controlling, for example, whether users visiting a Web site are allowed to see a particular page, upload information, or run scripts on the site. Unlike 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 account.


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 following example also shows 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 VDir1a, 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 
Set VDirObj = GetObject("IIS://MyComputer/W3SVC/1/Root/Vdir1/VDir1a") 

' 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 
%> 



The next example shows you how to write a customized script to create a virtual directory with Read, Script only, 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 vdir 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 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 VR 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.
%>



For more sample scripts and for details on writing your own scripts, see "Programmatic Admin Examples" in the IIS 5.0 online product documentation.