David Wang : Tips

HOWTO: IIS 6 Request Processing Basics, Part 2 - Web Site, Virtual Directory, and Web Application

David.Wang — Sun, 07 Dec 2008 19:24:00 GMT

Question:

In brief, what is different about a virtual directory that is also set as a Web Application? I can have a virtual directory, and then optionally set it to be a Web Application. Beyond updating the metabase, what does IIS do that causes the virtual directory to "be" a Web application? And how is the runtime behavior or capabilities different between a virtual directory that is not also a Web application, and one that is a Web application?

Is there anything different (in terms of runtime behavior or capabilities) between a Web Application defined on a Web Site root virtual directory, as compared to a Web Application additionally defined on a virtual directory beneath a Web Site root virtual directory (i.e., a "web application within a web application")?

Answer:

This is an often asked question and point of confusion. I will clarify the terms from an IIS perspective.

What's in a Name?

The generic terms "web application", "virtual directory", "virtual server", and "web site" are inconsistently defined between servers/applications/platforms, so you have to understand the term's meaning in each server/application/platform and translate appropriately. In fact, even Microsoft products do not standardize on a common meaning for those terms, and due to historical legacy of each product, they will likely never change, converge, nor standardize. Sigh.

For example, a Sharepoint "Virtual Server" is the same as an IIS "Web Site" and not to be confused with Microsoft's "Virtual Server" virtualization platform, which hosts virtual machines - who themselves can end up hosting Sharepoint Virtual Servers aka IIS Web Sites. Confused yet? Good. :-)

IIS's terminology does not include the term "Virtual Server". When most people talk about "Virtual Server" they are often thinking of an IIS Web Site, or something that answers HTTP requests to host their logical website, which consists of a single application codebase.

Web Site

An IIS Web Site is a mapping between a <IP:Port:Hostname> Binding triplet and a "root" Web Application (defined shortly) that responds to "/". The Web Site is how IIS figures out whether it should handle any given HTTP request and if so, with what configuration. Since this determination directly affects how a HTTP request is handled, all Binding definitions MUST be unique on a IIS machine. You do not want two Web Sites potentially fighting over the same request, right? Now, the Binding triplet is different than the "Friendly Name", which is an optional string meant for User's identification benefit. It can be "Default Web Site" or anything else, and since it is optional and not used for request handling determination, it can be duplicate or not defined.

For example, suppose you have the following Web Sites with the following Binding triplets. This is what each means:

:80: - across all IPs of all NICs, handle port 80 traffic, regardless of Host header
12.34.56.78:443 - only requests to IP 12.34.56.67 on port 443
:80:Domain2.com - across all IPs of all NICs, handle port 80 traffic for requests with Host header of Domain2.com

With this configuration, when IIS receives any request, it knows from TCP/IP which IP:Port the request is meant for, and if the data is unencrypted, it can decipher the Host: header, and with these three pieces of information, it can determine if it matches any Web Site's Binding definition (or none) and route/handle accordingly. If it matches nothing, a "400 Bad Request" response is returned.

SSL Host Header (sidetrack)

At this point, I will briefly digress on another topic, SSL Host Headers.

Technically, there is no such thing as SSL Host Header. From the perspective of the SSL Specification, host headers do not exist because they are defined in the HTTP specification and not TCP where SSL operates.

When IIS receives any request, it only knows the IP:Port that request is destined for. In order to determine the Host header of a request, IIS must decipher the request's payload data. And to do that for an SSL request, IIS has to first decrypt the payload data by using a Server Certificate to complete the SSL handshake with the Client. However, IIS needs to know the Host header in order to know which Binding, and hence which Server Certificate, to use to decrypt the payload data and decipher the Host header. This is clearly a Catch-22.

So, how does IIS implement "SSL Host Headers"? It breaks the Catch-22 by requiring all sites using SSL Host Headers for a given Binding must be configured to use the same Server Certificate. That way, when IIS gets a IP:Port of a request, it can unambiguously use that now-synchronized Server Certificate to first decrypt the Host: header, and THEN decide which Web Site matches the IP:Port:Host Binding and route the request to it.

Web Application

A Web Application is a mapping between a name in the virtual namespace (i.e. the URLs "/", "/App", or "/cgi-bin") and its runtime properties. These runtime properties tell IIS how to execute a request which belongs in the virtual namespace. Common runtime properties include:

Whether user's application code is to be executed "In Process", "Out of Process", or "Pooled" [for IIS 4/5/5.1/6 in IIS5 Compatibility Mode] or specific Application Pood ID [for IIS6 in Worker Process Isolation Mode and IIS7]
Process Identity used to execute program code
Monitoring/Recycling Metrics
etc...

By default, whenever you create a Web Site and define the Binding (and optionally the Friendly Name), IIS also creates a "root" Web Application for "/" and asks you for a Virtual Directory mapping (defined shortly). This is because people commonly create a Web Site to host a Web Application which consists of files located at same physical directory, so defining all three features make sense... but the three concepts are definitely different.

Virtual Directory

A Virtual Directory is a mapping between a name in the virtual namespace (i.e. the URLs "/", "/App", or "/cgi-bin") and a corresponding physical name (i.e. the Filesystem name "C:\inetpub\wwwroot\App"). It allows IIS to calculate a physical resource name for any given virtual name and provide it to the handler of the request.

For example, suppose "/" maps to the physical name "C:\inetpub\wwwroot". A request for "/default.asp" refers to the physical name "C:\inetpub\wwwroot\default.asp".

The astute reader should realize that the mapping provided by a Virtual Directory is merely a "recommendation" by IIS to the request's handler - the actual handler of a request can do whatever mapping it wants with the virtual and physical names provided.

In the case of /default.asp, IIS first goes through this process to figure out the handler. Suppose it ends up being ASP.DLL - it will honor the physical name C:\inetpub\wwwroot\default.asp and execute the script contained within it to generate a response.

However, the handler or its script code can choose to implement its own name mapping scheme to process a given request. For example, some people write ASP pages like "redir.asp" which return different responses based on template HTML stored within a SQL database depending on the querystring. i.e. /redir.asp?id=1 will load up some template HTML in SQL and generate a HTML response. Clearly, Virtual Directory is only a hint/recommendation provided by IIS to the request handler, which can do whatever it wants with the information.

Conclusion

Given the above information, the answers to your questions are straight forward.

A plain Virtual Directory provides a virtual/physical name mapping and MUST inherit and use the runtime settings defined at its nearest parent to execute code contained within it.

A Virtual Directory that is also a Web Application has the option to inherit from its nearest parent AND customize runtime settings to execute code contained within it.

Clearly, if you do not customize runtime settings, then it is not necessary to create a Web Application. And if you create a Web Application and customize runtime settings, then behavior of code execution may be different than a plain Virtual Directory (assuming that the inherited settings by the Virtual Directory do not match the customized settings of the Web Application).

As for differences between a "root" Web Application and a nested Web Application within another Web Application or Virtual Directory. IIS does not treat them differently since Web Applications are just runtime settings. However, application platforms running on top of IIS may choose to interpret the "application root" of an Web Application differently and behave accordingly. For example, ASP.Net uses "Web Application" to delimit the boundaries of its applications, so if you nest a Web Application within another, you end up with two different ASP.Net Web Applications.

//David

HOWTO: PreCondition an ISAPI Extension DLL

David.Wang — Fri, 31 Oct 2008 08:00:00 GMT

Question:

Hello

We have a legacy x64 ISAPI extension that runs without problems in Win 2003 64bit - IIS 6.0.

But in Win2008 EBS Security Manager setup, IIS 7.0 Default Application Pool's WOW64 / Enable32BitApp property is enabled by default, and this makes x64 ISAPI extension DLL to fail loading.

By setting the Enable32BitApp option as false in application pool settings, the problem gets resolved.

However we want to speicify ISAPI extension explicitly to be loaded as x64 module using "precondition='bitness64' " settings like ISAPI filters, so that ISAPI extension works no matter what application pool is configured for (x64 only, or both x64 and x86)

Could anyone please suggest how we can do this or the app cmd that would allow us to do it.

Answer:

Technically, preConditions only apply on a per-GlobalModule, per-Module, per-Handler, or per-ISAPI Filter basis. This is because globalModules, modules, handlers, and ISAPI Filters have to be explicitly configured within IIS to function. ISAPI Extensions simply need to be dropped into a web-accessible folder and then "allowed to execute" via Executable execution permission and IsapiCgiRestriction. There is no per-ISAPI Extension configuration to stick preConditions.

However, as I will illustrate shortly, it is STILL possible to apply preConditions on a per-ISAPI Extension basis in a fairly clean and clear manner.

Some people would propose that it would be nice to stick preCondition onto IsapiCgiRestriction since it is a sort of per-ISAPI Extension configuration, but IsapiCgiRestriction is really a security configuration which we hardly want to preCondition. Besides, what happens if notListedIsapisAllowed="true" and we still want to preCondition an ISAPI Extension - now we have to add a bogus entry for preCondition? Anyways, this is getting complicated very quickly, a sure sign that the proposed design has some fundamental logical flaw.

Common Misconceptions about Bitness and preConditions

Now, before I get into how to setup per-ISAPI Extension preCondition, I want to clarify some of the misconceptions in your question about Bitness and preCondition. Using preCondition="bitness64" does NOT:

Explicitly load an ISAPI Extension as x64 module
Make an ISAPI work no matter what the application pool is configured for
Allow "both x64 and x86" of ANYTHING

A preCondition is a simple filtering mechanism on the affected IIS configuration. What preCondition="bitness64" means is that the affected configuration is ONLY applicable in a 64bit Application Pool. A 64bit Application Pool will only see globalModule, module, handler, and isapiFilter with either bitness64 or no bitness preCondition. It will not see any globalModule, module, handler, and isapiFilter configuration with the bitness32 preCondition.

Thus, a preCondition does NOT cause an ISAPI to be explicitly loaded as any bitness. LoadLibrary() will just load the resolved DLL name into the process's address space, and if the bitness do not match, fail. Likewise, it cannot make the ISAPI work no matter what, because if the bitness does not match, it fails. Finally, Windows does not allow both 32bit and 64bit code to co-exist in the same process, and IIS does not allow an Application Pool to be both 32bit and 64bit.

What is a correct way to use the bitness preConditions? Check out the various pre-defined "-64" handlers when ASP.Net Feature support is installed. For example, the svc-ISAPI-2.0 and svc-ISAPI-2.0-64 handlers. Notice that the bitness32 preCondition applies to a 32bit ISAPI, and bitness64 preCondition applies to a separate 64bit ISAPI. This dual configuration allows the same feature to work with both 32bit and 64bit Application Pools with no additional configurations changes in-between. Remember how you had to run aspnet_regiis.exe from the correct Framework bitness directory every time you changed Application Pool bitness with .Net Framework 2.0 on IIS6 in 64bit Windows, or else you would see 503 Service Unavailable failure? No longer necessary with preConditions on IIS7 and things just work!

PreConditioning an ISAPI Extension DLL

