David Wang : IIS

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

WebDAV, Source, and Read Permissions on IIS

David.Wang — Mon, 29 Sep 2008 17:44:00 GMT

Question:

Hello:

With the new WebDAV upgrade in IIS 7.0, there is a permission named "Source". How is the "Source" permission different from "Read" please?

What if "Source" is enabled but "Read" is not??

Answer:

Source and Read permissions control different behaviors.

Read permission controls whether the IIS Static File Handler allows the requested resource to be retrieved (i.e. read) as the response. This action is subject to all behaviors of the IIS Static File Handler, including the MIME Type check.

Source permission, when WebDAV functionality is present (i.e. installed/enabled), controls what happens when the request has the Translate: header. The logic looks like:

If Translate:f AND "Source" is enabled Then
    // Handle with Static File Handler
Else
    // Continue processing normally
End If

Thus, the interesting combination for "Source" happens when:

Execute Permissions is either "Scripts" (or "Scripts and Executables") AND
The requested resource extension has an applicable Application Mapping (or is a DLL/EXE) AND
Request has Translate:f header
"Source" Permission is enabled (along with Read Permission)

In this special combination, the "un-translated" resource (i.e. the script source or DLL/EXE executable binary) gets served as the response by the IIS Static File Handler, INSTEAD of the usual execution of the script or binary to generate the response. This mechanism is how a WebDAV client (via Translate:f) as well as WebDAV server (via Source Permission) cooperatively implement WebDAV behavior. Both client and server have to implement their part in order for WebDAV to work.

Note that this allows WedDAV clients to retrieve of raw source code of an ASPX file even though the virtual directory has Script Execute Permissions and a .aspx Application Mapping, while a normal HTTP client will see response generated by running the ASPX file.

As for what happens when Source is enabled without Read - that is actually an incomplete question.

If Translate:f is present on the request, then a 403.2 is returned because the Static File Handler requires the Read permission and a MIME Type to be able to serve the response
If Translate:f is NOT present on the request, "Source" has no meaning and the request processes normally, as follows...

If the resource is handled by the Static File Handler, then a 403.2 is returned because of the missing Read Permission.
If the resource is handled by an Application Mapping or DLL/EXE, then it depends on the Execute Permission.

If it is None, then it is 403.1 for Application Mapping and 403.2 for DLL/EXE because of the missing Read Permission
If it is Scripts, then Application Mapping executes and 403.2 for DLL/EXE because of the missing Read Permission
If it is Scripts and Executables, then both Application Mapping and DLL/EXE executes

Note that when I mention Application Mapping and DLL/EXE from an IIS6 perspective, it just maps into handlers on IIS7. The logic remains the same. To the astute reader - yes, you can play around with the ordering of handlers and modules on IIS7 to generate any set of behaviors, including the one mentioned above. And yes, I consider all such permutation of behaviors valid because that is the power of a completely extensible platform. You are empowered to shoot anything else, including yourself, in the head.

//David

Managed Modules and ISAPI Filters

David.Wang — Tue, 09 Sep 2008 07:36:00 GMT

Question:

Hello,

I have an isapi filter and a managed module. I need to put both in the same website and I need that the manage module run before the isapi filter. The sequence are: Module--->ISAPI filter. How can I do this?

Answer:

The answer really depends on the filter events that the ISAPI Filter subscribes to.

Unfortunately, no built-in IIS UI or tool displays this information since it is rarely of interest to the user.

