HTTP.sys Manageability in Windows Vista and Longhorn Server

Microsoft Corporation

Published: 4/2/07

Author: Eric Han, Corey Plett

Editor: Scott Somohano

Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 2007 Microsoft Corporation. All rights reserved.

Microsoft, Windows, Windows NT, Windows Server, and Active Directory are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

All other trademarks are property of their respective owners.

Contents

HTTP.sys Manageability in Windows Vista and Windows Server Code Name "Longhorn"

With Windows Vista™ and Windows Server® Code Name "Longhorn", IT professionals will find improved manageability functionality for the HTTP Server API component, in addition to the HTTP logging support introduced in Windows Server 2003. To diagnose and configure the HTTP Server API component, IT professionals can use three tools:

 New ETW tracing functionality

 Performance Counters

 Netsh configuration commands

The HTTP Server API enables applications to communicate over HTTP and includes SSL support so that applications can exchange data over secure HTTP connections. The HTTP Server API is supported on the Windows Server 2003 family, and on Windows XP SP2.

HTTP.sys Manageability Scenarios

The following scenarios provide examples of how these tools can help IT professionals diagnose and solve issues related to the HTTP Server API (HTTP.sys) component. The tools used in these examples are available in Windows Vista and Windows Server "Longhorn".

Scenario 1: HTTP Timeout example using ETW Tracing and Netsh commands

The scenarios in this document are examples of using the HTTP Server API component's manageability tools. These examples are not meant to suggest specific configuration changes.

Through ETW tracing, the flow of data through the HTTP Server API component can be inspected to diagnose problems. For example, users of a web application may see error messages in their browser that a web page cannot display. On the server hosting the web application, the IT professional also sees a connection timeout entry within the HTTP Error Log, as shown in Figure 1 below. The HTTP Error Log can be found in the following directory: %windir%\System32\LogFiles\HTTPERR\.

Software: Microsoft HTTP API 2.0 Version: 1.0 Date: 2006-10-10 00:02:02 Fields: date time c-ip c-port s-ip s-port cs-version cs-method cs-uri sc-status s-siteid s-reason s-queuename 2006-10-10 00:06:07 127.0.0.1 49473 127.0.0.1 80 - - - - - Timer_ConnectionIdle -

Figure 1: HTTP Error Log for Timeout

Generating an ETW Trace Report

To generate an ETW trace report for the HTTP Server API component, run the steps below from the command prompt. In this example, the trace is run on the server since it is hosting the web application.

The steps below generate a trace called httptrace.etl and then convert the trace into a CSV file called httptrace.csv. As shown below, the ETW provider for the HTTP Server API is called Microsoft-Windows-HttpService. The 0xFFF command-line option indicates that all ETW events for this provider should be captured.

Generate an ETW Trace Report

1. Start ETW trace for HTTP Server API component: logman.exe start httptrace -p Microsoft-Windows-HttpService 0xFFFF -o httptrace.etl -ets 2. Reproduce the issue so that it can be captured in the trace. In this example, access the web application from a client machine, resulting in the “page cannot be displayed” message being shown on the client. 3. Now that the issue has been reproduced, stop the trace: logman.exe stop httptrace -ets 4. Convert the report into CSV format: tracerpt.exe httptrace.etl -of CSV -o httptrace.csv 5. View the trace report. An excerpt from a CSV trace is shown below in Table 1.

Viewing the Trace and Diagnosing