As I mentioned earlier, per-ISAPI Extension preCondition can be accomplished by leveraging preCondition support of handlers. The following configuration shows how to request an ISAPI Extension name "MyISAPI.dll" and have it work no matter the bitness of the Application Pool. It requires a 32bit version and 64bit version of the same DLL, named MyISAPI32.dll and MyISAPI64.dll, respectively.

<handlers>
  ...
  <add name="MyISAPI-64" path="MyISAPI.dll" verb="*" modules="IsapiModule" scriptProcessor="C:\inetpub\wwwroot\bin\MyISAPI64.dll" resourceType="File" requireAccess="Execute" preCondition="bitness64" />
  <add name="MyISAPI-32" path="MyISAPI.dll" verb="*" modules="IsapiModule" scriptProcessor="C:\inetpub\wwwroot\bin\MyISAPI32.dll" resourceType="File" requireAccess="Execute" preCondition="bitness32" />
  ...
</handlers>

Looking at the key configuration details:

Having two handlers, one with bitness32 preCondition on the 32bit MyISAPI32.dll, the other with bitness64 preCondition on the 64bit MyISAPI64.dll, assures that only one of these handlers with the correct bitness apply to any given Application Pool
path="MyISAPI.dll" means that end consumers only request /MyISAPI.dll while the dynamic 32/64bit wiring happens underneath the covers via the bitness preCondition
requireAccess="Execute" makes Execute permissions necessary to execute an ISAPI Extension DLL in a given URL namespace

The combination of preConditions, path-remapping, and requireAccess gives the illusion of a single named ISAPI DLL which transparently works with similar requirements as ISAPI Extension regardless of Application Pool bitness. Yes, don't forget to set IsapiCgiRestriction on both MyISAPI64.dll and MyISAPI32.dll as well as enable "Execute" permission on your virtual directory... :-)

Cheers.

//David

HOWTO: List all Virtual Directories and Paths of a List of Servers

David.Wang — Thu, 20 Dec 2007 08:30:00 GMT

Question:

I need to audit web servers in my domain, and would like to be able to connect to each server, and enumerate the virtual directories -- ultimately leading to a link to each web site hosted by the server. Can this code be modified to get that information?

Thanks.

Answer:

Yes, you can modify that code to get this information, but if you just want a list of virtual directories on a server, you don't need to write any script code to do it. At the end of this blog entry is one way, using a simple batch file, to get this information using ADSUTIL.VBS, a built-in script. Just make sure to provide the right filepath for CMD_ADSUTIL. And of course, the user running the script must have administrator privileges to enumerate the IIS metabase on all required servers.

This batch file accepts one optional input parameter.

If you provide no parameter, it will enumerate all vdirs and their respective physical paths of the local computer
If you provide a computer name, it will enumerate all vdirs of that computer
If you provide a filepath, it will treat each line of the file as a computer name and enumerate all its vdirs

Since I often see this feature requested, I decided to show one simple way to turn a script which takes a server name as input into one that loops through a list of server names stored in a text file, one server name on each line. This should hopefully be illustrative enough of the powerful combination of both VBScript/JScript and Batch script.

Sample usage:

C:\>enumvdirs -?
enumvdirs [servername | file-list]

Where:
    servername is the name of the server to query. DAVIDWANG by default
    file-list is filepath to text file containing list of servers, one per line

C:\>enumvdirs DAVIDWANG
DAVIDWANG/W3SVC/1/ROOT = "c:\inetpub\wwwroot"
DAVIDWANG/W3SVC/1/ROOT/IISHelp = "c:\windows\help\iishelp"
DAVIDWANG/W3SVC/1/ROOT/Printers = "C:\WINDOWS\web\printers"
DAVIDWANG/W3SVC/1/ROOT/Scripts = "C:\Inetpub\Scripts"

C:\>ECHO %COMPUTERNAME% > ListOfServers.txt

C:\>TYPE ListOfServers.txt
DAVIDWANG

C:\>enumvdirs ListOfServers.txt
DAVIDWANG/W3SVC/1/ROOT = "c:\inetpub\wwwroot"
DAVIDWANG/W3SVC/1/ROOT/IISHelp = "c:\windows\help\iishelp"
DAVIDWANG/W3SVC/1/ROOT/Printers = "C:\WINDOWS\web\printers"
DAVIDWANG/W3SVC/1/ROOT/Scripts = "C:\Inetpub\Scripts"

Enjoy.

@IF NOT DEFINED _ECHO ECHO OFF
SETLOCAL
SET CMD_ADSUTIL=CSCRIPT.EXE //Nologo %SYSTEMDRIVE%\Inetpub\Adminscripts\ADSUTIL.VBS
SET PROPERTY_TO_FIND=Path

SET SERVERS="%1"
IF ?%1? EQU ?? SET SERVERS="%COMPUTERNAME%"
IF EXIST %SERVERS% SET SERVERS=%SERVERS:~1,-1%

SET NEED_HELP=%SERVERS:?=%
IF /I "%NEED_HELP%" NEQ "%SERVERS%" GOTO :Help

FOR /F %%A IN ( %SERVERS% ) DO (
    FOR /F "usebackq skip=1 tokens=*" %%I IN ( `%CMD_ADSUTIL% FIND %PROPERTY_TO_FIND% -s:%%A` ) DO (
        FOR /F "usebackq tokens=3,*" %%J IN ( `%CMD_ADSUTIL% GET %%I/%PROPERTY_TO_FIND% -s:%%A` ) DO (
            ECHO %%A/%%I = %%K
        )
    )
)

ENDLOCAL
GOTO :EOF



:Help
ECHO %0 [servername ^| file-list]
ECHO.
ECHO Where:
ECHO     servername is the name of the server to query. %COMPUTERNAME% by default
ECHO     file-list is filepath to text file containing list of servers, one per line

GOTO :EOF

//David

HOWTO: Basic Native/Managed Code Interop

Anonymous — Thu, 13 Jul 2006 14:59:00 GMT

IIS7 core extensibility model supports both native and managed code as first-class citizens. So, I feel it is time for a little refresher on managed/native code interop... starting with the more popular route of how to wrap native code API for use within managed code. I am using the newer syntax introduced with .Net Framework 2.0 instead of the older, kludgy syntax.

Now, I am going to ignore the reciprocal route of calling managed code from native code for a couple of reasons:

It is just boiler plate COM Interop within native code after generating and registering the CCW (COM Callable Wrapper) of the managed class.
Why don't you just write a managed code module/handler in IIS7 to directly use that managed API?

The example illustrates how to use Managed Code to:

Pass a .NET String into Managed C++
Manipulate a .NET String in Managed C++
Return a .NET String from Managed C++
Pass in arbitrary number of args into Managed C++

Remember to use a Class Library Project for Sample.h and Sample.cpp to create a Managed C++ Wrapper around native code API, and you can use the resulting Managed Assembly from Sample.cs managed code.

Enjoy,

//David

Sample.h

#pragma once
#include <windows.h>
#include "SomeNativeAPI.h"

using namespace System;
using namespace System::Runtime::InteropServices;

namespace Sample
{
    public ref class ManagedClass
    {
    public:
        ManagedClass( String^ name );
        ~ManagedClass();
        !ManagedClass();
        String^ DebugPrint( String^ format, ...array<String^>^ args );
    private:
        SomeNativeType* m_pType;
    };
}

Sample.cpp

#include "Sample.h"

Sample::ManagedClass::ManagedClass( String^ name )
{
    //
    // Convert .NET String into LPSTR for 
    // Native code API to use in constructor
    //
    IntPtr szName;
    szName = Marshal::StringToHGlobalAnsi( name );
    m_pType = new SomeNativeType( szName );
    Marshal::FreeHGlobal( szName );
}
Sample::ManagedClass::~ManagedClass()
{
    this->!ManagedClass();
}
Sample::ManagedClass::!ManagedClass()
{
    delete m_pType;
}
String^ Sample::ManagedClass::DebugPrint( String^ format, ...array<String^>^ args )
{
    //
    // Use Managed Code to format variable arguments as .NET String,
    // convert the .NET String into Unicode String, and pass
    // it to Native API
    //
    String^ formattedString = System::String::Format( format, args );
    IntPtr  wszFormattedString;

    wszFormattedString = Marshal::StringToHGlobalUni( formattedString );
    m_pType->SomeFunctionUnicode( wszFormattedString );
    Marshal::FreeHGlobal( wszFormattedString );

    return formattedString;
}

Sample.cs

namespace Sample
{
    class Program
    {
        static void Main( string[] args )
        {
            Sample.ManagedClass cls = new Sample.ManagedClass( "Name?" );
            System.Console.WriteLine( cls.DebugPrint( "0:{0},1:{1}", "N", "V" ) );
        }
    }
}

HOWTO: Convert between JScript Array and VB Safe Array

Anonymous — Tue, 04 Jul 2006 12:10:00 GMT

I recently got a question about how to manipulate the LIST data type within JScript since my sample code only illustrated VBScript.

Well... one reason why that example is in VBScript is because LIST manipulation (a VB SafeArray) is more straight forward and requires much less code in VBScript.

Then, there is Microsoft documentation which says the following time and again (and echo'd in lots of other places):

There is currently no way to convert a JavaScript array into a VBArray

Really? I could not believe it. A quick search of the Internet turned up no results of how to do this, either... so it sounds like a good challenge to me. :-)

I racked my brain a little, and I came up with the following built-in solution to the problem of converting a JScript array into a VB SafeArray. Yes, I know it is not efficient, but for casual conversion for the purposes of IIS configuration, it definitely suffices. And it works on Windows 2000 on up with no additional requirements, a definite bonus from a dependency/ubiquity point-of-view.

See the following JScript code which manipulates the IIS ScriptMaps property (a VB SafeArray) by first converting the SafeArray into JScript array, then manipulating it in JScript, and finally converting it back to a VB SafeArray for use by the Scriptmaps LIST property.

Enjoy!

//David

var objRoot = GetObject( "IIS://localhost/w3svc/1/root" );
var arrVB = objRoot.Get( "ScriptMaps" );

//
// Convert from VB Array for manipulation in JScript
//
var arrJS = VB2JSArray( arrVB );
//
// Insert a test Value at end of ScriptMaps
//
arrJS[ arrJS.length ] = ".test,value,0";
//
// Convert back to VB Array to save by IIS
//
objRoot.ScriptMaps = JS2VBArray( arrJS );
objRoot.SetInfo();

function VB2JSArray( objVBArray )
{
    return new VBArray( objVBArray ).toArray();
}

function JS2VBArray( objJSArray )
{
    var dictionary = new ActiveXObject( "Scripting.Dictionary" );
    for ( var i = 0; i < objJSArray.length; i++ )
    {
        dictionary.add( i, objJSArray[ i ] );
    }

    return dictionary.Items();
}

HOWTO: Monitor Virtual Server Events

Anonymous — Thu, 29 Jun 2006 15:14:00 GMT

I think Virtual Server Events and Asynchronous Tasks are two of the least utilized features of the Virtual Server Administration API.

Contrary to the often-asked task of "find the VM, turn it off, manipulate its VHD, then turn it back on", which shows the synchronous, task-driven side of the VS Admin model, Events and Asynchronous Tasks show off a nice event-based, asynchronous model suitable for passive monitoring and response. What good is this?