However, you can use my tool from here to view the events that an ISAPI Filter subscribes for. To the astute reader - this filter status information is only available AFTER IIS successfully loads an ISAPI Filter (i.e. IIS successfully LoadLibrary(), GetProcAddress() the Filter DLL's GetFilterVersion() exported function, executes it for registered events, and the function returns TRUE to IIS), and depending on IIS version/mode and the type of ISAPI Filter, IIS ends up loading an ISAPI Filter at different times. The history and rationale behind the differences is an entire blog entry all to itself, but the following table is a sufficient summary for now:

IIS Version (Mode)	Global Filter Loads...	Site Filter Loads...
IIS4 / IIS5 / IIS5.1	On Server Startup	When Configured for a Website
IIS6 (IIS5 Compatibility Mode)	On Server Startup	When Configured, on first request to that Website
IIS6 (Worker Process Isolation Mode)	On w3wp.exe Startup	When Configured, on first request to that Website
IIS7 (Classic and Integrated Modes)	Same as IIS6 Worker Process Isolation Mode	Same as IIS6 Worker Process Isolation Mode

It's all about Timing

Now, you may wonder WHY knowing the subscribed filter events affect the answer. As in life and most things in our four dimensional world, it's all about timing, and this situation is no exception.

ISAPI Filter triggers on various events fired by IIS throughout a request's processing, while Managed Modules trigger after only one of those events (and in IIS7 in Integrated Pipeline Mode, Managed Modules trigger on ALMOST all of the events). Thus, if you want the Managed Module to run before the ISAPI Filter, the ISAPI Filter's subscribed events must be limited to those that happen AFTER the Module triggers.

Since Modules trigger pretty late in the request processing, right before response generation and logging, and ISAPI Filters typically trigger early in the request process, to perform either custom authentication, URL rewriting, etc, it is highly likely that what you want to do is impossible on any IIS version - without knowing the exact filter events involved, I cannot be definitive.

The following is a condensed outline of how ISAPI Filter and Managed Modules triggering are ordered:

On IIS4, IIS5, IIS5.1, and IIS6, Managed Modules trigger between the SF_NOTIFY_AUTH_COMPLETE and SF_NOTIFY_SEND_RESPONSE filter events.
On IIS7 in Classic Pipeline Mode, things behave as in IIS6.
On IIS7 in Integrated Pipeline Mode, Managed Modules trigger in-line with all ISAPI Filter events in all Pipeline Modes (Classic and Integrated) because ISAPI Filters are actually just DLLs loaded by the "ISAPI Filter" Module, which acts as a shim to trigger appropriate ISAPI Filter events for the corresponding Module events of the Integrated Pipeline. For example, the "ISAPI Filter Module" subscribes for the OnPreBeginRequest event, which when triggered by IIS will cause it to fire the SF_NOTIFY_PREPROC_HEADERS filter event to all applicable ISAPI Filters for that URL scope.

Conclusion

In general, if your ISAPI filter does NOT subscribe to events earlier than SF_NOTIFY_SEND_RESPONSE, it would be possible for a Managed Module to execute before the ISAPI filter triggers.

You should notice some direct correlations between the Module events of the IIS7 Integrated Pipeline and a merging of the ISAPI Filter events and classic ASP.Net HttpModule events. This is intentional - that is what we meant with the name "Integrated" Pipeline! :-)

The astute reader should note that Managed Modules on IIS7 do not have access to the OnPreBeginRequest module event. Since that event is used by the "ISAPI Filter" Module to trigger the SF_NOTIFY_PREPROC_HEADERS event, this means that even in Integrated Pipeline mode, where Managed Modules trigger in-line with any other module such as the "ISAPI Filter" Module shim, a Managed Module will NOT be able to execute before an ISAPI Filter that subscribes to the SF_NOTIFY_PREPROC_HEADERS event.

Yes, there is a huge story behind why OnPreBeginRequest even exists and why Managed Modules do not have access to that event (and other such global notification events). The blurbs on MSDN simply does not do it justice...

But at long last, here is the long-winded response to it all.

Cheers!

//David

HOWTO: Change IIS User Impersonation Token

David.Wang — Mon, 02 Jun 2008 10:30:00 GMT

Question:

Hi,

We are using our third party component for doing authentication and authorization with IIS6 web server on win2k3 X64 EE. Here we are using IMPERSONATION concept for this integration.

Can anybody describe the required configuration which are needed at IIS 6 for successfully impersonation of users with third party component?

Should we need to set Anonymous authentication explicitely for this kind of configuration?

Answer:

Third party code will not be able to directly impersonate and have IIS use that user token. IIS will:

Strip off the impersonation token after ISAPI Extension returns control to it
Ignore and re-apply IIS's desired impersonation token if ISAPI Filter changed it

Thus, the only way for you to impersonate users with IIS is to change IIS's desired impersonation token. The following are the methods, in no particular order, that ISAPI can change IIS's desired impersonation token and hence control impersonated user. The method you choose depends on your authentication protocol's requirements.

ISAPI Filter - SF_NOTIFY_PREPROC_HEADERS event - change the "Authorization" request header value to be: Basic [base64 encoding of username:password] . Requires Basic Authentication enabled in IIS.
ISAPI Filter - SF_NOTIFY_AUTHENTICATION event - change pszUser and pszPassword fields on HTTP_FILTER_AUTHENT. Remember to SET your values into the provided buffers (and change the cbUserBuff/cbPasswordBuf values) because those are the actual buffers IIS will use. Requires Anonymous or Basic Authentication enabled in IIS.
ISAPI Extension - HSE_REQ_EXEC_URL configured as Wildcard Application Mapping - change hImpersonationToken field on HSE_EXEC_URL_USER_INFO to be the actual NT User Token used by IIS for request impersonation. Requires Anonymous Authentication enabled in IIS.

//David

IIS7 Handlers - accessPolicy and requireAccess

David.Wang — Sun, 01 Jun 2008 11:50:00 GMT

Question:

Hello:

In IIS 7.0, you can edit a handler mapping in the Handler Mappings applet (like for AspClassic), then click Request Restrictions button, Access tab, and select the "Write" permission. But even when the "Edit Feature Permission" in that site/folder is set to Read+Script+Execute, the handler with the "Write" permission is still disabled!

Why?

How do you both keep a handler enabled and also set its request restriction to "Write" at the same time? I've read through all the IIS help files, they're either silent or incorrect on this question.

Answer:

What you want to do is not achievable via the UI. You have to configure the .config file directly.

This looks like a bug in the UI because the "accessPolicy" and "requireAccess" attributes are not aligned.