The resulting CSV file for traces can be viewed in Excel or any tool that supports the CSV format. Table 1 below shows excerpts from a sample trace file (httptrace.csv). In the trace report, the “Level” column shows an entry with a value of “3”, which corresponds to a warning in ETW. The HTTP Server API component follows the ETW Levels defined in the following article: (http://go.microsoft.com/fwlink/?LinkId=87056). The ETW levels include:

 1 - Critical

 2 - Error

 3 - Warning

 4 - Informational

 5 - Verbose

With this warning, the event type (Type column) reports "ConnTimedOut". In the subsequent columns for the ConnTimeOut event, the specific timer that expired is reported as "Timer_ConnectionIdle". Note the column with the "Timer_ConnectionIdle" entry is not included in the table for the sake brevity and to avoid excerpting noncontiguous columns.

Event Name	Type	Event ID	Version	Channel	Level
EventTrace	Header	0	2	0	0
Microsoft-Windows-HttpService	ChgUrlGrpProp	28	0	16	4
Microsoft-Windows-HttpService	AddUrl	31	0	16	4
Microsoft-Windows-HttpService	ChgReqQueueProp	30	0	16	4
Microsoft-Windows-HttpService	ChgUrlGrpProp	28	0	16	4
Microsoft-Windows-HttpService	ChgSrvSesProp	29	0	16	4
Microsoft-Windows-HttpService	ChgSrvSesProp	29	0	16	4
Microsoft-Windows-HttpService	ConnConnect	21	0	16	4
Microsoft-Windows-HttpService	ConnIdAssgn	22	0	16	4
Microsoft-Windows-HttpService	RecvReq	1	0	16	4
Microsoft-Windows-HttpService	Parse	2	0	16	4
Microsoft-Windows-HttpService	LogFileWrite	51	0	16	4
Microsoft-Windows-HttpService	ConnCleanup	24	0	16	4
Microsoft-Windows-HttpService	ConnTimedOut	53	0	16	3

Table 1: Excerpts from a Sample Trace Report for a Timer Issue

In this example, the expiration (ConnTimeOut event) of the header timer (Timer_ConnectionIdle) is the reason end-users see the “page cannot be displayed” message in their web clients. A potential reason for the timeout may be that Web clients are sending slowly due to slow connections. To address this issue, the timeout value can be adjusted through Netsh commands.

Adjusting Timeout through Netsh and Verifying the Solution

The Netsh commands for HTTP listed below allow an IT professional to view and configure setting values on the HTTP Server API component. Changes through Netsh HTTP commands affect all server applications hosted by the HTTP Server API component for that machine. These changes persist across restarts of the component and reboots of the machine. The Netsh HTTP commands are available in Windows Vista and Windows Server "Longhorn" and replace the Windows 2003 Resource Kit's HttpCfg.exe tool when running on Windows Vista and Windows Server "Longhorn". In this scenario, we will adjust a timeout value and then verify the solution. Timers exist in the HTTP Server API component to ensure availability and protect against overconsumption by a misconfigured or malicious user. Adjusting timers from default values should be carefully evaluated against a potential DoS attack.

In this example, the web clients are behind a slow network connection, resulting in the Timer_ConnectionIdle ETW event. After consideration of the cause of the timeouts and balancing with the impact on the server's load, the decision is made to increase the timeout values to a value of 240 seconds. You can view and then configure the timer with the following procedure.

Configure the idle connection timer (Timer_ConnectionIdle) via Netsh

1. On the server, open an elevated command window and run the steps below to view and configure the timeout value. A screenshot of the Netsh HTTP command is shown in Figure 2 below. 2. Show the current timeout values: Netsh http show timeout 3. Configure the Timer_ConnectionIdle timeout value. In this example, the value is changed to 240 seconds: Netsh http add timeout timeouttype=idleconnectiontimeout value=240

Figure 2: Netsh HTTP command window

After configuring the timeout value, rerun the ETW diagnosis steps. If the error condition is corrected, the ETW trace should no longer show a timeout with an ETW level of “3” for the connection idle timer.

Scenario 2: Parser example using ETW tracing

To generate an ETW trace report for the HTTP Server API component, run the steps as shown above in Generating an ETW Trace Report, but reproduce the error specific to this scenario. In this example, access the web application from a client machine, resulting in the “400 bad request” message being shown on the client. These steps are run on the server since it is hosting the web application.

Viewing the Trace and Diagnosing

The resulting CSV file for traces can be viewed in Excel or any tool that supports the CSV format. Table 2 below shows excerpts from a sample trace file (httptrace.csv). In the trace report, the “Level” column shows an entry with a value of “2”, which represents an error. As noted above, the HTTP Server API component follows the ETW Levels defined in the following article (http://go.microsoft.com/fwlink/?LinkId=87056).

The ETW levels include: 1 Critical; 2 Error; 3 Warning; 4 Informational; 5 Verbose.

With this error, the event type (Type column) reports "ParseRequestFailed". In the subsequent columns for the ParseRequestFailed event, we see an "InvalidHost" entry. This entry means that the identified host in the HTTP Request is incorrect, according the HTTP protocol. Note the column with the "InvalidHost" entry is not included in the table for the sake of brevity and to avoid excerpting noncontiguous columns.

To fix this parsing issue, the web client should be corrected to be compliant with the HTTP RFC.

Event Name	Type	Event ID	Version	Channel	Level
EventTrace	Header	0	2	0	0
Microsoft-Windows-HttpService	AddUrl	31	0	16	4
Microsoft-Windows-HttpService	ConnConnect	21	0	16	4
Microsoft-Windows-HttpService	ConnIdAssgn	22	0	16	4
Microsoft-Windows-HttpService	RecvReq	1	0	16	4
Microsoft-Windows-HttpService	ParseRequestFailed	52	0	16	2
Microsoft-Windows-HttpService	LogFileWrite	51	0	16	4

Table 2: Excerpts from a Sample Trace Report for a Parsing Issue

Scenario 3: Performance Counters

Performance counters measure quantities of information or data, according to the number, size, duration, and rate of data being requested or received. You should not expect to get a list of details from a counter, such as a list of error messages. Instead, use performance counters to get quantities, such as the number of error message since startup or the rate at which error messages are being generated.

Performance Counters for HTTP.sys

In Windows Vista and Windows Server "Longhorn", HTTP.sys has the following performance metric counters to help you with monitoring, diagnosing, and capacity planning for Web servers:

The HTTP Server API component has the following performance counters to help you with monitoring, diagnosing, and capacity planning for Web servers:

 HTTP Service Counters:

 Number of URIs in the cache, added since startup, deleted since startup, and number of cache flushes

 Cache hits/second and Cache misses/second

 HTTP Service URL Groups:

 Data send rate, data receive rate, bytes transferred (sent and received)

 Maximum number of connections, connection attempts rate, rate for GET and HEAD requests, and total number of requests

 HTTP Service Request Queues:

 Number of requests in queue, age of oldest requests in queue (age of the last request in the queue)

 Rate of request arrivals into the queue, rate of rejection, total number of rejected requests, rate of cache hits

With these new performance counters, metrics can be viewed through the Diagnostic Console snap-in or obtained through the Performance Counters API.

Accessing Performance Counters

1. Type perfmon at the command prompt to start the Performance Diagnostic Console. 2. Select Performance Monitor in the tree control and then open the Add Counters by clicking + 3. From Add Counters select from the three Performance Counters sets: HTTP Service, HTTP Service Request Queues, or HTTP Service Url Groups. 4. To view counters from the HTTP Service Request Queues and HTTP Service Url Groups counter sets, select instance(s) and click Add, and then click OK. To view the HTTP Service counters, select the counter set in the left pane and click Add.

Note

Only one instance of the HTTP Server API counters exists per machine, as these counters represent the component-wide state. With instances of Url Group performance counters, the instance ID (for the performance counter) will match the Url Group ID. The Url Group ID can be viewed by running netsh http show servicestate. With instances of Request Queues performance counters, the instance name corresponds to Request Queue Name. The Request Queue Name (if one exists) can be shown by the same netsh http show servicestate. However, some server applications may have unnamed Request Queues that cannot be matched to a performance counter instance ID.

Netsh commands for HTTP

You can use the Netsh commands for HTTP context to query and configure HTTP.sys settings and parameters.

You can run these commands at the command prompt in the Windows Vista operating system or at the command prompt for the netsh http context. For these commands to work at the command prompt in Windows Vista, you must type netsh http before typing commands and parameters as they appear in the syntax below. To view help for a command at the command prompt, type CommandName/?, where CommandName is the name of the command.

To view the command syntax, click a command:

 add iplisten

 add sslcert

 add timeout

 add urlacl

 delete cache

 delete iplisten

 delete sslcert

 delete timeout

 delete urlacl

 flush logbuffer

 show cachestate

 show iplisten

 show servicestate

 show sslcert

 show timeout

 show urlacl

add iplisten

Specifies an IPv4 or IPv6 address to be added to the IP listen list.

Syntax

add iplisten [ address=] IPAddress

Parameters

Term	Description
[ address=] IPAddress	Specifies the IPv4 or IPv6 address to be added to the IP listen list.

Remarks

Adds a new IP address to the IP listen list. This does not include the port number. The IP listen list is used to scope the list of addresses to which the HTTP service binds. "0.0.0.0" means any IPv4 address and "::" means any IPv6 address.

Examples

add iplisten address=fe80::1

add iplisten address=1.1.1.1

add iplisten address=0.0.0.0

add iplisten address=::

add sslcert

Adds a new Secure Sockets Layer (SSL) server certificate binding and the corresponding client certificate policies for an IP address and port.

Syntax

add sslcert [ipport=]IP Address:port

[certhash=]string

[appid=]GUID

[certstorename=]string

[verifyclientcertrevocation={enable|disable}]

[verifyrevocationwithcachedclientcertonly={enable|disable}]

[usagecheck={enable|disable}]

[revocationfreshnesstime=]u-int

[urlretrievaltimeout=]u-int

[sslctlidentifier=]string

[sslctlstorename=]string

[dsmapperusage={enable|disable}]

[clientcertnegotiation={enable|disable}]

Parameters

Term	Description
[ipport=]IP Address:port	Specifies the IP address and port for the binding.
[certhash=]string	Specifies the SHA hash of the certificate. This hash is 20 bytes long and specified as a hexadecimal string.
[appid=]GUID	Specifies the GUID to identify the owning application.
[certstorename=]string	Specifies the store name for the certificate. Defaults to MY. Certificate must be stored in the local computer context.
[verifyclientcertrevocation={enable|disable}]	Turns on or turnsoff verification of revocation of client certificates.
[verifyrevocationwithcachedclientcertonly={enable|disable}]	Turns on or turns off usage of only cached client certificate for revocation checking.
[usagecheck={enable|disable}]	Turns on or turns off usage check. Default is enabled.
[revocationfreshnesstime=]u-int	Specifies the time interval to check for an updated certificate revocation list (CRL). If this value is 0, then the new CRL is updated only if the previous one expires. (in seconds)
[urlretrievaltimeout=]u-int	Specifies the timeout interval on attempts to retrieve the certificate revocation list for the remote URL (in milliseconds).
[sslctlidentifier=]string	Lists the certificate issuers that can be trusted. This list can be a subset of the certificate issuers that are trusted by the computer.
[sslctlstorename=]string	Specifies the store name under LOCAL_MACHINE where SslCtlIdentifier is stored.
[dsmapperusage={enable|disable}]	Turns on or turns off DS mappers. Default is disabled.
[clientcertnegotiation={enable|disable}]	Turns on or turns off negotiation of certificate. Default is disabled.

Example

add sslcert ipport=1.1.1.1:443 certhash=0102030405060708090A0B0C0D0E0F1011121314 appid={00112233-4455-6677-8899-AABBCCDDEEFF}

add timeout

Adds a global timeout to the HTTP.sys service.

Syntax

add timeout [timeouttype=]{idleconnectiontimeout|headerwaittimeout}

[value=]u-short

Parameters

Term	Description
[timeouttype=]{idleconnectiontimeout|headerwaittimeout}	Specifies the type of timeout for setting.
[value=]u-short	Specifies the value of the timeout (in seconds). If value is hexadecimal, then add the prefix 0x.

Examples

add timeout timeouttype=idleconnectiontimeout value=120

add timeout timeouttype=headerwaittimeout value=0x40

add urlacl

Reserves the specified URL for non-administrator users and accounts. The discretionary access control list (DACL) can be specified by using a Windows NT account name with the listen and delegate parameters or by using a security descriptor definition language (SDDL) string.

Syntax

add urlacl [url=]string

[[user=]string

{[[listen={yes|no}] [delegate={yes|no}]] | [sddl=]string}

Parameters

Term	Description
[url=]string	Specifies the fully qualified URL.
[user=]string	Specifies the user or user group name.
[listen={yes|no}]	Specifies one of the following values:  yes: Allows the user to register URLs. This is the default value.  no: Denies the user from registering URLs.
[delegate={yes|no}]	One of the following values:  yes: Allows the user to delegate URLs.  no: Denies the user from delegating URLs. This is the default value.
[sddl=]string	Specifies the SDDL string that describes the DACL.

Examples

add urlacl url=http://+:80/MyUri user=DOMAIN\user

add urlacl url=http://www.contoso.com:80/MyUri user=DOMAIN\user listen=yes

add urlacl url=http://www.contoso.com:80/MyUri user=DOMAIN\user delegate=no

delete cache

Flushes the entire URL cache or deletes entries per specified URI.

Syntax

delete cache [url=]string [[recursive=]{yes|no}]

Parameters

Term	Description
[url=]string	Required. Specifies the fully qualified URL.
[recursive=]{yes|no}	If yes, removes all entries under the specified URL.

Examples

delete cache url=http://www.contoso.com:80/myresource/ recursive=yes

delete cache

delete iplisten

Specifies an IPv4 or IPv6 address to be deleted from the IP listen list.

Syntax

delete iplisten [ address=] IPAddress

Parameters

Term	Description
[ address=] IPAddress	Specifies the IPv4 or IPv6 address to be deleted from the IP listen list.

Remarks

Deletes an IP address to the IP listen list. This does not include the port number. The IP listen list is used to scope the list of addresses to which the HTTP service binds. "0.0.0.0" means any IPv4 address and "::" means any IPv6 address.

Examples

delete iplisten address=fe80::1

delete iplisten address=1.1.1.1

delete iplisten address=0.0.0.0

delete iplisten address=::

delete sslcert

Deletes SSL server certificate bindings and the corresponding client certificate policies for an IP address and port.

Syntax

delete sslcert [ipport=]IP Address:port

Parameters

Term	Description
[ipport=]IP Address:port	Specifies the IPv4 or IPv6 address and port for which the SSL certificate bindings will be deleted.

Examples

delete sslcert ipport=1.1.1.1:443

delete sslcert ipport=0.0.0.0:443

delete sslcert ipport=[::]:443

delete timeout

Deletes a global timeout and makes the HTTP.sys service revert to default values.

Syntax

delete timeout [timeouttype=]{idleconnectiontimeout|headerwaittimeout}

Parameters

Term	Description
[timeouttype=]{idleconnectiontimeout|headerwaittimeout}	Specifies the type of timeout setting.

Examples

delete timeout timeouttype=idleconnectiontimeout

delete timeout timeouttype=headerwaittimeout

delete urlacl

Deletes a reserved URL.

Syntax

delete urlacl [url=]string

Parameters

Term	Description
delete urlacl [url=]string	Specifies the fully qualified URL to be deleted.

Examples

delete urlacl url=http://+:80/MyUri

delete urlacl url=http://www.contoso.com:80/MyUri

flush logbuffer

Flushes the internal buffers for the log files.

Syntax

flush logbuffer

show cachestate

Lists all resources and their associated properties that are cached in the HTTP response cache or displays a single resource and its associated properties.

Syntax

show cachestate [[url=]string]

Parameters

Term	Description
show cachestate [[url=]string]	Fully qualified URL. If unspecified, implies all URLs. The URL can also be a prefix to registered URLs.

Examples

show cachestate url=http://www.contoso.com:80/myresource

show cachestate

show iplisten

Lists all IP addresses in the IP listen list. The IP listen list is used to scope the list of addresses to which the HTTP service binds. "0.0.0.0" means any IPv4 address and "::" means any IPv6 address.

Syntax

show iplisten

show servicestate

Shows a snapshot of the HTTP service.

Syntax

show servicestate [[view=]{session|requestq}] [[verbose=]{yes|no}]

Parameters

Term	Description
[[view=]{session|requestq}]	View snapshot of HTTP service state based on server session or request queues.
[[verbose=]{yes|no}]	View verbose information showing property information too.

Examples

show servicestate view=session

show servicestate view=requestq verbose=yes

show sslcert

Lists SSL server certificate bindings and the corresponding client certificate policies for an IP address and port.

Syntax

show sslcert [ipport=]IP Address:port

Parameters

Term	Description
[ipport=]IP Address:port	Specifies the IPv4 or IPv6 address and port for which the SSL certificate bindings will be displayed. Not specifying an ipport lists all bindings.

Examples

show sslcert ipport=[fe80::1]:443

show sslcert ipport=1.1.1.1:443

show sslcert ipport=0.0.0.0:443

show sslcert ipport=[::]:443

show sslcert

show timeout

Shows the timeout values of the service (in seconds).

Syntax

Show timeout

show urlacl

Lists DACLs for the specified reserved URL or all reserved URLs.

Syntax

show urlacl [url=]string

Parameters

Term	Description
[url=]string	Specifies the fully qualified URL. If unspecified, implies all URLs.

Examples

show urlacl url=http://+:80/MyUrl

show urlacl url=http://www.contoso.com:80/MyUrl

show urlacl

Formatting legend

Format	Meaning
Italic	Information that the user must supply
Bold	Elements that the user must type exactly as shown
Ellipsis (...)	Parameter that can be repeated several times in a command line
Between brackets ([])	Optional items
Between braces ({}); choices separated by pipe (|). Example: {even|odd}	Set of choices from which the user must choose only one
Courier font	Code or program output

25

---