Well... that's the motivation behind this blog entry's sample code, which illustrates a simple "Virtual Server Monitor Agent" which does a few basic things:

By default, it simply monitors all Virtual Server events and reports them to the console window. Assuming you named the JScript code VSMonitor.js, just launch it from the commandline with:
START CSCRIPT VSMonitor.js
Thereafter, whenever you start a Virtual Machine, a new child monitor script will pop up and monitor just that Virtual Machine
If that Virtual Machine has a Virtual DVD drive, they will also be monitored for media insertion/ejection and type (ISO or drive letter path)
When you turn off a Virtual machine, its associated child monitor script will also terminate (but it will first popup a message telling you this, in case you missed it).
It also notices when you fail to startup a Virtual Machine due to Out-of-Memory and report that via a popup

The sample basically illustrates how to:

Sync on Virtual Server wide events
Act on a Virtual Server wide event
Sync on Virtual Machine specific events
Act on a Virtual Machine specific event
Sync on Virtual DVD specific events
Report on Virtual DVD events

And it should provide enough information for you to play around, note when events happen, and note available data for the event... and implement other interesting ideas supported by the API. I don't have any in mind, but if you do... feel free to share... because then I may update this sample to do something more interesting. :-)

Enjoy.

//David

var strVMName = "sample VM Name";
var CRLF = "\r\n";
var NO_WAIT = false;
var VISIBLE = 1;

var ERROR_VM_NOT_FOUND = -2146828283;
var ERROR_VM_OUT_OF_MEMORY = 3238134821;

var fSignaled = false;
var fPopup = true;
var cPeriod = 10000;

var VM_STATE_STRING = {
    0 : "Invalid",
    1 : "Off",
    2 : "Saved",
    3 : "Turning on",
    4 : "Restoring",
    5 : "Running",
    6 : "Paused",
    7 : "Saving",
    8 : "Turning off",
    9 : "Merging drives",
    10 : "Deleting VM"
};
var VM_STATE_OFF = 1;
var VM_STATE_RUNNING = 5;

var objVS = null;
var objVM = null;
var objDVD = null;
var objShell = null;
var enumObjs;
var enumObj;

if ( WScript.Arguments.Length > 0 )
{
    strVMName = WScript.Arguments.Item( 0 );
}

try
{
    objShell = new ActiveXObject( "WScript.Shell" );
    objVS = new ActiveXObject( "VirtualServer.Application" );

    try
    {
        //
        // Try to locate the specified VM and listen for its events
        // If fail to locate VM, just listen for VS-wide events
        //
        objVM = objVS.FindVirtualMachine( strVMName );
        WScript.ConnectObject( objVM, "VirtualMachineEvent_" );

        //
        // If the VM has any DVD drives, listen for their changes, too
        //
        enumObjs = new Enumerator( objVM.DVDROMDrives );

        for ( ; !enumObjs.atEnd(); enumObjs.moveNext() )
        {
            objDVD = enumObjs.item();
            WScript.ConnectObject( objDVD, "VirtualDVDEvent_" );
        }
    }
    catch ( e )
    {
        if ( e.number == ERROR_VM_NOT_FOUND )
        {
            LogEcho( "Failed to find VM " + strVMName + "." );
        }
        else
        {
            LogEcho( formatErrorString( e ) );
        }

        objVM = null;
        WScript.ConnectObject( objVS, "VirtualServerEvent_" );
    }

    LogEcho( "Waiting for Events from: " + CRLF +
             ( objVM  != null ? "- VM " + strVMName + CRLF : "- VS Wide" ) +
             ( objDVD != null ? "- DVD Drive(s)" + CRLF : "" ) +
             "" );

    //
    // Poll every cPeriod time period to determine if should exit
    //
    while ( !fSignaled )
    {
        WScript.Sleep( cPeriod );
    }
}
catch ( e )
{
    LogEcho(
        formatErrorString( e ) + CRLF +
        ( objShell == null ?
            "Failed to create WScript.Shell - check:" + CRLF +
            "- %windir%\System32\WSHOM.OCX is ACLed for user" + CRLF +
            "- Scripts are allowed by Personal Security products" + CRLF :
            "" ) +
        ( objVS == null ?
            "Failed to create Virtual Server COM object - check:" + CRLF +
            "- Virtual Server is installed" + CRLF +
            "- User has Control/Execute Access in VS Security" + CRLF :
            "" )
            );
    LogEcho( "Waiting a few seconds for you to read this..." );
    WScript.Sleep( cPeriod );
}

function LogEcho( str )
{
    WScript.Echo( str );
}

function LogPopup( str )
{
    if ( fPopup )
    {
        objShell.Popup( str );
    }
    else
    {
        LogEcho( str );
    }
}

function formatErrorString( objError )
{
    return "(" + Int32ToHRESULT( objError.number ) + ")" + ": " +
           objError.description;
}

function Int32ToHRESULT( num )
{
    if ( num < 0 )
    {
        return "0x" + new Number( 0x100000000 + num ).toString( 16 );
    }
    else
    {
        return "0x" + num.toString( 16 );
    }
}

//
// Virtual Server Events
//
function VirtualServerEvent_OnEventLogged( e )
{
    LogEcho( "VirtualServer_OnEventLogged: (Event ID) " + e );

    if ( e == ERROR_VM_OUT_OF_MEMORY )
    {
        LogPopup( "Cannot start VM due to out of memory" );
    }
}
function VirtualServerEvent_OnHeartbeatStopped( e )
{
    LogEcho( "VirtualServer_OnHeartbeatStopped: (VMName) " + e );
}
function VirtualServerEvent_OnServiceEvent( e )
{
    LogEcho( "VirtualServer_OnServiceEvent: (Event ID) " + e );
}
function VirtualServerEvent_OnVMStateChange( e, s )
{
    var retVal;
    LogEcho( "VirtualServer_OnVMStateChange: VM " + e + " " +
             "changed to state " + s + "(" + VM_STATE_STRING[ s ] + ")" );
    switch ( s )
    {
        case VM_STATE_RUNNING:
            LogEcho( "Running " + WScript.ScriptFullName +
                     " to monitor VM " + e );
            retVal = objShell.Run(
                        "CSCRIPT.EXE" + " " +
                        "\"" + WScript.ScriptFullName + "\"" + " " +
                        "\"" + e + "\"",
                        VISIBLE,
                        NO_WAIT );
            break;
    }
}

function VirtualMachineEvent_OnConfigurationChanged( e, s )
{
    LogEcho( "VirtualMachine_OnConfigurationChanged: " + strVMName + " " +
             "config " + e + " = " + "\"" + s + "\"" );
}
function VirtualMachineEvent_OnHeartbeatStopped()
{
    LogEcho( "VirtualMachine_OnHeartbeatStopped: " + strVMName );
}
function VirtualMachineEvent_OnRequestShutdown()
{
    LogEcho( "VirtualMachine_OnRequestShutdown: " + strVMName );
    //
    // return true/false to reboot
    //
    return false;
}
function VirtualMachineEvent_OnReset()
{
    LogEcho( "VirtualMachine_OnReset: " + strVMName );
}
function VirtualMachineEvent_OnStateChange( e )
{
    LogEcho( "VirtualMachine_OnStateChange: " + strVMName + " " +
             "changed to state " + e + "(" + VM_STATE_STRING[ e ] + ")" );
    switch ( e )
    {
        case VM_STATE_OFF:
            LogPopup( "Signaled to stop monitoring VM " + strVMName );
            fSignaled = true;

            break;
    }
}
function VirtualMachineEvent_OnTripleFault()
{
    LogEcho( "VirtualMachine_OnTripleFault: " + strVMName );
}

function VirtualDVDEvent_OnMediaInsert( e )
{
    LogEcho( "VirtualDVDEvent_OnMediaInsert: " + strVMName + " " +
             "DVD is bound to " + e );
}
function VirtualDVDEvent_OnMediaEject( e )
{
    LogEcho( "VirtualDVDEvent_OnMediaEject: " + strVMName + " " +
             "DVD is not bound to " + e );
}

HOWTO: Install and Run PHP on IIS7, Part 3

Anonymous — Sat, 24 Jun 2006 13:15:00 GMT

A short while ago, I came out with a small script to properly configure PHP for IIS7. Sure enough, I got asked to make a similar one for IIS6. So, I figure that while I am at it, I might as well cover IIS4, IIS5, and IIS5.1 as well since it is not very different, and put it all into one script so that you can see one classic way to maintain a single automation script which runs version-specific logic.

For the astute reader - no, this script is not minimal, optimal, nor foolproof... it is illustrative. I am deliberately showing several possibilities at the expense of conciseness... but I hope you agree that the information is worth more than the result here...

To correctly configure the PHP Application Mapping prior to IIS7, you MUST provide a tool that can modify the IIS LIST data type.

I have provided such a tool in this blog entry, so you need to copy that script tool into the same directory as you copy this script and name it "ChgList.vbs". If you want to put the tool in a different directory or with a different name, you must modify the FILE_CHGLIST variable in this script appropriately to give the complete pathname.

In addition, I made several little illustrative enhancements:

Debug mode - if you want to merely SEE what is going to execute but NOT execute anything, set the _DEBUG environment variable to 1. Default executes.
Functions vs. Labels - the label :VerifyScripts is treated as a FUNCTION in batch (with ERRORLEVEL as the return value), while the labels :Menu and :Start are treated like GOTO labels
File Existence Validations - depending on the OS/IIS Version, validate the existence of necessary files and scripts
OS BuildNumber detection

Yes, when you write scripts/tools meant to run on multiple platforms and versions, you get constrained into the most reliable least-common-denominator and never get to use the new-fangled stuff. But that's the difference between getting stuff done with compatible software vs experimenting with the bleeding edge... ;-)

In this case, I am using OS BuildNumber, parsed from 'ver', to determine IIS version. If I can constrain this script to IIS5.1 and above (or W2K with REG.EXE from the Resource Kit), I can use REG.EXE to read the installed IIS version from the Registry... but I am not making those assumptions and hence use the OS BuildNumber as a compatible mechanism.

And to be complete - all of these actions require you to run with administrative privileges since you cannot modify the IIS Configuration file(s) without them. Prior to Vista, this means the user must be in the local Administrators group. On Vista with UAC (default), it means that you either run as the built-in Administrator (disabled by default) or run the script with elevated permissions (by saving the script and right-click running as Administrator).

One final disclaimer:

*** Please realize that the script tool simply makes PHP work in one configuration (default). It is not meant to fix or make your arbitrary configuration work ***

In particular, if you run this script more than once, it may not work correctly or configure duplicate settings. For example, APPCMD will fail to configure duplicate handlers and WebServiceExtension entries, iisext.vbs will fail to configure duplicate WebServiceExtension entries, and ChgList.vbs will keep adding duplicate .php ScriptMappings. It is a slippery slope, so I draw the line early.

Also, the script does not go through your ScriptMaps to change the right ones; you can do that yourself. It also does not verify file ACLs, user identities and permissions, etc - it assumes everything is working perfectly and you just need to make the minimal IIS-related configuration to make PHP work.