Here's what the UI is attempting to do:

accessPolicy corresponds to the old "Execute Permissions" set of checkboxes
requireAccess is brand new in IIS7. After we opened up the handler definition in IIS7, it became necessary to add requireAccess so that one could express the concept of "this handler requires script access permissions to execute" so that one could then use accessPolicy to control whether "scripts" can run or not.

Before IIS7, the logical tie between handlers and requireAccess was hardcoded into IIS into statements like:

StaticFileHandler requires Read Permission
All Other Handlers require Script Permission
EXE and DLL require Execute Permission

Starting from IIS7, it is completely wide open. The astute reader should realize that it is possible in IIS7 to do something goofy like set ISAPI Handler to require "no" permissions (instead of Execute) and allow the ISAPI Handler to be executed by IIS Core all the time. However, the actual execution of an ISAPI DLL by the ISAPI Handler is still subject to ISAPI CGI Restriction. This is another example of defense in depth!

What the UI tries to display via the "State" view is: "if you allow only scripts, only these handlers are active". Of course, it is missing the "Write" permission as a filter. Even though the handler require access dialog just added "Write". Thus, when you selected "Write" request restriction for the handler, it makes it impossible for the UI to display as enabled because it does not have "Write" permission as a filter.

I would chalk this up as a bug introduced when WebDAV was added for Windows Server 2008 because that's the main module that needs it. However, if you think about what I just said, this is really easy to work around. Remember, IIS7 does not know what "Execute" permission is (or else the goofy ISAPI Handler configuration would not be possible), so IIS7 does not know what "Write" permission is, either.

Internally, the handler execution logic in IIS7 Core is:

accessPolicy contains "Text1, Text2, Text3".
handler's requireAccess contains "Text3".
requireAccess text is found inside of accessPolicy text. Allow handler execution.

//David

Choice of Development Platform for IIS Modules

David.Wang — Fri, 18 Apr 2008 11:40:00 GMT

Question:

I am starting a new project (ASP.NET 3.5) that will require at least one custom HTTP module. My two development computers are running 32-bit XP Pro/SP2, but I plan to reimage with Vista (already have it ready to be installed). My preference would be to NOT switch to Vista quite yet, but continue the project with my XP Pro systems.

Is it possible or reasonable to proceed with developing the custom HTTP module(s) with my XP Pro system (IIS 5.1) and expect that they will work just fine with IIS7 - and with no changes - when I upgrade to Vista? Or do I really need to switch to Vista before developing these custom HTTP modules?

One module will implement a custom authentication scheme. Another will load an assembly into a separate app domain, execute some code, marshal the results back, stick them into the ASP.NET application state, and then kill that separate app domain.

Answer:

I think the choice of development platform should depend on the features you want to provide and the platforms you plan to support. Personal preference and upgrade schedule should not decide the development platform unless you also want them to decide your potential user/customer base.

Personally, I believe you should develop on Vista, and here is why.

First, IIS7 is finally the release where the development experience on the client OS matches the corresponding server OS. No more hassling over XP Pro and Windows Server 2003 differences in everything related to IIS, from security ACLs, security models, Application isolation between high/medium/low and Application Pools, Web Service Restrictions on CGI and ISAPI, configuration changes, TCP Connection limitations, etc... you get the picture. The same IIS7 server core is on Vista and Windows Server 2008, with the same security model, application isolation, configuration files, etc. Unity at last.

Now, for some more technical reasons. IIS7 has two "Pipeline modes", classic and integrated, that offer completely different behavior/abilities for certain events (authentication being one of them):

Classic mode is supposed to mirror ASP.Net behavior on IIS5x/6.0. With some minor tweaks while reconciling IIS and ASP.Net behavior.
Integrated mode is completely new and represents true managed code extensibility of IIS for the future that mostly matches the native code extensibility of IIS.

I must warn that Classic mode will NEVER match Integrated mode in terms of features and functionality - it exists only for legacy, compatibility reasons. Thus, by definition, the two modes are different.

So, yes, it should be relatively painless to author a Custom Authentication HttpModule in ASP.Net on IIS 5.1 and run it in Classic mode on IIS7. However, that module will likely fail when you switch to Integrated mode, especially for Authentication since it is one of those events whose ordering changes (intentionally, for the better) between Classic and Integrated mode.

In fact, the way you configure that module will be different in IIS7 between the two modes:

In Integrated mode, your simply add a new <module> using the type of your custom auth assembly in <modules>, and optionally add a preCondition to determine if the module should only run on requests involving managed code (i.e. only .aspx, .asmx, etc pages) or all requests (i.e. .html, .xml, .css, .asp, .php, pages).

This is exactly what people tried (in vain) to do with ASP.Net 2.0 on IIS6 but could not, and certainly not with the elegance and compactness of preConditions.

