microsoft press internet information services iis 70 resource kit phần 4 potx

Chapter 7: Using Command Line Tools 213

To learn more about using Appcmd to lock and unlock sections, see Chapter 4. To learn

about using fine-grained configuration locking, see the section titled “Granular Configuration

Locking” in Chapter 4.

Managing Configuration Backups

Appcmd provides a Backup object that you can use to create backups of global configuration

files and to restore them. Creating a backup can be as simple as using the Add verb on the

Backup object as shown here.

appcmd add backup

Issuing this command creates a new backup with a name based on the current date and time.

The format is as follows: YYYYMMDDThhmmss (where YYYY is the four-digit year, MM is the

two-digit month, DD is the two-digit day, T is a delimiter between the date and time, hh is the

two-digit hour, mm is the two-digit minute, and ss is the two-digit second). If you prefer to pro￾vide your own name for the backup, you can simply add it to the end of your Appcmd request.

appcmd add backup "MyServerBackup"

By issuing the List verb against the Backup object, you can see your newly created backup.

appcmd list backup

To restore a configuration backup, use the Restore verb and the name of the backup you want

to restore. For instance, to restore a backup named “MyServerBackup”, type the following.

appcmd restore backup "MyServerBackup"

Note The backup files are stored as subdirectories of the %SystemRoot%\System32\

Inetsrv\Backup folder with the name given to the backup instance. When you create a new

backup, administration.config and applicationHost.config are among the files that are stored.

You can learn more about managing IIS 7.0 configuration backups in the section titled

“Backing Up Configuration” in Chapter 4.

Working with Applications, Virtual Directories, and

Application Pools

Appcmd can be an effective way to create and configure many of the key Web server objects,

including Web sites, applications, virtual directories, and application pools. The Appcmd Site,

App, Vdir, and Apppool objects provide a convenient mechanism for managing these objects,

even though you can perform most of the tasks that these objects expose by using the Config

object to directly edit configuration files.

214 Part III: Administration

The Site object provides a convenient way to enumerate Web sites, as well as to create new

Web sites and set configurations on existing Web site definitions. For example, you create a

Web site in a single step by using the Add Site command.