Sorry... but please understand that I am not in the business of writing and supporting installation programs for other products nor troubleshooting why it does not work on IIS. I am just trying to show how things work, together.

Enjoy.

//David

@IF ?%_ECHO%?==?? ECHO OFF

SETLOCAL
IF ?%_DEBUG%? EQU ?1? (SET DEBUG=ECHO) ELSE (SET DEBUG=)
SET FILE_CHGLIST=chglist.vbs
SET FILE_IISEXT=%SYSTEMROOT%\System32\iisext.vbs
SET CMD_CHGLIST=CSCRIPT //NoLogo %FILE_CHGLIST%
SET CMD_IISEXT=CSCRIPT //NoLogo %FILE_IISEXT%
SET CMD_APPCMD=%SYSTEMROOT%\System32\inetsrv\APPCMD.EXE
SET DIR_PHP_FROM=%SYSTEMDRIVE%\Inetpub\PHP
SET PHP_TYPE=ISAPI
SET PHP_MODULE=IsapiModule
SET PHP_BINARY=php5isapi.dll

REM
REM Determine OS BuildNumber
REM 1381    NT4     IIS4
REM 2195    W2K     IIS5
REM 2600    WXP     IIS5.1
REM 3790    WS03    IIS6
REM Other   Vista   IIS7
REM
FOR /f "tokens=3 delims=.]" %%i IN ('ver') DO SET OS_BUILDNUMBER=%%i
IF "%OS_BUILDNUMBER%"=="" FOR /f "tokens=4" %%i IN ('ver') DO IF "%%i"=="4.0" SET OS_BUILDNUMBER=1381

:Menu
ECHO.
ECHO David.Wang's Sample PHP/IIS Configurator
ECHO Version: June 2006
ECHO OS BuildNumber: %OS_BUILDNUMBER%
ECHO.
ECHO ------------------------------ Summary ------------------------------
ECHO PHP Binaries Dir : %DIR_PHP_FROM%
ECHO PHP Binary Type  : %PHP_TYPE%
ECHO PHP Binary Name  : %PHP_BINARY%
ECHO ---------------------------------------------------------------------

REM
REM Do some basic validations
REM
ECHO.
ECHO Validating inputs...
IF /I ?%PHP_TYPE%? NEQ ?CGI? IF /I ?%PHP_TYPE%? NEQ ?ISAPI? ECHO.&ECHO ERROR: Binary Type MUST be either CGI or ISAPI
FOR %%I IN ( %PHP_BINARY% ) DO (
    IF /I ?%PHP_TYPE%? EQU ?CGI? IF /I ?%%~xI? NEQ ?.exe? ECHO.&ECHO WARNING: Binary Type %PHP_TYPE% requires a CGI EXE binary
    IF /I ?%PHP_TYPE%? EQU ?ISAPI? IF /I ?%%~xI? NEQ ?.dll? ECHO.&ECHO WARNING: Binary Type %PHP_TYPE% requires an ISAPI DLL binary
)
IF /I ?%PHP_TYPE%? EQU ?CGI? SET PHP_MODULE=CgiModule
IF /I ?%PHP_TYPE%? EQU ?CGI? ECHO.&ECHO ERROR: PHP CGI requires modifying cgi.force_redirect to 0 in "%DIR_PHP_FROM%\PHP.INI"
IF /I ?%PHP_BINARY%? NEQ ?php5isapi.dll? IF /I ?%PHP_BINARY%? NEQ ?php-cgi.exe? ECHO.&ECHO WARNING: Unrecognized PHP binary %PHP_BINARY%
Call :VerifyScripts
ECHO.
ECHO Remember to tweak PHP.INI for security and functionality per php.net
ECHO Finished input validation.
ECHO.

SET GO=
SET /P GO=Press 1 to EDIT choices, or ENTER to start IIS modifications:
IF ?%GO%? EQU ?? GOTO :Start

ECHO.
ECHO Press ENTER to accept [%DIR_PHP_FROM%], or provide new value (folder path)
SET /P DIR_PHP_FROM=PHP Binaries Dir:
ECHO Press ENTER to accept [%PHP_TYPE%], or provide new value (CGI or ISAPI)
SET /P PHP_TYPE=PHP Binary Type:
ECHO Press ENTER to accept [%PHP_BINARY%], or provide new value (filename)
SET /P PHP_BINARY=PHP Binary Name:

GOTO :Menu

:Start
REM
REM Start Configuration
REM
ECHO.
ECHO Starting IIS Configuration...
ECHO.
ECHO Copying "%DIR_PHP_FROM%\PHP.INI-Recommended" to PHP.INI...
%DEBUG% COPY /Y "%DIR_PHP_FROM%\PHP.INI-Recommended" "%DIR_PHP_FROM%\PHP.INI"

CALL :VerifyScripts
IF %ERRORLEVEL% EQU 2 GOTO :EOF

REM
REM Use OS Version to distinguish between IIS Versions
REM
REM 1381    NT4     IIS4
REM 2195    W2K     IIS5
REM 2600    WXP     IIS5.1
REM 3790    WS03    IIS6
REM Other   Vista   IIS7
REM
IF %OS_BUILDNUMBER% GTR 3790 (
    ECHO Setting PHP Handler...
    %DEBUG% %CMD_APPCMD% SET CONFIG -section:handlers "-+[name='PHP-%PHP_TYPE%',path='*.php',verb='GET,HEAD,POST',modules='%PHP_MODULE%',scriptProcessor='%DIR_PHP_FROM%\%PHP_BINARY%',resourceType='File']"

    ECHO Adding and Enabling PHP in ISAPI/CGI Restriction List...
    %DEBUG% %CMD_APPCMD% SET CONFIG -section:isapiCgiRestriction "-+[path='%DIR_PHP_FROM%\%PHP_BINARY%',allowed='true',groupId='PHP',description='PHP']"
) ELSE IF %OS_BUILDNUMBER% EQU 3790 (
    ECHO Setting PHP Handler...
    %DEBUG% %CMD_CHGLIST% W3SVC/ScriptMaps "" ".php,%DIR_PHP_FROM%\%PHP_BINARY%,0" /INSERT /COMMIT
    ECHO Adding and Enabling PHP in ISAPI/CGI Restriction List...
    %DEBUG% %CMD_IISEXT% /AddFile "%DIR_PHP_FROM%\%PHP_BINARY%" 1 PHP 1 PHP
) ELSE IF %OS_BUILDNUMBER% LSS 3790 (
    ECHO Setting PHP Handler...
    %DEBUG% %CMD_CHGLIST% W3SVC/ScriptMaps "" ".php,%DIR_PHP_FROM%\%PHP_BINARY%,0" /INSERT /COMMIT
)

ECHO.
ECHO Finished IIS Configuration.
ECHO.
ECHO Test installation using PHP file content of:  ^<?php phpinfo();?^>

ENDLOCAL
GOTO :EOF

REM
REM Sub-routines and Functions
REM
:VerifyScripts
SET ERRORLEVEL=0
IF NOT EXIST "%DIR_PHP_FROM%\%PHP_BINARY%" (
    ECHO.
    ECHO ERROR: PHP Binary "%DIR_PHP_FROM%\%PHP_BINARY%" does not exist!
    ECHO Please first completely extract PHP to "%DIR_PHP_FROM%"
    SET ERRORLEVEL=2
)
IF NOT EXIST "%DIR_PHP_FROM%\PHP.INI" (
    ECHO.
    ECHO ERROR: "%DIR_PHP_FROM%\PHP.INI" does not exist!
    SET ERRORLEVEL=2
)
IF %OS_BUILDNUMBER% GTR 3790 (
    IF NOT EXIST "%CMD_APPCMD%" (
        ECHO.
        ECHO ERROR: Script requires %CMD_APPCMD% for this OS.
        SET ERRORLEVEL=2
    )
)
IF %OS_BUILDNUMBER% EQU 3790 (
    IF NOT EXIST "%FILE_IISEXT%" (
        ECHO.
        ECHO ERROR: Script requires %FILE_IISEXT% for this OS.
        SET ERRORLEVEL=2
    )
)
IF %OS_BUILDNUMBER% LEQ 3790 (
    IF NOT EXIST "%FILE_CHGLIST%" (
        ECHO.
        ECHO ERROR: Script requires %FILE_CHGLIST% for this OS.
        ECHO http://blogs.msdn.com/david.wang/archive/2004/12/02/273681.aspx
        SET ERRORLEVEL=2
    )
)
GOTO :EOF

Anatomy of an Application Pool Crash

Anonymous — Thu, 22 Jun 2006 15:00:00 GMT

Question:

Ok, I read through David Wang's Troubleshooting crashes thing and got the DebugDiag and I am able to reproduce the problem.

If I select Hang, and type in one of the website addresses that we host on this server, the moment the Hang Test starts it brings the entire Application Pool to a stand still. All other sites in other application pools respond perfectly, just not in this application pool.

The moment I terminate the w3wp.exe process for this application pool, IIS respawns a new process and all of a sudden all the sites that were hanging respond instantly.

Any idea of what may be causing this?

Answer:

Actually, what you describe as "causing this" is by-design. Things are working exactly the way it should when you catch a crash with a debugger like DebugDiag. Hmm... this reminds me that I should hurry up and complete that blog entry describing native code debugging of IIS6... but let's get back to the question at hand.

Handling the Unhandled Exception

What is happening is that when you select Hang, DebugDiag attaches a debugger onto the w3wp.exe process and waits for an unhandled exception to happen. An unhandled exception is an exception that is not expected, usually caused by human logical error (i.e. "bug"), and it triggers an immediate execution halt of the process. The raising of the exception basically indicates a crash is ABOUT to happen, which is why a debugger waits on it. You want to debug the process and its state right as the exception happens so that you can figure out the human logical error and fix it.

So, as soon as the unhandled exception happens, the attached debugger seizes control of the process, and NOTHING runs in the process because the debugger preserves the failing state of the process for investigation.

Debugging Application Pools

Depending on the configuration of the Application Pool, when a debugger seizes control of its w3wp.exe, ALL sites/applications using this Application Pool may simply grind to a standstill and not run.

However, options exist for having the Application Pool function while a worker process is debugged, and they include:

Web Garden - other worker processes take up the slack while this worker process gets debugged.
Orphaning - WAS will orphan and "forget" about this w3wp.exe, so new w3wp.exe will be spawned to handle future requests

Of course, these options come with their own unique set of caveats. You will have to evaluate them to determine if your situation benefits. They are not defaults for good reasons.

As soon as you terminate the w3wp.exe (or exit the debugger), the attached debugger also terminates. At this point, WAS detects this as an unexpected crash because WAS waits on all worker processes' handles, and this one just went away unexpectedly (i.e. not due to a triggered process recycle), so it logs it in the Event Log.

Then, depending on health-monitoring metrics (i.e. have not unexpectedly crashed too many times recently), WAS will keep the Application Pool active for HTTP.SYS, meaning that requests continue to queue and spawn new w3wp.exe process as appropriate to handle them.

Conclusion