Instead, what one needs to do is the following set of kludges...
In Classic mode, you need configuration that emulates what it took on IIS6 to get similar (but not identical) behavior. This means:
1. *-scriptmap to aspnet_isapi.dll -- this is now a *-<handler> to isapi.dll with aspnet_isapi.dll as the scriptProcessor
2. <httpHandler> for * which derives from DefaultHttpHandler and tweaks some special settings on the HttpContext to cause it to call the HSE_REQ_EXEC_URL ISAPI ServerSupportFunction underneath the covers
3. Order the remaining <httpHandlers> correctly relative to #2 to get reasonable behavior

The astute reader will remind you that I just rushed through a WHOLE lot of details there, which many people have dedicated countless number of hours of pain/frustration/anguish and countless fragments of articles describing how to get an ASP.Net 2.0 Custom Authentication Module to [not] work on IIS 6. And what I just described does not even apply or work on the IIS 5.1 on XP Pro 32bit scenario you just described, unless you intend to only implement Custom Authentication module for ASP.Net pages and static files.

Now, we could have made it easier on the users (but much harder on us) in implementation, but we chose the clean implementation you currently see PRECISELY because it starkly shows how much more elegent Integrated mode is in comparison to classic mode at resolving the issue of managed code extensibility of IIS.

I hope this helps frame the discussion for your future development .

//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: Create Custom Application Pool from Commandline

David.Wang — Thu, 13 Dec 2007 09:15:00 GMT

Question

Hi,

I have a Web site configured to run in a custom application pool. The pool identify is set to a domain user.

I can change the users password using IIS Manager, but is there a command line method ?

Thanks

Answer

You can use the ADSUTIL.VBS tool to do this from the commandline (or steal the code from it for your own custom script).

The properties that you are interested in are all documented on MSDN at Metabase Properties.

The following is an example of how to create a new Application Pool called "MyAppPool" and configure it to use a custom Application Pool identity of domain\username with a password of pass. You can find all the property syntax and valid values in the MSDN. Remember, if you want to use the space character as a parameter, you have to put it in double-quotes since the commandline processor uses space as parameter delimiter.


CSCRIPT %SYSTEMDRIVE%\Inetpub\AdminScripts\ADSUTIL.VBS CREATE w3svc/AppPools/MyAppPool IIsApplicationPool
CSCRIPT %SYSTEMDRIVE%\Inetpub\AdminScripts\ADSUTIL.VBS SET w3svc/AppPools/MyAppPool/WamUserName "domain\username"
CSCRIPT %SYSTEMDRIVE%\Inetpub\AdminScripts\ADSUTIL.VBS SET w3svc/AppPools/MyAppPool/WamUserPass "pass"
CSCRIPT %SYSTEMDRIVE%\Inetpub\AdminScripts\ADSUTIL.VBS SET w3svc/AppPools/MyAppPool/AppPoolIdentityType 3

//David

Internet Explorer is not an HTTP Validator

Anonymous — Fri, 18 Aug 2006 09:45:00 GMT

Question:

I tried a 2nd approach in porting client code from WinInet, and that was to utilize managed C++, as opposed to WinHttp.

After implementing the .NET managed client code...
    HttpWebRequest^ myReq = dynamic_cast<HttpWebRequest^>(WebRequest::Create( strTargetURL ));
    myReq->Method = "POST";
    ...

HttpWebResponse^ HttpWResp = dynamic_cast<HttpWebResponse^>(myReq->GetResponse());

Within the code, GetResponse() throws...

An unhandled exception of type 'System.Net.WebException' occurred in System.dll
Additional information: The server committed a protocol violation. Section=ResponseStatusLine

On the Windows 2003 R2 SP1 server, the ISAPI extension has been simplified to the following...

    DWORD WINAPI HttpExtensionProc(EXTENSION_CONTROL_BLOCK *pECB)
    {
        DWORD dwPageSize, dwBytes;
        char szPage[] = "We're good to go";
        dwPageSize = (DWORD) strlen(szPage);

return ( pECB->WriteClient(pECB->ConnID, (LPVOID) szPage, &dwPageSize, 0) ) ? HSE_STATUS_SUCCESS : HSE_STATUS_ERROR;

}

Any help would be apreciated enabling more clients whether they are WinHttp or .NET clients, the ability to POST to the ISAPI extension.

Thanks,

Answer:

Actually, the problem you observe comes from your ISAPI Extension DLL. It is actually sending an invalid HTTP response without an entity body, and the APIs correctly complain. Let me explain.

Problem Restated

My understanding of your facts:

You have an ActiveX DLL using WinInet which successfully POSTs to an ISAPI Extension
You have a Windows Service which fails to POST to the exact same ISAPI Extension using either WinHttp or .NET Client

Based on that information, I hypothesize either:

The ISAPI Extension or other Server Side ISAPI Filter is doing something wrong, but WinInet ignores or covers it up while WinHttp/.NET Client correctly fail
The ISAPI Extension or other Server Side ISAPI Filter is doing something wrong, but IIS/ISAPI/Windows Networking stack does a special hack for WinInet but not others like WinHttp or .NET Client