ppcmd add site /name:MySite /bindings:http/*:81: /physicalPath:c:\mysite

This command creates a new Web site, listening on port 81, and automatically creates a root

application and a root virtual directory pointing to C:\mysite. You can also create the Web site

separately by omitting the physicalPath parameter and then create applications and virtual

directories for the Web site by using the Add App and Add Vdir commands respectively.

You can use the List Sites object to list the Web sites on the server or find specific Web sites by

attributes or URL. For example, to determine which Web site is configured to serve requests

to http://localhost:83, you can use the following syntax.

appcmd list sites http://localhost:83

To find all sites that are currently stopped, you can use the following syntax.

appcmd list sites /state:Stopped

You can also manually start and stop Web sites by using the Start Site and Stop Site commands.

Find more details on how to use Appcmd to list, create, and configure Web sites and virtual

directories in Chapter 9.

Similar to Web sites, you can also create, list, and manipulate applications, virtual directories,

and application pools. Find more information about how to create and configure applications

and application pools in Chapter 10, “Managing Applications and Application Pools.”

Working with Web Server Modules

The Module object in Appcmd provides convenient methods for installing, enabling, and

managing Web server modules. Again, you can perform the majority of these tasks by using

the Config object to directly edit configuration files.

For example, you can install native modules by using the Install Module command.

appcmd install module /name:MyNativeModule /image:c:\mymodule.dll

You can use the same command to add new managed modules.

appcmd add module /name:MyManagedModules /type:MyModules.MyManagedModule

You can also manage which modules are enabled on your Web server or application by adding

or deleting modules.

Find details about how to use Appcmd to install, enable, and configure Web server modules

in Chapter 12, “Managing Web Server Modules.”

Chapter 7: Using Command Line Tools 215

Inspecting Running Worker Processes and Requests

Viewing and changing configuration data is not the only thing that you can do with Appcmd.

You can also inspect the run-time state of the Web server by listing the currently executing

worker processes and even requests.

Listing Running IIS Worker Processes

You can use the List Wp command to list all currently running IIS worker processes. This

command uses the following syntax.

appcmd list wp [pid] [/apppool.name:string] [/wp.name:string]

The List Wp command supports the use of the Process ID (PID) as an identifier to locate the

specified IIS worker process. Additionally, you can specify the application pool name by using

the /apppool.name parameter to list IIS worker processes belonging to a specific application

pool.

For example, to list all IIS worker processes that are currently running, you can use the

following syntax.

appcmd list wp

The output of this command includes the PID of each IIS worker process, as well as the

application pool to which it belongs.

WP "3284" (applicationPool:DefaultAppPool)

Listing Currently Executing Requests

In addition to viewing the currently running worker processes, you can also look deeper into

the Web server operation by listing currently executing requests. This can give you a snapshot

of current system activity, as well as show which requests have been executing for a long time

(thus possibly indicating a problem).

You can list the currently executing requests by using the List Request command. For example,

to list all currently executing requests on the server, you can use the following syntax.

appcmd list requests

The output contains all requests that were executing in all IIS worker processes at the moment

of query.

REQUEST "fd00000180000004" (url:GET /wait.aspx?sleep=10000, time:4072 msec,

client:localhost, stage:ExecuteRequestHandler,

module:ManagedPipelineHandler)

216 Part III: Administration

As you can tell, each displayed request object contains quite a bit of information about the

currently executing request, including:

■ The request URL and verb.

■ The time that the request has spent executing.

■ The client issuing the request.

■ The pipeline stage that the request is currently in, and the module that is currently

executing.

You can use the time information—as well as the current pipeline stage and module data—to

effectively troubleshoot request hangs and performance degradation problems, by pinpointing

the exact URL and in some cases even the module that is causing the slowdown.

In addition to listing all requests on the server, which can be an expensive operation and may

give too much information to be useful in a lot of scenarios, you can use a variety of filters

to list only the relevant requests. To see how to do this, let’s look at the detailed syntax of the

List Requests command.

appcmd list requests [identifier] [/site.name:string] [/wp.name:string]

[/apppool.name:string] [/elapsed:uint] [/url:string] [/verb:string]

[ClientIp:string] [/stage:string] [/module:string]

This command supports the parameters listed in Table 7-6.

Table 7-6 Parameters for the List Requests Command

Parameter Description

identifier The request identifier to look up a specific request multiple times.

The request identifier is a randomly generated string similar to

“fd00000180000004” that is shown when requests are displayed in

Appcmd.

site.name The site name for which to display currently running requests.

wp.name The IIS worker process PID for which to display currently

running requests. This improves the efficiency of the query

because only the specified IIS worker process is polled.

apppool.name The application pool name for which to display currently

running requests. This improves the efficiency of the query

because only the IIS worker processes for the specified

application pool are polled.

elapsed The minimum elapsed time in milliseconds for requests to show.

Requests that have taken less time to execute are not returned. This

may increase the efficiency of the query by returning fewer requests.

Using the elapsed attribute is an effective way to determine hung

requests.

Chapter 7: Using Command Line Tools 217

Working with Failed Request Tracing

The Trace object in Appcmd provides a convenient way to enable and use the Failed Request

Tracing (FRT) feature in IIS 7.0 to diagnose server problems.

Note For more information about using Failed Request Tracing, see Chapter 16, “Tracing

and Troubleshooting.”

You can use the Trace object to do the following:

■ Turn FRT on and off for each Web site

■ Manage FRT tracing rules for any URL

■ Search for and inspect FRT log files

Turning on Failed Request Tracing

To turn on FRT for a particular URL, you must first enable the feature for the Web site. You can

do this with Appcmd by using the Configure Trace command.

appcmd configure trace SiteName /enablesite

The /enablesite parameter enables the use of FRT for the site specified by the SiteName

identifier (this identifier can also be a URL, in which case Appcmd will turn on tracing for

the corresponding site). For example, to enable FRT for the “Default Web Site” site, use the

following syntax.

appcmd configure trace "Default Web Site" /enablesite

url The URL of the request. You can specify the exact URL or

wildcard expressions on URLs to show requests only to specific URLs

(note that the URL may contain the query string as well).

clientip The IP of the requesting client. This can be in both IPv4 and IPv6

format depending on the client’s connection.

stage The request processing stage. Use to show only requests that are

currently executing in the specified request processing stage. For a

list of valid request processing stages, see the section titled “The

Request Processing Pipeline” in Chapter 12.

module The name of the module. Use to show only the requests that are

being processed by the specified module.

Table 7-6 Parameters for the List Requests Command

Parameter Description

218 Part III: Administration

Note Be sure to disable FRT when not using it with the /disablesite parameter.

You can also use the /disablesite parameter to turn off FRT for the Web site when you are not

using it. Doing so allows you to leave the Failed Request Tracing rules configured for URLs

on the site and simply toggle tracing on or off at the Web site level.

Creating Failed Request Tracing Rules

To produce FRT trace logs, you need to create rules that indicate the failure conditions that

trigger the trace to be logged, as well as which trace events should be captured. To do this, you

use the /enable parameter of the Configure Trace command. This has the following syntax.

appcmd Configure Trace <URL> /enable [/path:string] [/areas:string]

[/verbosity:level] [/timetaken:timespan] [/statuscodes:string]

This command supports the parameters listed in Table 7-7.

When you use the /enable command without specifying the /path parameter, it creates an

entry that matches all requests to the URL with path set to “*”. For example, we can use the

following syntax to quickly enable FRT tracing using all default configurations.

appcmd configure trace "Default Web Site/" /enable

Table 7-7 Parameters of the Configure Trace Command

Parameter Description

path The URL path for which the rule is enabled. This can be an extension in

the form of “*.extension” or “*” to indicate all requests. If not specified,

defaults to “*”.

areas The list of providers and their areas to trace. This is in the form of

“provider/area1,area2:verbosity,…”, where the area list and verbosity are

optional for each provider entry. If not specified, this uses all registered

providers and their subareas at “Verbose” verbosity level.

verbosity The verbosity level of an event that causes the request to meet the failure

definition and generate the trace log. You can use this to generate trace

logs if an event of Warning or Error verbosity is encountered. Allowed

values are Ignore, CriticalError, Error, and Warning. If not specified, the

default is Warning.

timetaken The execution time (in time span format) that causes the request to

meet the failure definition and generate the trace log. You can use this

parameter to generate trace logs only if the request exceeds the specified

execution time, to capture slow or hung requests. If not specified, defaults

to one minute.

statuscodes Response status codes that cause the request to meet the failure defini￾tion and generate the trace log. This is in the form of “status.substatus,…”,

where substatus is optional. You can use this to generate the trace log

for requests that fail with specific error response codes. If not specified,

defaults to “500,400,401,403”.

Chapter 7: Using Command Line Tools 219

This generates the following configuration for the system.webServer/tracing/traceFailedRequests

configuration section.

<tracing>

<traceFailedRequests>

<add path="*.aspx">

<traceAreas>

<add provider="ASPNET"

areas="Infrastructure,Module,Page,AppServices" />

</traceAreas>

<failureDefinitions statusCodes="404" />

</add>

<add path="*">

<traceAreas>

<add provider="WWW Server"

areas="Authentication,Security,Filter,StaticFile,CGI,Compression,Cache,RequestNotifications,

Module" verbosity="Verbose" />

<add provider="ASP" areas="" verbosity="Verbose" />

<add provider="ISAPI Extension" areas=""

verbosity="Verbose" />

<add provider="ASPNET"

areas="Infrastructure,Module,Page,AppServices" verbosity="Verbose" />

</traceAreas>

<failureDefinitions timeTaken="00:01:00"

statusCodes="500,400,401,403" verbosity="Warning" />

</add>

</traceFailedRequests>

</tracing>

Note that the rule uses a path of “*” to apply to all requests at or below the URL at which

the configuration is set, specifies all the registered trace providers and areas with the Verbose

verbosity level, and specifies the default failure definition triggers.

You can specify the /path parameter to create additional rules for specific extensions, for

example, to enable tracing for ASPX pages only.

appcmd configure trace "Default Web Site/" /enable /path:*.aspx

You can use the /disable parameter instead of /enable to remove the rules, specifying the /path

parameter to indicate which rule you’d like to remove. If you omit the /path parameter, the

tool will attempt to remove the rule with a path of “*”.

Additionally, you can override both the list of trace providers and areas that are being

captured by each rule—as well as the failure definition for the rule—by using the optional

parameters listed in Table 7-7. For example, to configure an FRT trace rule that intercepts

only the events from the ASP.NET provider and only generates log files for the 404 status

code, you can use the following syntax.

appcmd configure trace "Default Web Site/" /enable /path:*.aspx

/areas:ASPNET/Infrastructure,Module,Page,AppServices /statuscodes:404

220 Part III: Administration

Searching Failed Request Tracing logs

Besides enabling and configuring Failed Request Tracing rules, Appcmd also provides a

convenient ability to search the trace log files. You can use this to quickly find the trace log,

and even the event inside of the log, to help you with diagnosing a particular problem.

You can search the existing trace log files by using the List Trace command. This command has

the following syntax.

appcmd list traces [identifier] [/url:string] [/site.name:string] [apppool.name:string]

[/statuscode:string] …

This command accepts the parameters listed in Table 7-8.

In addition, you can specify other attributes of the trace object to filter the results on. To see

the available attributes, list the trace logs with a “/text:*” parameter. For example, to list all

trace logs for a particular Web site, use the following syntax.

appcmd list traces /site.name:"Default Web Site"

To list all trace logs for a particular URL, use the following syntax.

appcmd list traces /site.name:"Default Web Site"

/url:http://localhost/myapp/test.html

The output of the command contains the trace log objects, as in the following example, and

includes the trace log identifier, the URL of the request, the status code, and the worker process.

TRACE "Default Web Site/fr000021.xml"

(url:http://localhost:80/myapp/test.html,statuscode:200,wp:3284)

TRACE "Default Web Site/fr000022.xml"

(url:http://localhost:80/,statuscode:200,wp:3284)

Table 7-8 Parameters of the List Trace Command

Parameter Description

identifier The unique identifier of each trace log, which is in the form of

“SiteName/logfilename.xml”. You can use this to look up a specific

trace log.

url The URL of the request. Appcmd supports partial URLs by default,

doing a prefix match on a normalized version of the URL.

site.name The name of the Web site for which to show the request logs. Using

this can improve the efficiency of the command because only the

logs for the specified Web site are retrieved.

apppool.name The name of the application pool for which to show the request

logs.

statuscode The status code for the request.