This is why as soon as you terminate the w3wp.exe, the other sites become responsive. The requests were all queued and placed on-hold because a debugger halted the w3wp.exe that will handle them and the Application Pool is not configured to allow another w3wp.exe to handle them. As soon as the old w3wp.exe and associated debugger are out of the picture, a new w3wp.exe gets spawned to immediately handle the queued requests.

Thus, the "hang" you observe only happens when a debugger is attached to the crashing worker process and the Application Pool is configured in particular ways, and that is by-design. In the "normal" case where a debugger is not attached, the unhandled exception simply bubbles up to either the configured JIT Debugger or Windows itself, who usually just identify it as a crash and immediately terminates the process... and the subsequent requests simply spawn up a new w3wp.exe and continue onwards. You never see a "hang".

So, the IIS6 sequence is pretty darn optimal when it comes to handling code crashing at runtime and then gracefully recovering. It just may not appear that way at first glance.

//David

HOWTO: Install and Run PHP on IIS7, Part 2

Anonymous — Thu, 22 Jun 2006 06:39:00 GMT

A couple of months ago, I wrote a quick and dirty entry on how to install PHP on IIS7. The main purpose of that entry was to explain the details of what was going on as well as cookie-cutter instructions of one way to successfully install PHP on IIS7.

Well, the responses that I have received from that blog entry made me realize that I need to provide something a little more shrink-wapped which does a few more things other than just run the bare minimum... because I was seeing way too many broken custom modifications coming from mistaken assumptions about PHP or IIS7.

Here it is, V2. Just copy/paste the following into a .bat file, right-click run it as elevated Administrator on Vista, and follow the prompted instructions. You should have PHP extracted into a directory of your choice before-hand (I favor and default to %SYSTEMDRIVE%\Inetpub\PHP for many aforementioned reasons; in my examples, I chose "C:\Program Files\P H P" to show it working with long pathnames).

The batch script:

Works with PHP installed wherever, including pathnames with spaces. Just tell it where you installed PHP (sans double quotes and trailing backslash)
Gives choice of whether to use the CGI or ISAPI version of PHP. You do have to give the correct binary name (php5isapi.dll or php-cgi.exe, assuming PHP5), but there are checks for that
Gives warnings and errors if the directory/file does not exist, mismatched binary types, and additional steps you need to do to have a minimally functioning PHP

Now, I am no PHP expert, so I can only give instructions for how to get PHP configured and running on IIS7. Questions about all other PHP-related features (like PHP extensions, integration with mySQL, etc) and how to get them working really belong on a PHP support forum.

Sample Execution Results:

Setting up PHP5 installed at "C:\Program Files\P H P", ISAPI version. Notice the defaults and verification of provided inputs.

David.Wang's Sample PHP/IIS7 Configurator
Version: June 2006

------------------------------ Summary ------------------------------
PHP Binaries Dir : C:\Inetpub\PHP
PHP Binary Type  : ISAPI
PHP Binary Name  : php5isapi.dll
---------------------------------------------------------------------

Validating inputs...

ERROR: PHP Binary "C:\Inetpub\PHP\php5isapi.dll" does not exist!
Please first completely extract PHP to "C:\Inetpub\PHP"

Remember to tweak PHP.INI for security and functionality per php.net
Finished input validation.

Press 1 to EDIT choices, or ENTER to start IIS modifications:1

Press ENTER to accept [C:\Inetpub\PHP], or provide new value (folder path)
PHP Binaries Dir:C:\Program Files\P H P
Press ENTER to accept [ISAPI], or provide new value (CGI or ISAPI)
PHP Binary Type:
Press ENTER to accept [php5isapi.dll], or provide new value (filename)
PHP Binary Name:

David.Wang's Sample PHP/IIS7 Configurator
Version: June 2006

------------------------------ Summary ------------------------------
PHP Binaries Dir : C:\Program Files\P H P
PHP Binary Type  : ISAPI
PHP Binary Name  : php5isapi.dll
---------------------------------------------------------------------

Validating inputs...

Remember to tweak PHP.INI for security and functionality per php.net
Finished input validation.

Press 1 to EDIT choices, or ENTER to start IIS modifications:

Starting IIS7 Configuration...

Copying "C:\Program Files\P H P\PHP.INI-Recommended" to PHP.INI...
Setting PHP Handler...
CONFIG object "system.webServer/handlers" changed
Adding and Enabling PHP in ISAPI/CGI Restriction List...
CONFIG object "system.webServer/security/isapiCgiRestriction" changed

Finished IIS7 Configuration.

Test installation using PHP file content of:  <?php phpinfo();?>

Setting up PHP5 installed at "C:\Program Files\P H P", CGI version. Notice the defaults and reminders as you change to CGI.

David.Wang's Sample PHP/IIS7 Configurator
Version: June 2006

------------------------------ Summary ------------------------------
PHP Binaries Dir : C:\Inetpub\PHP
PHP Binary Type  : ISAPI
PHP Binary Name  : php5isapi.dll
---------------------------------------------------------------------

Validating inputs...

ERROR: PHP Binary "C:\Inetpub\PHP\php5isapi.dll" does not exist!
Please first completely extract PHP to "C:\Inetpub\PHP"

Remember to tweak PHP.INI for security and functionality per php.net
Finished input validation.

Press 1 to EDIT choices, or ENTER to start IIS modifications:1

Press ENTER to accept [C:\Inetpub\PHP], or provide new value (folder path)
PHP Binaries Dir:C:\Program Files\P H P
Press ENTER to accept [ISAPI], or provide new value (CGI or ISAPI)
PHP Binary Type:cgi
Press ENTER to accept [php5isapi.dll], or provide new value (filename)
PHP Binary Name:php-cgi.exe

David.Wang's Sample PHP/IIS7 Configurator
Version: June 2006

------------------------------ Summary ------------------------------
PHP Binaries Dir : C:\Program Files\P H P
PHP Binary Type  : cgi
PHP Binary Name  : php-cgi.exe
---------------------------------------------------------------------

Validating inputs...

ERROR: PHP CGI requires modifying cgi.force_redirect to 0 in "C:\Program Files\P H P\PHP.INI"

Remember to tweak PHP.INI for security and functionality per php.net
Finished input validation.

Press 1 to EDIT choices, or ENTER to start IIS modifications:

Starting IIS7 Configuration...

Copying "C:\Program Files\P H P\PHP.INI-Recommended" to PHP.INI...
Setting PHP Handler...
CONFIG object "system.webServer/handlers" changed
Adding and Enabling PHP in ISAPI/CGI Restriction List...
CONFIG object "system.webServer/security/isapiCgiRestriction" changed

Finished IIS7 Configuration.

Test installation using PHP file content of:  <?php phpinfo();?>

Enjoy.

//David

@IF ?%_ECHO%?==?? ECHO OFF

SETLOCAL
SET DIR_PHP_FROM=%SYSTEMDRIVE%\Inetpub\PHP
SET PHP_TYPE=ISAPI
SET PHP_MODULE=IsapiModule
SET PHP_BINARY=php5isapi.dll

:Menu
ECHO.
ECHO David.Wang's Sample PHP/IIS7 Configurator
ECHO Version: June 2006
ECHO.
ECHO ------------------------------ Summary ------------------------------
ECHO PHP Binaries Dir : %DIR_PHP_FROM%
ECHO PHP Binary Type  : %PHP_TYPE%
ECHO PHP Binary Name  : %PHP_BINARY%
ECHO ---------------------------------------------------------------------

REM
REM Do some basic validations
REM
ECHO.
ECHO Validating inputs...
IF /I ?%PHP_TYPE%? NEQ ?CGI? IF /I ?%PHP_TYPE%? NEQ ?ISAPI? ECHO.&ECHO ERROR: Binary Type MUST be either CGI or ISAPI
FOR %%I IN ( %PHP_BINARY% ) DO (
    IF /I ?%PHP_TYPE%? EQU ?CGI? IF /I ?%%~xI? NEQ ?.exe? ECHO.&ECHO WARNING: Binary Type %PHP_TYPE% requires a CGI EXE binary
    IF /I ?%PHP_TYPE%? EQU ?ISAPI? IF /I ?%%~xI? NEQ ?.dll? ECHO.&ECHO WARNING: Binary Type %PHP_TYPE% requires an ISAPI DLL binary
)
IF NOT EXIST "%DIR_PHP_FROM%\%PHP_BINARY%" (
    ECHO.
    ECHO ERROR: PHP Binary "%DIR_PHP_FROM%\%PHP_BINARY%" does not exist!
    ECHO Please first completely extract PHP to "%DIR_PHP_FROM%"
)
IF /I ?%PHP_TYPE%? EQU ?CGI? SET PHP_MODULE=CgiModule
IF /I ?%PHP_TYPE%? EQU ?CGI? ECHO.&ECHO ERROR: PHP CGI requires modifying cgi.force_redirect to 0 in "%DIR_PHP_FROM%\PHP.INI"
IF /I ?%PHP_BINARY%? NEQ ?php5isapi.dll? IF /I ?%PHP_BINARY%? NEQ ?php-cgi.exe? ECHO.&ECHO WARNING: Unrecognized PHP binary %PHP_BINARY%
ECHO.
ECHO Remember to tweak PHP.INI for security and functionality per php.net
ECHO Finished input validation.
ECHO.

SET GO=
SET /P GO=Press 1 to EDIT choices, or ENTER to start IIS modifications:
IF ?%GO%? EQU ?? GOTO :Start

ECHO.
ECHO Press ENTER to accept [%DIR_PHP_FROM%], or provide new value (folder path)
SET /P DIR_PHP_FROM=PHP Binaries Dir:
ECHO Press ENTER to accept [%PHP_TYPE%], or provide new value (CGI or ISAPI)
SET /P PHP_TYPE=PHP Binary Type:
ECHO Press ENTER to accept [%PHP_BINARY%], or provide new value (filename)
SET /P PHP_BINARY=PHP Binary Name:

GOTO :Menu

:Start
REM
REM Start Configuration
REM
IF NOT EXIST "%DIR_PHP_FROM%\%PHP_BINARY%" (
    ECHO.
    ECHO ERROR: PHP Binary "%DIR_PHP_FROM%\%PHP_BINARY%" does not exist!
    ECHO Please first completely extract PHP to "%DIR_PHP_FROM%"
    GOTO :EOF
)

ECHO.
ECHO Starting IIS7 Configuration...
ECHO.
ECHO Copying "%DIR_PHP_FROM%\PHP.INI-Recommended" to PHP.INI...
COPY /Y "%DIR_PHP_FROM%\PHP.INI-Recommended" "%DIR_PHP_FROM%\PHP.INI" >NUL

PUSHD %SYSTEMROOT%\System32\inetsrv

ECHO Setting PHP Handler...
APPCMD SET CONFIG -section:handlers "-+[name='PHP-%PHP_TYPE%',path='*.php',verb='GET,HEAD,POST',modules='%PHP_MODULE%',scriptProcessor='%DIR_PHP_FROM%\%PHP_BINARY%',resourceType='File']"

ECHO Adding and Enabling PHP in ISAPI/CGI Restriction List...
APPCMD SET CONFIG -section:isapiCgiRestriction "-+[path='%DIR_PHP_FROM%\%PHP_BINARY%',allowed='true',groupId='PHP',description='PHP']"

POPD