Personally, I am more inclined to believe that the former is happening. The latter is simply way too convoluted, difficult, and fragile. I am not a Conspiracy Theorist - I believe in straight-forward explanations for computer issues. :-)

Problem Confirmed

In this case, I am certain that #1 applies for several reasons:

The simplified ISAPI Extension does not send a proper HTTP Response
"WinInet accepts the response" does NOT mean "it is a proper HTTP response"

In other words, the ISAPI Extension is doing something bad, but WinInet (and IE, which uses WinInet) tries very hard to succeed and hence overlooks such errors.

<rant>

Yes, it gives a great user experience to see IE render all sorts of improper HTTP responses and HTML pages, but it also gives false user confidence in the correctness of such HTTP/HTML.

But, I do not think the problem is solely with Microsoft/IE but rather shared with the authors of such bad HTTP and HTML. Computer users expect things to magically "work", so someone has to make the broken things be "less broken" and "work". This expectation results in a viscious cycle:

If IE refused to render the broken HTTP/HTML but some other browser did, then users think that IE is broken instead of blaming the incorrect web page. Since IE renders more broken HTTP/HTML, web page developers have less motivation to author correctly... and IE will be punished for refusing to render that future broken web page.

How whacky is that!?! Of course, Users have no idea that this is going on - they only see rendered pages and think everything is alright - when in fact the browser and web developers are slowly diverging from published specifications, increasing their maintenance costs, and causing headaches on the development side of things. And all because we are trying to shield the End User...

This downside is what hits you right now. In this case, you see a response from the ISAPI Extension when browsed with Internet Explorer or WinInet, so you probably think the ISAPI is perfectly simple and correct. Hence, you think that Microsoft has a bug somewhere that either causes WinHttp or .NET Client to not work with the ISAPI, or that there is some devious hack somewhere to favor WinInet. Bad Microsoft.

But in reality, it is the ISAPI Extension that is broken, and you were fooled by the tainted validations with Internet Explorer and WinInet.

</rant>

Troubleshoot with Trusted Tools

This is why I only use the following basic but trusted tools to debug HTTP Client/Server issues... because they have no alternative agenda to mislead anyone:

WFetch to make raw requests and observe raw responses
Network Monitor to tap the network and observe raw requests and responses
Native Code Debuggers to observe programmatic state inside a process

I simply do not trust debugging/troubleshooting with anything else. If I have to use something like IE/FireFox, I always treat its answer with a heavy grain of salt and not as Gospel.

Resolution

If you change the ISAPI code to send the following response, then I believe it should work for WinHttp and .NET Client as well as WinInet:

char szPage[] = "HTTP/1.1 200 OK\r\n"
                "Content-Type: text/html\r\n"
                "Content-Length: 16\r\n"
                "\r\n"
                "We're good to go";

Basically, your ISAPI only sent back "We're good to go" as an HTTP response, and that is improperly formatted. The fix makes the ISAPI send back a proper HTTP response, so the client APIs like WinHttp or .NET Client should just work.

Conclusion

Powerful APIs, like ISAPI Extension and ISAPI Filter, directly control the data stream to/from IIS. Thus, they can either positively augment IIS behavior or negatively manipulate IIS to misbehave.

In particular, they differ from programming environments like ASP, ASP.Net, or PHP, which removes some of the power to protect the user from generating common HTTP mistakes. One just has to be aware of the guard-rails and training wheels.

Like many things, it is just a tradeoff that one needs to be aware of; nothing right or wrong.

//David

CGI Failing with 404 on IIS

Anonymous — Wed, 12 Jul 2006 11:59:00 GMT

Yes... software can have bugs, even if you test it. :-)

Question:

I have written a C EXE that I have renamed as 'prog.cgi'. I have tested it successfully on IIS 5.0 on Windows 2000 Server and IIS 6.0 on Windows 2003 Server.

The program is invoked like so:

http://mysite.com/cgi-bin/prog.cgi

During the first run the program creates a dynamic page that includes a form with ACTION="prog.cgi". It sets a hidden state variable so that the program can keep track of which screen to display. Very basic stuff.

I have a customer who has installed the file on their server (IIS 5.0 on W 2000 Svr), and they can get the first screen, but they get a 404 when they submit the form from the first screen with ACTION="prog.cgi".

It looks to me like a relative path vs. absolute path issue. In the code, I used the ACTION as the program name only, as opposed to making it "/cgi-bin/prog.cgi" to allow customers to install it in and directory they saw fit on their system.

I have read about absolute and relative paths in various places but they all seem to be referring to the file system and not the virtual path like the issue seems to be here.

I did not see this in any of my testing on any version of Windows with IIS or OmniHTTPD, or Unix (with Apache).

Thanks for any ideas.

Answer:

Yup, your issue is with relative path resolution of URIs by browsers, and it is caused by a bug in your CGI. Yes, I know you say that you have successfully tested the CGI on a number of platforms, but at the end of the day, your customer demonstrated a flaw within your CGI despite your testing, so you simply have to accept and fix it.

To allow your customers to install your CGI wherever they want, I suggest that you fix your CGI to use the Server Variable (or CGI environment variable) SCRIPT_NAME to generate the correct URI for ACTION. SCRIPT_NAME resolves back to the URL that invoked the CGI, wherever the user installed it. So, for a first run URL of http://mysite.com/cgi-bin/prog.cgi , SCRIPT_NAME returns /cgi-bin/prog.cgi... which should correctly resolve as ACTION for your subsequent PostBack.

If you just use "prog.cgi" as ACTION, you are assuming that the BROWSER resolves /cgi-bin as the base directory of the request and makes the PostBack to /cgi-bin/prog.cgi. If the browser does not resolve /cgi-bin as the base directory, the PostBack likely results in a 404. You can verify this with the server log file corresponding to the failed PostBack that results in a 404.

//David

IIS, Security Templates, and Anonymous Authentication

Anonymous — Sun, 02 Jul 2006 01:40:00 GMT

Sigh... security is never black and white, is it? :-)

Question:

Environment: IIS6.0 Windows 2003 R2, Windows 2003 level domain. Everything
standard.

1) The Microsoft security guide for IIS6.0 says that the IUSR account needs Log on Locally rights.
2) The Microsoft group policy Enterprise security template for Member Servers removes this right. When the policy is applied, anonymous access is broken.
3) The Member Server template is a baseline for all servers. You are supposed to ADD a Web Server template on top for web servers.
4) The Security Policy guide specifies that if you apply the more restrictive Limited Functionality template to Member Servers, then you need to move the web server out of that OU so the policy is not applied. By inference you don't do this for the standard Enterprise policy template.
5) Question: do the policy templates contradict the security guide?
6) Question: I read somewhere that if you enable Basic authentication, you no longer need the Log on Locally right for anon. Is that correct?
7) Question: I have enabled Advanced Digest authentication with the UseDigestSSP property set in the metabase. This works fine. I read something about this disabling subauthentication, and I recognise that subauthentication is something to do with the way IIS handles the IUSR account. Could it be that with Advanced Digest enabled, the IUSR account no longer works unless it has Log on Locally rights?

Thanks very much,

Answer:

Yup, the security guide and policy template appear to contradict, but it is perfectly alright because security is relative, not absolute. This subtle point is often overlooked. If security was absolute, then any monkey can apply rules to achieve security... but then what would you and I be doing? :-)

The IIS Security Guide simply says what is needed by IIS
The Group Policy Template can say anything else because its scope is different
The templates and guides just give you requirements and information. You have to assemble and decide which is more pertinent and important for your situation and reconcile the differences

Put it another way (extreme example for illustration):

Security and Functionality are at odds
You want the most secure and functional web server
You may read somewhere that the most secure server is one that is not powered
You may read somewhere else that the most functional server is one that is powered on
Yes, the two statements contradict, but is either wrong? Nope. You just have to figure out the right balance given the information and your requirements.

Enablement of authentication protocols does not have direct correlation with required user privileges. Likewise, enablement of SubAuthentication does not have direct correlation with required user privileges. The LogonMethod used to obtain the user token has direct correlation with the "Log on Locally" user privilege.

See these links for more information:

Yes, that's a lot of information. What do you really need to know between Anonymous, Basic, Advanced Digest, "Log on locally" privilege, and SubAuthentication?

Anonymous and SubAuthentication:

Anonymous Authentication's "let IIS control anonymous user's password" feature requires SubAuthentication
SubAuthentication requires LocalSystem as the process identity
If IIS runs with process identity of LocalSystem, it can obtain a user's token, without knowing the password, by using SubAuthentication
On IIS5, IIS runs as LocalSystem and can use SubAuthentication to offer the default feature of "let IIS control anonymous user's password" for the configured anonymous user. This is strictly a "usability" feature so that you do not have to remember to synchronize anonymous user password so Anonymous Authentication should not fail to logon (of course, other failures can still happen with Anonymous Authentication...)
On IIS6, IIS runs as Network Service and does NOT offer the "let IIS control anonymous user's password" feature by default (it is not even in the UI) since it would require SubAuthentication and LocalSystem. This a security feature for IIS6, and you have to remember to synchronize anonymous user credentials now. OS upgrade preserves the configuration; otherwise, you have to do extra work to tweak and configure the "let IIS control anonymous user's password" feature

Anonymous, Basic, and "Log on Locally":

Anonymous and Basic Authentication obtain user tokens compliant with LogonMethod
On IIS5, LogonMethod is INTERACTIVE and thus requires its users to have "Log on locally" privilege
On IIS6, LogonMethod is NEWORK_CLEARTEXT and thus does NOT require its users to have "Log on locally" privilege. But of course you can configure LogonMethod to be INTERACTIVE and require "Log on locally" privilege

Anonymous and Advanced Digest

Anonymous Authentication's "let IIS control anonymous user's password" feature requires SubAuthentication
SubAuthentication requires LocalSystem as the process identity
Advanced Digest does not require SubAuthentication
Standard Digest requires SubAuthentication

Conclusion