ECHO.
ECHO Finished IIS7 Configuration.
ECHO.
ECHO Test installation using PHP file content of:  ^<?php phpinfo();?^>

ENDLOCAL

Be Weary of Stylish Fonts and Commandlines!

Anonymous — Sat, 17 Jun 2006 10:15:00 GMT

I see variations of this common "stylish" mistake all the time... so I will highlight it this one time.

Question:

Hi,

according to
http://www.microsoft.com/technet/prodtechnol/WindowsServer2003/Library/IIS/69a58513-141a-4adb-b6bc-2aaad4ea77b8.mspx?mfr=true

I would like to trace the executing requests in iis6, but when I execute the
logman start W3wpTrace â€“p â€œIIS: Request Monitorâ€ -ets command, I get the
following error:

C:\>logman start W3wpTrace -p "IIS: Request Monitor" -ets
Unknown parameter "-p"
Unknown parameter ""IIS:"
Unknown parameter "Request"
Unknown parameter "Monitor""

The syntax of the command is incorrect.

We are running windows server 2003 web edition Sp1

Thanks.

Answer:

Ok, please don't strangle me, jump off a tall building, or thwap your forehead after reading my explanation of this one (though a "doh" comment or acknowledgement would be nice). :-) Don't feel bad; this one has stumped many people.

I think the URL you meant to reference is this one because the one from the question merely led me to a generic overview page.

In any case, your problem here is that the dash character in front of the "p" and the quote character around "IIS: Request Monitor" are stylized dash and quote characters and NOT the real ASCII dash (0x2D) and quote (0x22) used by logman.exe to delimit parameters and CMD shell to ignore space as parameter separator.

Yes, I know that you copied that commandline directly from the web page and pasted onto the CMD shell, and yes it all LOOKS fine, but believe me, the web page content has stylized quotes and dashes which do not work on the commandline.

Don't believe me? Verify it yourself. If you delete what appears to be the "dash" and "quote" characters and re-type the - and " characters on the keyboard onto the commandline, then I bet the command will work.

Yes, I can work magic! Where's my consultation fee? ;-)

The two tell-tale signs that tell me this "stylish" mistake happened?

The errors mentioned "-p" and ""IIS" as problematic. Since the real ASCII quote character escapes spaces (while the stylized quote does not), the fact that "IIS was considered the incorrect parameter means that the " was not interpreted as the real ASCII quote. Likewise, the real ASCII dash character delimits parameters, and the fact -p was considered incorrect means that - was not interpreted as the real ASCII dash.
The newsgroup post showed â€“p for "-p" and â€œIIS: Request Monitorâ€ for "IIS: Request Monitor", suggesting the stylized quote got converted and EXPOSED on the newgroup. This was the obvious sign.

Yeah, sneaky CMD shell. It uses a font that disguises the stylized dash and quote to look exactly like the ASCII dash and quote. Well, now you know. And knowing is half the battle.

Now, I consider this a bug in the documentation since commandlines should never use stylized quotes and dashes, but sigh, Documentation Writers use Word, which automatically changes things like this all the time... so it is a losing battle for me. Documentation Writers rarely use the commandline, so they have no idea how big of a mistake they are introducing. It is all just words and symbols to them, anyways.

So, I see this stylish mistake happen all the time, and I simply try to tell everyone about it.

//David

HOWTO: Enumerate IIS website and ftpsite configuration (VBScript using ADSI)

Anonymous — Fri, 09 Jun 2006 07:15:00 GMT

I recently got a request to make a script to illustrate how to enumerate useful values from both Web and FTP sites serviced by IIS, so I decided to make some additions to the original script tool located here to allow it to easily enumerate both Web and FTP sites.

The modifications basically illustrate how both the Web and FTP services have consistent programming models and mechanisms to read/change configuration values. I basically only abstracted:

Metabase configuration node from /W3SVC (Web) to /MSFTPSVC (FTP)
ADSI Class name from IIsWebServer (Web) to IIsFtpServer (FTP)
Account for SecureBindings which exist for HTTPS (Web) but not for FTP

And the exact same script now displays both FTP and Web site status. The new syntax is still pretty straight forward - I just added one new parameter to distinguish between querying FTP vs Web sites.

EnumSites.vbs - enumerates status for Websites on this server
EnumSites.vbs server1 - enumerates status for Websites on server1
EnumSites.vbs localhost FTP - enumerates status for Ftpsites on this server

Enjoy,

//David

OPTION EXPLICIT

DIM strServer, strServerType, strServerMetaType
DIM objService

strServer = "localhost"
strServerType = "Web"
strServerMetaType = "W3SVC"

IF WScript.Arguments.Length >= 1 THEN
    strServer = WScript.Arguments( 0 )
END IF

IF WScript.Arguments.Length = 2 THEN
    strServerType = WScript.Arguments( 1 )

    IF UCASE( strServerType ) = "FTP" THEN
        strServerType = "Ftp"
        strServerMetaType = "MSFTPSVC"
    ELSE
        strServerType = "Web"
        strServerMetaType = "W3SVC"
    END IF
END IF

WScript.Echo "Enumerating " & strServerType & "sites on " & strServer & VbCrLf
SET objService = GetObject( "IIS://" & strServer & "/" & strServerMetaType )
EnumServersites objService