All of these boil down to security improvements in IIS6 vs IIS5:

By changing default LogonMethod to NETWORK_CLEARTEXT, anonymous and basic authentication users do not need "Log on locally" privilege
By removing SubAuthentication, IIS worker process can run as the less privileged "Network Service" instead of privileged LocalSystem

These changes allow Anonymous, Basic, and Advanced Digest Authentication protocols to function while requiring fewer privileges of the user and process, but there are caveats - you now have to synchronize anonymous user credentials (see this blog entry for a common failure pattern), and legacy applications that require INTERACTIVE may fail.

As always, the choice is up to you as to which is preferable. :-)

//David

HOWTO: Diagnose One Cause of "%1 is not a valid Win32 application" on IIS6 on 64bit Windows

Anonymous — Tue, 27 Jun 2006 13:10:00 GMT

Question:

I have a new development server that i put together on a Windows 2003 64 bit machine. I also have SQL Server 2005 and Developers Studio 2005 and 2003 installed on this machine. I have executed the "Enable32bitAppOnWin64 1" command, as per the instructions when installing Developers Studio. I am unable to server ASPX pages from this machine. I started with a "500 - Internal Server Error" but am now getting a "%1 is not a valid Win32 application. "

Under Application Configuration, ASPX is pointed to C:\WINDOWS\Microsoft.NET\Framework64\v2.0.50727\aspnet_isapi.dll.

I have tried Googling this but haven't found anything.

Any suggestions?

Thanks!

Answer:

Back in this blog entry, I looked at one of many ways to arrive at the dreaded "503 Service Unavailable" - trying to load a 32bit ISAPI Filter DLL into a 64bit w3wp.exe fails because Windows WOW64 compatibility requires DLL and its loading process to have the same bitness. This question arrives at the problem the other way - trying to load a 64bit ISAPI DLL into a 32bit w3wp.exe - which also fails the same OS requirement of the DLL matching bitness of its loading process.

To make a long story short - there is a compatibility shim which triggers that recommendation for VS.Net 2003 Installation on 64bit Windows. However, there is a 50/50 chance that its recommendation is wrong - it totally depends on what you are trying to do and the order you do them - but we cannot change the .Net 1.1 installer, nor control the order of your installation, nor read your mind. So, we basically had to choose between 50% of users getting errors without ever seeing a warning dialog, or 50% getting errors after following instructions in the warning dialog - and we chose the latter.

In your case, you managed to configure IIS6 to:

Run worker processes in 32bit WOW64 mode (that's what Enable32bitAppOnWin64 1 means) AND
Load 64bit ASP.Net ISAPI DLL into those processes (that's what C:\WINDOWS\Microsoft.NET\Framework64\v2.0.50727\aspnet_isapi.dll means)

The bitness mismatch causes the "%1 is not a valid Win32 application." error when IIS6 tries and fails to load the ASP.Net ISAPI DLL handler.

My guess is that you first installed VS.Net 2005 (which set up 64bit Application Mappings), then installed VS.Net 2003 (which requires Enable32bitAppOnWin64), and upon following the advice, IIS6 stopped working.

The correct solution? It completely depends on what you are trying to accomplish and what applications you want to run, and there may be no solution. Here are some relevant decision points:

If you want to run ASP.Net 1.1, you MUST run worker processes in 32bit WOW64 mode because it only has a 32bit DLL.
If you want to use FPSE to deploy VS Solutions, you MUST run worker processes in 32bit WOW64 mode because it only has a 32bit DLL (through an ironic twist, there is a 64bit FPSE for Itanium but NOT 64bit FPSE for x64 - and I disregard Itanium availability/usage). Using UNC to deploy VS Solutions is bitness agnostic.
ASP.Net 2.0 can run in either 32bit or 64bit mode. You just have to remember to run the aspnet_regiis.exe from the appropriate Framework/Framework64 folder so that it can tweak the Application Mappings appropriately.
If you are using additional components/applications, make sure their bitness matches that of your configured worker process.
You switch worker process bitness with Enable32bitAppOnWin64, and it is done globally across IIS6.

In general, my advice for 64bit Windows users is that if you want to run 64bit Windows, then only run 64bit applications on it, especially server applications like ASP.Net. Otherwise, you have to learn and understand how a 32bit server application triggers the WOW64 compatibility layer and its interactions with an IIS6 worker process. If you do not do this, you will end up with either 500s or 503s - there are literally gazillion ways to trigger issues and hence very few documented solutions. I cannot document all those problem instances, but I CAN give you advice on how it works and how failures come about - so that you can apply the advice to your situation and determine what is right for you.

Good luck.

//David

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

IIS Configuration Woes with ADSI, WMI, and VBScript

Anonymous — Sat, 24 Jun 2006 09:55:00 GMT

You know, configuration of IIS can be quite confusing, with the various interfaces, paradigms, and programming languages. However, if you keep your wits about you, you can avoid the common pitfalls...

Question:

I need help with the following code. I'm trying to create an application pool to set as the default pool when I make a website. When I create my web site with this code the application pool is set to <Invalid App Pool>, but then in the drop down choice box the <DefaultAppPool> and my <MyCrazyAppPool> exist. I need to have <MyCrazyAppPool> set as the default though when the site is created, not <InvalidAppPool>.

All help is greatly appreciated. Thank you for your time.

Set objSite = objWMIService.Get("IIsWebServerSetting='" & strSitePath & "'")
Set objVirtualDirectory = objWMIService.Get("IIsWebVirtualDirSetting='" & strSitePath & "/ROOT'")

' Application Pool Creation

strAppPool = "MyCrazyAppPool"
Set objAppPools = GetObject("IIS://localhost/W3SVC/AppPools")
Set objAppPool = objAppPools.Create("IIsApplicationPool", strAppPool)
objAppPool.SetInfo

' Assign the Pool to the Site
objVirtualDirectory.AppPoolID = strAppPool
objVirtualDirectory.AppFriendlyName = "me app"
objVirtualDirectory.SetInfo

Answer:

Actually, your code illustrates several common problems and misconceptions. Let me dissect them all and hopefully you see what you need to do to fix them.

Problem 1: ADSI vs WMI

Your script snippet actually uses two completely different programming paradigms, with non-interchangeable features and syntax, to configure IIS - ADSI and WMI.

strAppPool = "MyCrazyAppPool"
Set objAppPools = GetObject("IIS://localhost/W3SVC/AppPools")
Set objAppPool = objAppPools.Create("IIsApplicationPool", strAppPool)
objAppPool.SetInfo

The above snippet uses ADSI, as evidenced by the GetObject() function call using the IIS:// namespace. It is using generic ADSI Create() syntax to create a new Application Pool and then save it with the generic ADSI SetInfo() syntax. One reason ADSI modifications are not immediately persisted but allow batched persistence by SetInfo() is to give the programmer fine-control over the balance between performance and immediacy. If you want immediate persistence, then call SetInfo() yourself as frequently as you want; if you want batched behavior, batch and then call SetInfo().

Set objSite = objWMIService.Get("IIsWebServerSetting='" & strSitePath & "'")
Set objVirtualDirectory = objWMIService.Get("IIsWebVirtualDirSetting='" & strSitePath & "/ROOT'")

' Assign the Pool to the Site
objVirtualDirectory.AppPoolID = strAppPool
objVirtualDirectory.AppFriendlyName = "me app"
objVirtualDirectory.SetInfo

The above code snippet uses WMI, as evidenced through the objWMIService being created against the root/MicrosoftIISv2 namespace (which you did not show but must have done). It is using the generic WMI Get() syntax to retrieve a vdir definition for the website. However, it is attempting to use the ADSI SetInfo() syntax to save the changes, which is not supported. WMI uses Put_() to save the changes.

The syntax error prevents your customization of AppPoolId from ever persisting.

One way to correct it is to use the correct WMI function to commit the change:

objVirtualDirectory.Put_()

The other way is to use ADSI (where strSitePath looks like "w3svc/1"):

objVirtualDirectory = GetObject( "IIS://localhost/" + strSitePath + "/ROOT" )

Problem 2: Error Checking

Now, we know that objVirtualDirectory is a WMI object, SetInfo() is an ADSI syntax, and the WMI object does not support the SetInfo() syntax and its execution should trigger an error that breaks the VBScript. However, your description indicates that you did not notice this syntax error at all - you noticed that the AppPoolId was not customized (because the syntax error prevented the change from persisting). Where did the syntax error go?

Well, you must have specified something like: On Error Resume Next somewhere earlier in the script in the applicable scope, which you did not show. This directive tells VBScript to silently ignore all errors, including the syntax error which prevented AppPoolId customization from persisting, and simply continue execution at the following statement. This leads to the script seemingly run to completion, yet the expected change did not happen. This is the classic problem of using "On Error Resume Next".

Thus, it should be clear that if you EVER use "On Error Resume Next", you need to diligently Clear and check the return code of the Err object after every function invocation to detect errors and handle errors yourself Yes, it can be a hassle and make the code look ugly and complicated, but you have no choice - you need to write code without glaring bugs and flaws. You can make it look prettier and simpler by writing better error handling abstractions (or just using a language with better error handling semantics).

Sure, by adding "On Error Resume Next", your VBScript stopped bailing execution due to errors, but just because code continues running does NOT mean that everything worked and the fatal errors masked by "On Error Resume Next" were ok. In reality, computers simply don't know how to fix them, so they simply stay silently masked until you DO notice the problem (like the AppPoolId change failing to show up).

Conclusion

Yeah, this nasty masking of errors and general hassle in handling errors really bug me about VBScript. It's all nice and easy assuming nothing bad happens, but when you need to do something REAL like handle real-world errors, you need to use "On Error Resume Next". And at that point, I end up writing VBScript code that exactly mirrors defensive C/C++ style code... by which point I am really not scripting... and then I get annoyed with the language itself. But that's another topic for another day. :-)

//David