SUB EnumServersites( objService )
    DIM objServer, strBindings

    FOR EACH objServer IN objService
        IF objServer.Class = "IIs" & strServerType & "Server" THEN
            WScript.Echo _
                "Site ID = " & objServer.Name & VbCrLf & _
                "Comment = """ & objServer.ServerComment & """ " & VbCrLf & _
                "State   = " & State2Desc( objServer.ServerState ) & VbCrLf & _
                "LogDir  = " & objServer.LogFileDirectory & _
                ""

            ' Enumerate the HTTP bindings (ServerBindings) and
            ' SSL bindings (SecureBindings) for HTTPS only
            strBindings = EnumBindings( objServer.ServerBindings )

            IF strServerType = "Web" THEN
                strBindings = strBindings & _
                EnumBindings( objServer.SecureBindings )
            END IF

            IF NOT strBindings = "" THEN
                WScript.Echo "IP Address" & VbTab & _
                             "Port" & VbTab & _
                             "Host" & VbCrLf & _
                             strBindings
            END IF
        END IF
    NEXT

END SUB

FUNCTION EnumBindings( objBindingList )
    DIM i, strIP, strPort, strHost
    DIM reBinding, reMatch, reMatches
    SET reBinding = NEW RegExp
    reBinding.Pattern = "([^:]*):([^:]*):(.*)"

    FOR i = LBOUND( objBindingList ) TO UBOUND( objBindingList )
        ' objBindingList( i ) is a string looking like IP:Port:Host
        SET reMatches = reBinding.Execute( objBindingList( i ) )
        FOR EACH reMatch in reMatches
            strIP = reMatch.SubMatches( 0 )
            strPort = reMatch.SubMatches( 1 )
            strHost = reMatch.SubMatches( 2 )

            ' Do some pretty processing
            IF strIP = "" THEN strIP = "All Unassigned"
            IF strHost = "" THEN strHost = "*"
            IF LEN( strIP ) < 8 THEN strIP = strIP & VbTab

            EnumBindings = EnumBindings & _
                           strIP & VbTab & _
                           strPort & VbTab & _
                           strHost & VbTab & _
                           ""
        NEXT

        EnumBindings = EnumBindings & VbCrLf
    NEXT

END FUNCTION

FUNCTION State2Desc( nState )
    SELECT CASE nState
    CASE 1
        State2Desc = "Starting (MD_SERVER_STATE_STARTING)"
    CASE 2
        State2Desc = "Started (MD_SERVER_STATE_STARTED)"
    CASE 3
        State2Desc = "Stopping (MD_SERVER_STATE_STOPPING)"
    CASE 4
        State2Desc = "Stopped (MD_SERVER_STATE_STOPPED)"
    CASE 5
        State2Desc = "Pausing (MD_SERVER_STATE_PAUSING)"
    CASE 6
        State2Desc = "Paused (MD_SERVER_STATE_PAUSED)"
    CASE 7
        State2Desc = "Continuing (MD_SERVER_STATE_CONTINUING)"
    CASE ELSE
        State2Desc = "Unknown state"
    END SELECT

END FUNCTION

HOWTO: Access POST form data with ISAPI

Anonymous — Thu, 11 May 2006 09:47:00 GMT

This is a frequently asked question about IIS6 extensibility - how to access the request entity body on the way in - as well as how to configure IIS.

Question:

I want to catch all incoming requests, add some header and watch it when its out. Therefore I used a filter which can't be use alone in IIS 6 cause of the post data and so I added the wildcards. I'm using the same DLL for both.

Since I'm interested in all incoming requests I thought its best to define a global filter and ScriptMap.

What do you think ?

Thanks,

Answer:

I am just going to give the logical answers now. At the moment, I am a little short on time, so I cannot post code samples showing how to do this with ISAPI Filter and Extension (yes, I write and test my code before publishing it publicly - you guys do want functional and correct code samples, not merely code I whipped together on the side, right? ;-) ). However, if you really want the code samples, you can ask via blog entry comments for the code sample, and I will see what I can do and link it in...

There are two ways to access request entity body with ISAPI on IIS6:

ISAPI Filter subscribing to SF_NOTIFY_READ_RAW_DATA and configured as a Global ISAPI Filter, which runs on all requests. It requires:

Run IIS6 in IIS5 Compatibility Mode (you lose tremendous benefits of Application Pools and process/application isolation)
Since SF_NOTIFY_READ_RAW_DATA is a streaming event (i.e. it triggers on every Network read), the ISAPI code must buffer and parse that data (including de-chunking) at an HTTP level to determine what is "request entity body POSTed by an HTML FORM"
In general, this parsing is non-trivial for an ISAPI to do correctly 100% of the time and comes with severe caveats, such as you cannot do this over SSL (request buffering in SF_NOTIFY_READ_RAW_DATA is not compatible with SSL). See this blog entry for more related details

ISAPI Extension calling HSE_REQ_EXEC_URL and configured as a wildcard application mapping. There are no difficult requirements, but since it is an application mapping which operates at a different point in request processing versus ISAPI Filters (see this blog entry for an end-to-end view), you have to be aware of the resulting difference in expected behavior.

Application Mappings are invoked ONCE per request. You do not get a callback on every Network read. Thus, it does NOT offer streaming access to data (i.e. you get exactly once chance to read/manipulate the entity body prior to passing it on to the child request)

This means that to manipulate large entity body, you HAVE to buffer it all in memory before manipulating it, and if you do not want to truncate the entity body, you HAVE to pass the buffer on to the child request on invoking HSE_REQ_EXEC_URL
Since ISAPI Extension operates an an application-level, you know that you get "request entity body POSTed by an HTML FORM" when you read ECB->lpbData for the pre-buffered data or call ReadClient() to get remaining data. No parsing, decrypting, or de-chunking required
This method works fine with SSL
The URL of the request determines the effective Application Mappings (including wildcard) of the request. Thus, it does not matter if you configure a wildcard application mapping at the global W3SVC/ScriptMaps level - if a child node has an overriding ScriptMaps setting which does NOT contain your wildcard application mapping, it will NOT execute for requests whose effective metadata comes from that overriding ScriptMaps setting.

In other words, unlike Global ISAPI Filter which reliably triggers on every request, a "global" wildcard application mapping can be silenced by a child URL whose effective ScriptMaps property does NOT include that wildcard application mapping.

//David

HOWTO: Rename the Computer running IIS6

Anonymous — Mon, 01 May 2006 12:30:00 GMT

Question:

Hi ,

I have two web servers. One web server(w2k3Ent) and IIS 6.0 in a work group and One identical Web Server in the Domain. I want to now rename the Server names of the both, to comply some policy. Will the IIS functionality be affected because the IUSR accounts still be left with old computer names, can I go ahead and rename them as well.

Any Microsoft links and help is appreciated

Thanks,

Answer:

Well, if you are merely interested in Microsoft links on the question, then you should just search for them. I punched in "Rename IIS Computer Name site:support.microsoft.com" in my favorite search engine, and it came up with tons of hits. I trust you know how to do this yourself and sort through the noise - it is a necessary skill in this day and age.

By design, Microsoft links for support/troubleshooting assume the user knows nothing, so they optimize towards keyword/pattern matching which results in some resolution instruction steps that tell you HOW to resolve that pattern with little explanation of WHY. If you pattern match incorrectly, the resolution may not apply and may/not harm you. If you do not follow the instructions correctly, the resolution may not apply and may/not harm you.

What I am going to talk about are the details behind the scenes of what is going on because I trust that when someone understands the dependencies and what is actually going on, they can figure out how to do the right things themselves or even correctly react to unexpected things since everyone's system is unique.

Give a man a fish, and you feed him that night. Teach a man to fish, and he feeds himself forever.

About the Computer Rename...

IIS itself does not care about the name of the user accounts used for purposes like:

Anonymous authentication - no, it does NOT mean that everyone automatically has access. See this blog entry for details.
UNC Vdir Access
Application Pool Identity
COM+ Application Identity

Therefore, IIS definitely functions after renaming the computer. The question is whether all OTHER dependent applications running on or related to IIS are kosher with renaming the computer.

For examples of the hassles, see KB 234142 on renaming a NT4 server running IIS4 (I know, it is not applicable here, but you wanted details, right?)

Or, you may be running bad/broken applications which ASSUME that the username of the IIS anonymous user is based on the machine name (i.e. they assume the anonymous user's name is IUSR_<NewMachineName> instead of reading the value from IIS configuration). These applications will obviously be broken after the computer rename, and you will have to determine how to address that - either fix the application or change the anonymous user's name to match the broken assumption.

Now, if you DECIDE for whatever reason to rename the user accounts used by IIS after renaming the computer (remember, IIS does not need you to do anything), you need to be aware of how Windows user accounts work that can affect IIS behavior:

If you create a NEW user account for use in IIS (as the anonymous user, for example), its SID will be DIFFERENT than the original anonymous user.
- Since files are ACL'd by SID and NOT by username, you will have to re-ACL files/directories EVERYWHERE to re-secure against anonymous access.
- You will also have to change IIS configuration to use the new user name since IIS stores and uses the username and NOT the SID for its user accounts.
If you RENAME the existing user account in Windows to a new name, the SID stays the same, so you do not need to re-ACL anything... but you still need to change IIS configuration to use the new user name.

Some Helpful Scripts

Now, I do not have a script you can run as Administratior which re-ACLs files one username had access to another username... and I am not going to tackle that problem here because that is way outside the scope of IIS. Find your favorite batch/scripting support group for a solution to this one.

However, I do have a script named "RenameIISUser.bat" to do the IIS configuration changes from old name to new name. See the end of this blog entry.

For safety purposes, the script only displays what it will do. You can inspect the output to see if it is OK and then copy/paste the commands yourself, or you can remove SET DEBUG=ECHO to have the script take action.

I also have a script called SyncIISUser.bat that allows you sync user account passwords in IIS configuration assuming you know the username.

So, if you happen to rename the user account AND change its password, you can first run the script at the end of this blog entry to change the username in IIS configuration, and then run the other script to associate the new password with that username in IIS configuration.

For example, suppose you renamed IUSR_MachineName used for Anonymous Authentication to "New User Name" and also changed its password to "New Password". You would run the following commands, in order, to fix your IIS configuration:

RenameIISUser.bat Anonymous "IUSR_%COMPUTERNAME%" "New User Name"
SyncIISUser.bat Anonymous "New User Name" "New Password"

Enjoy.

//David

@IF ?%_ECHO%?==?? ECHO OFF
SETLOCAL
SET CMD_ADSUTIL=CSCRIPT %SYSTEMDRIVE%\Inetpub\AdminScripts\adsutil.vbs
SET DEBUG=ECHO

IF ?%1? EQU ?? GOTO :Help
IF ?%2? EQU ?? GOTO :Help

IF /I ?%1? EQU ?Anonymous? SET PROPERTY_TO_FIND=AnonymousUserName
IF /I ?%1? EQU ?WAM?       SET PROPERTY_TO_FIND=WAMUserName
IF /I ?%1? EQU ?UNC?       SET PROPERTY_TO_FIND=UNCUserName

SET USERNAME_TO_MATCH=%2
SET NEW_PROPERTY_VALUE=%3

FOR /F "usebackq skip=1 tokens=*" %%I IN ( `%CMD_ADSUTIL% FIND %PROPERTY_TO_FIND%` ) DO (
    FOR /F "usebackq tokens=3,* delims= " %%J IN ( `%CMD_ADSUTIL% GET "%%I/%PROPERTY_TO_FIND%"` ) DO (
        IF /I ?%USERNAME_TO_MATCH%? EQU ?%%K? (
            %DEBUG% %CMD_ADSUTIL% SET "%%I/%PROPERTY_TO_FIND%" %NEW_PROPERTY_VALUE%
        )
    )
)

ENDLOCAL

GOTO :EOF



REM
REM Display syntax
REM
:Help
ECHO %~n0 {Anonymous^|WAM^|UNC} "UserName" "New UserName"
ECHO.
ECHO Find all [Anonymous^|WAM^|UNC] user accounts matching "UserName" in
ECHO IIS configuration and change it to "New UserName"
ECHO.

HOWTO: Run Console Applications from IIS6 on Windows Server 2003, Part 2

Anonymous — Fri, 28 Apr 2006 14:30:00 GMT

I finally have enough blog entries about various portions of IIS6 request processing that I can stitch together this meta-blog-entry explaining how it all works together and then apply it towards an issue. You probably want to keep a link to this loaded entry. Anyhow, here goes...

Question:

We currently has IIS 6 installed on a Windows 2003 server, and we are attempting to run some executables through the browser. We have "Scripts and Executables" selected for the web application, and we are currently allowing "All Unknown CGI Extensions" and "All Unknown ISAPI Extensions" under Web Service Extensions during testing.

With this setup we are able to run some executables successfully through a browser, like:

Ping
Hostname
netstat
query session

However other executables are not working:

Net
Dirquota
Filescrn
Fsutil quota

We are getting no value for most of these, except "Fsutil quota" which is returning:

The FSUTIL utility requires that you have administrative privileges

I have confirmed that the browser is using an ID that has administrative privileges by returning the userid it is using. This administrative ID does not have any problem running Fsutil quota on the server directly.

What privileges am I missing? Does something else need to be set up, or is it possible the executables not working are not CGI or ISAPI?

Thanks for any help.

Answer:

Ok, this blog entry is unique in that it is the first time that I am aggregating information from all my prior posts and applying it to resolve a problem. I will NOT explain everything in detail - only the new stuff... for everything else, if I pulled the information from a blog entry, it will be linked in this blog entry somewhere appropriate.

Putting it all together

When it comes to request execution on IIS6, this is how I think about things:

HTTP.SYS parses HTTP requests in kernel mode and sends a digested form to user mode w3wp.exe. Interesting details about this process can be found in this blog entry.
IIS6 in user mode w3wp.exe receives this request and determines the URL namespace (and hence all applicable metadata from configuration that affect the execution of this request - which includes the authentication required, the ScriptMaps applicable for the request, etc)
Then, the authentication process runs to determine the user token used to execute a request.

One of the factors that affect a user token's abilities is the way the user logon was performed (i.e. logon type). In other words, Interactive logon from Remote Desktop/Local Console is different than the Network logon performed by IIS6. This blog entry describes the differences in more detail.

Furthermore, IIS6 can perform different logon types depending on authentication protocol as well as by configuration, though the defaults pretty much work and should not be fiddled with.

So, logon difference alone may affect how FSUTIL.EXE behaves.
In addition to authentication producing a user token, IIS has to determine the correct handler to execute the requested resource (i.e. should the resource be handled as a static file and sent back as-is? or should it go to a CGI/ISAPI to process? or should it produce a courtesy redirect? Etc). This blog entry and this blog entry describes that decision process.
After determining the specific type of handler to execute a request, IIS uses the user token to execute the handler for the request. This blog entry describes how IIS selects the user token to execute the handler.
Additional user code can be run by the handler, which have arbitrary behavior when it comes to user token, privileges, and generated response
The browser client can have automatic behavior which affects the number and sequence of requests made to IIS, as described in this blog entry.

Whew. If you got to here and read through all the associated blog entries, you have just gone through a LOT of details about how IIS6 functions to process requests as well as how it interacts with user identity. Time to put this info to good use and apply it. :-)

The Problem Restated...

Ok, the following details and conclusions all come from the aforementioned blog entries. If you get lost, I suggest you read 'em and read 'em again until you understand it. :-)

The first thing that needs to be clear is HOW you are "running executables through the browser". Since IIS only recognizes static files, CGI/ISAPI, or Scripts (ok, I am simplifying DAV away since it is not involved in this picture), there are two basic ways to run executables:

As a CGI/ISAPI

If you want IIS to directly run the executable as a CGI or ISAPI, then you need to configure "Scripts and Executables" execute permission as well as Web Service Extension for the binary. i.e.

/cgi-bin has "Scripts and Executable" execute permission enabled.
<full-path-to-FSUTIL.EXE>\FSUTIL.EXE is enabled as a Web Service Extension.
You make a request to http://localhost/cgi-bin/FSUTIL.EXE
IIS is going to execute FSUTIL.EXE as a CGI, so it checks it against Web Service Extension. It is allowed.
Thus, IIS will execute FSUTIL.EXE as a CGI EXE using the user token obtained through whatever authentication protocol is negotiated between the browser and server.
The EXE is executed using either CreateProcess() or CreateProcessAsUser() Win32 API call, depending on IIS configuration for CGI execution. If it is CreateProcess(), then FSUTIL.EXE runs with the Process Identity; if it is CreateProcessAsUser(), then FSUTIL.EXE runs with the IIS impersonated identity.
IIS parses the text output from FSUTIL.EXE according to CGI specification and then sends a response back to the client.

If you use the nph- prefix, IIS won't parse the text and just send it back as is. Of course, if you happen to send invalid HTTP response using NPH, the client can complain or behave weirdly...

Via a Scriptmapped CGI/ISAPI

If you want to run executables on IIS from a script (i.e. an ASP, ASP.Net, or PHP page is considered a script resource executed by ASP.DLL, ASPNET_ISAPI.DLL, or PHP-CGI.EXE / PHPISAPI.DLL Script Engine, respectively), then you need to configure "Scripts" execute permission as well as Web Service Extension for the appropriate Script Engine. i.e.

MyScript.asp contains the following content which executes FSUTIL.EXE:

<%
set objShell = Server.CreateObject( "WScript.Shell" )
objShell.Run( "FSUTIL.EXE" )
%>

/cgi-bin has "Scripts" execute permission enabled.
%systemroot%\System32\inetsrv\ASP.DLL is enabled as a Web Service Extension.
/cgi-bin has a ScriptMaps property which associates .asp extension to %systemroot%\System32\inetsrv\ASP.DLL as a Script Engine.
You make a request to http://localhost/cgi-bin/MyScript.asp
IIS identifies ASP.DLL as the ISAPI Script Engine to process the /cgi-bin/MyScript.asp resource and checks it against Web Service Extension. Since it is allowed, it executes ASP.DLL using the user token obtained through whatever authentication protocol is negotiated between the browser and server.

Note: even though the ASP page runs FSUTIL.EXE, FSUTIL.EXE does NOT need to be in Web Service Extension because IIS never runs nor knows about FSUTIL.EXE. IIS only knows it is running ASP.DLL so that is what needs to be enabled as a Web Service Extension.
ASP.DLL will keep the impersonated identity from IIS and parse/execute the script code in MyScript.asp using Windows Scripting Host. objShell.Run() translates into a CreateProcess() Win32 API call, and FSUTIL.EXE runs using the Process Identity (this is how CreateProcess is documented to work!)
FSUTIL output is unknown to ASP (and IIS) unless you capture the output of objShell.Run() somehow and then Response.Write() it so that IIS knows about it.

Ok, back to the Original Problem

At this point, a couple differences should jump out at you:

When you ran FSUTIL QUOTA directly, it was executed by a user token with Interactive logon type. When you ran it from IIS, the user token has Network logon type.
Depending on how you ran the executables, FSUTIL.EXE was either called via CreateProcess() or CreateProcessAsUser(). The critical difference between them is that CreateProcess() implicitly uses the Process Identity to create the new FSUTIL.EXE process, while CreateProcessAsUser() uses the impersonated identity obtained by IIS through authentication.

The Application Pool Identity of the Application Pool servicing the URL namespace that executed the request determines the Process Identity

The authentication protocol negotiated between the browser and server determines the impersonated identity, in a manner consistent with this blog entry.

I do not know if FSUTIL.EXE has special code that cares about the above details. But I do know that CMD.EXE does... so YMMV.

What about the Executables which appear to return Nothing

As for the question of whether the executables "not working" are not CGI/ISAPI... After executing a request handler, IIS expects a valid HTTP response to come back so that it can send it back to the requesting client.

CGI is nothing more than an executable which outputs text which conforms to the CGI specification (this blog entry describes an interest interaction between CGI and HTTP). If the output conforms to specification, IIS sends it back as-is; otherwise, IIS returns a 502 response.

Since IIS6 in WS03SP1 is lax about CGI conformance and no longer requires the status: and content-type headers, if the executable happens to output a CRLF before printing data, that data gets interpreted as response entity by IIS and sent back to the client as-is. The following are some illustrative examples with CRLF clearly marked as \r\n.

NET.EXE Output:

The syntax of this command is:\r\n
\r\n
\r\n
NET [ ACCOUNTS | COMPUTER | CONFIG | CONTINUE | FILE | GROUP | HELP |\r\n
      HELPMSG | LOCALGROUP | NAME | PAUSE | PRINT | SEND | SESSION |\r\n
      SHARE | START | STATISTICS | STOP | TIME | USE | USER | VIEW ]\r\n

PING.EXE Output:

\r\n
Active Connections\r\n
\r\n
  Proto  Local Address          Foreign Address        State\r\n
  TCP    TEST-MACHINE:80        0.0.0.0:80             ESTABLISHED\r\n

As you can see, NET.EXE fails because its CGI output starts off with what looks like an invalid header named "The syntax of this command is:" (it has spaces in it, and no header value) prior to the double CRLF, so it fails to parse correctly and IIS returns a 502 "Bad Gateway" response. Meanwhile, PING.EXE succeeds because it starts off with a CRLF that tells IIS to use a 200 OK response header ahead of the PING output.

Now, if you prefix the resources with NPH- (i.e. nph-netstat.exe or nph-ping.exe), then IIS will NOT process the CGI output and just send it as-is back to the client. That is what NPH means - Non-Parsed Header. Of course, this avoids the 502 response from IIS, but if the output is not proper HTTP, it will now confuse the client, which can have its own arbitrary behavior...

Basically, these console commands are not designed to produce output that conforms to CGI specification, so the fact that they work when invoked as CGI by IIS is purely random, mostly depending on whether the output begins with something that looks like broken HTTP headers or not.

Conclusion

I congratulate you on getting to the end of this marathon of a blog post. I finally got a juicy topic to explain and a lot of blog entries to logically stitch together. :-)

Hopefully, this clears up common confusions surrounding:

IIS request execution logic
User identity used to execute a request
Executing an EXE via CreateProcess() is different than via CreateProcessAsUser(), regardless if you made IIS directly execute it as a CGI or indirectly through a Script
Executing an ISAPI uses the impersonated identity by default, but can be the Process Identity, depending on the ISAPI
How some EXEs magically work as "CGIs" but others fail
How some programs, like CMD.EXE, simply fail depending on whether invoked via CreateProcess() or CreateProcessAsUser()... and maybe FSUTIL.EXE is in the same category

//David

Why Clicking a hyperlink can result in multiple requests to web server(s)

Anonymous — Wed, 26 Apr 2006 15:56:00 GMT

Question:

Dear Experts,

If you could share your opinions or point out some reference links, I do appreciate!

My web server: IIS and SharePoint Portal server 2003

My qestion is: After I click one hyperlink in a page (ASP.NET site) using IE, why there are 3 requests recorded in the IIS log file?

Example:
2006-04-25 20:16:54 (IP) GET /_layouts/1033/Viewer.aspx
contentId=acbdef.htm 80 - (IP)
Mozilla/4.0+(compatible;+MSIE+6.0;+Windows+NT+5.2;+SV1;+.NET+CLR+1.1.4322)
SITESERVER=ID=(server_id) http://localhost/Manager.aspx 401 2
2148074254 1912 15

2006-04-25 20:17:02 (IP) GET /_layouts/1033/Viewer.aspx
contentId=acbdef.htm 80 - (IP)
Mozilla/4.0+(compatible;+MSIE+6.0;+Windows+NT+5.2;+SV1;+.NET+CLR+1.1.4322)
SITESERVER=ID=(server_id) http://localhost/Manager.aspx 401 1 0 2148 15

2006-04-25 20:17:20 (IP) GET /_layouts/1033/Viewer.aspx
contentId=acbdef.htm 80 (domain)\(my_id) (IP)
Mozilla/4.0+(compatible;+MSIE+6.0;+Windows+NT+5.2;+SV1;+.NET+CLR+1.1.4322)
SITESERVER=ID=(server_id) http://localhost/Manager.aspx 302 0 0 835
17671

Thank you very much!

Answer:

The IIS log file contains three entries because the browser actually made three requests on behalf of your single click of a hyperlink. Modern browsers are "smart" and do many things "behind the scenes" to ease the end-user experience.

In other words, you cannot assume that every click of a hyperlink translates into exactly one request to a web server.

Here are same examples of situations where you make one logical click of a hyperlink but the web browser makes multiple requests to web server(s) to satisfy the request.

Consider what happens when you click on a link to...

An HTML page which includes links to Pictures

You may have only clicked on the link to the HTML page, but the browser parses the HTML page, notices 10 pictures in IMG tags, makes 10 additional requests to web server(s) to retrieve those resources, and finally renders the HTML page composed with those pictures.

Similar behavior happens for referenced resources of an HTML page like CSS Stylesheets, client-side Javascript, etc... because the browser must retrieve those URL resources to properly render a given HTML page.

Clearly, to satisfy you making a single click of a hyperlink pointing to a single HTML page, the browser has to make MANY requests on your behalf to give you a desirable user experience of a properly rendered HTML page.

An HTML page that results in a 302 Redirection

You may have only clicked on the link which causes a 302 redirection response to be returned, but do you expect the browser to:

Ask you whether to follow the 302 redirection?
Automatically make a new request to follow the 302 redirection assuming it is "safe"... and continue following the 302 redirections, automatically, until a non-redirection response is retrieved

Most browser implementations default to #2, which means that for a single click, the web browser may automatically make MANY requests on your behalf, trasparently, to resolve through the redirections.

Users expect browsers to follow redirections and render the final result, not repeatedly ask for permission to follow redirections and not render the end result.

An HTML page that requires Authentication

You may have only clicked on the link which requires authentication, but do you expect the browser to:

Show you the 401 response since the URL requires authentication?
Immediately show you the username/password dialog?
Depending on security settings, either automatically attempt authentication via acceptable protocols to the web server or show the username/password dialog, correctly authenticate to the web server, and retrieve and display the secured resource?

Most browser implementations default to #3, which means that for a single click of a hyperlink to a resource that requires authentication, the web browser may automatically make additional requests and interpret their responses to negotiate authentication with the web server in reaction to getting a 401 response with WWW-Authenticate headers.

Users expect browsers to eliminate as many of the username/password popup dialogs as possible by automatically making additional requests to authenticate and retrieve the resource for them wherever it makes configured security sense... and not just repeatedly ask for user credentials to access resources.

Conclusion

In your case, you are observing the fact that:

The /Manager.aspx resource requires authentication
Thus, when you clicked on the link, it made the browser make an anonymous request to the server, and it got a 401.2 response back.

Making an anonymous request is the default behavior for a browser and makes sense. A browser has no way to know WHAT authentication protocols a given website requires BEFORE making that first request (software cannot tell the future... yet ;-) ), so the most obvious choice is to make an anonymous request and see what the web server does in response.
Since the website is in a security zone that allows the web browser to automatically authenticate, the web browser attempts to authenticate using the specified protocol(s) of the web server. My guess is that only Integrated Authentication is enabled on the website containing /Manager.aspx, so you see the second leg of that protocol negotiation sequence and a 401.1 response
Finally, the client successfully authenticates with IIS and IIS starts to execute the /Manager.aspx resource (no more 401 errors logged), but that resource actually ends up sending a 302 redirection ... so a 302 Redirection response is sent back to the client. At this point, the browser probably automatically follows that redirection to something else, and that process continues.

Hopefully, you now see that Modern browsers do many things transparently to make the end-user's life incredibly simple and easy - simple, logical actions that you do with a single click, like browsing a normal HTML page with pictures, or accessing an authenticated URL, or following a 302 redirection... all require additional requests and negotiation logic that the browser transparently performs on your behalf.

Thus, one may be surprised to see that a single logical click of a hyperlink results in multiple requests to servers... but I can only say that it is perfectly normal. :-)

//David